@karmaniverous/get-dotenv 5.2.2 → 5.2.3

package/dist/plugins.cjs

@@ -0,0 +1,3670 @@
+'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 url = require('url');
+var YAML = require('yaml');
+var nanoid = require('nanoid');
+var dotenv = require('dotenv');
+var crypto = require('crypto');
+var node_process = require('node:process');
+var promises = require('readline/promises');
+
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+// 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;
+};
+
+/**
+ * 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')
+            .configureHelp({ showGlobalOptions: true })
+            .enablePositionalOptions()
+            .passThroughOptions()
+            .allowUnknownOption(true)
+            // Boolean toggles
+            .option('--login-on-demand', 'attempt aws sso login on-demand')
+            .option('--no-login-on-demand', 'disable sso login on-demand')
+            .option('--set-env', 'write resolved values into process.env')
+            .option('--no-set-env', 'do not write resolved values into process.env')
+            .option('--add-ctx', 'mirror results under ctx.plugins.aws')
+            .option('--no-add-ctx', 'do not mirror results under ctx.plugins.aws')
+            // Strings / enums
+            .option('--profile <string>', 'AWS profile name')
+            .option('--region <string>', 'AWS region')
+            .option('--default-region <string>', 'fallback region')
+            .option('--strategy <string>', 'credential acquisition strategy: cli-export|none')
+            // Advanced key overrides
+            .option('--profile-key <string>', 'dotenv/config key for local profile')
+            .option('--profile-fallback-key <string>', 'fallback dotenv/config key for profile')
+            .option('--region-key <string>', 'dotenv/config key for region')
+            // Accept any extra operands so Commander does not error when tokens appear after "--".
+            .argument('[args...]')
+            .action(async (args, opts, thisCommand) => {
+            const self = thisCommand;
+            const parent = (self.parent ?? null);
+            // Access merged root CLI options (installed by passOptions())
+            const rootOpts = (parent?.getDotenvCliOptions ?? {});
+            const capture = process.env.GETDOTENV_STDIO === 'pipe' ||
+                Boolean(rootOpts?.capture);
+            const underTests = process.env.GETDOTENV_TEST === '1' ||
+                typeof process.env.VITEST_WORKER_ID === 'string';
+            // Build overlay cfg from subcommand flags layered over discovered config.
+            const ctx = cli.getCtx();
+            const cfgBase = (ctx?.pluginConfigs?.['aws'] ??
+                {});
+            const overlay = {};
+            // Map boolean toggles (respect explicit --no-*)
+            if (Object.prototype.hasOwnProperty.call(opts, 'loginOnDemand'))
+                overlay.loginOnDemand = Boolean(opts.loginOnDemand);
+            if (Object.prototype.hasOwnProperty.call(opts, 'setEnv'))
+                overlay.setEnv = Boolean(opts.setEnv);
+            if (Object.prototype.hasOwnProperty.call(opts, 'addCtx'))
+                overlay.addCtx = Boolean(opts.addCtx);
+            // Strings/enums
+            if (typeof opts.profile === 'string')
+                overlay.profile = opts.profile;
+            if (typeof opts.region === 'string')
+                overlay.region = opts.region;
+            if (typeof opts.defaultRegion === 'string')
+                overlay.defaultRegion = opts.defaultRegion;
+            if (typeof opts.strategy === 'string')
+                overlay.strategy =
+                    opts.strategy;
+            // Advanced key overrides
+            if (typeof opts.profileKey === 'string')
+                overlay.profileKey = opts.profileKey;
+            if (typeof opts.profileFallbackKey === 'string')
+                overlay.profileFallbackKey = opts.profileFallbackKey;
+            if (typeof opts.regionKey === 'string')
+                overlay.regionKey = opts.regionKey;
+            const cfg = {
+                ...cfgBase,
+                ...overlay,
+            };
+            // Resolve current context with overrides
+            const out = await resolveAwsContext({
+                dotenv: ctx?.dotenv ?? {},
+                cfg,
+            });
+            // Apply env/ctx mirrors per toggles
+            if (cfg.setEnv !== false) {
+                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, 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) {
+                const envBag = getDotenvCliOptions !== undefined
+                    ? { getDotenvCliOptions: JSON.stringify(getDotenvCliOptions) }
+                    : undefined;
+                await runCommand(command, shell, {
+                    cwd: path,
+                    env: buildSpawnEnv(process.env, envBag),
+                    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 || {});
+    // 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),
+                globs,
+                ignoreErrors,
+                list: false,
+                logger: loggerLocal,
+                ...(pkgCwd ? { pkgCwd } : {}),
+                rootPath,
+                shell: resolveShell(scripts, commandOpt, shell),
+            });
+            return;
+        }
+        if (raw.list || localList) {
+            await execShellCommandBatch({
+                globs,
+                ignoreErrors,
+                list: true,
+                logger: loggerLocal,
+                ...(pkgCwd ? { pkgCwd } : {}),
+                rootPath,
+                shell: (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,
+        ...(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 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,
+            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),
+            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
+        ns.description('Batch command execution across multiple working directories.')
+            .enablePositionalOptions()
+            .passThroughOptions()
+            .option('-p, --pkg-cwd', 'use nearest package directory as current working directory')
+            .option('-r, --root-path <string>', 'path to batch root directory from current working directory', './')
+            .option('-g, --globs <string>', 'space-delimited globs from root path', '*')
+            .option('-c, --command <string>', 'command executed according to the base shell resolution')
+            .option('-l, --list', 'list working directories without executing command')
+            .option('-e, --ignore-errors', 'ignore errors and continue with next path')
+            .argument('[command...]')
+            .addCommand(new 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]';
+/**
+ * Produce a shallow redacted copy of an env-like object for display.
+ */
+const redactObject = (obj, opts) => {
+    if (!opts?.redact)
+        return { ...obj };
+    const regs = compile(opts.redactPatterns);
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+        out[k] = v && shouldRedactKey(k, regs) ? MASK : v;
+    }
+    return out;
+};
+/**
+ * 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)
+};
+
+const baseGetDotenvCliOptions = baseRootOptionDefaults;
+
+/** @internal */
+const isPlainObject$1 = (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$1(tVal) && isPlainObject$1(sVal)) {
+            target[key] = mergeInto({ ...tVal }, sVal);
+        }
+        else if (isPlainObject$1(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;
+};
+
+// src/GetDotenvOptions.ts
+const getDotenvOptionsFilename = 'getdotenv.config.json';
+/**
+ * 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 resolveGetDotenvOptions = async (customOptions) => {
+    /**
+     * Resolve {@link GetDotenvOptions} by layering defaults in ascending precedence:
+     *
+     * 1. Base defaults derived from the CLI generator defaults
+     *    ({@link baseGetDotenvCliOptions}).
+     * 2. Local project overrides from a `getdotenv.config.json` in the nearest
+     *    package root (if present).
+     * 3. The provided {@link customOptions}.
+     *
+     * The result preserves explicit empty values and drops only `undefined`.
+     *
+     * @returns Fully-resolved {@link GetDotenvOptions}.
+     *
+     * @example
+     * ```ts
+     * const options = await resolveGetDotenvOptions({ env: 'dev' });
+     * ```
+     */
+    const localPkgDir = await packageDirectory.packageDirectory();
+    const localOptionsPath = localPkgDir
+        ? path.join(localPkgDir, getDotenvOptionsFilename)
+        : undefined;
+    const localOptions = (localOptionsPath && (await fs.exists(localOptionsPath))
+        ? JSON.parse((await fs.readFile(localOptionsPath)).toString())
+        : {});
+    // Merge order: base < local < custom (custom has highest precedence)
+    const mergedCli = defaultsDeep(baseGetDotenvCliOptions, localOptions);
+    const defaultsFromCli = getDotenvCliOptions2Options(mergedCli);
+    const result = defaultsDeep(defaultsFromCli, customOptions);
+    return {
+        ...result, // Keep explicit empty strings/zeros; drop only undefined
+        vars: Object.fromEntries(Object.entries(result.vars ?? {}).filter(([, v]) => v !== undefined)),
+    };
+};
+
+/**
+ * Zod schemas for programmatic GetDotenv options.
+ *
+ * NOTE: These schemas are introduced without wiring to avoid behavior changes.
+ * Legacy paths continue to use existing types/logic. The new plugin host will
+ * use these schemas in strict mode; legacy paths will adopt them in warn mode
+ * later per the staged plan.
+ */
+// Minimal process env representation: string values or undefined to indicate "unset".
+const processEnvSchema = zod.z.record(zod.z.string(), zod.z.string().optional());
+// RAW: all fields optional — undefined means "inherit" from lower layers.
+const getDotenvOptionsSchemaRaw = zod.z.object({
+    defaultEnv: zod.z.string().optional(),
+    dotenvToken: zod.z.string().optional(),
+    dynamicPath: zod.z.string().optional(),
+    // Dynamic map is intentionally wide for now; refine once sources are normalized.
+    dynamic: zod.z.record(zod.z.string(), zod.z.unknown()).optional(),
+    env: zod.z.string().optional(),
+    excludeDynamic: zod.z.boolean().optional(),
+    excludeEnv: zod.z.boolean().optional(),
+    excludeGlobal: zod.z.boolean().optional(),
+    excludePrivate: zod.z.boolean().optional(),
+    excludePublic: zod.z.boolean().optional(),
+    loadProcess: zod.z.boolean().optional(),
+    log: zod.z.boolean().optional(),
+    outputPath: zod.z.string().optional(),
+    paths: zod.z.array(zod.z.string()).optional(),
+    privateToken: zod.z.string().optional(),
+    vars: processEnvSchema.optional(),
+    // Host-only feature flag: guarded integration of config loader/overlay
+    useConfigLoader: zod.z.boolean().optional(),
+});
+// RESOLVED: service-boundary contract (post-inheritance).
+// For Step A, keep identical to RAW (no behavior change). Later stages will// materialize required defaults and narrow shapes as resolution is wired.
+const getDotenvOptionsSchemaResolved = getDotenvOptionsSchemaRaw;
+
+/**
+ * Zod schemas for configuration files discovered by the new loader.
+ *
+ * Notes:
+ * - RAW: all fields optional; shapes are stringly-friendly (paths may be string[] or string).
+ * - RESOLVED: normalized shapes (paths always string[]).
+ * - For JSON/YAML configs, the loader rejects "dynamic" and "schema" (JS/TS-only).
+ */
+// String-only env value map
+const stringMap = zod.z.record(zod.z.string(), zod.z.string());
+const envStringMap = zod.z.record(zod.z.string(), stringMap);
+// Allow string[] or single string for "paths" in RAW; normalize later.
+const rawPathsSchema = zod.z.union([zod.z.array(zod.z.string()), zod.z.string()]).optional();
+const getDotenvConfigSchemaRaw = zod.z.object({
+    dotenvToken: zod.z.string().optional(),
+    privateToken: zod.z.string().optional(),
+    paths: rawPathsSchema,
+    loadProcess: zod.z.boolean().optional(),
+    log: zod.z.boolean().optional(),
+    shell: zod.z.union([zod.z.string(), zod.z.boolean()]).optional(),
+    scripts: zod.z.record(zod.z.string(), zod.z.unknown()).optional(), // Scripts validation left wide; generator validates elsewhere
+    requiredKeys: zod.z.array(zod.z.string()).optional(),
+    schema: zod.z.unknown().optional(), // JS/TS-only; loader rejects in JSON/YAML
+    vars: stringMap.optional(), // public, global
+    envVars: envStringMap.optional(), // public, per-env
+    // Dynamic in config (JS/TS only). JSON/YAML loader will reject if set.
+    dynamic: zod.z.unknown().optional(),
+    // Per-plugin config bag; validated by plugins/host when used.
+    plugins: zod.z.record(zod.z.string(), zod.z.unknown()).optional(),
+});
+// Normalize paths to string[]
+const normalizePaths = (p) => p === undefined ? undefined : Array.isArray(p) ? p : [p];
+const getDotenvConfigSchemaResolved = getDotenvConfigSchemaRaw.transform((raw) => ({
+    ...raw,
+    paths: normalizePaths(raw.paths),
+}));
+
+// Discovery candidates (first match wins per scope/privacy).
+// Order preserves historical JSON/YAML precedence; JS/TS added afterwards.
+const PUBLIC_FILENAMES = [
+    'getdotenv.config.json',
+    'getdotenv.config.yaml',
+    'getdotenv.config.yml',
+    'getdotenv.config.js',
+    'getdotenv.config.mjs',
+    'getdotenv.config.cjs',
+    'getdotenv.config.ts',
+    'getdotenv.config.mts',
+    'getdotenv.config.cts',
+];
+const LOCAL_FILENAMES = [
+    'getdotenv.config.local.json',
+    'getdotenv.config.local.yaml',
+    'getdotenv.config.local.yml',
+    'getdotenv.config.local.js',
+    'getdotenv.config.local.mjs',
+    'getdotenv.config.local.cjs',
+    'getdotenv.config.local.ts',
+    'getdotenv.config.local.mts',
+    'getdotenv.config.local.cts',
+];
+const isYaml = (p) => ['.yaml', '.yml'].includes(path.extname(p).toLowerCase());
+const isJson = (p) => path.extname(p).toLowerCase() === '.json';
+const isJsOrTs = (p) => ['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts'].includes(path.extname(p).toLowerCase());
+// --- Internal JS/TS module loader helpers (default export) ---
+const importDefault$1 = async (fileUrl) => {
+    const mod = (await import(fileUrl));
+    return mod.default;
+};
+const cacheName = (absPath, suffix) => {
+    // sanitized filename with suffix; recompile on mtime changes not tracked here (simplified)
+    const base = path.basename(absPath).replace(/[^a-zA-Z0-9._-]/g, '_');
+    return `${base}.${suffix}.mjs`;
+};
+const ensureDir$1 = async (dir) => {
+    await fs.ensureDir(dir);
+    return dir;
+};
+const loadJsTsDefault = async (absPath) => {
+    const fileUrl = url.pathToFileURL(absPath).toString();
+    const ext = path.extname(absPath).toLowerCase();
+    if (ext === '.js' || ext === '.mjs' || ext === '.cjs') {
+        return importDefault$1(fileUrl);
+    }
+    // Try direct import first in case a TS loader is active.
+    try {
+        const val = await importDefault$1(fileUrl);
+        if (val)
+            return val;
+    }
+    catch {
+        /* fallthrough */
+    }
+    // esbuild bundle to a temp ESM file
+    try {
+        const esbuild = (await import('esbuild'));
+        const outDir = await ensureDir$1(path.resolve('.tsbuild', 'getdotenv-config'));
+        const outfile = path.join(outDir, cacheName(absPath, 'bundle'));
+        await esbuild.build({
+            entryPoints: [absPath],
+            bundle: true,
+            platform: 'node',
+            format: 'esm',
+            target: 'node20',
+            outfile,
+            sourcemap: false,
+            logLevel: 'silent',
+        });
+        return await importDefault$1(url.pathToFileURL(outfile).toString());
+    }
+    catch {
+        /* fallthrough to TS transpile */
+    }
+    // typescript.transpileModule simple transpile (single-file)
+    try {
+        const ts = (await import('typescript'));
+        const src = await fs.readFile(absPath, 'utf-8');
+        const out = ts.transpileModule(src, {
+            compilerOptions: {
+                module: 'ESNext',
+                target: 'ES2022',
+                moduleResolution: 'NodeNext',
+            },
+        }).outputText;
+        const outDir = await ensureDir$1(path.resolve('.tsbuild', 'getdotenv-config'));
+        const outfile = path.join(outDir, cacheName(absPath, 'ts'));
+        await fs.writeFile(outfile, out, 'utf-8');
+        return await importDefault$1(url.pathToFileURL(outfile).toString());
+    }
+    catch {
+        throw new Error(`Unable to load JS/TS config: ${absPath}. Install 'esbuild' for robust bundling or ensure a TS loader.`);
+    }
+};
+/**
+ * Discover JSON/YAML config files in the packaged root and project root.
+ * Order: packaged public → project public → project local. */
+const discoverConfigFiles = async (importMetaUrl) => {
+    const files = [];
+    // Packaged root via importMetaUrl (optional)
+    if (importMetaUrl) {
+        const fromUrl = url.fileURLToPath(importMetaUrl);
+        const packagedRoot = await packageDirectory.packageDirectory({ cwd: fromUrl });
+        if (packagedRoot) {
+            for (const name of PUBLIC_FILENAMES) {
+                const p = path.join(packagedRoot, name);
+                if (await fs.pathExists(p)) {
+                    files.push({ path: p, privacy: 'public', scope: 'packaged' });
+                    break; // only one public file expected per scope
+                }
+            }
+            // By policy, packaged .local is not expected; skip even if present.
+        }
+    }
+    // Project root (from current working directory)
+    const projectRoot = await packageDirectory.packageDirectory();
+    if (projectRoot) {
+        for (const name of PUBLIC_FILENAMES) {
+            const p = path.join(projectRoot, name);
+            if (await fs.pathExists(p)) {
+                files.push({ path: p, privacy: 'public', scope: 'project' });
+                break;
+            }
+        }
+        for (const name of LOCAL_FILENAMES) {
+            const p = path.join(projectRoot, name);
+            if (await fs.pathExists(p)) {
+                files.push({ path: p, privacy: 'local', scope: 'project' });
+                break;
+            }
+        }
+    }
+    return files;
+};
+/**
+ * Load a single config file (JSON/YAML). JS/TS is not supported in this step.
+ * Validates with Zod RAW schema, then normalizes to RESOLVED.
+ *
+ * For JSON/YAML: if a "dynamic" property is present, throws with guidance.
+ * For JS/TS: default export is loaded; "dynamic" is allowed.
+ */
+const loadConfigFile = async (filePath) => {
+    let raw = {};
+    try {
+        const abs = path.resolve(filePath);
+        if (isJsOrTs(abs)) {
+            // JS/TS support: load default export via robust pipeline.
+            const mod = await loadJsTsDefault(abs);
+            raw = mod ?? {};
+        }
+        else {
+            const txt = await fs.readFile(abs, 'utf-8');
+            raw = isJson(abs) ? JSON.parse(txt) : isYaml(abs) ? YAML.parse(txt) : {};
+        }
+    }
+    catch (err) {
+        throw new Error(`Failed to read/parse config: ${filePath}. ${String(err)}`);
+    }
+    // Validate RAW
+    const parsed = getDotenvConfigSchemaRaw.safeParse(raw);
+    if (!parsed.success) {
+        const msgs = parsed.error.issues
+            .map((i) => `${i.path.join('.')}: ${i.message}`)
+            .join('\n');
+        throw new Error(`Invalid config ${filePath}:\n${msgs}`);
+    }
+    // Disallow dynamic and schema in JSON/YAML; allow both in JS/TS.
+    if (!isJsOrTs(filePath) &&
+        (parsed.data.dynamic !== undefined || parsed.data.schema !== undefined)) {
+        throw new Error(`Config ${filePath} specifies unsupported keys for JSON/YAML. ` +
+            `Use JS/TS config for "dynamic" or "schema".`);
+    }
+    return getDotenvConfigSchemaResolved.parse(parsed.data);
+};
+/**
+ * Discover and load configs into resolved shapes, ordered by scope/privacy.
+ * JSON/YAML/JS/TS supported; first match per scope/privacy applies.
+ */
+const resolveGetDotenvConfigSources = async (importMetaUrl) => {
+    const discovered = await discoverConfigFiles(importMetaUrl);
+    const result = {};
+    for (const f of discovered) {
+        const cfg = await loadConfigFile(f.path);
+        if (f.scope === 'packaged') {
+            // packaged public only
+            result.packaged = cfg;
+        }
+        else {
+            result.project ??= {};
+            if (f.privacy === 'public')
+                result.project.public = cfg;
+            else
+                result.project.local = cfg;
+        }
+    }
+    return result;
+};
+
+/**
+ * Dotenv expansion utilities.
+ *
+ * This module implements recursive expansion of environment-variable
+ * references in strings and records. It supports both whitespace and
+ * bracket syntaxes with optional defaults:
+ *
+ * - Whitespace: `$VAR[:default]`
+ * - Bracketed: `${VAR[:default]}`
+ *
+ * Escaped dollar signs (`\$`) are preserved.
+ * Unknown variables resolve to empty string unless a default is provided.
+ */
+/**
+ * Like String.prototype.search but returns the last index.
+ * @internal
+ */
+const searchLast = (str, rgx) => {
+    const matches = Array.from(str.matchAll(rgx));
+    return matches.length > 0 ? (matches.slice(-1)[0]?.index ?? -1) : -1;
+};
+const replaceMatch = (value, match, ref) => {
+    /**
+     * @internal
+     */
+    const group = match[0];
+    const key = match[1];
+    const defaultValue = match[2];
+    if (!key)
+        return value;
+    const replacement = value.replace(group, ref[key] ?? defaultValue ?? '');
+    return interpolate(replacement, ref);
+};
+const interpolate = (value = '', ref = {}) => {
+    /**
+     * @internal
+     */
+    // if value is falsy, return it as is
+    if (!value)
+        return value;
+    // get position of last unescaped dollar sign
+    const lastUnescapedDollarSignIndex = searchLast(value, /(?!(?<=\\))\$/g);
+    // return value if none found
+    if (lastUnescapedDollarSignIndex === -1)
+        return value;
+    // evaluate the value tail
+    const tail = value.slice(lastUnescapedDollarSignIndex);
+    // find whitespace pattern: $KEY:DEFAULT
+    const whitespacePattern = /^\$([\w]+)(?::([^\s]*))?/;
+    const whitespaceMatch = whitespacePattern.exec(tail);
+    if (whitespaceMatch != null)
+        return replaceMatch(value, whitespaceMatch, ref);
+    else {
+        // find bracket pattern: ${KEY:DEFAULT}
+        const bracketPattern = /^\${([\w]+)(?::([^}]*))?}/;
+        const bracketMatch = bracketPattern.exec(tail);
+        if (bracketMatch != null)
+            return replaceMatch(value, bracketMatch, ref);
+    }
+    return value;
+};
+/**
+ * Recursively expands environment variables in a string. Variables may be
+ * presented with optional default as `$VAR[:default]` or `${VAR[:default]}`.
+ * Unknown variables will expand to an empty string.
+ *
+ * @param value - The string to expand.
+ * @param ref - The reference object to use for variable expansion.
+ * @returns The expanded string.
+ *
+ * @example
+ * ```ts
+ * process.env.FOO = 'bar';
+ * dotenvExpand('Hello $FOO'); // "Hello bar"
+ * dotenvExpand('Hello $BAZ:world'); // "Hello world"
+ * ```
+ *
+ * @remarks
+ * The expansion is recursive. If a referenced variable itself contains
+ * references, those will also be expanded until a stable value is reached.
+ * Escaped references (e.g. `\$FOO`) are preserved as literals.
+ */
+const dotenvExpand = (value, ref = process.env) => {
+    const result = interpolate(value, ref);
+    return result ? result.replace(/\\\$/g, '$') : undefined;
+};
+/**
+ * Recursively expands environment variables in the values of a JSON object.
+ * Variables may be presented with optional default as `$VAR[:default]` or
+ * `${VAR[:default]}`. Unknown variables will expand to an empty string.
+ *
+ * @param values - The values object to expand.
+ * @param options - Expansion options.
+ * @returns The value object with expanded string values.
+ *
+ * @example
+ * ```ts
+ * process.env.FOO = 'bar';
+ * dotenvExpandAll({ A: '$FOO', B: 'x${FOO}y' });
+ * // => { A: "bar", B: "xbary" }
+ * ```
+ *
+ * @remarks
+ * Options:
+ * - ref: The reference object to use for expansion (defaults to process.env).
+ * - progressive: Whether to progressively add expanded values to the set of
+ *   reference keys.
+ *
+ * When `progressive` is true, each expanded key becomes available for
+ * subsequent expansions in the same object (left-to-right by object key order).
+ */
+const dotenvExpandAll = (values = {}, options = {}) => Object.keys(values).reduce((acc, key) => {
+    const { ref = process.env, progressive = false } = options;
+    acc[key] = dotenvExpand(values[key], {
+        ...ref,
+        ...(progressive ? acc : {}),
+    });
+    return acc;
+}, {});
+/**
+ * Recursively expands environment variables in a string using `process.env` as
+ * the expansion reference. Variables may be presented with optional default as
+ * `$VAR[:default]` or `${VAR[:default]}`. Unknown variables will expand to an
+ * empty string.
+ *
+ * @param value - The string to expand.
+ * @returns The expanded string.
+ *
+ * @example
+ * ```ts
+ * process.env.FOO = 'bar';
+ * dotenvExpandFromProcessEnv('Hello $FOO'); // "Hello bar"
+ * ```
+ */
+const dotenvExpandFromProcessEnv = (value) => dotenvExpand(value, process.env);
+
+const applyKv = (current, kv) => {
+    if (!kv || Object.keys(kv).length === 0)
+        return current;
+    const expanded = dotenvExpandAll(kv, { ref: current, progressive: true });
+    return { ...current, ...expanded };
+};
+const applyConfigSlice = (current, cfg, env) => {
+    if (!cfg)
+        return current;
+    // kind axis: global then env (env overrides global)
+    const afterGlobal = applyKv(current, cfg.vars);
+    const envKv = env && cfg.envVars ? cfg.envVars[env] : undefined;
+    return applyKv(afterGlobal, envKv);
+};
+/**
+ * Overlay config-provided values onto a base ProcessEnv using precedence axes:
+ * - kind: env \> global
+ * - privacy: local \> public
+ * - source: project \> packaged \> base
+ *
+ * Programmatic explicit vars (if provided) override all config slices.
+ * Progressive expansion is applied within each slice.
+ */
+const overlayEnv = ({ base, env, configs, programmaticVars, }) => {
+    let current = { ...base };
+    // Source: packaged (public -> local)
+    current = applyConfigSlice(current, configs.packaged, env);
+    // Packaged "local" is not expected by policy; if present, honor it.
+    // We do not have a separate object for packaged.local in sources, keep as-is.
+    // Source: project (public -> local)
+    current = applyConfigSlice(current, configs.project?.public, env);
+    current = applyConfigSlice(current, configs.project?.local, env);
+    // Programmatic explicit vars (top of static tier)
+    if (programmaticVars) {
+        const toApply = Object.fromEntries(Object.entries(programmaticVars).filter(([_k, v]) => typeof v === 'string'));
+        current = applyKv(current, toApply);
+    }
+    return current;
+};
+
+/**
+ * Asynchronously read a dotenv file & parse it into an object.
+ *
+ * @param path - Path to dotenv file.
+ * @returns The parsed dotenv object.
+ */
+const readDotenv = async (path) => {
+    try {
+        return (await fs.exists(path)) ? dotenv.parse(await fs.readFile(path)) : {};
+    }
+    catch {
+        return {};
+    }
+};
+
+const importDefault = async (fileUrl) => {
+    const mod = (await import(fileUrl));
+    return mod.default;
+};
+const cacheHash = (absPath, mtimeMs) => crypto.createHash('sha1')
+    .update(absPath)
+    .update(String(mtimeMs))
+    .digest('hex')
+    .slice(0, 12);
+/**
+ * Remove older compiled cache files for a given source base name, keeping
+ * at most `keep` most-recent files. Errors are ignored by design.
+ */
+const cleanupOldCacheFiles = async (cacheDir, baseName, keep = Math.max(1, Number.parseInt(process.env.GETDOTENV_CACHE_KEEP ?? '2'))) => {
+    try {
+        const entries = await fs.readdir(cacheDir);
+        const mine = entries
+            .filter((f) => f.startsWith(`${baseName}.`) && f.endsWith('.mjs'))
+            .map((f) => path.join(cacheDir, f));
+        if (mine.length <= keep)
+            return;
+        const stats = await Promise.all(mine.map(async (p) => ({ p, mtimeMs: (await fs.stat(p)).mtimeMs })));
+        stats.sort((a, b) => b.mtimeMs - a.mtimeMs);
+        const toDelete = stats.slice(keep).map((s) => s.p);
+        await Promise.all(toDelete.map(async (p) => {
+            try {
+                await fs.remove(p);
+            }
+            catch {
+                // best-effort cleanup
+            }
+        }));
+    }
+    catch {
+        // best-effort cleanup
+    }
+};
+/**
+ * Load a module default export from a JS/TS file with robust fallbacks:
+ * - .js/.mjs/.cjs: direct import * - .ts/.mts/.cts/.tsx:
+ *   1) try direct import (if a TS loader is active),
+ *   2) esbuild bundle to a temp ESM file,
+ *   3) typescript.transpileModule fallback for simple modules.
+ *
+ * @param absPath - absolute path to source file
+ * @param cacheDirName - cache subfolder under .tsbuild
+ */
+const loadModuleDefault = async (absPath, cacheDirName) => {
+    const ext = path.extname(absPath).toLowerCase();
+    const fileUrl = url.pathToFileURL(absPath).toString();
+    if (!['.ts', '.mts', '.cts', '.tsx'].includes(ext)) {
+        return importDefault(fileUrl);
+    }
+    // Try direct import first (TS loader active)
+    try {
+        const dyn = await importDefault(fileUrl);
+        if (dyn)
+            return dyn;
+    }
+    catch {
+        /* fall through */
+    }
+    const stat = await fs.stat(absPath);
+    const hash = cacheHash(absPath, stat.mtimeMs);
+    const cacheDir = path.resolve('.tsbuild', cacheDirName);
+    await fs.ensureDir(cacheDir);
+    const cacheFile = path.join(cacheDir, `${path.basename(absPath)}.${hash}.mjs`);
+    // Try esbuild
+    try {
+        const esbuild = (await import('esbuild'));
+        await esbuild.build({
+            entryPoints: [absPath],
+            bundle: true,
+            platform: 'node',
+            format: 'esm',
+            target: 'node20',
+            outfile: cacheFile,
+            sourcemap: false,
+            logLevel: 'silent',
+        });
+        const result = await importDefault(url.pathToFileURL(cacheFile).toString());
+        // Best-effort: trim older cache files for this source.
+        await cleanupOldCacheFiles(cacheDir, path.basename(absPath));
+        return result;
+    }
+    catch {
+        /* fall through to TS transpile */
+    }
+    // TypeScript transpile fallback
+    try {
+        const ts = (await import('typescript'));
+        const code = await fs.readFile(absPath, 'utf-8');
+        const out = ts.transpileModule(code, {
+            compilerOptions: {
+                module: 'ESNext',
+                target: 'ES2022',
+                moduleResolution: 'NodeNext',
+            },
+        }).outputText;
+        await fs.writeFile(cacheFile, out, 'utf-8');
+        const result = await importDefault(url.pathToFileURL(cacheFile).toString());
+        // Best-effort: trim older cache files for this source.
+        await cleanupOldCacheFiles(cacheDir, path.basename(absPath));
+        return result;
+    }
+    catch {
+        // Caller decides final error wording; rethrow for upstream mapping.
+        throw new Error(`Unable to load JS/TS module: ${absPath}. Install 'esbuild' or ensure a TS loader.`);
+    }
+};
+
+/**
+ * Asynchronously process dotenv files of the form `.env[.<ENV>][.<PRIVATE_TOKEN>]`
+ *
+ * @param options - `GetDotenvOptions` object
+ * @returns The combined parsed dotenv object.
+ * * @example Load from the project root with default tokens
+ * ```ts
+ * const vars = await getDotenv();
+ * console.log(vars.MY_SETTING);
+ * ```
+ *
+ * @example Load from multiple paths and a specific environment
+ * ```ts
+ * const vars = await getDotenv({
+ *   env: 'dev',
+ *   dotenvToken: '.testenv',
+ *   privateToken: 'secret',
+ *   paths: ['./', './packages/app'],
+ * });
+ * ```
+ *
+ * @example Use dynamic variables
+ * ```ts
+ * // .env.js default-exports: { DYNAMIC: ({ PREV }) => `${PREV}-suffix` }
+ * const vars = await getDotenv({ dynamicPath: '.env.js' });
+ * ```
+ *
+ * @remarks
+ * - When {@link GetDotenvOptions.loadProcess} is true, the resulting variables are merged
+ *   into `process.env` as a side effect.
+ * - When {@link GetDotenvOptions.outputPath} is provided, a consolidated dotenv file is written.
+ *   The path is resolved after expansion, so it may reference previously loaded vars.
+ *
+ * @throws Error when a dynamic module is present but cannot be imported.
+ * @throws Error when an output path was requested but could not be resolved.
+ */
+const getDotenv = async (options = {}) => {
+    // Apply defaults.
+    const { defaultEnv, dotenvToken = '.env', dynamicPath, env, excludeDynamic = false, excludeEnv = false, excludeGlobal = false, excludePrivate = false, excludePublic = false, loadProcess = false, log = false, logger = console, outputPath, paths = [], privateToken = 'local', vars = {}, } = await resolveGetDotenvOptions(options);
+    // Read .env files.
+    const loaded = paths.length
+        ? await paths.reduce(async (e, p) => {
+            const publicGlobal = excludePublic || excludeGlobal
+                ? Promise.resolve({})
+                : readDotenv(path.resolve(p, dotenvToken));
+            const publicEnv = excludePublic || excludeEnv || (!env && !defaultEnv)
+                ? Promise.resolve({})
+                : readDotenv(path.resolve(p, `${dotenvToken}.${env ?? defaultEnv ?? ''}`));
+            const privateGlobal = excludePrivate || excludeGlobal
+                ? Promise.resolve({})
+                : readDotenv(path.resolve(p, `${dotenvToken}.${privateToken}`));
+            const privateEnv = excludePrivate || excludeEnv || (!env && !defaultEnv)
+                ? Promise.resolve({})
+                : readDotenv(path.resolve(p, `${dotenvToken}.${env ?? defaultEnv ?? ''}.${privateToken}`));
+            const [eResolved, publicGlobalResolved, publicEnvResolved, privateGlobalResolved, privateEnvResolved,] = await Promise.all([
+                e,
+                publicGlobal,
+                publicEnv,
+                privateGlobal,
+                privateEnv,
+            ]);
+            return {
+                ...eResolved,
+                ...publicGlobalResolved,
+                ...publicEnvResolved,
+                ...privateGlobalResolved,
+                ...privateEnvResolved,
+            };
+        }, Promise.resolve({}))
+        : {};
+    const outputKey = nanoid.nanoid();
+    const dotenv = dotenvExpandAll({
+        ...loaded,
+        ...vars,
+        ...(outputPath ? { [outputKey]: outputPath } : {}),
+    }, { progressive: true });
+    // Process dynamic variables. Programmatic option takes precedence over path.
+    if (!excludeDynamic) {
+        let dynamic = undefined;
+        if (options.dynamic && Object.keys(options.dynamic).length > 0) {
+            dynamic = options.dynamic;
+        }
+        else if (dynamicPath) {
+            const absDynamicPath = path.resolve(dynamicPath);
+            if (await fs.exists(absDynamicPath)) {
+                try {
+                    dynamic = await loadModuleDefault(absDynamicPath, 'getdotenv-dynamic');
+                }
+                catch {
+                    // Preserve legacy error text for compatibility with tests/docs.
+                    throw new Error(`Unable to load dynamic TypeScript file: ${absDynamicPath}. ` +
+                        `Install 'esbuild' (devDependency) to enable TypeScript dynamic modules.`);
+                }
+            }
+        }
+        if (dynamic) {
+            try {
+                for (const key in dynamic)
+                    Object.assign(dotenv, {
+                        [key]: typeof dynamic[key] === 'function'
+                            ? dynamic[key](dotenv, env ?? defaultEnv)
+                            : dynamic[key],
+                    });
+            }
+            catch {
+                throw new Error(`Unable to evaluate dynamic variables.`);
+            }
+        }
+    }
+    // Write output file.
+    let resultDotenv = dotenv;
+    if (outputPath) {
+        const outputPathResolved = dotenv[outputKey];
+        if (!outputPathResolved)
+            throw new Error('Output path not found.');
+        const { [outputKey]: _omitted, ...dotenvForOutput } = dotenv;
+        await fs.writeFile(outputPathResolved, Object.keys(dotenvForOutput).reduce((contents, key) => {
+            const value = dotenvForOutput[key] ?? '';
+            return `${contents}${key}=${value.includes('\n') ? `"${value}"` : value}\n`;
+        }, ''), { encoding: 'utf-8' });
+        resultDotenv = dotenvForOutput;
+    }
+    // Log result.
+    if (log) {
+        const redactFlag = options.redact ?? false;
+        const redactPatterns = options.redactPatterns ?? undefined;
+        const redOpts = {};
+        if (redactFlag)
+            redOpts.redact = true;
+        if (redactFlag && Array.isArray(redactPatterns))
+            redOpts.redactPatterns = redactPatterns;
+        const bag = redactFlag
+            ? redactObject(resultDotenv, redOpts)
+            : { ...resultDotenv };
+        logger.log(bag);
+        // Entropy warnings: once-per-key-per-run (presentation only)
+        const warnEntropyVal = options.warnEntropy ?? true;
+        const entropyThresholdVal = options
+            .entropyThreshold;
+        const entropyMinLengthVal = options
+            .entropyMinLength;
+        const entropyWhitelistVal = options
+            .entropyWhitelist;
+        const entOpts = {};
+        if (typeof warnEntropyVal === 'boolean')
+            entOpts.warnEntropy = warnEntropyVal;
+        if (typeof entropyThresholdVal === 'number')
+            entOpts.entropyThreshold = entropyThresholdVal;
+        if (typeof entropyMinLengthVal === 'number')
+            entOpts.entropyMinLength = entropyMinLengthVal;
+        if (Array.isArray(entropyWhitelistVal))
+            entOpts.entropyWhitelist = entropyWhitelistVal;
+        for (const [k, v] of Object.entries(resultDotenv)) {
+            maybeWarnEntropy(k, v, v !== undefined ? 'dotenv' : 'unset', entOpts, (line) => {
+                logger.log(line);
+            });
+        }
+    }
+    // Load process.env.
+    if (loadProcess)
+        Object.assign(process.env, resultDotenv);
+    return resultDotenv;
+};
+
+/**
+ * Deep interpolation utility for string leaves.
+ * - Expands string values using dotenv-style expansion against the provided envRef.
+ * - Preserves non-strings as-is.
+ * - Does not recurse into arrays (arrays are returned unchanged).
+ *
+ * Intended for:
+ * - Phase C option/config interpolation after composing ctx.dotenv.
+ * - Per-plugin config slice interpolation before afterResolve.
+ */
+/** @internal */
+const isPlainObject = (v) => v !== null &&
+    typeof v === 'object' &&
+    !Array.isArray(v) &&
+    Object.getPrototypeOf(v) === Object.prototype;
+/**
+ * Deeply interpolate string leaves against envRef.
+ * Arrays are not recursed into; they are returned unchanged.
+ *
+ * @typeParam T - Shape of the input value.
+ * @param value - Input value (object/array/primitive).
+ * @param envRef - Reference environment for interpolation.
+ * @returns A new value with string leaves interpolated.
+ */
+const interpolateDeep = (value, envRef) => {
+    // Strings: expand and return
+    if (typeof value === 'string') {
+        const out = dotenvExpand(value, envRef);
+        // dotenvExpand returns string | undefined; preserve original on undefined
+        return (out ?? value);
+    }
+    // Arrays: return as-is (no recursion)
+    if (Array.isArray(value)) {
+        return value;
+    }
+    // Plain objects: shallow clone and recurse into values
+    if (isPlainObject(value)) {
+        const src = value;
+        const out = {};
+        for (const [k, v] of Object.entries(src)) {
+            // Recurse for strings/objects; keep arrays as-is; preserve other scalars
+            if (typeof v === 'string')
+                out[k] = dotenvExpand(v, envRef) ?? v;
+            else if (Array.isArray(v))
+                out[k] = v;
+            else if (isPlainObject(v))
+                out[k] = interpolateDeep(v, envRef);
+            else
+                out[k] = v;
+        }
+        return out;
+    }
+    // Other primitives/types: return as-is
+    return value;
+};
+
+/**
+ * Compute the dotenv context for the host (uses the config loader/overlay path).
+ * - Resolves and validates options strictly (host-only).
+ * - Applies file cascade, overlays, dynamics, and optional effects.
+ * - Merges and validates per-plugin config slices (when provided).
+ *
+ * @param customOptions - Partial options from the current invocation.
+ * @param plugins - Installed plugins (for config validation).
+ * @param hostMetaUrl - import.meta.url of the host module (for packaged root discovery). */
+const computeContext = async (customOptions, plugins, hostMetaUrl) => {
+    const optionsResolved = await resolveGetDotenvOptions(customOptions);
+    const validated = getDotenvOptionsSchemaResolved.parse(optionsResolved);
+    // Always-on loader path
+    // 1) Base from files only (no dynamic, no programmatic vars)
+    const base = await getDotenv({
+        ...validated,
+        // Build a pure base without side effects or logging.
+        excludeDynamic: true,
+        vars: {},
+        log: false,
+        loadProcess: false,
+        outputPath: undefined,
+    });
+    // 2) Discover config sources and overlay
+    const sources = await resolveGetDotenvConfigSources(hostMetaUrl);
+    const dotenvOverlaid = overlayEnv({
+        base,
+        env: validated.env ?? validated.defaultEnv,
+        configs: sources,
+        ...(validated.vars ? { programmaticVars: validated.vars } : {}),
+    });
+    // Helper to apply a dynamic map progressively.
+    const applyDynamic = (target, dynamic, env) => {
+        if (!dynamic)
+            return;
+        for (const key of Object.keys(dynamic)) {
+            const value = typeof dynamic[key] === 'function'
+                ? dynamic[key](target, env)
+                : dynamic[key];
+            Object.assign(target, { [key]: value });
+        }
+    };
+    // 3) Apply dynamics in order
+    const dotenv = { ...dotenvOverlaid };
+    applyDynamic(dotenv, validated.dynamic, validated.env ?? validated.defaultEnv);
+    applyDynamic(dotenv, (sources.packaged?.dynamic ?? undefined), validated.env ?? validated.defaultEnv);
+    applyDynamic(dotenv, (sources.project?.public?.dynamic ?? undefined), validated.env ?? validated.defaultEnv);
+    applyDynamic(dotenv, (sources.project?.local?.dynamic ?? undefined), validated.env ?? validated.defaultEnv);
+    // file dynamicPath (lowest)
+    if (validated.dynamicPath) {
+        const absDynamicPath = path.resolve(validated.dynamicPath);
+        try {
+            const dyn = await loadModuleDefault(absDynamicPath, 'getdotenv-dynamic-host');
+            applyDynamic(dotenv, dyn, validated.env ?? validated.defaultEnv);
+        }
+        catch {
+            throw new Error(`Unable to load dynamic from ${validated.dynamicPath}`);
+        }
+    }
+    // 4) Output/log/process merge
+    if (validated.outputPath) {
+        await fs.writeFile(validated.outputPath, Object.keys(dotenv).reduce((contents, key) => {
+            const value = dotenv[key] ?? '';
+            return `${contents}${key}=${value.includes('\n') ? `"${value}"` : value}\n`;
+        }, ''), { encoding: 'utf-8' });
+    }
+    const logger = validated.logger ?? console;
+    if (validated.log)
+        logger.log(dotenv);
+    if (validated.loadProcess)
+        Object.assign(process.env, dotenv);
+    // 5) Merge and validate per-plugin config (packaged < project.public < project.local)
+    const packagedPlugins = (sources.packaged &&
+        sources.packaged.plugins) ??
+        {};
+    const publicPlugins = (sources.project?.public &&
+        sources.project.public.plugins) ??
+        {};
+    const localPlugins = (sources.project?.local &&
+        sources.project.local.plugins) ??
+        {};
+    const mergedPluginConfigs = defaultsDeep({}, packagedPlugins, publicPlugins, localPlugins);
+    for (const p of plugins) {
+        if (!p.id)
+            continue;
+        const slice = mergedPluginConfigs[p.id];
+        if (slice === undefined)
+            continue;
+        // Per-plugin interpolation just before validation/afterResolve:
+        // precedence: process.env wins over ctx.dotenv for slice defaults.
+        const envRef = {
+            ...dotenv,
+            ...process.env,
+        };
+        const interpolated = interpolateDeep(slice, envRef);
+        // Validate if a schema is provided; otherwise accept interpolated slice as-is.
+        if (p.configSchema) {
+            const parsed = p.configSchema.safeParse(interpolated);
+            if (!parsed.success) {
+                const msgs = parsed.error.issues
+                    .map((i) => `${i.path.join('.')}: ${i.message}`)
+                    .join('\n');
+                throw new Error(`Invalid config for plugin '${p.id}':\n${msgs}`);
+            }
+            mergedPluginConfigs[p.id] = parsed.data;
+        }
+        else {
+            mergedPluginConfigs[p.id] = interpolated;
+        }
+    }
+    return {
+        optionsResolved: validated,
+        dotenv: dotenv,
+        plugins: {},
+        pluginConfigs: mergedPluginConfigs,
+    };
+};
+
+const HOST_META_URL = (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('plugins.cjs', document.baseURI).href));
+const CTX_SYMBOL = Symbol('GetDotenvCli.ctx');
+const OPTS_SYMBOL = Symbol('GetDotenvCli.options');
+const HELP_HEADER_SYMBOL = Symbol('GetDotenvCli.helpHeader');
+/**
+ * Plugin-first CLI host for get-dotenv. Extends Commander.Command.
+ *
+ * Responsibilities:
+ * - Resolve options strictly and compute dotenv context (resolveAndLoad).
+ * - Expose a stable accessor for the current context (getCtx).
+ * - Provide a namespacing helper (ns).
+ * - Support composable plugins with parent → children install and afterResolve.
+ *
+ * NOTE: This host is additive and does not alter the legacy CLI.
+ */
+class GetDotenvCli extends commander.Command {
+    /** Registered top-level plugins (composition happens via .use()) */
+    _plugins = [];
+    /** One-time installation guard */
+    _installed = false;
+    /** Optional header line to prepend in help output */
+    [HELP_HEADER_SYMBOL];
+    constructor(alias = 'getdotenv') {
+        super(alias);
+        // Ensure subcommands that use passThroughOptions can be attached safely.
+        // Commander requires parent commands to enable positional options when a
+        // child uses passThroughOptions.
+        this.enablePositionalOptions();
+        // Configure grouped help: show only base options in default "Options";
+        // append App/Plugin sections after default help.
+        this.configureHelp({
+            visibleOptions: (cmd) => {
+                const all = cmd.options ??
+                    [];
+                const base = all.filter((opt) => {
+                    const group = opt.__group;
+                    return group === 'base';
+                });
+                // Sort: short-aliased options first, then long-only; stable by flags.
+                const hasShort = (opt) => {
+                    const flags = opt.flags ?? '';
+                    // Matches "-x," or starting "-x " before any long
+                    return /(^|\s|,)-[A-Za-z]/.test(flags);
+                };
+                const byFlags = (opt) => opt.flags ?? '';
+                base.sort((a, b) => {
+                    const aS = hasShort(a) ? 1 : 0;
+                    const bS = hasShort(b) ? 1 : 0;
+                    return bS - aS || byFlags(a).localeCompare(byFlags(b));
+                });
+                return base;
+            },
+        });
+        this.addHelpText('beforeAll', () => {
+            const header = this[HELP_HEADER_SYMBOL];
+            return header && header.length > 0 ? `${header}\n\n` : '';
+        });
+        this.addHelpText('afterAll', (ctx) => this.#renderOptionGroups(ctx.command));
+        // Skeleton preSubcommand hook: produce a context if absent, without
+        // mutating process.env. The passOptions hook (when installed) will    // compute the final context using merged CLI options; keeping
+        // loadProcess=false here avoids leaking dotenv values into the parent
+        // process env before subcommands execute.
+        this.hook('preSubcommand', async () => {
+            if (this.getCtx())
+                return;
+            await this.resolveAndLoad({ loadProcess: false });
+        });
+    }
+    /**
+     * Resolve options (strict) and compute dotenv context.   * Stores the context on the instance under a symbol.
+     */
+    async resolveAndLoad(customOptions = {}) {
+        // Resolve defaults, then validate strictly under the new host.
+        const optionsResolved = await resolveGetDotenvOptions(customOptions);
+        getDotenvOptionsSchemaResolved.parse(optionsResolved);
+        // Delegate the heavy lifting to the shared helper (guarded path supported).
+        const ctx = await computeContext(optionsResolved, this._plugins, HOST_META_URL);
+        // Persist context on the instance for later access.
+        this[CTX_SYMBOL] =
+            ctx;
+        // Ensure plugins are installed exactly once, then run afterResolve.
+        await this.install();
+        await this._runAfterResolve(ctx);
+        return ctx;
+    }
+    /**
+     * Retrieve the current invocation context (if any).
+     */
+    getCtx() {
+        return this[CTX_SYMBOL];
+    }
+    /**
+     * Retrieve the merged root CLI options bag (if set by passOptions()).
+     * Downstream-safe: no generics required.
+     */
+    getOptions() {
+        return this[OPTS_SYMBOL];
+    }
+    /** Internal: set the merged root options bag for this run. */
+    _setOptionsBag(bag) {
+        this[OPTS_SYMBOL] = bag;
+    }
+    /**   * Convenience helper to create a namespaced subcommand.
+     */
+    ns(name) {
+        return this.command(name);
+    }
+    /**
+     * Tag options added during the provided callback as 'app' for grouped help.
+     * Allows downstream apps to demarcate their root-level options.
+     */
+    tagAppOptions(fn) {
+        const root = this;
+        const originalAddOption = root.addOption.bind(root);
+        const originalOption = root.option.bind(root);
+        const tagLatest = (cmd, group) => {
+            const optsArr = cmd.options;
+            if (Array.isArray(optsArr) && optsArr.length > 0) {
+                const last = optsArr[optsArr.length - 1];
+                last.__group = group;
+            }
+        };
+        root.addOption = function patchedAdd(opt) {
+            opt.__group = 'app';
+            return originalAddOption(opt);
+        };
+        root.option = function patchedOption(...args) {
+            const ret = originalOption(...args);
+            tagLatest(this, 'app');
+            return ret;
+        };
+        try {
+            return fn(root);
+        }
+        finally {
+            root.addOption = originalAddOption;
+            root.option = originalOption;
+        }
+    }
+    /**
+     * Branding helper: set CLI name/description/version and optional help header.
+     * If version is omitted and importMetaUrl is provided, attempts to read the
+     * nearest package.json version (best-effort; non-fatal on failure).
+     */
+    async brand(args) {
+        const { name, description, version, importMetaUrl, helpHeader } = args;
+        if (typeof name === 'string' && name.length > 0)
+            this.name(name);
+        if (typeof description === 'string')
+            this.description(description);
+        let v = version;
+        if (!v && importMetaUrl) {
+            try {
+                const fromUrl = url.fileURLToPath(importMetaUrl);
+                const pkgDir = await packageDirectory.packageDirectory({ cwd: fromUrl });
+                if (pkgDir) {
+                    const txt = await fs.readFile(`${pkgDir}/package.json`, 'utf-8');
+                    const pkg = JSON.parse(txt);
+                    if (pkg.version)
+                        v = pkg.version;
+                }
+            }
+            catch {
+                // best-effort only
+            }
+        }
+        if (v)
+            this.version(v);
+        // Help header:
+        // - If caller provides helpHeader, use it.
+        // - Otherwise, when a version is known, default to "<name> v<version>".
+        if (typeof helpHeader === 'string') {
+            this[HELP_HEADER_SYMBOL] = helpHeader;
+        }
+        else if (v) {
+            // Use the current command name (possibly overridden by 'name' above).
+            const header = `${this.name()} v${v}`;
+            this[HELP_HEADER_SYMBOL] = header;
+        }
+        return this;
+    }
+    /**
+     * Register a plugin for installation (parent level).
+     * Installation occurs on first resolveAndLoad() (or explicit install()).
+     */
+    use(plugin) {
+        this._plugins.push(plugin);
+        // Immediately run setup so subcommands exist before parsing.
+        const setupOne = (p) => {
+            p.setup(this);
+            for (const child of p.children)
+                setupOne(child);
+        };
+        setupOne(plugin);
+        return this;
+    }
+    /**
+     * Install all registered plugins in parent → children (pre-order).
+     * Runs only once per CLI instance.
+     */
+    async install() {
+        // Setup is performed immediately in use(); here we only guard for afterResolve.
+        this._installed = true;
+        // Satisfy require-await without altering behavior.
+        await Promise.resolve();
+    }
+    /**
+     * Run afterResolve hooks for all plugins (parent → children).
+     */
+    async _runAfterResolve(ctx) {
+        const run = async (p) => {
+            if (p.afterResolve)
+                await p.afterResolve(this, ctx);
+            for (const child of p.children)
+                await run(child);
+        };
+        for (const p of this._plugins)
+            await run(p);
+    }
+    // Render App/Plugin grouped options appended after default help.
+    #renderOptionGroups(cmd) {
+        const all = cmd.options ?? [];
+        const byGroup = new Map();
+        for (const o of all) {
+            const opt = o;
+            const g = opt.__group;
+            if (!g || g === 'base')
+                continue; // base handled by default help
+            const rows = byGroup.get(g) ?? [];
+            rows.push({
+                flags: opt.flags ?? '',
+                description: opt.description ?? '',
+            });
+            byGroup.set(g, rows);
+        }
+        if (byGroup.size === 0)
+            return '';
+        const renderRows = (title, rows) => {
+            const width = Math.min(40, rows.reduce((m, r) => Math.max(m, r.flags.length), 0));
+            // Sort within group: short-aliased flags first
+            rows.sort((a, b) => {
+                const aS = /(^|\s|,)-[A-Za-z]/.test(a.flags) ? 1 : 0;
+                const bS = /(^|\s|,)-[A-Za-z]/.test(b.flags) ? 1 : 0;
+                return bS - aS || a.flags.localeCompare(b.flags);
+            });
+            const lines = rows
+                .map((r) => {
+                const pad = ' '.repeat(Math.max(2, width - r.flags.length + 2));
+                return `  ${r.flags}${pad}${r.description}`.trimEnd();
+            })
+                .join('\n');
+            return `\n${title}:\n${lines}\n`;
+        };
+        let out = '';
+        // App options (if any)
+        const app = byGroup.get('app');
+        if (app && app.length > 0) {
+            out += renderRows('App options', app);
+        }
+        // Plugin groups sorted by id
+        const pluginKeys = Array.from(byGroup.keys()).filter((k) => k.startsWith('plugin:'));
+        pluginKeys.sort((a, b) => a.localeCompare(b));
+        for (const k of pluginKeys) {
+            const id = k.slice('plugin:'.length) || '(unknown)';
+            const rows = byGroup.get(k) ?? [];
+            if (rows.length > 0) {
+                out += renderRows(`Plugin options — ${id}`, rows);
+            }
+        }
+        return out;
+    }
+}
+
+/**
+ * Validate a composed env against config-provided validation surfaces.
+ * Precedence for validation definitions:
+ *   project.local -\> project.public -\> packaged
+ *
+ * Behavior:
+ * - If a JS/TS `schema` is present, use schema.safeParse(finalEnv).
+ * - Else if `requiredKeys` is present, check presence (value !== undefined).
+ * - Returns a flat list of issue strings; caller decides warn vs fail.
+ */
+const validateEnvAgainstSources = (finalEnv, sources) => {
+    const pick = (getter) => {
+        const pl = sources.project?.local;
+        const pp = sources.project?.public;
+        const pk = sources.packaged;
+        return ((pl && getter(pl)) ||
+            (pp && getter(pp)) ||
+            (pk && getter(pk)) ||
+            undefined);
+    };
+    const schema = pick((cfg) => cfg['schema']);
+    if (schema &&
+        typeof schema.safeParse === 'function') {
+        try {
+            const parsed = schema.safeParse(finalEnv);
+            if (!parsed.success) {
+                // Try to render zod-style issues when available.
+                const err = parsed.error;
+                const issues = Array.isArray(err.issues) && err.issues.length > 0
+                    ? err.issues.map((i) => {
+                        const path = Array.isArray(i.path) ? i.path.join('.') : '';
+                        const msg = i.message ?? 'Invalid value';
+                        return path ? `[schema] ${path}: ${msg}` : `[schema] ${msg}`;
+                    })
+                    : ['[schema] validation failed'];
+                return issues;
+            }
+            return [];
+        }
+        catch {
+            // If schema invocation fails, surface a single diagnostic.
+            return [
+                '[schema] validation failed (unable to execute schema.safeParse)',
+            ];
+        }
+    }
+    const requiredKeys = pick((cfg) => cfg['requiredKeys']);
+    if (Array.isArray(requiredKeys) && requiredKeys.length > 0) {
+        const missing = requiredKeys.filter((k) => finalEnv[k] === undefined);
+        if (missing.length > 0) {
+            return missing.map((k) => `[requiredKeys] missing: ${k}`);
+        }
+    }
+    return [];
+};
+
+/**
+ * Attach legacy root flags to a Commander program.
+ * Uses provided defaults to render help labels without coupling to generators.
+ */
+const attachRootOptions = (program, defaults, opts) => {
+    // Install temporary wrappers to tag all options added here as "base".
+    const GROUP = 'base';
+    const tagLatest = (cmd, group) => {
+        const optsArr = cmd.options;
+        if (Array.isArray(optsArr) && optsArr.length > 0) {
+            const last = optsArr[optsArr.length - 1];
+            last.__group = group;
+        }
+    };
+    const originalAddOption = program.addOption.bind(program);
+    const originalOption = program.option.bind(program);
+    program.addOption = function patchedAdd(opt) {
+        // Tag before adding, in case consumers inspect the Option directly.
+        opt.__group = GROUP;
+        const ret = originalAddOption(opt);
+        return ret;
+    };
+    program.option = function patchedOption(...args) {
+        const ret = originalOption(...args);
+        tagLatest(this, GROUP);
+        return ret;
+    };
+    const { defaultEnv, dotenvToken, dynamicPath, env, excludeDynamic, excludeEnv, excludeGlobal, excludePrivate, excludePublic, loadProcess, log, outputPath, paths, pathsDelimiter, pathsDelimiterPattern, privateToken, scripts, shell, varsAssignor, varsAssignorPattern, varsDelimiter, varsDelimiterPattern, } = defaults ?? {};
+    const va = typeof defaults?.varsAssignor === 'string' ? defaults.varsAssignor : '=';
+    const vd = typeof defaults?.varsDelimiter === 'string' ? defaults.varsDelimiter : ' ';
+    // Build initial chain.
+    let p = program
+        .enablePositionalOptions()
+        .passThroughOptions()
+        .option('-e, --env <string>', `target environment (dotenv-expanded)`, dotenvExpandFromProcessEnv, env);
+    p = p.option('-v, --vars <string>', `extra variables expressed as delimited key-value pairs (dotenv-expanded): ${[
+        ['KEY1', 'VAL1'],
+        ['KEY2', 'VAL2'],
+    ]
+        .map((v) => v.join(va))
+        .join(vd)}`, dotenvExpandFromProcessEnv);
+    // Optional legacy root command flag (kept for generated CLI compatibility).
+    // Default is OFF; the generator opts in explicitly.
+    if (opts?.includeCommandOption === true) {
+        p = p.option('-c, --command <string>', 'command executed according to the --shell option, conflicts with cmd subcommand (dotenv-expanded)', dotenvExpandFromProcessEnv);
+    }
+    p = p
+        .option('-o, --output-path <string>', 'consolidated output file  (dotenv-expanded)', dotenvExpandFromProcessEnv, outputPath)
+        .addOption(new commander.Option('-s, --shell [string]', (() => {
+        let defaultLabel = '';
+        if (shell !== undefined) {
+            if (typeof shell === 'boolean') {
+                defaultLabel = ' (default OS shell)';
+            }
+            else if (typeof shell === 'string') {
+                // Safe string interpolation
+                defaultLabel = ` (default ${shell})`;
+            }
+        }
+        return `command execution shell, no argument for default OS shell or provide shell string${defaultLabel}`;
+    })()).conflicts('shellOff'))
+        .addOption(new commander.Option('-S, --shell-off', `command execution shell OFF${!shell ? ' (default)' : ''}`).conflicts('shell'))
+        .addOption(new commander.Option('-p, --load-process', `load variables to process.env ON${loadProcess ? ' (default)' : ''}`).conflicts('loadProcessOff'))
+        .addOption(new commander.Option('-P, --load-process-off', `load variables to process.env OFF${!loadProcess ? ' (default)' : ''}`).conflicts('loadProcess'))
+        .addOption(new commander.Option('-a, --exclude-all', `exclude all dotenv variables from loading ON${excludeDynamic &&
+        ((excludeEnv && excludeGlobal) || (excludePrivate && excludePublic))
+        ? ' (default)'
+        : ''}`).conflicts('excludeAllOff'))
+        .addOption(new commander.Option('-A, --exclude-all-off', `exclude all dotenv variables from loading OFF (default)`).conflicts('excludeAll'))
+        .addOption(new commander.Option('-z, --exclude-dynamic', `exclude dynamic dotenv variables from loading ON${excludeDynamic ? ' (default)' : ''}`).conflicts('excludeDynamicOff'))
+        .addOption(new commander.Option('-Z, --exclude-dynamic-off', `exclude dynamic dotenv variables from loading OFF${!excludeDynamic ? ' (default)' : ''}`).conflicts('excludeDynamic'))
+        .addOption(new commander.Option('-n, --exclude-env', `exclude environment-specific dotenv variables from loading${excludeEnv ? ' (default)' : ''}`).conflicts('excludeEnvOff'))
+        .addOption(new commander.Option('-N, --exclude-env-off', `exclude environment-specific dotenv variables from loading OFF${!excludeEnv ? ' (default)' : ''}`).conflicts('excludeEnv'))
+        .addOption(new commander.Option('-g, --exclude-global', `exclude global dotenv variables from loading ON${excludeGlobal ? ' (default)' : ''}`).conflicts('excludeGlobalOff'))
+        .addOption(new commander.Option('-G, --exclude-global-off', `exclude global dotenv variables from loading OFF${!excludeGlobal ? ' (default)' : ''}`).conflicts('excludeGlobal'))
+        .addOption(new commander.Option('-r, --exclude-private', `exclude private dotenv variables from loading ON${excludePrivate ? ' (default)' : ''}`).conflicts('excludePrivateOff'))
+        .addOption(new commander.Option('-R, --exclude-private-off', `exclude private dotenv variables from loading OFF${!excludePrivate ? ' (default)' : ''}`).conflicts('excludePrivate'))
+        .addOption(new commander.Option('-u, --exclude-public', `exclude public dotenv variables from loading ON${excludePublic ? ' (default)' : ''}`).conflicts('excludePublicOff'))
+        .addOption(new commander.Option('-U, --exclude-public-off', `exclude public dotenv variables from loading OFF${!excludePublic ? ' (default)' : ''}`).conflicts('excludePublic'))
+        .addOption(new commander.Option('-l, --log', `console log loaded variables ON${log ? ' (default)' : ''}`).conflicts('logOff'))
+        .addOption(new commander.Option('-L, --log-off', `console log loaded variables OFF${!log ? ' (default)' : ''}`).conflicts('log'))
+        .option('--capture', 'capture child process stdio for commands (tests/CI)')
+        .option('--redact', 'mask secret-like values in logs/trace (presentation-only)')
+        .option('--default-env <string>', 'default target environment', dotenvExpandFromProcessEnv, defaultEnv)
+        .option('--dotenv-token <string>', 'dotenv-expanded token indicating a dotenv file', dotenvExpandFromProcessEnv, dotenvToken)
+        .option('--dynamic-path <string>', 'dynamic variables path (.js or .ts; .ts is auto-compiled when esbuild is available, otherwise precompile)', dotenvExpandFromProcessEnv, dynamicPath)
+        .option('--paths <string>', 'dotenv-expanded delimited list of paths to dotenv directory', dotenvExpandFromProcessEnv, paths)
+        .option('--paths-delimiter <string>', 'paths delimiter string', pathsDelimiter)
+        .option('--paths-delimiter-pattern <string>', 'paths delimiter regex pattern', pathsDelimiterPattern)
+        .option('--private-token <string>', 'dotenv-expanded token indicating private variables', dotenvExpandFromProcessEnv, privateToken)
+        .option('--vars-delimiter <string>', 'vars delimiter string', varsDelimiter)
+        .option('--vars-delimiter-pattern <string>', 'vars delimiter regex pattern', varsDelimiterPattern)
+        .option('--vars-assignor <string>', 'vars assignment operator string', varsAssignor)
+        .option('--vars-assignor-pattern <string>', 'vars assignment operator regex pattern', varsAssignorPattern)
+        // Hidden scripts pipe-through (stringified)
+        .addOption(new commander.Option('--scripts <string>')
+        .default(JSON.stringify(scripts))
+        .hideHelp());
+    // Diagnostics: opt-in tracing; optional variadic keys after the flag.
+    p = p.option('--trace [keys...]', 'emit diagnostics for child env composition (optional keys)');
+    // Validation: strict mode fails on env validation issues (warn by default).
+    p = p.option('--strict', 'fail on env validation errors (schema/requiredKeys)');
+    // Entropy diagnostics (presentation-only)
+    p = p
+        .addOption(new commander.Option('--entropy-warn', 'enable entropy warnings (default on)').conflicts('entropyWarnOff'))
+        .addOption(new commander.Option('--entropy-warn-off', 'disable entropy warnings').conflicts('entropyWarn'))
+        .option('--entropy-threshold <number>', 'entropy bits/char threshold (default 3.8)')
+        .option('--entropy-min-length <number>', 'min length to examine for entropy (default 16)')
+        .option('--entropy-whitelist <pattern...>', 'suppress entropy warnings when key matches any regex pattern')
+        .option('--redact-pattern <pattern...>', 'additional key-match regex patterns to trigger redaction');
+    // Restore original methods to avoid tagging future additions outside base.
+    program.addOption = originalAddOption;
+    program.option = originalOption;
+    return p;
+};
+
+/**
+ * Resolve a tri-state optional boolean flag under exactOptionalPropertyTypes.
+ * - If the user explicitly enabled the flag, return true.
+ * - If the user explicitly disabled (the "...-off" variant), return undefined (unset).
+ * - Otherwise, adopt the default (true → set; false/undefined → unset).
+ *
+ * @param exclude - The "on" flag value as parsed by Commander.
+ * @param excludeOff - The "off" toggle (present when specified) as parsed by Commander.
+ * @param defaultValue - The generator default to adopt when no explicit toggle is present.
+ * @returns boolean | undefined — use `undefined` to indicate "unset" (do not emit).
+ *
+ * @example
+ * ```ts
+ * resolveExclusion(undefined, undefined, true); // => true
+ * ```
+ */
+const resolveExclusion = (exclude, excludeOff, defaultValue) => exclude ? true : excludeOff ? undefined : defaultValue ? true : undefined;
+/**
+ * Resolve an optional flag with "--exclude-all" overrides.
+ * If excludeAll is set and the individual "...-off" is not, force true.
+ * If excludeAllOff is set and the individual flag is not explicitly set, unset.
+ * Otherwise, adopt the default (true → set; false/undefined → unset).
+ *
+ * @param exclude - Individual include/exclude flag.
+ * @param excludeOff - Individual "...-off" flag.
+ * @param defaultValue - Default for the individual flag.
+ * @param excludeAll - Global "exclude-all" flag.
+ * @param excludeAllOff - Global "exclude-all-off" flag.
+ *
+ * @example
+ * resolveExclusionAll(undefined, undefined, false, true, undefined) =\> true
+ */
+const resolveExclusionAll = (exclude, excludeOff, defaultValue, excludeAll, excludeAllOff) => 
+// Order of precedence:
+// 1) Individual explicit "on" wins outright.
+// 2) Individual explicit "off" wins over any global.
+// 3) Global exclude-all forces true when not explicitly turned off.
+// 4) Global exclude-all-off unsets when the individual wasn't explicitly enabled.
+// 5) Fall back to the default (true => set; false/undefined => unset).
+(() => {
+    // Individual "on"
+    if (exclude === true)
+        return true;
+    // Individual "off"
+    if (excludeOff === true)
+        return undefined;
+    // Global "exclude-all" ON (unless explicitly turned off)
+    if (excludeAll === true)
+        return true;
+    // Global "exclude-all-off" (unless explicitly enabled)
+    if (excludeAllOff === true)
+        return undefined;
+    // Default
+    return defaultValue ? true : undefined;
+})();
+/**
+ * exactOptionalPropertyTypes-safe setter for optional boolean flags:
+ * delete when undefined; assign when defined — without requiring an index signature on T.
+ *
+ * @typeParam T - Target object type.
+ * @param obj - The object to write to.
+ * @param key - The optional boolean property key of {@link T}.
+ * @param value - The value to set or `undefined` to unset.
+ *
+ * @remarks
+ * Writes through a local `Record<string, unknown>` view to avoid requiring an index signature on {@link T}.
+ */
+const setOptionalFlag = (obj, key, value) => {
+    const target = obj;
+    const k = key;
+    // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+    if (value === undefined)
+        delete target[k];
+    else
+        target[k] = value;
+};
+
+/**
+ * Merge and normalize raw Commander options (current + parent + defaults)
+ * into a GetDotenvCliOptions-like object. Types are intentionally wide to
+ * avoid cross-layer coupling; callers may cast as needed.
+ */
+const resolveCliOptions = (rawCliOptions, defaults, parentJson) => {
+    const parent = typeof parentJson === 'string' && parentJson.length > 0
+        ? JSON.parse(parentJson)
+        : undefined;
+    const { command, debugOff, excludeAll, excludeAllOff, excludeDynamicOff, excludeEnvOff, excludeGlobalOff, excludePrivateOff, excludePublicOff, loadProcessOff, logOff, entropyWarn, entropyWarnOff, scripts, shellOff, ...rest } = rawCliOptions;
+    const current = { ...rest };
+    if (typeof scripts === 'string') {
+        try {
+            current.scripts = JSON.parse(scripts);
+        }
+        catch {
+            // ignore parse errors; leave scripts undefined
+        }
+    }
+    const merged = defaultsDeep({}, defaults, parent ?? {}, current);
+    const d = defaults;
+    setOptionalFlag(merged, 'debug', resolveExclusion(merged.debug, debugOff, d.debug));
+    setOptionalFlag(merged, 'excludeDynamic', resolveExclusionAll(merged.excludeDynamic, excludeDynamicOff, d.excludeDynamic, excludeAll, excludeAllOff));
+    setOptionalFlag(merged, 'excludeEnv', resolveExclusionAll(merged.excludeEnv, excludeEnvOff, d.excludeEnv, excludeAll, excludeAllOff));
+    setOptionalFlag(merged, 'excludeGlobal', resolveExclusionAll(merged.excludeGlobal, excludeGlobalOff, d.excludeGlobal, excludeAll, excludeAllOff));
+    setOptionalFlag(merged, 'excludePrivate', resolveExclusionAll(merged.excludePrivate, excludePrivateOff, d.excludePrivate, excludeAll, excludeAllOff));
+    setOptionalFlag(merged, 'excludePublic', resolveExclusionAll(merged.excludePublic, excludePublicOff, d.excludePublic, excludeAll, excludeAllOff));
+    setOptionalFlag(merged, 'log', resolveExclusion(merged.log, logOff, d.log));
+    setOptionalFlag(merged, 'loadProcess', resolveExclusion(merged.loadProcess, loadProcessOff, d.loadProcess));
+    // warnEntropy (tri-state)
+    setOptionalFlag(merged, 'warnEntropy', resolveExclusion(merged.warnEntropy, entropyWarnOff, d.warnEntropy));
+    // Normalize shell for predictability: explicit default shell per OS.
+    const defaultShell = process.platform === 'win32' ? 'powershell.exe' : '/bin/bash';
+    let resolvedShell = merged.shell;
+    if (shellOff)
+        resolvedShell = false;
+    else if (resolvedShell === true || resolvedShell === undefined) {
+        resolvedShell = defaultShell;
+    }
+    else if (typeof resolvedShell !== 'string' &&
+        typeof defaults.shell === 'string') {
+        resolvedShell = defaults.shell;
+    }
+    merged.shell = resolvedShell;
+    const cmd = typeof command === 'string' ? command : undefined;
+    return cmd !== undefined ? { merged, command: cmd } : { merged };
+};
+
+GetDotenvCli.prototype.attachRootOptions = function (defaults, opts) {
+    const d = (defaults ?? baseRootOptionDefaults);
+    attachRootOptions(this, d, opts);
+    return this;
+};
+GetDotenvCli.prototype.passOptions = function (defaults) {
+    const d = (defaults ?? baseRootOptionDefaults);
+    this.hook('preSubcommand', async (thisCommand) => {
+        const raw = thisCommand.opts();
+        const { merged } = resolveCliOptions(raw, d, process.env.getDotenvCliOptions);
+        // Persist merged options for nested invocations (batch exec).
+        thisCommand.getDotenvCliOptions =
+            merged;
+        // Also store on the host for downstream ergonomic accessors.
+        this._setOptionsBag(merged);
+        // Build service options and compute context (always-on config loader path).
+        const serviceOptions = getDotenvCliOptions2Options(merged);
+        await this.resolveAndLoad(serviceOptions);
+        // Global validation: once after Phase C using config sources.
+        try {
+            const ctx = this.getCtx();
+            const dotenv = (ctx?.dotenv ?? {});
+            const sources = await resolveGetDotenvConfigSources((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('plugins.cjs', document.baseURI).href)));
+            const issues = validateEnvAgainstSources(dotenv, sources);
+            if (Array.isArray(issues) && issues.length > 0) {
+                const logger = (merged.logger ??
+                    console);
+                const emit = logger.error ?? logger.log;
+                issues.forEach((m) => {
+                    emit(m);
+                });
+                if (merged.strict) {
+                    // Deterministic failure under strict mode
+                    process.exit(1);
+                }
+            }
+        }
+        catch {
+            // Be tolerant: validation errors reported above; unexpected failures here
+            // should not crash non-strict flows.
+        }
+    });
+    // Also handle root-level flows (no subcommand) so option-aliases can run
+    // with the same merged options and context without duplicating logic.
+    this.hook('preAction', async (thisCommand) => {
+        const raw = thisCommand.opts();
+        const { merged } = resolveCliOptions(raw, d, process.env.getDotenvCliOptions);
+        thisCommand.getDotenvCliOptions =
+            merged;
+        this._setOptionsBag(merged);
+        // Avoid duplicate heavy work if a context is already present.
+        if (!this.getCtx()) {
+            const serviceOptions = getDotenvCliOptions2Options(merged);
+            await this.resolveAndLoad(serviceOptions);
+            try {
+                const ctx = this.getCtx();
+                const dotenv = (ctx?.dotenv ?? {});
+                const sources = await resolveGetDotenvConfigSources((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('plugins.cjs', document.baseURI).href)));
+                const issues = validateEnvAgainstSources(dotenv, sources);
+                if (Array.isArray(issues) && issues.length > 0) {
+                    const logger = (merged
+                        .logger ?? console);
+                    const emit = logger.error ?? logger.log;
+                    issues.forEach((m) => {
+                        emit(m);
+                    });
+                    if (merged.strict) {
+                        process.exit(1);
+                    }
+                }
+            }
+            catch {
+                // Tolerate validation side-effects in non-strict mode
+            }
+        }
+    });
+    return this;
+};
+
+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;
+        const cmd = new commander.Command()
+            .name('cmd')
+            .description('Batch execute command according to the --shell option, conflicts with --command option (default subcommand)')
+            .configureHelp({ showGlobalOptions: true })
+            .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: pass the resolved dotenv map to the child.
+            // This avoids leaking prior secrets from the parent process.env when
+            // exclusions (e.g., --exclude-private) are in effect.
+            const host = cli;
+            const ctx = host.getCtx();
+            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: { ...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: { ...process.env, ...dotenv },
+                stdio: 'inherit',
+            });
+        });
+    },
+    /**
+     * Optional: afterResolve can initialize per-plugin state using ctx.dotenv.
+     * For the demo we just log once to hint where such logic would live.
+     */
+    afterResolve(_cli, ctx) {
+        const keys = Object.keys(ctx.dotenv);
+        if (keys.length > 0) {
+            // Keep noise low; a single-line breadcrumb is sufficient for the demo.
+            console.error('[demo] afterResolve: dotenv keys loaded:', keys.length);
+        }
+    },
+});
+
+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;