import { type Result } from "@fjall/generator";
import type { DockerBuildArgValue } from "@fjall/util/manifest/schemas";
/**
 * Resolve a sourced (`{ ssm | secretsManager | env }`) build-arg value to its
 * string value. Threaded in from the caller so this resolver stays free of an
 * AWS dependency; the CLI/worker pass the scoped-session reader (sub-deliverable
 * C) and the resolver only calls it when no higher precedence tier shadows the
 * key.
 */
export type SourcedBuildArgResolver = (key: string, source: Exclude<DockerBuildArgValue, string>) => Promise<Result<string>>;
export interface ResolveBuildArgsContext {
    /**
     * The `docker.buildArgs` declared in the manifest (lowest precedence). Only
     * keys present here (∪ flag keys) are ever emitted — the resolver never
     * injects arbitrary host env.
     */
    manifestBuildArgs?: Record<string, DockerBuildArgValue>;
    /** Build-context directory holding `.env*` files (`identity.buildContext`). */
    serviceDir: string;
    /** App-dir fallback when a `.env*` file is absent from `serviceDir`. */
    appDir?: string;
    /** Deployment stage, used for the `.env.<stage>` tier (e.g. "production"). */
    stage?: string;
    /** The build-host shell environment (usually `process.env`). */
    shellEnv: Record<string, string | undefined>;
    /**
     * Phase-4 CLI `--build-arg` override seam. Today the callers pass undefined /
     * {}. Highest precedence; its keys widen the emitted set beyond the manifest.
     */
    flagBuildArgs?: Record<string, string>;
    /**
     * Resolves a sourced manifest value to a string. Required only when the
     * manifest declares a sourced value that no higher tier shadows; absent it
     * (or a sourced value reaching it being unresolvable) fails closed.
     */
    resolveSourcedValue?: SourcedBuildArgResolver;
}
export interface ResolveBuildArgsResult {
    /** The resolved `KEY=VALUE` map for `DockerBuildParams.buildArgs`. */
    buildArgs: Record<string, string>;
    /**
     * Keys auto-declared because a public-prefixed key was found in a parsed
     * `.env`/`.env.<stage>` FILE (not explicit in the manifest, not a flag). The
     * caller surfaces an R3-style inverse-footgun warning for each (masked at the
     * sink) — auto-baking a `.env` key freezes it into the image.
     */
    inferredDotenvKeys: string[];
}
/**
 * Resolve `docker.buildArgs` to a flat `Record<string, string>` for
 * `DockerBuildParams`, applying the source-precedence ladder (highest → lowest):
 *
 *   flagBuildArgs  >  shell env `KEY`  >  `.env.<stage>`  >  `.env`/`.env.production`
 *                  >  manifest literal/sourced value
 *
 * Keys declared in `manifestBuildArgs` (∪ `flagBuildArgs`) are always emitted.
 * Phase 3 ADDITIONALLY auto-declares a key that is BOTH public-prefixed
 * (`isPublicBuildVarName`) AND present in a parsed `.env`/`.env.<stage>` FILE —
 * never from raw shell env. Shell remains a VALUE-override tier for already
 * declared/inferred keys; it is never a KEY source, so arbitrary host env can
 * never be injected as a build-arg.
 *
 * An empty string at ANY tier is treated as ABSENT and falls through to the
 * next tier (the 2026-06-10 Turnstile empty-string shadow shape); deploy-core
 * has no `getEnv`, so the check is inline `raw !== undefined && raw !== ""`.
 *
 * A manifest value that is a sourced reference (`{ ssm | secretsManager | env }`)
 * is resolved via `resolveSourcedValue` ONLY when no higher tier supplied a
 * value for that key. A plain-string manifest value is used verbatim. An
 * auto-declared `.env` key carries no manifest value — the ladder supplies it.
 */
export declare function resolveBuildArgs(ctx: ResolveBuildArgsContext): Promise<Result<ResolveBuildArgsResult>>;