/**
 * Minimal root options shape shared by CLI and generator layers.
 * Keep keys optional to respect exactOptionalPropertyTypes semantics.
 *
 * @public
 */
interface RootOptionsShape {
    /** Target environment (dotenv-expanded). */
    env?: string;
    /** Explicit variable overrides (dotenv-expanded). */
    vars?: string;
    /** Command to execute (dotenv-expanded). */
    command?: string;
    /** Output path for the consolidated environment file (dotenv-expanded). */
    outputPath?: string;
    /**
     * Shell execution strategy.
     * - `true`: use default OS shell.
     * - `false`: use plain execution (no shell).
     * - string: use specific shell path.
     */
    shell?: string | boolean;
    /** Whether to load variables into `process.env`. */
    loadProcess?: boolean;
    /** Exclude all variables from loading. */
    excludeAll?: boolean;
    /** Exclude dynamic variables. */
    excludeDynamic?: boolean;
    /** Exclude environment-specific variables. */
    excludeEnv?: boolean;
    /** Exclude global variables. */
    excludeGlobal?: boolean;
    /** Exclude private variables. */
    excludePrivate?: boolean;
    /** Exclude public variables. */
    excludePublic?: boolean;
    /** Enable console logging of loaded variables. */
    log?: boolean;
    /** Enable debug logging to stderr. */
    debug?: boolean;
    /** Capture child process stdio (useful for tests/CI). */
    capture?: boolean;
    /** Fail on validation errors (schema/requiredKeys). */
    strict?: boolean;
    /** Enable presentation-time redaction of secret-like keys. */
    redact?: boolean;
    /** Enable entropy warnings for high-entropy values. */
    warnEntropy?: boolean;
    /** Entropy threshold (bits/char) for warnings (default 3.8). */
    entropyThreshold?: number;
    /** Minimum string length to check for entropy (default 16). */
    entropyMinLength?: number;
    /** Regex patterns for keys to exclude from entropy checks. */
    entropyWhitelist?: ReadonlyArray<string>;
    /** Additional regex patterns for keys to redact. */
    redactPatterns?: string[];
    /** Default target environment when not specified. */
    defaultEnv?: string;
    /** Env var name in global dotenv files that specifies the default environment. */
    defaultEnvKey?: string;
    /** Token indicating a dotenv file (default: ".env"). */
    dotenvToken?: string;
    /** Path to dynamic variables module (default: undefined). */
    dynamicPath?: string;
    /**
     * Emit diagnostics for child env composition.
     * - `true`: trace all keys.
     * - `string[]`: trace selected keys.
     */
    trace?: boolean | string[];
    /** Paths to search for dotenv files (space-delimited string or array). */
    paths?: string | string[];
    /** Delimiter for paths string (default: space). */
    pathsDelimiter?: string;
    /** Regex pattern for paths delimiter. */
    pathsDelimiterPattern?: string;
    /** Token indicating private variables (default: "local"). */
    privateToken?: string;
    /** Delimiter for vars string (default: space). */
    varsDelimiter?: string;
    /** Regex pattern for vars delimiter. */
    varsDelimiterPattern?: string;
    /** Assignment operator for vars (default: "="). */
    varsAssignor?: string;
    /** Regex pattern for vars assignment operator. */
    varsAssignorPattern?: string;
    /** Table of named scripts for execution. */
    scripts?: ScriptsTable;
}
/**
 * Definition for a single script entry.
 */
interface ScriptDef<TShell extends string | boolean = string | boolean> {
    /** The command string to execute. */
    cmd: string;
    /** Shell override for this script. */
    shell?: TShell | undefined;
}
/**
 * Scripts table shape.
 */
type ScriptsTable<TShell extends string | boolean = string | boolean> = Record<string, string | ScriptDef<TShell>>;

/**
 * Unify Scripts via the generic ScriptsTable<TShell> so shell types propagate.
 */
type Scripts = ScriptsTable;

/**
 * Resolved configuration object type returned by {@link getDotenvConfigSchemaResolved}.
 *
 * @public
 */
