@karmaniverous/get-dotenv 5.2.3 → 5.2.5

package/dist/cliHost.mjs

@@ -1,4 +1,4 @@
-import { Command } from 'commander';
+import { Command, Option } from 'commander';
 import fs from 'fs-extra';
 import { packageDirectory } from 'package-directory';
 import url, { fileURLToPath, pathToFileURL } from 'url';
@@ -9,27 +9,6 @@ import { nanoid } from 'nanoid';
 import { parse } from 'dotenv';
 import { createHash } from 'crypto';
 
-/**
- * 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',
@@ -586,6 +565,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)
@@ -1436,6 +1431,412 @@ class GetDotenvCli extends 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 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 Option('-S, --shell-off', `command execution shell OFF${!shell ? ' (default)' : ''}`).conflicts('shell'))
+        .addOption(new Option('-p, --load-process', `load variables to process.env ON${loadProcess ? ' (default)' : ''}`).conflicts('loadProcessOff'))
+        .addOption(new Option('-P, --load-process-off', `load variables to process.env OFF${!loadProcess ? ' (default)' : ''}`).conflicts('loadProcess'))
+        .addOption(new Option('-a, --exclude-all', `exclude all dotenv variables from loading ON${excludeDynamic &&
+        ((excludeEnv && excludeGlobal) || (excludePrivate && excludePublic))
+        ? ' (default)'
+        : ''}`).conflicts('excludeAllOff'))
+        .addOption(new Option('-A, --exclude-all-off', `exclude all dotenv variables from loading OFF (default)`).conflicts('excludeAll'))
+        .addOption(new Option('-z, --exclude-dynamic', `exclude dynamic dotenv variables from loading ON${excludeDynamic ? ' (default)' : ''}`).conflicts('excludeDynamicOff'))
+        .addOption(new Option('-Z, --exclude-dynamic-off', `exclude dynamic dotenv variables from loading OFF${!excludeDynamic ? ' (default)' : ''}`).conflicts('excludeDynamic'))
+        .addOption(new Option('-n, --exclude-env', `exclude environment-specific dotenv variables from loading${excludeEnv ? ' (default)' : ''}`).conflicts('excludeEnvOff'))
+        .addOption(new Option('-N, --exclude-env-off', `exclude environment-specific dotenv variables from loading OFF${!excludeEnv ? ' (default)' : ''}`).conflicts('excludeEnv'))
+        .addOption(new Option('-g, --exclude-global', `exclude global dotenv variables from loading ON${excludeGlobal ? ' (default)' : ''}`).conflicts('excludeGlobalOff'))
+        .addOption(new Option('-G, --exclude-global-off', `exclude global dotenv variables from loading OFF${!excludeGlobal ? ' (default)' : ''}`).conflicts('excludeGlobal'))
+        .addOption(new Option('-r, --exclude-private', `exclude private dotenv variables from loading ON${excludePrivate ? ' (default)' : ''}`).conflicts('excludePrivateOff'))
+        .addOption(new Option('-R, --exclude-private-off', `exclude private dotenv variables from loading OFF${!excludePrivate ? ' (default)' : ''}`).conflicts('excludePrivate'))
+        .addOption(new Option('-u, --exclude-public', `exclude public dotenv variables from loading ON${excludePublic ? ' (default)' : ''}`).conflicts('excludePublicOff'))
+        .addOption(new Option('-U, --exclude-public-off', `exclude public dotenv variables from loading OFF${!excludePublic ? ' (default)' : ''}`).conflicts('excludePublic'))
+        .addOption(new Option('-l, --log', `console log loaded variables ON${log ? ' (default)' : ''}`).conflicts('logOff'))
+        .addOption(new 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 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 Option('--entropy-warn', 'enable entropy warnings (default on)').conflicts('entropyWarnOff'))
+        .addOption(new 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(import.meta.url);
+            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(import.meta.url);
+                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/getdotenv.cli.mjs

@@ -2066,6 +2066,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.
  *
@@ -3202,11 +3209,8 @@ const cmdPlugin = (options = {}) => definePlugin({
             const { logger: _omit, ...envBag } = merged;
             const capture = process.env.GETDOTENV_STDIO === 'pipe' ||
                 Boolean(merged.capture);
-            // Prefer explicit env injection: pass the resolved dotenv map to the child.
-            // This avoids leaking prior secrets from the parent process.env when
-            // exclusions (e.g., --exclude-private) are in effect.
-            const host = cli;
-            const ctx = host.getCtx();
+            // Prefer explicit env injection using the resolved dotenv map.
+            const ctx = cli.getCtx();
             const dotenv = (ctx?.dotenv ?? {});
             // Diagnostics: --trace [keys...] (space-delimited keys if provided; all keys when true)
             const traceOpt = merged.trace;
@@ -3748,7 +3752,7 @@ new Command()
 
 new Command()
     .name('cmd')
-    .description('Batch execute command according to the --shell option, conflicts with --command option (default subcommand)')
+    .description('Execute command according to the --shell option, conflicts with --command option (default subcommand)')
     .configureHelp({ showGlobalOptions: true })
     .enablePositionalOptions()
     .passThroughOptions()

package/dist/index.cjs

@@ -2075,6 +2075,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.
  *
@@ -3211,11 +3218,8 @@ const cmdPlugin = (options = {}) => definePlugin({
             const { logger: _omit, ...envBag } = merged;
             const capture = process.env.GETDOTENV_STDIO === 'pipe' ||
                 Boolean(merged.capture);
-            // Prefer explicit env injection: pass the resolved dotenv map to the child.
-            // This avoids leaking prior secrets from the parent process.env when
-            // exclusions (e.g., --exclude-private) are in effect.
-            const host = cli;
-            const ctx = host.getCtx();
+            // Prefer explicit env injection using the resolved dotenv map.
+            const ctx = cli.getCtx();
             const dotenv = (ctx?.dotenv ?? {});
             // Diagnostics: --trace [keys...] (space-delimited keys if provided; all keys when true)
             const traceOpt = merged.trace;
@@ -3757,7 +3761,7 @@ const batchCommand = new commander.Command()
 
 const cmdCommand = new commander.Command()
     .name('cmd')
-    .description('Batch execute command according to the --shell option, conflicts with --command option (default subcommand)')
+    .description('Execute command according to the --shell option, conflicts with --command option (default subcommand)')
     .configureHelp({ showGlobalOptions: true })
     .enablePositionalOptions()
     .passThroughOptions()
@@ -4108,6 +4112,7 @@ function createCli(opts = {}) {
     };
 }
 
+exports.buildSpawnEnv = buildSpawnEnv;
 exports.createCli = createCli;
 exports.defineDynamic = defineDynamic;
 exports.dotenvExpand = dotenvExpand;

package/dist/index.d.cts

@@ -70,6 +70,24 @@ declare module '../cliHost/GetDotenvCli' {
     }
 }
 
+/** 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;
+
 type RootOptionsShapeCompat = Omit<RootOptionsShape, 'vars' | 'paths'> & {
     vars?: string | Record<string, string | undefined>;
     paths?: string | string[];
@@ -456,5 +474,5 @@ declare function createCli(opts?: CreateCliOptions): {
     run: (argv: string[]) => Promise<void>;
 };
 
-export { createCli, defineDynamic, dotenvExpand, dotenvExpandAll, dotenvExpandFromProcessEnv, generateGetDotenvCli, getDotenv, getDotenvCliOptions2Options, interpolateDeep };
+export { buildSpawnEnv, createCli, defineDynamic, dotenvExpand, dotenvExpandAll, dotenvExpandFromProcessEnv, generateGetDotenvCli, getDotenv, getDotenvCliOptions2Options, interpolateDeep };
 export type { CreateCliOptions, GetDotenvDynamic, GetDotenvOptions, ProcessEnv };

package/dist/index.d.mts

@@ -70,6 +70,24 @@ declare module '../cliHost/GetDotenvCli' {
     }
 }
 
+/** 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;
+
 type RootOptionsShapeCompat = Omit<RootOptionsShape, 'vars' | 'paths'> & {
     vars?: string | Record<string, string | undefined>;
     paths?: string | string[];
@@ -456,5 +474,5 @@ declare function createCli(opts?: CreateCliOptions): {
     run: (argv: string[]) => Promise<void>;
 };
 
-export { createCli, defineDynamic, dotenvExpand, dotenvExpandAll, dotenvExpandFromProcessEnv, generateGetDotenvCli, getDotenv, getDotenvCliOptions2Options, interpolateDeep };
+export { buildSpawnEnv, createCli, defineDynamic, dotenvExpand, dotenvExpandAll, dotenvExpandFromProcessEnv, generateGetDotenvCli, getDotenv, getDotenvCliOptions2Options, interpolateDeep };
 export type { CreateCliOptions, GetDotenvDynamic, GetDotenvOptions, ProcessEnv };

package/dist/index.d.ts

@@ -70,6 +70,24 @@ declare module '../cliHost/GetDotenvCli' {
     }
 }
 
+/** 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;
+
 type RootOptionsShapeCompat = Omit<RootOptionsShape, 'vars' | 'paths'> & {
     vars?: string | Record<string, string | undefined>;
     paths?: string | string[];
@@ -456,5 +474,5 @@ declare function createCli(opts?: CreateCliOptions): {
     run: (argv: string[]) => Promise<void>;
 };
 
-export { createCli, defineDynamic, dotenvExpand, dotenvExpandAll, dotenvExpandFromProcessEnv, generateGetDotenvCli, getDotenv, getDotenvCliOptions2Options, interpolateDeep };
+export { buildSpawnEnv, createCli, defineDynamic, dotenvExpand, dotenvExpandAll, dotenvExpandFromProcessEnv, generateGetDotenvCli, getDotenv, getDotenvCliOptions2Options, interpolateDeep };
 export type { CreateCliOptions, GetDotenvDynamic, GetDotenvOptions, ProcessEnv };