@karmaniverous/get-dotenv 6.0.0-0 → 6.0.0

package/dist/plugins.cjs

@@ -1,2327 +0,0 @@
-'use strict';
-
-var execa = require('execa');
-var zod = require('zod');
-var commander = require('commander');
-var globby = require('globby');
-var packageDirectory = require('package-directory');
-var path = require('path');
-var fs = require('fs-extra');
-var node_process = require('node:process');
-var promises = require('readline/promises');
-
-// 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;
-};
-// 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) => {
-    if (!env)
-        return undefined;
-    const entries = Object.entries(env).filter((e) => typeof e[1] === 'string');
-    return entries.length > 0 ? Object.fromEntries(entries) : undefined;
-};
-/**
- * Execute a command and capture stdout/stderr (buffered).
- * - Preserves plain vs shell behavior and argv/string normalization.
- * - Never re-emits stdout/stderr to parent; returns captured buffers.
- * - Supports optional timeout (ms).
- */
-const runCommandResult = async (command, shell, opts = {}) => {
-    const envSan = sanitizeEnv(opts.env);
-    {
-        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 { exitCode: 0, stdout: '', stderr: '' };
-        dbg$1('exec:capture (plain)', { file, args });
-        try {
-            const result = await execa.execa(file, args, {
-                ...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),
-                ...(envSan !== undefined ? { env: envSan } : {}),
-                stdio: 'pipe',
-                ...(opts.timeoutMs !== undefined
-                    ? { timeout: opts.timeoutMs, killSignal: 'SIGKILL' }
-                    : {}),
-            });
-            const ok = pickResult(result);
-            dbg$1('exit:capture (plain)', { exitCode: ok.exitCode });
-            return ok;
-        }
-        catch (err) {
-            const out = pickResult(err);
-            dbg$1('exit:capture:error (plain)', { exitCode: out.exitCode });
-            return out;
-        }
-    }
-};
-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;
-};
-
-/**
- * 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);
-
-const DEFAULT_TIMEOUT_MS = 15_000;
-const trim = (s) => (typeof s === 'string' ? s.trim() : '');
-const unquote = (s) => s.length >= 2 &&
-    ((s.startsWith('"') && s.endsWith('"')) ||
-        (s.startsWith("'") && s.endsWith("'")))
-    ? s.slice(1, -1)
-    : s;
-const parseExportCredentialsJson = (txt) => {
-    try {
-        const obj = JSON.parse(txt);
-        const src = obj.Credentials ?? obj;
-        const ak = src.AccessKeyId;
-        const sk = src.SecretAccessKey;
-        const tk = src.SessionToken;
-        if (ak && sk)
-            return {
-                accessKeyId: ak,
-                secretAccessKey: sk,
-                ...(tk ? { sessionToken: tk } : {}),
-            };
-    }
-    catch {
-        /* ignore */
-    }
-    return undefined;
-};
-const parseExportCredentialsEnv = (txt) => {
-    const lines = txt.split(/\r?\n/);
-    let id;
-    let secret;
-    let token;
-    for (const raw of lines) {
-        const line = raw.trim();
-        if (!line)
-            continue;
-        // POSIX: export AWS_ACCESS_KEY_ID=..., export AWS_SECRET_ACCESS_KEY=..., export AWS_SESSION_TOKEN=...
-        let m = /^export\s+([A-Z0-9_]+)\s*=\s*(.+)$/.exec(line);
-        if (!m) {
-            // PowerShell: $Env:AWS_ACCESS_KEY_ID="...", etc.
-            m = /^\$Env:([A-Z0-9_]+)\s*=\s*(.+)$/.exec(line);
-        }
-        if (!m)
-            continue;
-        const k = m[1];
-        const valRaw = m[2];
-        if (typeof valRaw !== 'string')
-            continue;
-        let v = unquote(valRaw.trim());
-        // Drop trailing semicolons if present (some shells)
-        v = v.replace(/;$/, '');
-        if (k === 'AWS_ACCESS_KEY_ID')
-            id = v;
-        else if (k === 'AWS_SECRET_ACCESS_KEY')
-            secret = v;
-        else if (k === 'AWS_SESSION_TOKEN')
-            token = v;
-    }
-    if (id && secret)
-        return {
-            accessKeyId: id,
-            secretAccessKey: secret,
-            ...(token ? { sessionToken: token } : {}),
-        };
-    return undefined;
-};
-const getAwsConfigure = async (key, profile, timeoutMs = DEFAULT_TIMEOUT_MS) => {
-    const r = await runCommandResult(['aws', 'configure', 'get', key, '--profile', profile], false, {
-        env: process.env,
-        timeoutMs,
-    });
-    // Guard for mocked undefined in tests; keep narrow lint scope.
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-    if (!r || typeof r.exitCode !== 'number')
-        return undefined;
-    if (r.exitCode === 0) {
-        const v = trim(r.stdout);
-        return v.length > 0 ? v : undefined;
-    }
-    return undefined;
-};
-const exportCredentials = async (profile, timeoutMs = DEFAULT_TIMEOUT_MS) => {
-    // Try JSON format first (AWS CLI v2)
-    const rJson = await runCommandResult([
-        'aws',
-        'configure',
-        'export-credentials',
-        '--profile',
-        profile,
-        '--format',
-        'json',
-    ], false, { env: process.env, timeoutMs });
-    if (rJson.exitCode === 0) {
-        const creds = parseExportCredentialsJson(rJson.stdout);
-        if (creds)
-            return creds;
-    }
-    // Fallback: env lines
-    const rEnv = await runCommandResult(['aws', 'configure', 'export-credentials', '--profile', profile], false, { env: process.env, timeoutMs });
-    if (rEnv.exitCode === 0) {
-        const creds = parseExportCredentialsEnv(rEnv.stdout);
-        if (creds)
-            return creds;
-    }
-    return undefined;
-};
-const resolveAwsContext = async ({ dotenv, cfg, }) => {
-    const profileKey = cfg.profileKey ?? 'AWS_LOCAL_PROFILE';
-    const profileFallbackKey = cfg.profileFallbackKey ?? 'AWS_PROFILE';
-    const regionKey = cfg.regionKey ?? 'AWS_REGION';
-    const profile = cfg.profile ??
-        dotenv[profileKey] ??
-        dotenv[profileFallbackKey] ??
-        undefined;
-    let region = cfg.region ?? dotenv[regionKey] ?? undefined;
-    // Short-circuit when strategy is disabled.
-    if (cfg.strategy === 'none') {
-        // If region is still missing and we have a profile, try best-effort region resolve.
-        if (!region && profile)
-            region = await getAwsConfigure('region', profile);
-        if (!region && cfg.defaultRegion)
-            region = cfg.defaultRegion;
-        const out = {};
-        if (profile !== undefined)
-            out.profile = profile;
-        if (region !== undefined)
-            out.region = region;
-        return out;
-    }
-    // Env-first credentials.
-    let credentials;
-    const envId = trim(process.env.AWS_ACCESS_KEY_ID);
-    const envSecret = trim(process.env.AWS_SECRET_ACCESS_KEY);
-    const envToken = trim(process.env.AWS_SESSION_TOKEN);
-    if (envId && envSecret) {
-        credentials = {
-            accessKeyId: envId,
-            secretAccessKey: envSecret,
-            ...(envToken ? { sessionToken: envToken } : {}),
-        };
-    }
-    else if (profile) {
-        // Try export-credentials
-        credentials = await exportCredentials(profile);
-        // On failure, detect SSO and optionally login then retry
-        if (!credentials) {
-            const ssoSession = await getAwsConfigure('sso_session', profile);
-            const looksSSO = typeof ssoSession === 'string' && ssoSession.length > 0;
-            if (looksSSO && cfg.loginOnDemand) {
-                // Best-effort login, then retry export once.
-                await runCommandResult(['aws', 'sso', 'login', '--profile', profile], false, {
-                    env: process.env,
-                    timeoutMs: DEFAULT_TIMEOUT_MS,
-                });
-                credentials = await exportCredentials(profile);
-            }
-        }
-        // Static fallback if still missing.
-        if (!credentials) {
-            const id = await getAwsConfigure('aws_access_key_id', profile);
-            const secret = await getAwsConfigure('aws_secret_access_key', profile);
-            const token = await getAwsConfigure('aws_session_token', profile);
-            if (id && secret) {
-                credentials = {
-                    accessKeyId: id,
-                    secretAccessKey: secret,
-                    ...(token ? { sessionToken: token } : {}),
-                };
-            }
-        }
-    }
-    // Final region resolution
-    if (!region && profile)
-        region = await getAwsConfigure('region', profile);
-    if (!region && cfg.defaultRegion)
-        region = cfg.defaultRegion;
-    const out = {};
-    if (profile !== undefined)
-        out.profile = profile;
-    if (region !== undefined)
-        out.region = region;
-    if (credentials)
-        out.credentials = credentials;
-    return out;
-};
-
-const AwsPluginConfigSchema = zod.z.object({
-    profile: zod.z.string().optional(),
-    region: zod.z.string().optional(),
-    defaultRegion: zod.z.string().optional(),
-    profileKey: zod.z.string().default('AWS_LOCAL_PROFILE').optional(),
-    profileFallbackKey: zod.z.string().default('AWS_PROFILE').optional(),
-    regionKey: zod.z.string().default('AWS_REGION').optional(),
-    strategy: zod.z.enum(['cli-export', 'none']).default('cli-export').optional(),
-    loginOnDemand: zod.z.boolean().default(false).optional(),
-    setEnv: zod.z.boolean().default(true).optional(),
-    addCtx: zod.z.boolean().default(true).optional(),
-});
-
-const awsPlugin = () => definePlugin({
-    id: 'aws',
-    // Host validates this slice when the loader path is active.
-    configSchema: AwsPluginConfigSchema,
-    setup(cli) {
-        // Subcommand: aws
-        cli
-            .ns('aws')
-            .description('Establish an AWS session and optionally forward to the AWS CLI')
-            .enablePositionalOptions()
-            .passThroughOptions()
-            .allowUnknownOption(true)
-            // Boolean toggles
-            .option('--login-on-demand', 'attempt aws sso login on-demand')
-            .option('--no-login-on-demand', 'disable sso login on-demand')
-            .option('--set-env', 'write resolved values into process.env')
-            .option('--no-set-env', 'do not write resolved values into process.env')
-            .option('--add-ctx', 'mirror results under ctx.plugins.aws')
-            .option('--no-add-ctx', 'do not mirror results under ctx.plugins.aws')
-            // Strings / enums
-            .option('--profile <string>', 'AWS profile name')
-            .option('--region <string>', 'AWS region')
-            .option('--default-region <string>', 'fallback region')
-            .option('--strategy <string>', 'credential acquisition strategy: cli-export|none')
-            // Advanced key overrides
-            .option('--profile-key <string>', 'dotenv/config key for local profile')
-            .option('--profile-fallback-key <string>', 'fallback dotenv/config key for profile')
-            .option('--region-key <string>', 'dotenv/config key for region')
-            // Accept any extra operands so Commander does not error when tokens appear after "--".
-            .argument('[args...]')
-            .action(async (args, opts, thisCommand) => {
-            const self = thisCommand;
-            const parent = (self.parent ?? null);
-            // Access merged root CLI options (installed by passOptions())
-            const rootOpts = (parent?.getDotenvCliOptions ?? {});
-            const capture = process.env.GETDOTENV_STDIO === 'pipe' ||
-                Boolean(rootOpts?.capture);
-            const underTests = process.env.GETDOTENV_TEST === '1' ||
-                typeof process.env.VITEST_WORKER_ID === 'string';
-            // Build overlay cfg from subcommand flags layered over discovered config.
-            const ctx = cli.getCtx();
-            const cfgBase = (ctx?.pluginConfigs?.['aws'] ??
-                {});
-            const overlay = {};
-            // Map boolean toggles (respect explicit --no-*)
-            if (Object.prototype.hasOwnProperty.call(opts, 'loginOnDemand'))
-                overlay.loginOnDemand = Boolean(opts.loginOnDemand);
-            if (Object.prototype.hasOwnProperty.call(opts, 'setEnv'))
-                overlay.setEnv = Boolean(opts.setEnv);
-            if (Object.prototype.hasOwnProperty.call(opts, 'addCtx'))
-                overlay.addCtx = Boolean(opts.addCtx);
-            // Strings/enums
-            if (typeof opts.profile === 'string')
-                overlay.profile = opts.profile;
-            if (typeof opts.region === 'string')
-                overlay.region = opts.region;
-            if (typeof opts.defaultRegion === 'string')
-                overlay.defaultRegion = opts.defaultRegion;
-            if (typeof opts.strategy === 'string')
-                overlay.strategy =
-                    opts.strategy;
-            // Advanced key overrides
-            if (typeof opts.profileKey === 'string')
-                overlay.profileKey = opts.profileKey;
-            if (typeof opts.profileFallbackKey === 'string')
-                overlay.profileFallbackKey = opts.profileFallbackKey;
-            if (typeof opts.regionKey === 'string')
-                overlay.regionKey = opts.regionKey;
-            const cfg = {
-                ...cfgBase,
-                ...overlay,
-            };
-            // Resolve current context with overrides
-            const out = await resolveAwsContext({
-                dotenv: ctx?.dotenv ?? {},
-                cfg,
-            });
-            // Apply env/ctx mirrors per toggles
-            if (cfg.setEnv !== false) {
-                if (out.region) {
-                    process.env.AWS_REGION = out.region;
-                    if (!process.env.AWS_DEFAULT_REGION)
-                        process.env.AWS_DEFAULT_REGION = out.region;
-                }
-                if (out.credentials) {
-                    process.env.AWS_ACCESS_KEY_ID = out.credentials.accessKeyId;
-                    process.env.AWS_SECRET_ACCESS_KEY =
-                        out.credentials.secretAccessKey;
-                    if (out.credentials.sessionToken !== undefined) {
-                        process.env.AWS_SESSION_TOKEN = out.credentials.sessionToken;
-                    }
-                }
-            }
-            if (cfg.addCtx !== false) {
-                if (ctx) {
-                    ctx.plugins ??= {};
-                    ctx.plugins['aws'] = {
-                        ...(out.profile ? { profile: out.profile } : {}),
-                        ...(out.region ? { region: out.region } : {}),
-                        ...(out.credentials ? { credentials: out.credentials } : {}),
-                    };
-                }
-            }
-            // Forward when positional args are present; otherwise session-only.
-            if (Array.isArray(args) && args.length > 0) {
-                const argv = ['aws', ...args];
-                const shellSetting = resolveShell(rootOpts?.scripts, 'aws', rootOpts?.shell);
-                const ctxDotenv = (ctx?.dotenv ?? {});
-                const exit = await runCommand(argv, shellSetting, {
-                    env: buildSpawnEnv(process.env, ctxDotenv),
-                    stdio: capture ? 'pipe' : 'inherit',
-                });
-                // Deterministic termination (suppressed under tests)
-                if (!underTests) {
-                    process.exit(typeof exit === 'number' ? exit : 0);
-                }
-                return;
-            }
-            else {
-                // Session only: low-noise breadcrumb under debug
-                if (process.env.GETDOTENV_DEBUG) {
-                    const log = console;
-                    log.log('[aws] session established', {
-                        profile: out.profile,
-                        region: out.region,
-                        hasCreds: Boolean(out.credentials),
-                    });
-                }
-                if (!underTests)
-                    process.exit(0);
-                return;
-            }
-        });
-    },
-    async afterResolve(_cli, ctx) {
-        const log = console;
-        const cfgRaw = (ctx.pluginConfigs?.['aws'] ?? {});
-        const cfg = (cfgRaw || {});
-        const out = await resolveAwsContext({
-            dotenv: ctx.dotenv,
-            cfg,
-        });
-        const { profile, region, credentials } = out;
-        if (cfg.setEnv !== false) {
-            if (region) {
-                process.env.AWS_REGION = region;
-                if (!process.env.AWS_DEFAULT_REGION)
-                    process.env.AWS_DEFAULT_REGION = region;
-            }
-            if (credentials) {
-                process.env.AWS_ACCESS_KEY_ID = credentials.accessKeyId;
-                process.env.AWS_SECRET_ACCESS_KEY = credentials.secretAccessKey;
-                if (credentials.sessionToken !== undefined) {
-                    process.env.AWS_SESSION_TOKEN = credentials.sessionToken;
-                }
-            }
-        }
-        if (cfg.addCtx !== false) {
-            ctx.plugins ??= {};
-            ctx.plugins['aws'] = {
-                ...(profile ? { profile } : {}),
-                ...(region ? { region } : {}),
-                ...(credentials ? { credentials } : {}),
-            };
-        }
-        // Optional: low-noise breadcrumb for diagnostics
-        if (process.env.GETDOTENV_DEBUG) {
-            log.log('[aws] afterResolve', {
-                profile,
-                region,
-                hasCreds: Boolean(credentials),
-            });
-        }
-    },
-});
-
-const globPaths = async ({ globs, logger, pkgCwd, rootPath, }) => {
-    let cwd = process.cwd();
-    if (pkgCwd) {
-        const pkgDir = await packageDirectory.packageDirectory();
-        if (!pkgDir) {
-            logger.error('No package directory found.');
-            process.exit(0);
-        }
-        cwd = pkgDir;
-    }
-    const absRootPath = path.posix.join(cwd.split(path.sep).join(path.posix.sep), rootPath.split(path.sep).join(path.posix.sep));
-    const paths = await globby.globby(globs.split(/\s+/), {
-        cwd: absRootPath,
-        expandDirectories: false,
-        onlyDirectories: true,
-        absolute: true,
-    });
-    if (!paths.length) {
-        logger.error(`No paths found for globs '${globs}' at '${absRootPath}'.`);
-        process.exit(0);
-    }
-    return { absRootPath, paths };
-};
-const execShellCommandBatch = async ({ command, getDotenvCliOptions, dotenvEnv, globs, ignoreErrors, list, logger, pkgCwd, rootPath, shell, }) => {
-    const capture = process.env.GETDOTENV_STDIO === 'pipe' ||
-        Boolean(getDotenvCliOptions?.capture);
-    // Require a command only when not listing. In list mode, a command is optional.
-    if (!command && !list) {
-        logger.error(`No command provided. Use --command or --list.`);
-        process.exit(0);
-    }
-    const { absRootPath, paths } = await globPaths({
-        globs,
-        logger,
-        rootPath,
-        // exactOptionalPropertyTypes: only include when defined
-        ...(pkgCwd !== undefined ? { pkgCwd } : {}),
-    });
-    const headerTitle = list
-        ? 'Listing working directories...'
-        : 'Executing command batch...';
-    logger.info('');
-    const headerRootPath = `ROOT:  ${absRootPath}`;
-    const headerGlobs = `GLOBS: ${globs}`;
-    // Prepare a safe label for the header (avoid undefined in template)
-    const commandLabel = Array.isArray(command)
-        ? command.join(' ')
-        : typeof command === 'string' && command.length > 0
-            ? command
-            : '';
-    const headerCommand = list ? `CMD:   (list only)` : `CMD:   ${commandLabel}`;
-    logger.info('*'.repeat(Math.max(headerTitle.length, headerRootPath.length, headerGlobs.length, headerCommand.length)));
-    logger.info(headerTitle);
-    logger.info('');
-    logger.info(headerRootPath);
-    logger.info(headerGlobs);
-    logger.info(headerCommand);
-    for (const path of paths) {
-        // Write path and command to console.
-        const pathLabel = `CWD:   ${path}`;
-        if (list) {
-            logger.info(pathLabel);
-            continue;
-        }
-        logger.info('');
-        logger.info('*'.repeat(pathLabel.length));
-        logger.info(pathLabel);
-        logger.info(headerCommand);
-        // Execute command.
-        try {
-            const hasCmd = (typeof command === 'string' && command.length > 0) ||
-                (Array.isArray(command) && command.length > 0);
-            if (hasCmd) {
-                // Compose child env overlay from dotenv (drop undefined) and merged options
-                const overlay = {};
-                if (dotenvEnv) {
-                    for (const [k, v] of Object.entries(dotenvEnv)) {
-                        if (typeof v === 'string')
-                            overlay[k] = v;
-                    }
-                }
-                if (getDotenvCliOptions !== undefined) {
-                    try {
-                        overlay.getDotenvCliOptions = JSON.stringify(getDotenvCliOptions);
-                    }
-                    catch {
-                        // best-effort: omit if serialization fails
-                    }
-                }
-                await runCommand(command, shell, {
-                    cwd: path,
-                    env: buildSpawnEnv(process.env, overlay),
-                    stdio: capture ? 'pipe' : 'inherit',
-                });
-            }
-            else {
-                // Should not occur due to the early guard; retain for type safety.
-                logger.error(`No command provided. Use --command or --list.`);
-                process.exit(0);
-            }
-        }
-        catch (error) {
-            if (!ignoreErrors) {
-                throw error;
-            }
-        }
-    }
-    logger.info('');
-};
-
-/**
- * Build the default "cmd" subcommand action for the batch plugin.
- * Mirrors the original inline implementation with identical behavior.
- */
-const buildDefaultCmdAction = (cli, batchCmd, opts) => async (commandParts, _subOpts, _thisCommand) => {
-    const loggerLocal = opts.logger ?? console;
-    // Guard: when invoked without positional args (e.g., `batch --list`),
-    // defer entirely to the parent action handler.
-    const argsRaw = Array.isArray(commandParts)
-        ? commandParts
-        : [];
-    const localList = argsRaw.includes('-l') || argsRaw.includes('--list');
-    const args = localList
-        ? argsRaw.filter((t) => t !== '-l' && t !== '--list')
-        : argsRaw;
-    // Access merged per-plugin config from host context (if any).
-    const ctx = cli.getCtx();
-    const cfgRaw = (ctx?.pluginConfigs?.['batch'] ?? {});
-    const cfg = (cfgRaw || {});
-    const dotenvEnv = (ctx?.dotenv ?? {});
-    // Resolve batch flags from the captured parent (batch) command.
-    const raw = batchCmd.opts();
-    const listFromParent = !!raw.list;
-    const ignoreErrors = !!raw.ignoreErrors;
-    const globs = typeof raw.globs === 'string' ? raw.globs : (cfg.globs ?? '*');
-    const pkgCwd = raw.pkgCwd !== undefined ? !!raw.pkgCwd : !!cfg.pkgCwd;
-    const rootPath = typeof raw.rootPath === 'string' ? raw.rootPath : (cfg.rootPath ?? './');
-    // Resolve scripts/shell with precedence:
-    // plugin opts → plugin config → merged root CLI options
-    const mergedBag = ((batchCmd.parent ?? null)?.getDotenvCliOptions ?? {});
-    const scripts = opts.scripts ?? cfg.scripts ?? mergedBag.scripts;
-    const shell = opts.shell ?? cfg.shell ?? mergedBag.shell;
-    // If no positional args were given, bridge to --command/--list paths here.
-    if (args.length === 0) {
-        const commandOpt = typeof raw.command === 'string' ? raw.command : undefined;
-        if (typeof commandOpt === 'string') {
-            await execShellCommandBatch({
-                command: resolveCommand(scripts, commandOpt),
-                dotenvEnv,
-                globs,
-                ignoreErrors,
-                list: false,
-                logger: loggerLocal,
-                ...(pkgCwd ? { pkgCwd } : {}),
-                rootPath,
-                shell: resolveShell(scripts, commandOpt, shell),
-            });
-            return;
-        }
-        if (raw.list || localList) {
-            const shellBag = ((batchCmd.parent ?? undefined)?.getDotenvCliOptions ?? {});
-            await execShellCommandBatch({
-                globs,
-                ignoreErrors,
-                list: true,
-                logger: loggerLocal,
-                ...(pkgCwd ? { pkgCwd } : {}),
-                rootPath,
-                shell: (shell ?? shellBag.shell ?? false),
-            });
-            return;
-        }
-        {
-            const lr = loggerLocal;
-            const emit = lr.error ?? lr.log;
-            emit(`No command provided. Use --command or --list.`);
-        }
-        process.exit(0);
-    }
-    // If a local list flag was supplied with positional tokens (and no --command),
-    // treat tokens as additional globs and execute list mode.
-    if (localList && typeof raw.command !== 'string') {
-        const extraGlobs = args.map(String).join(' ').trim();
-        const mergedGlobs = [globs, extraGlobs].filter(Boolean).join(' ');
-        const shellBag = ((batchCmd.parent ?? undefined)?.getDotenvCliOptions ?? {});
-        await execShellCommandBatch({
-            globs: mergedGlobs,
-            ignoreErrors,
-            list: true,
-            logger: loggerLocal,
-            ...(pkgCwd ? { pkgCwd } : {}),
-            rootPath,
-            shell: (shell ?? shellBag.shell ?? false),
-        });
-        return;
-    }
-    // If parent list flag is set and positional tokens are present (and no --command),
-    // treat tokens as additional globs for list-only mode.
-    if (listFromParent && args.length > 0 && typeof raw.command !== 'string') {
-        const extra = args.map(String).join(' ').trim();
-        const mergedGlobs = [globs, extra].filter(Boolean).join(' ');
-        const mergedBag2 = ((batchCmd.parent ?? undefined)?.getDotenvCliOptions ?? {});
-        await execShellCommandBatch({
-            globs: mergedGlobs,
-            ignoreErrors,
-            list: true,
-            logger: loggerLocal,
-            ...(pkgCwd ? { pkgCwd } : {}),
-            rootPath,
-            shell: (shell ?? mergedBag2.shell ?? false),
-        });
-        return;
-    }
-    // Join positional args as the command to execute.
-    const input = args.map(String).join(' ');
-    // Optional: round-trip parent merged options if present (shipped CLI).
-    const envBag = (batchCmd.parent ?? undefined)?.getDotenvCliOptions;
-    const mergedExec = ((batchCmd.parent ?? undefined)?.getDotenvCliOptions ?? {});
-    const scriptsExec = scripts ?? mergedExec.scripts;
-    const shellExec = shell ?? mergedExec.shell;
-    const resolved = resolveCommand(scriptsExec, input);
-    const shellSetting = resolveShell(scriptsExec, input, shellExec);
-    // Preserve argv array only for shell-off Node -e snippets to avoid
-    // lossy re-tokenization (Windows/PowerShell quoting). For simple
-    // commands (e.g., "echo OK") keep string form to satisfy unit tests.
-    let commandArg = resolved;
-    if (shellSetting === false && resolved === input) {
-        const first = (args[0] ?? '').toLowerCase();
-        const hasEval = args.includes('-e') || args.includes('--eval');
-        if (first === 'node' && hasEval) {
-            commandArg = args.map(String);
-        }
-    }
-    await execShellCommandBatch({
-        command: commandArg,
-        dotenvEnv,
-        ...(envBag ? { getDotenvCliOptions: envBag } : {}),
-        globs,
-        ignoreErrors,
-        list: false,
-        logger: loggerLocal,
-        ...(pkgCwd ? { pkgCwd } : {}),
-        rootPath,
-        shell: shellSetting,
-    });
-};
-
-/**
- * Build the parent "batch" action handler (no explicit subcommand).
- */
-const buildParentAction = (cli, opts) => async (commandParts, thisCommand) => {
-    const logger = opts.logger ?? console;
-    // Ensure context exists (host preSubcommand on root creates if missing).
-    const ctx = cli.getCtx();
-    const dotenvEnv = (ctx?.dotenv ?? {});
-    const cfgRaw = (ctx?.pluginConfigs?.['batch'] ?? {});
-    const cfg = (cfgRaw || {});
-    const raw = thisCommand.opts();
-    const commandOpt = typeof raw.command === 'string' ? raw.command : undefined;
-    const ignoreErrors = !!raw.ignoreErrors;
-    let globs = typeof raw.globs === 'string' ? raw.globs : (cfg.globs ?? '*');
-    const list = !!raw.list;
-    const pkgCwd = raw.pkgCwd !== undefined ? !!raw.pkgCwd : !!cfg.pkgCwd;
-    const rootPath = typeof raw.rootPath === 'string' ? raw.rootPath : (cfg.rootPath ?? './');
-    // Treat parent positional tokens as the command when no explicit 'cmd' is used.
-    const argsParent = Array.isArray(commandParts) ? commandParts : [];
-    if (argsParent.length > 0 && !list) {
-        const input = argsParent.map(String).join(' ');
-        const mergedBag = ((thisCommand.parent ?? null)?.getDotenvCliOptions ?? {});
-        const scriptsAll = opts.scripts ?? cfg.scripts ?? mergedBag.scripts;
-        const shellAll = opts.shell ?? cfg.shell ?? mergedBag.shell;
-        const resolved = resolveCommand(scriptsAll, input);
-        const shellSetting = resolveShell(scriptsAll, input, shellAll);
-        // Parent path: pass a string; executor handles shell-specific details.
-        const commandArg = resolved;
-        await execShellCommandBatch({
-            command: commandArg,
-            dotenvEnv,
-            globs,
-            ignoreErrors,
-            list: false,
-            logger,
-            ...(pkgCwd ? { pkgCwd } : {}),
-            rootPath,
-            shell: shellSetting,
-        });
-        return;
-    }
-    // List-only: merge extra positional tokens into globs when no --command is present.
-    if (list && argsParent.length > 0 && !commandOpt) {
-        const extra = argsParent.map(String).join(' ').trim();
-        if (extra.length > 0)
-            globs = [globs, extra].filter(Boolean).join(' ');
-        const mergedBag = ((thisCommand.parent ?? null)?.getDotenvCliOptions ?? {});
-        await execShellCommandBatch({
-            globs,
-            ignoreErrors,
-            list: true,
-            logger,
-            ...(pkgCwd ? { pkgCwd } : {}),
-            rootPath,
-            shell: (opts.shell ?? cfg.shell ?? mergedBag.shell ?? false),
-        });
-        return;
-    }
-    if (!commandOpt && !list) {
-        logger.error(`No command provided. Use --command or --list.`);
-        process.exit(0);
-    }
-    if (typeof commandOpt === 'string') {
-        const mergedBag = ((thisCommand.parent ?? null)?.getDotenvCliOptions ?? {});
-        const scriptsOpt = opts.scripts ?? cfg.scripts ?? mergedBag.scripts;
-        const shellOpt = opts.shell ?? cfg.shell ?? mergedBag.shell;
-        await execShellCommandBatch({
-            command: resolveCommand(scriptsOpt, commandOpt),
-            dotenvEnv,
-            globs,
-            ignoreErrors,
-            list,
-            logger,
-            ...(pkgCwd ? { pkgCwd } : {}),
-            rootPath,
-            shell: resolveShell(scriptsOpt, commandOpt, shellOpt),
-        });
-        return;
-    }
-    // list only (explicit --list without --command)
-    const mergedBag = ((thisCommand.parent ?? null)?.getDotenvCliOptions ?? {});
-    const shellOnly = (opts.shell ?? cfg.shell ?? mergedBag.shell ?? false);
-    await execShellCommandBatch({
-        globs,
-        ignoreErrors,
-        list: true,
-        logger,
-        ...(pkgCwd ? { pkgCwd } : {}),
-        rootPath,
-        shell: (shellOnly ?? false),
-    });
-};
-
-// Per-plugin config schema (optional fields; used as defaults).
-const ScriptSchema = zod.z.union([
-    zod.z.string(),
-    zod.z.object({
-        cmd: zod.z.string(),
-        shell: zod.z.union([zod.z.string(), zod.z.boolean()]).optional(),
-    }),
-]);
-const BatchConfigSchema = zod.z.object({
-    scripts: zod.z.record(zod.z.string(), ScriptSchema).optional(),
-    shell: zod.z.union([zod.z.string(), zod.z.boolean()]).optional(),
-    rootPath: zod.z.string().optional(),
-    globs: zod.z.string().optional(),
-    pkgCwd: zod.z.boolean().optional(),
-});
-
-/**
- * Batch plugin for the GetDotenv CLI host.
- *
- * Mirrors the legacy batch subcommand behavior without altering the shipped CLI.
- * Options:
- * - scripts/shell: used to resolve command and shell behavior per script or global default.
- * - logger: defaults to console.
- */
-const batchPlugin = (opts = {}) => definePlugin({
-    id: 'batch',
-    // Host validates this when config-loader is enabled; plugins may also
-    // re-validate at action time as a safety belt.
-    configSchema: BatchConfigSchema,
-    setup(cli) {
-        const ns = cli.ns('batch');
-        const batchCmd = ns; // capture the parent "batch" command for default-subcommand context
-        const host = cli;
-        const pluginId = 'batch';
-        const GROUP = `plugin:${pluginId}`;
-        ns.description('Batch command execution across multiple working directories.')
-            .enablePositionalOptions()
-            .passThroughOptions()
-            // Dynamic help: show effective defaults from the merged/interpolated plugin config slice.
-            .addOption((() => {
-            const opt = host.createDynamicOption('-p, --pkg-cwd', (cfg) => {
-                const slice = cfg.plugins.batch ?? {};
-                const on = !!slice.pkgCwd;
-                return `use nearest package directory as current working directory${on ? ' (default)' : ''}`;
-            });
-            opt.__group = GROUP;
-            return opt;
-        })())
-            .addOption((() => {
-            const opt = host.createDynamicOption('-r, --root-path <string>', (cfg) => `path to batch root directory from current working directory (default: ${JSON.stringify(cfg.plugins.batch?.rootPath || './')})`);
-            opt.__group = GROUP;
-            return opt;
-        })())
-            .addOption((() => {
-            const opt = host.createDynamicOption('-g, --globs <string>', (cfg) => `space-delimited globs from root path (default: ${JSON.stringify(cfg.plugins.batch?.globs || '*')})`);
-            opt.__group = GROUP;
-            return opt;
-        })())
-            .option('-c, --command <string>', 'command executed according to the base shell resolution')
-            .option('-l, --list', 'list working directories without executing command')
-            .option('-e, --ignore-errors', 'ignore errors and continue with next path')
-            .argument('[command...]')
-            .addCommand(new commander.Command()
-            .name('cmd')
-            .description('execute command, conflicts with --command option (default subcommand)')
-            .enablePositionalOptions()
-            .passThroughOptions()
-            .argument('[command...]')
-            .action(buildDefaultCmdAction(cli, batchCmd, opts)), { isDefault: true })
-            .action(buildParentAction(cli, opts));
-    },
-});
-
-/** 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;
-};
-
-// 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);
-    },
-});
-
-const demoPlugin = () => definePlugin({
-    id: 'demo',
-    setup(cli) {
-        const logger = console;
-        const ns = cli
-            .ns('demo')
-            .description('Educational demo of host/plugin features (context, child exec, scripts/shell)');
-        /**
-         * demo ctx
-         * Print a summary of the current dotenv context.
-         *
-         * Notes:
-         * - The host resolves context once per invocation in a preSubcommand hook
-         *   (added by enhanceGetDotenvCli.passOptions() in the shipped CLI).
-         * - ctx.dotenv contains the final merged values after overlays/dynamics.
-         */
-        ns.command('ctx')
-            .description('Print a summary of the current dotenv context')
-            .action(() => {
-            const ctx = cli.getCtx();
-            const dotenv = ctx?.dotenv ?? {};
-            const keys = Object.keys(dotenv).sort();
-            const sample = keys.slice(0, 5);
-            logger.log('[demo] Context summary:');
-            logger.log(`- keys: ${keys.length.toString()}`);
-            logger.log(`- sample keys: ${sample.join(', ') || '(none)'}`);
-            logger.log('- tip: use "--trace [keys...]" for per-key diagnostics');
-        });
-        /**
-         * demo run [--print KEY]
-         * Execute a small child process that prints a dotenv value.
-         *
-         * Design:
-         * - Use shell-off + argv array to avoid cross-platform quoting pitfalls.
-         * - Inject ctx.dotenv explicitly into the child env.
-         * - Inherit stdio so output streams live (works well outside CI).
-         *
-         * Tip:
-         * - For deterministic capture in CI, run with "--capture" (or set
-         *   GETDOTENV_STDIO=pipe). The shipped CLI honors both.
-         */
-        ns.command('run')
-            .description('Run a small child process under the current dotenv (shell-off)')
-            .option('--print <key>', 'dotenv key to print', 'APP_SETTING')
-            .action(async (opts) => {
-            const key = typeof opts.print === 'string' && opts.print.length > 0
-                ? opts.print
-                : 'APP_SETTING';
-            // Build a minimal node -e payload via argv array (avoid quoting issues).
-            const code = `console.log(process.env.${key} ?? "")`;
-            const ctx = cli.getCtx();
-            const dotenv = (ctx?.dotenv ?? {});
-            // Inherit stdio for an interactive demo. Use --capture for CI.
-            await runCommand(['node', '-e', code], false, {
-                env: buildSpawnEnv(process.env, dotenv),
-                stdio: 'inherit',
-            });
-        });
-        /**
-         * demo script [command...]
-         * Resolve and execute a command using the current scripts table and
-         * shell preference (with per-script overrides).
-         *
-         * How it works:
-         * - We read the merged CLI options persisted by the shipped CLI’s
-         *   passOptions() hook on the current command instance’s parent.
-         * - resolveCommand resolves a script name → cmd or passes through a raw
-         *   command string.
-         * - resolveShell chooses the appropriate shell:
-         *    scripts[name].shell ?? global shell (string|boolean).
-         */
-        ns.command('script')
-            .description('Resolve a command via scripts and execute it with the proper shell')
-            .argument('[command...]')
-            .action(async (commandParts, _opts, thisCommand) => {
-            // Safely access the parent’s merged options (installed by passOptions()).
-            const parent = thisCommand.parent;
-            const bag = (parent?.getDotenvCliOptions ?? {});
-            const input = Array.isArray(commandParts)
-                ? commandParts.map(String).join(' ')
-                : '';
-            if (!input) {
-                logger.log('[demo] Please provide a command or script name, e.g. "echo OK" or "git-status".');
-                return;
-            }
-            const resolved = resolveCommand(bag?.scripts, input);
-            const shell = resolveShell(bag?.scripts, input, bag?.shell);
-            // Compose child env (parent + ctx.dotenv). This mirrors cmd/batch behavior.
-            const ctx = cli.getCtx();
-            const dotenv = (ctx?.dotenv ?? {});
-            await runCommand(resolved, shell, {
-                env: buildSpawnEnv(process.env, dotenv),
-                stdio: 'inherit',
-            });
-        });
-    },
-    /**
-     * Optional: afterResolve can initialize per-plugin state using ctx.dotenv.
-     * For the demo we emit a single breadcrumb only when GETDOTENV_DEBUG is set,
-     * keeping default runs (tests/CI/smoke) quiet.
-     */
-    afterResolve(_cli, ctx) {
-        if (process.env.GETDOTENV_DEBUG) {
-            const keys = Object.keys(ctx.dotenv);
-            if (keys.length > 0) {
-                // Keep noise low; a single-line breadcrumb is sufficient for the demo.
-                console.error('[demo] afterResolve: dotenv keys loaded:', keys.length);
-            }
-        }
-    },
-});
-
-const ensureDir = async (p) => {
-    await fs.ensureDir(p);
-    return p;
-};
-const writeFile = async (dest, data) => {
-    await ensureDir(path.dirname(dest));
-    await fs.writeFile(dest, data, 'utf-8');
-};
-const copyTextFile = async (src, dest, substitutions) => {
-    const contents = await fs.readFile(src, 'utf-8');
-    const out = substitutions && Object.keys(substitutions).length > 0
-        ? Object.entries(substitutions).reduce((acc, [k, v]) => acc.split(k).join(v), contents)
-        : contents;
-    await writeFile(dest, out);
-};
-/**
- * Ensure a set of lines exist (exact match) in a file. Creates the file
- * when missing. Returns whether it was created or changed.
- */
-const ensureLines = async (filePath, lines) => {
-    const exists = await fs.pathExists(filePath);
-    const current = exists ? await fs.readFile(filePath, 'utf-8') : '';
-    const curLines = current.split(/\r?\n/);
-    const have = new Set(curLines.filter((l) => l.length > 0));
-    let mutated = false;
-    for (const l of lines) {
-        if (!have.has(l)) {
-            curLines.push(l);
-            have.add(l);
-            mutated = true;
-        }
-    }
-    // Normalize to LF and ensure trailing newline
-    const next = curLines.filter((l) => l.length > 0).join('\n') + '\n';
-    if (!exists) {
-        await writeFile(filePath, next);
-        return { created: true, changed: true };
-    }
-    if (mutated) {
-        await fs.writeFile(filePath, next, 'utf-8');
-        return { created: false, changed: true };
-    }
-    return { created: false, changed: false };
-};
-
-// Templates root used by the scaffolder
-const TEMPLATES_ROOT = path.resolve('templates');
-
-const planConfigCopies = ({ format, withLocal, destRoot, }) => {
-    const copies = [];
-    if (format === 'json') {
-        copies.push({
-            src: path.join(TEMPLATES_ROOT, 'config', 'json', 'public', 'getdotenv.config.json'),
-            dest: path.join(destRoot, 'getdotenv.config.json'),
-        });
-        if (withLocal) {
-            copies.push({
-                src: path.join(TEMPLATES_ROOT, 'config', 'json', 'local', 'getdotenv.config.local.json'),
-                dest: path.join(destRoot, 'getdotenv.config.local.json'),
-            });
-        }
-    }
-    else if (format === 'yaml') {
-        copies.push({
-            src: path.join(TEMPLATES_ROOT, 'config', 'yaml', 'public', 'getdotenv.config.yaml'),
-            dest: path.join(destRoot, 'getdotenv.config.yaml'),
-        });
-        if (withLocal) {
-            copies.push({
-                src: path.join(TEMPLATES_ROOT, 'config', 'yaml', 'local', 'getdotenv.config.local.yaml'),
-                dest: path.join(destRoot, 'getdotenv.config.local.yaml'),
-            });
-        }
-    }
-    else if (format === 'js') {
-        copies.push({
-            src: path.join(TEMPLATES_ROOT, 'config', 'js', 'getdotenv.config.js'),
-            dest: path.join(destRoot, 'getdotenv.config.js'),
-        });
-    }
-    else {
-        copies.push({
-            src: path.join(TEMPLATES_ROOT, 'config', 'ts', 'getdotenv.config.ts'),
-            dest: path.join(destRoot, 'getdotenv.config.ts'),
-        });
-    }
-    return copies;
-};
-const planCliCopies = ({ cliName, destRoot, }) => {
-    const subs = { __CLI_NAME__: cliName };
-    const base = path.join(destRoot, 'src', 'cli', cliName);
-    return [
-        {
-            src: path.join(TEMPLATES_ROOT, 'cli', 'ts', 'index.ts'),
-            dest: path.join(base, 'index.ts'),
-            subs,
-        },
-        {
-            src: path.join(TEMPLATES_ROOT, 'cli', 'ts', 'plugins', 'hello.ts'),
-            dest: path.join(base, 'plugins', 'hello.ts'),
-            subs,
-        },
-    ];
-};
-
-/**
- * Determine whether the current environment should be treated as non-interactive.
- * CI heuristics include: CI, GITHUB_ACTIONS, BUILDKITE, TEAMCITY_VERSION, TF_BUILD.
- */
-const isNonInteractive = () => {
-    const ciLike = process.env.CI ||
-        process.env.GITHUB_ACTIONS ||
-        process.env.BUILDKITE ||
-        process.env.TEAMCITY_VERSION ||
-        process.env.TF_BUILD;
-    return Boolean(ciLike) || !(node_process.stdin.isTTY && node_process.stdout.isTTY);
-};
-const promptDecision = async (filePath, logger, rl) => {
-    logger.log(`File exists: ${filePath}\nChoose: [o]verwrite, [e]xample, [s]kip, [O]verwrite All, [E]xample All, [S]kip All`);
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-    while (true) {
-        const a = (await rl.question('> ')).trim();
-        const valid = ['o', 'e', 's', 'O', 'E', 'S'];
-        if (valid.includes(a))
-            return a;
-        logger.log('Please enter one of: o e s O E S');
-    }
-};
-
-/**
- * Requirements: Init scaffolding plugin with collision flow and CI detection.
- * Note: Large file scheduled for decomposition; tracked in stan.todo.md.
- */
-const initPlugin = (opts = {}) => definePlugin({
-    id: 'init',
-    setup(cli) {
-        const logger = opts.logger ?? console;
-        const cmd = cli
-            .ns('init')
-            .description('Scaffold getdotenv config files and a host-based CLI skeleton.')
-            .argument('[dest]', 'destination path (default: ./)', '.')
-            .option('--config-format <format>', 'config format: json|yaml|js|ts', 'json')
-            .option('--with-local', 'include .local config variant')
-            .option('--dynamic', 'include dynamic examples (JS/TS configs)')
-            .option('--cli-name <string>', 'CLI name for skeleton and tokens')
-            .option('--force', 'overwrite all existing files')
-            .option('--yes', 'skip all collisions (no overwrite)')
-            .action(async (destArg) => {
-            // Read options directly from the captured command instance.
-            // Cast to a plain record to satisfy exact-optional and lint safety.
-            const o = cmd.opts() ?? {};
-            const destRel = typeof destArg === 'string' && destArg.length > 0 ? destArg : '.';
-            const cwd = process.cwd();
-            const destRoot = path.resolve(cwd, destRel);
-            const formatInput = o.configFormat;
-            const formatRaw = typeof formatInput === 'string'
-                ? formatInput.toLowerCase()
-                : 'json';
-            const format = (['json', 'yaml', 'js', 'ts'].includes(formatRaw)
-                ? formatRaw
-                : 'json');
-            const withLocal = !!o.withLocal;
-            // dynamic flag reserved for future template variants; present for UX compatibility
-            void o.dynamic;
-            // CLI name default: --cli-name | basename(dest) | 'mycli'
-            const cliName = (typeof o.cliName === 'string' && o.cliName.length > 0
-                ? o.cliName
-                : path.basename(destRoot) || 'mycli') || 'mycli';
-            // Precedence: --force > --yes > auto-detect(non-interactive => yes)
-            const force = !!o.force;
-            const yes = !!o.yes || (!force && isNonInteractive());
-            // Build copy plan
-            const cfgCopies = planConfigCopies({ format, withLocal, destRoot });
-            const cliCopies = planCliCopies({ cliName, destRoot });
-            const copies = [...cfgCopies, ...cliCopies];
-            // Interactive state
-            let globalDecision;
-            const rl = promises.createInterface({ input: node_process.stdin, output: node_process.stdout });
-            try {
-                for (const item of copies) {
-                    const exists = await fs.pathExists(item.dest);
-                    if (!exists) {
-                        const subs = item.subs ?? {};
-                        await copyTextFile(item.src, item.dest, subs);
-                        logger.log(`Created ${path.relative(cwd, item.dest)}`);
-                        continue;
-                    }
-                    // Collision
-                    if (force) {
-                        const subs = item.subs ?? {};
-                        await copyTextFile(item.src, item.dest, subs);
-                        logger.log(`Overwrote ${path.relative(cwd, item.dest)}`);
-                        continue;
-                    }
-                    if (yes) {
-                        logger.log(`Skipped ${path.relative(cwd, item.dest)}`);
-                        continue;
-                    }
-                    let decision = globalDecision;
-                    if (!decision) {
-                        const a = await promptDecision(item.dest, logger, rl);
-                        if (a === 'O') {
-                            globalDecision = 'overwrite';
-                            decision = 'overwrite';
-                        }
-                        else if (a === 'E') {
-                            globalDecision = 'example';
-                            decision = 'example';
-                        }
-                        else if (a === 'S') {
-                            globalDecision = 'skip';
-                            decision = 'skip';
-                        }
-                        else {
-                            decision =
-                                a === 'o' ? 'overwrite' : a === 'e' ? 'example' : 'skip';
-                        }
-                    }
-                    if (decision === 'overwrite') {
-                        const subs = item.subs ?? {};
-                        await copyTextFile(item.src, item.dest, subs);
-                        logger.log(`Overwrote ${path.relative(cwd, item.dest)}`);
-                    }
-                    else if (decision === 'example') {
-                        const destEx = `${item.dest}.example`;
-                        const subs = item.subs ?? {};
-                        await copyTextFile(item.src, destEx, subs);
-                        logger.log(`Wrote example ${path.relative(cwd, destEx)}`);
-                    }
-                    else {
-                        logger.log(`Skipped ${path.relative(cwd, item.dest)}`);
-                    }
-                }
-                // Ensure .gitignore includes local config patterns.
-                const giPath = path.join(destRoot, '.gitignore');
-                const { created, changed } = await ensureLines(giPath, [
-                    'getdotenv.config.local.*',
-                    '*.local',
-                ]);
-                if (created) {
-                    logger.log(`Created ${path.relative(cwd, giPath)}`);
-                }
-                else if (changed) {
-                    logger.log(`Updated ${path.relative(cwd, giPath)}`);
-                }
-            }
-            finally {
-                rl.close();
-            }
-        });
-    },
-});
-
-exports.awsPlugin = awsPlugin;
-exports.batchPlugin = batchPlugin;
-exports.cmdPlugin = cmdPlugin;
-exports.demoPlugin = demoPlugin;
-exports.initPlugin = initPlugin;