@karmaniverous/get-dotenv 5.2.3 → 5.2.5

package/dist/plugins-aws.d.ts

@@ -1,5 +1,75 @@
-import { ZodType } from 'zod';
 import { Command } from 'commander';
+import { ZodType } from 'zod';
+
+/**
+ * Minimal root options shape shared by CLI and generator layers.
+ * Keep keys optional to respect exactOptionalPropertyTypes semantics.
+ */
+type RootOptionsShape = {
+    env?: string;
+    vars?: string;
+    command?: string;
+    outputPath?: string;
+    shell?: string | boolean;
+    loadProcess?: boolean;
+    excludeAll?: boolean;
+    excludeDynamic?: boolean;
+    excludeEnv?: boolean;
+    excludeGlobal?: boolean;
+    excludePrivate?: boolean;
+    excludePublic?: boolean;
+    log?: boolean;
+    debug?: boolean;
+    capture?: boolean;
+    strict?: boolean;
+    redact?: boolean;
+    warnEntropy?: boolean;
+    entropyThreshold?: number;
+    entropyMinLength?: number;
+    entropyWhitelist?: string[];
+    redactPatterns?: string[];
+    defaultEnv?: string;
+    dotenvToken?: string;
+    dynamicPath?: string;
+    trace?: boolean | string[];
+    paths?: string;
+    pathsDelimiter?: string;
+    pathsDelimiterPattern?: string;
+    privateToken?: string;
+    varsDelimiter?: string;
+    varsDelimiterPattern?: string;
+    varsAssignor?: string;
+    varsAssignorPattern?: string;
+    scripts?: ScriptsTable;
+};
+/**
+ * Scripts table shape (configurable shell type).
+ */
+type ScriptsTable<TShell extends string | boolean = string | boolean> = Record<string, string | {
+    cmd: string;
+    shell?: TShell;
+}>;
+
+/**
+ * Adapter-layer augmentation: add chainable helpers to GetDotenvCli without
+ * coupling the core host to cliCore. Importing this module has side effects:
+ * it extends the prototype and merges types for consumers.
+ */
+declare module '../cliHost/GetDotenvCli' {
+    interface GetDotenvCli {
+        /**
+         * Attach legacy root flags to this CLI instance. Defaults come from
+         * baseRootOptionDefaults when none are provided.     */
+        attachRootOptions(defaults?: Partial<RootOptionsShape>, opts?: {
+            includeCommandOption?: boolean;
+        }): this;
+        /**
+         * Install a preSubcommand hook that merges CLI flags (including parent
+         * round-trip) and resolves the dotenv context before executing actions.
+         * Defaults come from baseRootOptionDefaults when none are provided.
+         */ passOptions(defaults?: Partial<RootOptionsShape>): this;
+    }
+}
 
 /**
  * A minimal representation of an environment key/value mapping.
@@ -95,93 +165,6 @@ interface GetDotenvOptions {
     useConfigLoader?: boolean;
 }
 
-type Scripts = Record<string, string | {
-    cmd: string;
-    shell?: string | boolean;
-}>;
-/**
- * Options passed programmatically to `getDotenvCli`.
- */
-interface GetDotenvCliOptions extends Omit<GetDotenvOptions, 'paths' | 'vars'> {
-    /**
-     * Logs CLI internals when true.
-     */
-    debug?: boolean;
-    /**
-     * Strict mode: fail the run when env validation issues are detected
-     * (schema or requiredKeys). Warns by default when false or unset.
-     */
-    strict?: boolean;
-    /**
-     * Redaction (presentation): mask secret-like values in logs/trace.
-     */
-    redact?: boolean;
-    /**
-     * Entropy warnings (presentation): emit once-per-key warnings for high-entropy values.
-     */
-    warnEntropy?: boolean;
-    entropyThreshold?: number;
-    entropyMinLength?: number;
-    entropyWhitelist?: string[];
-    redactPatterns?: string[];
-    /**
-     * When true, capture child stdout/stderr and re-emit after completion.
-     * Useful for tests/CI. Default behavior is streaming via stdio: 'inherit'.
-     */
-    capture?: boolean;
-    /**
-     * A delimited string of paths to dotenv files.
-     */
-    paths?: string;
-    /**
-     * A delimiter string with which to split `paths`. Only used if
-     * `pathsDelimiterPattern` is not provided.
-     */
-    pathsDelimiter?: string;
-    /**
-     * A regular expression pattern with which to split `paths`. Supersedes
-     * `pathsDelimiter`.
-     */
-    pathsDelimiterPattern?: string;
-    /**
-     * Scripts that can be executed from the CLI, either individually or via the batch subcommand.
-     */
-    scripts?: Scripts;
-    /**
-     * 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`)
-     */
-    shell?: string | boolean;
-    /**
-     * A delimited string of key-value pairs declaratively specifying variables &
-     * values to be loaded in addition to any dotenv files.
-     */
-    vars?: string;
-    /**
-     * A string with which to split keys from values in `vars`. Only used if
-     * `varsDelimiterPattern` is not provided.
-     */
-    varsAssignor?: string;
-    /**
-     * A regular expression pattern with which to split variable names from values
-     * in `vars`. Supersedes `varsAssignor`.
-     */
-    varsAssignorPattern?: string;
-    /**
-     * A string with which to split `vars` into key-value pairs. Only used if
-     * `varsDelimiterPattern` is not provided.
-     */
-    varsDelimiter?: string;
-    /**
-     * A regular expression pattern with which to split `vars` into key-value
-     * pairs. Supersedes `varsDelimiter`.
-     */
-    varsDelimiterPattern?: string;
-}
-
 /** * Per-invocation context shared with plugins and actions. */
 type GetDotenvCliCtx<TOptions extends GetDotenvOptions = GetDotenvOptions> = {
     optionsResolved: TOptions;
@@ -189,89 +172,42 @@ type GetDotenvCliCtx<TOptions extends GetDotenvOptions = GetDotenvOptions> = {
     plugins?: Record<string, unknown>;
     pluginConfigs?: Record<string, unknown>;
 };
-declare const HELP_HEADER_SYMBOL: unique symbol;
-/**
- * Plugin-first CLI host for get-dotenv. Extends Commander.Command.
+
+/** src/cliHost/definePlugin.ts
+ * Plugin contracts for the GetDotenv CLI host.
  *
- * 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.
+ * 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.
+ */
+
+/**
+ * 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.
  *
- * NOTE: This host is additive and does not alter the legacy CLI.
+ * Purpose: remove nominal class identity (private fields) from the plugin seam
+ * to avoid TS2379 under exactOptionalPropertyTypes in downstream consumers.
  */
-declare class GetDotenvCli<TOptions extends GetDotenvOptions = GetDotenvOptions> extends Command {
-    #private;
-    /** 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];
-    constructor(alias?: string);
-    /**
-     * Resolve options (strict) and compute dotenv context.   * Stores the context on the instance under a symbol.
-     */
-    resolveAndLoad(customOptions?: Partial<TOptions>): Promise<GetDotenvCliCtx<TOptions>>;
-    /**
-     * Retrieve the current invocation context (if any).
-     */
-    getCtx(): GetDotenvCliCtx<TOptions> | undefined;
-    /**
-     * Retrieve the merged root CLI options bag (if set by passOptions()).
-     * Downstream-safe: no generics required.
-     */
-    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;
-    /**
-     * Tag options added during the provided callback as 'app' for grouped help.
-     * Allows downstream apps to demarcate their root-level options.
-     */
-    tagAppOptions<T>(fn: (root: Command) => T): T;
-    /**
-     * 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).
-     */
-    brand(args: {
-        name?: string;
-        description?: string;
-        version?: string;
-        importMetaUrl?: string;
-        helpHeader?: string;
-    }): Promise<this>;
-    /**
-     * Register a plugin for installation (parent level).
-     * Installation occurs on first resolveAndLoad() (or explicit install()).
-     */
-    use(plugin: GetDotenvCliPlugin): this;
+type GetDotenvCliPublic<TOptions extends GetDotenvOptions = GetDotenvOptions> = Command & {
+    ns: (name: string) => Command;
+    getCtx: () => GetDotenvCliCtx<TOptions> | undefined;
+    resolveAndLoad: (customOptions?: Partial<TOptions>) => Promise<GetDotenvCliCtx<TOptions>>;
+};
+/** Public plugin contract used by the GetDotenv CLI host. */
+interface GetDotenvCliPlugin {
+    id?: string;
     /**
-     * Install all registered plugins in parent → children (pre-order).
-     * Runs only once per CLI instance.
+     * Setup phase: register commands and wiring on the provided CLI instance.
+     * Runs parent → children (pre-order).
      */
-    install(): Promise<void>;
-    /**
-     * Run afterResolve hooks for all plugins (parent → children).
-     */
-    private _runAfterResolve;
-}
-
-/** Public plugin contract used by the GetDotenv CLI host. */ interface GetDotenvCliPlugin {
-    id?: string /**
-     * Setup phase: register commands and wiring on the provided CLI instance.   * Runs parent → children (pre-order).
-     */;
-    setup: (cli: GetDotenvCli) => void | Promise<void>;
+    setup: (cli: GetDotenvCliPublic) => 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).
      */
-    afterResolve?: (cli: GetDotenvCli, ctx: GetDotenvCliCtx) => void | Promise<void>;
+    afterResolve?: (cli: GetDotenvCliPublic, ctx: GetDotenvCliCtx) => void | Promise<void>;
     /**
      * Optional Zod schema for this plugin's config slice (from config.plugins[id]).
      * When provided, the host validates the merged config under the guarded loader path.
@@ -279,7 +215,8 @@ declare class GetDotenvCli<TOptions extends GetDotenvOptions = GetDotenvOptions>
     configSchema?: ZodType;
     /**
      * Compositional children. Installed after the parent per pre-order.
-     */ children: GetDotenvCliPlugin[];
+     */
+    children: GetDotenvCliPlugin[];
     /**
      * Compose a child plugin. Returns the parent to enable chaining.
      */

package/dist/plugins-aws.mjs

@@ -234,6 +234,13 @@ const buildSpawnEnv = (base, overlay) => {
     return out;
 };
 
+/** 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.
+ */
 /**
  * Define a GetDotenv CLI plugin with compositional helpers.
  *

package/dist/plugins-batch.cjs

@@ -7,6 +7,13 @@ var path = require('path');
 var execa = require('execa');
 var zod = require('zod');
 
+/** 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.
+ */
 /**
  * Define a GetDotenv CLI plugin with compositional helpers.
  *

package/dist/plugins-batch.d.cts

@@ -1,5 +1,75 @@
-import { ZodType } from 'zod';
 import { Command } from 'commander';
+import { ZodType } from 'zod';
+
+/**
+ * Minimal root options shape shared by CLI and generator layers.
+ * Keep keys optional to respect exactOptionalPropertyTypes semantics.
+ */
+type RootOptionsShape = {
+    env?: string;
+    vars?: string;
+    command?: string;
+    outputPath?: string;
+    shell?: string | boolean;
+    loadProcess?: boolean;
+    excludeAll?: boolean;
+    excludeDynamic?: boolean;
+    excludeEnv?: boolean;
+    excludeGlobal?: boolean;
+    excludePrivate?: boolean;
+    excludePublic?: boolean;
+    log?: boolean;
+    debug?: boolean;
+    capture?: boolean;
+    strict?: boolean;
+    redact?: boolean;
+    warnEntropy?: boolean;
+    entropyThreshold?: number;
+    entropyMinLength?: number;
+    entropyWhitelist?: string[];
+    redactPatterns?: string[];
+    defaultEnv?: string;
+    dotenvToken?: string;
+    dynamicPath?: string;
+    trace?: boolean | string[];
+    paths?: string;
+    pathsDelimiter?: string;
+    pathsDelimiterPattern?: string;
+    privateToken?: string;
+    varsDelimiter?: string;
+    varsDelimiterPattern?: string;
+    varsAssignor?: string;
+    varsAssignorPattern?: string;
+    scripts?: ScriptsTable;
+};
+/**
+ * Scripts table shape (configurable shell type).
+ */
+type ScriptsTable<TShell extends string | boolean = string | boolean> = Record<string, string | {
+    cmd: string;
+    shell?: TShell;
+}>;
+
+/**
+ * Adapter-layer augmentation: add chainable helpers to GetDotenvCli without
+ * coupling the core host to cliCore. Importing this module has side effects:
+ * it extends the prototype and merges types for consumers.
+ */
+declare module '../cliHost/GetDotenvCli' {
+    interface GetDotenvCli {
+        /**
+         * Attach legacy root flags to this CLI instance. Defaults come from
+         * baseRootOptionDefaults when none are provided.     */
+        attachRootOptions(defaults?: Partial<RootOptionsShape>, opts?: {
+            includeCommandOption?: boolean;
+        }): this;
+        /**
+         * Install a preSubcommand hook that merges CLI flags (including parent
+         * round-trip) and resolves the dotenv context before executing actions.
+         * Defaults come from baseRootOptionDefaults when none are provided.
+         */ passOptions(defaults?: Partial<RootOptionsShape>): this;
+    }
+}
 
 /**
  * A minimal representation of an environment key/value mapping.
@@ -95,93 +165,6 @@ interface GetDotenvOptions {
     useConfigLoader?: boolean;
 }
 
-type Scripts$1 = Record<string, string | {
-    cmd: string;
-    shell?: string | boolean;
-}>;
-/**
- * Options passed programmatically to `getDotenvCli`.
- */
-interface GetDotenvCliOptions extends Omit<GetDotenvOptions, 'paths' | 'vars'> {
-    /**
-     * Logs CLI internals when true.
-     */
-    debug?: boolean;
-    /**
-     * Strict mode: fail the run when env validation issues are detected
-     * (schema or requiredKeys). Warns by default when false or unset.
-     */
-    strict?: boolean;
-    /**
-     * Redaction (presentation): mask secret-like values in logs/trace.
-     */
-    redact?: boolean;
-    /**
-     * Entropy warnings (presentation): emit once-per-key warnings for high-entropy values.
-     */
-    warnEntropy?: boolean;
-    entropyThreshold?: number;
-    entropyMinLength?: number;
-    entropyWhitelist?: string[];
-    redactPatterns?: string[];
-    /**
-     * When true, capture child stdout/stderr and re-emit after completion.
-     * Useful for tests/CI. Default behavior is streaming via stdio: 'inherit'.
-     */
-    capture?: boolean;
-    /**
-     * A delimited string of paths to dotenv files.
-     */
-    paths?: string;
-    /**
-     * A delimiter string with which to split `paths`. Only used if
-     * `pathsDelimiterPattern` is not provided.
-     */
-    pathsDelimiter?: string;
-    /**
-     * A regular expression pattern with which to split `paths`. Supersedes
-     * `pathsDelimiter`.
-     */
-    pathsDelimiterPattern?: string;
-    /**
-     * Scripts that can be executed from the CLI, either individually or via the batch subcommand.
-     */
-    scripts?: Scripts$1;
-    /**
-     * 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`)
-     */
-    shell?: string | boolean;
-    /**
-     * A delimited string of key-value pairs declaratively specifying variables &
-     * values to be loaded in addition to any dotenv files.
-     */
-    vars?: string;
-    /**
-     * A string with which to split keys from values in `vars`. Only used if
-     * `varsDelimiterPattern` is not provided.
-     */
-    varsAssignor?: string;
-    /**
-     * A regular expression pattern with which to split variable names from values
-     * in `vars`. Supersedes `varsAssignor`.
-     */
-    varsAssignorPattern?: string;
-    /**
-     * A string with which to split `vars` into key-value pairs. Only used if
-     * `varsDelimiterPattern` is not provided.
-     */
-    varsDelimiter?: string;
-    /**
-     * A regular expression pattern with which to split `vars` into key-value
-     * pairs. Supersedes `varsDelimiter`.
-     */
-    varsDelimiterPattern?: string;
-}
-
 /** * Per-invocation context shared with plugins and actions. */
 type GetDotenvCliCtx<TOptions extends GetDotenvOptions = GetDotenvOptions> = {
     optionsResolved: TOptions;
@@ -189,89 +172,42 @@ type GetDotenvCliCtx<TOptions extends GetDotenvOptions = GetDotenvOptions> = {
     plugins?: Record<string, unknown>;
     pluginConfigs?: Record<string, unknown>;
 };
-declare const HELP_HEADER_SYMBOL: unique symbol;
-/**
- * Plugin-first CLI host for get-dotenv. Extends Commander.Command.
+
+/** src/cliHost/definePlugin.ts
+ * Plugin contracts for the GetDotenv CLI host.
  *
- * 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.
+ * 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.
+ */
+
+/**
+ * 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.
  *
- * NOTE: This host is additive and does not alter the legacy CLI.
+ * Purpose: remove nominal class identity (private fields) from the plugin seam
+ * to avoid TS2379 under exactOptionalPropertyTypes in downstream consumers.
  */
-declare class GetDotenvCli<TOptions extends GetDotenvOptions = GetDotenvOptions> extends Command {
-    #private;
-    /** 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];
-    constructor(alias?: string);
-    /**
-     * Resolve options (strict) and compute dotenv context.   * Stores the context on the instance under a symbol.
-     */
-    resolveAndLoad(customOptions?: Partial<TOptions>): Promise<GetDotenvCliCtx<TOptions>>;
-    /**
-     * Retrieve the current invocation context (if any).
-     */
-    getCtx(): GetDotenvCliCtx<TOptions> | undefined;
-    /**
-     * Retrieve the merged root CLI options bag (if set by passOptions()).
-     * Downstream-safe: no generics required.
-     */
-    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;
-    /**
-     * Tag options added during the provided callback as 'app' for grouped help.
-     * Allows downstream apps to demarcate their root-level options.
-     */
-    tagAppOptions<T>(fn: (root: Command) => T): T;
-    /**
-     * 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).
-     */
-    brand(args: {
-        name?: string;
-        description?: string;
-        version?: string;
-        importMetaUrl?: string;
-        helpHeader?: string;
-    }): Promise<this>;
-    /**
-     * Register a plugin for installation (parent level).
-     * Installation occurs on first resolveAndLoad() (or explicit install()).
-     */
-    use(plugin: GetDotenvCliPlugin): this;
+type GetDotenvCliPublic<TOptions extends GetDotenvOptions = GetDotenvOptions> = Command & {
+    ns: (name: string) => Command;
+    getCtx: () => GetDotenvCliCtx<TOptions> | undefined;
+    resolveAndLoad: (customOptions?: Partial<TOptions>) => Promise<GetDotenvCliCtx<TOptions>>;
+};
+/** Public plugin contract used by the GetDotenv CLI host. */
+interface GetDotenvCliPlugin {
+    id?: string;
     /**
-     * Install all registered plugins in parent → children (pre-order).
-     * Runs only once per CLI instance.
+     * Setup phase: register commands and wiring on the provided CLI instance.
+     * Runs parent → children (pre-order).
      */
-    install(): Promise<void>;
-    /**
-     * Run afterResolve hooks for all plugins (parent → children).
-     */
-    private _runAfterResolve;
-}
-
-/** Public plugin contract used by the GetDotenv CLI host. */ interface GetDotenvCliPlugin {
-    id?: string /**
-     * Setup phase: register commands and wiring on the provided CLI instance.   * Runs parent → children (pre-order).
-     */;
-    setup: (cli: GetDotenvCli) => void | Promise<void>;
+    setup: (cli: GetDotenvCliPublic) => 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).
      */
-    afterResolve?: (cli: GetDotenvCli, ctx: GetDotenvCliCtx) => void | Promise<void>;
+    afterResolve?: (cli: GetDotenvCliPublic, ctx: GetDotenvCliCtx) => void | Promise<void>;
     /**
      * Optional Zod schema for this plugin's config slice (from config.plugins[id]).
      * When provided, the host validates the merged config under the guarded loader path.
@@ -279,7 +215,8 @@ declare class GetDotenvCli<TOptions extends GetDotenvOptions = GetDotenvOptions>
     configSchema?: ZodType;
     /**
      * Compositional children. Installed after the parent per pre-order.
-     */ children: GetDotenvCliPlugin[];
+     */
+    children: GetDotenvCliPlugin[];
     /**
      * Compose a child plugin. Returns the parent to enable chaining.
      */