type GetDotenvConfigResolved = {
    /**
     * Help-time/runtime root defaults applied by the host (collapsed families; CLI‑like).
     */
    rootOptionDefaults?: Partial<RootOptionsShape>;
    /**
     * Help-time visibility for root flags; when a key is false the corresponding
     * option(s) are hidden in root help output.
     */
    rootOptionVisibility?: Partial<Record<keyof RootOptionsShape, boolean>>;
    /**
     * Merged scripts table for resolving commands and shell behavior.
     * Entries may be strings or objects with `cmd` and optional `shell`.
     */
    scripts?: Scripts;
    /**
     * Keys required to be present in the final composed environment.
     * Validation occurs after overlays and dynamics.
     */
    requiredKeys?: string[];
    /**
     * Optional validation schema (e.g., Zod). When present and it exposes
     * `safeParse(finalEnv)`, the host executes it once after overlays.
     */
    schema?: unknown;
    /**
     * Public global variables (string‑only).
     */
    vars?: Record<string, string>;
    /**
     * Public per‑environment variables (string‑only).
     */
    envVars?: Record<string, Record<string, string>>;
    /**
     * Dynamic variable definitions (JS/TS configs only).
     */
    dynamic?: unknown;
    /**
     * Per‑plugin configuration slices keyed by realized mount path
     * (for example, "aws/whoami").
     */
    plugins?: Record<string, unknown>;
};

/**
 * A minimal representation of an environment key/value mapping.
 * Values may be `undefined` to represent "unset".
 */
type ProcessEnv = Record<string, string | undefined>;
/**
 * Dynamic variable function signature. Receives the current expanded variables
 * and the selected environment (if any), and returns either a string to set
 * or `undefined` to unset/skip the variable.
 */
type GetDotenvDynamicFunction = (vars: ProcessEnv, env: string | undefined) => string | null | undefined;
/**
 * A map of dynamic variable definitions.
 * Keys are variable names; values are either literal strings or functions.
 */
type GetDotenvDynamic = Record<string, GetDotenvDynamicFunction | ReturnType<GetDotenvDynamicFunction>>;

/**
 * Dotenv provenance model (descriptor-only).
 *
 * Requirements addressed:
 * - Host ctx carries a dotenv provenance mapping describing per-key origin and override history.
 * - Provenance is descriptor-only (no value payloads).
 * - Provenance is an ordered stack per key in ascending precedence; the last entry is effective.
 * - Explicit unsets are represented as `op: 'unset'` without requiring deletion of keys from the env map.
 */
/**
 * Provenance kind for an entry in {@link DotenvProvenance}.
 *
 * @public
 */
type DotenvProvenanceKind = 'file' | 'config' | 'vars' | 'dynamic';
/**
 * Operation represented by a provenance entry.
 *
 * @public
 */
type DotenvProvenanceOp = 'set' | 'unset';
/**
 * Base shape for all provenance entries.
 *
 * @public
 */
interface DotenvProvenanceEntryBase {
    /**
     * The kind of provenance entry.
     */
    kind: DotenvProvenanceKind;
    /**
     * The operation applied at this layer.
     */
    op: DotenvProvenanceOp;
}
/**
 * Provenance entry representing a value sourced from a dotenv file in the cascade.
 *
 * @public
 */
interface DotenvFileProvenanceEntry extends DotenvProvenanceEntryBase {
    /** Discriminator. */
    kind: 'file';
    /** Global vs env-scoped file. */
    scope: 'global' | 'env';
    /** Public vs private file. */
    privacy: 'public' | 'private';
    /** Environment name (required when scope is `env`). */
    env?: string;
    /**
     * The corresponding `paths[]` entry as provided by the caller/CLI.
     * This is not an absolute path by policy.
     */
    path: string;
    /**
     * The computed dotenv filename token (e.g., `.env`, `.env.dev`, `.env.local`, `.env.dev.local`).
     */
    file: string;
}
/**
 * Provenance entry representing a value sourced from config overlays (`vars` / `envVars`).
 *
 * @public
 */
