@karmaniverous/get-dotenv 5.2.6 → 6.0.0-1

package/dist/index.d.ts

@@ -1,22 +1,6 @@
-import { Command } from 'commander';
-
-/** src/cliCore/spawnEnv.ts
- * Build a sanitized environment bag for child processes.
- *
- * Requirements addressed:
- * - Provide a single helper (buildSpawnEnv) to normalize/dedupe child env.
- * - Drop undefined values (exactOptional semantics).
- * - On Windows, dedupe keys case-insensitively and prefer the last value,
- *   preserving the latest key's casing. Ensure HOME fallback from USERPROFILE.
- *   Normalize TMP/TEMP consistency when either is present.
- * - On POSIX, keep keys as-is; when a temp dir key is present (TMPDIR/TMP/TEMP),
- *   ensure TMPDIR exists for downstream consumers that expect it.
- *
- * Adapter responsibility: pure mapping; no business logic.
- */
-type SpawnEnv = Readonly<Partial<Record<string, string>>>;
-/** Build a sanitized env for child processes from base + overlay. */
-declare const buildSpawnEnv: (base?: NodeJS.ProcessEnv, overlay?: Record<string, string | undefined>) => SpawnEnv;
+import { z, ZodObject } from 'zod';
+export { z } from 'zod';
+import { Command, Option } from 'commander';
 
 /**
  * Minimal root options shape shared by CLI and generator layers.
@@ -64,8 +48,92 @@ type RootOptionsShape = {
  */
 type ScriptsTable<TShell extends string | boolean = string | boolean> = Record<string, string | {
     cmd: string;
-    shell?: TShell;
+    shell?: TShell | undefined;
 }>;
