@karmaniverous/get-dotenv 6.2.2 → 6.2.4

package/dist/plugins-aws.mjs

@@ -1,2542 +1,19 @@
+import { r as readMergedOptions, d as definePlugin } from './chunks/readMergedOptions-Nt0TR7dX.mjs';
+import 'execa';
+import 'fs-extra';
+import 'crypto';
+import 'path';
+import 'url';
+import '@commander-js/extra-typings';
+import 'nanoid';
+import 'dotenv';
+import './chunks/loader-DnhPeGfq.mjs';
+import 'package-directory';
+import 'yaml';
 import { z } from 'zod';
-import path, { join, extname } from 'path';
-import fs from 'fs-extra';
-import { packageDirectory } from 'package-directory';
-import url, { fileURLToPath } from 'url';
-import YAML from 'yaml';
-import { createHash } from 'crypto';
-import { nanoid } from 'nanoid';
-import { parse } from 'dotenv';
-import { execa, execaCommand } from 'execa';
-import { Option, Command } from '@commander-js/extra-typings';
-
-/**
- * Zod schemas for programmatic GetDotenv options.
- *
- * Canonical source of truth for options shape. Public types are derived
- * from these schemas (see consumers via z.output\<\>).
- */
-/**
- * Minimal process env representation used by options and helpers.
- * Values may be `undefined` to indicate "unset".
- */
-/**
- * Schema for an env-like record.
- *
- * Keys are environment variable names and values are either strings or `undefined`
- * (to represent “unset”).
- *
- * @public
- */
-const processEnvSchema = z.record(z.string(), z.string().optional());
-// RAW: all fields optional — undefined means "inherit" from lower layers.
-/**
- * Programmatic options schema (raw).
- *
- * This schema is the canonical runtime source of truth for the `getDotenv()` programmatic API.
- * All fields are optional; `undefined` generally means “inherit default/lower layer”.
- *
- * @public
- */
-const getDotenvOptionsSchemaRaw = z.object({
-    /** Default environment name when `env` is not provided. */
-    defaultEnv: z.string().optional(),
-    /** Base dotenv filename token (default `.env`). */
-    dotenvToken: z.string().optional(),
-    /** Path to a dynamic variables module (JS/TS) to load and apply. */
-    dynamicPath: z.string().optional(),
-    /** Dynamic map is intentionally wide for now; refine once sources are normalized. */
-    dynamic: z.record(z.string(), z.unknown()).optional(),
-    /** Selected environment name for this invocation (for env-scoped files and overlays). */
-    env: z.string().optional(),
-    /** When true, skip applying dynamic variables. */
-    excludeDynamic: z.boolean().optional(),
-    /** When true, skip environment-scoped dotenv files. */
-    excludeEnv: z.boolean().optional(),
-    /** When true, skip global dotenv files. */
-    excludeGlobal: z.boolean().optional(),
-    /** When true, skip private dotenv files. */
-    excludePrivate: z.boolean().optional(),
-    /** When true, skip public dotenv files. */
-    excludePublic: z.boolean().optional(),
-    /** When true, merge the final composed environment into `process.env`. */
-    loadProcess: z.boolean().optional(),
-    /** When true, log the final environment map via `logger`. */
-    log: z.boolean().optional(),
-    /** Logger used when `log` is enabled (console-compatible). */
-    logger: z.unknown().default(console),
-    /** Optional output dotenv file path to write after composition. */
-    outputPath: z.string().optional(),
-    /** Dotenv search paths (ordered). */
-    paths: z.array(z.string()).optional(),
-    /** Private token suffix for private dotenv files (default `local`). */
-    privateToken: z.string().optional(),
-    /** Explicit variables to overlay onto the composed dotenv map. */
-    vars: processEnvSchema.optional(),
-});
-/**
- * Resolved programmatic options schema (post-inheritance).
- * For now, this mirrors the RAW schema; future stages may materialize defaults
- * and narrow shapes as resolution is wired into the host.
- */
-/**
- * Programmatic options schema (resolved).
- *
- * Today this mirrors {@link getDotenvOptionsSchemaRaw}, but is kept as a distinct export
- * so future resolution steps can narrow or materialize defaults without breaking the API.
- *
- * @public
- */
-const getDotenvOptionsSchemaResolved = getDotenvOptionsSchemaRaw;
-
-/**
- * Zod schemas for CLI-facing GetDotenv options (raw/resolved stubs).
- *
- * RAW allows stringly inputs (paths/vars + splitters). RESOLVED will later
- * reflect normalized types (paths: string[], vars: ProcessEnv), applied in the
- * CLI resolution pipeline.
- */
-/**
- * CLI options schema (raw).
- *
- * Extends the programmatic options schema with CLI-only flags and stringly inputs
- * which are normalized later by the host resolution pipeline.
- *
- * @public
- */
-const getDotenvCliOptionsSchemaRaw = getDotenvOptionsSchemaRaw.extend({
-    // CLI-specific fields (stringly inputs before preprocessing)
-    /** Enable verbose debug output (host-specific). */
-    debug: z.boolean().optional(),
-    /** Fail on validation errors (schema/requiredKeys). */
-    strict: z.boolean().optional(),
-    /** Capture child process stdio (useful for CI/tests). */
-    capture: z.boolean().optional(),
-    /** Emit child env diagnostics (boolean or selected keys). */
-    trace: z.union([z.boolean(), z.array(z.string())]).optional(),
-    /** Enable presentation-time redaction in trace/log output. */
-    redact: z.boolean().optional(),
-    /** Enable entropy warnings in trace/log output. */
-    warnEntropy: z.boolean().optional(),
-    /** Entropy threshold (bits/char) for warnings. */
-    entropyThreshold: z.number().optional(),
-    /** Minimum value length to consider for entropy warnings. */
-    entropyMinLength: z.number().optional(),
-    /** Regex patterns (strings) to suppress entropy warnings by key. */
-    entropyWhitelist: z.array(z.string()).optional(),
-    /** Additional key-match patterns (strings) for redaction. */
-    redactPatterns: z.array(z.string()).optional(),
-    /** Dotenv search paths provided as a single delimited string. */
-    paths: z.string().optional(),
-    /** Delimiter string used to split `paths`. */
-    pathsDelimiter: z.string().optional(),
-    /** Regex pattern used to split `paths` (takes precedence over delimiter). */
-    pathsDelimiterPattern: z.string().optional(),
-    /** Scripts table in a permissive shape at parse time (validated elsewhere). */
-    scripts: z.record(z.string(), z.unknown()).optional(),
-    /** Shell selection (`false` for shell-off, string for explicit shell). */
-    shell: z.union([z.boolean(), z.string()]).optional(),
-    /** Extra variables expressed as a single delimited string of assignments. */
-    vars: z.string().optional(),
-    /** Assignment operator used when parsing `vars`. */
-    varsAssignor: z.string().optional(),
-    /** Regex pattern used as the assignment operator for `vars` parsing. */
-    varsAssignorPattern: z.string().optional(),
-    /** Delimiter string used to split `vars`. */
-    varsDelimiter: z.string().optional(),
-    /** Regex pattern used to split `vars` (takes precedence over delimiter). */
-    varsDelimiterPattern: z.string().optional(),
-});
-
-const visibilityMap = z.record(z.string(), z.boolean());
-/**
- * Zod schemas for configuration files discovered by the new loader.
- *
- * Notes:
- * - RAW: all fields optional; only allowed top-level keys are:
- *   - rootOptionDefaults, rootOptionVisibility
- *   - scripts, vars, envVars
- *   - dynamic (JS/TS only), schema (JS/TS only)
- *   - plugins, requiredKeys
- * - RESOLVED: mirrors RAW (no path normalization).
- * - For JSON/YAML configs, the loader rejects "dynamic" and "schema" (JS/TS only).
- */
-// String-only env value map
-const stringMap = z.record(z.string(), z.string());
-const envStringMap = z.record(z.string(), stringMap);
-/**
- * Raw configuration schema for get‑dotenv config files (JSON/YAML/JS/TS).
- * Validates allowed top‑level keys without performing path normalization.
- */
-/**
- * Config schema for discovered get-dotenv configuration documents (raw).
- *
- * This schema validates the allowed top-level keys for configuration files.
- * It does not normalize paths or coerce types beyond Zod’s parsing.
- *
- * @public
- */
-const getDotenvConfigSchemaRaw = z.object({
-    /** Root option defaults applied by the host (CLI-like, collapsed families). */
-    rootOptionDefaults: getDotenvCliOptionsSchemaRaw.optional(),
-    /** Help-time visibility map for root flags (false hides). */
-    rootOptionVisibility: visibilityMap.optional(),
-    /** Scripts table used by cmd/batch resolution (validation intentionally permissive here). */
-    scripts: z.record(z.string(), z.unknown()).optional(),
-    /** Keys required to be present in the final composed environment. */
-    requiredKeys: z.array(z.string()).optional(),
-    /** Validation schema (JS/TS only; JSON/YAML loader rejects). */
-    schema: z.unknown().optional(), // JS/TS-only; loader rejects in JSON/YAML
-    /** Public global variables (string-only). */
-    vars: stringMap.optional(), // public, global
-    /** Public per-environment variables (string-only). */
-    envVars: envStringMap.optional(), // public, per-env
-    // Dynamic in config (JS/TS only). JSON/YAML loader will reject if set.
-    /** Dynamic variable definitions (JS/TS only). */
-    dynamic: z.unknown().optional(),
-    // Per-plugin config bag; validated by plugins/host when used.
-    /** Per-plugin config slices keyed by realized mount path (for example, `aws/whoami`). */
-    plugins: z.record(z.string(), z.unknown()).optional(),
-});
-/**
- * Resolved configuration schema which preserves the raw shape while narrowing
- * the output to {@link GetDotenvConfigResolved}. Consumers get a strongly typed
- * object, while the underlying validation remains Zod‑driven.
- */
-const getDotenvConfigSchemaResolved = getDotenvConfigSchemaRaw.transform((raw) => raw);
-
-/** @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;
-};
-function defaultsDeep(...layers) {
-    const result = layers
-        .filter(Boolean)
-        .reduce((acc, layer) => mergeInto(acc, layer), {});
-    return result;
-}
-
-/**
- * Serialize a dotenv record to a file with minimal quoting (multiline values are quoted).
- * Future-proofs for ordering/sorting changes (currently insertion order).
- *
- * @param filename - Destination dotenv file path.
- * @param data - Env-like map of values to write (values may be `undefined`).
- * @returns A `Promise\<void\>` which resolves when the file has been written.
- */
-async function writeDotenvFile(filename, data) {
-    // Serialize: key=value with quotes only for multiline values.
-    const body = Object.keys(data).reduce((acc, key) => {
-        const v = data[key] ?? '';
-        const val = v.includes('\n') ? `"${v}"` : v;
-        return `${acc}${key}=${val}\n`;
-    }, '');
-    await fs.writeFile(filename, body, { encoding: 'utf-8' });
-}
-
-/**
- * Dotenv expansion utilities.
- *
- * This module implements recursive expansion of environment-variable
- * references in strings and records. It supports both whitespace and
- * bracket syntaxes with optional defaults:
- *
- * - Whitespace: `$VAR[:default]`
- * - Bracketed: `${VAR[:default]}`
- *
- * Escaped dollar signs (`\$`) are preserved.
- * Unknown variables resolve to empty string unless a default is provided.
- */
-/**
- * Like String.prototype.search but returns the last index.
- * @internal
- */
-const searchLast = (str, rgx) => {
-    const matches = Array.from(str.matchAll(rgx));
-    return matches.length > 0 ? (matches.slice(-1)[0]?.index ?? -1) : -1;
-};
-const replaceMatch = (value, match, ref) => {
-    /**
-     * @internal
-     */
-    const group = match[0];
-    const key = match[1];
-    const defaultValue = match[2];
-    if (!key)
-        return value;
-    const replacement = value.replace(group, ref[key] ?? defaultValue ?? '');
-    return interpolate(replacement, ref);
-};
-const interpolate = (value = '', ref = {}) => {
-    /**
-     * @internal
-     */
-    // if value is falsy, return it as is
-    if (!value)
-        return value;
-    // get position of last unescaped dollar sign
-    const lastUnescapedDollarSignIndex = searchLast(value, /(?!(?<=\\))\$/g);
-    // return value if none found
-    if (lastUnescapedDollarSignIndex === -1)
-        return value;
-    // evaluate the value tail
-    const tail = value.slice(lastUnescapedDollarSignIndex);
-    // find whitespace pattern: $KEY:DEFAULT
-    const whitespacePattern = /^\$([\w]+)(?::([^\s]*))?/;
-    const whitespaceMatch = whitespacePattern.exec(tail);
-    if (whitespaceMatch != null)
-        return replaceMatch(value, whitespaceMatch, ref);
-    else {
-        // find bracket pattern: ${KEY:DEFAULT}
-        const bracketPattern = /^\${([\w]+)(?::([^}]*))?}/;
-        const bracketMatch = bracketPattern.exec(tail);
-        if (bracketMatch != null)
-            return replaceMatch(value, bracketMatch, ref);
-    }
-    return value;
-};
-/**
- * Recursively expands environment variables in a string. Variables may be
- * presented with optional default as `$VAR[:default]` or `${VAR[:default]}`.
- * Unknown variables will expand to an empty string.
- *
- * @param value - The string to expand.
- * @param ref - The reference object to use for variable expansion.
- * @returns The expanded string.
- *
- * @example
- * ```ts
- * process.env.FOO = 'bar';
- * dotenvExpand('Hello $FOO'); // "Hello bar"
- * dotenvExpand('Hello $BAZ:world'); // "Hello world"
- * ```
- *
- * @remarks
- * The expansion is recursive. If a referenced variable itself contains
- * references, those will also be expanded until a stable value is reached.
- * Escaped references (e.g. `\$FOO`) are preserved as literals.
- */
-const dotenvExpand = (value, ref = process.env) => {
-    const result = interpolate(value, ref);
-    return result ? result.replace(/\\\$/g, '$') : undefined;
-};
-/**
- * Recursively expands environment variables in the values of a JSON object.
- * Variables may be presented with optional default as `$VAR[:default]` or
- * `${VAR[:default]}`. Unknown variables will expand to an empty string.
- *
- * @param values - The values object to expand.
- * @param options - Expansion options.
- * @returns The value object with expanded string values.
- *
- * @example
- * ```ts
- * process.env.FOO = 'bar';
- * dotenvExpandAll({ A: '$FOO', B: 'x${FOO}y' });
- * // => { A: "bar", B: "xbary" }
- * ```
- *
- * @remarks
- * Options:
- * - ref: The reference object to use for expansion (defaults to process.env).
- * - progressive: Whether to progressively add expanded values to the set of
- *   reference keys.
- *
- * When `progressive` is true, each expanded key becomes available for
- * subsequent expansions in the same object (left-to-right by object key order).
- */
-function dotenvExpandAll(values, options = {}) {
-    const { ref = process.env, progressive = false, } = options;
-    const out = Object.keys(values).reduce((acc, key) => {
-        acc[key] = dotenvExpand(values[key], {
-            ...ref,
-            ...(progressive ? acc : {}),
-        });
-        return acc;
-    }, {});
-    // Key-preserving return with a permissive index signature to allow later additions.
-    return out;
-}
-/**
- * Recursively expands environment variables in a string using `process.env` as
- * the expansion reference. Variables may be presented with optional default as
- * `$VAR[:default]` or `${VAR[:default]}`. Unknown variables will expand to an
- * empty string.
- *
- * @param value - The string to expand.
- * @returns The expanded string.
- *
- * @example
- * ```ts
- * process.env.FOO = 'bar';
- * dotenvExpandFromProcessEnv('Hello $FOO'); // "Hello bar"
- * ```
- */
-const dotenvExpandFromProcessEnv = (value) => dotenvExpand(value, process.env);
-
-/** @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;
-};
-
-const importDefault = async (fileUrl) => {
-    const mod = (await import(fileUrl));
-    return mod.default;
-};
-const cacheHash = (absPath, mtimeMs) => 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.
- *
- * Behavior by extension:
- *
- * - `.js`/`.mjs`/`.cjs`: direct dynamic import.
- * - `.ts`/`.mts`/`.cts`/`.tsx`:
- *   - try direct dynamic import (when a TS loader is active),
- *   - else compile via `esbuild` to a cached `.mjs` file and import,
- *   - else fallback to `typescript.transpileModule` for simple modules.
- *
- * @typeParam T - Type of the expected default export.
- * @param absPath - Absolute path to the source file.
- * @param cacheDirName - Cache subfolder under `.tsbuild/`.
- * @returns A `Promise\<T | undefined\>` resolving to the default export (if any).
- */
-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.`);
-    }
-};
-
-/** src/util/omitUndefined.ts
- * Helpers to drop undefined-valued properties in a typed-friendly way.
- */
-/**
- * Omit keys whose runtime value is undefined from a shallow object.
- * Returns a Partial with non-undefined value types preserved.
- *
- * @typeParam T - Input object shape.
- * @param obj - Object to filter.
- * @returns A shallow copy of `obj` without keys whose value is `undefined`.
- */
-function omitUndefined(obj) {
-    const out = {};
-    for (const [k, v] of Object.entries(obj)) {
-        if (v !== undefined)
-            out[k] = v;
-    }
-    return out;
-}
-/**
- * Specialized helper for env-like maps: drop undefined and return string-only.
- *
- * @typeParam V - Value type for present entries (must extend `string`).
- * @param obj - Env-like record containing `string | undefined` values.
- * @returns A new record containing only the keys with defined values.
- */
-function omitUndefinedRecord(obj) {
-    const out = {};
-    for (const [k, v] of Object.entries(obj)) {
-        if (v !== undefined)
-            out[k] = v;
-    }
-    return out;
-}
-
-/**
- * Minimal tokenizer for shell-off execution.
- * Splits by whitespace while preserving quoted segments (single or double quotes).
- *
- * @param command - The command string to tokenize.
- * @param opts - Tokenization options (e.g. quote handling).
- */
-const tokenize = (command, opts) => {
-    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:
-                // default: "" -> " and '' -> ' (Windows/PowerShell style)
-                // preserve: keep as "" to allow empty string literals in Node -e payloads
-                const next = command.charAt(i + 1);
-                if (next === quote) {
-                    {
-                        // Collapse to a single literal 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;
-};
-
-/**
- * @packageDocumentation
- * Configuration discovery and loading for get‑dotenv. Discovers config files
- * in the packaged root and project root, loads JSON/YAML/JS/TS documents, and
- * validates them against Zod schemas.
- */
-// 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(extname(p).toLowerCase());
-const isJson = (p) => extname(p).toLowerCase() === '.json';
-const isJsOrTs = (p) => ['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts'].includes(extname(p).toLowerCase());
-/**
- * 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 = fileURLToPath(importMetaUrl);
-        const packagedRoot = await packageDirectory({ cwd: fromUrl });
-        if (packagedRoot) {
-            for (const name of PUBLIC_FILENAMES) {
-                const p = 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();
-    if (projectRoot) {
-        for (const name of PUBLIC_FILENAMES) {
-            const p = 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 = 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 shared robust pipeline.
-            const mod = await loadModuleDefault(abs, 'getdotenv-config');
-            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;
-};
-
-/** src/env/dynamic.ts
- * Helpers for applying and loading dynamic variables (JS/TS).
- *
- * Requirements addressed:
- * - Single service to apply a dynamic map progressively.
- * - Single service to load a JS/TS dynamic module with robust fallbacks (util/loadModuleDefault).
- * - Unify error messaging so callers show consistent guidance.
- */
-/**
- * Apply a dynamic map to the target progressively.
- * - Functions receive (target, env) and may return string | undefined.
- * - Literals are assigned directly (including undefined).
- *
- * @param target - Mutable target environment to assign into.
- * @param map - Dynamic map to apply (functions and/or literal values).
- * @param env - Selected environment name (if any) passed through to dynamic functions.
- * @returns Nothing.
- */
-function applyDynamicMap(target, map, env) {
-    if (!map)
-        return;
-    for (const key of Object.keys(map)) {
-        const val = typeof map[key] === 'function'
-            ? map[key](target, env)
-            : map[key];
-        Object.assign(target, { [key]: val });
-    }
-}
-/**
- * Load a default-export dynamic map from a JS/TS file and apply it.
- * Uses util/loadModuleDefault for robust TS handling (direct import, esbuild,
- * typescript.transpile fallback).
- *
- * Error behavior:
- * - On failure to load/compile/evaluate the module, throws a unified message:
- *   "Unable to load dynamic TypeScript file: <absPath>. Install 'esbuild'..."
- *
- * @param target - Mutable target environment to assign into.
- * @param absPath - Absolute path to the dynamic module file.
- * @param env - Selected environment name (if any).
- * @param cacheDirName - Cache subdirectory under `.tsbuild/` for compiled artifacts.
- * @returns A `Promise\<void\>` which resolves after the module (if present) has been applied.
- */
-async function loadAndApplyDynamic(target, absPath, env, cacheDirName) {
-    if (!(await fs.exists(absPath)))
-        return;
-    let dyn;
-    try {
-        dyn = await loadModuleDefault(absPath, cacheDirName);
-    }
-    catch {
-        // Preserve legacy/clear guidance used by tests and docs.
-        throw new Error(`Unable to load dynamic TypeScript file: ${absPath}. ` +
-            `Install 'esbuild' (devDependency) to enable TypeScript dynamic modules.`);
-    }
-    applyDynamicMap(target, dyn, 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);
-};
-function overlayEnv(args) {
-    const { base, env, configs } = args;
-    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' in args) {
-        const toApply = Object.fromEntries(Object.entries(args.programmaticVars).filter(([_k, v]) => typeof v === 'string'));
-        current = applyKv(current, toApply);
-    }
-    return current;
-}
-
-/** 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) => (typeof p === 'string' ? new RegExp(p, 'i') : p));
-const whitelisted = (key, regs) => regs.some((re) => re.test(key));
-const shannonBitsPerChar = (s) => {
-    const freq = new Map();
-    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) => typeof p === 'string' ? new RegExp(p, 'i') : p);
-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;
-};
-
-/**
- * Base root CLI defaults (shared; kept untyped here to avoid cross-layer deps).
- * Used as the bottom layer for CLI option resolution.
- */
-const baseScripts = {
-    'git-status': {
-        cmd: 'git branch --show-current && git status -s -u',
-        shell: true,
-    },
-};
-/**
- * Default values for root CLI options used by the host and helpers as the baseline layer during option resolution.
- *
- * These defaults correspond to the “stringly” root surface (see `RootOptionsShape`) and are merged by precedence with:
- * - create-time overrides
- * - any discovered configuration `rootOptionDefaults`
- * - and finally CLI flags at runtime
- *
- * @public
- */
-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: baseScripts,
-    shell: true,
-    vars: '',
-    varsAssignor: '=',
-    varsDelimiter: ' ',
-    // tri-state flags default to unset unless explicitly provided
-    // (debug/log/exclude* resolved via flag utils)
-};
-
-/**
- * Converts programmatic CLI options to `getDotenv` options.
- *
- * Accepts "stringly" CLI inputs for vars/paths and normalizes them into
- * the programmatic shape. Preserves exactOptionalPropertyTypes semantics by
- * omitting keys when undefined.
- */
-const getDotenvCliOptions2Options = ({ paths, pathsDelimiter, pathsDelimiterPattern, vars, varsAssignor, varsAssignorPattern, varsDelimiter, varsDelimiterPattern, 
-// drop CLI-only keys from the pass-through bag
-debug: _debug, scripts: _scripts, ...rest }) => {
-    // Split helper for delimited strings or regex patterns
-    const splitBy = (value, delim, pattern) => {
-        if (!value)
-            return [];
-        if (pattern)
-            return value.split(RegExp(pattern));
-        if (typeof delim === 'string')
-            return value.split(delim);
-        return value.split(' ');
-    };
-    // Tolerate vars as either a CLI string ("A=1 B=2") or an object map.
-    let parsedVars;
-    if (typeof vars === 'string') {
-        const kvPairs = splitBy(vars, varsDelimiter, varsDelimiterPattern)
-            .map((v) => v.split(varsAssignorPattern
-            ? RegExp(varsAssignorPattern)
-            : (varsAssignor ?? '=')))
-            .filter(([k]) => typeof k === 'string' && k.length > 0);
-        parsedVars = Object.fromEntries(kvPairs);
-    }
-    else if (vars && typeof vars === 'object' && !Array.isArray(vars)) {
-        // Accept provided object map of string | undefined; drop undefined values
-        // in the normalization step below to produce a ProcessEnv-compatible bag.
-        parsedVars = Object.fromEntries(Object.entries(vars));
-    }
-    // Drop undefined-valued entries at the converter stage to match ProcessEnv
-    // expectations and the compat test assertions.
-    if (parsedVars) {
-        parsedVars = omitUndefinedRecord(parsedVars);
-    }
-    // Tolerate paths as either a delimited string or string[]
-    const pathsOut = Array.isArray(paths)
-        ? paths.filter((p) => typeof p === 'string')
-        : splitBy(paths, pathsDelimiter, pathsDelimiterPattern);
-    // Preserve exactOptionalPropertyTypes: only include keys when defined.
-    return {
-        // Ensure the required logger property is present. The base CLI defaults
-        // specify console as the logger; callers can override upstream if desired.
-        logger: console,
-        ...rest,
-        ...(pathsOut.length > 0 ? { paths: pathsOut } : {}),
-        ...(parsedVars !== undefined ? { vars: parsedVars } : {}),
-    };
-};
-/**
- * Resolve {@link GetDotenvOptions} by layering defaults in ascending precedence:
- *
- * 1. Base defaults derived from the CLI generator defaults
- *    ({@link baseGetDotenvCliOptions}).
- * 2. Local project overrides from a `getdotenv.config.json` in the nearest
- *    package root (if present).
- * 3. The provided customOptions.
- *
- * The result preserves explicit empty values and drops only `undefined`.
- */
-const resolveGetDotenvOptions = (customOptions) => {
-    // Programmatic callers use neutral defaults only. Do not read local packaged
-    // getdotenv.config.json here; the host path applies packaged/project configs
-    // via the dedicated loader/overlay pipeline.
-    const mergedDefaults = baseRootOptionDefaults;
-    const defaultsFromCli = getDotenvCliOptions2Options(mergedDefaults);
-    const result = defaultsDeep(defaultsFromCli, customOptions);
-    return Promise.resolve({
-        ...result, // Keep explicit empty strings/zeros; drop only undefined
-        vars: omitUndefinedRecord(result.vars ?? {}),
-    });
-};
-
-/**
- * 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)) ? parse(await fs.readFile(path)) : {};
-    }
-    catch {
-        return {};
-    }
-};
-
-async function getDotenv(options = {}) {
-    // Apply defaults.
-    const { defaultEnv, dotenvToken = '.env', dynamicPath, env, excludeDynamic = false, excludeEnv = false, excludeGlobal = false, excludePrivate = false, excludePublic = false, loadProcess = false, log = false, logger = console, outputPath, paths = [], privateToken = 'local', vars = {}, } = await resolveGetDotenvOptions(options);
-    // Read .env files.
-    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();
-    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);
-            await loadAndApplyDynamic(dotenv, absDynamicPath, env ?? defaultEnv, 'getdotenv-dynamic');
-        }
-        if (dynamic) {
-            try {
-                applyDynamicMap(dotenv, dynamic, env ?? defaultEnv);
-            }
-            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 writeDotenvFile(outputPathResolved, dotenvForOutput);
-        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;
-}
-
-/**
- * Compute the realized path for a command mount (leaf-up to root).
- * Excludes the root application alias.
- *
- * @param cli - The mounted command instance.
- */
-/**
- * Flatten a plugin tree into a list of `{ plugin, path }` entries.
- * Traverses the namespace chain in pre-order.
- */
-function flattenPluginTreeByPath(plugins, prefix) {
-    const out = [];
-    for (const p of plugins) {
-        const here = prefix && prefix.length > 0 ? `${prefix}/${p.ns}` : p.ns;
-        out.push({ plugin: p, path: here });
-        if (Array.isArray(p.children) && p.children.length > 0) {
-            out.push(...flattenPluginTreeByPath(p.children.map((c) => c.plugin), here));
-        }
-    }
-    return out;
-}
-
-/**
- * Instance-bound plugin config store.
- * Host stores the validated/interpolated slice per plugin instance.
- * The store is intentionally private to this module; definePlugin()
- * provides a typed accessor that reads from this store for the calling
- * plugin instance.
- */
-const PLUGIN_CONFIG_STORE = new WeakMap();
-/**
- * Store a validated, interpolated config slice for a specific plugin instance.
- * Generic on both the host options type and the plugin config type to avoid
- * defaulting to GetDotenvOptions under exactOptionalPropertyTypes.
- */
-const setPluginConfig = (plugin, cfg) => {
-    PLUGIN_CONFIG_STORE.set(plugin, cfg);
-};
-/**
- * Retrieve the validated/interpolated config slice for a plugin instance.
- */
-const getPluginConfig = (plugin) => {
-    return PLUGIN_CONFIG_STORE.get(plugin);
-};
-/**
- * Compute the dotenv context for the host (uses the config loader/overlay path).
- * - Resolves and validates options strictly (host-only).
- * - Applies file cascade, overlays, dynamics, and optional effects.
- * - Merges and validates per-plugin config slices (when provided), keyed by
- *   realized mount path (ns chain).
- *
- * @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);
-    // Zod boundary: parse returns the schema-derived shape; we adopt our public
-    // GetDotenvOptions overlay (logger/dynamic typing) for internal processing.
-    const validated = getDotenvOptionsSchemaResolved.parse(optionsResolved);
-    // Build a pure base without side effects or logging (no dynamics, no programmatic vars).
-    const cleanedValidated = omitUndefined(validated);
-    const base = await getDotenv({
-        ...cleanedValidated,
-        excludeDynamic: true,
-        vars: {},
-        log: false,
-        loadProcess: false,
-    });
-    // Discover config sources and overlay with progressive expansion per slice.
-    const sources = await resolveGetDotenvConfigSources(hostMetaUrl);
-    const dotenvOverlaid = overlayEnv({
-        base,
-        env: validated.env ?? validated.defaultEnv,
-        configs: sources,
-        ...(validated.vars ? { programmaticVars: validated.vars } : {}),
-    });
-    const dotenv = { ...dotenvOverlaid };
-    // Programmatic dynamic variables (when provided)
-    applyDynamicMap(dotenv, validated.dynamic, validated.env ?? validated.defaultEnv);
-    // Packaged/project dynamics
-    const packagedDyn = (sources.packaged?.dynamic ?? undefined);
-    const publicDyn = (sources.project?.public?.dynamic ?? undefined);
-    const localDyn = (sources.project?.local?.dynamic ?? undefined);
-    applyDynamicMap(dotenv, packagedDyn, validated.env ?? validated.defaultEnv);
-    applyDynamicMap(dotenv, publicDyn, validated.env ?? validated.defaultEnv);
-    applyDynamicMap(dotenv, localDyn, validated.env ?? validated.defaultEnv);
-    // file dynamicPath (lowest)
-    if (validated.dynamicPath) {
-        const absDynamicPath = path.resolve(validated.dynamicPath);
-        await loadAndApplyDynamic(dotenv, absDynamicPath, validated.env ?? validated.defaultEnv, 'getdotenv-dynamic-host');
-    }
-    // Effects:
-    if (validated.outputPath) {
-        await writeDotenvFile(validated.outputPath, dotenv);
-    }
-    const logger = validated.logger;
-    if (validated.log)
-        logger.log(dotenv);
-    if (validated.loadProcess)
-        Object.assign(process.env, dotenv);
-    // Merge and validate per-plugin config keyed by realized path (ns chain).
-    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 entries = flattenPluginTreeByPath(plugins);
-    const mergedPluginConfigsByPath = {};
-    const envRef = {
-        ...dotenv,
-        ...process.env,
-    };
-    for (const e of entries) {
-        const pathKey = e.path;
-        const mergedRaw = defaultsDeep({}, packagedPlugins[pathKey] ?? {}, publicPlugins[pathKey] ?? {}, localPlugins[pathKey] ?? {});
-        const interpolated = mergedRaw && typeof mergedRaw === 'object'
-            ? interpolateDeep(mergedRaw, envRef)
-            : {};
-        const schema = e.plugin.configSchema;
-        if (schema) {
-            const parsed = schema.safeParse(interpolated);
-            if (!parsed.success) {
-                const err = parsed.error;
-                const msgs = err.issues
-                    .map((i) => {
-                    const pth = Array.isArray(i.path) ? i.path.join('.') : '';
-                    const msg = typeof i.message === 'string' ? i.message : 'Invalid value';
-                    return pth ? `${pth}: ${msg}` : msg;
-                })
-                    .join('\n');
-                throw new Error(`Invalid config for plugin at '${pathKey}':\n${msgs}`);
-            }
-            const frozen = Object.freeze(parsed.data);
-            setPluginConfig(e.plugin, frozen);
-            mergedPluginConfigsByPath[pathKey] = frozen;
-        }
-        else {
-            const frozen = Object.freeze(interpolated);
-            setPluginConfig(e.plugin, frozen);
-            mergedPluginConfigsByPath[pathKey] = frozen;
-        }
-    }
-    return {
-        optionsResolved: validated,
-        dotenv,
-        plugins: {},
-        pluginConfigs: mergedPluginConfigsByPath,
-    };
-};
-
-// Implementation
-function definePlugin(spec) {
-    const { ...rest } = spec;
-    const effectiveSchema = spec.configSchema ?? z.object({}).strict();
-    const base = {
-        ...rest,
-        configSchema: effectiveSchema,
-        children: [],
-        use(child, override) {
-            // Enforce sibling uniqueness at composition time.
-            const desired = (override && typeof override.ns === 'string' && override.ns.length > 0
-                ? override.ns
-                : child.ns).trim();
-            const collision = this.children.some((c) => {
-                const ns = (c.override &&
-                    typeof c.override.ns === 'string' &&
-                    c.override.ns.length > 0
-                    ? c.override.ns
-                    : c.plugin.ns).trim();
-                return ns === desired;
-            });
-            if (collision) {
-                const under = this.ns && this.ns.length > 0 ? this.ns : 'root';
-                throw new Error(`Duplicate namespace '${desired}' under '${under}'. ` +
-                    `Override via .use(plugin, { ns: '...' }).`);
-            }
-            this.children.push({ plugin: child, override });
-            return this;
-        },
-    };
-    const extended = base;
-    extended.readConfig = function (_cli) {
-        const value = getPluginConfig(extended);
-        if (value === undefined) {
-            throw new Error('Plugin config not available. Ensure resolveAndLoad() has been called before readConfig().');
-        }
-        return value;
-    };
-    extended.createPluginDynamicOption = function (cli, flags, desc, parser, defaultValue) {
-        // Derive realized path strictly from the provided mount (leaf-up).
-        const realizedPath = (() => {
-            const parts = [];
-            let node = cli;
-            while (node.parent) {
-                parts.push(node.name());
-                node = node.parent;
-            }
-            return parts.reverse().join('/');
-        })();
-        return cli.createDynamicOption(flags, (c) => {
-            const fromStore = getPluginConfig(extended);
-            let cfgVal = fromStore ?? {};
-            // Strict fallback only by realized path for help-time synthetic usage.
-            if (!fromStore && realizedPath.length > 0) {
-                const bag = c.plugins;
-                const maybe = bag[realizedPath];
-                if (maybe && typeof maybe === 'object') {
-                    cfgVal = maybe;
-                }
-            }
-            // c is strictly typed as ResolvedHelpConfig from cli.createDynamicOption
-            return desc(c, cfgVal);
-        }, parser, defaultValue);
-    };
-    return extended;
-}
-
-const dbg = (...args) => {
-    if (process.env.GETDOTENV_DEBUG) {
-        // Use stderr to avoid interfering with stdout assertions
-        console.error('[getdotenv:run]', ...args);
-    }
-};
-/**
- * Helper to decide whether to capture child stdio.
- * Checks GETDOTENV_STDIO env var or the provided bag capture flag.
- */
-const shouldCapture = (bagCapture) => process.env.GETDOTENV_STDIO === 'pipe' || Boolean(bagCapture);
-// 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;
-};
-/**
- * Core executor that normalizes shell/plain forms and capture/inherit modes.
- * Returns captured buffers; callers may stream stdout when desired.
- */
-async function _execNormalized(command, shell, opts = {}) {
-    const envSan = sanitizeEnv(opts.env);
-    const timeoutBits = typeof opts.timeoutMs === 'number'
-        ? { timeout: opts.timeoutMs, killSignal: 'SIGKILL' }
-        : {};
-    const stdio = opts.stdio ?? 'pipe';
-    if (shell === false) {
-        let file;
-        let args = [];
-        if (typeof command === 'string') {
-            const tokens = tokenize(command);
-            file = tokens[0];
-            args = tokens.slice(1);
-        }
-        else {
-            file = command[0];
-            args = command.slice(1).map(stripOuterQuotes);
-        }
-        if (!file)
-            return { exitCode: 0, stdout: '', stderr: '' };
-        dbg('exec (plain)', { file, args, stdio });
-        try {
-            const ok = pickResult((await execa(file, args, {
-                ...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),
-                ...(envSan !== undefined ? { env: envSan } : {}),
-                stdio,
-                ...timeoutBits,
-            })));
-            dbg('exit (plain)', { exitCode: ok.exitCode });
-            return ok;
-        }
-        catch (e) {
-            const out = pickResult(e);
-            dbg('exit:error (plain)', { exitCode: out.exitCode });
-            return out;
-        }
-    }
-    // Shell path (string|true|URL): execaCommand handles shell resolution.
-    const commandStr = typeof command === 'string' ? command : command.join(' ');
-    dbg('exec (shell)', {
-        command: commandStr,
-        shell: typeof shell === 'string' ? shell : 'custom',
-        stdio,
-    });
-    try {
-        const ok = pickResult((await execaCommand(commandStr, {
-            shell,
-            ...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),
-            ...(envSan !== undefined ? { env: envSan } : {}),
-            stdio,
-            ...timeoutBits,
-        })));
-        dbg('exit (shell)', { exitCode: ok.exitCode });
-        return ok;
-    }
-    catch (e) {
-        const out = pickResult(e);
-        dbg('exit:error (shell)', { exitCode: out.exitCode });
-        return out;
-    }
-}
-/**
- * Execute a command and capture stdout/stderr (buffered).
- *
- * @param command - Command string (shell) or argv array (shell-off supported).
- * @param shell - Shell setting (false for plain execution).
- * @param opts - Execution options (cwd/env/timeout).
- * @returns A promise resolving to the captured result.
- */
-async function runCommandResult(command, shell, opts = {}) {
-    // Build opts without injecting undefined (exactOptionalPropertyTypes-safe)
-    const coreOpts = { stdio: 'pipe' };
-    if (opts.cwd !== undefined) {
-        coreOpts.cwd = opts.cwd;
-    }
-    if (opts.env !== undefined) {
-        coreOpts.env = opts.env;
-    }
-    if (opts.timeoutMs !== undefined) {
-        coreOpts.timeoutMs = opts.timeoutMs;
-    }
-    return _execNormalized(command, shell, coreOpts);
-}
-/**
- * Execute a command and return its exit code.
- *
- * @param command - Command string (shell) or argv array (shell-off supported).
- * @param shell - Shell setting (false for plain execution).
- * @param opts - Execution options (cwd/env/stdio).
- * @returns A promise resolving to the process exit code.
- */
-async function runCommand(command, shell, opts) {
-    // Build opts without injecting undefined (exactOptionalPropertyTypes-safe)
-    const callOpts = {};
-    if (opts.cwd !== undefined) {
-        callOpts.cwd = opts.cwd;
-    }
-    if (opts.env !== undefined) {
-        callOpts.env = opts.env;
-    }
-    if (opts.stdio !== undefined)
-        callOpts.stdio = opts.stdio;
-    const ok = await _execNormalized(command, shell, callOpts);
-    if (opts.stdio === 'pipe' && ok.stdout) {
-        process.stdout.write(ok.stdout + (ok.stdout.endsWith('\n') ? '' : '\n'));
-    }
-    return typeof ok.exitCode === 'number' ? ok.exitCode : Number.NaN;
-}
-
-/**
- * Attach root flags to a {@link GetDotenvCli} instance.
- *
- * Program is typed as {@link GetDotenvCli} and supports {@link GetDotenvCli.createDynamicOption | createDynamicOption}.
- */
-const attachRootOptions = (program, defaults) => {
-    const GROUP = 'base';
-    const { defaultEnv, dotenvToken, dynamicPath, env, outputPath, paths, pathsDelimiter, pathsDelimiterPattern, privateToken, varsAssignor, varsAssignorPattern, varsDelimiter, varsDelimiterPattern, } = defaults ?? {};
-    const va = typeof defaults?.varsAssignor === 'string' ? defaults.varsAssignor : '=';
-    const vd = typeof defaults?.varsDelimiter === 'string' ? defaults.varsDelimiter : ' ';
-    // Helper: append (default) tags for ON/OFF toggles
-    const onOff = (on, isDefault) => on
-        ? `ON${isDefault ? ' (default)' : ''}`
-        : `OFF${isDefault ? ' (default)' : ''}`;
-    program.enablePositionalOptions().passThroughOptions();
-    // -e, --env <string>
-    {
-        const opt = new Option('-e, --env <string>', 'target environment (dotenv-expanded)');
-        opt.argParser(dotenvExpandFromProcessEnv);
-        if (env !== undefined)
-            opt.default(env);
-        program.addOption(opt);
-        program.setOptionGroup(opt, GROUP);
-    }
-    // -v, --vars <string>
-    {
-        const examples = [
-            ['KEY1', 'VAL1'],
-            ['KEY2', 'VAL2'],
-        ]
-            .map((v) => v.join(va))
-            .join(vd);
-        const opt = new Option('-v, --vars <string>', `extra variables expressed as delimited key-value pairs (dotenv-expanded): ${examples}`);
-        opt.argParser(dotenvExpandFromProcessEnv);
-        program.addOption(opt);
-        program.setOptionGroup(opt, GROUP);
-    }
-    // Output path (interpolated later; help can remain static)
-    {
-        const opt = new Option('-o, --output-path <string>', 'consolidated output file  (dotenv-expanded)');
-        opt.argParser(dotenvExpandFromProcessEnv);
-        if (outputPath !== undefined)
-            opt.default(outputPath);
-        program.addOption(opt);
-        program.setOptionGroup(opt, GROUP);
-    }
-    // Shell ON (string or boolean true => default shell)
-    {
-        const opt = program
-            .createDynamicOption('-s, --shell [string]', (cfg) => {
-            const s = cfg.shell;
-            let tag = '';
-            if (typeof s === 'boolean' && s)
-                tag = ' (default OS shell)';
-            else if (typeof s === 'string' && s.length > 0)
-                tag = ` (default ${s})`;
-            return `command execution shell, no argument for default OS shell or provide shell string${tag}`;
-        })
-            .conflicts('shellOff');
-        program.addOption(opt);
-        program.setOptionGroup(opt, GROUP);
-    }
-    // Shell OFF
-    {
-        const opt = program
-            .createDynamicOption('-S, --shell-off', (cfg) => {
-            const s = cfg.shell;
-            return `command execution shell OFF${s === false ? ' (default)' : ''}`;
-        })
-            .conflicts('shell');
-        program.addOption(opt);
-        program.setOptionGroup(opt, GROUP);
-    }
-    // Load process ON/OFF (dynamic defaults)
-    {
-        const optOn = program
-            .createDynamicOption('-p, --load-process', (cfg) => `load variables to process.env ${onOff(true, Boolean(cfg.loadProcess))}`)
-            .conflicts('loadProcessOff');
-        program.addOption(optOn);
-        program.setOptionGroup(optOn, GROUP);
-        const optOff = program
-            .createDynamicOption('-P, --load-process-off', (cfg) => `load variables to process.env ${onOff(false, !cfg.loadProcess)}`)
-            .conflicts('loadProcess');
-        program.addOption(optOff);
-        program.setOptionGroup(optOff, GROUP);
-    }
-    // Exclusion master toggle (dynamic)
-    {
-        const optAll = program
-            .createDynamicOption('-a, --exclude-all', (cfg) => {
-            const allOn = !!cfg.excludeDynamic &&
-                ((!!cfg.excludeEnv && !!cfg.excludeGlobal) ||
-                    (!!cfg.excludePrivate && !!cfg.excludePublic));
-            const suffix = allOn ? ' (default)' : '';
-            return `exclude all dotenv variables from loading ON${suffix}`;
-        })
-            .conflicts('excludeAllOff');
-        program.addOption(optAll);
-        program.setOptionGroup(optAll, GROUP);
-        const optAllOff = new Option('-A, --exclude-all-off', 'exclude all dotenv variables from loading OFF (default)').conflicts('excludeAll');
-        program.addOption(optAllOff);
-        program.setOptionGroup(optAllOff, GROUP);
-    }
-    // Per-family exclusions (dynamic defaults)
-    {
-        const o1 = program
-            .createDynamicOption('-z, --exclude-dynamic', (cfg) => `exclude dynamic dotenv variables from loading ${onOff(true, Boolean(cfg.excludeDynamic))}`)
-            .conflicts('excludeDynamicOff');
-        program.addOption(o1);
-        program.setOptionGroup(o1, GROUP);
-        const o2 = program
-            .createDynamicOption('-Z, --exclude-dynamic-off', (cfg) => `exclude dynamic dotenv variables from loading ${onOff(false, !cfg.excludeDynamic)}`)
-            .conflicts('excludeDynamic');
-        program.addOption(o2);
-        program.setOptionGroup(o2, GROUP);
-    }
-    {
-        const o1 = program
-            .createDynamicOption('-n, --exclude-env', (cfg) => `exclude environment-specific dotenv variables from loading ${onOff(true, Boolean(cfg.excludeEnv))}`)
-            .conflicts('excludeEnvOff');
-        program.addOption(o1);
-        program.setOptionGroup(o1, GROUP);
-        const o2 = program
-            .createDynamicOption('-N, --exclude-env-off', (cfg) => `exclude environment-specific dotenv variables from loading ${onOff(false, !cfg.excludeEnv)}`)
-            .conflicts('excludeEnv');
-        program.addOption(o2);
-        program.setOptionGroup(o2, GROUP);
-    }
-    {
-        const o1 = program
-            .createDynamicOption('-g, --exclude-global', (cfg) => `exclude global dotenv variables from loading ${onOff(true, Boolean(cfg.excludeGlobal))}`)
-            .conflicts('excludeGlobalOff');
-        program.addOption(o1);
-        program.setOptionGroup(o1, GROUP);
-        const o2 = program
-            .createDynamicOption('-G, --exclude-global-off', (cfg) => `exclude global dotenv variables from loading ${onOff(false, !cfg.excludeGlobal)}`)
-            .conflicts('excludeGlobal');
-        program.addOption(o2);
-        program.setOptionGroup(o2, GROUP);
-    }
-    {
-        const p1 = program
-            .createDynamicOption('-r, --exclude-private', (cfg) => `exclude private dotenv variables from loading ${onOff(true, Boolean(cfg.excludePrivate))}`)
-            .conflicts('excludePrivateOff');
-        program.addOption(p1);
-        program.setOptionGroup(p1, GROUP);
-        const p2 = program
-            .createDynamicOption('-R, --exclude-private-off', (cfg) => `exclude private dotenv variables from loading ${onOff(false, !cfg.excludePrivate)}`)
-            .conflicts('excludePrivate');
-        program.addOption(p2);
-        program.setOptionGroup(p2, GROUP);
-        const pu1 = program
-            .createDynamicOption('-u, --exclude-public', (cfg) => `exclude public dotenv variables from loading ${onOff(true, Boolean(cfg.excludePublic))}`)
-            .conflicts('excludePublicOff');
-        program.addOption(pu1);
-        program.setOptionGroup(pu1, GROUP);
-        const pu2 = program
-            .createDynamicOption('-U, --exclude-public-off', (cfg) => `exclude public dotenv variables from loading ${onOff(false, !cfg.excludePublic)}`)
-            .conflicts('excludePublic');
-        program.addOption(pu2);
-        program.setOptionGroup(pu2, GROUP);
-    }
-    // Log ON/OFF (dynamic)
-    {
-        const lo = program
-            .createDynamicOption('-l, --log', (cfg) => `console log loaded variables ${onOff(true, Boolean(cfg.log))}`)
-            .conflicts('logOff');
-        program.addOption(lo);
-        program.setOptionGroup(lo, GROUP);
-        const lf = program
-            .createDynamicOption('-L, --log-off', (cfg) => `console log loaded variables ${onOff(false, !cfg.log)}`)
-            .conflicts('log');
-        program.addOption(lf);
-        program.setOptionGroup(lf, GROUP);
-    }
-    // Capture flag (no default display; static)
-    {
-        const opt = new Option('--capture', 'capture child process stdio for commands (tests/CI)');
-        program.addOption(opt);
-        program.setOptionGroup(opt, GROUP);
-    }
-    // Core bootstrap/static flags (kept static in help)
-    {
-        const o1 = new Option('--default-env <string>', 'default target environment');
-        o1.argParser(dotenvExpandFromProcessEnv);
-        if (defaultEnv !== undefined)
-            o1.default(defaultEnv);
-        program.addOption(o1);
-        program.setOptionGroup(o1, GROUP);
-        const o2 = new Option('--dotenv-token <string>', 'dotenv-expanded token indicating a dotenv file');
-        o2.argParser(dotenvExpandFromProcessEnv);
-        if (dotenvToken !== undefined)
-            o2.default(dotenvToken);
-        program.addOption(o2);
-        program.setOptionGroup(o2, GROUP);
-        const o3 = new Option('--dynamic-path <string>', 'dynamic variables path (.js or .ts; .ts is auto-compiled when esbuild is available, otherwise precompile)');
-        o3.argParser(dotenvExpandFromProcessEnv);
-        if (dynamicPath !== undefined)
-            o3.default(dynamicPath);
-        program.addOption(o3);
-        program.setOptionGroup(o3, GROUP);
-        const o4 = new Option('--paths <string>', 'dotenv-expanded delimited list of paths to dotenv directory');
-        o4.argParser(dotenvExpandFromProcessEnv);
-        if (paths !== undefined)
-            o4.default(paths);
-        program.addOption(o4);
-        program.setOptionGroup(o4, GROUP);
-        const o5 = new Option('--paths-delimiter <string>', 'paths delimiter string');
-        if (pathsDelimiter !== undefined)
-            o5.default(pathsDelimiter);
-        program.addOption(o5);
-        program.setOptionGroup(o5, GROUP);
-        const o6 = new Option('--paths-delimiter-pattern <string>', 'paths delimiter regex pattern');
-        if (pathsDelimiterPattern !== undefined)
-            o6.default(pathsDelimiterPattern);
-        program.addOption(o6);
-        program.setOptionGroup(o6, GROUP);
-        const o7 = new Option('--private-token <string>', 'dotenv-expanded token indicating private variables');
-        o7.argParser(dotenvExpandFromProcessEnv);
-        if (privateToken !== undefined)
-            o7.default(privateToken);
-        program.addOption(o7);
-        program.setOptionGroup(o7, GROUP);
-        const o8 = new Option('--vars-delimiter <string>', 'vars delimiter string');
-        if (varsDelimiter !== undefined)
-            o8.default(varsDelimiter);
-        program.addOption(o8);
-        program.setOptionGroup(o8, GROUP);
-        const o9 = new Option('--vars-delimiter-pattern <string>', 'vars delimiter regex pattern');
-        if (varsDelimiterPattern !== undefined)
-            o9.default(varsDelimiterPattern);
-        program.addOption(o9);
-        program.setOptionGroup(o9, GROUP);
-        const o10 = new Option('--vars-assignor <string>', 'vars assignment operator string');
-        if (varsAssignor !== undefined)
-            o10.default(varsAssignor);
-        program.addOption(o10);
-        program.setOptionGroup(o10, GROUP);
-        const o11 = new Option('--vars-assignor-pattern <string>', 'vars assignment operator regex pattern');
-        if (varsAssignorPattern !== undefined)
-            o11.default(varsAssignorPattern);
-        program.addOption(o11);
-        program.setOptionGroup(o11, GROUP);
-    }
-    // Diagnostics / validation / entropy
-    {
-        const tr = new Option('--trace [keys...]', 'emit diagnostics for child env composition (optional keys)');
-        program.addOption(tr);
-        program.setOptionGroup(tr, GROUP);
-        const st = new Option('--strict', 'fail on env validation errors (schema/requiredKeys)');
-        program.addOption(st);
-        program.setOptionGroup(st, GROUP);
-    }
-    {
-        const w = program
-            .createDynamicOption('--entropy-warn', (cfg) => {
-            const warn = cfg.warnEntropy;
-            // Default is effectively ON when warnEntropy is true or undefined.
-            return `enable entropy warnings${warn === false ? '' : ' (default on)'}`;
-        })
-            .conflicts('entropyWarnOff');
-        program.addOption(w);
-        program.setOptionGroup(w, GROUP);
-        const woff = program
-            .createDynamicOption('--entropy-warn-off', (cfg) => `disable entropy warnings${cfg.warnEntropy === false ? ' (default)' : ''}`)
-            .conflicts('entropyWarn');
-        program.addOption(woff);
-        program.setOptionGroup(woff, GROUP);
-        const th = new Option('--entropy-threshold <number>', 'entropy bits/char threshold (default 3.8)');
-        program.addOption(th);
-        program.setOptionGroup(th, GROUP);
-        const ml = new Option('--entropy-min-length <number>', 'min length to examine for entropy (default 16)');
-        program.addOption(ml);
-        program.setOptionGroup(ml, GROUP);
-        const wl = new Option('--entropy-whitelist <pattern...>', 'suppress entropy warnings when key matches any regex pattern');
-        program.addOption(wl);
-        program.setOptionGroup(wl, GROUP);
-        const rp = new Option('--redact-pattern <pattern...>', 'additional key-match regex patterns to trigger redaction');
-        program.addOption(rp);
-        program.setOptionGroup(rp, GROUP);
-        // Redact ON/OFF (dynamic)
-        {
-            const rOn = program
-                .createDynamicOption('--redact', (cfg) => `presentation-time redaction for secret-like keys ON${cfg.redact ? ' (default)' : ''}`)
-                .conflicts('redactOff');
-            program.addOption(rOn);
-            program.setOptionGroup(rOn, GROUP);
-            const rOff = program
-                .createDynamicOption('--redact-off', (cfg) => `presentation-time redaction for secret-like keys OFF${cfg.redact === false ? ' (default)' : ''}`)
-                .conflicts('redact');
-            program.addOption(rOff);
-            program.setOptionGroup(rOff, GROUP);
-        }
-    }
-    return program;
-};
-
-/**
- * Registry for option grouping.
- * Root help renders these groups between "Options" and "Commands".
- */
-const GROUP_TAG = new WeakMap();
-/**
- * Render help option groups (App/Plugins) for a given command.
- * Groups are injected between Options and Commands in the help output.
- */
-function renderOptionGroups(cmd) {
-    const all = cmd.options;
-    const byGroup = new Map();
-    for (const o of all) {
-        const opt = o;
-        const g = GROUP_TAG.get(opt);
-        if (!g || g === 'base')
-            continue; // base handled by default help
-        const rows = byGroup.get(g) ?? [];
-        rows.push({
-            flags: opt.flags,
-            description: opt.description ?? '',
-        });
-        byGroup.set(g, rows);
-    }
-    if (byGroup.size === 0)
-        return '';
-    const renderRows = (title, rows) => {
-        const width = Math.min(40, rows.reduce((m, r) => Math.max(m, r.flags.length), 0));
-        // Sort within group: short-aliased flags first
-        rows.sort((a, b) => {
-            const aS = /(^|\s|,)-[A-Za-z]/.test(a.flags) ? 1 : 0;
-            const bS = /(^|\s|,)-[A-Za-z]/.test(b.flags) ? 1 : 0;
-            return bS - aS || a.flags.localeCompare(b.flags);
-        });
-        const lines = rows
-            .map((r) => {
-            const pad = ' '.repeat(Math.max(2, width - r.flags.length + 2));
-            return `  ${r.flags}${pad}${r.description}`.trimEnd();
-        })
-            .join('\n');
-        return `\n${title}:\n${lines}\n`;
-    };
-    let out = '';
-    // App options (if any)
-    const app = byGroup.get('app');
-    if (app && app.length > 0) {
-        out += renderRows('App options', app);
-    }
-    // Plugin groups sorted by id; suppress self group on the owning command name.
-    const pluginKeys = Array.from(byGroup.keys()).filter((k) => k.startsWith('plugin:'));
-    const currentName = cmd.name();
-    pluginKeys.sort((a, b) => a.localeCompare(b));
-    for (const k of pluginKeys) {
-        const id = k.slice('plugin:'.length) || '(unknown)';
-        const rows = byGroup.get(k) ?? [];
-        if (rows.length > 0 && id !== currentName) {
-            out += renderRows(`Plugin options — ${id}`, rows);
-        }
-    }
-    return out;
-}
-
-/**
- * Compose root/parent help output by inserting grouped sections between
- * Options and Commands, ensuring a trailing blank line.
- *
- * @param base - Base help text produced by Commander.
- * @param cmd - Command instance whose grouped options should be rendered.
- * @returns The modified help text with grouped blocks inserted.
- */
-function buildHelpInformation(base, cmd) {
-    const groups = renderOptionGroups(cmd);
-    const block = typeof groups === 'string' ? groups.trim() : '';
-    if (!block) {
-        return base.endsWith('\n\n')
-            ? base
-            : base.endsWith('\n')
-                ? `${base}\n`
-                : `${base}\n\n`;
-    }
-    const marker = '\nCommands:';
-    const idx = base.indexOf(marker);
-    let out = base;
-    if (idx >= 0) {
-        const toInsert = groups.startsWith('\n') ? groups : `\n${groups}`;
-        out = `${base.slice(0, idx)}${toInsert}${base.slice(idx)}`;
-    }
-    else {
-        const sep = base.endsWith('\n') || groups.startsWith('\n') ? '' : '\n';
-        out = `${base}${sep}${groups}`;
-    }
-    return out.endsWith('\n\n')
-        ? out
-        : out.endsWith('\n')
-            ? `${out}\n`
-            : `${out}\n\n`;
-}
-
-/** src/cliHost/GetDotenvCli/dynamicOptions.ts
- * Helpers for dynamic option descriptions and evaluation.
- */
-/**
- * Registry for dynamic descriptions keyed by Option (WeakMap for GC safety).
- */
-const DYN_DESC = new WeakMap();
-/**
- * Create an Option with a dynamic description callback stored in DYN_DESC.
- */
-function makeDynamicOption(flags, desc, parser, defaultValue) {
-    const opt = new Option(flags, '');
-    DYN_DESC.set(opt, desc);
-    if (parser) {
-        opt.argParser((value, previous) => parser(value, previous));
-    }
-    if (defaultValue !== undefined)
-        opt.default(defaultValue);
-    // Commander.Option is structurally compatible; help-time wiring is stored in DYN_DESC.
-    return opt;
-}
-/**
- * Evaluate dynamic descriptions across a command tree using the resolved config.
- */
-function evaluateDynamicOptions(root, resolved) {
-    const visit = (cmd) => {
-        const arr = cmd.options;
-        for (const o of arr) {
-            const dyn = DYN_DESC.get(o);
-            if (typeof dyn === 'function') {
-                try {
-                    const txt = dyn(resolved);
-                    // Commander uses Option.description during help rendering.
-                    o.description = txt;
-                }
-                catch {
-                    /* best-effort; leave as-is */
-                }
-            }
-        }
-        for (const c of cmd.commands)
-            visit(c);
-    };
-    visit(root);
-}
-
-/**
- * Initialize a {@link GetDotenvCli} instance with help configuration and safe defaults.
- *
- * @remarks
- * This is a low-level initializer used by the host constructor to keep `GetDotenvCli.ts`
- * small and to centralize help/output behavior.
- *
- * @param cli - The CLI instance to initialize.
- * @param headerGetter - Callback returning an optional help header string.
- */
-function initializeInstance(cli, headerGetter) {
-    // Configure grouped help: show only base options in default "Options";
-    // subcommands show all of their own options.
-    cli.configureHelp({
-        visibleOptions: (cmd) => {
-            const all = cmd.options;
-            const isRoot = cmd.parent === null;
-            const list = isRoot
-                ? all.filter((opt) => {
-                    const group = GROUP_TAG.get(opt);
-                    return group === 'base';
-                })
-                : all.slice();
-            // Sort: short-aliased options first, then long-only; stable by flags.
-            const hasShort = (opt) => {
-                const flags = opt.flags;
-                return /(^|\s|,)-[A-Za-z]/.test(flags);
-            };
-            const byFlags = (opt) => opt.flags;
-            list.sort((a, b) => {
-                const aS = hasShort(a) ? 1 : 0;
-                const bS = hasShort(b) ? 1 : 0;
-                return bS - aS || byFlags(a).localeCompare(byFlags(b));
-            });
-            return list;
-        },
-    });
-    // Optional branded header before help text (kept minimal and deterministic).
-    cli.addHelpText('beforeAll', () => {
-        const header = headerGetter();
-        return header && header.length > 0 ? `${header}\n\n` : '';
-    });
-    // Tests-only: suppress process.exit during help/version flows under Vitest.
-    // Unit tests often construct GetDotenvCli directly (bypassing createCli),
-    // so install a local exitOverride when a test environment is detected.
-    const underTests = process.env.GETDOTENV_TEST === '1' ||
-        typeof process.env.VITEST_WORKER_ID === 'string';
-    if (underTests) {
-        cli.exitOverride((err) => {
-            const code = err?.code;
-            if (code === 'commander.helpDisplayed' ||
-                code === 'commander.version' ||
-                code === 'commander.help')
-                return;
-            throw err;
-        });
-    }
-    // Ensure the root has a no-op action so preAction hooks installed by
-    // passOptions() fire for root-only invocations (no subcommand).
-    // Subcommands still take precedence and will not hit this action.
-    // This keeps root-side effects (e.g., --log) working in direct hosts/tests.
-    cli.action(() => {
-        /* no-op */
-    });
-    // PreSubcommand hook: compute a context if absent, without mutating process.env.
-    // The passOptions() helper, when installed, resolves the final context.
-    cli.hook('preSubcommand', async () => {
-        if (cli.hasCtx())
-            return;
-        await cli.resolveAndLoad({ loadProcess: false });
-    });
-}
-
-/**
- * Determine the effective namespace for a child plugin (override \> default).
- */
-const effectiveNs = (child) => {
-    const o = child.override;
-    return (o && typeof o.ns === 'string' && o.ns.length > 0 ? o.ns : child.plugin.ns).trim();
-};
-const isPromise = (v) => !!v && typeof v.then === 'function';
-function runInstall(parentCli, plugin) {
-    // Create mount and run setup
-    const mount = parentCli.ns(plugin.ns);
-    const setupRet = plugin.setup(mount);
-    const pending = [];
-    if (isPromise(setupRet))
-        pending.push(setupRet.then(() => undefined));
-    // Enforce sibling uniqueness before creating children
-    const names = new Set();
-    for (const entry of plugin.children) {
-        const ns = effectiveNs(entry);
-        if (names.has(ns)) {
-            const under = mount.name();
-            throw new Error(`Duplicate namespace '${ns}' under '${under || 'root'}'. Override via .use(plugin, { ns: '...' }).`);
-        }
-        names.add(ns);
-    }
-    // Install children (pre-order), synchronously when possible
-    for (const entry of plugin.children) {
-        const childRet = runInstall(mount, entry.plugin);
-        if (isPromise(childRet))
-            pending.push(childRet);
-    }
-    if (pending.length > 0)
-        return Promise.all(pending).then(() => undefined);
-    return;
-}
-/**
- * Install a plugin and its children (pre-order setup phase).
- * Enforces sibling namespace uniqueness.
- */
-function setupPluginTree(cli, plugin) {
-    const ret = runInstall(cli, plugin);
-    return isPromise(ret) ? ret : Promise.resolve();
-}
-
-/**
- * Resolve options strictly and compute the dotenv context via the loader/overlay path.
- *
- * @param customOptions - Partial options overlay.
- * @param plugins - Plugins list for config validation.
- * @param hostMetaUrl - Import URL for resolving the packaged root.
- */
-async function resolveAndComputeContext(customOptions, plugins, hostMetaUrl) {
-    const optionsResolved = await resolveGetDotenvOptions(customOptions);
-    // Strict schema validation
-    getDotenvOptionsSchemaResolved.parse(optionsResolved);
-    const ctx = await computeContext(optionsResolved, plugins, hostMetaUrl);
-    return ctx;
-}
-
-/**
- * Run afterResolve hooks for a plugin tree (parent → children).
- */
-async function runAfterResolveTree(cli, plugins, ctx) {
-    const run = async (p) => {
-        if (p.afterResolve)
-            await p.afterResolve(cli, ctx);
-        for (const child of p.children)
-            await run(child.plugin);
-    };
-    for (const p of plugins)
-        await run(p);
-}
-
-/**
- * Temporarily tag options added during a callback as 'app' for grouped help.
- * Wraps `addOption` on the command instance.
- */
-function tagAppOptionsAround(root, setOptionGroup, fn) {
-    const originalAddOption = root.addOption.bind(root);
-    root.addOption = ((opt) => {
-        setOptionGroup(opt, 'app');
-        return originalAddOption(opt);
-    });
-    try {
-        return fn(root);
-    }
-    finally {
-        root.addOption = originalAddOption;
-    }
-}
-
-/**
- * Read the version from the nearest `package.json` relative to the provided import URL.
- *
- * @param importMetaUrl - The `import.meta.url` of the calling module.
- * @returns The version string or undefined if not found.
- */
-async function readPkgVersion(importMetaUrl) {
-    if (!importMetaUrl)
-        return undefined;
-    try {
-        const fromUrl = fileURLToPath(importMetaUrl);
-        const pkgDir = await packageDirectory({ cwd: fromUrl });
-        if (!pkgDir)
-            return undefined;
-        const txt = await fs.readFile(`${pkgDir}/package.json`, 'utf-8');
-        const pkg = JSON.parse(txt);
-        return pkg.version ?? undefined;
-    }
-    catch {
-        // best-effort only
-        return undefined;
-    }
-}
-
-/** src/cliHost/GetDotenvCli.ts
- * Plugin-first CLI host for get-dotenv with Commander generics preserved.
- * Public surface implements GetDotenvCliPublic and provides:
- *  - attachRootOptions (builder-only; no public override wiring)
- *  - resolveAndLoad (strict resolve + context compute)
- *  - getCtx/hasCtx accessors
- *  - ns() for typed subcommand creation with duplicate-name guard
- *  - grouped help rendering with dynamic option descriptions
- */
-const HOST_META_URL = import.meta.url;
-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.
- */
-class GetDotenvCli extends Command {
-    /** Registered top-level plugins (composition happens via .use()) */
-    _plugins = [];
-    /** One-time installation guard */
-    _installed = false;
-    /** In-flight installation promise to guard against concurrent installs */
-    _installing;
-    /** Optional header line to prepend in help output */
-    [HELP_HEADER_SYMBOL];
-    /** Context/options stored under symbols (typed) */
-    [CTX_SYMBOL];
-    [OPTS_SYMBOL];
-    /**
-     * Create a subcommand using the same subclass, preserving helpers like
-     * dynamicOption on children.
-     */
-    createCommand(name) {
-        // Explicitly construct a GetDotenvCli for children to preserve helpers.
-        return new GetDotenvCli(name);
-    }
-    constructor(alias = 'getdotenv') {
-        super(alias);
-        this.enablePositionalOptions();
-        // Delegate the heavy setup to a helper to keep the constructor lean.
-        initializeInstance(this, () => this[HELP_HEADER_SYMBOL]);
-    }
-    /**
-     * Attach legacy/base root flags to this CLI instance.
-     * Delegates to the pure builder in attachRootOptions.ts.
-     */
-    attachRootOptions(defaults) {
-        const d = (defaults ?? baseRootOptionDefaults);
-        attachRootOptions(this, d);
-        return this;
-    }
-    /**
-     * Resolve options (strict) and compute dotenv context.
-     * Stores the context on the instance under a symbol.
-     *
-     * Options:
-     * - opts.runAfterResolve (default true): when false, skips running plugin
-     *   afterResolve hooks. Useful for top-level help rendering to avoid
-     *   long-running side-effects while still evaluating dynamic help text.
-     */
-    async resolveAndLoad(customOptions = {}, opts) {
-        const ctx = await resolveAndComputeContext(customOptions, 
-        // Pass only plugin instances to the resolver (not entries with overrides)
-        this._plugins.map((e) => e.plugin), 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();
-        if (opts?.runAfterResolve ?? true) {
-            await this._runAfterResolve(ctx);
-        }
-        return ctx;
-    }
-    // Implementation
-    createDynamicOption(flags, desc, parser, defaultValue) {
-        return makeDynamicOption(flags, (c) => desc(c), parser, defaultValue);
-    }
-    /**
-     * Evaluate dynamic descriptions for this command and all descendants using
-     * the provided resolved configuration. Mutates the Option.description in
-     * place so Commander help renders updated text.
-     */
-    evaluateDynamicOptions(resolved) {
-        evaluateDynamicOptions(this, resolved);
-    }
-    /** Internal: climb to the true root (host) command. */
-    _root() {
-        let node = this;
-        while (node.parent) {
-            node = node.parent;
-        }
-        return node;
-    }
-    /**
-     * Retrieve the current invocation context (if any).
-     */
-    getCtx() {
-        let ctx = this[CTX_SYMBOL];
-        if (!ctx) {
-            const root = this._root();
-            ctx = root[CTX_SYMBOL];
-        }
-        if (!ctx) {
-            throw new Error('Dotenv context unavailable. Ensure resolveAndLoad() has been called or the host is wired with passOptions() before invoking commands.');
-        }
-        return ctx;
-    }
-    /**
-     * Check whether a context has been resolved (non-throwing guard).
-     */
-    hasCtx() {
-        if (this[CTX_SYMBOL] !== undefined)
-            return true;
-        const root = this._root();
-        return root[CTX_SYMBOL] !== undefined;
-    }
-    /**
-     * Retrieve the merged root CLI options bag (if set by passOptions()).
-     * Downstream-safe: no generics required.
-     */
-    getOptions() {
-        if (this[OPTS_SYMBOL])
-            return this[OPTS_SYMBOL];
-        const root = this._root();
-        const bag = root[OPTS_SYMBOL];
-        if (bag)
-            return bag;
-        return undefined;
-    }
-    /** Internal: set the merged root options bag for this run. */
-    _setOptionsBag(bag) {
-        this[OPTS_SYMBOL] = bag;
-    }
-    /**
-     * Convenience helper to create a namespaced subcommand with argument inference.
-     * This mirrors Commander generics so downstream chaining stays fully typed.
-     */
-    ns(name) {
-        // Guard against same-level duplicate command names for clearer diagnostics.
-        const exists = this.commands.some((c) => c.name() === name);
-        if (exists) {
-            throw new Error(`Duplicate command name: ${name}`);
-        }
-        return this.command(name);
-    }
-    /**
-     * Tag options added during the provided callback as 'app' for grouped help.
-     * Allows downstream apps to demarcate their root-level options.
-     */
-    tagAppOptions(fn) {
-        return tagAppOptionsAround(this, this.setOptionGroup.bind(this), fn);
-    }
-    /**
-     * 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);
-        const v = version ?? (await readPkgVersion(importMetaUrl));
-        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) {
-            const header = `${this.name()} v${v}`;
-            this[HELP_HEADER_SYMBOL] = header;
-        }
-        return this;
-    }
-    /**
-     * Insert grouped plugin/app options between "Options" and "Commands" for
-     * hybrid ordering. Applies to root and any parent command.
-     */
-    helpInformation() {
-        return buildHelpInformation(super.helpInformation(), this);
-    }
-    /**
-     * Public: tag an Option with a display group for help (root/app/plugin:<id>).
-     */
-    setOptionGroup(opt, group) {
-        GROUP_TAG.set(opt, group);
-    }
-    /**
-     * Register a plugin for installation (parent level).
-     * Installation occurs on first resolveAndLoad() (or explicit install()).
-     */
-    use(plugin, override) {
-        this._plugins.push({ plugin, override });
-        return this;
-    }
-    /**
-     * Install all registered plugins in parent → children (pre-order).
-     * Runs only once per CLI instance.
-     */
-    async install() {
-        if (this._installed)
-            return;
-        if (this._installing) {
-            await this._installing;
-            return;
-        }
-        this._installing = (async () => {
-            // Install parent → children with host-created mounts (async-aware).
-            for (const entry of this._plugins) {
-                const p = entry.plugin;
-                await setupPluginTree(this, p);
-            }
-            this._installed = true;
-        })();
-        try {
-            await this._installing;
-        }
-        finally {
-            // leave _installing as resolved; subsequent calls return early via _installed
-        }
-    }
-    /**
-     * Run afterResolve hooks for all plugins (parent → children).
-     */
-    async _runAfterResolve(ctx) {
-        await runAfterResolveTree(this, this._plugins.map((e) => e.plugin), ctx);
-    }
-}
-
-/**
- * Retrieve the merged root options bag from the current command context.
- * Climbs to the root `GetDotenvCli` instance to access the persisted options.
- *
- * @param cmd - The current command instance (thisCommand).
- * @throws Error if the root is not a GetDotenvCli or options are missing.
- */
-const readMergedOptions = (cmd) => {
-    // Climb to the true root
-    let root = cmd;
-    while (root.parent)
-        root = root.parent;
-    // Assert we ended at our host
-    if (!(root instanceof GetDotenvCli)) {
-        throw new Error('readMergedOptions: root command is not a GetDotenvCli.' +
-            'Ensure your CLI is constructed with GetDotenvCli.');
-    }
-    // Require passOptions() to have persisted the bag
-    const bag = root.getOptions();
-    if (!bag || typeof bag !== 'object') {
-        throw new Error('readMergedOptions: merged options are unavailable. ' +
-            'Call .passOptions() on the host before parsing.');
-    }
-    return bag;
-};
-
-/**
- * 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 ScriptsTable} 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).
- */
-/**
- * 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 dropUndefined = (bag) => Object.fromEntries(Object.entries(bag).filter((e) => typeof e[1] === 'string'));
-/**
- * Build a sanitized environment object for spawning child processes.
- * Merges `base` and `overlay`, drops undefined values, and handles platform-specific
- * normalization (e.g. case-insensitivity on Windows).
- *
- * @param base - Base environment (usually `process.env`).
- * @param overlay - Environment variables to 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;
-};
+import { r as runCommand, a as runCommandResult, s as shouldCapture, d as resolveShell, b as buildSpawnEnv } from './chunks/spawnEnv-CN8a7cNR.mjs';
+import './chunks/overlayEnv-Bs2kVayG.mjs';
+import './chunks/loadModuleDefault-Dj8B3Stt.mjs';
 
 /**
  * Apply resolved AWS context to `process.env` and `ctx.plugins`.
@@ -2603,7 +80,19 @@ function applyAwsContext(out, ctx, setProcessEnv = true) {
     };
 }
 
-const AWS_CLI_TIMEOUT_MS = 15_000;
+// Keep AWS CLI probing bounded so the aws plugin does not stall unrelated commands.
+// This is especially important when a profile is present but SSO refresh/export
+// is slow or blocked (common on Windows).
+const AWS_CLI_TIMEOUT_MS = 3_000;
+const AWS_CLI_BUDGET_MS = 9_000;
+const pickTimeoutMs = (deadlineMs) => {
+    if (typeof deadlineMs !== 'number')
+        return AWS_CLI_TIMEOUT_MS;
+    const remaining = deadlineMs - Date.now();
+    if (remaining <= 0)
+        return 0;
+    return Math.min(AWS_CLI_TIMEOUT_MS, remaining);
+};
 const trim = (s) => (typeof s === 'string' ? s.trim() : '');
 const unquote = (s) => s.length >= 2 &&
     ((s.startsWith('"') && s.endsWith('"')) ||
@@ -2687,7 +176,10 @@ const parseExportCredentialsEnv = (txt) => {
         };
     return undefined;
 };
-const getAwsConfigure = async (key, profile, timeoutMs = AWS_CLI_TIMEOUT_MS) => {
+const getAwsConfigure = async (key, profile, deadlineMs) => {
+    const timeoutMs = pickTimeoutMs(deadlineMs);
+    if (timeoutMs <= 0)
+        return undefined;
     const r = await runCommandResult(['aws', 'configure', 'get', key, '--profile', profile], false, {
         env: process.env,
         timeoutMs,
@@ -2702,8 +194,11 @@ const getAwsConfigure = async (key, profile, timeoutMs = AWS_CLI_TIMEOUT_MS) =>
     }
     return undefined;
 };
-const exportCredentials = async (profile, timeoutMs = AWS_CLI_TIMEOUT_MS) => {
+const exportCredentials = async (profile, deadlineMs) => {
     const tryExport = async (format) => {
+        const timeoutMs = pickTimeoutMs(deadlineMs);
+        if (timeoutMs <= 0)
+            return undefined;
         const argv = [
             'aws',
             'configure',
@@ -2724,20 +219,13 @@ const exportCredentials = async (profile, timeoutMs = AWS_CLI_TIMEOUT_MS) => {
         // Some formats produce JSON ("process"), some produce shell-ish env lines.
         return parseExportCredentialsJson(out) ?? parseExportCredentialsEnv(out);
     };
-    // Prefer the default/JSON "process" format first; then fall back to shell env outputs.
-    // Note: AWS CLI v2 supports: process | env | env-no-export | powershell | windows-cmd
-    const formats = [
-        'process',
-        ...(process.platform === 'win32'
-            ? ['powershell', 'windows-cmd', 'env', 'env-no-export']
-            : ['env', 'env-no-export']),
-    ];
-    for (const f of formats) {
-        const creds = await tryExport(f);
-        if (creds)
-            return creds;
-    }
-    // Final fallback: no --format (AWS CLI default output)
+    // Keep the probe set small; budgeted calls above prevent long hangs.
+    const primary = await tryExport('process');
+    if (primary)
+        return primary;
+    const secondary = await tryExport(process.platform === 'win32' ? 'powershell' : 'env');
+    if (secondary)
+        return secondary;
     return tryExport(undefined);
 };
 /**
@@ -2751,6 +239,7 @@ 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 deadlineMs = cfg.strategy !== 'none' ? Date.now() + AWS_CLI_BUDGET_MS : undefined;
     const profile = cfg.profile ??
         dotenv[profileKey] ??
         dotenv[profileFallbackKey] ??
@@ -2760,7 +249,7 @@ const resolveAwsContext = async ({ dotenv, cfg, }) => {
     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);
+            region = await getAwsConfigure('region', profile, Date.now() + AWS_CLI_BUDGET_MS);
         if (!region && cfg.defaultRegion)
             region = cfg.defaultRegion;
         const out = {};
@@ -2774,12 +263,12 @@ const resolveAwsContext = async ({ dotenv, cfg, }) => {
     // Profile wins over ambient env creds when present (from flags/config/dotenv).
     if (profile) {
         // Try export-credentials
-        credentials = await exportCredentials(profile);
+        credentials = await exportCredentials(profile, deadlineMs);
         // On failure, detect SSO and optionally login then retry
         if (!credentials) {
-            const ssoSession = await getAwsConfigure('sso_session', profile);
+            const ssoSession = await getAwsConfigure('sso_session', profile, deadlineMs);
             // Legacy SSO profiles use sso_start_url/sso_region rather than sso_session.
-            const ssoStartUrl = await getAwsConfigure('sso_start_url', profile);
+            const ssoStartUrl = await getAwsConfigure('sso_start_url', profile, deadlineMs);
             const looksSSO = (typeof ssoSession === 'string' && ssoSession.length > 0) ||
                 (typeof ssoStartUrl === 'string' && ssoStartUrl.length > 0);
             if (looksSSO && cfg.loginOnDemand) {
@@ -2791,14 +280,14 @@ const resolveAwsContext = async ({ dotenv, cfg, }) => {
                 if (exit !== 0) {
                     throw new Error(`aws sso login failed for profile '${profile}' (exit ${String(exit)})`);
                 }
-                credentials = await exportCredentials(profile);
+                credentials = await exportCredentials(profile, deadlineMs);
             }
         }
         // 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);
+            const id = await getAwsConfigure('aws_access_key_id', profile, deadlineMs);
+            const secret = await getAwsConfigure('aws_secret_access_key', profile, deadlineMs);
+            const token = await getAwsConfigure('aws_session_token', profile, deadlineMs);
             if (id && secret) {
                 credentials = {
                     accessKeyId: id,
@@ -2823,7 +312,7 @@ const resolveAwsContext = async ({ dotenv, cfg, }) => {
     }
     // Final region resolution
     if (!region && profile)
-        region = await getAwsConfigure('region', profile);
+        region = await getAwsConfigure('region', profile, deadlineMs);
     if (!region && cfg.defaultRegion)
         region = cfg.defaultRegion;
     const out = {};
@@ -2988,7 +477,7 @@ function attachAwsDefaultAction(cli, plugin, awsCmd) {
  * @internal
  */
 function attachAwsOptions(cli, plugin) {
-    return (cli
+    return cli
         // Description is owned by the plugin index (src/plugins/aws/index.ts).
         .enablePositionalOptions()
         .passThroughOptions()
@@ -3006,7 +495,7 @@ function attachAwsOptions(cli, plugin) {
         .addOption(plugin.createPluginDynamicOption(cli, '--profile-fallback-key <string>', (_bag, cfg) => `fallback dotenv/config key for profile${cfg.profileFallbackKey ? ` (default: ${JSON.stringify(cfg.profileFallbackKey)})` : ''}`))
         .addOption(plugin.createPluginDynamicOption(cli, '--region-key <string>', (_bag, cfg) => `dotenv/config key for region${cfg.regionKey ? ` (default: ${JSON.stringify(cfg.regionKey)})` : ''}`))
         // Accept any extra operands so Commander does not error when tokens appear after "--".
-        .argument('[args...]'));
+        .argument('[args...]');
 }
 
 /**
@@ -3060,8 +549,16 @@ const awsPluginConfigSchema = z.object({
     profileFallbackKey: z.string().default('AWS_PROFILE').optional(),
     /** Dotenv/config key for region lookup (default `AWS_REGION`). */
     regionKey: z.string().default('AWS_REGION').optional(),
-    /** Credential acquisition strategy (`cli-export` to resolve via AWS CLI, or `none` to skip). */
-    strategy: z.enum(['cli-export', 'none']).default('cli-export').optional(),
+    /**
+     * Credential acquisition strategy.
+     *
+     * - `'cli-export'`: resolve via AWS CLI
+     * - `'none'`: skip credential resolution
+     */
+    strategy: z
+        .union([z.literal('cli-export'), z.literal('none')])
+        .default('cli-export')
+        .optional(),
     /** When true, attempt `aws sso login` on-demand when credential export fails for an SSO profile. */
     loginOnDemand: z.boolean().default(false).optional(),
 });