interface DotenvConfigProvenanceEntry extends DotenvProvenanceEntryBase {
    /** Discriminator. */
    kind: 'config';
    /** Global vs env-scoped config slice. */
    scope: 'global' | 'env';
    /** Public vs private on the privacy axis (`local` config maps to `private`). */
    privacy: 'public' | 'private';
    /** Environment name (required when scope is `env`). */
    env?: string;
    /** Packaged vs project config origin. */
    configScope: 'packaged' | 'project';
    /** Public vs local config file. */
    configPrivacy: 'public' | 'local';
}
/**
 * Provenance entry representing explicit variables overrides.
 *
 * Notes:
 * - This kind represents values injected via `vars` (CLI/programmatic), not dotenv files.
 *
 * @public
 */
interface DotenvVarsProvenanceEntry extends DotenvProvenanceEntryBase {
    /** Discriminator. */
    kind: 'vars';
}
/**
 * Source tier for dynamic variables.
 *
 * @public
 */
type DotenvDynamicSource = 'config' | 'programmatic' | 'dynamicPath';
/**
 * Provenance entry representing dynamic variables.
 *
 * @public
 */
interface DotenvDynamicProvenanceEntry extends DotenvProvenanceEntryBase {
    /** Discriminator. */
    kind: 'dynamic';
    /** Dynamic source tier. */
    dynamicSource: DotenvDynamicSource;
    /**
     * The `dynamicPath` value as provided by the caller/CLI when `dynamicSource` is `dynamicPath`.
     * This is not resolved to an absolute path by provenance policy.
     */
    dynamicPath?: string;
}
/**
 * Union of all supported provenance entry shapes.
 *
 * @public
 */
type DotenvProvenanceEntry = DotenvFileProvenanceEntry | DotenvConfigProvenanceEntry | DotenvVarsProvenanceEntry | DotenvDynamicProvenanceEntry;
/**
 * Per-key provenance history.
 *
 * Each key maps to an array of entries ordered in ascending precedence (lower to higher).
 *
 * @public
 */
type DotenvProvenance = Record<string, DotenvProvenanceEntry[]>;
/**
 * Create an empty provenance map.
 *
 * @public
 */
declare function createDotenvProvenance(): DotenvProvenance;
/**
 * Append a provenance entry for a key.
 *
 * @param prov - Provenance map to mutate.
 * @param key - Variable name.
 * @param entry - Descriptor-only provenance entry.
 *
 * @public
 */
declare function pushDotenvProvenance(prov: DotenvProvenance, key: string, entry: DotenvProvenanceEntry): void;

/**
 * Apply a dynamic map to the target progressively.
 * - Functions receive (target, env) and may return string | null | undefined.
 * - string → set the key to that value.
 * - undefined → no-op, leave existing value unchanged.
 * - null → delete the key from the target.
 *
 * @param target - Mutable target environment to assign into.
 * @param map - Dynamic map to apply (functions and/or literal values).
 * @param env - Selected environment name (if any) passed through to dynamic functions.
 * @returns Set of keys that were deleted (value was null).
 */
declare function applyDynamicMap(target: ProcessEnv, map?: GetDotenvDynamic, env?: string): Set<string>;
/**
 * Load a default-export dynamic map from a JS/TS file (without applying it).
 *
 * Uses util/loadModuleDefault for robust TS handling (direct import, esbuild,
 * typescript.transpile fallback).
 *
 * Error behavior:
 * - On failure to load/compile/evaluate the module, throws a unified message:
 *   "Unable to load dynamic TypeScript file: <absPath>. Install 'esbuild'..."
 *
 * @param absPath - Absolute path to the dynamic module file.
 * @param cacheDirName - Cache subdirectory under `.tsbuild/` for compiled artifacts.
 * @returns A `Promise\<GetDotenvDynamic | undefined\>` resolving to the module default export (if present).
 *
 * @public
 */
declare function loadDynamicModuleDefault(absPath: string, cacheDirName: string): Promise<GetDotenvDynamic | undefined>;
/**
 * Apply a dynamic map and append provenance entries per key.
 *
 * Requirements addressed:
 * - Dynamic provenance entries record `dynamicSource` and optional `dynamicPath` (as provided).
 * - Record `op: 'unset'` when the dynamic evaluation yields `undefined`.
 *
 * @param target - Mutable env map to assign into.
 * @param map - Dynamic map (functions and/or literals).
 * @param env - Selected environment name (if any).
 * @param prov - Provenance map to append into.
 * @param meta - Dynamic provenance metadata (source tier and optional dynamicPath).
 *
 * @returns Set of keys that were deleted (value was null).
 *
 * @public
 */
