@karmaniverous/get-dotenv 5.2.6 → 6.0.0-1

package/dist/index.mjs

@@ -1,10 +1,11 @@
-import { Option, Command } from 'commander';
+import { z } from 'zod';
+export { z } from 'zod';
 import fs from 'fs-extra';
 import { packageDirectory } from 'package-directory';
 import path, { join, extname } from 'path';
 import url, { fileURLToPath, pathToFileURL } from 'url';
 import YAML from 'yaml';
-import { z } from 'zod';
+import { Option, Command } from 'commander';
 import { nanoid } from 'nanoid';
 import { parse } from 'dotenv';
 import { createHash } from 'crypto';
@@ -14,256 +15,10 @@ import { stdin, stdout } from 'node:process';
 import { createInterface } from 'readline/promises';
 
 /**
- * Dotenv expansion utilities.
- *
- * This module implements recursive expansion of environment-variable
- * references in strings and records. It supports both whitespace and
- * bracket syntaxes with optional defaults:
- *
- * - Whitespace: `$VAR[:default]`
- * - Bracketed: `${VAR[:default]}`
- *
- * Escaped dollar signs (`\$`) are preserved.
- * Unknown variables resolve to empty string unless a default is provided.
- */
-/**
- * Like String.prototype.search but returns the last index.
- * @internal
- */
-const searchLast = (str, rgx) => {
-    const matches = Array.from(str.matchAll(rgx));
-    return matches.length > 0 ? (matches.slice(-1)[0]?.index ?? -1) : -1;
-};
-const replaceMatch = (value, match, ref) => {
-    /**
-     * @internal
-     */
-    const group = match[0];
-    const key = match[1];
-    const defaultValue = match[2];
-    if (!key)
-        return value;
-    const replacement = value.replace(group, ref[key] ?? defaultValue ?? '');
-    return interpolate(replacement, ref);
-};
-const interpolate = (value = '', ref = {}) => {
-    /**
-     * @internal
-     */
-    // if value is falsy, return it as is
-    if (!value)
-        return value;
-    // get position of last unescaped dollar sign
-    const lastUnescapedDollarSignIndex = searchLast(value, /(?!(?<=\\))\$/g);
-    // return value if none found
-    if (lastUnescapedDollarSignIndex === -1)
-        return value;
-    // evaluate the value tail
-    const tail = value.slice(lastUnescapedDollarSignIndex);
-    // find whitespace pattern: $KEY:DEFAULT
-    const whitespacePattern = /^\$([\w]+)(?::([^\s]*))?/;
-    const whitespaceMatch = whitespacePattern.exec(tail);
-    if (whitespaceMatch != null)
-        return replaceMatch(value, whitespaceMatch, ref);
-    else {
-        // find bracket pattern: ${KEY:DEFAULT}
-        const bracketPattern = /^\${([\w]+)(?::([^}]*))?}/;
-        const bracketMatch = bracketPattern.exec(tail);
-        if (bracketMatch != null)
-            return replaceMatch(value, bracketMatch, ref);
-    }
-    return value;
-};
-/**
- * Recursively expands environment variables in a string. 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.
- * @param ref - The reference object to use for variable expansion.
- * @returns The expanded string.
- *
- * @example
- * ```ts
- * process.env.FOO = 'bar';
- * dotenvExpand('Hello $FOO'); // "Hello bar"
- * dotenvExpand('Hello $BAZ:world'); // "Hello world"
- * ```
- *
- * @remarks
- * The expansion is recursive. If a referenced variable itself contains
- * references, those will also be expanded until a stable value is reached.
- * Escaped references (e.g. `\$FOO`) are preserved as literals.
- */
-const dotenvExpand = (value, ref = process.env) => {
-    const result = interpolate(value, ref);
-    return result ? result.replace(/\\\$/g, '$') : undefined;
-};
-/**
- * Recursively expands environment variables in the values of a JSON object.
- * Variables may be presented with optional default as `$VAR[:default]` or
- * `${VAR[:default]}`. Unknown variables will expand to an empty string.
- *
- * @param values - The values object to expand.
- * @param options - Expansion options.
- * @returns The value object with expanded string values.
- *
- * @example
- * ```ts
- * process.env.FOO = 'bar';
- * dotenvExpandAll({ A: '$FOO', B: 'x${FOO}y' });
- * // => { A: "bar", B: "xbary" }
- * ```
- *
- * @remarks
- * Options:
- * - ref: The reference object to use for expansion (defaults to process.env).
- * - progressive: Whether to progressively add expanded values to the set of
- *   reference keys.
- *
- * When `progressive` is true, each expanded key becomes available for
- * subsequent expansions in the same object (left-to-right by object key order).
- */
-const dotenvExpandAll = (values = {}, options = {}) => Object.keys(values).reduce((acc, key) => {
-    const { ref = process.env, progressive = false } = options;
-    acc[key] = dotenvExpand(values[key], {
-        ...ref,
-        ...(progressive ? acc : {}),
-    });
-    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);
-
-/**
- * Attach legacy root flags to a Commander program.
- * Uses provided defaults to render help labels without coupling to generators.
+ * Identity helper to define a scripts table while preserving a concrete TShell
+ * type parameter in downstream inference.
  */
-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;
-};
+const defineScripts = () => (t) => t;
 
 // Base root CLI defaults (shared; kept untyped here to avoid cross-layer deps).
 const baseRootOptionDefaults = {
@@ -313,26 +68,12 @@ const mergeInto = (target, source) => {
     }
     return target;
 };
-/**
- * Perform a deep defaults-style merge across plain objects. *
- * - Only merges plain objects (prototype === Object.prototype).
- * - Arrays and non-objects are replaced, not merged.
- * - `undefined` values are ignored and do not overwrite prior values.
- *
- * @typeParam T - The resulting shape after merging all layers.
- * @param layers - Zero or more partial layers in ascending precedence order.
- * @returns The merged object typed as {@link T}.
- *
- * @example
- * defaultsDeep(\{ a: 1, nested: \{ b: 2 \} \}, \{ nested: \{ b: 3, c: 4 \} \})
- * =\> \{ a: 1, nested: \{ b: 3, c: 4 \} \}
- */
-const defaultsDeep = (...layers) => {
+function defaultsDeep(...layers) {
     const result = layers
         .filter(Boolean)
         .reduce((acc, layer) => mergeInto(acc, layer), {});
     return result;
-};
+}
 
 /**
  * Resolve a tri-state optional boolean flag under exactOptionalPropertyTypes.
@@ -754,113 +495,458 @@ const validateEnvAgainstSources = (finalEnv, sources) => {
 
 const baseGetDotenvCliOptions = baseRootOptionDefaults;
 
+/** src/util/omitUndefined.ts
+ * Helpers to drop undefined-valued properties in a typed-friendly way.
+ */
+/**
+ * Omit keys whose runtime value is undefined from a shallow object.
+ * Returns a Partial with non-undefined value types preserved.
+ */
+function omitUndefined(obj) {
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+        if (v !== undefined)
+            out[k] = v;
+    }
+    return out;
+}
+/**
+ * Specialized helper for env-like maps: drop undefined and return string-only.
+ */
+function omitUndefinedRecord(obj) {
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+        if (v !== undefined)
+            out[k] = v;
+    }
+    return out;
+}
+
 // src/GetDotenvOptions.ts
-const getDotenvOptionsFilename = 'getdotenv.config.json';
 /**
- * Helper to define a dynamic map with strong inference.
+ * Canonical programmatic options and helpers for get-dotenv.
  *
- * @example
- * const dynamic = defineDynamic(\{ KEY: (\{ FOO = '' \}) =\> FOO + '-x' \});
+ * Requirements addressed:
+ * - GetDotenvOptions derives from the Zod schema output (single source of truth).
+ * - Removed deprecated/compat flags from the public shape (e.g., useConfigLoader).
+ * - Provide Vars-aware defineDynamic and a typed config builder defineGetDotenvConfig\<Vars, Env\>().
+ * - Preserve existing behavior for defaults resolution and compat converters.
  */
-const defineDynamic = (d) => d;
+const getDotenvOptionsFilename = 'getdotenv.config.json';
+// Implementation
+function defineDynamic(d) {
+    return d;
+}
+function defineGetDotenvConfig(cfg) {
+    return cfg;
+}
 /**
- * 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.
  */
