@karmaniverous/get-dotenv 5.2.3 → 5.2.5

package/README.md

@@ -12,11 +12,11 @@ Load environment variables with a cascade of environment-aware dotenv files. You
 
 ✅ Asynchronously load environment variables from multiple dotenv files.
 
-✅ Segregate variables info distinct files:
+✅ Segregate variables into distinct files:
 
-- Public files (e.g. `.env`, `env.dev`, `env.test`) are synced with your git repository.
-- Private files (e.g. `.env.local`, `env.dev.local`, `env.test.local`) are protected by `.gitignore`.
-- Global files (e.g. `.env`, `env.local`) apply to all environments.
+- Public files (e.g. `.env`, `.env.dev`, `.env.test`) are synced with your git repository.
+- Private files (e.g. `.env.local`, `.env.dev.local`, `.env.test.local`) are protected by `.gitignore`.
+- Global files (e.g. `.env`, `.env.local`) apply to all environments.
 - Env files (e.g. `.env.dev`, `.env.dev.local`, `.env.test`, `.env.test.local`) apply to a specific environment.
 - [Dynamic files](#dynamic-processing) (`.env.js`) export logic that dynamically & progressively generates new variables or overrides current ones.
 
@@ -278,7 +278,7 @@ You can also use `getdotenv` from the command line:
 #
 # Commands:
 #   batch [options]                     Batch shell commands across multiple working directories.
-#   cmd                                 Batch execute command according to the --shell option, conflicts with --command option (default command)
+#   cmd                                 Execute command according to the --shell option, conflicts with --command option (default command)
 #   help [command]                      display help for command
 ```
 

package/dist/cliHost.cjs

@@ -12,27 +12,6 @@ var dotenv = require('dotenv');
 var crypto = require('crypto');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
-/**
- * Define a GetDotenv CLI plugin with compositional helpers.
- *
- * @example
- * const parent = definePlugin(\{ id: 'p', setup(cli) \{ /* ... *\/ \} \})
- *   .use(childA)
- *   .use(childB);
- */
-const definePlugin = (spec) => {
-    const { children = [], ...rest } = spec;
-    const plugin = {
-        ...rest,
-        children: [...children],
-        use(child) {
-            this.children.push(child);
-            return this;
-        },
-    };
-    return plugin;
-};
-
 // Base root CLI defaults (shared; kept untyped here to avoid cross-layer deps).
 const baseRootOptionDefaults = {
     dotenvToken: '.env',
@@ -589,6 +568,22 @@ const dotenvExpandAll = (values = {}, options = {}) => Object.keys(values).reduc
     });
     return acc;
 }, {});
+/**
+ * Recursively expands environment variables in a string using `process.env` as
+ * the expansion reference. Variables may be presented with optional default as
+ * `$VAR[:default]` or `${VAR[:default]}`. Unknown variables will expand to an
+ * empty string.
+ *
+ * @param value - The string to expand.
+ * @returns The expanded string.
+ *
+ * @example
+ * ```ts
+ * process.env.FOO = 'bar';
+ * dotenvExpandFromProcessEnv('Hello $FOO'); // "Hello bar"
+ * ```
+ */
+const dotenvExpandFromProcessEnv = (value) => dotenvExpand(value, process.env);
 
 const applyKv = (current, kv) => {
     if (!kv || Object.keys(kv).length === 0)
@@ -1439,6 +1434,412 @@ class GetDotenvCli extends commander.Command {
     }
 }
 
+/**
+ * Validate a composed env against config-provided validation surfaces.
+ * Precedence for validation definitions:
+ *   project.local -\> project.public -\> packaged
+ *
+ * Behavior:
+ * - If a JS/TS `schema` is present, use schema.safeParse(finalEnv).
+ * - Else if `requiredKeys` is present, check presence (value !== undefined).
+ * - Returns a flat list of issue strings; caller decides warn vs fail.
+ */
+const validateEnvAgainstSources = (finalEnv, sources) => {
+    const pick = (getter) => {
+        const pl = sources.project?.local;
+        const pp = sources.project?.public;
+        const pk = sources.packaged;
+        return ((pl && getter(pl)) ||
+            (pp && getter(pp)) ||
+            (pk && getter(pk)) ||
+            undefined);
+    };
+    const schema = pick((cfg) => cfg['schema']);
+    if (schema &&
+        typeof schema.safeParse === 'function') {
+        try {
+            const parsed = schema.safeParse(finalEnv);
+            if (!parsed.success) {
+                // Try to render zod-style issues when available.
+                const err = parsed.error;
+                const issues = Array.isArray(err.issues) && err.issues.length > 0
+                    ? err.issues.map((i) => {
+                        const path = Array.isArray(i.path) ? i.path.join('.') : '';
+                        const msg = i.message ?? 'Invalid value';
+                        return path ? `[schema] ${path}: ${msg}` : `[schema] ${msg}`;
+                    })
+                    : ['[schema] validation failed'];
+                return issues;
+            }
+            return [];
+        }
+        catch {
+            // If schema invocation fails, surface a single diagnostic.
+            return [
+                '[schema] validation failed (unable to execute schema.safeParse)',
+            ];
+        }
+    }
+    const requiredKeys = pick((cfg) => cfg['requiredKeys']);
+    if (Array.isArray(requiredKeys) && requiredKeys.length > 0) {
+        const missing = requiredKeys.filter((k) => finalEnv[k] === undefined);
+        if (missing.length > 0) {
+            return missing.map((k) => `[requiredKeys] missing: ${k}`);
+        }
+    }
+    return [];
+};
+
+/**
+ * Attach legacy root flags to a Commander program.
+ * Uses provided defaults to render help labels without coupling to generators.
+ */
+const attachRootOptions = (program, defaults, opts) => {
+    // Install temporary wrappers to tag all options added here as "base".
+    const GROUP = 'base';
+    const tagLatest = (cmd, group) => {
+        const optsArr = cmd.options;
+        if (Array.isArray(optsArr) && optsArr.length > 0) {
+            const last = optsArr[optsArr.length - 1];
+            last.__group = group;
+        }
+    };
+    const originalAddOption = program.addOption.bind(program);
+    const originalOption = program.option.bind(program);
+    program.addOption = function patchedAdd(opt) {
+        // Tag before adding, in case consumers inspect the Option directly.
+        opt.__group = GROUP;
+        const ret = originalAddOption(opt);
+        return ret;
+    };
+    program.option = function patchedOption(...args) {
+        const ret = originalOption(...args);
+        tagLatest(this, GROUP);
+        return ret;
+    };
+    const { defaultEnv, dotenvToken, dynamicPath, env, excludeDynamic, excludeEnv, excludeGlobal, excludePrivate, excludePublic, loadProcess, log, outputPath, paths, pathsDelimiter, pathsDelimiterPattern, privateToken, scripts, shell, varsAssignor, varsAssignorPattern, varsDelimiter, varsDelimiterPattern, } = defaults ?? {};
+    const va = typeof defaults?.varsAssignor === 'string' ? defaults.varsAssignor : '=';
+    const vd = typeof defaults?.varsDelimiter === 'string' ? defaults.varsDelimiter : ' ';
+    // Build initial chain.
+    let p = program
+        .enablePositionalOptions()
+        .passThroughOptions()
+        .option('-e, --env <string>', `target environment (dotenv-expanded)`, dotenvExpandFromProcessEnv, env);
+    p = p.option('-v, --vars <string>', `extra variables expressed as delimited key-value pairs (dotenv-expanded): ${[
+        ['KEY1', 'VAL1'],
+        ['KEY2', 'VAL2'],
+    ]
+        .map((v) => v.join(va))
+        .join(vd)}`, dotenvExpandFromProcessEnv);
+    // Optional legacy root command flag (kept for generated CLI compatibility).
+    // Default is OFF; the generator opts in explicitly.
+    if (opts?.includeCommandOption === true) {
+        p = p.option('-c, --command <string>', 'command executed according to the --shell option, conflicts with cmd subcommand (dotenv-expanded)', dotenvExpandFromProcessEnv);
+    }
+    p = p
+        .option('-o, --output-path <string>', 'consolidated output file  (dotenv-expanded)', dotenvExpandFromProcessEnv, outputPath)
+        .addOption(new commander.Option('-s, --shell [string]', (() => {
+        let defaultLabel = '';
+        if (shell !== undefined) {
+            if (typeof shell === 'boolean') {
+                defaultLabel = ' (default OS shell)';
+            }
+            else if (typeof shell === 'string') {
+                // Safe string interpolation
+                defaultLabel = ` (default ${shell})`;
+            }
+        }
+        return `command execution shell, no argument for default OS shell or provide shell string${defaultLabel}`;
+    })()).conflicts('shellOff'))
+        .addOption(new commander.Option('-S, --shell-off', `command execution shell OFF${!shell ? ' (default)' : ''}`).conflicts('shell'))
+        .addOption(new commander.Option('-p, --load-process', `load variables to process.env ON${loadProcess ? ' (default)' : ''}`).conflicts('loadProcessOff'))
+        .addOption(new commander.Option('-P, --load-process-off', `load variables to process.env OFF${!loadProcess ? ' (default)' : ''}`).conflicts('loadProcess'))
+        .addOption(new commander.Option('-a, --exclude-all', `exclude all dotenv variables from loading ON${excludeDynamic &&
+        ((excludeEnv && excludeGlobal) || (excludePrivate && excludePublic))
+        ? ' (default)'
+        : ''}`).conflicts('excludeAllOff'))
+        .addOption(new commander.Option('-A, --exclude-all-off', `exclude all dotenv variables from loading OFF (default)`).conflicts('excludeAll'))
+        .addOption(new commander.Option('-z, --exclude-dynamic', `exclude dynamic dotenv variables from loading ON${excludeDynamic ? ' (default)' : ''}`).conflicts('excludeDynamicOff'))
+        .addOption(new commander.Option('-Z, --exclude-dynamic-off', `exclude dynamic dotenv variables from loading OFF${!excludeDynamic ? ' (default)' : ''}`).conflicts('excludeDynamic'))
+        .addOption(new commander.Option('-n, --exclude-env', `exclude environment-specific dotenv variables from loading${excludeEnv ? ' (default)' : ''}`).conflicts('excludeEnvOff'))
+        .addOption(new commander.Option('-N, --exclude-env-off', `exclude environment-specific dotenv variables from loading OFF${!excludeEnv ? ' (default)' : ''}`).conflicts('excludeEnv'))
+        .addOption(new commander.Option('-g, --exclude-global', `exclude global dotenv variables from loading ON${excludeGlobal ? ' (default)' : ''}`).conflicts('excludeGlobalOff'))
+        .addOption(new commander.Option('-G, --exclude-global-off', `exclude global dotenv variables from loading OFF${!excludeGlobal ? ' (default)' : ''}`).conflicts('excludeGlobal'))
+        .addOption(new commander.Option('-r, --exclude-private', `exclude private dotenv variables from loading ON${excludePrivate ? ' (default)' : ''}`).conflicts('excludePrivateOff'))
+        .addOption(new commander.Option('-R, --exclude-private-off', `exclude private dotenv variables from loading OFF${!excludePrivate ? ' (default)' : ''}`).conflicts('excludePrivate'))
+        .addOption(new commander.Option('-u, --exclude-public', `exclude public dotenv variables from loading ON${excludePublic ? ' (default)' : ''}`).conflicts('excludePublicOff'))
+        .addOption(new commander.Option('-U, --exclude-public-off', `exclude public dotenv variables from loading OFF${!excludePublic ? ' (default)' : ''}`).conflicts('excludePublic'))
+        .addOption(new commander.Option('-l, --log', `console log loaded variables ON${log ? ' (default)' : ''}`).conflicts('logOff'))
+        .addOption(new commander.Option('-L, --log-off', `console log loaded variables OFF${!log ? ' (default)' : ''}`).conflicts('log'))
+        .option('--capture', 'capture child process stdio for commands (tests/CI)')
+        .option('--redact', 'mask secret-like values in logs/trace (presentation-only)')
+        .option('--default-env <string>', 'default target environment', dotenvExpandFromProcessEnv, defaultEnv)
+        .option('--dotenv-token <string>', 'dotenv-expanded token indicating a dotenv file', dotenvExpandFromProcessEnv, dotenvToken)
+        .option('--dynamic-path <string>', 'dynamic variables path (.js or .ts; .ts is auto-compiled when esbuild is available, otherwise precompile)', dotenvExpandFromProcessEnv, dynamicPath)
+        .option('--paths <string>', 'dotenv-expanded delimited list of paths to dotenv directory', dotenvExpandFromProcessEnv, paths)
+        .option('--paths-delimiter <string>', 'paths delimiter string', pathsDelimiter)
+        .option('--paths-delimiter-pattern <string>', 'paths delimiter regex pattern', pathsDelimiterPattern)
+        .option('--private-token <string>', 'dotenv-expanded token indicating private variables', dotenvExpandFromProcessEnv, privateToken)
+        .option('--vars-delimiter <string>', 'vars delimiter string', varsDelimiter)
+        .option('--vars-delimiter-pattern <string>', 'vars delimiter regex pattern', varsDelimiterPattern)
+        .option('--vars-assignor <string>', 'vars assignment operator string', varsAssignor)
+        .option('--vars-assignor-pattern <string>', 'vars assignment operator regex pattern', varsAssignorPattern)
+        // Hidden scripts pipe-through (stringified)
+        .addOption(new commander.Option('--scripts <string>')
+        .default(JSON.stringify(scripts))
+        .hideHelp());
+    // Diagnostics: opt-in tracing; optional variadic keys after the flag.
+    p = p.option('--trace [keys...]', 'emit diagnostics for child env composition (optional keys)');
+    // Validation: strict mode fails on env validation issues (warn by default).
+    p = p.option('--strict', 'fail on env validation errors (schema/requiredKeys)');
+    // Entropy diagnostics (presentation-only)
+    p = p
+        .addOption(new commander.Option('--entropy-warn', 'enable entropy warnings (default on)').conflicts('entropyWarnOff'))
+        .addOption(new commander.Option('--entropy-warn-off', 'disable entropy warnings').conflicts('entropyWarn'))
+        .option('--entropy-threshold <number>', 'entropy bits/char threshold (default 3.8)')
+        .option('--entropy-min-length <number>', 'min length to examine for entropy (default 16)')
+        .option('--entropy-whitelist <pattern...>', 'suppress entropy warnings when key matches any regex pattern')
+        .option('--redact-pattern <pattern...>', 'additional key-match regex patterns to trigger redaction');
+    // Restore original methods to avoid tagging future additions outside base.
+    program.addOption = originalAddOption;
+    program.option = originalOption;
+    return p;
+};
+
+/**
+ * Resolve a tri-state optional boolean flag under exactOptionalPropertyTypes.
+ * - If the user explicitly enabled the flag, return true.
+ * - If the user explicitly disabled (the "...-off" variant), return undefined (unset).
+ * - Otherwise, adopt the default (true → set; false/undefined → unset).
+ *
+ * @param exclude - The "on" flag value as parsed by Commander.
+ * @param excludeOff - The "off" toggle (present when specified) as parsed by Commander.
+ * @param defaultValue - The generator default to adopt when no explicit toggle is present.
+ * @returns boolean | undefined — use `undefined` to indicate "unset" (do not emit).
+ *
+ * @example
+ * ```ts
+ * resolveExclusion(undefined, undefined, true); // => true
+ * ```
+ */
+const resolveExclusion = (exclude, excludeOff, defaultValue) => exclude ? true : excludeOff ? undefined : defaultValue ? true : undefined;
+/**
+ * Resolve an optional flag with "--exclude-all" overrides.
+ * If excludeAll is set and the individual "...-off" is not, force true.
+ * If excludeAllOff is set and the individual flag is not explicitly set, unset.
+ * Otherwise, adopt the default (true → set; false/undefined → unset).
+ *
+ * @param exclude - Individual include/exclude flag.
+ * @param excludeOff - Individual "...-off" flag.
+ * @param defaultValue - Default for the individual flag.
+ * @param excludeAll - Global "exclude-all" flag.
+ * @param excludeAllOff - Global "exclude-all-off" flag.
+ *
+ * @example
+ * resolveExclusionAll(undefined, undefined, false, true, undefined) =\> true
+ */
+const resolveExclusionAll = (exclude, excludeOff, defaultValue, excludeAll, excludeAllOff) => 
+// Order of precedence:
+// 1) Individual explicit "on" wins outright.
+// 2) Individual explicit "off" wins over any global.
+// 3) Global exclude-all forces true when not explicitly turned off.
+// 4) Global exclude-all-off unsets when the individual wasn't explicitly enabled.
+// 5) Fall back to the default (true => set; false/undefined => unset).
+(() => {
+    // Individual "on"
+    if (exclude === true)
+        return true;
+    // Individual "off"
+    if (excludeOff === true)
+        return undefined;
+    // Global "exclude-all" ON (unless explicitly turned off)
+    if (excludeAll === true)
+        return true;
+    // Global "exclude-all-off" (unless explicitly enabled)
+    if (excludeAllOff === true)
+        return undefined;
+    // Default
+    return defaultValue ? true : undefined;
+})();
+/**
+ * exactOptionalPropertyTypes-safe setter for optional boolean flags:
+ * delete when undefined; assign when defined — without requiring an index signature on T.
+ *
+ * @typeParam T - Target object type.
+ * @param obj - The object to write to.
+ * @param key - The optional boolean property key of {@link T}.
+ * @param value - The value to set or `undefined` to unset.
+ *
+ * @remarks
+ * Writes through a local `Record<string, unknown>` view to avoid requiring an index signature on {@link T}.
+ */
+const setOptionalFlag = (obj, key, value) => {
+    const target = obj;
+    const k = key;
+    // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+    if (value === undefined)
+        delete target[k];
+    else
+        target[k] = value;
+};
+
+/**
+ * Merge and normalize raw Commander options (current + parent + defaults)
+ * into a GetDotenvCliOptions-like object. Types are intentionally wide to
+ * avoid cross-layer coupling; callers may cast as needed.
+ */
+const resolveCliOptions = (rawCliOptions, defaults, parentJson) => {
+    const parent = typeof parentJson === 'string' && parentJson.length > 0
+        ? JSON.parse(parentJson)
+        : undefined;
+    const { command, debugOff, excludeAll, excludeAllOff, excludeDynamicOff, excludeEnvOff, excludeGlobalOff, excludePrivateOff, excludePublicOff, loadProcessOff, logOff, entropyWarn, entropyWarnOff, scripts, shellOff, ...rest } = rawCliOptions;
+    const current = { ...rest };
+    if (typeof scripts === 'string') {
+        try {
+            current.scripts = JSON.parse(scripts);
+        }
+        catch {
+            // ignore parse errors; leave scripts undefined
+        }
+    }
+    const merged = defaultsDeep({}, defaults, parent ?? {}, current);
+    const d = defaults;
+    setOptionalFlag(merged, 'debug', resolveExclusion(merged.debug, debugOff, d.debug));
+    setOptionalFlag(merged, 'excludeDynamic', resolveExclusionAll(merged.excludeDynamic, excludeDynamicOff, d.excludeDynamic, excludeAll, excludeAllOff));
+    setOptionalFlag(merged, 'excludeEnv', resolveExclusionAll(merged.excludeEnv, excludeEnvOff, d.excludeEnv, excludeAll, excludeAllOff));
+    setOptionalFlag(merged, 'excludeGlobal', resolveExclusionAll(merged.excludeGlobal, excludeGlobalOff, d.excludeGlobal, excludeAll, excludeAllOff));
+    setOptionalFlag(merged, 'excludePrivate', resolveExclusionAll(merged.excludePrivate, excludePrivateOff, d.excludePrivate, excludeAll, excludeAllOff));
+    setOptionalFlag(merged, 'excludePublic', resolveExclusionAll(merged.excludePublic, excludePublicOff, d.excludePublic, excludeAll, excludeAllOff));
+    setOptionalFlag(merged, 'log', resolveExclusion(merged.log, logOff, d.log));
+    setOptionalFlag(merged, 'loadProcess', resolveExclusion(merged.loadProcess, loadProcessOff, d.loadProcess));
+    // warnEntropy (tri-state)
+    setOptionalFlag(merged, 'warnEntropy', resolveExclusion(merged.warnEntropy, entropyWarnOff, d.warnEntropy));
+    // Normalize shell for predictability: explicit default shell per OS.
+    const defaultShell = process.platform === 'win32' ? 'powershell.exe' : '/bin/bash';
+    let resolvedShell = merged.shell;
+    if (shellOff)
+        resolvedShell = false;
+    else if (resolvedShell === true || resolvedShell === undefined) {
+        resolvedShell = defaultShell;
+    }
+    else if (typeof resolvedShell !== 'string' &&
+        typeof defaults.shell === 'string') {
+        resolvedShell = defaults.shell;
+    }
+    merged.shell = resolvedShell;
+    const cmd = typeof command === 'string' ? command : undefined;
+    return cmd !== undefined ? { merged, command: cmd } : { merged };
+};
+
+GetDotenvCli.prototype.attachRootOptions = function (defaults, opts) {
+    const d = (defaults ?? baseRootOptionDefaults);
+    attachRootOptions(this, d, opts);
+    return this;
+};
+GetDotenvCli.prototype.passOptions = function (defaults) {
+    const d = (defaults ?? baseRootOptionDefaults);
+    this.hook('preSubcommand', async (thisCommand) => {
+        const raw = thisCommand.opts();
+        const { merged } = resolveCliOptions(raw, d, process.env.getDotenvCliOptions);
+        // Persist merged options for nested invocations (batch exec).
+        thisCommand.getDotenvCliOptions =
+            merged;
+        // Also store on the host for downstream ergonomic accessors.
+        this._setOptionsBag(merged);
+        // Build service options and compute context (always-on config loader path).
+        const serviceOptions = getDotenvCliOptions2Options(merged);
+        await this.resolveAndLoad(serviceOptions);
+        // Global validation: once after Phase C using config sources.
+        try {
+            const ctx = this.getCtx();
+            const dotenv = (ctx?.dotenv ?? {});
+            const sources = await resolveGetDotenvConfigSources((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cliHost.cjs', document.baseURI).href)));
+            const issues = validateEnvAgainstSources(dotenv, sources);
+            if (Array.isArray(issues) && issues.length > 0) {
+                const logger = (merged.logger ??
+                    console);
+                const emit = logger.error ?? logger.log;
+                issues.forEach((m) => {
+                    emit(m);
+                });
+                if (merged.strict) {
+                    // Deterministic failure under strict mode
+                    process.exit(1);
+                }
+            }
+        }
+        catch {
+            // Be tolerant: validation errors reported above; unexpected failures here
+            // should not crash non-strict flows.
+        }
+    });
+    // Also handle root-level flows (no subcommand) so option-aliases can run
+    // with the same merged options and context without duplicating logic.
+    this.hook('preAction', async (thisCommand) => {
+        const raw = thisCommand.opts();
+        const { merged } = resolveCliOptions(raw, d, process.env.getDotenvCliOptions);
+        thisCommand.getDotenvCliOptions =
+            merged;
+        this._setOptionsBag(merged);
+        // Avoid duplicate heavy work if a context is already present.
+        if (!this.getCtx()) {
+            const serviceOptions = getDotenvCliOptions2Options(merged);
+            await this.resolveAndLoad(serviceOptions);
+            try {
+                const ctx = this.getCtx();
+                const dotenv = (ctx?.dotenv ?? {});
+                const sources = await resolveGetDotenvConfigSources((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cliHost.cjs', document.baseURI).href)));
+                const issues = validateEnvAgainstSources(dotenv, sources);
+                if (Array.isArray(issues) && issues.length > 0) {
+                    const logger = (merged
+                        .logger ?? console);
+                    const emit = logger.error ?? logger.log;
+                    issues.forEach((m) => {
+                        emit(m);
+                    });
+                    if (merged.strict) {
+                        process.exit(1);
+                    }
+                }
+            }
+            catch {
+                // Tolerate validation side-effects in non-strict mode
+            }
+        }
+    });
+    return this;
+};
+
+/** 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.
+ *
+ * @example
+ * const parent = definePlugin(\{ id: 'p', setup(cli) \{ /* ... *\/ \} \})
+ *   .use(childA)
+ *   .use(childB);
+ */
+const definePlugin = (spec) => {
+    const { children = [], ...rest } = spec;
+    const plugin = {
+        ...rest,
+        children: [...children],
+        use(child) {
+            this.children.push(child);
+            return this;
+        },
+    };
+    return plugin;
+};
+
+// Ensure attachRootOptions() and passOptions() are available whenever the
+// /cliHost subpath is imported (unconditional for downstream hosts).
 /**
  * Helper to retrieve the merged root options bag from any action handler
  * that only has access to thisCommand. Avoids structural casts.

package/dist/cliHost.d.cts

@@ -1,6 +1,47 @@
 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).
  */
@@ -9,6 +50,27 @@ type ScriptsTable<TShell extends string | boolean = string | boolean> = Record<s
     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.
  * Values may be `undefined` to represent "unset". */ type ProcessEnv = Record<string, string | undefined>;
@@ -269,17 +331,41 @@ declare class GetDotenvCli<TOptions extends GetDotenvOptions = GetDotenvOptions>
     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>;
+/** 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.
+ */
+
+/**
+ * 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.
+ */
+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;
+    /**
+     * Setup phase: register commands and wiring on the provided CLI instance.
+     * Runs parent → children (pre-order).
+     */
+    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.
@@ -287,7 +373,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.
      */
@@ -317,4 +404,4 @@ declare const definePlugin: (spec: DefineSpec) => GetDotenvCliPlugin;
 declare const readMergedOptions: (cmd: Command) => GetDotenvCliOptions | undefined;
 
 export { GetDotenvCli, definePlugin, readMergedOptions };
-export type { DefineSpec, GetDotenvCliCtx, GetDotenvCliOptions, GetDotenvCliPlugin, ScriptsTable };
+export type { DefineSpec, GetDotenvCliCtx, GetDotenvCliOptions, GetDotenvCliPlugin, GetDotenvCliPublic, ScriptsTable };