declare function applyDynamicMapWithProvenance(target: ProcessEnv, map: GetDotenvDynamic | undefined, env: string | undefined, prov: DotenvProvenance, meta: {
    dynamicSource: DotenvDynamicSource;
    dynamicPath?: string;
}): Set<string>;
/**
 * Load a default-export dynamic map from a JS/TS file and apply it.
 * Uses util/loadModuleDefault for robust TS handling (direct import, esbuild,
 * typescript.transpile fallback).
 *
 * Error behavior:
 * - On failure to load/compile/evaluate the module, throws a unified message:
 *   "Unable to load dynamic TypeScript file: <absPath>. Install 'esbuild'..."
 *
 * @param target - Mutable target environment to assign into.
 * @param absPath - Absolute path to the dynamic module file.
 * @param env - Selected environment name (if any).
 * @param cacheDirName - Cache subdirectory under `.tsbuild/` for compiled artifacts.
 * @returns A `Promise\<Set\<string\>\>` resolving to the set of deleted keys.
 */
declare function loadAndApplyDynamic(target: ProcessEnv, absPath: string, env: string | undefined, cacheDirName: string): Promise<Set<string>>;

/**
 * Configuration sources for environment overlay.
 * Organized by scope (packaged vs project) and privacy (public vs local).
 *
 * @public
 */
type OverlayConfigSources = {
    /** Packaged configuration (public). */
    packaged?: GetDotenvConfigResolved;
    /** Project configuration (public and local). */
    project?: {
        /** Project public configuration. */
        public?: GetDotenvConfigResolved;
        /** Project local configuration. */
        local?: GetDotenvConfigResolved;
    };
};
/**
 * Base options for overlaying config-provided values onto a dotenv map.
 *
 * @typeParam B - base env shape
 * @public
 */
interface OverlayEnvOptionsBase<B extends ProcessEnv | Readonly<ProcessEnv>> {
    /** Base environment variables. */
    base: B;
    /** Target environment name. */
    env: string | undefined;
    /** Configuration sources to overlay. */
    configs: OverlayConfigSources;
}
/**
 * Options including explicit programmatic variables which take top precedence.
 *
 * @typeParam B - base env shape
 * @typeParam P - programmatic vars shape
 * @public
 */
interface OverlayEnvOptionsWithProgrammatic<B extends ProcessEnv | Readonly<ProcessEnv>, P extends ProcessEnv | Readonly<ProcessEnv>> extends OverlayEnvOptionsBase<B> {
    /**
     * Explicit programmatic variables applied at the highest precedence tier.
     */
    programmaticVars: P;
}
/**
 * Overlay config-provided values onto a base ProcessEnv using precedence axes:
 * - kind: env \> global
 * - privacy: local \> public
 * - source: project \> packaged \> base
 *
 * Programmatic explicit vars (if provided) override all config slices.
 * Progressive expansion is applied within each slice.
 */
declare function overlayEnv<B extends ProcessEnv | Readonly<ProcessEnv>>(args: {
    base: B;
    env: string | undefined;
    configs: OverlayConfigSources;
}): B;
declare function overlayEnv<B extends ProcessEnv | Readonly<ProcessEnv>, P extends ProcessEnv | Readonly<ProcessEnv>>(args: {
    base: B;
    env: string | undefined;
    configs: OverlayConfigSources;
    programmaticVars: P;
}): B & P;

/**
 * Overlay config-provided values onto a base env while recording provenance.
 *
 * Requirements addressed:
 * - Provenance entries for `kind: 'config'` include scope/privacy/env/configScope/configPrivacy.
 * - Provenance entries for `kind: 'vars'` represent explicit vars overlays.
 * - Provenance is recorded as layers are applied (no post-hoc reconstruction).
 * - Record `op: 'unset'` when a layer writes an undefined result (e.g., expansion yields empty).
 */

/**
 * Input options for {@link overlayEnvWithProvenance}.
 *
 * @public
 */