-const getDotenvCliOptions2Options = ({ paths, pathsDelimiter, pathsDelimiterPattern, vars, varsAssignor, varsAssignorPattern, varsDelimiter, varsDelimiterPattern, ...rest }) => {
-    /**
-     * Convert CLI-facing string options into {@link GetDotenvOptions}.
-     *
-     * - Splits {@link GetDotenvCliOptions.paths} using either a delimiter   *   or a regular expression pattern into a string array.   * - Parses {@link GetDotenvCliOptions.vars} as space-separated `KEY=VALUE`
-     *   pairs (configurable delimiters) into a {@link ProcessEnv}.
-     * - Drops CLI-only keys that have no programmatic equivalent.
-     *
-     * @remarks
-     * Follows exact-optional semantics by not emitting undefined-valued entries.
-     */
-    // Drop CLI-only keys (debug/scripts) without relying on Record casts.
-    // Create a shallow copy then delete optional CLI-only keys if present.
-    const restObj = { ...rest };
-    delete restObj.debug;
-    delete restObj.scripts;
-    const splitBy = (value, delim, pattern) => (value ? value.split(pattern ? RegExp(pattern) : (delim ?? ' ')) : []);
+const getDotenvCliOptions2Options = ({ paths, pathsDelimiter, pathsDelimiterPattern, vars, varsAssignor, varsAssignorPattern, varsDelimiter, varsDelimiterPattern, 
+// drop CLI-only keys from the pass-through bag
+debug: _debug, scripts: _scripts, ...rest }) => {
+    // Split helper for delimited strings or regex patterns
+    const splitBy = (value, delim, pattern) => {
+        if (!value)
+            return [];
+        if (pattern)
+            return value.split(RegExp(pattern));
+        if (typeof delim === 'string')
+            return value.split(delim);
+        return value.split(' ');
+    };
     // Tolerate vars as either a CLI string ("A=1 B=2") or an object map.
     let parsedVars;
     if (typeof vars === 'string') {
-        const kvPairs = splitBy(vars, varsDelimiter, varsDelimiterPattern).map((v) => v.split(varsAssignorPattern
+        const kvPairs = splitBy(vars, varsDelimiter, varsDelimiterPattern)
+            .map((v) => v.split(varsAssignorPattern
             ? RegExp(varsAssignorPattern)
-            : (varsAssignor ?? '=')));
+            : (varsAssignor ?? '=')))
+            .filter(([k]) => typeof k === 'string' && k.length > 0);
         parsedVars = Object.fromEntries(kvPairs);
     }
     else if (vars && typeof vars === 'object' && !Array.isArray(vars)) {
-        // Keep only string or undefined values to match ProcessEnv.
-        const entries = Object.entries(vars).filter(([k, v]) => typeof k === 'string' && (typeof v === 'string' || v === undefined));
-        parsedVars = Object.fromEntries(entries);
+        // Accept provided object map of string | undefined; drop undefined values
+        // in the normalization step below to produce a ProcessEnv-compatible bag.
+        parsedVars = Object.fromEntries(Object.entries(vars));
     }
     // Drop undefined-valued entries at the converter stage to match ProcessEnv
     // expectations and the compat test assertions.
     if (parsedVars) {
-        parsedVars = Object.fromEntries(Object.entries(parsedVars).filter(([, v]) => v !== undefined));
+        parsedVars = omitUndefinedRecord(parsedVars);
     }
     // Tolerate paths as either a delimited string or string[]
-    // Use a locally cast union type to avoid lint warnings about always-falsy conditions
-    // under the RootOptionsShape (which declares paths as string | undefined).
-    const pathsAny = paths;
-    const pathsOut = Array.isArray(pathsAny)
-        ? pathsAny.filter((p) => typeof p === 'string')
-        : splitBy(pathsAny, pathsDelimiter, pathsDelimiterPattern);
+    const pathsOut = Array.isArray(paths)
+        ? paths.filter((p) => typeof p === 'string')
+        : splitBy(paths, pathsDelimiter, pathsDelimiterPattern);
     // Preserve exactOptionalPropertyTypes: only include keys when defined.
     return {
-        ...restObj,
+        ...rest,
         ...(pathsOut.length > 0 ? { paths: pathsOut } : {}),
         ...(parsedVars !== undefined ? { vars: parsedVars } : {}),
     };
 };
+/**
+ * Resolve {@link GetDotenvOptions} by layering defaults in ascending precedence:
+ *
+ * 1. Base defaults derived from the CLI generator defaults
+ *    ({@link baseGetDotenvCliOptions}).
+ * 2. Local project overrides from a `getdotenv.config.json` in the nearest
+ *    package root (if present).
+ * 3. The provided customOptions.
+ *
+ * The result preserves explicit empty values and drops only `undefined`.
+ */
 const resolveGetDotenvOptions = async (customOptions) => {
-    /**
-     * Resolve {@link GetDotenvOptions} by layering defaults in ascending precedence:
-     *
-     * 1. Base defaults derived from the CLI generator defaults
-     *    ({@link baseGetDotenvCliOptions}).
-     * 2. Local project overrides from a `getdotenv.config.json` in the nearest
-     *    package root (if present).
-     * 3. The provided {@link customOptions}.
-     *
-     * The result preserves explicit empty values and drops only `undefined`.
-     *
-     * @returns Fully-resolved {@link GetDotenvOptions}.
-     *
-     * @example
-     * ```ts
-     * const options = await resolveGetDotenvOptions({ env: 'dev' });
-     * ```
-     */
     const localPkgDir = await packageDirectory();
     const localOptionsPath = localPkgDir
         ? join(localPkgDir, getDotenvOptionsFilename)
         : undefined;
-    const localOptions = (localOptionsPath && (await fs.exists(localOptionsPath))
-        ? JSON.parse((await fs.readFile(localOptionsPath)).toString())
-        : {});
+    // Safely read local CLI-facing defaults (defensive typing to satisfy strict linting).
+    let localOptions = {};
+    if (localOptionsPath && (await fs.exists(localOptionsPath))) {
+        try {
+            const txt = await fs.readFile(localOptionsPath, 'utf-8');
+            const parsed = JSON.parse(txt);
+            if (parsed && typeof parsed === 'object') {
+                localOptions = parsed;
+            }
+        }
+        catch {
+            // Malformed or unreadable local options are treated as absent.
+            localOptions = {};
+        }
+    }
     // Merge order: base < local < custom (custom has highest precedence)
     const mergedCli = defaultsDeep(baseGetDotenvCliOptions, localOptions);
     const defaultsFromCli = getDotenvCliOptions2Options(mergedCli);
     const result = defaultsDeep(defaultsFromCli, customOptions);
     return {
         ...result, // Keep explicit empty strings/zeros; drop only undefined
-        vars: Object.fromEntries(Object.entries(result.vars ?? {}).filter(([, v]) => v !== undefined)),
+        vars: omitUndefinedRecord(result.vars ?? {}),
+    };
+};
+
+/**
+ * Dotenv expansion utilities.
+ *
+ * This module implements recursive expansion of environment-variable
+ * references in strings and records. It supports both whitespace and
+ * bracket syntaxes with optional defaults:
+ *
+ * - Whitespace: `$VAR[:default]`
+ * - Bracketed: `${VAR[:default]}`
+ *
+ * Escaped dollar signs (`\$`) are preserved.
+ * Unknown variables resolve to empty string unless a default is provided.
+ */
+/**
+ * Like String.prototype.search but returns the last index.
+ * @internal
+ */
+const searchLast = (str, rgx) => {
+    const matches = Array.from(str.matchAll(rgx));
+    return matches.length > 0 ? (matches.slice(-1)[0]?.index ?? -1) : -1;
+};
+const replaceMatch = (value, match, ref) => {
+    /**
+     * @internal
+     */
+    const group = match[0];
+    const key = match[1];
+    const defaultValue = match[2];
+    if (!key)
+        return value;
+    const replacement = value.replace(group, ref[key] ?? defaultValue ?? '');
+    return interpolate(replacement, ref);
+};
+const interpolate = (value = '', ref = {}) => {
+    /**
+     * @internal
+     */
+    // if value is falsy, return it as is
+    if (!value)
+        return value;
+    // get position of last unescaped dollar sign
+    const lastUnescapedDollarSignIndex = searchLast(value, /(?!(?<=\\))\$/g);
+    // return value if none found
+    if (lastUnescapedDollarSignIndex === -1)
+        return value;
+    // evaluate the value tail
+    const tail = value.slice(lastUnescapedDollarSignIndex);
+    // find whitespace pattern: $KEY:DEFAULT
+    const whitespacePattern = /^\$([\w]+)(?::([^\s]*))?/;
+    const whitespaceMatch = whitespacePattern.exec(tail);
+    if (whitespaceMatch != null)
+        return replaceMatch(value, whitespaceMatch, ref);
+    else {
+        // find bracket pattern: ${KEY:DEFAULT}
+        const bracketPattern = /^\${([\w]+)(?::([^}]*))?}/;
+        const bracketMatch = bracketPattern.exec(tail);
+        if (bracketMatch != null)
+            return replaceMatch(value, bracketMatch, ref);
+    }
+    return value;
+};
+/**
+ * Recursively expands environment variables in a string. 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.
+ * @param ref - The reference object to use for variable expansion.
+ * @returns The expanded string.
+ *
+ * @example
+ * ```ts
+ * process.env.FOO = 'bar';
+ * dotenvExpand('Hello $FOO'); // "Hello bar"
+ * dotenvExpand('Hello $BAZ:world'); // "Hello world"
+ * ```
+ *
+ * @remarks
+ * The expansion is recursive. If a referenced variable itself contains
+ * references, those will also be expanded until a stable value is reached.
+ * Escaped references (e.g. `\$FOO`) are preserved as literals.
+ */
+const dotenvExpand = (value, ref = process.env) => {
+    const result = interpolate(value, ref);
+    return result ? result.replace(/\\\$/g, '$') : undefined;
+};
+/**
+ * Recursively expands environment variables in the values of a JSON object.
+ * Variables may be presented with optional default as `$VAR[:default]` or
+ * `${VAR[:default]}`. Unknown variables will expand to an empty string.
+ *
+ * @param values - The values object to expand.
+ * @param options - Expansion options.
+ * @returns The value object with expanded string values.
+ *
+ * @example
+ * ```ts
+ * process.env.FOO = 'bar';
+ * dotenvExpandAll({ A: '$FOO', B: 'x${FOO}y' });
+ * // => { A: "bar", B: "xbary" }
+ * ```
+ *
+ * @remarks
+ * Options:
+ * - ref: The reference object to use for expansion (defaults to process.env).
+ * - progressive: Whether to progressively add expanded values to the set of
+ *   reference keys.
+ *
+ * When `progressive` is true, each expanded key becomes available for
+ * subsequent expansions in the same object (left-to-right by object key order).
+ */
+function dotenvExpandAll(values, options = {}) {
+    const { ref = process.env, progressive = false, } = options;
+    const out = Object.keys(values).reduce((acc, key) => {
+        acc[key] = dotenvExpand(values[key], {
+            ...ref,
+            ...(progressive ? acc : {}),
+        });
+        return acc;
+    }, {});
+    // Key-preserving return with a permissive index signature to allow later additions.
+    return out;
+}
+/**
+ * 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);
+
+/* eslint-disable @typescript-eslint/no-deprecated */
+/**
+ * Attach root flags to a GetDotenvCli instance.
+ * - Host-only: program is typed as GetDotenvCli and supports dynamicOption/createDynamicOption.
+ * - Any flag that displays an effective default in help uses dynamic descriptions.
+ */
+const attachRootOptions = (program, defaults) => {
+    // Install temporary wrappers to tag all options added here as "base" for grouped help.
+    const GROUP = 'base';
+    const tagLatest = (cmd, group) => {
+        const optsArr = cmd.options ?? [];
+        if (Array.isArray(optsArr) && optsArr.length > 0) {
+            const last = optsArr[optsArr.length - 1];
+            program.setOptionGroup(last, group);
+        }
+    };
+    const originalAddOption = program.addOption.bind(program);
+    const originalOption = program.option.bind(program);
+    program.addOption = function patchedAdd(opt) {
+        program.setOptionGroup(opt, GROUP);
+        return originalAddOption(opt);
     };
+    program.option = function patchedOption(...args) {
+        const ret = originalOption(...args);
+        tagLatest(this, GROUP);
+        return ret;
+    };
+    const { defaultEnv, dotenvToken, dynamicPath, env, outputPath, paths, pathsDelimiter, pathsDelimiterPattern, privateToken, scripts, varsAssignor, varsAssignorPattern, varsDelimiter, varsDelimiterPattern, } = defaults ?? {};
+    const va = typeof defaults?.varsAssignor === 'string' ? defaults.varsAssignor : '=';
+    const vd = typeof defaults?.varsDelimiter === 'string' ? defaults.varsDelimiter : ' ';
+    // Helper: append (default) tags for ON/OFF toggles
+    const onOff = (on, isDefault) => on
+        ? `ON${isDefault ? ' (default)' : ''}`
+        : `OFF${isDefault ? ' (default)' : ''}`;
+    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);
+    // Output path (interpolated later; help can remain static)
+    p = p.option('-o, --output-path <string>', 'consolidated output file  (dotenv-expanded)', dotenvExpandFromProcessEnv, outputPath);
+    // Shell ON (string or boolean true => default shell)
+    p = p
+        .addOption(program
+        .createDynamicOption('-s, --shell [string]', (cfg) => {
+        const s = cfg.shell;
+        let tag = '';
+        if (typeof s === 'boolean' && s)
+            tag = ' (default OS shell)';
+        else if (typeof s === 'string' && s.length > 0)
+            tag = ` (default ${s})`;
+        return `command execution shell, no argument for default OS shell or provide shell string${tag}`;
+    })
+        .conflicts('shellOff'))
+        // Shell OFF
+        .addOption(program
+        .createDynamicOption('-S, --shell-off', (cfg) => {
+        const s = cfg.shell;
+        return `command execution shell OFF${s === false ? ' (default)' : ''}`;
+    })
+        .conflicts('shell'));
+    // Load process ON/OFF (dynamic defaults)
+    p = p
+        .addOption(program
+        .createDynamicOption('-p, --load-process', (cfg) => `load variables to process.env ${onOff(true, Boolean(cfg.loadProcess))}`)
+        .conflicts('loadProcessOff'))
+        .addOption(program
+        .createDynamicOption('-P, --load-process-off', (cfg) => `load variables to process.env ${onOff(false, !cfg.loadProcess)}`)
+        .conflicts('loadProcess'));
+    // Exclusion master toggle (dynamic)
+    p = p
+        .addOption(program
+        .createDynamicOption('-a, --exclude-all', (cfg) => {
+        const allOn = !!cfg.excludeDynamic &&
+            ((!!cfg.excludeEnv && !!cfg.excludeGlobal) ||
+                (!!cfg.excludePrivate && !!cfg.excludePublic));
+        const suffix = allOn ? ' (default)' : '';
+        return `exclude all dotenv variables from loading ON${suffix}`;
+    })
+        .conflicts('excludeAllOff'))
+        .addOption(new Option('-A, --exclude-all-off', `exclude all dotenv variables from loading OFF (default)`).conflicts('excludeAll'));
+    // Per-family exclusions (dynamic defaults)
+    p = p
+        .addOption(program
+        .createDynamicOption('-z, --exclude-dynamic', (cfg) => `exclude dynamic dotenv variables from loading ${onOff(true, Boolean(cfg.excludeDynamic))}`)
+        .conflicts('excludeDynamicOff'))
+        .addOption(program
+        .createDynamicOption('-Z, --exclude-dynamic-off', (cfg) => `exclude dynamic dotenv variables from loading ${onOff(false, !cfg.excludeDynamic)}`)
+        .conflicts('excludeDynamic'))
+        .addOption(program
+        .createDynamicOption('-n, --exclude-env', (cfg) => `exclude environment-specific dotenv variables from loading ${onOff(true, Boolean(cfg.excludeEnv))}`)
+        .conflicts('excludeEnvOff'))
+        .addOption(program
+        .createDynamicOption('-N, --exclude-env-off', (cfg) => `exclude environment-specific dotenv variables from loading ${onOff(false, !cfg.excludeEnv)}`)
+        .conflicts('excludeEnv'))
+        .addOption(program
+        .createDynamicOption('-g, --exclude-global', (cfg) => `exclude global dotenv variables from loading ${onOff(true, Boolean(cfg.excludeGlobal))}`)
+        .conflicts('excludeGlobalOff'))
+        .addOption(program
+        .createDynamicOption('-G, --exclude-global-off', (cfg) => `exclude global dotenv variables from loading ${onOff(false, !cfg.excludeGlobal)}`)
+        .conflicts('excludeGlobal'))
+        .addOption(program
+        .createDynamicOption('-r, --exclude-private', (cfg) => `exclude private dotenv variables from loading ${onOff(true, Boolean(cfg.excludePrivate))}`)
+        .conflicts('excludePrivateOff'))
+        .addOption(program
+        .createDynamicOption('-R, --exclude-private-off', (cfg) => `exclude private dotenv variables from loading ${onOff(false, !cfg.excludePrivate)}`)
+        .conflicts('excludePrivate'))
+        .addOption(program
+        .createDynamicOption('-u, --exclude-public', (cfg) => `exclude public dotenv variables from loading ${onOff(true, Boolean(cfg.excludePublic))}`)
+        .conflicts('excludePublicOff'))
+        .addOption(program
+        .createDynamicOption('-U, --exclude-public-off', (cfg) => `exclude public dotenv variables from loading ${onOff(false, !cfg.excludePublic)}`)
+        .conflicts('excludePublic'));
+    // Log ON/OFF (dynamic)
+    p = p
+        .addOption(program
+        .createDynamicOption('-l, --log', (cfg) => `console log loaded variables ${onOff(true, Boolean(cfg.log))}`)
+        .conflicts('logOff'))
+        .addOption(program
+        .createDynamicOption('-L, --log-off', (cfg) => `console log loaded variables ${onOff(false, !cfg.log)}`)
+        .conflicts('log'));
+    // Capture flag (no default display; static)
+    p = p.option('--capture', 'capture child process stdio for commands (tests/CI)');
+    // Core bootstrap/static flags (kept static in help)
+    p = p
+        .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 / validation / entropy
+    p = p
+        .option('--trace [keys...]', 'emit diagnostics for child env composition (optional keys)')
+        .option('--strict', 'fail on env validation errors (schema/requiredKeys)');
+    p = p
+        .addOption(program
+        .createDynamicOption('--entropy-warn', (cfg) => {
+        const warn = cfg.warnEntropy;
+        // Default is effectively ON when warnEntropy is true or undefined.
+        return `enable entropy warnings${warn === false ? '' : ' (default on)'}`;
+    })
+        .conflicts('entropyWarnOff'))
+        .addOption(program
+        .createDynamicOption('--entropy-warn-off', (cfg) => `disable entropy warnings${cfg.warnEntropy === false ? ' (default)' : ''}`)
+        .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
+    program.addOption = originalAddOption;
+    program.option = originalOption;
+    return p;
 };
 
 /**
  * Zod schemas for programmatic GetDotenv options.
  *
- * NOTE: These schemas are introduced without wiring to avoid behavior changes.
- * Legacy paths continue to use existing types/logic. The new plugin host will
- * use these schemas in strict mode; legacy paths will adopt them in warn mode
- * later per the staged plan.
+ * Canonical source of truth for options shape. Public types are derived
+ * from these schemas (see consumers via z.output\<\>).
  */
 // Minimal process env representation: string values or undefined to indicate "unset".
 const processEnvSchema = z.record(z.string(), z.string().optional());
@@ -879,12 +965,11 @@ const getDotenvOptionsSchemaRaw = z.object({
     excludePublic: z.boolean().optional(),
     loadProcess: z.boolean().optional(),
     log: z.boolean().optional(),
+    logger: z.unknown().optional(),
     outputPath: z.string().optional(),
     paths: z.array(z.string()).optional(),
     privateToken: z.string().optional(),
     vars: processEnvSchema.optional(),
-    // Host-only feature flag: guarded integration of config loader/overlay
-    useConfigLoader: z.boolean().optional(),
 });
 // RESOLVED: service-boundary contract (post-inheritance).
 // For Step A, keep identical to RAW (no behavior change). Later stages will// materialize required defaults and narrow shapes as resolution is wired.
@@ -904,16 +989,7 @@ const applyConfigSlice = (current, cfg, env) => {
     const envKv = env && cfg.envVars ? cfg.envVars[env] : undefined;
     return applyKv(afterGlobal, envKv);
 };
-/**
- * Overlay config-provided values onto a base ProcessEnv using precedence axes:
- * - kind: env \> global
- * - privacy: local \> public
- * - source: project \> packaged \> base
- *
- * Programmatic explicit vars (if provided) override all config slices.
- * Progressive expansion is applied within each slice.
- */
-const overlayEnv = ({ base, env, configs, programmaticVars, }) => {
+function overlayEnv({ base, env, configs, programmaticVars, }) {
     let current = { ...base };
     // Source: packaged (public -> local)
     current = applyConfigSlice(current, configs.packaged, env);
@@ -928,7 +1004,7 @@ const overlayEnv = ({ base, env, configs, programmaticVars, }) => {
         current = applyKv(current, toApply);
     }
     return current;
-};
+}
 
 /** src/diagnostics/entropy.ts
  * Entropy diagnostics (presentation-only).
@@ -938,7 +1014,7 @@ const overlayEnv = ({ base, env, configs, programmaticVars, }) => {
  */
 const warned = new Set();
 const isPrintableAscii = (s) => /^[\x20-\x7E]+$/.test(s);