+/**
+ * Identity helper to define a scripts table while preserving a concrete TShell
+ * type parameter in downstream inference.
+ */
+declare const defineScripts: <TShell extends string | boolean>() => <T extends ScriptsTable<TShell>>(t: T) => T;
+
+/** Build a sanitized env for child processes from base + overlay. */
+declare const buildSpawnEnv: (base?: NodeJS.ProcessEnv, overlay?: Record<string, string | undefined>) => NodeJS.ProcessEnv;
+
+declare const getDotenvCliOptionsSchemaResolved: z.ZodObject<{
+    defaultEnv: 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.ZodOptional<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>;
+
+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 = z.output<typeof getDotenvCliOptionsSchemaResolved> & {
+    /**
+     * Compile-only overlay for DX: logger narrowed from unknown.
+     */
+    logger?: Logger;
+    /**
+     * Compile-only overlay for DX: scripts narrowed from Record\<string, unknown\>.
+     */
+    scripts?: Scripts;
+};
+
+declare const getDotenvOptionsSchemaResolved: z.ZodObject<{
+    defaultEnv: 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.ZodOptional<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>;
 
 type RootOptionsShapeCompat = Omit<RootOptionsShape, 'vars' | 'paths'> & {
     vars?: string | Record<string, string | undefined>;
@@ -73,7 +141,9 @@ type RootOptionsShapeCompat = Omit<RootOptionsShape, 'vars' | 'paths'> & {
 };
 /**
  * A minimal representation of an environment key/value mapping.
- * Values may be `undefined` to represent "unset". */ type ProcessEnv = Record<string, string | undefined>;
+ * 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
@@ -83,101 +153,72 @@ type GetDotenvDynamicFunction = (vars: ProcessEnv, env: string | undefined) => s
 type GetDotenvDynamic = Record<string, GetDotenvDynamicFunction | ReturnType<GetDotenvDynamicFunction>>;
 type Logger = Record<string, (...args: unknown[]) => void> | typeof console;
 /**
- * Helper to define a dynamic map with strong inference.
- *
- * @example
- * const dynamic = defineDynamic(\{ KEY: (\{ FOO = '' \}) =\> FOO + '-x' \});
- */
-declare const defineDynamic: <T extends GetDotenvDynamic>(d: T) => T;
-/**
- * Options passed programmatically to `getDotenv`.
+ * Canonical programmatic options type (schema-derived).
+ * This type is the single source of truth for programmatic options.
  */
-interface GetDotenvOptions {
-    /**
-     * default target environment (used if `env` is not provided)
-     */
-    defaultEnv?: string;
+type GetDotenvOptions = z.output<typeof getDotenvOptionsSchemaResolved> & {
     /**
-     * token indicating a dotenv file
+     * Compile-time overlay: narrowed logger for DX (schema stores unknown).
      */
-    dotenvToken: string;
-    /**
-     * path to JS/TS module default-exporting an object keyed to dynamic variable functions
-     */
-    dynamicPath?: string;
+    logger?: Logger;
     /**
-     * Programmatic dynamic variables map. When provided, this takes precedence
-     * over {@link GetDotenvOptions.dynamicPath}.
+     * Compile-time overlay: narrowed dynamic map for DX (schema stores unknown).
      */
     dynamic?: GetDotenvDynamic;
-    /**
-     * target environment
-     */
-    env?: string;
-    /**
-     * exclude dynamic variables from loading
-     */
-    excludeDynamic?: boolean;
-    /**
-     * exclude environment-specific variables from loading
-     */
-    excludeEnv?: boolean;
-    /**
-     * exclude global variables from loading
-     */
-    excludeGlobal?: boolean;
-    /**
-     * exclude private variables from loading
-     */
-    excludePrivate?: boolean;
-    /**
-     * exclude public variables from loading
-     */
-    excludePublic?: boolean;
-    /**
-     * load dotenv variables to `process.env`
-     */
+};
+/**
+ * Vars-aware dynamic helpers (compile-time DX).
+ * DynamicFn: receive the current expanded variables and optional env.
+ */
+type DynamicFn<Vars extends Record<string, string | undefined>> = (vars: Vars, env?: string) => string | undefined;
+type DynamicMap<Vars extends Record<string, string | undefined>> = Record<string, DynamicFn<Vars> | ReturnType<DynamicFn<Vars>>>;
+/**
+ * Helper to define a dynamic map with strong inference (Vars-aware).
+ *
+ * Overload A (preferred): bind Vars to your intended key set for improved inference.
+ */
+declare function defineDynamic<Vars extends Record<string, string | undefined>, T extends DynamicMap<Vars>>(d: T): T;
+/**
+ * Overload B (backward-compatible): generic over legacy GetDotenvDynamic.
+ *
+ * Accepts legacy GetDotenvDynamic without Vars binding.
+ */
+declare function defineDynamic<T extends GetDotenvDynamic>(d: T): T;
+/**
+ * Typed config shape and builder for authoring JS/TS getdotenv config files.
+ *
+ * Compile-time only; the runtime loader remains schema-driven.
+ */
+type GetDotenvConfig<Vars extends ProcessEnv, Env extends string = string> = {
+    dotenvToken?: string;
+    privateToken?: string;
+    paths?: string | string[];
     loadProcess?: boolean;
-    /**
-     * log loaded dotenv variables to `logger`
-     */
     log?: boolean;
-    /**
-     * logger object (defaults to console)
-     */
-    logger?: Logger;
-    /**
-     * if populated, writes consolidated dotenv file to this path (follows dotenvExpand rules)
-     */
-    outputPath?: string;
-    /**
-     * array of input directory paths
-     */
-    paths?: string[];
-    /**
-     * filename token indicating private variables
-     */
-    privateToken?: string;
-    /**
-     * explicit variables to include
-     */
-    vars?: ProcessEnv;
-    /**
-     * Reserved: config loader flag (no-op).
-     * The plugin-first host and generator paths already use the config
-     * loader/overlay pipeline unconditionally (no-op when no config files
-     * are present). This flag is accepted for forward compatibility but
-     * currently has no effect.
-     */
-    useConfigLoader?: boolean;
-}
+    shell?: string | boolean;
+    scripts?: Scripts;
+    requiredKeys?: string[];
+    schema?: unknown;
+    vars?: Vars;
+    envVars?: Record<Env, Partial<Vars>>;
+    dynamic?: DynamicMap<Vars>;
+    plugins?: Record<string, unknown>;
+};
+declare function defineGetDotenvConfig<Vars extends ProcessEnv, Env extends string = string, T extends GetDotenvConfig<Vars, Env> = GetDotenvConfig<Vars, Env>>(cfg: T): T;
+/**
+ * Compile-time helper to derive the Vars shape from a typed getdotenv config document.
+ */
+type InferGetDotenvVarsFromConfig<T> = T extends {
+    vars?: infer V;
+} ? V extends Record<string, string | undefined> ? V : never : never;
 /**
- * Converts programmatic CLI options to `getDotenv` options. *
- * @param cliOptions - CLI options. Defaults to `{}`.
+ * Converts programmatic CLI options to `getDotenv` options.
  *
- * @returns `getDotenv` options.
+ * Accepts "stringly" CLI inputs for vars/paths and normalizes them into
+ * the programmatic shape. Preserves exactOptionalPropertyTypes semantics by
+ * omitting keys when undefined.
  */
-declare const getDotenvCliOptions2Options: ({ paths, pathsDelimiter, pathsDelimiterPattern, vars, varsAssignor, varsAssignorPattern, varsDelimiter, varsDelimiterPattern, ...rest }: RootOptionsShapeCompat) => GetDotenvOptions;
+declare const getDotenvCliOptions2Options: ({ paths, pathsDelimiter, pathsDelimiterPattern, vars, varsAssignor, varsAssignorPattern, varsDelimiter, varsDelimiterPattern, debug: _debug, scripts: _scripts, ...rest }: RootOptionsShapeCompat) => GetDotenvOptions;
 
 /**
  * Recursively expands environment variables in a string. Variables may be
@@ -226,10 +267,12 @@ declare const dotenvExpand: (value: string | undefined, ref?: ProcessEnv) => str
  * When `progressive` is true, each expanded key becomes available for
  * subsequent expansions in the same object (left-to-right by object key order).
  */
-declare const dotenvExpandAll: (values?: ProcessEnv, options?: {
-    ref?: ProcessEnv;
+declare function dotenvExpandAll<T extends Record<string, string | undefined> | Readonly<Record<string, string | undefined>>>(values: T, options?: {
+    ref?: Record<string, string | undefined>;
     progressive?: boolean;
-}) => Record<string, string | undefined>;
+}): Record<string, string | undefined> & {
+    [K in keyof T]: string | undefined;
+};
 /**
  * Recursively expands environment variables in a string using `process.env` as
  * the expansion reference. Variables may be presented with optional default as
@@ -247,198 +290,328 @@ declare const dotenvExpandAll: (values?: ProcessEnv, options?: {
  */
 declare const dotenvExpandFromProcessEnv: (value: string | undefined) => string | undefined;
 
-type Scripts = Record<string, string | {
-    cmd: string;
-    shell?: string | boolean;
-}>;
 /**
- * Options passed programmatically to `getDotenvCli`.
+ * Asynchronously process dotenv files of the form `.env[.<ENV>][.<PRIVATE_TOKEN>]`
+ *
+ * @param options - `GetDotenvOptions` object
+ * @returns The combined parsed dotenv object.
+ * * @example Load from the project root with default tokens
+ * ```ts
+ * const vars = await getDotenv();
+ * console.log(vars.MY_SETTING);
+ * ```
+ *
+ * @example Load from multiple paths and a specific environment
+ * ```ts
+ * const vars = await getDotenv({
+ *   env: 'dev',
+ *   dotenvToken: '.testenv',
+ *   privateToken: 'secret',
+ *   paths: ['./', './packages/app'],
+ * });
+ * ```
+ *
+ * @example Use dynamic variables
+ * ```ts
+ * // .env.js default-exports: { DYNAMIC: ({ PREV }) => `${PREV}-suffix` }
+ * const vars = await getDotenv({ dynamicPath: '.env.js' });
+ * ```
+ *
+ * @remarks
+ * - When {@link GetDotenvOptions | loadProcess} is true, the resulting variables are merged
+ *   into `process.env` as a side effect.
+ * - When {@link GetDotenvOptions | outputPath} is provided, a consolidated dotenv file is written.
+ *   The path is resolved after expansion, so it may reference previously loaded vars.
+ *
+ * @throws Error when a dynamic module is present but cannot be imported.
+ * @throws Error when an output path was requested but could not be resolved.
+ */
+declare function getDotenv<Vars extends ProcessEnv = ProcessEnv>(options?: Partial<GetDotenvOptions>): Promise<Vars>;
+declare function getDotenv<Vars extends ProcessEnv>(options: Partial<GetDotenvOptions> & {
+    vars: Vars;
+}): Promise<ProcessEnv & Vars>;
+
+/** src/types/deepReadonly.ts
+ * Utility DeepReadonly type for downstream DX.
+ * Compile-time only; no runtime footprint.
+ */
+type DeepReadonly<T> = T extends (...args: unknown[]) => unknown ? T : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepReadonly<U>> : T extends Array<infer U> ? ReadonlyArray<DeepReadonly<U>> : T extends object ? {
+    readonly [K in keyof T]: DeepReadonly<T[K]>;
+} : T;
+
+/**
+ * Deeply interpolate string leaves against envRef.
+ * Arrays are not recursed into; they are returned unchanged.
+ *
+ * @typeParam T - Shape of the input value.
+ * @param value - Input value (object/array/primitive).
+ * @param envRef - Reference environment for interpolation.
+ * @returns A new value with string leaves interpolated.
  */
-interface GetDotenvCliOptions extends Omit<GetDotenvOptions, 'paths' | 'vars'> {
-    /**
-     * Logs CLI internals when true.
-     */
-    debug?: boolean;
+declare const interpolateDeep: <T>(value: T, envRef: ProcessEnv) => T;
+
+type ResolvedHelpConfig = Partial<GetDotenvCliOptions> & {
+    plugins: Record<string, unknown>;
+};
+/** Per-invocation context shared with plugins and actions. */
+type GetDotenvCliCtx<TOptions extends GetDotenvOptions = GetDotenvOptions> = {
+    optionsResolved: TOptions;
+    dotenv: ProcessEnv;
+    plugins?: Record<string, unknown>;
+    pluginConfigs?: Record<string, unknown>;
+};
+declare const CTX_SYMBOL: unique symbol;
+declare const OPTS_SYMBOL: unique symbol;
+declare const HELP_HEADER_SYMBOL: unique symbol;
+/**
+ * Plugin-first CLI host for get-dotenv. Extends Commander.Command.
+ *
+ * Responsibilities:
+ * - Resolve options strictly and compute dotenv context (resolveAndLoad).
+ * - Expose a stable accessor for the current context (getCtx).
+ * - Provide a namespacing helper (ns).
+ * - Support composable plugins with parent → children install and afterResolve.
+ */
+declare class GetDotenvCli$1<TOptions extends GetDotenvOptions = GetDotenvOptions> extends Command implements GetDotenvCliPublic<TOptions> {
+    /** Registered top-level plugins (composition happens via .use()) */
+    private _plugins;
+    /** One-time installation guard */
+    private _installed;
+    /** Optional header line to prepend in help output */
+    private [HELP_HEADER_SYMBOL];
+    /** Context/options stored under symbols (typed) */
+    private [CTX_SYMBOL]?;
+    private [OPTS_SYMBOL]?;
     /**
-     * Strict mode: fail the run when env validation issues are detected
-     * (schema or requiredKeys). Warns by default when false or unset.
+     * Create a subcommand using the same subclass, preserving helpers like
+     * dynamicOption on children.
      */
-    strict?: boolean;
+    createCommand(name?: string): Command;
+    constructor(alias?: string);
     /**
-     * Redaction (presentation): mask secret-like values in logs/trace.
+     * Resolve options (strict) and compute dotenv context.
+     * Stores the context on the instance under a symbol.
+     *
+     * Options:
+     * - opts.runAfterResolve (default true): 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.
      */
-    redact?: boolean;
+    resolveAndLoad(customOptions?: Partial<TOptions>, opts?: {
+        runAfterResolve?: boolean;
+    }): Promise<GetDotenvCliCtx<TOptions>>;
     /**
-     * Entropy warnings (presentation): emit once-per-key warnings for high-entropy values.
+     * Create a Commander Option that computes its description at help time.
+     * The returned Option may be configured (conflicts, default, parser) and
+     * added via addOption().
      */
-    warnEntropy?: boolean;
-    entropyThreshold?: number;
-    entropyMinLength?: number;
-    entropyWhitelist?: string[];
-    redactPatterns?: string[];
+    createDynamicOption(flags: string, desc: (cfg: ResolvedHelpConfig & {
+        plugins: Record<string, unknown>;
+    }) => string, parser?: (value: string, previous?: unknown) => unknown, defaultValue?: unknown): Option;
+    createDynamicOption<TValue = unknown>(flags: string, desc: (cfg: ResolvedHelpConfig & {
+        plugins: Record<string, unknown>;
+    }) => string, parser: (value: string, previous?: TValue) => TValue, defaultValue?: TValue): Option;
     /**
-     * When true, capture child stdout/stderr and re-emit after completion.
-     * Useful for tests/CI. Default behavior is streaming via stdio: 'inherit'.
+     * Chainable helper mirroring .option(), but with a dynamic description.
+     * Equivalent to addOption(createDynamicOption(...)).
      */
-    capture?: boolean;
+    dynamicOption(flags: string, desc: (cfg: ResolvedHelpConfig & {
+        plugins: Record<string, unknown>;
+    }) => string, parser?: (value: string, previous?: unknown) => unknown, defaultValue?: unknown): this;
     /**
-     * A delimited string of paths to dotenv files.
+     * Evaluate dynamic descriptions for this command and all descendants using
+     * the provided resolved configuration. Mutates the Option.description in
+     * place so Commander help renders updated text.
      */
-    paths?: string;
+    evaluateDynamicOptions(resolved: ResolvedHelpConfig): void;
     /**
-     * A delimiter string with which to split `paths`. Only used if
-     * `pathsDelimiterPattern` is not provided.
+     * Retrieve the current invocation context (if any).
      */
-    pathsDelimiter?: string;
+    getCtx(): GetDotenvCliCtx<TOptions> | undefined;
     /**
-     * A regular expression pattern with which to split `paths`. Supersedes
-     * `pathsDelimiter`.
+     * Retrieve the merged root CLI options bag (if set by passOptions()).
+     * Downstream-safe: no generics required.
      */
-    pathsDelimiterPattern?: string;
+    getOptions(): GetDotenvCliOptions | undefined;
+    /** Internal: set the merged root options bag for this run. */
+    _setOptionsBag(bag: GetDotenvCliOptions): void;
+    /** Convenience helper to create a namespaced subcommand. */
+    ns(name: string): Command;
     /**
-     * Scripts that can be executed from the CLI, either individually or via the batch subcommand.
+     * Tag options added during the provided callback as 'app' for grouped help.
+     * Allows downstream apps to demarcate their root-level options.
      */
-    scripts?: Scripts;
+    tagAppOptions<T>(fn: (root: Command) => T): T;
     /**
-     * Determines how commands and scripts are executed. If `false` or
-     * `undefined`, commands are executed as plain Javascript using the default
-     * execa parser. If `true`, commands are executed using the default OS shell
-     * parser. Otherwise the user may provide a specific shell string (e.g.
-     * `/bin/bash`)
+     * Branding helper: set CLI name/description/version and optional help header.
+     * If version is omitted and importMetaUrl is provided, attempts to read the
+     * nearest package.json version (best-effort; non-fatal on failure).
      */
-    shell?: string | boolean;
+    brand(args: {
+        name?: string;
+        description?: string;
+        version?: string;
+        importMetaUrl?: string;
+        helpHeader?: string;
+    }): Promise<this>;
     /**
-     * A delimited string of key-value pairs declaratively specifying variables &
-     * values to be loaded in addition to any dotenv files.
+     * Insert grouped plugin/app options between "Options" and "Commands" for
+     * hybrid ordering. Applies to root and any parent command.
      */
-    vars?: string;
+    helpInformation(): string;
     /**
-     * A string with which to split keys from values in `vars`. Only used if
-     * `varsDelimiterPattern` is not provided.
+     * Public: tag an Option with a display group for help (root/app/plugin:<id>).
      */
-    varsAssignor?: string;
+    setOptionGroup(opt: Option, group: string): void;
     /**
-     * A regular expression pattern with which to split variable names from values
-     * in `vars`. Supersedes `varsAssignor`.
+     * Register a plugin for installation (parent level).
+     * Installation occurs on first resolveAndLoad() (or explicit install()).
      */
-    varsAssignorPattern?: string;
+    use(plugin: GetDotenvCliPlugin<TOptions>): this;
     /**
-     * A string with which to split `vars` into key-value pairs. Only used if
-     * `varsDelimiterPattern` is not provided.
+     * Install all registered plugins in parent → children (pre-order).
+     * Runs only once per CLI instance.
      */
-    varsDelimiter?: string;
+    install(): Promise<void>;
     /**
-     * A regular expression pattern with which to split `vars` into key-value
-     * pairs. Supersedes `varsDelimiter`.
+     * Run afterResolve hooks for all plugins (parent → children).
      */
-    varsDelimiterPattern?: string;
+    private _runAfterResolve;
 }
 
-/**
- * GetDotenv CLI Pre-hook Callback function type. Mutates inbound options &
- * executes side effects within the `getDotenv` context.
- */
-type GetDotenvCliPreHookCallback = (options: GetDotenvCliOptions) => Promise<void>;
-/**
- * GetDotenv CLI Post-hook Callback function type. Executes side effects within
- * the `getDotenv` context.
+/** src/cliHost/definePlugin.ts
+ * Plugin contracts for the GetDotenv CLI host.
+ *
+ * This module exposes a structural public interface for the host that plugins
+ * should use (GetDotenvCliPublic). Using a structural type at the seam avoids
+ * nominal class identity issues (private fields) in downstream consumers.
  */
-type GetDotenvCliPostHookCallback = (dotenv: ProcessEnv) => Promise<void>;
+
 /**
- * `generateGetDotenvCli` options. Defines local instance of the GetDotenv CLI and
- * sets defaults that can be overridden by local `getdotenv.config.json` in
- * projects that import the CLI.
+ * 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 GetDotenvCliGenerateOptions extends GetDotenvCliOptions {
-    /**
-     * CLI alias. Should align with the `bin` property in `package.json`.
-     */
-    alias: string;
+interface GetDotenvCliPublic<TOptions extends GetDotenvOptions = GetDotenvOptions> extends Command {
+    ns(name: string): Command;
+    getCtx(): GetDotenvCliCtx<TOptions> | undefined;
+    resolveAndLoad(customOptions?: Partial<TOptions>, opts?: {
+        runAfterResolve?: boolean;
+    }): Promise<GetDotenvCliCtx<TOptions>>;
+    setOptionGroup(opt: Option, group: string): void;
+    /**
+     * Create a dynamic option whose description is computed at help time
+     * from the resolved configuration.
+     */
+    createDynamicOption(flags: string, desc: (cfg: ResolvedHelpConfig & {
+        plugins: Record<string, unknown>;
+    }) => string, parser?: (value: string, previous?: unknown) => unknown, defaultValue?: unknown): Option;
+    createDynamicOption<TValue = unknown>(flags: string, desc: (cfg: ResolvedHelpConfig & {
+        plugins: Record<string, unknown>;
+    }) => string, parser: (value: string, previous?: TValue) => TValue, defaultValue?: TValue): Option;
+}
+/** Public plugin contract used by the GetDotenv CLI host. */
+interface GetDotenvCliPlugin<TOptions extends GetDotenvOptions = GetDotenvOptions> {
+    id?: string;
     /**
-     * Cli description (appears in CLI help).
+     * Setup phase: register commands and wiring on the provided CLI instance.
+     * Runs parent → children (pre-order).
      */
-    description: string;
+    setup: (cli: GetDotenvCliPublic<TOptions>) => void | Promise<void>;
     /**
-     * The `import.meta.url` of the module generating the CLI.
+     * 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).
      */
-    importMetaUrl: string;
+    afterResolve?: (cli: GetDotenvCliPublic<TOptions>, ctx: GetDotenvCliCtx<TOptions>) => void | Promise<void>;
     /**
-     * Logger object (defaults to console)
+     * Zod schema for this plugin's config slice (from config.plugins[id]).
+     * Enforced object-like (ZodObject) to simplify code paths and inference.
      */
-    logger: Logger;
+    configSchema?: ZodObject;
     /**
-     * Mutates inbound options & executes side effects within the `getDotenv`
-     * context before executing CLI commands.
+     * Compositional children. Installed after the parent per pre-order.
      */
-    preHook?: GetDotenvCliPreHookCallback;
+    children: GetDotenvCliPlugin<TOptions>[];
     /**
-     * Executes side effects within the `getDotenv` context after executing CLI
-     * commands.
+     * Compose a child plugin. Returns the parent to enable chaining.
      */
-    postHook?: GetDotenvCliPostHookCallback;
+    use: (child: GetDotenvCliPlugin<TOptions>) => GetDotenvCliPlugin<TOptions>;
 }
-
 /**
- * Generate a Commander CLI Command for get-dotenv.
- * Orchestration only: delegates building and lifecycle hooks.
+ * 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.
  */
-declare const generateGetDotenvCli: (customOptions: Pick<GetDotenvCliGenerateOptions, "importMetaUrl"> & Partial<Omit<GetDotenvCliGenerateOptions, "importMetaUrl">>) => Promise<Command>;
-
+type PluginWithInstanceHelpers<TOptions extends GetDotenvOptions = GetDotenvOptions, TConfig = unknown> = GetDotenvCliPlugin<TOptions> & {
+    readConfig<TCfg = TConfig>(cli: GetDotenvCliPublic<TOptions>): Readonly<TCfg>;
+    createPluginDynamicOption<TCfg = TConfig>(cli: GetDotenvCliPublic<TOptions>, flags: string, desc: (cfg: ResolvedHelpConfig & {
+        plugins: Record<string, unknown>;
+    }, pluginCfg: Readonly<TCfg>) => string, parser?: (value: string, previous?: unknown) => unknown, defaultValue?: unknown): Option;
+};
 /**
- * Asynchronously process dotenv files of the form `.env[.<ENV>][.<PRIVATE_TOKEN>]`
- *
- * @param options - `GetDotenvOptions` object
- * @returns The combined parsed dotenv object.
- * * @example Load from the project root with default tokens
- * ```ts
- * const vars = await getDotenv();
- * console.log(vars.MY_SETTING);
- * ```
- *
- * @example Load from multiple paths and a specific environment
- * ```ts
- * const vars = await getDotenv({
- *   env: 'dev',
- *   dotenvToken: '.testenv',
- *   privateToken: 'secret',
- *   paths: ['./', './packages/app'],
- * });
- * ```
- *
- * @example Use dynamic variables
- * ```ts
- * // .env.js default-exports: { DYNAMIC: ({ PREV }) => `${PREV}-suffix` }
- * const vars = await getDotenv({ dynamicPath: '.env.js' });
- * ```
- *
- * @remarks
- * - When {@link GetDotenvOptions.loadProcess} is true, the resulting variables are merged
- *   into `process.env` as a side effect.
- * - When {@link GetDotenvOptions.outputPath} is provided, a consolidated dotenv file is written.
- *   The path is resolved after expansion, so it may reference previously loaded vars.
+ * Public spec type for defining a plugin with optional children.
+ * Exported to ensure TypeDoc links and navigation resolve correctly.
+ */
+type DefineSpec<TOptions extends GetDotenvOptions = GetDotenvOptions> = Omit<GetDotenvCliPlugin<TOptions>, 'children' | 'use'> & {
+    children?: GetDotenvCliPlugin<TOptions>[];
+};
+/**
+ * Define a GetDotenv CLI plugin with compositional helpers.
  *
- * @throws Error when a dynamic module is present but cannot be imported.
- * @throws Error when an output path was requested but could not be resolved.
+ * @example
+ * const parent = definePlugin({ id: 'p', setup(cli) { /* omitted *\/ } })
+ *   .use(childA)
+ *   .use(childB);
  */
-declare const getDotenv: (options?: Partial<GetDotenvOptions>) => Promise<ProcessEnv>;
+declare function definePlugin<TOptions extends GetDotenvOptions, Schema extends ZodObject>(spec: Omit<DefineSpec<TOptions>, 'configSchema'> & {
+    configSchema: Schema;
+}): PluginWithInstanceHelpers<TOptions, z.output<Schema>>;
+declare function definePlugin<TOptions extends GetDotenvOptions>(spec: DefineSpec<TOptions>): PluginWithInstanceHelpers<TOptions, {}>;
 
 /**
- * Deeply interpolate string leaves against envRef.
- * Arrays are not recursed into; they are returned unchanged.
- *
- * @typeParam T - Shape of the input value.
- * @param value - Input value (object/array/primitive).
- * @param envRef - Reference environment for interpolation.
- * @returns A new value with string leaves interpolated.
+ * Infer the compile-time plugin config type from a plugin instance created by definePlugin.
+ * Returns a deeply readonly view to discourage mutation at call sites.
  */
-declare const interpolateDeep: <T>(value: T, envRef: ProcessEnv) => T;
+type InferPluginConfig<P> = P extends PluginWithInstanceHelpers<GetDotenvOptions, infer C> ? Readonly<C> : never;
+
+/**
+ * GetDotenvCli with root helpers as real class methods.
+ * - attachRootOptions: installs legacy/base root flags on the command.
+ * - passOptions: merges flags (parent \< current), computes dotenv context once,
+ *   runs validation, and persists merged options for nested flows.
+ */
+declare class GetDotenvCli extends GetDotenvCli$1 {
+    /**
+     * Attach legacy root flags to this CLI instance. Defaults come from
+     * baseRootOptionDefaults when none are provided.
+     */
+    attachRootOptions(defaults?: Partial<RootOptionsShape>): this;
+    /**
+     * Install preSubcommand/preAction hooks that:
+     * - Merge options (parent round-trip + current invocation) using resolveCliOptions.
+     * - Persist the merged bag on the current command and on the host (for ergonomics).
+     * - Compute the dotenv context once via resolveAndLoad(serviceOptions).
+     * - Validate the composed env against discovered config (warn or --strict fail).
+     */
+    passOptions(defaults?: Partial<RootOptionsShape>): this;
+}
+/**
+ * Helper to retrieve the merged root options bag from any action handler
+ * that only has access to thisCommand. Avoids structural casts.
+ */
+declare const readMergedOptions: (cmd: Command) => GetDotenvCliOptions | undefined;
 
 /**
  * Create a get-dotenv CLI host with included plugins.
  *
  * Options:
  * - alias: command name used for help/argv scaffolding (default: "getdotenv")
- * - branding: optional help header; when omitted, brand() uses "<alias> v<version>"
+ * - branding: optional help header; when omitted, brand() uses "\<alias\> v\<version\>"
  *
  * Usage:
  *   import \{ createCli \} from '\@karmaniverous/get-dotenv';
@@ -453,5 +626,5 @@ declare function createCli(opts?: CreateCliOptions): {
     run: (argv: string[]) => Promise<void>;
 };
 
-export { buildSpawnEnv, createCli, defineDynamic, dotenvExpand, dotenvExpandAll, dotenvExpandFromProcessEnv, generateGetDotenvCli, getDotenv, getDotenvCliOptions2Options, interpolateDeep };
-export type { CreateCliOptions, GetDotenvDynamic, GetDotenvOptions, ProcessEnv };
+export { GetDotenvCli, buildSpawnEnv, createCli, defineDynamic, defineGetDotenvConfig, definePlugin, defineScripts, dotenvExpand, dotenvExpandAll, dotenvExpandFromProcessEnv, getDotenv, getDotenvCliOptions2Options, interpolateDeep, readMergedOptions };
+export type { CreateCliOptions, DeepReadonly, DynamicFn, DynamicMap, GetDotenvCliOptions, GetDotenvCliPlugin, GetDotenvCliPublic, GetDotenvConfig, GetDotenvDynamic, GetDotenvOptions, InferGetDotenvVarsFromConfig, InferPluginConfig, PluginWithInstanceHelpers, ProcessEnv, ScriptsTable };