@karmaniverous/get-dotenv 5.2.6 → 6.0.0-1

package/dist/plugins-cmd.mjs

@@ -1,25 +1,43 @@
-import { Command } from 'commander';
 import { execa, execaCommand } from 'execa';
+import { z } from 'zod';
 import 'fs-extra';
-import 'package-directory';
 import 'path';
+import 'package-directory';
+import 'url';
+import 'yaml';
+import 'nanoid';
+import 'dotenv';
+import 'crypto';
 
 // 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
@@ -74,6 +92,17 @@ const stripOuterQuotes = (s) => {
     }
     return out;
 };
+// Extract exitCode/stdout/stderr from execa result or error in a tolerant way.
+const pickResult = (r) => {
+    const exit = r.exitCode;
+    const stdoutVal = r.stdout;
+    const stderrVal = r.stderr;
+    return {
+        exitCode: typeof exit === 'number' ? exit : Number.NaN,
+        stdout: typeof stdoutVal === 'string' ? stdoutVal : '',
+        stderr: typeof stderrVal === 'string' ? stderrVal : '',
+    };
+};
 // Convert NodeJS.ProcessEnv (string | undefined values) to the shape execa
 // expects (Readonly<Partial<Record<string, string>>>), dropping undefineds.
 const sanitizeEnv = (env) => {
@@ -82,19 +111,19 @@ const sanitizeEnv = (env) => {
     const entries = Object.entries(env).filter((e) => typeof e[1] === 'string');
     return entries.length > 0 ? Object.fromEntries(entries) : undefined;
 };
-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 });
@@ -107,16 +136,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,
@@ -130,17 +158,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) => {
@@ -183,33 +223,145 @@ const buildSpawnEnv = (base, overlay) => {
     return out;
 };
 
-/** src/cliHost/definePlugin.ts
- * Plugin contracts for the GetDotenv CLI host.
+/**
+ * Zod schemas for configuration files discovered by the new loader.
  *
- * This module exposes a structural public interface for the host that plugins
- * should use (GetDotenvCliPublic). Using a structural type at the seam avoids
- * nominal class identity issues (private fields) in downstream consumers.
+ * Notes:
+ * - RAW: all fields optional; shapes are stringly-friendly (paths may be string[] or string).
+ * - RESOLVED: normalized shapes (paths always string[]).
+ * - For JSON/YAML configs, the loader rejects "dynamic" and "schema" (JS/TS-only).
  */
+// String-only env value map
+const stringMap = z.record(z.string(), z.string());
+const envStringMap = z.record(z.string(), stringMap);
+// Allow string[] or single string for "paths" in RAW; normalize later.
+const rawPathsSchema = z.union([z.array(z.string()), z.string()]).optional();
+const getDotenvConfigSchemaRaw = z.object({
+    dotenvToken: z.string().optional(),
+    privateToken: z.string().optional(),
+    paths: rawPathsSchema,
+    loadProcess: z.boolean().optional(),
+    log: z.boolean().optional(),
+    shell: z.union([z.string(), z.boolean()]).optional(),
+    scripts: z.record(z.string(), z.unknown()).optional(), // Scripts validation left wide; generator validates elsewhere
+    requiredKeys: z.array(z.string()).optional(),
+    schema: z.unknown().optional(), // JS/TS-only; loader rejects in JSON/YAML
+    vars: stringMap.optional(), // public, global
+    envVars: envStringMap.optional(), // public, per-env
+    // Dynamic in config (JS/TS only). JSON/YAML loader will reject if set.
+    dynamic: z.unknown().optional(),
+    // Per-plugin config bag; validated by plugins/host when used.
+    plugins: z.record(z.string(), z.unknown()).optional(),
+});
+// Normalize paths to string[]
+const normalizePaths = (p) => p === undefined ? undefined : Array.isArray(p) ? p : [p];
+getDotenvConfigSchemaRaw.transform((raw) => ({
+    ...raw,
+    paths: normalizePaths(raw.paths),
+}));
+
 /**
- * Define a GetDotenv CLI plugin with compositional helpers.
+ * 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
- * const parent = definePlugin(\{ id: 'p', setup(cli) \{ /* ... *\/ \} \})
- *   .use(childA)
- *   .use(childB);
+ * ```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 definePlugin = (spec) => {
-    const { children = [], ...rest } = spec;
-    const plugin = {
-        ...rest,
-        children: [...children],
-        use(child) {
-            this.children.push(child);
-            return this;
-        },
-    };
-    return plugin;
+const dotenvExpand = (value, ref = process.env) => {
+    const result = interpolate(value, ref);
+    return result ? result.replace(/\\\$/g, '$') : undefined;
 };
+/**
+ * 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);
 
 /** src/diagnostics/entropy.ts
  * Entropy diagnostics (presentation-only).
@@ -219,7 +371,7 @@ const definePlugin = (spec) => {
  */
 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();
@@ -266,7 +418,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]';
 /**
@@ -291,34 +443,6 @@ const redactTriple = (key, triple, opts) => {
     return out;
 };
 
-/**
- * Batch services (neutral): resolve command and shell settings.
- * Shared by the generator path and the batch plugin to avoid circular deps.
- */
-/**
- * Resolve a command string from the {@link Scripts} table.
- * A script may be expressed as a string or an object with a `cmd` property.
- *
- * @param scripts - Optional scripts table.
- * @param command - User-provided command name or string.
- * @returns Resolved command string (falls back to the provided command).
- */
-const resolveCommand = (scripts, command) => scripts && typeof scripts[command] === 'object'
-    ? scripts[command].cmd
-    : (scripts?.[command] ?? command);
-/**
- * Resolve the shell setting for a given command:
- * - If the script entry is an object, prefer its `shell` override.
- * - Otherwise use the provided `shell` (string | boolean).
- *
- * @param scripts - Optional scripts table.
- * @param command - User-provided command name or string.
- * @param shell - Global shell preference (string | boolean).
- */
-const resolveShell = (scripts, command, shell) => scripts && typeof scripts[command] === 'object'
-    ? (scripts[command].shell ?? false)
-    : (shell ?? false);
-
 // Base root CLI defaults (shared; kept untyped here to avoid cross-layer deps).
 const baseRootOptionDefaults = {
     dotenvToken: '.env',
@@ -346,6 +470,8 @@ const baseRootOptionDefaults = {
     // (debug/log/exclude* resolved via flag utils)
 };
 
+const baseGetDotenvCliOptions = baseRootOptionDefaults;
+
 /** @internal */
 const isPlainObject = (value) => value !== null &&
     typeof value === 'object' &&
@@ -367,27 +493,223 @@ 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;
+}
+
+/** 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.
+ */
+/**
+ * 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
+/**
+ * Canonical programmatic options and helpers for get-dotenv.
+ *
+ * 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.
+ */
+/**
+ * Converts programmatic CLI options to `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, 
+// 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
+            ? RegExp(varsAssignorPattern)
+            : (varsAssignor ?? '=')))
+            .filter(([k]) => typeof k === 'string' && k.length > 0);
+        parsedVars = Object.fromEntries(kvPairs);
+    }
+    else if (vars && typeof vars === 'object' && !Array.isArray(vars)) {
+        // 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 = omitUndefinedRecord(parsedVars);
+    }
+    // Tolerate paths as either a delimited string or string[]
+    const pathsOut = Array.isArray(paths)
+        ? paths.filter((p) => typeof p === 'string')
+        : splitBy(paths, pathsDelimiter, pathsDelimiterPattern);
+    // Preserve exactOptionalPropertyTypes: only include keys when defined.
+    return {
+        ...rest,
+        ...(pathsOut.length > 0 ? { paths: pathsOut } : {}),
+        ...(parsedVars !== undefined ? { vars: parsedVars } : {}),
+    };
 };
 
+/**
+ * Zod schemas for programmatic GetDotenv options.
+ *
+ * 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());
+// RAW: all fields optional — undefined means "inherit" from lower layers.
+z.object({
+    defaultEnv: z.string().optional(),
+    dotenvToken: z.string().optional(),
+    dynamicPath: z.string().optional(),
+    // Dynamic map is intentionally wide for now; refine once sources are normalized.
+    dynamic: z.record(z.string(), z.unknown()).optional(),
+    env: z.string().optional(),
+    excludeDynamic: z.boolean().optional(),
+    excludeEnv: z.boolean().optional(),
+    excludeGlobal: z.boolean().optional(),
+    excludePrivate: z.boolean().optional(),
+    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(),
+});
+
+/**
+ * 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 _getPluginConfigForInstance = (plugin) => PLUGIN_CONFIG_STORE.get(plugin);
+
+/** src/cliHost/definePlugin.ts
+ * Plugin contracts for the GetDotenv CLI host.
+ *
+ * This module exposes a structural public interface for the host that plugins
+ * should use (GetDotenvCliPublic). Using a structural type at the seam avoids
+ * nominal class identity issues (private fields) in downstream consumers.
+ */
+/* eslint-disable tsdoc/syntax */
+function definePlugin(spec) {
+    const { children = [], ...rest } = spec;
+    // 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;
+        },
+    };
+    // 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;
+}
+
+/**
+ * Batch services (neutral): resolve command and shell settings.
+ * Shared by the generator path and the batch plugin to avoid circular deps.
+ */
+/**
+ * Resolve a command string from the {@link Scripts} table.
+ * A script may be expressed as a string or an object with a `cmd` property.
+ *
+ * @param scripts - Optional scripts table.
+ * @param command - User-provided command name or string.
+ * @returns Resolved command string (falls back to the provided command).
+ */
+const resolveCommand = (scripts, command) => scripts && typeof scripts[command] === 'object'
+    ? scripts[command].cmd
+    : (scripts?.[command] ?? command);
+/**
+ * Resolve the shell setting for a given command:
+ * - If the script entry is an object, prefer its `shell` override.
+ * - Otherwise use the provided `shell` (string | boolean).
+ *
+ * @param scripts - Optional scripts table.
+ * @param command - User-provided command name or string.
+ * @param shell - Global shell preference (string | boolean).
+ */
+const resolveShell = (scripts, command, shell) => scripts && typeof scripts[command] === 'object'
+    ? (scripts[command].shell ?? false)
+    : (shell ?? false);
+
 /**
  * Resolve a tri-state optional boolean flag under exactOptionalPropertyTypes.
  * - If the user explicitly enabled the flag, return true.
@@ -513,180 +835,225 @@ const resolveCliOptions = (rawCliOptions, defaults, parentJson) => {
     return cmd !== undefined ? { merged, command: cmd } : { merged };
 };
 
-/**
- * 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);
+const dbg = (...args) => {
+    if (process.env.GETDOTENV_DEBUG) {
+        // Use stderr to avoid interfering with stdout assertions
+        console.error('[getdotenv:alias]', ...args);
     }
-    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;
+// 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;
 };
-/**
- * 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);
-
-// src/GetDotenvOptions.ts
-/**
- * Converts programmatic CLI options to `getDotenv` options. *
- * @param cliOptions - CLI options. Defaults to `{}`.
- *
- * @returns `getDotenv` options.
- */
-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 ?? ' ')) : []);
-    // 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
-            ? RegExp(varsAssignorPattern)
-            : (varsAssignor ?? '=')));
-        parsedVars = Object.fromEntries(kvPairs);
+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
     }
-    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);
+    if (state.handled) {
+        dbg('alias:maybe:already-handled');
+        return;
     }
-    // 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));
+    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}'`);
     }
-    // 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);
-    // Preserve exactOptionalPropertyTypes: only include keys when defined.
-    return {
-        ...restObj,
-        ...(pathsOut.length > 0 ? { paths: pathsOut } : {}),
-        ...(parsedVars !== undefined ? { vars: parsedVars } : {}),
-    };
-};
-
-const dbg = (...args) => {
-    if (process.env.GETDOTENV_DEBUG) {
-        // Use stderr to avoid interfering with stdout assertions
-        console.error('[getdotenv:alias]', ...args);
+    // 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());
@@ -696,256 +1063,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);
     });
 };
 
@@ -967,10 +1102,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...]')
@@ -1041,8 +1176,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;