interface OverlayEnvWithProvenanceArgs {
    /**
     * Base environment variables.
     */
    base: ProcessEnv | Readonly<ProcessEnv>;
    /**
     * Target environment name.
     */
    env: string | undefined;
    /**
     * Configuration sources to overlay.
     */
    configs: OverlayConfigSources;
    /**
     * Explicit vars overlays applied at the highest static precedence tier.
     */
    programmaticVars?: ProcessEnv | Readonly<ProcessEnv>;
    /**
     * Existing provenance map to append into. When omitted, a new map is created.
     */
    provenance?: DotenvProvenance;
}
/**
 * Output of {@link overlayEnvWithProvenance}.
 *
 * @public
 */
interface OverlayEnvWithProvenanceResult {
    /**
     * The overlaid environment.
     */
    env: ProcessEnv;
    /**
     * Provenance history for keys affected by overlays.
     */
    provenance: DotenvProvenance;
}
/**
 * Overlay config-provided values onto a base ProcessEnv using precedence axes:
 * - kind: env \> global
 * - privacy: local \> public
 * - source: project \> packaged \> base
 *
 * Programmatic explicit vars override all config slices.
 *
 * @param args - Overlay inputs.
 * @returns The overlaid env and the updated provenance mapping.
 *
 * @public
 */
declare function overlayEnvWithProvenance(args: OverlayEnvWithProvenanceArgs): OverlayEnvWithProvenanceResult;

/**
 * Read dotenv files from the deterministic cascade and record provenance.
 *
 * Requirements addressed:
 * - Provenance entries for `kind: 'file'` include scope/privacy/env/path/file (descriptor-only).
 * - Provenance is ordered in ascending precedence as layers are applied.
 * - Uses the same file naming convention as get-dotenv (public/private × global/env).
 */

/**
 * Inputs for reading the dotenv cascade with provenance.
 *
 * @public
 */
interface ReadDotenvCascadeArgs {
    /** Base dotenv filename token (default `.env`). */
    dotenvToken?: string;
    /** Private token suffix (default `local`). */
    privateToken?: string;
    /** Ordered search paths (directories). */
    paths: string[];
    /** Selected env name (used for env-scoped files). */
    env?: string;
    /** Default env name (used when `env` is not provided). */
    defaultEnv?: string;
    /** Exclude env-scoped files. */
    excludeEnv?: boolean;
    /** Exclude global files. */
    excludeGlobal?: boolean;
    /** Exclude private files. */
    excludePrivate?: boolean;
    /** Exclude public files. */
    excludePublic?: boolean;
}
/**
 * Result of reading the dotenv cascade with provenance.
 *
 * @public
 */
interface ReadDotenvCascadeResult {
    /** Expanded dotenv map composed from file sources only. */
    dotenv: ProcessEnv;
    /** File-only provenance history for keys in {@link ReadDotenvCascadeResult.dotenv}. */
    provenance: DotenvProvenance;
}
/**
 * Read and expand dotenv vars from the deterministic file cascade, recording file provenance.
 *
 * @param args - Cascade selector options (tokens/paths/excludes/env).
 * @returns Expanded dotenv and provenance.
 *
 * @public
 */
declare function readDotenvCascadeWithProvenance(args: ReadDotenvCascadeArgs): Promise<ReadDotenvCascadeResult>;

export { applyDynamicMap, applyDynamicMapWithProvenance, createDotenvProvenance, loadAndApplyDynamic, loadDynamicModuleDefault, overlayEnv, overlayEnvWithProvenance, pushDotenvProvenance, readDotenvCascadeWithProvenance };
export type { DotenvConfigProvenanceEntry, DotenvDynamicProvenanceEntry, DotenvDynamicSource, DotenvFileProvenanceEntry, DotenvProvenance, DotenvProvenanceEntry, DotenvProvenanceEntryBase, DotenvProvenanceKind, DotenvProvenanceOp, DotenvVarsProvenanceEntry, OverlayConfigSources, OverlayEnvOptionsBase, OverlayEnvOptionsWithProgrammatic, OverlayEnvWithProvenanceArgs, OverlayEnvWithProvenanceResult, ReadDotenvCascadeArgs, ReadDotenvCascadeResult };