import { OptionValues, Command, InferCommandArguments, Option } from '@commander-js/extra-typings';
import { z, ZodObject } from 'zod';

/**
 * 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[]>;

/**
 * Resolved CLI options schema.
 * For the current step this mirrors the RAW schema; later stages may further
 * narrow types post-resolution in the host pipeline.
 */
/**
 * CLI options schema (resolved).
 *
 * Today this mirrors {@link getDotenvCliOptionsSchemaRaw}, but is kept as a distinct export
 * so future resolution steps can narrow or materialize defaults without breaking the API.
 *
 * @public
 */
declare const getDotenvCliOptionsSchemaResolved: z.ZodObject<{
    defaultEnv: z.ZodOptional<z.ZodString>;
    defaultEnvKey: z.ZodOptional<z.ZodString>;
    dotenvToken: z.ZodOptional<z.ZodString>;
    dynamicPath: z.ZodOptional<z.ZodString>;
    dynamic: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
    env: z.ZodOptional<z.ZodString>;
    excludeDynamic: z.ZodOptional<z.ZodBoolean>;
    excludeEnv: z.ZodOptional<z.ZodBoolean>;
    excludeGlobal: z.ZodOptional<z.ZodBoolean>;
    excludePrivate: z.ZodOptional<z.ZodBoolean>;
    excludePublic: z.ZodOptional<z.ZodBoolean>;
    loadProcess: z.ZodOptional<z.ZodBoolean>;
    log: z.ZodOptional<z.ZodBoolean>;
    logger: z.ZodDefault<z.ZodUnknown>;
    outputPath: z.ZodOptional<z.ZodString>;
    privateToken: z.ZodOptional<z.ZodString>;
    debug: z.ZodOptional<z.ZodBoolean>;
    strict: z.ZodOptional<z.ZodBoolean>;
    capture: z.ZodOptional<z.ZodBoolean>;
    trace: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodArray<z.ZodString>]>>;
    redact: z.ZodOptional<z.ZodBoolean>;
    warnEntropy: z.ZodOptional<z.ZodBoolean>;
    entropyThreshold: z.ZodOptional<z.ZodNumber>;
    entropyMinLength: z.ZodOptional<z.ZodNumber>;
    entropyWhitelist: z.ZodOptional<z.ZodArray<z.ZodString>>;
    redactPatterns: z.ZodOptional<z.ZodArray<z.ZodString>>;
    paths: z.ZodOptional<z.ZodString>;
    pathsDelimiter: z.ZodOptional<z.ZodString>;
    pathsDelimiterPattern: z.ZodOptional<z.ZodString>;
    scripts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
    shell: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
    vars: z.ZodOptional<z.ZodString>;
    varsAssignor: z.ZodOptional<z.ZodString>;
    varsAssignorPattern: z.ZodOptional<z.ZodString>;
    varsDelimiter: z.ZodOptional<z.ZodString>;
    varsDelimiterPattern: z.ZodOptional<z.ZodString>;
}, z.core.$strip>;

/**
 * Resolved programmatic options schema (post-inheritance).
 * For now, this mirrors the RAW schema; future stages may materialize defaults
 * and narrow shapes as resolution is wired into the host.
 */
/**
 * Programmatic options schema (resolved).
 *
 * Today this mirrors {@link getDotenvOptionsSchemaRaw}, but is kept as a distinct export
 * so future resolution steps can narrow or materialize defaults without breaking the API.
 *
 * @public
 */
declare const getDotenvOptionsSchemaResolved: z.ZodObject<{
    defaultEnv: z.ZodOptional<z.ZodString>;
    defaultEnvKey: z.ZodOptional<z.ZodString>;
    dotenvToken: z.ZodOptional<z.ZodString>;
    dynamicPath: z.ZodOptional<z.ZodString>;
    dynamic: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
    env: z.ZodOptional<z.ZodString>;
    excludeDynamic: z.ZodOptional<z.ZodBoolean>;
    excludeEnv: z.ZodOptional<z.ZodBoolean>;
    excludeGlobal: z.ZodOptional<z.ZodBoolean>;
    excludePrivate: z.ZodOptional<z.ZodBoolean>;
    excludePublic: z.ZodOptional<z.ZodBoolean>;
    loadProcess: z.ZodOptional<z.ZodBoolean>;
    log: z.ZodOptional<z.ZodBoolean>;
    logger: z.ZodDefault<z.ZodUnknown>;
    outputPath: z.ZodOptional<z.ZodString>;
    paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
    privateToken: z.ZodOptional<z.ZodString>;
    vars: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodOptional<z.ZodString>>>;
}, z.core.$strip>;

/**
 * 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>>;
/**
 * Per-invocation context shared with plugins and actions.
 *
 * @public
 */
