@karmaniverous/get-dotenv 6.0.0-0 → 6.0.0

package/dist/plugins-cmd.cjs

@@ -1,1112 +0,0 @@
-'use strict';
-
-var execa = require('execa');
-require('fs-extra');
-require('package-directory');
-require('path');
-
-// Minimal tokenizer for shell-off execution:
-// Splits by whitespace while preserving quoted segments (single or double quotes).
-const tokenize = (command) => {
-    const out = [];
-    let cur = '';
-    let quote = null;
-    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 '' -> '
-                const next = command.charAt(i + 1);
-                if (next === quote) {
-                    cur += quote;
-                    i += 1; // skip the second quote
-                }
-                else {
-                    // end of quoted segment
-                    quote = null;
-                }
-            }
-            else {
-                cur += c;
-            }
-        }
-        else {
-            if (c === '"' || c === "'") {
-                quote = c;
-            }
-            else if (/\s/.test(c)) {
-                if (cur) {
-                    out.push(cur);
-                    cur = '';
-                }
-            }
-            else {
-                cur += c;
-            }
-        }
-    }
-    if (cur)
-        out.push(cur);
-    return out;
-};
-
-const dbg$1 = (...args) => {
-    if (process.env.GETDOTENV_DEBUG) {
-        // Use stderr to avoid interfering with stdout assertions
-        console.error('[getdotenv:run]', ...args);
-    }
-};
-// Strip repeated symmetric outer quotes (single or double) until stable.
-// This is safe for argv arrays passed to execa (no quoting needed) and avoids
-// passing quote characters through to Node (e.g., for `node -e "<code>"`).
-// Handles stacked quotes from shells like PowerShell: """code""" -> code.
-const stripOuterQuotes = (s) => {
-    let out = s;
-    // Repeatedly trim only when the entire string is wrapped in matching quotes.
-    // Stop as soon as the ends are asymmetric or no quotes remain.
-    while (out.length >= 2) {
-        const a = out.charAt(0);
-        const b = out.charAt(out.length - 1);
-        const symmetric = (a === '"' && b === '"') || (a === "'" && b === "'");
-        if (!symmetric)
-            break;
-        out = out.slice(1, -1);
-    }
-    return out;
-};
-// Convert NodeJS.ProcessEnv (string | undefined values) to the shape execa
-// expects (Readonly<Partial<Record<string, string>>>), dropping undefineds.
-const sanitizeEnv = (env) => {
-    if (!env)
-        return undefined;
-    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) => {
-    if (shell === false) {
-        let file;
-        let args = [];
-        if (Array.isArray(command)) {
-            file = command[0];
-            args = command.slice(1).map(stripOuterQuotes);
-        }
-        else {
-            const tokens = tokenize(command);
-            file = tokens[0];
-            args = tokens.slice(1);
-        }
-        if (!file)
-            return 0;
-        dbg$1('exec (plain)', { file, args, stdio: opts.stdio });
-        // Build options without injecting undefined properties (exactOptionalPropertyTypes).
-        const envSan = sanitizeEnv(opts.env);
-        const plainOpts = {};
-        if (opts.cwd !== undefined)
-            plainOpts.cwd = opts.cwd;
-        if (envSan !== undefined)
-            plainOpts.env = envSan;
-        if (opts.stdio !== undefined)
-            plainOpts.stdio = opts.stdio;
-        const result = await execa.execa(file, args, plainOpts);
-        if (opts.stdio === 'pipe' && result.stdout) {
-            process.stdout.write(result.stdout + (result.stdout.endsWith('\n') ? '' : '\n'));
-        }
-        const exit = result?.exitCode;
-        dbg$1('exit (plain)', { exitCode: exit });
-        return typeof exit === 'number' ? exit : Number.NaN;
-    }
-    else {
-        const commandStr = Array.isArray(command) ? command.join(' ') : command;
-        dbg$1('exec (shell)', {
-            shell: typeof shell === 'string' ? shell : 'custom',
-            stdio: opts.stdio,
-            command: commandStr,
-        });
-        const envSan = sanitizeEnv(opts.env);
-        const shellOpts = { shell };
-        if (opts.cwd !== undefined)
-            shellOpts.cwd = opts.cwd;
-        if (envSan !== undefined)
-            shellOpts.env = envSan;
-        if (opts.stdio !== undefined)
-            shellOpts.stdio = opts.stdio;
-        const result = await execa.execaCommand(commandStr, shellOpts);
-        const out = result?.stdout;
-        if (opts.stdio === 'pipe' && out) {
-            process.stdout.write(out + (out.endsWith('\n') ? '' : '\n'));
-        }
-        const exit = result?.exitCode;
-        dbg$1('exit (shell)', { exitCode: exit });
-        return typeof exit === 'number' ? exit : Number.NaN;
-    }
-};
-
-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) => {
-    const raw = {
-        ...(base ?? {}),
-        ...(overlay ?? {}),
-    };
-    // Drop undefined first
-    const entries = Object.entries(dropUndefined(raw));
-    if (process.platform === 'win32') {
-        // Windows: keys are case-insensitive; collapse duplicates
-        const byLower = new Map();
-        for (const [k, v] of entries) {
-            byLower.set(k.toLowerCase(), [k, v]); // last wins; preserve latest casing
-        }
-        const out = {};
-        for (const [, [k, v]] of byLower)
-            out[k] = v;
-        // HOME fallback from USERPROFILE (common expectation)
-        if (!Object.prototype.hasOwnProperty.call(out, 'HOME')) {
-            const up = out['USERPROFILE'];
-            if (typeof up === 'string' && up.length > 0)
-                out['HOME'] = up;
-        }
-        // Normalize TMP/TEMP coherence (pick any present; reflect to both)
-        const tmp = out['TMP'] ?? out['TEMP'];
-        if (typeof tmp === 'string' && tmp.length > 0) {
-            out['TMP'] = tmp;
-            out['TEMP'] = tmp;
-        }
-        return out;
-    }
-    // POSIX: keep keys as-is
-    const out = Object.fromEntries(entries);
-    // Ensure TMPDIR exists when any temp key is present (best-effort)
-    const tmpdir = out['TMPDIR'] ?? out['TMP'] ?? out['TEMP'];
-    if (typeof tmpdir === 'string' && tmpdir.length > 0) {
-        out['TMPDIR'] = tmpdir;
-    }
-    return out;
-};
-
-/** src/cliHost/definePlugin.ts
- * Plugin contracts for the GetDotenv CLI host.
- *
- * This module exposes a structural public interface for the host that plugins
- * should use (GetDotenvCliPublic). Using a structural type at the seam avoids
- * nominal class identity issues (private fields) in downstream consumers.
- */
-/**
- * Define a GetDotenv CLI plugin with compositional helpers.
- *
- * @example
- * const parent = definePlugin(\{ id: 'p', setup(cli) \{ /* ... *\/ \} \})
- *   .use(childA)
- *   .use(childB);
- */
-const definePlugin = (spec) => {
-    const { children = [], ...rest } = spec;
-    const plugin = {
-        ...rest,
-        children: [...children],
-        use(child) {
-            this.children.push(child);
-            return this;
-        },
-    };
-    return plugin;
-};
-
-/** src/diagnostics/entropy.ts
- * Entropy diagnostics (presentation-only).
- * - Gated by min length and printable ASCII.
- * - Warn once per key per run when bits/char \>= threshold.
- * - Supports whitelist patterns to suppress known-noise keys.
- */
-const warned = new Set();
-const isPrintableAscii = (s) => /^[\x20-\x7E]+$/.test(s);
-const compile$1 = (patterns) => (patterns ?? []).map((p) => new RegExp(p, 'i'));
-const whitelisted = (key, regs) => regs.some((re) => re.test(key));
-const shannonBitsPerChar = (s) => {
-    const freq = new Map();
-    for (const ch of s)
-        freq.set(ch, (freq.get(ch) ?? 0) + 1);
-    const n = s.length;
-    let h = 0;
-    for (const c of freq.values()) {
-        const p = c / n;
-        h -= p * Math.log2(p);
-    }
-    return h;
-};
-/**
- * Maybe emit a one-line entropy warning for a key.
- * Caller supplies an `emit(line)` function; the helper ensures once-per-key.
- */
-const maybeWarnEntropy = (key, value, origin, opts, emit) => {
-    if (!opts || opts.warnEntropy === false)
-        return;
-    if (warned.has(key))
-        return;
-    const v = value ?? '';
-    const minLen = Math.max(0, opts.entropyMinLength ?? 16);
-    const threshold = opts.entropyThreshold ?? 3.8;
-    if (v.length < minLen)
-        return;
-    if (!isPrintableAscii(v))
-        return;
-    const wl = compile$1(opts.entropyWhitelist);
-    if (whitelisted(key, wl))
-        return;
-    const bpc = shannonBitsPerChar(v);
-    if (bpc >= threshold) {
-        warned.add(key);
-        emit(`[entropy] key=${key} score=${bpc.toFixed(2)} len=${String(v.length)} origin=${origin}`);
-    }
-};
-
-const DEFAULT_PATTERNS = [
-    '\\bsecret\\b',
-    '\\btoken\\b',
-    '\\bpass(word)?\\b',
-    '\\bapi[_-]?key\\b',
-    '\\bkey\\b',
-];
-const compile = (patterns) => (patterns && patterns.length > 0 ? patterns : DEFAULT_PATTERNS).map((p) => new RegExp(p, 'i'));
-const shouldRedactKey = (key, regs) => regs.some((re) => re.test(key));
-const MASK = '[redacted]';
-/**
- * Utility to redact three related displayed values (parent/dotenv/final)
- * consistently for trace lines.
- */
-const redactTriple = (key, triple, opts) => {
-    if (!opts?.redact)
-        return triple;
-    const regs = compile(opts.redactPatterns);
-    const maskIf = (v) => (v && shouldRedactKey(key, regs) ? MASK : v);
-    const out = {};
-    const p = maskIf(triple.parent);
-    const d = maskIf(triple.dotenv);
-    const f = maskIf(triple.final);
-    if (p !== undefined)
-        out.parent = p;
-    if (d !== undefined)
-        out.dotenv = d;
-    if (f !== undefined)
-        out.final = f;
-    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',
-    loadProcess: true,
-    logger: console,
-    // Diagnostics defaults
-    warnEntropy: true,
-    entropyThreshold: 3.8,
-    entropyMinLength: 16,
-    entropyWhitelist: ['^GIT_', '^npm_', '^CI$', 'SHLVL'],
-    paths: './',
-    pathsDelimiter: ' ',
-    privateToken: 'local',
-    scripts: {
-        'git-status': {
-            cmd: 'git branch --show-current && git status -s -u',
-            shell: true,
-        },
-    },
-    shell: true,
-    vars: '',
-    varsAssignor: '=',
-    varsDelimiter: ' ',
-    // tri-state flags default to unset unless explicitly provided
-    // (debug/log/exclude* resolved via flag utils)
-};
-
-/** @internal */
-const isPlainObject = (value) => value !== null &&
-    typeof value === 'object' &&
-    Object.getPrototypeOf(value) === Object.prototype;
-const mergeInto = (target, source) => {
-    for (const [key, sVal] of Object.entries(source)) {
-        if (sVal === undefined)
-            continue; // do not overwrite with undefined
-        const tVal = target[key];
-        if (isPlainObject(tVal) && isPlainObject(sVal)) {
-            target[key] = mergeInto({ ...tVal }, sVal);
-        }
-        else if (isPlainObject(sVal)) {
-            target[key] = mergeInto({}, sVal);
-        }
-        else {
-            target[key] = sVal;
-        }
-    }
-    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) => {
-    const result = layers
-        .filter(Boolean)
-        .reduce((acc, layer) => mergeInto(acc, layer), {});
-    return result;
-};
-
-/**
- * Resolve a tri-state optional boolean flag under exactOptionalPropertyTypes.
- * - If the user explicitly enabled the flag, return true.
- * - If the user explicitly disabled (the "...-off" variant), return undefined (unset).
- * - Otherwise, adopt the default (true → set; false/undefined → unset).
- *
- * @param exclude - The "on" flag value as parsed by Commander.
- * @param excludeOff - The "off" toggle (present when specified) as parsed by Commander.
- * @param defaultValue - The generator default to adopt when no explicit toggle is present.
- * @returns boolean | undefined — use `undefined` to indicate "unset" (do not emit).
- *
- * @example
- * ```ts
- * resolveExclusion(undefined, undefined, true); // => true
- * ```
- */
-const resolveExclusion = (exclude, excludeOff, defaultValue) => exclude ? true : excludeOff ? undefined : defaultValue ? true : undefined;
-/**
- * Resolve an optional flag with "--exclude-all" overrides.
- * If excludeAll is set and the individual "...-off" is not, force true.
- * If excludeAllOff is set and the individual flag is not explicitly set, unset.
- * Otherwise, adopt the default (true → set; false/undefined → unset).
- *
- * @param exclude - Individual include/exclude flag.
- * @param excludeOff - Individual "...-off" flag.
- * @param defaultValue - Default for the individual flag.
- * @param excludeAll - Global "exclude-all" flag.
- * @param excludeAllOff - Global "exclude-all-off" flag.
- *
- * @example
- * resolveExclusionAll(undefined, undefined, false, true, undefined) =\> true
- */
-const resolveExclusionAll = (exclude, excludeOff, defaultValue, excludeAll, excludeAllOff) => 
-// Order of precedence:
-// 1) Individual explicit "on" wins outright.
-// 2) Individual explicit "off" wins over any global.
-// 3) Global exclude-all forces true when not explicitly turned off.
-// 4) Global exclude-all-off unsets when the individual wasn't explicitly enabled.
-// 5) Fall back to the default (true => set; false/undefined => unset).
-(() => {
-    // Individual "on"
-    if (exclude === true)
-        return true;
-    // Individual "off"
-    if (excludeOff === true)
-        return undefined;
-    // Global "exclude-all" ON (unless explicitly turned off)
-    if (excludeAll === true)
-        return true;
-    // Global "exclude-all-off" (unless explicitly enabled)
-    if (excludeAllOff === true)
-        return undefined;
-    // Default
-    return defaultValue ? true : undefined;
-})();
-/**
- * exactOptionalPropertyTypes-safe setter for optional boolean flags:
- * delete when undefined; assign when defined — without requiring an index signature on T.
- *
- * @typeParam T - Target object type.
- * @param obj - The object to write to.
- * @param key - The optional boolean property key of {@link T}.
- * @param value - The value to set or `undefined` to unset.
- *
- * @remarks
- * Writes through a local `Record<string, unknown>` view to avoid requiring an index signature on {@link T}.
- */
-const setOptionalFlag = (obj, key, value) => {
-    const target = obj;
-    const k = key;
-    // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
-    if (value === undefined)
-        delete target[k];
-    else
-        target[k] = value;
-};
-
-/**
- * Merge and normalize raw Commander options (current + parent + defaults)
- * into a GetDotenvCliOptions-like object. Types are intentionally wide to
- * avoid cross-layer coupling; callers may cast as needed.
- */
-const resolveCliOptions = (rawCliOptions, defaults, parentJson) => {
-    const parent = typeof parentJson === 'string' && parentJson.length > 0
-        ? JSON.parse(parentJson)
-        : undefined;
-    const { command, debugOff, excludeAll, excludeAllOff, excludeDynamicOff, excludeEnvOff, excludeGlobalOff, excludePrivateOff, excludePublicOff, loadProcessOff, logOff, entropyWarn, entropyWarnOff, scripts, shellOff, ...rest } = rawCliOptions;
-    const current = { ...rest };
-    if (typeof scripts === 'string') {
-        try {
-            current.scripts = JSON.parse(scripts);
-        }
-        catch {
-            // ignore parse errors; leave scripts undefined
-        }
-    }
-    const merged = defaultsDeep({}, defaults, parent ?? {}, current);
-    const d = defaults;
-    setOptionalFlag(merged, 'debug', resolveExclusion(merged.debug, debugOff, d.debug));
-    setOptionalFlag(merged, 'excludeDynamic', resolveExclusionAll(merged.excludeDynamic, excludeDynamicOff, d.excludeDynamic, excludeAll, excludeAllOff));
-    setOptionalFlag(merged, 'excludeEnv', resolveExclusionAll(merged.excludeEnv, excludeEnvOff, d.excludeEnv, excludeAll, excludeAllOff));
-    setOptionalFlag(merged, 'excludeGlobal', resolveExclusionAll(merged.excludeGlobal, excludeGlobalOff, d.excludeGlobal, excludeAll, excludeAllOff));
-    setOptionalFlag(merged, 'excludePrivate', resolveExclusionAll(merged.excludePrivate, excludePrivateOff, d.excludePrivate, excludeAll, excludeAllOff));
-    setOptionalFlag(merged, 'excludePublic', resolveExclusionAll(merged.excludePublic, excludePublicOff, d.excludePublic, excludeAll, excludeAllOff));
-    setOptionalFlag(merged, 'log', resolveExclusion(merged.log, logOff, d.log));
-    setOptionalFlag(merged, 'loadProcess', resolveExclusion(merged.loadProcess, loadProcessOff, d.loadProcess));
-    // warnEntropy (tri-state)
-    setOptionalFlag(merged, 'warnEntropy', resolveExclusion(merged.warnEntropy, entropyWarnOff, d.warnEntropy));
-    // Normalize shell for predictability: explicit default shell per OS.
-    const defaultShell = process.platform === 'win32' ? 'powershell.exe' : '/bin/bash';
-    let resolvedShell = merged.shell;
-    if (shellOff)
-        resolvedShell = false;
-    else if (resolvedShell === true || resolvedShell === undefined) {
-        resolvedShell = defaultShell;
-    }
-    else if (typeof resolvedShell !== 'string' &&
-        typeof defaults.shell === 'string') {
-        resolvedShell = defaults.shell;
-    }
-    merged.shell = resolvedShell;
-    const cmd = typeof command === 'string' ? command : undefined;
-    return cmd !== undefined ? { merged, command: cmd } : { merged };
-};
-
-/**
- * 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 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);
-    }
-    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);
-    }
-    // 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));
-    }
-    // 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);
-    }
-};
-const attachParentAlias = (cli, options, _cmd) => {
-    const aliasSpec = typeof options.optionAlias === 'string'
-        ? { flags: options.optionAlias, description: undefined, expand: true }
-        : options.optionAlias;
-    if (!aliasSpec)
-        return;
-    const deriveKey = (flags) => {
-        dbg('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());
-    };
-    const aliasKey = deriveKey(aliasSpec.flags);
-    // Expose the option on the parent.
-    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 */
-    }
-    // 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));
-        }
-    };
-    // 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);
-    });
-    cli.hook('preSubcommand', async (thisCommand) => {
-        await maybeRunAlias(thisCommand);
-    });
-};
-
-/**+ Cmd plugin: executes a command using the current getdotenv CLI context.
- *
- * - Joins positional args into a single command string.
- * - Resolves scripts and shell settings using shared helpers.
- * - Forwards merged CLI options to subprocesses via
- *   process.env.getDotenvCliOptions for nested CLI behavior. */
-const cmdPlugin = (options = {}) => definePlugin({
-    id: 'cmd',
-    setup(cli) {
-        const aliasSpec = typeof options.optionAlias === 'string'
-            ? { flags: options.optionAlias}
-            : options.optionAlias;
-        const deriveKey = (flags) => {
-            const long = flags.split(/[ ,|]+/).find((f) => f.startsWith('--')) ?? '--cmd';
-            const name = long.replace(/^--/, '');
-            return name.replace(/-([a-z])/g, (_m, c) => c.toUpperCase());
-        };
-        const aliasKey = aliasSpec ? deriveKey(aliasSpec.flags) : undefined;
-        // 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)')
-            .enablePositionalOptions()
-            .passThroughOptions()
-            .argument('[command...]')
-            .action(async (commandParts, _opts, thisCommand) => {
-            // Commander passes positional tokens as the first action argument
-            const args = Array.isArray(commandParts) ? commandParts : [];
-            // No-op when invoked as the default command with no args.
-            if (args.length === 0)
-                return;
-            const parent = thisCommand.parent;
-            if (!parent)
-                throw new Error('parent command not found'); // Conflict detection: if an alias option is present on parent, do not
-            // also accept positional cmd args.
-            if (aliasKey) {
-                const pv = parent.opts();
-                const ov = pv[aliasKey];
-                if (ov !== undefined) {
-                    const merged = parent.getDotenvCliOptions ?? {};
-                    const logger = merged.logger ?? console;
-                    const lr = logger;
-                    const emit = lr.error ?? lr.log;
-                    emit(`--${aliasKey} option conflicts with cmd subcommand.`);
-                    process.exit(0);
-                }
-            }
-            // Merged CLI options are persisted by the shipped CLI preSubcommand hook.
-            const merged = parent.getDotenvCliOptions ?? {};
-            const logger = merged.logger ?? console;
-            // Join positional args into the command string.
-            const input = args.map(String).join(' ');
-            // Resolve command and shell using shared helpers.
-            const scripts = merged.scripts;
-            const shell = merged.shell;
-            const resolved = resolveCommand(scripts, input);
-            if (merged.debug) {
-                const lg = logger;
-                (lg.debug ?? lg.log)('\n*** command ***\n', `'${resolved}'`);
-            }
-            // Round-trip CLI options for nested getdotenv invocations.
-            // Omit logger (functions are not serializable).
-            const { logger: _omit, ...envBag } = merged;
-            const capture = process.env.GETDOTENV_STDIO === 'pipe' ||
-                Boolean(merged.capture);
-            // Prefer explicit env injection using the resolved dotenv map.
-            const ctx = cli.getCtx();
-            const dotenv = (ctx?.dotenv ?? {});
-            // Diagnostics: --trace [keys...] (space-delimited keys if provided; all keys when true)
-            const traceOpt = merged.trace;
-            if (traceOpt) {
-                // Determine keys to trace: all keys (parent ∪ dotenv) or selected.
-                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;
-                // Child env preview (as composed below; excluding getDotenvCliOptions)
-                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';
-                    // Apply presentation-time redaction (if enabled)
-                    const redFlag = merged.redact;
-                    const redPatterns = merged
-                        .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);
-                    // Emit concise diagnostic line to stderr.
-                    process.stderr.write(`[trace] key=${k} origin=${origin} parent=${triple.parent ?? ''} dotenv=${triple.dotenv ?? ''} final=${triple.final ?? ''}\n`);
-                    // Optional entropy warning (once-per-key)
-                    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'));
-                }
-            }
-            const shellSetting = resolveShell(scripts, input, shell);
-            /**
-             * Preserve original argv array when:
-             * - shell is OFF (plain execa), and
-             * - no script alias remap occurred (resolved === input).
-             *
-             * This avoids lossy re-tokenization of code snippets such as:
-             *   node -e "console.log(process.env.APP_SECRET ?? '')"
-             * where quotes may have been stripped by the parent shell and
-             * spaces inside the code must remain a single argument.
-             */
-            const commandArg = shellSetting === false && resolved === input
-                ? args.map(String)
-                : resolved;
-            await runCommand(commandArg, shellSetting, {
-                env: buildSpawnEnv(process.env, {
-                    ...dotenv,
-                    getDotenvCliOptions: JSON.stringify(envBag),
-                }),
-                stdio: capture ? 'pipe' : 'inherit',
-            });
-        });
-        if (options.asDefault)
-            cli.addCommand(cmd, { isDefault: true });
-        else
-            cli.addCommand(cmd);
-        // Parent-attached option alias (optional).
-        if (aliasSpec)
-            attachParentAlias(cli, options);
-    },
-});
-
-exports.cmdPlugin = cmdPlugin;