-const compile$1 = (patterns) => (patterns ?? []).map((p) => new RegExp(p, 'i'));
+const compile$1 = (patterns) => (patterns ?? []).map((p) => (typeof p === 'string' ? new RegExp(p, 'i') : p));
 const whitelisted = (key, regs) => regs.some((re) => re.test(key));
 const shannonBitsPerChar = (s) => {
     const freq = new Map();
@@ -985,7 +1061,7 @@ const DEFAULT_PATTERNS = [
     '\\bapi[_-]?key\\b',
     '\\bkey\\b',
 ];
-const compile = (patterns) => (patterns && patterns.length > 0 ? patterns : DEFAULT_PATTERNS).map((p) => new RegExp(p, 'i'));
+const compile = (patterns) => (patterns && patterns.length > 0 ? patterns : DEFAULT_PATTERNS).map((p) => typeof p === 'string' ? new RegExp(p, 'i') : p);
 const shouldRedactKey = (key, regs) => regs.some((re) => re.test(key));
 const MASK = '[redacted]';
 /**
@@ -1149,43 +1225,7 @@ const loadModuleDefault = async (absPath, cacheDirName) => {
     }
 };
 
-/**
- * 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.
- */
-const getDotenv = async (options = {}) => {
+async function getDotenv(options = {}) {
     // Apply defaults.
     const { defaultEnv, dotenvToken = '.env', dynamicPath, env, excludeDynamic = false, excludeEnv = false, excludeGlobal = false, excludePrivate = false, excludePublic = false, loadProcess = false, log = false, logger = console, outputPath, paths = [], privateToken = 'local', vars = {}, } = await resolveGetDotenvOptions(options);
     // Read .env files.
@@ -1290,8 +1330,7 @@ const getDotenv = async (options = {}) => {
             .entropyThreshold;
         const entropyMinLengthVal = options
             .entropyMinLength;
-        const entropyWhitelistVal = options
-            .entropyWhitelist;
+        const entropyWhitelistVal = options.entropyWhitelist;
         const entOpts = {};
         if (typeof warnEntropyVal === 'boolean')
             entOpts.warnEntropy = warnEntropyVal;
@@ -1311,7 +1350,7 @@ const getDotenv = async (options = {}) => {
     if (loadProcess)
         Object.assign(process.env, resultDotenv);
     return resultDotenv;
-};
+}
 
 /**
  * Deep interpolation utility for string leaves.
@@ -1369,6 +1408,18 @@ const interpolateDeep = (value, envRef) => {
     return value;
 };
 
+/**
+ * Instance-bound plugin config store.
+ * Host stores the validated/interpolated slice per plugin instance.
+ * The store is intentionally private to this module; definePlugin()
+ * provides a typed accessor that reads from this store for the calling
+ * plugin instance.
+ */
+const PLUGIN_CONFIG_STORE = new WeakMap();
+const _setPluginConfigForInstance = (plugin, cfg) => {
+    PLUGIN_CONFIG_STORE.set(plugin, cfg);
+};
+const _getPluginConfigForInstance = (plugin) => PLUGIN_CONFIG_STORE.get(plugin);
 /**
  * Compute the dotenv context for the host (uses the config loader/overlay path).
  * - Resolves and validates options strictly (host-only).
@@ -1377,20 +1428,26 @@ const interpolateDeep = (value, envRef) => {
  *
  * @param customOptions - Partial options from the current invocation.
  * @param plugins - Installed plugins (for config validation).
- * @param hostMetaUrl - import.meta.url of the host module (for packaged root discovery). */
+ * @param hostMetaUrl - import.meta.url of the host module (for packaged root discovery).
+ */
 const computeContext = async (customOptions, plugins, hostMetaUrl) => {
     const optionsResolved = await resolveGetDotenvOptions(customOptions);
+    // Zod boundary: parse returns the schema-derived shape; we adopt our public
+    // GetDotenvOptions overlay (logger/dynamic typing) for internal processing.
     const validated = getDotenvOptionsSchemaResolved.parse(optionsResolved);
     // Always-on loader path
     // 1) Base from files only (no dynamic, no programmatic vars)
+    // Sanitize to avoid passing properties explicitly set to undefined.
+    const cleanedValidated = omitUndefined(validated);
     const base = await getDotenv({
-        ...validated,
+        ...cleanedValidated,
         // Build a pure base without side effects or logging.
         excludeDynamic: true,
         vars: {},
         log: false,
         loadProcess: false,
-        outputPath: undefined,
+        // Intentionally omit outputPath for the base pass; including a key with
+        // undefined would violate exactOptionalPropertyTypes on the Partial target.
     });
     // 2) Discover config sources and overlay
     const sources = await resolveGetDotenvConfigSources(hostMetaUrl);
@@ -1435,7 +1492,7 @@ const computeContext = async (customOptions, plugins, hostMetaUrl) => {
             return `${contents}${key}=${value.includes('\n') ? `"${value}"` : value}\n`;
         }, ''), { encoding: 'utf-8' });
     }
-    const logger = validated.logger ?? console;
+    const logger = customOptions.logger ?? console;
     if (validated.log)
         logger.log(dotenv);
     if (validated.loadProcess)
@@ -1450,43 +1507,148 @@ const computeContext = async (customOptions, plugins, hostMetaUrl) => {
     const localPlugins = (sources.project?.local &&
         sources.project.local.plugins) ??
         {};
-    const mergedPluginConfigs = defaultsDeep({}, packagedPlugins, publicPlugins, localPlugins);
+    // The by-id map is retained only for backwards-compat rendering paths
+    // (root help dynamic evaluation). Instance-bound access is the source
+    // of truth going forward and is populated below.
+    const mergedPluginConfigsById = defaultsDeep({}, packagedPlugins, publicPlugins, localPlugins);
     for (const p of plugins) {
         if (!p.id)
             continue;
-        const slice = mergedPluginConfigs[p.id];
-        if (slice === undefined)
-            continue;
-        // Per-plugin interpolation just before validation/afterResolve:
-        // precedence: process.env wins over ctx.dotenv for slice defaults.
+        const slice = mergedPluginConfigsById[p.id];
+        // Build interpolation reference once per plugin:
         const envRef = {
             ...dotenv,
             ...process.env,
         };
-        const interpolated = interpolateDeep(slice, envRef);
-        // Validate if a schema is provided; otherwise accept interpolated slice as-is.
-        if (p.configSchema) {
-            const parsed = p.configSchema.safeParse(interpolated);
-            if (!parsed.success) {
-                const msgs = parsed.error.issues
-                    .map((i) => `${i.path.join('.')}: ${i.message}`)
-                    .join('\n');
-                throw new Error(`Invalid config for plugin '${p.id}':\n${msgs}`);
-            }
-            mergedPluginConfigs[p.id] = parsed.data;
-        }
-        else {
-            mergedPluginConfigs[p.id] = interpolated;
+        const interpolated = slice && typeof slice === 'object'
+            ? interpolateDeep(slice, envRef)
+            : {};
+        // Enforced: plugins always carry a schema (strict empty by default).
+        // Zod v4: avoid legacy multi-generic usage; treat as generic ZodObject.
+        const schema = p.configSchema;
+        const toParse = interpolated;
+        const parsed = schema.safeParse(toParse);
+        if (!parsed.success) {
+            const err = parsed.error;
+            const msgs = err.issues
+                .map((i) => {
+                const path = Array.isArray(i.path) ? i.path.join('.') : '';
+                const msg = typeof i.message === 'string' ? i.message : 'Invalid value';
+                return path ? `${path}: ${msg}` : msg;
+            })
+                .join('\n');
+            throw new Error(`Invalid config for plugin '${p.id}':\n${msgs}`);
         }
+        // Store a readonly (shallow-frozen) value for runtime safety.
+        const frozen = Object.freeze(parsed.data);
+        _setPluginConfigForInstance(p, frozen);
+        mergedPluginConfigsById[p.id] = frozen;
     }
     return {
         optionsResolved: validated,
         dotenv: dotenv,
         plugins: {},
-        pluginConfigs: mergedPluginConfigs,
+        // Retained for legacy root help dynamic evaluation only. Instance-bound
+        // access is used by plugins themselves and tests/docs moving forward.
+        pluginConfigs: mergedPluginConfigsById,
     };
 };
 
+// Registry for dynamic descriptions keyed by Option (WeakMap so GC-friendly)
+const DYN_DESC = new WeakMap();
+/**
+ * Create an Option with a dynamic description callback stored in DYN_DESC.
+ */
+function makeDynamicOption(flags, desc, parser, defaultValue) {
+    const opt = new Option(flags, '');
+    DYN_DESC.set(opt, desc);
+    if (parser) {
+        opt.argParser((value, previous) => parser(value, previous));
+    }
+    if (defaultValue !== undefined)
+        opt.default(defaultValue);
+    return opt;
+}
+/**
+ * Evaluate dynamic descriptions across a command tree using the resolved config.
+ */
+function evaluateDynamicOptions(root, resolved) {
+    const visit = (cmd) => {
+        const arr = cmd.options;
+        for (const o of arr) {
+            const dyn = DYN_DESC.get(o);
+            if (typeof dyn === 'function') {
+                try {
+                    const txt = dyn(resolved);
+                    // Commander uses Option.description during help rendering.
+                    o.description = txt;
+                }
+                catch {
+                    /* best-effort; leave as-is */
+                }
+            }
+        }
+        for (const c of cmd.commands)
+            visit(c);
+    };
+    visit(root);
+}
+
+// Registry for grouping; root help renders groups between Options and Commands.
+const GROUP_TAG = new WeakMap();
+function renderOptionGroups(cmd) {
+    const all = cmd.options;
+    const byGroup = new Map();
+    for (const o of all) {
+        const opt = o;
+        const g = GROUP_TAG.get(opt);
+        if (!g || g === 'base')
+            continue; // base handled by default help
+        const rows = byGroup.get(g) ?? [];
+        rows.push({
+            flags: opt.flags,
+            description: opt.description ?? '',
+        });
+        byGroup.set(g, rows);
+    }
+    if (byGroup.size === 0)
+        return '';
+    const renderRows = (title, rows) => {
+        const width = Math.min(40, rows.reduce((m, r) => Math.max(m, r.flags.length), 0));
+        // Sort within group: short-aliased flags first
+        rows.sort((a, b) => {
+            const aS = /(^|\s|,)-[A-Za-z]/.test(a.flags) ? 1 : 0;
+            const bS = /(^|\s|,)-[A-Za-z]/.test(b.flags) ? 1 : 0;
+            return bS - aS || a.flags.localeCompare(b.flags);
+        });
+        const lines = rows
+            .map((r) => {
+            const pad = ' '.repeat(Math.max(2, width - r.flags.length + 2));
+            return `  ${r.flags}${pad}${r.description}`.trimEnd();
+        })
+            .join('\n');
+        return `\n${title}:\n${lines}\n`;
+    };
+    let out = '';
+    // App options (if any)
+    const app = byGroup.get('app');
+    if (app && app.length > 0) {
+        out += renderRows('App options', app);
+    }
+    // Plugin groups sorted by id; suppress self group on the owning command name.
+    const pluginKeys = Array.from(byGroup.keys()).filter((k) => k.startsWith('plugin:'));
+    const currentName = cmd.name();
+    pluginKeys.sort((a, b) => a.localeCompare(b));
+    for (const k of pluginKeys) {
+        const id = k.slice('plugin:'.length) || '(unknown)';
+        const rows = byGroup.get(k) ?? [];
+        if (rows.length > 0 && id !== currentName) {
+            out += renderRows(`Plugin options — ${id}`, rows);
+        }
+    }
+    return out;
+}
+
 const HOST_META_URL = import.meta.url;
 const CTX_SYMBOL = Symbol('GetDotenvCli.ctx');
 const OPTS_SYMBOL = Symbol('GetDotenvCli.options');
@@ -1499,8 +1661,6 @@ const HELP_HEADER_SYMBOL = Symbol('GetDotenvCli.helpHeader');
  * - Expose a stable accessor for the current context (getCtx).
  * - Provide a namespacing helper (ns).
  * - Support composable plugins with parent → children install and afterResolve.
- *
- * NOTE: This host is additive and does not alter the legacy CLI.
  */
 let GetDotenvCli$1 = class GetDotenvCli extends Command {
     /** Registered top-level plugins (composition happens via .use()) */
@@ -1509,6 +1669,17 @@ let GetDotenvCli$1 = class GetDotenvCli extends Command {
     _installed = false;
     /** Optional header line to prepend in help output */
     [HELP_HEADER_SYMBOL];
+    /** Context/options stored under symbols (typed) */
+    [CTX_SYMBOL];
+    [OPTS_SYMBOL];
+    /**
+     * Create a subcommand using the same subclass, preserving helpers like
+     * dynamicOption on children.
+     */
+    createCommand(name) {
+        // Explicitly construct a GetDotenvCli (drop subclass constructor semantics).
+        return new GetDotenvCli(name);
+    }
     constructor(alias = 'getdotenv') {
         super(alias);
         // Ensure subcommands that use passThroughOptions can be attached safely.
@@ -1516,37 +1687,39 @@ let GetDotenvCli$1 = class GetDotenvCli extends Command {
         // child uses passThroughOptions.
         this.enablePositionalOptions();
         // Configure grouped help: show only base options in default "Options";
-        // append App/Plugin sections after default help.
+        // we will insert App/Plugin sections before Commands in helpInformation().
         this.configureHelp({
             visibleOptions: (cmd) => {
-                const all = cmd.options ??
-                    [];
-                const base = all.filter((opt) => {
-                    const group = opt.__group;
-                    return group === 'base';
-                });
+                const all = cmd.options;
+                const isRoot = cmd.parent === null;
+                const list = isRoot
+                    ? all.filter((opt) => {
+                        const group = GROUP_TAG.get(opt);
+                        return group === 'base';
+                    })
+                    : all.slice(); // subcommands: show all options (their own "Options:" block)
                 // Sort: short-aliased options first, then long-only; stable by flags.
                 const hasShort = (opt) => {
-                    const flags = opt.flags ?? '';
+                    const flags = opt.flags;
                     // Matches "-x," or starting "-x " before any long
                     return /(^|\s|,)-[A-Za-z]/.test(flags);
                 };
-                const byFlags = (opt) => opt.flags ?? '';
-                base.sort((a, b) => {
+                const byFlags = (opt) => opt.flags;
+                list.sort((a, b) => {
                     const aS = hasShort(a) ? 1 : 0;
                     const bS = hasShort(b) ? 1 : 0;
                     return bS - aS || byFlags(a).localeCompare(byFlags(b));
                 });
-                return base;
+                return list;
             },
         });
         this.addHelpText('beforeAll', () => {
             const header = this[HELP_HEADER_SYMBOL];
             return header && header.length > 0 ? `${header}\n\n` : '';
         });
-        this.addHelpText('afterAll', (ctx) => this.#renderOptionGroups(ctx.command));
         // Skeleton preSubcommand hook: produce a context if absent, without
-        // mutating process.env. The passOptions hook (when installed) will    // compute the final context using merged CLI options; keeping
+        // mutating process.env. The passOptions hook (when installed) will
+        // compute the final context using merged CLI options; keeping
         // loadProcess=false here avoids leaking dotenv values into the parent
         // process env before subcommands execute.
         this.hook('preSubcommand', async () => {
@@ -1556,22 +1729,49 @@ let GetDotenvCli$1 = class GetDotenvCli extends Command {
         });
     }
     /**
-     * Resolve options (strict) and compute dotenv context.   * Stores the context on the instance under a symbol.
+     * 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.
      */
-    async resolveAndLoad(customOptions = {}) {
+    async resolveAndLoad(customOptions = {}, opts) {
         // Resolve defaults, then validate strictly under the new host.
         const optionsResolved = await resolveGetDotenvOptions(customOptions);
         getDotenvOptionsSchemaResolved.parse(optionsResolved);
         // Delegate the heavy lifting to the shared helper (guarded path supported).
         const ctx = await computeContext(optionsResolved, this._plugins, HOST_META_URL);
         // Persist context on the instance for later access.
-        this[CTX_SYMBOL] =
-            ctx;
+        this[CTX_SYMBOL] = ctx;
         // Ensure plugins are installed exactly once, then run afterResolve.
         await this.install();
-        await this._runAfterResolve(ctx);
+        if (opts?.runAfterResolve ?? true) {
+            await this._runAfterResolve(ctx);
+        }
         return ctx;
     }
+    // Implementation
+    createDynamicOption(flags, desc, parser, defaultValue) {
+        return makeDynamicOption(flags, (c) => desc(c), parser, defaultValue);
+    }
+    /**
+     * Chainable helper mirroring .option(), but with a dynamic description.
+     * Equivalent to addOption(createDynamicOption(...)).
+     */
+    dynamicOption(flags, desc, parser, defaultValue) {
+        this.addOption(this.createDynamicOption(flags, desc, parser, defaultValue));
+        return this;
+    }
+    /**
+     * 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.
+     */
+    evaluateDynamicOptions(resolved) {
+        evaluateDynamicOptions(this, resolved);
+    }
     /**
      * Retrieve the current invocation context (if any).
      */
@@ -1589,9 +1789,13 @@ let GetDotenvCli$1 = class GetDotenvCli extends Command {
     _setOptionsBag(bag) {
         this[OPTS_SYMBOL] = bag;
     }
-    /**   * Convenience helper to create a namespaced subcommand.
-     */
+    /** Convenience helper to create a namespaced subcommand. */
     ns(name) {
+        // Guard against same-level duplicate command names for clearer diagnostics.
+        const exists = this.commands.some((c) => c.name() === name);
+        if (exists) {
+            throw new Error(`Duplicate command name: ${name}`);
+        }
         return this.command(name);
     }
     /**
@@ -1601,29 +1805,15 @@ let GetDotenvCli$1 = class GetDotenvCli extends Command {
     tagAppOptions(fn) {
         const root = this;
         const originalAddOption = root.addOption.bind(root);
-        const originalOption = root.option.bind(root);
-        const tagLatest = (cmd, group) => {
-            const optsArr = cmd.options;
-            if (Array.isArray(optsArr) && optsArr.length > 0) {
-                const last = optsArr[optsArr.length - 1];
-                last.__group = group;
-            }
-        };
         root.addOption = function patchedAdd(opt) {
-            opt.__group = 'app';
+            root.setOptionGroup(opt, 'app');
             return originalAddOption(opt);
         };
-        root.option = function patchedOption(...args) {
-            const ret = originalOption(...args);
-            tagLatest(this, 'app');
-            return ret;
-        };
         try {
             return fn(root);
         }
         finally {
             root.addOption = originalAddOption;
-            root.option = originalOption;
         }
     }
     /**
@@ -1662,12 +1852,51 @@ let GetDotenvCli$1 = class GetDotenvCli extends Command {
             this[HELP_HEADER_SYMBOL] = helpHeader;
         }
         else if (v) {
-            // Use the current command name (possibly overridden by 'name' above).
             const header = `${this.name()} v${v}`;
             this[HELP_HEADER_SYMBOL] = header;
         }
         return this;
     }
+    /**
+     * Insert grouped plugin/app options between "Options" and "Commands" for
+     * hybrid ordering. Applies to root and any parent command.
+     */
+    helpInformation() {
+        // Base help text first (includes beforeAll/after hooks).
+        const base = super.helpInformation();
+        const groups = renderOptionGroups(this);
+        const block = typeof groups === 'string' ? groups.trim() : '';
+        let out = base;
+        if (!block) {
+            // Ensure a trailing blank line even when no extra groups render.
+            if (!out.endsWith('\n\n'))
+                out = out.endsWith('\n') ? `${out}\n` : `${out}\n\n`;
+            return out;
+        }
+        // Insert just before "Commands:" when present.
+        const marker = '\nCommands:';
+        const idx = base.indexOf(marker);
+        if (idx >= 0) {
+            const toInsert = groups.startsWith('\n') ? groups : `\n${groups}`;
+            out = `${base.slice(0, idx)}${toInsert}${base.slice(idx)}`;
+        }
+        else {
+            // Otherwise append.
+            const sep = base.endsWith('\n') || groups.startsWith('\n') ? '' : '\n';
+            out = `${base}${sep}${groups}`;
+        }
+        // Ensure a trailing blank line for prompt separation.
+        if (!out.endsWith('\n\n')) {
+            out = out.endsWith('\n') ? `${out}\n` : `${out}\n\n`;
+        }
+        return out;
+    }
+    /**
+     * Public: tag an Option with a display group for help (root/app/plugin:<id>).
+     */
+    setOptionGroup(opt, group) {
+        GROUP_TAG.set(opt, group);
+    }
     /**
      * Register a plugin for installation (parent level).
      * Installation occurs on first resolveAndLoad() (or explicit install()).
@@ -1706,58 +1935,18 @@ let GetDotenvCli$1 = class GetDotenvCli extends Command {
         for (const p of this._plugins)
             await run(p);
     }
-    // Render App/Plugin grouped options appended after default help.
-    #renderOptionGroups(cmd) {
-        const all = cmd.options ?? [];
-        const byGroup = new Map();
-        for (const o of all) {
-            const opt = o;
-            const g = opt.__group;
-            if (!g || g === 'base')
-                continue; // base handled by default help
-            const rows = byGroup.get(g) ?? [];
-            rows.push({
-                flags: opt.flags ?? '',
-                description: opt.description ?? '',
-            });
-            byGroup.set(g, rows);
-        }
-        if (byGroup.size === 0)
-            return '';
-        const renderRows = (title, rows) => {
-            const width = Math.min(40, rows.reduce((m, r) => Math.max(m, r.flags.length), 0));
-            // Sort within group: short-aliased flags first
-            rows.sort((a, b) => {
-                const aS = /(^|\s|,)-[A-Za-z]/.test(a.flags) ? 1 : 0;
-                const bS = /(^|\s|,)-[A-Za-z]/.test(b.flags) ? 1 : 0;
-                return bS - aS || a.flags.localeCompare(b.flags);
-            });
-            const lines = rows
-                .map((r) => {
-                const pad = ' '.repeat(Math.max(2, width - r.flags.length + 2));
-                return `  ${r.flags}${pad}${r.description}`.trimEnd();
-            })
-                .join('\n');
-            return `\n${title}:\n${lines}\n`;
-        };
-        let out = '';
-        // App options (if any)
-        const app = byGroup.get('app');
-        if (app && app.length > 0) {
-            out += renderRows('App options', app);
-        }
-        // Plugin groups sorted by id
-        const pluginKeys = Array.from(byGroup.keys()).filter((k) => k.startsWith('plugin:'));
-        pluginKeys.sort((a, b) => a.localeCompare(b));
-        for (const k of pluginKeys) {
-            const id = k.slice('plugin:'.length) || '(unknown)';
-            const rows = byGroup.get(k) ?? [];
-            if (rows.length > 0) {
-                out += renderRows(`Plugin options — ${id}`, rows);
-            }
-        }
-        return out;
-    }
+};
+
+/**
+ * Build a help-time configuration bag for dynamic option descriptions.
+ * Centralizes construction and reduces inline casts at call sites.
+ */
+const toHelpConfig = (merged, plugins) => {
+    const bag = {
+        ...merged,
+        plugins: plugins ?? {},
+    };
+    return bag;
 };
 
 /** src/cliHost/definePlugin.ts
@@ -1767,26 +1956,59 @@ let GetDotenvCli$1 = class GetDotenvCli extends Command {
  * 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) => {
+/* eslint-disable tsdoc/syntax */
+function definePlugin(spec) {
     const { children = [], ...rest } = spec;
-    const plugin = {
+    // Default to a strict empty-object schema so “no-config” plugins fail fast
+    // on unknown keys and provide a concrete {} at runtime.
+    const effectiveSchema = spec.configSchema ?? z.object({}).strict();
+    // Build base plugin first, then extend with instance-bound helpers.
+    const base = {
         ...rest,
+        // Always carry a schema (strict empty by default) to simplify host logic
+        // and improve inference/ergonomics for plugin authors.
+        configSchema: effectiveSchema,
         children: [...children],
         use(child) {
             this.children.push(child);
             return this;
         },
     };
-    return plugin;
-};
+    // Attach instance-bound helpers on the returned plugin object.
+    const extended = base;
+    extended.readConfig = function (_cli) {
+        // Config is stored per-plugin-instance by the host (WeakMap in computeContext).
+        const value = _getPluginConfigForInstance(extended);
+        if (value === undefined) {
+            // Guard: host has not resolved config yet (incorrect lifecycle usage).
+            throw new Error('Plugin config not available. Ensure resolveAndLoad() has been called before readConfig().');
+        }
+        return value;
+    };
+    // Plugin-bound dynamic option factory
+    extended.createPluginDynamicOption = function (cli, flags, desc, parser, defaultValue) {
+        return cli.createDynamicOption(flags, (cfg) => {
+            // Prefer the validated slice stored per instance; fallback to help-bag
+            // (by-id) so top-level `-h` can render effective defaults before resolve.
+            const fromStore = _getPluginConfigForInstance(extended);
+            const id = extended.id;
+            let fromBag;
+            if (!fromStore && id) {
+                const maybe = cfg.plugins[id];
+                if (maybe && typeof maybe === 'object') {
+                    fromBag = maybe;
+                }
+            }
+            // Always provide a concrete object to dynamic callbacks:
+            // - With a schema: computeContext stores the parsed object.
+            // - Without a schema: computeContext stores {}.
+            // - Help-time fallback: coalesce to {} when only a by-id bag exists.
+            const cfgVal = (fromStore ?? fromBag ?? {});
+            return desc(cfg, cfgVal);
+        }, parser, defaultValue);
+    };
+    return extended;
+}
 
 /**
  * GetDotenvCli with root helpers as real class methods.
@@ -1799,9 +2021,9 @@ class GetDotenvCli extends GetDotenvCli$1 {
      * Attach legacy root flags to this CLI instance. Defaults come from
      * baseRootOptionDefaults when none are provided.
      */
-    attachRootOptions(defaults, opts) {
+    attachRootOptions(defaults) {
         const d = (defaults ?? baseRootOptionDefaults);
-        attachRootOptions(this, d, opts);
+        attachRootOptions(this, d);
         return this;
     }
     /**
@@ -1823,10 +2045,19 @@ class GetDotenvCli extends GetDotenvCli$1 {
             // Build service options and compute context (always-on loader path).
             const serviceOptions = getDotenvCliOptions2Options(merged);
             await this.resolveAndLoad(serviceOptions);
+            // Refresh dynamic option descriptions using resolved config + plugin slices
+            try {
+                const ctx = this.getCtx();
+                const helpCfg = toHelpConfig(merged, ctx?.pluginConfigs ?? {});
+                this.evaluateDynamicOptions(helpCfg);
+            }
+            catch {
+                /* best-effort */
+            }
             // Global validation: once after Phase C using config sources.
             try {
                 const ctx = this.getCtx();
-                const dotenv = (ctx?.dotenv ?? {});
+                const dotenv = ctx?.dotenv ?? {};
                 const sources = await resolveGetDotenvConfigSources(import.meta.url);
                 const issues = validateEnvAgainstSources(dotenv, sources);
                 if (Array.isArray(issues) && issues.length > 0) {
@@ -1836,9 +2067,8 @@ class GetDotenvCli extends GetDotenvCli$1 {
                     issues.forEach((m) => {
                         emit(m);
                     });
-                    if (merged.strict) {
+                    if (merged.strict)
                         process.exit(1);
-                    }
                 }
             }
             catch {
@@ -1857,6 +2087,14 @@ class GetDotenvCli extends GetDotenvCli$1 {
             if (!this.getCtx()) {
                 const serviceOptions = getDotenvCliOptions2Options(merged);
                 await this.resolveAndLoad(serviceOptions);
+                try {
+                    const ctx = this.getCtx();
+                    const helpCfg = toHelpConfig(merged, ctx?.pluginConfigs ?? {});
+                    this.evaluateDynamicOptions(helpCfg);
+                }
+                catch {
+                    /* tolerate */
+                }
                 try {
                     const ctx = this.getCtx();
                     const dotenv = (ctx?.dotenv ?? {});
@@ -1882,23 +2120,52 @@ class GetDotenvCli extends GetDotenvCli$1 {
         return this;
     }
 }
+/**
+ * Helper to retrieve the merged root options bag from any action handler
+ * that only has access to thisCommand. Avoids structural casts.
+ */
+const readMergedOptions = (cmd) => {
+    // Ascend to the root command
+    let root = cmd;
+    while (root.parent) {
+        root = root.parent;
+    }
+    const hostAny = root;
+    return typeof hostAny.getOptions === 'function'
+        ? hostAny.getOptions()
+        : root
+            .getDotenvCliOptions;
+};
 
 // Minimal tokenizer for shell-off execution:
 // Splits by whitespace while preserving quoted segments (single or double quotes).
-const tokenize = (command) => {
+// Optionally preserve doubled quotes inside quoted segments:
+// - default: "" => " (Windows/PowerShell style literal-quote escape)
+// - preserveDoubledQuotes: true => "" stays "" (needed for Node -e payloads)
+const tokenize = (command, opts) => {
     const out = [];
     let cur = '';
     let quote = null;
+    const preserve = opts && opts.preserveDoubledQuotes === true ? true : false;
     for (let i = 0; i < command.length; i++) {
         const c = command.charAt(i);
         if (quote) {
             if (c === quote) {
-                // Support doubled quotes inside a quoted segment (Windows/PowerShell style):
-                // "" -> " and '' -> '
+                // Support doubled quotes inside a quoted segment:
+                // default: "" -> " and '' -> ' (Windows/PowerShell style)
+                // preserve: keep as "" to allow empty string literals in Node -e payloads
                 const next = command.charAt(i + 1);
                 if (next === quote) {
-                    cur += quote;
-                    i += 1; // skip the second quote
+                    if (preserve) {
+                        // Keep "" as-is; append both and continue within the quoted segment.
+                        cur += quote + quote;
+                        i += 1; // skip the second quote char (we already appended both)
+                    }
+                    else {
+                        // Collapse to a single literal quote
+                        cur += quote;
+                        i += 1; // skip the second quote
+                    }
                 }
                 else {
                     // end of quoted segment
@@ -1972,62 +2239,55 @@ const sanitizeEnv = (env) => {
     const entries = Object.entries(env).filter((e) => typeof e[1] === 'string');
     return entries.length > 0 ? Object.fromEntries(entries) : undefined;
 };
-/**
- * Execute a command and capture stdout/stderr (buffered).
- * - Preserves plain vs shell behavior and argv/string normalization.
- * - Never re-emits stdout/stderr to parent; returns captured buffers.
- * - Supports optional timeout (ms).
- */
-const runCommandResult = async (command, shell, opts = {}) => {
+async function runCommandResult(command, shell, opts = {}) {
     const envSan = sanitizeEnv(opts.env);
     {
         let file;
         let args = [];
-        if (Array.isArray(command)) {
-            file = command[0];
-            args = command.slice(1).map(stripOuterQuotes);
-        }
-        else {
+        if (typeof command === 'string') {
             const tokens = tokenize(command);
             file = tokens[0];
             args = tokens.slice(1);
         }
+        else {
+            file = command[0];
+            args = command.slice(1).map(stripOuterQuotes);
+        }
         if (!file)
             return { exitCode: 0, stdout: '', stderr: '' };
         dbg$1('exec:capture (plain)', { file, args });
         try {
-            const result = await execa(file, args, {
+            const ok = pickResult((await execa(file, args, {
                 ...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),
                 ...(envSan !== undefined ? { env: envSan } : {}),
                 stdio: 'pipe',
                 ...(opts.timeoutMs !== undefined
                     ? { timeout: opts.timeoutMs, killSignal: 'SIGKILL' }
                     : {}),
-            });
-            const ok = pickResult(result);
+            })));
             dbg$1('exit:capture (plain)', { exitCode: ok.exitCode });
             return ok;
         }
-        catch (err) {
-            const out = pickResult(err);
+        catch (e) {
+            const out = pickResult(e);
             dbg$1('exit:capture:error (plain)', { exitCode: out.exitCode });
             return out;
         }
     }
-};
-const runCommand = async (command, shell, opts) => {
+}
+async function runCommand(command, shell, opts) {
     if (shell === false) {
         let file;
         let args = [];
-        if (Array.isArray(command)) {
-            file = command[0];
-            args = command.slice(1).map(stripOuterQuotes);
-        }
-        else {
+        if (typeof command === 'string') {
             const tokens = tokenize(command);
             file = tokens[0];
             args = tokens.slice(1);
         }
+        else {
+            file = command[0];
+            args = command.slice(1).map(stripOuterQuotes);
+        }
         if (!file)
             return 0;
         dbg$1('exec (plain)', { file, args, stdio: opts.stdio });
@@ -2040,16 +2300,15 @@ const runCommand = async (command, shell, opts) => {
             plainOpts.env = envSan;
         if (opts.stdio !== undefined)
             plainOpts.stdio = opts.stdio;
-        const result = await execa(file, args, plainOpts);
-        if (opts.stdio === 'pipe' && result.stdout) {
-            process.stdout.write(result.stdout + (result.stdout.endsWith('\n') ? '' : '\n'));
+        const ok = pickResult((await execa(file, args, plainOpts)));
+        if (opts.stdio === 'pipe' && ok.stdout) {
+            process.stdout.write(ok.stdout + (ok.stdout.endsWith('\n') ? '' : '\n'));
         }
-        const exit = result?.exitCode;
-        dbg$1('exit (plain)', { exitCode: exit });
-        return typeof exit === 'number' ? exit : Number.NaN;
+        dbg$1('exit (plain)', { exitCode: ok.exitCode });
+        return typeof ok.exitCode === 'number' ? ok.exitCode : Number.NaN;
     }
     else {
-        const commandStr = Array.isArray(command) ? command.join(' ') : command;
+        const commandStr = typeof command === 'string' ? command : command.join(' ');
         dbg$1('exec (shell)', {
             shell: typeof shell === 'string' ? shell : 'custom',
             stdio: opts.stdio,
@@ -2063,17 +2322,29 @@ const runCommand = async (command, shell, opts) => {
             shellOpts.env = envSan;
         if (opts.stdio !== undefined)
             shellOpts.stdio = opts.stdio;
-        const result = await execaCommand(commandStr, shellOpts);
-        const out = result?.stdout;
-        if (opts.stdio === 'pipe' && out) {
-            process.stdout.write(out + (out.endsWith('\n') ? '' : '\n'));
+        const ok = pickResult((await execaCommand(commandStr, shellOpts)));
+        if (opts.stdio === 'pipe' && ok.stdout) {
+            process.stdout.write(ok.stdout + (ok.stdout.endsWith('\n') ? '' : '\n'));
         }
-        const exit = result?.exitCode;
-        dbg$1('exit (shell)', { exitCode: exit });
-        return typeof exit === 'number' ? exit : Number.NaN;
+        dbg$1('exit (shell)', { exitCode: ok.exitCode });
+        return typeof ok.exitCode === 'number' ? ok.exitCode : Number.NaN;
     }
-};
+}
 
+/** 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.
+ */
 const dropUndefined = (bag) => Object.fromEntries(Object.entries(bag).filter((e) => typeof e[1] === 'string'));
 /** Build a sanitized env for child processes from base + overlay. */
 const buildSpawnEnv = (base, overlay) => {
@@ -2338,90 +2609,79 @@ const AwsPluginConfigSchema = z.object({
     regionKey: z.string().default('AWS_REGION').optional(),
     strategy: z.enum(['cli-export', 'none']).default('cli-export').optional(),
     loginOnDemand: z.boolean().default(false).optional(),
-    setEnv: z.boolean().default(true).optional(),
-    addCtx: z.boolean().default(true).optional(),
 });
 
-const awsPlugin = () => definePlugin({
-    id: 'aws',
-    // Host validates this slice when the loader path is active.
-    configSchema: AwsPluginConfigSchema,
-    setup(cli) {
-        // Subcommand: aws
-        cli
-            .ns('aws')
-            .description('Establish an AWS session and optionally forward to the AWS CLI')
-            .configureHelp({ showGlobalOptions: true })
-            .enablePositionalOptions()
-            .passThroughOptions()
-            .allowUnknownOption(true)
-            // Boolean toggles
-            .option('--login-on-demand', 'attempt aws sso login on-demand')
-            .option('--no-login-on-demand', 'disable sso login on-demand')
-            .option('--set-env', 'write resolved values into process.env')
-            .option('--no-set-env', 'do not write resolved values into process.env')
-            .option('--add-ctx', 'mirror results under ctx.plugins.aws')
-            .option('--no-add-ctx', 'do not mirror results under ctx.plugins.aws')
-            // Strings / enums
-            .option('--profile <string>', 'AWS profile name')
-            .option('--region <string>', 'AWS region')
-            .option('--default-region <string>', 'fallback region')
-            .option('--strategy <string>', 'credential acquisition strategy: cli-export|none')
-            // Advanced key overrides
-            .option('--profile-key <string>', 'dotenv/config key for local profile')
-            .option('--profile-fallback-key <string>', 'fallback dotenv/config key for profile')
-            .option('--region-key <string>', 'dotenv/config key for region')
-            // Accept any extra operands so Commander does not error when tokens appear after "--".
-            .argument('[args...]')
-            .action(async (args, opts, thisCommand) => {
-            const self = thisCommand;
-            const parent = (self.parent ?? null);
-            // Access merged root CLI options (installed by passOptions())
-            const rootOpts = (parent?.getDotenvCliOptions ?? {});
-            const capture = process.env.GETDOTENV_STDIO === 'pipe' ||
-                Boolean(rootOpts?.capture);
-            const underTests = process.env.GETDOTENV_TEST === '1' ||
-                typeof process.env.VITEST_WORKER_ID === 'string';
-            // Build overlay cfg from subcommand flags layered over discovered config.
-            const ctx = cli.getCtx();
-            const cfgBase = (ctx?.pluginConfigs?.['aws'] ??
-                {});
-            const overlay = {};
-            // Map boolean toggles (respect explicit --no-*)
-            if (Object.prototype.hasOwnProperty.call(opts, 'loginOnDemand'))
-                overlay.loginOnDemand = Boolean(opts.loginOnDemand);
-            if (Object.prototype.hasOwnProperty.call(opts, 'setEnv'))
-                overlay.setEnv = Boolean(opts.setEnv);
-            if (Object.prototype.hasOwnProperty.call(opts, 'addCtx'))
-                overlay.addCtx = Boolean(opts.addCtx);
-            // Strings/enums
-            if (typeof opts.profile === 'string')
-                overlay.profile = opts.profile;
-            if (typeof opts.region === 'string')
-                overlay.region = opts.region;
-            if (typeof opts.defaultRegion === 'string')
-                overlay.defaultRegion = opts.defaultRegion;
-            if (typeof opts.strategy === 'string')
-                overlay.strategy =
-                    opts.strategy;
-            // Advanced key overrides
-            if (typeof opts.profileKey === 'string')
-                overlay.profileKey = opts.profileKey;
-            if (typeof opts.profileFallbackKey === 'string')
-                overlay.profileFallbackKey = opts.profileFallbackKey;
-            if (typeof opts.regionKey === 'string')
-                overlay.regionKey = opts.regionKey;
-            const cfg = {
-                ...cfgBase,
-                ...overlay,
-            };
-            // Resolve current context with overrides
-            const out = await resolveAwsContext({
-                dotenv: ctx?.dotenv ?? {},
-                cfg,
-            });
-            // Apply env/ctx mirrors per toggles
-            if (cfg.setEnv !== false) {
+const awsPlugin = () => {
+    const plugin = definePlugin({
+        id: 'aws',
+        // Host validates this slice when the loader path is active.
+        configSchema: AwsPluginConfigSchema,
+        setup(cli) {
+            // Subcommand: aws
+            cli
+                .ns('aws')
+                .description('Establish an AWS session and optionally forward to the AWS CLI')
+                .enablePositionalOptions()
+                .passThroughOptions()
+                .allowUnknownOption(true)
+                // Boolean toggles with dynamic help labels (effective defaults)
+                .addOption(plugin.createPluginDynamicOption(cli, '--login-on-demand', (_bag, cfg) => `attempt aws sso login on-demand${cfg.loginOnDemand ? ' (default)' : ''}`))
+                .addOption(plugin.createPluginDynamicOption(cli, '--no-login-on-demand', (_bag, cfg) => `disable sso login on-demand${cfg.loginOnDemand === false ? ' (default)' : ''}`))
+                // Strings / enums
+                .addOption(plugin.createPluginDynamicOption(cli, '--profile <string>', (_bag, cfg) => `AWS profile name${cfg.profile ? ` (default: ${JSON.stringify(cfg.profile)})` : ''}`))
+                .addOption(plugin.createPluginDynamicOption(cli, '--region <string>', (_bag, cfg) => `AWS region${cfg.region ? ` (default: ${JSON.stringify(cfg.region)})` : ''}`))
+                .addOption(plugin.createPluginDynamicOption(cli, '--default-region <string>', (_bag, cfg) => `fallback region${cfg.defaultRegion ? ` (default: ${JSON.stringify(cfg.defaultRegion)})` : ''}`))
+                .addOption(plugin.createPluginDynamicOption(cli, '--strategy <string>', (_bag, cfg) => `credential acquisition strategy: cli-export|none${cfg.strategy ? ` (default: ${JSON.stringify(cfg.strategy)})` : ''}`))
+                // Advanced key overrides
+                .addOption(plugin.createPluginDynamicOption(cli, '--profile-key <string>', (_bag, cfg) => `dotenv/config key for local profile${cfg.profileKey ? ` (default: ${JSON.stringify(cfg.profileKey)})` : ''}`))
+                .addOption(plugin.createPluginDynamicOption(cli, '--profile-fallback-key <string>', (_bag, cfg) => `fallback dotenv/config key for profile${cfg.profileFallbackKey ? ` (default: ${JSON.stringify(cfg.profileFallbackKey)})` : ''}`))
+                .addOption(plugin.createPluginDynamicOption(cli, '--region-key <string>', (_bag, cfg) => `dotenv/config key for region${cfg.regionKey ? ` (default: ${JSON.stringify(cfg.regionKey)})` : ''}`))
+                // Accept any extra operands so Commander does not error when tokens appear after "--".
+                .argument('[args...]')
+                .action(async (args, opts, thisCommand) => {
+                const pluginInst = plugin;
+                const cmdSelf = thisCommand;
+                const parent = (cmdSelf.parent ?? null);
+                // Access merged root CLI options (installed by passOptions())
+                const rootOpts = (parent?.getDotenvCliOptions ?? {});
+                const capture = process.env.GETDOTENV_STDIO === 'pipe' ||
+                    Boolean(rootOpts?.capture);
+                const underTests = process.env.GETDOTENV_TEST === '1' ||
+                    typeof process.env.VITEST_WORKER_ID === 'string';
+                // Build overlay cfg from subcommand flags layered over discovered config.
+                const ctx = cli.getCtx();
+                const cfgBase = pluginInst.readConfig(cli);
+                const o = opts;
+                const overlay = {};
+                // Map boolean toggles (respect explicit --no-*)
+                if (Object.prototype.hasOwnProperty.call(o, 'loginOnDemand'))
+                    overlay.loginOnDemand = Boolean(o.loginOnDemand);
+                // Strings/enums
+                if (typeof o.profile === 'string')
+                    overlay.profile = o.profile;
+                if (typeof o.region === 'string')
+                    overlay.region = o.region;
+                if (typeof o.defaultRegion === 'string')
+                    overlay.defaultRegion = o.defaultRegion;
+                if (typeof o.strategy === 'string')
+                    overlay.strategy = o.strategy;
+                // Advanced key overrides
+                if (typeof o.profileKey === 'string')
+                    overlay.profileKey = o.profileKey;
+                if (typeof o.profileFallbackKey === 'string')
+                    overlay.profileFallbackKey = o.profileFallbackKey;
+                if (typeof o.regionKey === 'string')
+                    overlay.regionKey = o.regionKey;
+                const cfg = {
+                    ...cfgBase,
+                    ...overlay,
+                };
+                // Resolve current context with overrides
+                const out = await resolveAwsContext({
+                    dotenv: ctx?.dotenv ?? {},
+                    cfg,
+                });
+                // Unconditional env writes (no per-plugin toggle)
                 if (out.region) {
                     process.env.AWS_REGION = out.region;
                     if (!process.env.AWS_DEFAULT_REGION)
@@ -2435,58 +2695,53 @@ const awsPlugin = () => definePlugin({
                         process.env.AWS_SESSION_TOKEN = out.credentials.sessionToken;
                     }
                 }
-            }
-            if (cfg.addCtx !== false) {
+                // Always publish minimal non-sensitive metadata
                 if (ctx) {
                     ctx.plugins ??= {};
                     ctx.plugins['aws'] = {
                         ...(out.profile ? { profile: out.profile } : {}),
                         ...(out.region ? { region: out.region } : {}),
-                        ...(out.credentials ? { credentials: out.credentials } : {}),
                     };
                 }
-            }
-            // Forward when positional args are present; otherwise session-only.
-            if (Array.isArray(args) && args.length > 0) {
-                const argv = ['aws', ...args];
-                const shellSetting = resolveShell(rootOpts?.scripts, 'aws', rootOpts?.shell);
-                const ctxDotenv = (ctx?.dotenv ?? {});
-                const exit = await runCommand(argv, shellSetting, {
-                    env: buildSpawnEnv(process.env, ctxDotenv),
-                    stdio: capture ? 'pipe' : 'inherit',
-                });
-                // Deterministic termination (suppressed under tests)
-                if (!underTests) {
-                    process.exit(typeof exit === 'number' ? exit : 0);
-                }
-                return;
-            }
-            else {
-                // Session only: low-noise breadcrumb under debug
-                if (process.env.GETDOTENV_DEBUG) {
-                    const log = console;
-                    log.log('[aws] session established', {
-                        profile: out.profile,
-                        region: out.region,
-                        hasCreds: Boolean(out.credentials),
+                // Forward when positional args are present; otherwise session-only.
+                if (Array.isArray(args) && args.length > 0) {
+                    const argv = ['aws', ...args];
+                    const shellSetting = resolveShell(rootOpts?.scripts, 'aws', rootOpts?.shell);
+                    const exit = await runCommand(argv, shellSetting, {
+                        env: buildSpawnEnv(process.env, ctx?.dotenv),
+                        stdio: capture ? 'pipe' : 'inherit',
                     });
+                    // Deterministic termination (suppressed under tests)
+                    if (!underTests) {
+                        process.exit(typeof exit === 'number' ? exit : 0);
+                    }
+                    return;
                 }
-                if (!underTests)
-                    process.exit(0);
-                return;
-            }
-        });
-    },
-    async afterResolve(_cli, ctx) {
-        const log = console;
-        const cfgRaw = (ctx.pluginConfigs?.['aws'] ?? {});
-        const cfg = (cfgRaw || {});
-        const out = await resolveAwsContext({
-            dotenv: ctx.dotenv,
-            cfg,
-        });
-        const { profile, region, credentials } = out;
-        if (cfg.setEnv !== false) {
+                else {
+                    // Session only: low-noise breadcrumb under debug
+                    if (process.env.GETDOTENV_DEBUG) {
+                        const log = console;
+                        log.log('[aws] session established', {
+                            profile: out.profile,
+                            region: out.region,
+                            hasCreds: Boolean(out.credentials),
+                        });
+                    }
+                    if (!underTests)
+                        process.exit(0);
+                    return;
+                }
+            });
+        },
+        async afterResolve(_cli, ctx) {
+            const log = console;
+            const cfg = plugin.readConfig(_cli);
+            const out = await resolveAwsContext({
+                dotenv: ctx.dotenv,
+                cfg,
+            });
+            const { profile, region, credentials } = out;
+            // Unconditional env writes in host path
             if (region) {
                 process.env.AWS_REGION = region;
                 if (!process.env.AWS_DEFAULT_REGION)
@@ -2499,25 +2754,24 @@ const awsPlugin = () => definePlugin({
                     process.env.AWS_SESSION_TOKEN = credentials.sessionToken;
                 }
             }
-        }
-        if (cfg.addCtx !== false) {
+            // Always publish minimal non-sensitive metadata
             ctx.plugins ??= {};
             ctx.plugins['aws'] = {
                 ...(profile ? { profile } : {}),
                 ...(region ? { region } : {}),
-                ...(credentials ? { credentials } : {}),
             };
-        }
-        // Optional: low-noise breadcrumb for diagnostics
-        if (process.env.GETDOTENV_DEBUG) {
-            log.log('[aws] afterResolve', {
-                profile,
-                region,
-                hasCreds: Boolean(credentials),
-            });
-        }
-    },
-});
+            // Optional: low-noise breadcrumb for diagnostics
+            if (process.env.GETDOTENV_DEBUG) {
+                log.log('[aws] afterResolve', {
+                    profile,
+                    region,
+                    hasCreds: Boolean(credentials),
+                });
+            }
+        },
+    });
+    return plugin;
+};
 
 const globPaths = async ({ globs, logger, pkgCwd, rootPath, }) => {
     let cwd = process.cwd();
@@ -2542,9 +2796,10 @@ const globPaths = async ({ globs, logger, pkgCwd, rootPath, }) => {
     }
     return { absRootPath, paths };
 };
-const execShellCommandBatch = async ({ command, getDotenvCliOptions, globs, ignoreErrors, list, logger, pkgCwd, rootPath, shell, }) => {
+const execShellCommandBatch = async ({ command, getDotenvCliOptions, dotenvEnv, globs, ignoreErrors, list, logger, pkgCwd, rootPath, shell, }) => {
     const capture = process.env.GETDOTENV_STDIO === 'pipe' ||
-        Boolean(getDotenvCliOptions?.capture); // Require a command only when not listing. In list mode, a command is optional.
+        Boolean(getDotenvCliOptions?.capture);
+    // Require a command only when not listing. In list mode, a command is optional.
     if (!command && !list) {
         logger.error(`No command provided. Use --command or --list.`);
         process.exit(0);
@@ -2591,12 +2846,25 @@ const execShellCommandBatch = async ({ command, getDotenvCliOptions, globs, igno
             const hasCmd = (typeof command === 'string' && command.length > 0) ||
                 (Array.isArray(command) && command.length > 0);
             if (hasCmd) {
-                const envBag = getDotenvCliOptions !== undefined
-                    ? { getDotenvCliOptions: JSON.stringify(getDotenvCliOptions) }
-                    : undefined;
+                // Compose child env overlay from dotenv (drop undefined) and merged options
+                const overlay = {};
+                if (dotenvEnv) {
+                    for (const [k, v] of Object.entries(dotenvEnv)) {
+                        if (typeof v === 'string')
+                            overlay[k] = v;
+                    }
+                }
+                if (getDotenvCliOptions !== undefined) {
+                    try {
+                        overlay.getDotenvCliOptions = JSON.stringify(getDotenvCliOptions);
+                    }
+                    catch {
+                        // best-effort: omit if serialization fails
+                    }
+                }
                 await runCommand(command, shell, {
                     cwd: path,
-                    env: buildSpawnEnv(process.env, envBag),
+                    env: buildSpawnEnv(process.env, overlay),
                     stdio: capture ? 'pipe' : 'inherit',
                 });
             }
@@ -2619,7 +2887,7 @@ const execShellCommandBatch = async ({ command, getDotenvCliOptions, globs, igno
  * Build the default "cmd" subcommand action for the batch plugin.
  * Mirrors the original inline implementation with identical behavior.
  */
-const buildDefaultCmdAction = (cli, batchCmd, opts) => async (commandParts, _subOpts, _thisCommand) => {
+const buildDefaultCmdAction = (plugin, cli, batchCmd, opts) => async (commandParts, _subOpts, _thisCommand) => {
     const loggerLocal = opts.logger ?? console;
     // Guard: when invoked without positional args (e.g., `batch --list`),
     // defer entirely to the parent action handler.
@@ -2631,9 +2899,8 @@ const buildDefaultCmdAction = (cli, batchCmd, opts) => async (commandParts, _sub
         ? argsRaw.filter((t) => t !== '-l' && t !== '--list')
         : argsRaw;
     // Access merged per-plugin config from host context (if any).
-    const ctx = cli.getCtx();
-    const cfgRaw = (ctx?.pluginConfigs?.['batch'] ?? {});
-    const cfg = (cfgRaw || {});
+    const cfg = plugin.readConfig(cli);
+    const dotenvEnv = (cli.getCtx()?.dotenv ?? {});
     // Resolve batch flags from the captured parent (batch) command.
     const raw = batchCmd.opts();
     const listFromParent = !!raw.list;
@@ -2652,6 +2919,7 @@ const buildDefaultCmdAction = (cli, batchCmd, opts) => async (commandParts, _sub
         if (typeof commandOpt === 'string') {
             await execShellCommandBatch({
                 command: resolveCommand(scripts, commandOpt),
+                dotenvEnv,
                 globs,
                 ignoreErrors,
                 list: false,
@@ -2663,6 +2931,7 @@ const buildDefaultCmdAction = (cli, batchCmd, opts) => async (commandParts, _sub
             return;
         }
         if (raw.list || localList) {
+            const shellBag = ((batchCmd.parent ?? undefined)?.getDotenvCliOptions ?? {});
             await execShellCommandBatch({
                 globs,
                 ignoreErrors,
@@ -2670,7 +2939,7 @@ const buildDefaultCmdAction = (cli, batchCmd, opts) => async (commandParts, _sub
                 logger: loggerLocal,
                 ...(pkgCwd ? { pkgCwd } : {}),
                 rootPath,
-                shell: (shell ?? false),
+                shell: shell ?? shellBag.shell ?? false,
             });
             return;
         }
@@ -2694,7 +2963,7 @@ const buildDefaultCmdAction = (cli, batchCmd, opts) => async (commandParts, _sub
             logger: loggerLocal,
             ...(pkgCwd ? { pkgCwd } : {}),
             rootPath,
-            shell: (shell ?? shellBag.shell ?? false),
+            shell: shell ?? shellBag.shell ?? false,
         });
         return;
     }
@@ -2737,6 +3006,7 @@ const buildDefaultCmdAction = (cli, batchCmd, opts) => async (commandParts, _sub
     }
     await execShellCommandBatch({
         command: commandArg,
+        dotenvEnv,
         ...(envBag ? { getDotenvCliOptions: envBag } : {}),
         globs,
         ignoreErrors,
@@ -2751,12 +3021,11 @@ const buildDefaultCmdAction = (cli, batchCmd, opts) => async (commandParts, _sub
 /**
  * Build the parent "batch" action handler (no explicit subcommand).
  */
-const buildParentAction = (cli, opts) => async (commandParts, thisCommand) => {
-    const logger = opts.logger ?? console;
+const buildParentAction = (plugin, cli, opts) => async (commandParts, thisCommand) => {
+    const loggerLocal = opts.logger ?? console;
     // Ensure context exists (host preSubcommand on root creates if missing).
-    const ctx = cli.getCtx();
-    const cfgRaw = (ctx?.pluginConfigs?.['batch'] ?? {});
-    const cfg = (cfgRaw || {});
+    const dotenvEnv = (cli.getCtx()?.dotenv ?? {});
+    const cfg = plugin.readConfig(cli);
     const raw = thisCommand.opts();
     const commandOpt = typeof raw.command === 'string' ? raw.command : undefined;
     const ignoreErrors = !!raw.ignoreErrors;
@@ -2777,10 +3046,11 @@ const buildParentAction = (cli, opts) => async (commandParts, thisCommand) => {
         const commandArg = resolved;
         await execShellCommandBatch({
             command: commandArg,
+            dotenvEnv,
             globs,
             ignoreErrors,
             list: false,
-            logger,
+            logger: loggerLocal,
             ...(pkgCwd ? { pkgCwd } : {}),
             rootPath,
             shell: shellSetting,
@@ -2793,19 +3063,20 @@ const buildParentAction = (cli, opts) => async (commandParts, thisCommand) => {
         if (extra.length > 0)
             globs = [globs, extra].filter(Boolean).join(' ');
         const mergedBag = ((thisCommand.parent ?? null)?.getDotenvCliOptions ?? {});
+        const shellMerged = opts.shell ?? cfg.shell ?? mergedBag.shell ?? false;
         await execShellCommandBatch({
             globs,
             ignoreErrors,
             list: true,
-            logger,
+            logger: loggerLocal,
             ...(pkgCwd ? { pkgCwd } : {}),
             rootPath,
-            shell: (opts.shell ?? cfg.shell ?? mergedBag.shell ?? false),
+            shell: shellMerged,
         });
         return;
     }
     if (!commandOpt && !list) {
-        logger.error(`No command provided. Use --command or --list.`);
+        loggerLocal.error(`No command provided. Use --command or --list.`);
         process.exit(0);
     }
     if (typeof commandOpt === 'string') {
@@ -2814,10 +3085,11 @@ const buildParentAction = (cli, opts) => async (commandParts, thisCommand) => {
         const shellOpt = opts.shell ?? cfg.shell ?? mergedBag.shell;
         await execShellCommandBatch({
             command: resolveCommand(scriptsOpt, commandOpt),
+            dotenvEnv,
             globs,
             ignoreErrors,
             list,
-            logger,
+            logger: loggerLocal,
             ...(pkgCwd ? { pkgCwd } : {}),
             rootPath,
             shell: resolveShell(scriptsOpt, commandOpt, shellOpt),
@@ -2826,15 +3098,15 @@ const buildParentAction = (cli, opts) => async (commandParts, thisCommand) => {
     }
     // list only (explicit --list without --command)
     const mergedBag = ((thisCommand.parent ?? null)?.getDotenvCliOptions ?? {});
-    const shellOnly = (opts.shell ?? cfg.shell ?? mergedBag.shell ?? false);
+    const shellOnly = opts.shell ?? cfg.shell ?? mergedBag.shell ?? false;
     await execShellCommandBatch({
         globs,
         ignoreErrors,
         list: true,
-        logger,
+        logger: loggerLocal,
         ...(pkgCwd ? { pkgCwd } : {}),
         rootPath,
-        shell: (shellOnly ?? false),
+        shell: shellOnly,
     });
 };
 
@@ -2857,53 +3129,277 @@ const BatchConfigSchema = z.object({
 /**
  * Batch plugin for the GetDotenv CLI host.
  *
- * Mirrors the legacy batch subcommand behavior without altering the shipped CLI. * Options:
+ * Mirrors the legacy batch subcommand behavior without altering the shipped CLI.
+ * Options:
  * - scripts/shell: used to resolve command and shell behavior per script or global default.
  * - logger: defaults to console.
  */
-const batchPlugin = (opts = {}) => definePlugin({
-    id: 'batch',
-    // Host validates this when config-loader is enabled; plugins may also
-    // re-validate at action time as a safety belt.
-    configSchema: BatchConfigSchema,
-    setup(cli) {
-        const ns = cli.ns('batch');
-        const batchCmd = ns; // capture the parent "batch" command for default-subcommand context
-        ns.description('Batch command execution across multiple working directories.')
-            .enablePositionalOptions()
-            .passThroughOptions()
-            .option('-p, --pkg-cwd', 'use nearest package directory as current working directory')
-            .option('-r, --root-path <string>', 'path to batch root directory from current working directory', './')
-            .option('-g, --globs <string>', 'space-delimited globs from root path', '*')
-            .option('-c, --command <string>', 'command executed according to the base shell resolution')
-            .option('-l, --list', 'list working directories without executing command')
-            .option('-e, --ignore-errors', 'ignore errors and continue with next path')
-            .argument('[command...]')
-            .addCommand(new Command()
-            .name('cmd')
-            .description('execute command, conflicts with --command option (default subcommand)')
-            .enablePositionalOptions()
-            .passThroughOptions()
-            .argument('[command...]')
-            .action(buildDefaultCmdAction(cli, batchCmd, opts)), { isDefault: true })
-            .action(buildParentAction(cli, opts));
-    },
-});
+const batchPlugin = (opts = {}) => {
+    const plugin = definePlugin({
+        id: 'batch',
+        // Host validates this when config-loader is enabled; plugins may also
+        // re-validate at action time as a safety belt.
+        configSchema: BatchConfigSchema,
+        setup(cli) {
+            const ns = cli.ns('batch');
+            const batchCmd = ns; // capture the parent "batch" command for default-subcommand context
+            const pluginId = 'batch';
+            const GROUP = `plugin:${pluginId}`;
+            ns.description('Batch command execution across multiple working directories.')
+                .enablePositionalOptions()
+                .passThroughOptions()
+                // Dynamic help: show effective defaults from the merged/interpolated plugin config slice.
+                .addOption((() => {
+                const opt = plugin.createPluginDynamicOption(cli, '-p, --pkg-cwd', (_bag, cfg) => `use nearest package directory as current working directory${cfg.pkgCwd ? ' (default)' : ''}`);
+                cli.setOptionGroup(opt, GROUP);
+                return opt;
+            })())
+                .addOption((() => {
+                const opt = plugin.createPluginDynamicOption(cli, '-r, --root-path <string>', (_bag, cfg) => `path to batch root directory from current working directory (default: ${JSON.stringify(cfg.rootPath || './')})`);
+                cli.setOptionGroup(opt, GROUP);
+                return opt;
+            })())
+                .addOption((() => {
+                const opt = plugin.createPluginDynamicOption(cli, '-g, --globs <string>', (_bag, cfg) => `space-delimited globs from root path (default: ${JSON.stringify(cfg.globs || '*')})`);
+                cli.setOptionGroup(opt, GROUP);
+                return opt;
+            })())
+                .option('-c, --command <string>', 'command executed according to the base shell resolution')
+                .option('-l, --list', 'list working directories without executing command')
+                .option('-e, --ignore-errors', 'ignore errors and continue with next path')
+                .argument('[command...]')
+                .addCommand(new Command()
+                .name('cmd')
+                .description('execute command, conflicts with --command option (default subcommand)')
+                .enablePositionalOptions()
+                .passThroughOptions()
+                .argument('[command...]')
+                .action(buildDefaultCmdAction(plugin, cli, batchCmd, opts)), { isDefault: true })
+                .action(buildParentAction(plugin, cli, opts));
+        },
+    });
+    return plugin;
+};
 
 const dbg = (...args) => {
     if (process.env.GETDOTENV_DEBUG) {
         // Use stderr to avoid interfering with stdout assertions
         console.error('[getdotenv:alias]', ...args);
     }
-};
+};
+// Strip one symmetric outer quote layer
+const stripOne = (s) => {
+    if (s.length < 2)
+        return s;
+    const a = s.charAt(0);
+    const b = s.charAt(s.length - 1);
+    const symmetric = (a === '"' && b === '"') || (a === "'" && b === "'");
+    return symmetric ? s.slice(1, -1) : s;
+};
+async function maybeRunAlias(cli, thisCommand, aliasKey, state) {
+    dbg('alias:maybe:start');
+    const raw = thisCommand.rawArgs ?? [];
+    const childNames = thisCommand.commands.flatMap((c) => [
+        c.name(),
+        ...c.aliases(),
+    ]);
+    const hasSub = childNames.some((n) => raw.includes(n));
+    const o = thisCommand.opts();
+    const val = o[aliasKey];
+    const provided = typeof val === 'string'
+        ? val.length > 0
+        : Array.isArray(val)
+            ? val.length > 0
+            : false;
+    if (!provided || hasSub) {
+        dbg('alias:maybe:skip', { provided, hasSub });
+        return; // not an alias-only invocation
+    }
+    if (state.handled) {
+        dbg('alias:maybe:already-handled');
+        return;
+    }
+    state.handled = true;
+    dbg('alias-only invocation detected');
+    // Merge CLI options and resolve dotenv context.
+    const { merged } = resolveCliOptions(o, baseGetDotenvCliOptions, process.env.getDotenvCliOptions);
+    const mergedBag = merged;
+    const logger = (mergedBag.logger ?? console);
+    const serviceOptions = getDotenvCliOptions2Options(mergedBag);
+    await cli.resolveAndLoad(serviceOptions);
+    // Normalize alias value
+    const joined = typeof val === 'string'
+        ? val
+        : Array.isArray(val)
+            ? val.map(String).join(' ')
+            : '';
+    const expanded = dotenvExpandFromProcessEnv(joined);
+    const input = mergedBag.expand === false
+        ? joined
+        : expanded !== undefined
+            ? expanded
+            : joined;
+    // Scripts: prefer well-formed records; tolerate absent/bad shapes
+    const maybeScripts = mergedBag.scripts;
+    const scripts = maybeScripts && typeof maybeScripts === 'object'
+        ? maybeScripts
+        : undefined;
+    const resolved = resolveCommand(scripts, input);
+    if (mergedBag.debug) {
+        logger.log('\n*** command ***\n', `'${resolved}'`);
+    }
+    // Round-trip CLI options for nested getdotenv invocations. Omit logger
+    // (functions/circulars) and guard JSON serialization to avoid hard failures.
+    const { logger: _omitLogger, ...envBag } = mergedBag;
+    let nestedBag;
+    try {
+        nestedBag = JSON.stringify(envBag);
+    }
+    catch {
+        nestedBag = undefined;
+    }
+    const underTests = process.env.GETDOTENV_TEST === '1' ||
+        typeof process.env.VITEST_WORKER_ID === 'string';
+    const forceExit = process.env.GETDOTENV_FORCE_EXIT === '1';
+    const capture = !underTests &&
+        (process.env.GETDOTENV_STDIO === 'pipe' ||
+            Boolean(mergedBag.capture));
+    dbg('run:start', {
+        capture,
+        shell: mergedBag.shell,
+    });
+    const ctx = cli.getCtx();
+    const dotenv = (ctx?.dotenv ?? {});
+    // Diagnostics: --trace [keys...]
+    const traceOpt = mergedBag.trace;
+    if (traceOpt) {
+        const parentKeys = Object.keys(process.env);
+        const dotenvKeys = Object.keys(dotenv);
+        const allKeys = Array.from(new Set([...parentKeys, ...dotenvKeys])).sort();
+        const keys = Array.isArray(traceOpt) ? traceOpt : allKeys;
+        const childEnvPreview = {
+            ...process.env,
+            ...dotenv,
+        };
+        for (const k of keys) {
+            const parent = process.env[k];
+            const dot = dotenv[k];
+            const final = childEnvPreview[k];
+            const origin = dot !== undefined
+                ? 'dotenv'
+                : parent !== undefined
+                    ? 'parent'
+                    : 'unset';
+            const redFlag = mergedBag.redact;
+            const redPatterns = mergedBag.redactPatterns;
+            const redOpts = {};
+            if (redFlag)
+                redOpts.redact = true;
+            if (redFlag && Array.isArray(redPatterns))
+                redOpts.redactPatterns = redPatterns;
+            const tripleBag = {};
+            if (parent !== undefined)
+                tripleBag.parent = parent;
+            if (dot !== undefined)
+                tripleBag.dotenv = dot;
+            if (final !== undefined)
+                tripleBag.final = final;
+            const triple = redactTriple(k, tripleBag, redOpts);
+            process.stderr.write(`[trace] key=${k} origin=${origin} parent=${triple.parent ?? ''} dotenv=${triple.dotenv ?? ''} final=${triple.final ?? ''}\n`);
+            const entOpts = {};
+            const warnEntropy = mergedBag.warnEntropy;
+            const entropyThreshold = mergedBag
+                .entropyThreshold;
+            const entropyMinLength = mergedBag
+                .entropyMinLength;
+            const entropyWhitelist = mergedBag.entropyWhitelist;
+            if (typeof warnEntropy === 'boolean')
+                entOpts.warnEntropy = warnEntropy;
+            if (typeof entropyThreshold === 'number')
+                entOpts.entropyThreshold = entropyThreshold;
+            if (typeof entropyMinLength === 'number')
+                entOpts.entropyMinLength = entropyMinLength;
+            if (Array.isArray(entropyWhitelist))
+                entOpts.entropyWhitelist = entropyWhitelist;
+            maybeWarnEntropy(k, final, origin, entOpts, (line) => process.stderr.write(line + '\n'));
+        }
+    }
+    const shellSetting = resolveShell(scripts, input, mergedBag.shell);
+    // Preserve argv array for Node -e snippets under shell-off
+    let commandArg = resolved;
+    if (shellSetting === false && resolved === input) {
+        // Important: preserve doubled quotes within the Node -e payload so
+        // empty string literals ("") survive; Windows-style doubling must not
+        // collapse "" -> " in this path.
+        const parts = tokenize(input, { preserveDoubledQuotes: true });
+        if (parts.length >= 3 &&
+            parts[0]?.toLowerCase() === 'node' &&
+            (parts[1] === '-e' || parts[1] === '--eval')) {
+            // Peel exactly one symmetric outer quote on the code arg
+            parts[2] = stripOne(parts[2] ?? '');
+            // Historical behavior: pass the argv array through unchanged for shell-off.
+            commandArg = parts;
+        }
+    }
+    let exitCode = Number.NaN;
+    try {
+        exitCode = await runCommand(commandArg, shellSetting, {
+            env: buildSpawnEnv(process.env, nestedBag
+                ? {
+                    ...dotenv,
+                    getDotenvCliOptions: nestedBag,
+                }
+                : {
+                    ...dotenv,
+                }),
+            stdio: capture ? 'pipe' : 'inherit',
+        });
+        dbg('run:done', { exitCode });
+    }
+    catch (err) {
+        const code = typeof err.exitCode === 'number'
+            ? err.exitCode
+            : 1;
+        dbg('run:error', { exitCode: code, error: String(err) });
+        if (!underTests) {
+            dbg('process.exit (error path)', { exitCode: code });
+            process.exit(code);
+        }
+        else {
+            dbg('process.exit suppressed for tests (error path)', {
+                exitCode: code,
+            });
+        }
+        return;
+    }
+    if (!Number.isNaN(exitCode)) {
+        dbg('process.exit', { exitCode });
+        process.exit(exitCode);
+    }
+    if (!underTests) {
+        dbg('process.exit (fallback: non-numeric exitCode)', { exitCode: 0 });
+        process.exit(0);
+    }
+    else {
+        dbg('process.exit (fallback suppressed for tests: non-numeric exitCode)', {
+            exitCode: 0,
+        });
+    }
+    if (forceExit) {
+        setImmediate(() => process.exit(Number.isNaN(exitCode) ? 0 : exitCode));
+    }
+}
+
 const attachParentAlias = (cli, options, _cmd) => {
     const aliasSpec = typeof options.optionAlias === 'string'
-        ? { flags: options.optionAlias, description: undefined, expand: true }
+        ? { flags: options.optionAlias, description: undefined}
         : options.optionAlias;
     if (!aliasSpec)
         return;
     const deriveKey = (flags) => {
-        dbg('install alias option', flags);
+        if (process.env.GETDOTENV_DEBUG) {
+            console.error('[getdotenv:alias] install alias option', flags);
+        }
         const long = flags.split(/[ ,|]+/).find((f) => f.startsWith('--')) ?? '--cmd';
         const name = long.replace(/^--/, '');
         return name.replace(/-([a-z])/g, (_m, c) => c.toUpperCase());
@@ -2913,256 +3409,24 @@ const attachParentAlias = (cli, options, _cmd) => {
     const desc = aliasSpec.description ??
         'alias of cmd subcommand; provide command tokens (variadic)';
     cli.option(aliasSpec.flags, desc);
-    // Tag the just-added parent option for grouped help rendering.
-    try {
-        const optsArr = cli.options;
-        if (Array.isArray(optsArr) && optsArr.length > 0) {
-            const last = optsArr[optsArr.length - 1];
-            last.__group = 'plugin:cmd';
-        }
-    }
-    catch {
-        /* noop */
+    // Tag the just-added parent option for grouped help rendering at the root.
+    const optsArr = cli.options;
+    if (optsArr.length > 0) {
+        const last = optsArr[optsArr.length - 1];
+        if (last)
+            cli.setOptionGroup(last, 'plugin:cmd');
     }
     // Shared alias executor for either preAction or preSubcommand hooks.
     // Ensure we only execute once even if both hooks fire in a single parse.
-    let aliasHandled = false;
-    const maybeRunAlias = async (thisCommand) => {
-        dbg('alias:maybe:start');
-        const raw = thisCommand.rawArgs ?? [];
-        const childNames = thisCommand.commands.flatMap((c) => [
-            c.name(),
-            ...c.aliases(),
-        ]);
-        const hasSub = childNames.some((n) => raw.includes(n));
-        // Read alias value from parent opts.
-        const o = thisCommand.opts();
-        const val = o[aliasKey];
-        const provided = typeof val === 'string'
-            ? val.length > 0
-            : Array.isArray(val)
-                ? val.length > 0
-                : false;
-        if (!provided || hasSub) {
-            dbg('alias:maybe:skip', { provided, hasSub });
-            return; // not an alias-only invocation
-        }
-        if (aliasHandled) {
-            dbg('alias:maybe:already-handled');
-            return;
-        }
-        aliasHandled = true;
-        dbg('alias-only invocation detected');
-        // Merge CLI options and resolve dotenv context.
-        const { merged } = resolveCliOptions(o, 
-        // cast through unknown to avoid readonly -> mutable incompatibilities
-        baseRootOptionDefaults, process.env.getDotenvCliOptions);
-        const logger = merged.logger ?? console;
-        const serviceOptions = getDotenvCliOptions2Options(merged);
-        await cli.resolveAndLoad(serviceOptions);
-        // Normalize alias value.
-        const joined = typeof val === 'string'
-            ? val
-            : Array.isArray(val)
-                ? val.map(String).join(' ')
-                : '';
-        const input = aliasSpec.expand === false
-            ? joined
-            : (dotenvExpandFromProcessEnv(joined) ?? joined);
-        dbg('resolved input', { input });
-        const resolved = resolveCommand(merged.scripts, input);
-        const lg = logger;
-        if (merged.debug) {
-            (lg.debug ?? lg.log)('\n*** command ***\n', `'${resolved}'`);
-        }
-        const { logger: _omit, ...envBag } = merged;
-        // Test guard: when running under tests, prefer stdio: 'inherit' to avoid
-        // assertions depending on captured stdio; ignore GETDOTENV_STDIO/capture.
-        const underTests = process.env.GETDOTENV_TEST === '1' ||
-            typeof process.env.VITEST_WORKER_ID === 'string';
-        const forceExit = process.env.GETDOTENV_FORCE_EXIT === '1';
-        const capture = !underTests &&
-            (process.env.GETDOTENV_STDIO === 'pipe' ||
-                Boolean(merged.capture));
-        dbg('run:start', { capture, shell: merged.shell });
-        // Prefer explicit env injection: include resolved dotenv map to avoid leaking
-        // parent process.env secrets when exclusions are set.
-        const ctx = cli.getCtx();
-        const dotenv = (ctx?.dotenv ?? {});
-        // Diagnostics: --trace [keys...]
-        const traceOpt = merged.trace;
-        if (traceOpt) {
-            const parentKeys = Object.keys(process.env);
-            const dotenvKeys = Object.keys(dotenv);
-            const allKeys = Array.from(new Set([...parentKeys, ...dotenvKeys])).sort();
-            const keys = Array.isArray(traceOpt) ? traceOpt : allKeys;
-            const childEnvPreview = {
-                ...process.env,
-                ...dotenv,
-            };
-            for (const k of keys) {
-                const parent = process.env[k];
-                const dot = dotenv[k];
-                const final = childEnvPreview[k];
-                const origin = dot !== undefined
-                    ? 'dotenv'
-                    : parent !== undefined
-                        ? 'parent'
-                        : 'unset';
-                // Build redact options and triple bag without undefined-valued fields
-                const redOpts = {};
-                const redFlag = merged.redact;
-                const redPatterns = merged
-                    .redactPatterns;
-                if (redFlag)
-                    redOpts.redact = true;
-                if (redFlag && Array.isArray(redPatterns))
-                    redOpts.redactPatterns = redPatterns;
-                const tripleBag = {};
-                if (parent !== undefined)
-                    tripleBag.parent = parent;
-                if (dot !== undefined)
-                    tripleBag.dotenv = dot;
-                if (final !== undefined)
-                    tripleBag.final = final;
-                const triple = redactTriple(k, tripleBag, redOpts);
-                process.stderr.write(`[trace] key=${k} origin=${origin} parent=${triple.parent ?? ''} dotenv=${triple.dotenv ?? ''} final=${triple.final ?? ''}\n`);
-                const entOpts = {};
-                const warnEntropy = merged.warnEntropy;
-                const entropyThreshold = merged
-                    .entropyThreshold;
-                const entropyMinLength = merged
-                    .entropyMinLength;
-                const entropyWhitelist = merged
-                    .entropyWhitelist;
-                if (typeof warnEntropy === 'boolean')
-                    entOpts.warnEntropy = warnEntropy;
-                if (typeof entropyThreshold === 'number')
-                    entOpts.entropyThreshold = entropyThreshold;
-                if (typeof entropyMinLength === 'number')
-                    entOpts.entropyMinLength = entropyMinLength;
-                if (Array.isArray(entropyWhitelist))
-                    entOpts.entropyWhitelist = entropyWhitelist;
-                maybeWarnEntropy(k, final, origin, entOpts, (line) => process.stderr.write(line + '\n'));
-            }
-        }
-        let exitCode = Number.NaN;
-        try {
-            // Resolve shell and preserve argv for Node -e snippets under shell-off.
-            const shellSetting = resolveShell(merged.scripts, input, merged.shell);
-            let commandArg = resolved;
-            /**       * Special-case: when shell is OFF and no script alias remap occurred
-             * (resolved === input), treat a Node eval payload as an argv array to
-             * avoid lossy re-tokenization of the code string.
-             *
-             * Examples handled:
-             *   "node -e \"console.log(JSON.stringify(...))\""
-             *   "node --eval 'console.log(...)'"
-             *
-             * We peel exactly one pair of symmetric outer quotes from the code
-             * argument when present; inner quotes remain untouched.
-             */
-            if (shellSetting === false && resolved === input) {
-                // Helper: strip one symmetric outer quote layer
-                const stripOne = (s) => {
-                    if (s.length < 2)
-                        return s;
-                    const a = s.charAt(0);
-                    const b = s.charAt(s.length - 1);
-                    const symmetric = (a === '"' && b === '"') || (a === "'" && b === "'");
-                    return symmetric ? s.slice(1, -1) : s;
-                };
-                // Normalize whole input once for robust matching
-                const normalized = stripOne(input.trim());
-                // First try a lightweight regex on the normalized string
-                const m = /^\s*node\s+(--eval|-e)\s+([\s\S]+)$/i.exec(normalized);
-                if (m && typeof m[1] === 'string' && typeof m[2] === 'string') {
-                    const evalFlag = m[1];
-                    let codeArg = m[2].trim();
-                    codeArg = stripOne(codeArg);
-                    const flag = evalFlag.startsWith('--') ? '--eval' : '-e';
-                    commandArg = ['node', flag, codeArg];
-                }
-                else {
-                    // Fallback: tokenize and detect node -e/--eval form
-                    const parts = tokenize(input);
-                    if (parts.length >= 3) {
-                        // Narrow under noUncheckedIndexedAccess
-                        const p0 = parts[0];
-                        const p1 = parts[1];
-                        if (p0?.toLowerCase() === 'node' &&
-                            (p1 === '-e' || p1 === '--eval')) {
-                            commandArg = parts;
-                        }
-                    }
-                }
-            }
-            exitCode = await runCommand(commandArg, shellSetting, {
-                env: buildSpawnEnv(process.env, {
-                    ...dotenv,
-                    getDotenvCliOptions: JSON.stringify(envBag),
-                }),
-                stdio: capture ? 'pipe' : 'inherit',
-            });
-            dbg('run:done', { exitCode });
-        }
-        catch (err) {
-            const code = typeof err.exitCode === 'number'
-                ? err.exitCode
-                : 1;
-            dbg('run:error', { exitCode: code, error: String(err) });
-            if (!underTests) {
-                dbg('process.exit (error path)', { exitCode: code });
-                process.exit(code);
-            }
-            else {
-                dbg('process.exit suppressed for tests (error path)', {
-                    exitCode: code,
-                });
-            }
-            return;
-        }
-        if (!Number.isNaN(exitCode)) {
-            dbg('process.exit', { exitCode });
-            process.exit(exitCode);
-        }
-        // Fallback: Some environments may not surface a numeric exitCode even on success.
-        // Always terminate alias-only invocations outside tests to avoid hanging the process,
-        // regardless of capture/GETDOTENV_STDIO. Under tests, suppress to keep the runner alive.
-        if (!underTests) {
-            dbg('process.exit (fallback: non-numeric exitCode)', { exitCode: 0 });
-            process.exit(0);
-        }
-        else {
-            dbg('process.exit (fallback suppressed for tests: non-numeric exitCode)', { exitCode: 0 });
-        }
-        // Optional last-resort guard: force an exit on the next tick when enabled.
-        // Intended for diagnosing environments where the process appears to linger
-        // despite reaching the success/error handlers above. Disabled under tests.
-        if (forceExit) {
-            try {
-                if (process.env.GETDOTENV_DEBUG_VERBOSE) {
-                    const getHandles = process._getActiveHandles;
-                    const handles = typeof getHandles === 'function' ? getHandles() : [];
-                    dbg('active handles before forced exit', {
-                        count: Array.isArray(handles) ? handles.length : undefined,
-                    });
-                }
-            }
-            catch {
-                // best-effort only
-            }
-            const code = Number.isNaN(exitCode) ? 0 : exitCode;
-            dbg('process.exit (forced)', { exitCode: code });
-            setImmediate(() => process.exit(code));
-        }
+    const aliasState = { handled: false };
+    const maybeRun = async (thisCommand) => {
+        await maybeRunAlias(cli, thisCommand, aliasKey, aliasState);
     };
-    // Execute alias-only invocations whether the root handles the action  // itself (preAction) or Commander routes to a default subcommand (preSubcommand).
     cli.hook('preAction', async (thisCommand, _actionCommand) => {
-        await maybeRunAlias(thisCommand);
+        await maybeRun(thisCommand);
     });
     cli.hook('preSubcommand', async (thisCommand) => {
-        await maybeRunAlias(thisCommand);
+        await maybeRun(thisCommand);
     });
 };
 
@@ -3184,10 +3448,10 @@ const cmdPlugin = (options = {}) => definePlugin({
             return name.replace(/-([a-z])/g, (_m, c) => c.toUpperCase());
         };
         const aliasKey = aliasSpec ? deriveKey(aliasSpec.flags) : undefined;
-        const cmd = new Command()
-            .name('cmd')
+        // Create as a GetDotenvCli child so helpInformation includes a trailing blank line.
+        const cmd = cli
+            .createCommand('cmd')
             .description('Execute command according to the --shell option, conflicts with --command option (default subcommand)')
-            .configureHelp({ showGlobalOptions: true })
             .enablePositionalOptions()
             .passThroughOptions()
             .argument('[command...]')
@@ -3258,8 +3522,7 @@ const cmdPlugin = (options = {}) => definePlugin({
                             : 'unset';
                     // Apply presentation-time redaction (if enabled)
                     const redFlag = merged.redact;
-                    const redPatterns = merged
-                        .redactPatterns;
+                    const redPatterns = merged.redactPatterns;
                     const redOpts = {};
                     if (redFlag)
                         redOpts.redact = true;
@@ -3376,10 +3639,9 @@ const demoPlugin = () => definePlugin({
             // Build a minimal node -e payload via argv array (avoid quoting issues).
             const code = `console.log(process.env.${key} ?? "")`;
             const ctx = cli.getCtx();
-            const dotenv = (ctx?.dotenv ?? {});
             // Inherit stdio for an interactive demo. Use --capture for CI.
             await runCommand(['node', '-e', code], false, {
-                env: { ...process.env, ...dotenv },
+                env: buildSpawnEnv(process.env, ctx?.dotenv),
                 stdio: 'inherit',
             });
         });
@@ -3414,22 +3676,24 @@ const demoPlugin = () => definePlugin({
             const shell = resolveShell(bag?.scripts, input, bag?.shell);
             // Compose child env (parent + ctx.dotenv). This mirrors cmd/batch behavior.
             const ctx = cli.getCtx();
-            const dotenv = (ctx?.dotenv ?? {});
             await runCommand(resolved, shell, {
-                env: { ...process.env, ...dotenv },
+                env: buildSpawnEnv(process.env, ctx?.dotenv),
                 stdio: 'inherit',
             });
         });
     },
     /**
      * Optional: afterResolve can initialize per-plugin state using ctx.dotenv.
-     * For the demo we just log once to hint where such logic would live.
+     * For the demo we emit a single breadcrumb only when GETDOTENV_DEBUG is set,
+     * keeping default runs (tests/CI/smoke) quiet.
      */
     afterResolve(_cli, ctx) {
-        const keys = Object.keys(ctx.dotenv);
-        if (keys.length > 0) {
-            // Keep noise low; a single-line breadcrumb is sufficient for the demo.
-            console.error('[demo] afterResolve: dotenv keys loaded:', keys.length);
+        if (process.env.GETDOTENV_DEBUG) {
+            const keys = Object.keys(ctx.dotenv);
+            if (keys.length > 0) {
+                // Keep noise low; a single-line breadcrumb is sufficient for the demo.
+                console.error('[demo] afterResolve: dotenv keys loaded:', keys.length);
+            }
         }
     },
 });
@@ -3687,402 +3951,39 @@ const initPlugin = (opts = {}) => definePlugin({
     },
 });
 
-const cmdCommand$1 = new Command()
-    .name('cmd')
-    .description('execute command, conflicts with --command option (default subcommand)')
-    .enablePositionalOptions()
-    .passThroughOptions()
-    .argument('[command...]')
-    .action(async (commandParts, _options, thisCommand) => {
-    if (!thisCommand.parent)
-        throw new Error(`unable to resolve parent command`);
-    if (!thisCommand.parent.parent)
-        throw new Error(`unable to resolve root command`);
-    const { getDotenvCliOptions: { logger = console, ...getDotenvCliOptions }, } = thisCommand.parent.parent;
-    const raw = thisCommand.parent.opts();
-    const ignoreErrors = !!raw.ignoreErrors;
-    const globs = typeof raw.globs === 'string' ? raw.globs : '*';
-    const list = !!raw.list;
-    const pkgCwd = !!raw.pkgCwd;
-    const rootPath = typeof raw.rootPath === 'string' ? raw.rootPath : './';
-    // Execute command.
-    const args = Array.isArray(commandParts) ? commandParts : [];
-    // When no positional tokens are provided (e.g., option form `-c/--command`),
-    // the preSubcommand hook handles execution. Avoid a duplicate call here.
-    if (args.length === 0)
-        return;
-    const command = args.map(String).join(' ');
-    await execShellCommandBatch({
-        command: resolveCommand(getDotenvCliOptions.scripts, command),
-        getDotenvCliOptions,
-        globs,
-        ignoreErrors,
-        list,
-        logger,
-        pkgCwd,
-        rootPath,
-        // execa expects string | boolean | URL for `shell`. We normalize earlier;
-        // scripts[name].shell overrides take precedence and may be boolean or string.
-        shell: resolveShell(getDotenvCliOptions.scripts, command, getDotenvCliOptions.shell),
-    });
-});
-
-const batchCommand = new Command()
-    .name('batch')
-    .description('Batch command execution across multiple working directories.')
-    .enablePositionalOptions()
-    .passThroughOptions()
-    .option('-p, --pkg-cwd', 'use nearest package directory as current working directory')
-    .option('-r, --root-path <string>', 'path to batch root directory from current working directory', './')
-    .option('-g, --globs <string>', 'space-delimited globs from root path', '*')
-    .option('-c, --command <string>', 'command executed according to the base --shell option, conflicts with cmd subcommand (dotenv-expanded)', dotenvExpandFromProcessEnv)
-    .option('-l, --list', 'list working directories without executing command')
-    .option('-e, --ignore-errors', 'ignore errors and continue with next path')
-    .hook('preSubcommand', async (thisCommand) => {
-    if (!thisCommand.parent)
-        throw new Error(`unable to resolve root command`);
-    const { getDotenvCliOptions: { logger = console, ...getDotenvCliOptions }, } = thisCommand.parent;
-    const raw = thisCommand.opts();
-    const commandOpt = typeof raw.command === 'string' ? raw.command : undefined;
-    const ignoreErrors = !!raw.ignoreErrors;
-    const globs = typeof raw.globs === 'string' ? raw.globs : '*';
-    const list = !!raw.list;
-    const pkgCwd = !!raw.pkgCwd;
-    const rootPath = typeof raw.rootPath === 'string' ? raw.rootPath : './';
-    const argCount = thisCommand.args.length;
-    if (typeof commandOpt === 'string' && argCount > 0) {
-        logger.error(`--command option conflicts with cmd subcommand.`);
-        process.exit(0);
-    }
-    // Execute command.
-    if (typeof commandOpt === 'string')
-        await execShellCommandBatch({
-            command: resolveCommand(getDotenvCliOptions.scripts, commandOpt),
-            getDotenvCliOptions,
-            globs,
-            ignoreErrors,
-            list,
-            logger,
-            pkgCwd,
-            rootPath,
-            // execa expects string | boolean | URL for `shell`. We normalize earlier;
-            // scripts[name].shell overrides take precedence and may be boolean or string.
-            shell: resolveShell(getDotenvCliOptions.scripts, commandOpt, getDotenvCliOptions.shell),
-        });
-})
-    .addCommand(cmdCommand$1, { isDefault: true });
-
-const cmdCommand = new Command()
-    .name('cmd')
-    .description('Execute command according to the --shell option, conflicts with --command option (default subcommand)')
-    .configureHelp({ showGlobalOptions: true })
-    .enablePositionalOptions()
-    .passThroughOptions()
-    .argument('[command...]')
-    .action(async (commandParts, _options, thisCommand) => {
-    const args = Array.isArray(commandParts) ? commandParts : [];
-    if (args.length === 0)
-        return;
-    if (!thisCommand.parent)
-        throw new Error('parent command not found');
-    const { getDotenvCliOptions: { logger = console, ...getDotenvCliOptions }, } = thisCommand.parent;
-    const command = args.map(String).join(' ');
-    const cmd = resolveCommand(getDotenvCliOptions.scripts, command);
-    if (getDotenvCliOptions.debug)
-        logger.log('\n*** command ***\n', `'${cmd}'`);
-    await execaCommand(cmd, {
-        env: {
-            ...process.env,
-            getDotenvCliOptions: JSON.stringify(getDotenvCliOptions),
-        },
-        // execa expects string | boolean | URL; we normalize in generator
-        // and allow script-level overrides.
-        shell: resolveShell(getDotenvCliOptions.scripts, command, getDotenvCliOptions.shell),
-        stdio: 'inherit',
-    });
-});
-
-/**
- * Create the root Commander command with legacy root options (via cliCore)
- * and built-in subcommands. Pure builder: no side-effects; the caller attaches
- * lifecycle hooks separately.
- */
-const createRootCommand = (opts) => {
-    const program = new Command().name(opts.alias).description(opts.description);
-    // Attach legacy root flags using shared cliCore builder to keep parity.
-    attachRootOptions(program, opts, {
-        includeCommandOption: true,
-    });
-    // Subcommands
-    program.addCommand(batchCommand).addCommand(cmdCommand, { isDefault: true });
-    return program;
-};
-
-/**
- * Resolve `GetDotenvCliGenerateOptions` from `import.meta.url` and custom options.
- */
-const resolveGetDotenvCliGenerateOptions = async ({ importMetaUrl, ...customOptions }) => {
-    const baseOptions = {
-        ...baseGetDotenvCliOptions,
-        alias: 'getdotenv',
-        description: 'Base CLI.',
-    };
-    const globalPkgDir = importMetaUrl
-        ? await packageDirectory({
-            cwd: fileURLToPath(importMetaUrl),
-        })
-        : undefined;
-    const globalOptionsPath = globalPkgDir
-        ? join(globalPkgDir, getDotenvOptionsFilename)
-        : undefined;
-    const globalOptions = (globalOptionsPath && (await fs.exists(globalOptionsPath))
-        ? JSON.parse((await fs.readFile(globalOptionsPath)).toString())
-        : {});
-    const localPkgDir = await packageDirectory();
-    const localOptionsPath = localPkgDir
-        ? join(localPkgDir, getDotenvOptionsFilename)
-        : undefined;
-    const localOptions = (localOptionsPath &&
-        localOptionsPath !== globalOptionsPath &&
-        (await fs.exists(localOptionsPath))
-        ? JSON.parse((await fs.readFile(localOptionsPath)).toString())
-        : {});
-    // Merge order: base < global < local < custom
-    const merged = defaultsDeep(baseOptions, globalOptions, localOptions, customOptions);
-    return merged;
-};
-
-/**
- * Resolve dotenv values using the config-loader/overlay path (always-on in
- * host/generator flows; no-op when no config files are present).
- *
- * Order:
- * 1) Compute base from files only (exclude dynamic; ignore programmatic vars).
- * 2) Discover packaged + project config sources and overlay onto base.
- * 3) Apply dynamics in order:
- *    programmatic dynamic \> config dynamic (packaged → project public → project local)
- *    \> file dynamicPath.
- * 4) Phase C interpolation of remaining string options (e.g., outputPath).
- * 5) Optionally write outputPath, log, and merge into process.env.
- */
-const resolveDotenvWithConfigLoader = async (validated) => {
-    // 1) Base from files, no dynamic, no programmatic vars
-    const base = await getDotenv({
-        ...validated,
-        // Build a pure base without side effects or logging.
-        excludeDynamic: true,
-        vars: {},
-        log: false,
-        loadProcess: false,
-        outputPath: undefined,
-    });
-    // 2) Discover config sources (packaged via this module's import.meta.url)
-    const sources = await resolveGetDotenvConfigSources(import.meta.url);
-    const dotenv = overlayEnv({
-        base,
-        env: validated.env ?? validated.defaultEnv,
-        configs: sources,
-        ...(validated.vars ? { programmaticVars: validated.vars } : {}),
-    });
-    // Helper to apply a dynamic map progressively.
-    const applyDynamic = (target, dynamic, env) => {
-        if (!dynamic)
-            return;
-        for (const key of Object.keys(dynamic)) {
-            const value = typeof dynamic[key] === 'function'
-                ? dynamic[key](target, env)
-                : dynamic[key];
-            Object.assign(target, { [key]: value });
-        }
-    };
-    // 3) Apply dynamics in order
-    applyDynamic(dotenv, validated.dynamic, validated.env ?? validated.defaultEnv);
-    applyDynamic(dotenv, (sources.packaged?.dynamic ?? undefined), validated.env ?? validated.defaultEnv);
-    applyDynamic(dotenv, (sources.project?.public?.dynamic ?? undefined), validated.env ?? validated.defaultEnv);
-    applyDynamic(dotenv, (sources.project?.local?.dynamic ?? undefined), validated.env ?? validated.defaultEnv);
-    // file dynamicPath (lowest)
-    if (validated.dynamicPath) {
-        const absDynamicPath = path.resolve(validated.dynamicPath);
-        try {
-            const dyn = await loadModuleDefault(absDynamicPath, 'getdotenv-dynamic-host');
-            applyDynamic(dotenv, dyn, validated.env ?? validated.defaultEnv);
-        }
-        catch {
-            throw new Error(`Unable to load dynamic from ${validated.dynamicPath}`);
-        }
-    }
-    // 4) Phase C: interpolate remaining string options (exclude bootstrap set).
-    // For now, interpolate outputPath only; bootstrap keys are excluded by design.
-    const envRef = { ...process.env, ...dotenv };
-    const outputPathInterpolated = typeof validated.outputPath === 'string'
-        ? interpolateDeep(validated.outputPath, envRef)
-        : undefined;
-    // 5) Output/log/process merge (use interpolated outputPath if present)
-    if (outputPathInterpolated) {
-        await fs.writeFile(outputPathInterpolated, Object.keys(dotenv).reduce((contents, key) => {
-            const value = dotenv[key] ?? '';
-            return `${contents}${key}=${value.includes('\n') ? `"${value}"` : value}\n`;
-        }, ''), { encoding: 'utf-8' });
-    }
-    const logger = validated.logger ?? console;
-    if (validated.log) {
-        const redactFlag = validated.redact ?? false;
-        const redactPatterns = validated.redactPatterns;
-        const redOpts = {};
-        if (redactFlag)
-            redOpts.redact = true;
-        if (redactFlag && Array.isArray(redactPatterns))
-            redOpts.redactPatterns = redactPatterns;
-        const bag = redactFlag ? redactObject(dotenv, redOpts) : { ...dotenv };
-        logger.log(bag);
-        // Entropy warnings: once per key per run (presentation only)
-        const warnEntropyVal = validated.warnEntropy ?? true;
-        const entropyThresholdVal = validated.entropyThreshold;
-        const entropyMinLengthVal = validated.entropyMinLength;
-        const entropyWhitelistVal = validated.entropyWhitelist;
-        const entOpts = {};
-        // include keys only when defined to satisfy exactOptionalPropertyTypes
-        if (typeof warnEntropyVal === 'boolean')
-            entOpts.warnEntropy = warnEntropyVal;
-        if (typeof entropyThresholdVal === 'number')
-            entOpts.entropyThreshold = entropyThresholdVal;
-        if (typeof entropyMinLengthVal === 'number')
-            entOpts.entropyMinLength = entropyMinLengthVal;
-        if (Array.isArray(entropyWhitelistVal))
-            entOpts.entropyWhitelist = entropyWhitelistVal;
-        for (const [k, v] of Object.entries(dotenv)) {
-            maybeWarnEntropy(k, v, v !== undefined ? 'dotenv' : 'unset', entOpts, (line) => {
-                logger.log(line);
-            });
-        }
-    }
-    if (validated.loadProcess)
-        Object.assign(process.env, dotenv);
-    return dotenv;
-};
-
-/**
- * Omit a "logger" key from an options object in a typed manner.
- */
-const omitLogger = (obj) => {
-    const { logger: _omitted, ...rest } = obj;
-    return rest;
-};
-/**
- * Build the Commander preSubcommand hook using the provided context.
- * * Responsibilities:
- * - Merge parent CLI options with current invocation (parent \< current). * - Resolve tri-state flags, including `--exclude-all` overrides.
- * - Normalize the shell setting to a concrete value (string | boolean).
- * - Persist merged options on the command instance and pass to subcommands.
- * - Execute {@link getDotenv} and optional post-hook.
- * - Either forward to the default `cmd` subcommand or execute `--command`.
- *
- * @param context - See {@link PreSubHookContext}.
- * @returns An async hook suitable for Commander’s `preSubcommand`.
- *
- * @example `program.hook('preSubcommand', makePreSubcommandHook(ctx));`
- */
-const makePreSubcommandHook = ({ logger, preHook, postHook, defaults, }) => {
-    return async (thisCommand) => {
-        // Get raw CLI options from commander.
-        const rawCliOptions = thisCommand.opts();
-        const { merged: mergedGetDotenvCliOptions, command: commandOpt } = resolveCliOptions(rawCliOptions, defaults, process.env.getDotenvCliOptions);
-        // Optional debug logging retained via mergedGetDotenvCliOptions.debug if desired.    // Execute pre-hook.
-        if (preHook) {
-            await preHook(mergedGetDotenvCliOptions);
-            if (mergedGetDotenvCliOptions.debug)
-                logger.debug('\n*** GetDotenvCliOptions after pre-hook ***\n', mergedGetDotenvCliOptions);
-        }
-        // Persist GetDotenvCliOptions in command for subcommand access.
-        thisCommand.getDotenvCliOptions =
-            mergedGetDotenvCliOptions;
-        // Execute getdotenv via always-on config loader/overlay path.
-        const serviceOptions = getDotenvCliOptions2Options(mergedGetDotenvCliOptions);
-        const dotenv = await resolveDotenvWithConfigLoader(serviceOptions);
-        // Global validation against config (warn by default; --strict fails).
-        try {
-            const sources = await resolveGetDotenvConfigSources(import.meta.url);
-            const issues = validateEnvAgainstSources(dotenv, sources);
-            if (Array.isArray(issues) && issues.length > 0) {
-                issues.forEach((m) => {
-                    logger.error(m);
-                });
-                if (mergedGetDotenvCliOptions.strict) {
-                    process.exit(1);
-                }
-            }
-        }
-        catch {
-            // Tolerate validator failures in non-strict mode
-        }
-        // Execute post-hook.
-        if (postHook)
-            await postHook(dotenv); // Execute command.
-        const args = thisCommand.args ?? [];
-        const isCommand = typeof commandOpt === 'string' && commandOpt.length > 0;
-        if (isCommand && args.length > 0) {
-            const lr = logger;
-            (lr.error ?? lr.log)(`--command option conflicts with cmd subcommand.`);
-            process.exit(0);
-        }
-        if (typeof commandOpt === 'string' && commandOpt.length > 0) {
-            const cmd = resolveCommand(mergedGetDotenvCliOptions.scripts, commandOpt);
-            if (mergedGetDotenvCliOptions.debug)
-                logger.debug('\n*** command ***\n', cmd);
-            // Build a logger-free bag for env round-trip.
-            const envSafe = omitLogger(mergedGetDotenvCliOptions);
-            await execaCommand(cmd, {
-                env: { ...process.env, getDotenvCliOptions: JSON.stringify(envSafe) },
-                shell: resolveShell(mergedGetDotenvCliOptions.scripts, commandOpt, mergedGetDotenvCliOptions.shell),
-                stdio: 'inherit',
-            });
-        }
-    };
-};
-
-/**
- * Generate a Commander CLI Command for get-dotenv.
- * Orchestration only: delegates building and lifecycle hooks.
- */
-const generateGetDotenvCli = async (customOptions) => {
-    const options = await resolveGetDotenvCliGenerateOptions(customOptions);
-    const program = createRootCommand(options);
-    const defaults = {};
-    if (options.debug !== undefined)
-        defaults.debug = options.debug;
-    if (options.excludeDynamic !== undefined)
-        defaults.excludeDynamic = options.excludeDynamic;
-    if (options.excludeEnv !== undefined)
-        defaults.excludeEnv = options.excludeEnv;
-    if (options.excludeGlobal !== undefined)
-        defaults.excludeGlobal = options.excludeGlobal;
-    if (options.excludePrivate !== undefined)
-        defaults.excludePrivate = options.excludePrivate;
-    if (options.excludePublic !== undefined)
-        defaults.excludePublic = options.excludePublic;
-    if (options.loadProcess !== undefined)
-        defaults.loadProcess = options.loadProcess;
-    if (options.log !== undefined)
-        defaults.log = options.log;
-    if (options.scripts !== undefined)
-        defaults.scripts = options.scripts;
-    if (options.shell !== undefined)
-        defaults.shell = options.shell;
-    const ctx = {
-        logger: options.logger,
-        defaults,
-        ...(options.preHook ? { preHook: options.preHook } : {}),
-        ...(options.postHook ? { postHook: options.postHook } : {}),
-    };
-    program.hook('preSubcommand', makePreSubcommandHook(ctx));
-    return program;
-};
-
 function createCli(opts = {}) {
     const alias = typeof opts.alias === 'string' && opts.alias.length > 0
         ? opts.alias
         : 'getdotenv';
     const program = new GetDotenvCli(alias);
+    // Normalize Commander output so help prints always end with a blank line.
+    // This keeps E2E assertions (CRLF and >=2 trailing newlines) portable across
+    // runtimes and capture modes without altering Commander internals.
+    const outputCfg = {
+        writeOut(str) {
+            const txt = typeof str === 'string' ? str : '';
+            const hasTwo = /(?:\r?\n){2,}$/.test(txt);
+            const hasOne = /\r?\n$/.test(txt);
+            const out = hasTwo ? txt : hasOne ? txt + '\n' : txt + '\n\n';
+            try {
+                process.stdout.write(out);
+            }
+            catch {
+                /* ignore */
+            }
+        },
+        writeErr(str) {
+            process.stderr.write(str);
+        },
+    };
+    // Apply to root and recursively to subcommands so all help paths are normalized.
+    program.configureOutput(outputCfg);
+    const applyOutputRecursively = (cmd) => {
+        cmd.configureOutput(outputCfg);
+        for (const child of cmd.commands)
+            applyOutputRecursively(child);
+    };
+    applyOutputRecursively(program);
     // Install base root flags and included plugins; resolve context once per run.
     program
         .attachRootOptions({ loadProcess: false })
@@ -4098,19 +3999,68 @@ function createCli(opts = {}) {
     if (underTests) {
         program.exitOverride((err) => {
             const code = err?.code;
-            if (code === 'commander.helpDisplayed' || code === 'commander.version')
+            // Commander printed help already; ensure a trailing blank line for tests/CI capture.
+            if (code === 'commander.helpDisplayed') {
+                try {
+                    process.stdout.write('\n');
+                }
+                catch {
+                    /* ignore */
+                }
                 return;
+            }
+            if (code === 'commander.version') {
+                return;
+            }
             throw err;
         });
     }
     return {
         async run(argv) {
-            // Always short-circuit help to avoid Commander-triggered process.exit
-            // across environments (CJS/ESM) and to return immediately under dynamic
-            // ESM without performing extra IO. Prints help and returns.
-            if (argv.some((a) => a === '-h' || a === '--help')) {
-                program.outputHelp();
-                return;
+            // Help handling:
+            // - Short-circuit ONLY for true top-level -h/--help (no subcommand before flag).
+            // - If a subcommand token appears before -h/--help, defer to Commander
+            //   to render that subcommand's help.
+            const helpIdx = argv.findIndex((a) => a === '-h' || a === '--help');
+            if (helpIdx >= 0) {
+                // Build a set of known subcommand names/aliases on the root.
+                const subs = new Set();
+                for (const c of program.commands) {
+                    subs.add(c.name());
+                    for (const a of c.aliases())
+                        subs.add(a);
+                }
+                const hasSubBeforeHelp = argv
+                    .slice(0, helpIdx)
+                    .some((tok) => subs.has(tok));
+                if (!hasSubBeforeHelp) {
+                    await program.brand({
+                        name: alias,
+                        importMetaUrl: import.meta.url,
+                        description: 'Base CLI.',
+                        ...(typeof opts.branding === 'string' && opts.branding.length > 0
+                            ? { helpHeader: opts.branding }
+                            : {}),
+                    });
+                    // Resolve context once without side effects for help rendering.
+                    const ctx = await program.resolveAndLoad({
+                        loadProcess: false,
+                        log: false,
+                    }, { runAfterResolve: false });
+                    // Build a defaults-only merged CLI bag for help-time parity (no side effects).
+                    const { merged: defaultsMerged } = resolveCliOptions({}, baseRootOptionDefaults, undefined);
+                    const helpCfg = toHelpConfig(defaultsMerged, ctx.pluginConfigs ?? {});
+                    program.evaluateDynamicOptions(helpCfg);
+                    // Suppress output only during unit tests; allow E2E to capture.
+                    const piping = process.env.GETDOTENV_STDIO === 'pipe' ||
+                        process.env.GETDOTENV_STDOUT === 'pipe';
+                    if (!(underTests && !piping)) {
+                        program.outputHelp();
+                    }
+                    return;
+                }
+                // Subcommand token exists before -h: fall through to normal parsing,
+                // letting Commander print that subcommand's help.
             }
             await program.brand({
                 name: alias,
@@ -4125,4 +4075,4 @@ function createCli(opts = {}) {
     };
 }
 
-export { buildSpawnEnv, createCli, defineDynamic, dotenvExpand, dotenvExpandAll, dotenvExpandFromProcessEnv, generateGetDotenvCli, getDotenv, getDotenvCliOptions2Options, interpolateDeep };
+export { GetDotenvCli, buildSpawnEnv, createCli, defineDynamic, defineGetDotenvConfig, definePlugin, defineScripts, dotenvExpand, dotenvExpandAll, dotenvExpandFromProcessEnv, getDotenv, getDotenvCliOptions2Options, interpolateDeep, readMergedOptions };