@karmaniverous/get-dotenv 6.2.3 → 6.3.0

package/dist/plugins-cmd.mjs

@@ -1,3094 +1,20 @@
-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;
-    const preserve = opts && opts.preserveDoubledQuotes === true ? true : false;
-    for (let i = 0; i < command.length; i++) {
-        const c = command.charAt(i);
-        if (quote) {
-            if (c === quote) {
-                // Support doubled quotes inside a quoted segment:
-                // 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) {
-                    if (preserve) {
-                        // Keep "" as-is; append both and continue within the quoted segment.
-                        cur += quote + quote;
-                        i += 1; // skip the second quote char (we already appended both)
-                    }
-                    else {
-                        // Collapse to a single literal quote
-                        cur += quote;
-                        i += 1; // skip the second quote
-                    }
-                }
-                else {
-                    // end of quoted segment
-                    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;
-};
-/**
- * Utility to redact three related displayed values (parent/dotenv/final)
- * consistently for trace lines.
- */
-const redactTriple = (key, triple, opts) => {
-    if (!opts?.redact)
-        return triple;
-    const regs = compile(opts.redactPatterns);
-    const maskIf = (v) => (v && shouldRedactKey(key, regs) ? MASK : v);
-    const out = {};
-    const p = maskIf(triple.parent);
-    const d = maskIf(triple.dotenv);
-    const f = maskIf(triple.final);
-    if (p !== undefined)
-        out.parent = p;
-    if (d !== undefined)
-        out.dotenv = d;
-    if (f !== undefined)
-        out.final = f;
-    return out;
-};
-
-/**
- * Trace child env composition with redaction and entropy warnings.
- * Presentation-only: does not mutate env; writes lines via the provided sink.
- */
-function traceChildEnv(opts) {
-    const { parentEnv, dotenv, keys, redact, redactPatterns, warnEntropy, entropyThreshold, entropyMinLength, entropyWhitelist, write, } = opts;
-    const parentKeys = Object.keys(parentEnv);
-    const dotenvKeys = Object.keys(dotenv);
-    const allKeys = Array.from(new Set([...parentKeys, ...dotenvKeys])).sort();
-    const effectiveKeys = Array.isArray(keys) && keys.length > 0 ? keys : allKeys;
-    // Redaction options for display
-    const redOpts = {};
-    if (redact) {
-        redOpts.redact = true;
-        if (Array.isArray(redactPatterns))
-            redOpts.redactPatterns = redactPatterns;
-    }
-    // Entropy warning options
-    const entOpts = {};
-    if (typeof warnEntropy === 'boolean')
-        entOpts.warnEntropy = warnEntropy;
-    if (typeof entropyThreshold === 'number')
-        entOpts.entropyThreshold = entropyThreshold;
-    if (typeof entropyMinLength === 'number')
-        entOpts.entropyMinLength = entropyMinLength;
-    if (Array.isArray(entropyWhitelist))
-        entOpts.entropyWhitelist = entropyWhitelist;
-    for (const k of effectiveKeys) {
-        const parentVal = parentEnv[k];
-        const dot = dotenv[k];
-        const final = dot !== undefined ? dot : parentVal;
-        const origin = dot !== undefined
-            ? 'dotenv'
-            : parentVal !== undefined
-                ? 'parent'
-                : 'unset';
-        const tripleIn = {};
-        if (parentVal !== undefined)
-            tripleIn.parent = parentVal;
-        if (dot !== undefined)
-            tripleIn.dotenv = dot;
-        if (final !== undefined)
-            tripleIn.final = final;
-        const triple = redactTriple(k, tripleIn, redOpts);
-        write(`[trace] key=${k} origin=${origin} parent=${triple.parent ?? ''} dotenv=${triple.dotenv ?? ''} final=${triple.final ?? ''}`);
-        maybeWarnEntropy(k, final, origin, entOpts, (line) => {
-            write(line);
-        });
-    }
-}
-
-/**
- * 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 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);
-    }
-}
-
-/**
- * Base CLI options derived from the shared root option defaults.
- * Used for type-safe initialization of CLI options bags.
- */
-const baseGetDotenvCliOptions = baseRootOptionDefaults;
-
-/**
- * Compose a child-process env overlay from dotenv and the merged CLI options bag.
- * Returns a shallow object including getDotenvCliOptions when serializable.
- *
- * @param merged - Resolved CLI options bag (or a JSON-serializable subset).
- * @param dotenv - Composed dotenv variables for the current invocation.
- * @returns A string-only env overlay suitable for child process spawning.
- */
-function composeNestedEnv(merged, dotenv) {
-    const out = {};
-    for (const [k, v] of Object.entries(dotenv)) {
-        if (typeof v === 'string')
-            out[k] = v;
-    }
-    try {
-        const { logger: _omit, ...bag } = merged;
-        const txt = JSON.stringify(bag);
-        if (typeof txt === 'string')
-            out.getDotenvCliOptions = txt;
-    }
-    catch {
-        /* best-effort only */
-    }
-    return out;
-}
-/**
- * Strip one layer of symmetric outer quotes (single or double) from a string.
- *
- * @param s - Input string.
- * @returns `s` without one symmetric outer quote pair (when present).
- */
-const stripOne = (s) => {
-    if (s.length < 2)
-        return s;
-    const a = s.charAt(0);
-    const b = s.charAt(s.length - 1);
-    const symmetric = (a === '"' && b === '"') || (a === "'" && b === "'");
-    return symmetric ? s.slice(1, -1) : s;
-};
-/**
- * Preserve argv array for Node -e/--eval payloads under shell-off and
- * peel one symmetric outer quote layer from the code argument.
- *
- * @param args - Argument vector intended for direct execution (shell-off).
- * @returns Either the original `args` or a modified copy with a normalized eval payload.
- */
-function maybePreserveNodeEvalArgv(args) {
-    if (args.length >= 3) {
-        const first = (args[0] ?? '').toLowerCase();
-        const hasEval = args[1] === '-e' || args[1] === '--eval';
-        if (first === 'node' && hasEval) {
-            const copy = args.slice();
-            copy[2] = stripOne(copy[2] ?? '');
-            return copy;
-        }
-    }
-    return args;
-}
-
-/**
- * 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).
- */
-const resolveCommand = (scripts, command) => scripts && typeof scripts[command] === 'object'
-    ? scripts[command].cmd
-    : (scripts?.[command] ?? command);
-/**
- * Resolve the shell setting for a given command:
- * - If the script entry is an object, prefer its `shell` override.
- * - Otherwise use the provided `shell` (string | boolean).
- *
- * @param scripts - Optional scripts table.
- * @param command - User-provided command name or string.
- * @param shell - Global shell preference (string | boolean).
- */
-const resolveShell = (scripts, command, shell) => scripts && typeof scripts[command] === 'object'
-    ? (scripts[command].shell ?? false)
-    : (shell ?? false);
-
-/**
- * Resolve a tri-state optional boolean flag under exactOptionalPropertyTypes.
- * - If the user explicitly enabled the flag, return true.
- * - If the user explicitly disabled (the "...-off" variant), return undefined (unset).
- * - Otherwise, adopt the default (true → set; false/undefined → unset).
- *
- * @param exclude - The "on" flag value as parsed by Commander.
- * @param excludeOff - The "off" toggle (present when specified) as parsed by Commander.
- * @param defaultValue - The generator default to adopt when no explicit toggle is present.
- * @returns boolean | undefined — use `undefined` to indicate "unset" (do not emit).
- *
- * @example
- * ```ts
- * resolveExclusion(undefined, undefined, true); // => true
- * ```
- */
-const resolveExclusion = (exclude, excludeOff, defaultValue) => exclude ? true : excludeOff ? undefined : defaultValue ? true : undefined;
-/**
- * Resolve an optional flag with "--exclude-all" overrides.
- * If excludeAll is set and the individual "...-off" is not, force true.
- * If excludeAllOff is set and the individual flag is not explicitly set, unset.
- * Otherwise, adopt the default (true → set; false/undefined → unset).
- *
- * @param exclude - Individual include/exclude flag.
- * @param excludeOff - Individual "...-off" flag.
- * @param defaultValue - Default for the individual flag.
- * @param excludeAll - Global "exclude-all" flag.
- * @param excludeAllOff - Global "exclude-all-off" flag.
- *
- * @example
- * resolveExclusionAll(undefined, undefined, false, true, undefined) =\> true
- */
-const resolveExclusionAll = (exclude, excludeOff, defaultValue, excludeAll, excludeAllOff) => 
-// Order of precedence:
-// 1) Individual explicit "on" wins outright.
-// 2) Individual explicit "off" wins over any global.
-// 3) Global exclude-all forces true when not explicitly turned off.
-// 4) Global exclude-all-off unsets when the individual wasn't explicitly enabled.
-// 5) Fall back to the default (true => set; false/undefined => unset).
-(() => {
-    // Individual "on"
-    if (exclude === true)
-        return true;
-    // Individual "off"
-    if (excludeOff === true)
-        return undefined;
-    // Global "exclude-all" ON (unless explicitly turned off)
-    if (excludeAll === true)
-        return true;
-    // Global "exclude-all-off" (unless explicitly enabled)
-    if (excludeAllOff === true)
-        return undefined;
-    // Default
-    return defaultValue ? true : undefined;
-})();
-/**
- * exactOptionalPropertyTypes-safe setter for optional boolean flags:
- * delete when undefined; assign when defined — without requiring an index signature on T.
- *
- * @typeParam T - Target object type.
- * @param obj - The object to write to.
- * @param key - The optional boolean property key of {@link T}.
- * @param value - The value to set or `undefined` to unset.
- *
- * @remarks
- * Writes through a local `Record<string, unknown>` view to avoid requiring an index signature on {@link T}.
- */
-const setOptionalFlag = (obj, key, value) => {
-    const target = obj;
-    const k = key;
-    // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
-    if (value === undefined)
-        delete target[k];
-    else
-        target[k] = value;
-};
-
-/**
- * Merge and normalize raw Commander options (current + parent + defaults)
- * into a GetDotenvCliOptions-like object. Types are intentionally wide to
- * avoid cross-layer coupling; callers may cast as needed.
- */
-const resolveCliOptions = (rawCliOptions, defaults, parentJson) => {
-    const parent = typeof parentJson === 'string' && parentJson.length > 0
-        ? JSON.parse(parentJson)
-        : undefined;
-    const { command, debugOff, excludeAll, excludeAllOff, excludeDynamicOff, excludeEnvOff, excludeGlobalOff, excludePrivateOff, excludePublicOff, loadProcessOff, logOff, entropyWarn, entropyWarnOff, scripts, shellOff, ...rest } = rawCliOptions;
-    const current = { ...rest };
-    if (typeof scripts === 'string') {
-        try {
-            current.scripts = JSON.parse(scripts);
-        }
-        catch {
-            // ignore parse errors; leave scripts undefined
-        }
-    }
-    const merged = defaultsDeep({}, defaults, parent ?? {}, current);
-    const d = defaults;
-    setOptionalFlag(merged, 'debug', resolveExclusion(merged.debug, debugOff, d.debug));
-    setOptionalFlag(merged, 'excludeDynamic', resolveExclusionAll(merged.excludeDynamic, excludeDynamicOff, d.excludeDynamic, excludeAll, excludeAllOff));
-    setOptionalFlag(merged, 'excludeEnv', resolveExclusionAll(merged.excludeEnv, excludeEnvOff, d.excludeEnv, excludeAll, excludeAllOff));
-    setOptionalFlag(merged, 'excludeGlobal', resolveExclusionAll(merged.excludeGlobal, excludeGlobalOff, d.excludeGlobal, excludeAll, excludeAllOff));
-    setOptionalFlag(merged, 'excludePrivate', resolveExclusionAll(merged.excludePrivate, excludePrivateOff, d.excludePrivate, excludeAll, excludeAllOff));
-    setOptionalFlag(merged, 'excludePublic', resolveExclusionAll(merged.excludePublic, excludePublicOff, d.excludePublic, excludeAll, excludeAllOff));
-    setOptionalFlag(merged, 'log', resolveExclusion(merged.log, logOff, d.log));
-    setOptionalFlag(merged, 'loadProcess', resolveExclusion(merged.loadProcess, loadProcessOff, d.loadProcess));
-    // warnEntropy (tri-state)
-    setOptionalFlag(merged, 'warnEntropy', resolveExclusion(merged.warnEntropy, entropyWarnOff, d.warnEntropy));
-    // Normalize shell for predictability: explicit default shell per OS.
-    const defaultShell = process.platform === 'win32' ? 'powershell.exe' : '/bin/bash';
-    let resolvedShell = merged.shell;
-    if (shellOff)
-        resolvedShell = false;
-    else if (resolvedShell === true || resolvedShell === undefined) {
-        resolvedShell = defaultShell;
-    }
-    else if (typeof resolvedShell !== 'string' &&
-        typeof defaults.shell === 'string') {
-        resolvedShell = defaults.shell;
-    }
-    merged.shell = resolvedShell;
-    const cmd = typeof command === 'string' ? command : undefined;
-    return cmd !== undefined ? { merged, command: cmd } : { merged };
-};
-
-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;
-};
-
-/** src/plugins/cmd/actions/runner.ts
- * Unified runner for cmd subcommand and parent alias.
- * - Resolves command via scripts
- * - Emits --trace diagnostics (centralized helper with redaction/entropy)
- * - Preserves Node -e argv under shell-off
- * - Normalizes child env and honors capture
- */
-/**
- * Execute a command using the current CLI context.
- * Resolves command/shell via scripts, emits traces, and handles execution.
- *
- * @param cli - The CLI instance.
- * @param merged - Merged CLI options.
- * @param command - Command string or array of args.
- * @param _opts - Execution options (e.g. origin label).
- */
-async function runCmdWithContext(cli, merged, command, _opts) {
-    const { logger, debug, capture, scripts: scriptsCfg, shell: shellPref, trace, redact, redactPatterns, warnEntropy, entropyThreshold, entropyMinLength, entropyWhitelist, } = merged;
-    const dotenv = cli.getCtx().dotenv;
-    // Build input string and note original argv (when available).
-    const parts = Array.isArray(command) ? command.map(String) : [];
-    const inputStr = Array.isArray(command) ? parts.join(' ') : command;
-    // Resolve command and shell from scripts/global.
-    const resolved = resolveCommand(scriptsCfg, inputStr);
-    if (debug)
-        logger.debug('\n*** command ***\n', `'${resolved}'`);
-    const shellSetting = resolveShell(scriptsCfg, inputStr, shellPref);
-    // Diagnostics: --trace [keys...]
-    const traceOpt = trace;
-    if (traceOpt) {
-        traceChildEnv({
-            parentEnv: process.env,
-            dotenv,
-            ...(Array.isArray(traceOpt) ? { keys: traceOpt } : {}),
-            ...(redact ? { redact: true } : {}),
-            ...(redact && Array.isArray(redactPatterns) ? { redactPatterns } : {}),
-            ...(typeof warnEntropy === 'boolean' ? { warnEntropy } : {}),
-            ...(typeof entropyThreshold === 'number' ? { entropyThreshold } : {}),
-            ...(typeof entropyMinLength === 'number' ? { entropyMinLength } : {}),
-            ...(Array.isArray(entropyWhitelist) ? { entropyWhitelist } : {}),
-            write: (line) => {
-                try {
-                    process.stderr.write(line + '\n');
-                }
-                catch {
-                    /* ignore */
-                }
-            },
-        });
-    }
-    // Preserve Node -e argv under shell-off when the script did not remap input.
-    let commandArg = resolved;
-    if (shellSetting === false && resolved === inputStr) {
-        if (Array.isArray(command)) {
-            commandArg = maybePreserveNodeEvalArgv(parts);
-        }
-        else {
-            const toks = tokenize(inputStr, { preserveDoubledQuotes: true });
-            if (toks.length >= 3 &&
-                (toks[0] ?? '').toLowerCase() === 'node' &&
-                (toks[1] === '-e' || toks[1] === '--eval')) {
-                toks[2] = stripOne(toks[2] ?? '');
-                commandArg = toks;
-            }
-        }
-    }
-    // Child env: compose nested bag and sanitize.
-    const childOverlay = composeNestedEnv(merged, dotenv);
-    const captureFlag = shouldCapture(capture);
-    let exit;
-    try {
-        exit = await runCommand(commandArg, shellSetting, {
-            env: buildSpawnEnv(process.env, childOverlay),
-            stdio: captureFlag ? 'pipe' : 'inherit',
-        });
-    }
-    catch (e) {
-        // Under unit tests, execa may be mocked to return undefined which causes
-        // pickResult access to throw. Treat as success to allow call-count assertions.
-        if (process.env.VITEST_WORKER_ID)
-            return 0;
-        throw e;
-    }
-    return typeof exit === 'number' ? exit : 0;
-}
-
-/**
- * Attach the default "cmd" subcommand action.
- * Mirrors the prior inline implementation in cmd/index.ts.
- */
-const attachCmdDefaultAction = (cli, cmd, aliasKey) => {
-    cmd.action(async function (...allArgs) {
-        // Commander passes: [...positionals, options, thisCommand]
-        const thisCommand = allArgs[allArgs.length - 1];
-        const commandParts = allArgs[0];
-        const args = Array.isArray(commandParts)
-            ? commandParts.map(String)
-            : [];
-        // No-op when invoked as the default command with no args.
-        if (args.length === 0)
-            return;
-        const merged = readMergedOptions(thisCommand);
-        const parent = thisCommand.parent;
-        if (!parent)
-            throw new Error('parent command not found');
-        // Conflict detection: if an alias option is present on parent, do not
-        // also accept positional cmd args.
-        if (aliasKey) {
-            const p = parent;
-            const pv = typeof p.optsWithGlobals === 'function'
-                ? p.optsWithGlobals()
-                : typeof p.opts === 'function'
-                    ? p.opts()
-                    : {};
-            const ov = pv[aliasKey];
-            if (ov !== undefined) {
-                merged.logger.error(`--${aliasKey} option conflicts with cmd subcommand.`);
-                process.exit(0);
-            }
-        }
-        await runCmdWithContext(cli, merged, args);
-    });
-};
-
-/**
- * Attach options/arguments for the cmd plugin mount.
- *
- * Note: the plugin description is owned by `src/plugins/cmd/index.ts` and must
- * not be set here.
- *
- * @param cli - The `cmd` command mount.
- * @returns The same `cli` instance for chaining.
- *
- * @internal
- */
-function attachCmdOptions(cli) {
-    return cli
-        .enablePositionalOptions()
-        .passThroughOptions()
-        .argument('[command...]');
-}
-
-/**
- * Install the parent-level invoker (alias) for the cmd plugin.
- * Unifies naming with batch attachParentInvoker; behavior unchanged.
- */
-const attachCmdParentInvoker = (cli, options, plugin) => {
-    const dbg = (...args) => {
-        if (process.env.GETDOTENV_DEBUG) {
-            try {
-                const line = args
-                    .map((a) => (typeof a === 'string' ? a : JSON.stringify(a)))
-                    .join(' ');
-                process.stderr.write(`[getdotenv:alias] ${line}\n`);
-            }
-            catch {
-                /* ignore */
-            }
-        }
-    };
-    const aliasSpec = typeof options.optionAlias === 'string'
-        ? { flags: options.optionAlias, description: undefined}
-        : options.optionAlias;
-    if (!aliasSpec)
-        return;
-    const deriveKey = (flags) => {
-        // install alias option
-        if (process.env.GETDOTENV_DEBUG) {
-            console.error('[getdotenv:alias] install alias option', flags);
-        }
-        const long = flags.split(/[ ,|]+/).find((f) => f.startsWith('--')) ?? '--cmd';
-        const name = long.replace(/^--/, '');
-        return name.replace(/-([a-z])/g, (_m, c) => c.toUpperCase());
-    };
-    const aliasKey = deriveKey(aliasSpec.flags);
-    // Expose the option on the parent (root) command.
-    const parentCmd = cli.parent ??
-        cli;
-    const desc = aliasSpec.description ??
-        'alias of cmd subcommand; provide command tokens (variadic)';
-    parentCmd.option(aliasSpec.flags, desc);
-    // Tag the just-added parent option for grouped help rendering at the root.
-    const optsArr = parentCmd.options;
-    if (optsArr.length > 0) {
-        const last = optsArr[optsArr.length - 1];
-        if (last)
-            parentCmd.setOptionGroup(last, 'plugin:cmd');
-    }
-    // Shared alias executor for either preAction or preSubcommand hooks.
-    // Ensure we only execute once even if both hooks fire in a single parse.
-    const aliasState = { handled: false };
-    const maybeRun = async (thisCommand) => {
-        dbg('maybeRun:start');
-        // Read plugin config expand default; fall back to undefined (handled in maybeRunAlias)
-        let expandDefault = undefined;
-        try {
-            const cfg = plugin.readConfig(cli);
-            if (typeof cfg.expand === 'boolean')
-                expandDefault = cfg.expand;
-        }
-        catch {
-            /* config may be unavailable before resolve; default handled downstream */
-        }
-        // Inspect parent options and rawArgs to detect alias-only invocation.
-        if (aliasState.handled)
-            return;
-        const cmd = thisCommand;
-        dbg('maybeRun:rawArgs', cmd.rawArgs ?? []);
-        const raw = typeof cmd.opts === 'function' ? cmd.opts() : {};
-        const val = raw[aliasKey];
-        const provided = typeof val === 'string'
-            ? val.length > 0
-            : Array.isArray(val)
-                ? val.length > 0
-                : false;
-        dbg('maybeRun:aliasKey', aliasKey, 'provided', provided, 'value', val);
-        if (!provided)
-            return;
-        const childNames = cmd.commands.flatMap((c) => [c.name(), ...c.aliases()]);
-        dbg('maybeRun:childNames', childNames);
-        const hasSub = (cmd.rawArgs ?? []).some((t) => childNames.includes(t));
-        dbg('maybeRun:hasSub', hasSub);
-        if (hasSub)
-            return; // do not run alias when an explicit subcommand is present
-        aliasState.handled = true;
-        // Merge CLI options and resolve dotenv context for this invocation.
-        const { merged } = resolveCliOptions(raw, baseGetDotenvCliOptions, process.env.getDotenvCliOptions);
-        const serviceOptions = getDotenvCliOptions2Options(merged);
-        await cli.resolveAndLoad(serviceOptions);
-        // Build input string and apply optional expansion (by config default).
-        const joined = typeof val === 'string'
-            ? val
-            : Array.isArray(val)
-                ? val.map(String).join(' ')
-                : '';
-        const effectiveExpand = expandDefault !== false;
-        const expanded = dotenvExpandFromProcessEnv(joined);
-        const input = effectiveExpand && expanded !== undefined ? expanded : joined;
-        // Hand off to shared runner and terminate (except under tests).
-        const exitCode = await runCmdWithContext(cli, merged, input);
-        const underTests = process.env.GETDOTENV_TEST === '1' ||
-            typeof process.env.VITEST_WORKER_ID === 'string';
-        if (!underTests) {
-            process.exit(typeof exitCode === 'number' ? exitCode : 0);
-        }
-    };
-    parentCmd.hook('preAction', async (thisCommand) => {
-        await maybeRun(thisCommand);
-    });
-    parentCmd.hook('preSubcommand', async (thisCommand) => {
-        await maybeRun(thisCommand);
-    });
-};
-
-/**
- * Zod schema for cmd plugin configuration.
- */
-const cmdPluginConfigSchema = z
-    .object({
-    /** When true, expand the alias value before execution (default behavior when omitted). */
-    expand: z.boolean().optional(),
-})
-    .strict();
-
-/**
- * @packageDocumentation
- * Cmd plugin subpath. Provides the `cmd` subcommand and an optional parent‑level
- * alias to execute a command within the resolved dotenv context.
- */
-/**
- * Cmd plugin: executes a command using the current getdotenv CLI context.
- * Registers the `cmd` subcommand and optionally attaches a parent-level alias (e.g. `-c`).
- *
- * @param options - Plugin configuration options.
- */
-const cmdPlugin = (options = {}) => {
-    const plugin = definePlugin({
-        ns: 'cmd',
-        configSchema: cmdPluginConfigSchema,
-        setup(cli) {
-            const aliasSpec = typeof options.optionAlias === 'string'
-                ? { flags: options.optionAlias}
-                : options.optionAlias;
-            const deriveKey = (flags) => {
-                const long = flags.split(/[ ,|]+/).find((f) => f.startsWith('--')) ?? '--cmd';
-                const name = long.replace(/^--/, '');
-                return name.replace(/-([a-z])/g, (_m, c) => c.toUpperCase());
-            };
-            const aliasKey = aliasSpec ? deriveKey(aliasSpec.flags) : undefined;
-            // Mount is the command ('cmd'); attach default action.
-            cli.description('Execute command according to the --shell option, conflicts with --command option (default subcommand)');
-            // Options/arguments (positional payload, argv routing) are attached separately.
-            attachCmdOptions(cli);
-            attachCmdDefaultAction(cli, cli, aliasKey);
-            // Parent-attached option alias (optional, unified naming).
-            if (aliasSpec !== undefined) {
-                attachCmdParentInvoker(cli, options, plugin);
-            }
-            return undefined;
-        },
-    });
-    return plugin;
-};
-
-export { cmdPlugin };
+import './chunks/readMergedOptions-DLBDzpXX.mjs';
+import 'execa';
+import 'fs-extra';
+import 'node:path';
+import 'crypto';
+import 'path';
+import 'url';
+import '@commander-js/extra-typings';
+import 'nanoid';
+import 'dotenv';
+import './chunks/loader-CePOf74i.mjs';
+import 'package-directory';
+import 'yaml';
+import 'zod';
+export { c as cmdPlugin } from './chunks/index-BqZ3PB6c.mjs';
+import './chunks/overlayEnv-Bqh_kPGA.mjs';
+import './chunks/loadModuleDefault-Dj8B3Stt.mjs';
+import './chunks/spawnEnv-CQwFu7ZJ.mjs';
+import './chunks/invoke-DuRPU1oC.mjs';
+import './chunks/resolveCliOptions-_qtsVxda.mjs';