interface GetDotenvCliCtx<TOptions extends GetDotenvOptions = GetDotenvOptions> {
    /**
     * Effective environment name after resolution (explicit -e \> defaultEnvKey \> defaultEnv).
     */
    env?: string;
    /**
     * Fully resolved option bag used to compute this context.
     */
    optionsResolved: TOptions;
    /**
     * Final composed dotenv environment for this invocation.
     */
    dotenv: ProcessEnv;
    /**
     * Dotenv provenance history for {@link GetDotenvCliCtx.dotenv}.
     *
     * Descriptor-only: does not include value payloads.
     */
    dotenvProvenance: DotenvProvenance;
    /**
     * Optional runtime plugin state bag. Plugins may publish non-sensitive metadata here.
     */
    plugins?: Record<string, unknown>;
    /**
     * Per-plugin validated configuration slices keyed by realized mount path.
     */
    pluginConfigs?: 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>>;
/**
 * Logger interface compatible with AWS SDK v3 expectations (`debug`, `info`, `warn`, `error`).
 * Consumers must provide an object that implements these four methods.
 * Additional methods (like `log`) are allowed but not required or used by this library.
 */
type Logger = Pick<Console, 'debug' | 'info' | 'warn' | 'error'>;
/**
 * Canonical programmatic options type (schema-derived).
 * This type is the single source of truth for programmatic options.
 */
type GetDotenvOptions = Omit<z.output<typeof getDotenvOptionsSchemaResolved>, 'logger' | 'dynamic'> & {
    /**
     * Compile-time overlay: narrowed logger for DX (schema stores unknown).
     */
    logger: Logger;
    /**
     * Compile-time overlay: narrowed dynamic map for DX (schema stores unknown).
     */
    dynamic?: GetDotenvDynamic;
};

/**
 * Unify Scripts via the generic ScriptsTable<TShell> so shell types propagate.
 */
type Scripts = ScriptsTable;
/**
 * Canonical CLI options type derived from the Zod schema output.
 * Includes CLI-only flags (debug/strict/capture/trace/redaction/entropy),
 * stringly paths/vars, and inherited programmatic fields (minus normalized
 * shapes that are handled by resolution).
 */
type GetDotenvCliOptions = Omit<z.output<typeof getDotenvCliOptionsSchemaResolved>, 'logger' | 'dynamic' | 'scripts'> & {
    /**
     * Compile-only overlay for DX: logger narrowed from unknown.
     */
    logger: Logger;
    /**
     * Compile-only overlay for DX: dynamic map narrowed from unknown.
     */
    dynamic?: GetDotenvDynamic;
    /**
     * Compile-only overlay for DX: scripts narrowed from Record\<string, unknown\>.
     */
    scripts?: Scripts;
};

/**
 * Configuration context used for generating dynamic help descriptions.
 * Contains merged CLI options and plugin configuration slices.
 *
 * @public
 */
type ResolvedHelpConfig = Partial<GetDotenvCliOptions> & {
    /**
     * Per‑plugin configuration slices keyed by realized mount path
     * (e.g., `"aws"` or `"aws/whoami"`), used for dynamic help text.
     */
    plugins: Record<string, unknown>;
};

/** src/cliHost/definePlugin/contracts.ts
 * Public contracts for plugin authoring (types only).
 * - No runtime logic or state.
 * - Safe to import broadly without introducing cycles.
 */

/**
 * Options for resolving and loading the configuration.
 *
 * @public
 */
interface ResolveAndLoadOptions {
    /**
     * When false, skips running plugin afterResolve hooks.
     * Useful for top-level help rendering to avoid long-running side-effects
     * while still evaluating dynamic help text.
     *
     * @default true
     */
    runAfterResolve?: boolean;
    /**
     * Name of the invoked subcommand (plugin namespace). When provided,
     * only the matching plugin subtree runs afterResolve hooks.
     * When omitted, all plugins run afterResolve (backward compatibility).
     */
    invokedSubcommand?: string;
}
/**
 * Structural public interface for the host exposed to plugins.
 * - Extends Commander.Command so plugins can attach options/commands/hooks.
 * - Adds host-specific helpers used by built-in plugins.
 *
 * Purpose: remove nominal class identity (private fields) from the plugin seam
 * to avoid TS2379 under exactOptionalPropertyTypes in downstream consumers.
 */
interface GetDotenvCliPublic<TOptions extends GetDotenvOptions = GetDotenvOptions, TArgs extends unknown[] = [], TOpts extends OptionValues = {}, TGlobal extends OptionValues = {}> extends Command<TArgs, TOpts, TGlobal> {
    /**
     * Create a namespaced child command with argument inference.
     * Mirrors Commander generics so downstream chaining remains fully typed.
     */
    ns<Usage extends string>(name: Usage, opts?: NsOptions): GetDotenvCliPublic<TOptions, [
        ...TArgs,
        ...InferCommandArguments<Usage>
    ], {}, TOpts & TGlobal>;
    /** Return the current context; throws if not yet resolved. */
    getCtx(): GetDotenvCliCtx<TOptions>;
    /** Check whether a context has been resolved (non-throwing). */
    hasCtx(): boolean;
    /**
     * Resolve options and compute the dotenv context for this invocation.
     *
     * @param customOptions - Partial options to overlay for this invocation.
     * @param opts - Optional resolver behavior switches (for example, whether to run `afterResolve`).
     * @returns A promise resolving to the computed invocation context.
     */
    resolveAndLoad(customOptions?: Partial<TOptions>, opts?: ResolveAndLoadOptions): Promise<GetDotenvCliCtx<TOptions>>;
    /**
     * Tag an option with a help group identifier for grouped root help rendering.
     *
     * @param opt - The Commander option to tag.
     * @param group - Group identifier (for example, `base`, `app`, or `plugin:<name>`).
     * @returns Nothing.
     */
    setOptionGroup(opt: Option, group: string): void;
    /**
     * Create a dynamic option whose description is computed at help time
     * from the resolved configuration.
     */
    /**
     * Create a dynamic option whose description is computed at help time from the resolved configuration.
     *
     * @param flags - Commander option flags usage string.
     * @param desc - Description builder called during help rendering with the resolved help config.
     * @param parser - Optional argument parser.
     * @param defaultValue - Optional default value.
     * @returns A Commander `Option` instance with a dynamic description.
     */
    createDynamicOption<Usage extends string>(flags: Usage, desc: (cfg: ResolvedHelpConfig) => string, parser?: (value: string, previous?: unknown) => unknown, defaultValue?: unknown): Option<Usage>;
    /** {@inheritDoc} */
    createDynamicOption<Usage extends string, TValue = unknown>(flags: Usage, desc: (cfg: ResolvedHelpConfig) => string, parser: (value: string, previous?: TValue) => TValue, defaultValue?: TValue): Option<Usage>;
}
/**
 * Options for the `ns()` subcommand factory, forwarded to Commander's
 * `command(name, opts)` second argument.
 *
 * @public
 */
interface NsOptions {
    /**
     * When true, this subcommand becomes the default: Commander routes
     * unrecognized positional tokens to it when no explicit subcommand matches.
     */
    isDefault?: boolean;
    /**
     * When true, the subcommand is hidden from help output.
     */
    hidden?: boolean;
}
/**
 * Optional overrides for plugin composition.
 *
 * @public
 */
interface PluginNamespaceOverride {
    /**
     * Override the default namespace for this plugin instance.
     */
    ns?: string;
}
/**
 * An entry in the plugin children array.
 *
 * @public
 */
interface PluginChildEntry<TOptions extends GetDotenvOptions = GetDotenvOptions, TArgs extends unknown[] = [], TOpts extends OptionValues = {}, TGlobal extends OptionValues = {}> {
    /** The child plugin instance to mount under this parent. */
    plugin: GetDotenvCliPlugin<TOptions, TArgs, TOpts, TGlobal>;
    /**
     * Optional namespace override for the child when mounted under the parent.
     * When provided, this name is used instead of the child's default `ns`.
     */
    override: PluginNamespaceOverride | undefined;
}
/** Public plugin contract used by the GetDotenv CLI host. */
interface GetDotenvCliPlugin<TOptions extends GetDotenvOptions = GetDotenvOptions, TArgs extends unknown[] = [], TOpts extends OptionValues = {}, TGlobal extends OptionValues = {}> {
    /** Namespace (required): the command name where this plugin is mounted. */
    ns: string;
    /**
     * Options forwarded to the host's `ns()` call when creating the mount
     * for this plugin (e.g. `{ isDefault: true }`).
     */
    nsOptions?: NsOptions;
    /**
     * Setup phase: register commands and wiring on the provided mount.
     * Runs parent → children (pre-order). Return nothing (void).
     */
    setup: (cli: GetDotenvCliPublic<TOptions, TArgs, TOpts, TGlobal>) => void | Promise<void>;
    /**
     * After the dotenv context is resolved, initialize any clients/secrets
     * or attach per-plugin state under ctx.plugins (by convention).
     * Runs parent → children (pre-order).
     *
     * **Scoping**: When the host provides an invoked subcommand filter,
     * afterResolve only fires for plugins whose namespace matches the
     * invoked command path. A plugin's afterResolve should never produce
     * side effects for commands outside its subtree.
     */
    afterResolve?: (cli: GetDotenvCliPublic<TOptions, TArgs, TOpts, TGlobal>, ctx: GetDotenvCliCtx<TOptions>) => void | Promise<void>;
    /** Zod schema for this plugin's config slice (from config.plugins[…]). */
    configSchema?: ZodObject;
    /**
     * Compositional children, with optional per-child overrides (e.g., ns).
     * Installed after the parent per pre-order.
     */
    children: Array<PluginChildEntry<TOptions, TArgs, TOpts, TGlobal>>;
    /**
     * Compose a child plugin with optional override (ns). Returns the parent
     * to enable chaining.
     */
    use: (child: GetDotenvCliPlugin<TOptions, TArgs, TOpts, TGlobal>, override?: PluginNamespaceOverride) => GetDotenvCliPlugin<TOptions, TArgs, TOpts, TGlobal>;
}
/**
 * Compile-time helper type: the plugin object returned by definePlugin always
 * includes the instance-bound helpers as required members. Keeping the public
 * interface optional preserves compatibility for ad-hoc/test plugins, while
 * return types from definePlugin provide stronger DX for shipped/typed plugins.
 */
interface PluginWithInstanceHelpers<TOptions extends GetDotenvOptions = GetDotenvOptions, TConfig = unknown, TArgs extends unknown[] = [], TOpts extends OptionValues = {}, TGlobal extends OptionValues = {}> extends GetDotenvCliPlugin<TOptions, TArgs, TOpts, TGlobal> {
    /**
     * Read the validated (and interpolated) configuration slice for this plugin instance.
     *
     * @param cli - The plugin mount (or any command under this mount) used to resolve the invocation context.
     * @returns The plugin configuration slice, typed as `TCfg`.
     * @throws Error when called before the host has resolved the invocation context.
     */
    readConfig<TCfg = TConfig>(cli: GetDotenvCliPublic<TOptions, unknown[], OptionValues, OptionValues>): Readonly<TCfg>;
    /**
     * Create a Commander option whose help-time description receives the resolved root help config
     * and this plugin instance’s validated configuration slice.
     *
     * @typeParam TCfg - The plugin configuration slice type.
     * @typeParam Usage - The Commander usage string for the option flags.
     * @param cli - The plugin mount used to associate the option with a realized mount path.
     * @param flags - Commander option flags usage string.
     * @param desc - Description builder receiving the resolved help config and the plugin config slice.
     * @param parser - Optional argument parser.
     * @param defaultValue - Optional default value.
     * @returns A Commander `Option` instance with a dynamic description.
     */
    createPluginDynamicOption<TCfg = TConfig, Usage extends string = string>(cli: GetDotenvCliPublic<TOptions, unknown[], OptionValues, OptionValues>, flags: Usage, desc: (cfg: ResolvedHelpConfig, pluginCfg: Readonly<TCfg>) => string, parser?: (value: string, previous?: unknown) => unknown, defaultValue?: unknown): Option<Usage>;
}

/**
 * Configuration for the parent-level command alias.
 *
 * @public
 */
interface CmdOptionAlias {
    /** Option flags (e.g. "-c, --cmd \<command...\>"). */
    flags: string;
    /** Option description. */
    description?: string;
    /** Whether to expand the alias value before execution. */
    expand?: boolean;
}
/**
 * Options provided to the cmd plugin factory.
 *
 * @public
 */
interface CmdPluginOptions {
    /**
     * When true, register as the default subcommand at the root.
     */
    asDefault?: boolean;
    /**
     * Optional alias option attached to the parent command to invoke the cmd
     * behavior without specifying the subcommand explicitly.
     */
    optionAlias?: string | CmdOptionAlias;
}
/**
 * Options for the cmd runner helper.
 *
 * Used to label the execution origin for diagnostics and future behavior
 * adjustments without changing the call sites.
 *
 * @public
 */
interface RunCmdWithContextOptions {
    /**
     * Execution origin: parent alias or explicit subcommand.
     */
    origin?: 'alias' | 'subcommand';
}

/**
 * Cmd plugin: executes a command using the current getdotenv CLI context.
 * Registers the `cmd` subcommand and optionally attaches a parent-level alias (e.g. `-c`).
 *
 * @param options - Plugin configuration options.
 */
declare const cmdPlugin: (options?: CmdPluginOptions) => PluginWithInstanceHelpers<GetDotenvOptions, {
    expand?: boolean | undefined;
}, [], {}, {}>;
/**
 * Cmd plugin instance type returned by {@link cmdPlugin}.
 *
 * @public
 */
type CmdPlugin = ReturnType<typeof cmdPlugin>;

export { cmdPlugin };
export type { CmdPlugin, RunCmdWithContextOptions };