@karmaniverous/get-dotenv 5.2.1 → 5.2.3

package/dist/plugins-cmd.mjs

@@ -0,0 +1,2498 @@
+import { Command, Option } from 'commander';
+import { execa, execaCommand } from 'execa';
+import fs from 'fs-extra';
+import { packageDirectory } from 'package-directory';
+import url, { fileURLToPath, pathToFileURL } from 'url';
+import path, { join, extname } from 'path';
+import { z } from 'zod';
+import YAML from 'yaml';
+import { nanoid } from 'nanoid';
+import { parse } from 'dotenv';
+import { createHash } from 'crypto';
+
+// Minimal tokenizer for shell-off execution:
+// Splits by whitespace while preserving quoted segments (single or double quotes).
+const tokenize = (command) => {
+    const out = [];
+    let cur = '';
+    let quote = null;
+    for (let i = 0; i < command.length; i++) {
+        const c = command.charAt(i);
+        if (quote) {
+            if (c === quote) {
+                // Support doubled quotes inside a quoted segment (Windows/PowerShell style):
+                // "" -> " and '' -> '
+                const next = command.charAt(i + 1);
+                if (next === quote) {
+                    cur += quote;
+                    i += 1; // skip the second quote
+                }
+                else {
+                    // end of quoted segment
+                    quote = null;
+                }
+            }
+            else {
+                cur += c;
+            }
+        }
+        else {
+            if (c === '"' || c === "'") {
+                quote = c;
+            }
+            else if (/\s/.test(c)) {
+                if (cur) {
+                    out.push(cur);
+                    cur = '';
+                }
+            }
+            else {
+                cur += c;
+            }
+        }
+    }
+    if (cur)
+        out.push(cur);
+    return out;
+};
+
+const dbg$1 = (...args) => {
+    if (process.env.GETDOTENV_DEBUG) {
+        // Use stderr to avoid interfering with stdout assertions
+        console.error('[getdotenv:run]', ...args);
+    }
+};
+// Strip repeated symmetric outer quotes (single or double) until stable.
+// This is safe for argv arrays passed to execa (no quoting needed) and avoids
+// passing quote characters through to Node (e.g., for `node -e "<code>"`).
+// Handles stacked quotes from shells like PowerShell: """code""" -> code.
+const stripOuterQuotes = (s) => {
+    let out = s;
+    // Repeatedly trim only when the entire string is wrapped in matching quotes.
+    // Stop as soon as the ends are asymmetric or no quotes remain.
+    while (out.length >= 2) {
+        const a = out.charAt(0);
+        const b = out.charAt(out.length - 1);
+        const symmetric = (a === '"' && b === '"') || (a === "'" && b === "'");
+        if (!symmetric)
+            break;
+        out = out.slice(1, -1);
+    }
+    return out;
+};
+// Convert NodeJS.ProcessEnv (string | undefined values) to the shape execa
+// expects (Readonly<Partial<Record<string, string>>>), dropping undefineds.
+const sanitizeEnv = (env) => {
+    if (!env)
+        return undefined;
+    const entries = Object.entries(env).filter((e) => typeof e[1] === 'string');
+    return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+};
+const runCommand = async (command, shell, opts) => {
+    if (shell === false) {
+        let file;
+        let args = [];
+        if (Array.isArray(command)) {
+            file = command[0];
+            args = command.slice(1).map(stripOuterQuotes);
+        }
+        else {
+            const tokens = tokenize(command);
+            file = tokens[0];
+            args = tokens.slice(1);
+        }
+        if (!file)
+            return 0;
+        dbg$1('exec (plain)', { file, args, stdio: opts.stdio });
+        // Build options without injecting undefined properties (exactOptionalPropertyTypes).
+        const envSan = sanitizeEnv(opts.env);
+        const plainOpts = {};
+        if (opts.cwd !== undefined)
+            plainOpts.cwd = opts.cwd;
+        if (envSan !== undefined)
+            plainOpts.env = envSan;
+        if (opts.stdio !== undefined)
+            plainOpts.stdio = opts.stdio;
+        const result = await execa(file, args, plainOpts);
+        if (opts.stdio === 'pipe' && result.stdout) {
+            process.stdout.write(result.stdout + (result.stdout.endsWith('\n') ? '' : '\n'));
+        }
+        const exit = result?.exitCode;
+        dbg$1('exit (plain)', { exitCode: exit });
+        return typeof exit === 'number' ? exit : Number.NaN;
+    }
+    else {
+        const commandStr = Array.isArray(command) ? command.join(' ') : command;
+        dbg$1('exec (shell)', {
+            shell: typeof shell === 'string' ? shell : 'custom',
+            stdio: opts.stdio,
+            command: commandStr,
+        });
+        const envSan = sanitizeEnv(opts.env);
+        const shellOpts = { shell };
+        if (opts.cwd !== undefined)
+            shellOpts.cwd = opts.cwd;
+        if (envSan !== undefined)
+            shellOpts.env = envSan;
+        if (opts.stdio !== undefined)
+            shellOpts.stdio = opts.stdio;
+        const result = await execaCommand(commandStr, shellOpts);
+        const out = result?.stdout;
+        if (opts.stdio === 'pipe' && out) {
+            process.stdout.write(out + (out.endsWith('\n') ? '' : '\n'));
+        }
+        const exit = result?.exitCode;
+        dbg$1('exit (shell)', { exitCode: exit });
+        return typeof exit === 'number' ? exit : Number.NaN;
+    }
+};
+
+const dropUndefined = (bag) => Object.fromEntries(Object.entries(bag).filter((e) => typeof e[1] === 'string'));
+/** Build a sanitized env for child processes from base + overlay. */
+const buildSpawnEnv = (base, overlay) => {
+    const raw = {
+        ...(base ?? {}),
+        ...(overlay ?? {}),
+    };
+    // Drop undefined first
+    const entries = Object.entries(dropUndefined(raw));
+    if (process.platform === 'win32') {
+        // Windows: keys are case-insensitive; collapse duplicates
+        const byLower = new Map();
+        for (const [k, v] of entries) {
+            byLower.set(k.toLowerCase(), [k, v]); // last wins; preserve latest casing
+        }
+        const out = {};
+        for (const [, [k, v]] of byLower)
+            out[k] = v;
+        // HOME fallback from USERPROFILE (common expectation)
+        if (!Object.prototype.hasOwnProperty.call(out, 'HOME')) {
+            const up = out['USERPROFILE'];
+            if (typeof up === 'string' && up.length > 0)
+                out['HOME'] = up;
+        }
+        // Normalize TMP/TEMP coherence (pick any present; reflect to both)
+        const tmp = out['TMP'] ?? out['TEMP'];
+        if (typeof tmp === 'string' && tmp.length > 0) {
+            out['TMP'] = tmp;
+            out['TEMP'] = tmp;
+        }
+        return out;
+    }
+    // POSIX: keep keys as-is
+    const out = Object.fromEntries(entries);
+    // Ensure TMPDIR exists when any temp key is present (best-effort)
+    const tmpdir = out['TMPDIR'] ?? out['TMP'] ?? out['TEMP'];
+    if (typeof tmpdir === 'string' && tmpdir.length > 0) {
+        out['TMPDIR'] = tmpdir;
+    }
+    return out;
+};
+
+/**
+ * Define a GetDotenv CLI plugin with compositional helpers.
+ *
+ * @example
+ * const parent = definePlugin(\{ id: 'p', setup(cli) \{ /* ... *\/ \} \})
+ *   .use(childA)
+ *   .use(childB);
+ */
+const definePlugin = (spec) => {
+    const { children = [], ...rest } = spec;
+    const plugin = {
+        ...rest,
+        children: [...children],
+        use(child) {
+            this.children.push(child);
+            return this;
+        },
+    };
+    return plugin;
+};
+
+/** src/diagnostics/entropy.ts
+ * Entropy diagnostics (presentation-only).
+ * - Gated by min length and printable ASCII.
+ * - Warn once per key per run when bits/char \>= threshold.
+ * - Supports whitelist patterns to suppress known-noise keys.
+ */
+const warned = new Set();
+const isPrintableAscii = (s) => /^[\x20-\x7E]+$/.test(s);
+const compile$1 = (patterns) => (patterns ?? []).map((p) => new RegExp(p, 'i'));
+const whitelisted = (key, regs) => regs.some((re) => re.test(key));
+const shannonBitsPerChar = (s) => {
+    const freq = new Map();
+    for (const ch of s)
+        freq.set(ch, (freq.get(ch) ?? 0) + 1);
+    const n = s.length;
+    let h = 0;
+    for (const c of freq.values()) {
+        const p = c / n;
+        h -= p * Math.log2(p);
+    }
+    return h;
+};
+/**
+ * Maybe emit a one-line entropy warning for a key.
+ * Caller supplies an `emit(line)` function; the helper ensures once-per-key.
+ */
+const maybeWarnEntropy = (key, value, origin, opts, emit) => {
+    if (!opts || opts.warnEntropy === false)
+        return;
+    if (warned.has(key))
+        return;
+    const v = value ?? '';
+    const minLen = Math.max(0, opts.entropyMinLength ?? 16);
+    const threshold = opts.entropyThreshold ?? 3.8;
+    if (v.length < minLen)
+        return;
+    if (!isPrintableAscii(v))
+        return;
+    const wl = compile$1(opts.entropyWhitelist);
+    if (whitelisted(key, wl))
+        return;
+    const bpc = shannonBitsPerChar(v);
+    if (bpc >= threshold) {
+        warned.add(key);
+        emit(`[entropy] key=${key} score=${bpc.toFixed(2)} len=${String(v.length)} origin=${origin}`);
+    }
+};
+
+const DEFAULT_PATTERNS = [
+    '\\bsecret\\b',
+    '\\btoken\\b',
+    '\\bpass(word)?\\b',
+    '\\bapi[_-]?key\\b',
+    '\\bkey\\b',
+];
+const compile = (patterns) => (patterns && patterns.length > 0 ? patterns : DEFAULT_PATTERNS).map((p) => new RegExp(p, 'i'));
+const shouldRedactKey = (key, regs) => regs.some((re) => re.test(key));
+const MASK = '[redacted]';
+/**
+ * Produce a shallow redacted copy of an env-like object for display.
+ */
+const redactObject = (obj, opts) => {
+    if (!opts?.redact)
+        return { ...obj };
+    const regs = compile(opts.redactPatterns);
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+        out[k] = v && shouldRedactKey(k, regs) ? MASK : v;
+    }
+    return out;
+};
+/**
+ * Utility to redact three related displayed values (parent/dotenv/final)
+ * consistently for trace lines.
+ */
+const redactTriple = (key, triple, opts) => {
+    if (!opts?.redact)
+        return triple;
+    const regs = compile(opts.redactPatterns);
+    const maskIf = (v) => (v && shouldRedactKey(key, regs) ? MASK : v);
+    const out = {};
+    const p = maskIf(triple.parent);
+    const d = maskIf(triple.dotenv);
+    const f = maskIf(triple.final);
+    if (p !== undefined)
+        out.parent = p;
+    if (d !== undefined)
+        out.dotenv = d;
+    if (f !== undefined)
+        out.final = f;
+    return out;
+};
+
+/**
+ * Batch services (neutral): resolve command and shell settings.
+ * Shared by the generator path and the batch plugin to avoid circular deps.
+ */
+/**
+ * Resolve a command string from the {@link Scripts} table.
+ * A script may be expressed as a string or an object with a `cmd` property.
+ *
+ * @param scripts - Optional scripts table.
+ * @param command - User-provided command name or string.
+ * @returns Resolved command string (falls back to the provided command).
+ */
+const resolveCommand = (scripts, command) => scripts && typeof scripts[command] === 'object'
+    ? scripts[command].cmd
+    : (scripts?.[command] ?? command);
+/**
+ * Resolve the shell setting for a given command:
+ * - If the script entry is an object, prefer its `shell` override.
+ * - Otherwise use the provided `shell` (string | boolean).
+ *
+ * @param scripts - Optional scripts table.
+ * @param command - User-provided command name or string.
+ * @param shell - Global shell preference (string | boolean).
+ */
+const resolveShell = (scripts, command, shell) => scripts && typeof scripts[command] === 'object'
+    ? (scripts[command].shell ?? false)
+    : (shell ?? false);
+
+// Base root CLI defaults (shared; kept untyped here to avoid cross-layer deps).
+const baseRootOptionDefaults = {
+    dotenvToken: '.env',
+    loadProcess: true,
+    logger: console,
+    // Diagnostics defaults
+    warnEntropy: true,
+    entropyThreshold: 3.8,
+    entropyMinLength: 16,
+    entropyWhitelist: ['^GIT_', '^npm_', '^CI$', 'SHLVL'],
+    paths: './',
+    pathsDelimiter: ' ',
+    privateToken: 'local',
+    scripts: {
+        'git-status': {
+            cmd: 'git branch --show-current && git status -s -u',
+            shell: true,
+        },
+    },
+    shell: true,
+    vars: '',
+    varsAssignor: '=',
+    varsDelimiter: ' ',
+    // tri-state flags default to unset unless explicitly provided
+    // (debug/log/exclude* resolved via flag utils)
+};
+
+const baseGetDotenvCliOptions = baseRootOptionDefaults;
+
+/** @internal */
+const isPlainObject$1 = (value) => value !== null &&
+    typeof value === 'object' &&
+    Object.getPrototypeOf(value) === Object.prototype;
+const mergeInto = (target, source) => {
+    for (const [key, sVal] of Object.entries(source)) {
+        if (sVal === undefined)
+            continue; // do not overwrite with undefined
+        const tVal = target[key];
+        if (isPlainObject$1(tVal) && isPlainObject$1(sVal)) {
+            target[key] = mergeInto({ ...tVal }, sVal);
+        }
+        else if (isPlainObject$1(sVal)) {
+            target[key] = mergeInto({}, sVal);
+        }
+        else {
+            target[key] = sVal;
+        }
+    }
+    return target;
+};
+/**
+ * Perform a deep defaults-style merge across plain objects. *
+ * - Only merges plain objects (prototype === Object.prototype).
+ * - Arrays and non-objects are replaced, not merged.
+ * - `undefined` values are ignored and do not overwrite prior values.
+ *
+ * @typeParam T - The resulting shape after merging all layers.
+ * @param layers - Zero or more partial layers in ascending precedence order.
+ * @returns The merged object typed as {@link T}.
+ *
+ * @example
+ * defaultsDeep(\{ a: 1, nested: \{ b: 2 \} \}, \{ nested: \{ b: 3, c: 4 \} \})
+ * =\> \{ a: 1, nested: \{ b: 3, c: 4 \} \}
+ */
+const defaultsDeep = (...layers) => {
+    const result = layers
+        .filter(Boolean)
+        .reduce((acc, layer) => mergeInto(acc, layer), {});
+    return result;
+};
+
+// src/GetDotenvOptions.ts
+const getDotenvOptionsFilename = 'getdotenv.config.json';
+/**
+ * Converts programmatic CLI options to `getDotenv` options. *
+ * @param cliOptions - CLI options. Defaults to `{}`.
+ *
+ * @returns `getDotenv` options.
+ */
+const getDotenvCliOptions2Options = ({ paths, pathsDelimiter, pathsDelimiterPattern, vars, varsAssignor, varsAssignorPattern, varsDelimiter, varsDelimiterPattern, ...rest }) => {
+    /**
+     * Convert CLI-facing string options into {@link GetDotenvOptions}.
+     *
+     * - Splits {@link GetDotenvCliOptions.paths} using either a delimiter   *   or a regular expression pattern into a string array.   * - Parses {@link GetDotenvCliOptions.vars} as space-separated `KEY=VALUE`
+     *   pairs (configurable delimiters) into a {@link ProcessEnv}.
+     * - Drops CLI-only keys that have no programmatic equivalent.
+     *
+     * @remarks
+     * Follows exact-optional semantics by not emitting undefined-valued entries.
+     */
+    // Drop CLI-only keys (debug/scripts) without relying on Record casts.
+    // Create a shallow copy then delete optional CLI-only keys if present.
+    const restObj = { ...rest };
+    delete restObj.debug;
+    delete restObj.scripts;
+    const splitBy = (value, delim, pattern) => (value ? value.split(pattern ? RegExp(pattern) : (delim ?? ' ')) : []);
+    // Tolerate vars as either a CLI string ("A=1 B=2") or an object map.
+    let parsedVars;
+    if (typeof vars === 'string') {
+        const kvPairs = splitBy(vars, varsDelimiter, varsDelimiterPattern).map((v) => v.split(varsAssignorPattern
+            ? RegExp(varsAssignorPattern)
+            : (varsAssignor ?? '=')));
+        parsedVars = Object.fromEntries(kvPairs);
+    }
+    else if (vars && typeof vars === 'object' && !Array.isArray(vars)) {
+        // Keep only string or undefined values to match ProcessEnv.
+        const entries = Object.entries(vars).filter(([k, v]) => typeof k === 'string' && (typeof v === 'string' || v === undefined));
+        parsedVars = Object.fromEntries(entries);
+    }
+    // Drop undefined-valued entries at the converter stage to match ProcessEnv
+    // expectations and the compat test assertions.
+    if (parsedVars) {
+        parsedVars = Object.fromEntries(Object.entries(parsedVars).filter(([, v]) => v !== undefined));
+    }
+    // Tolerate paths as either a delimited string or string[]
+    // Use a locally cast union type to avoid lint warnings about always-falsy conditions
+    // under the RootOptionsShape (which declares paths as string | undefined).
+    const pathsAny = paths;
+    const pathsOut = Array.isArray(pathsAny)
+        ? pathsAny.filter((p) => typeof p === 'string')
+        : splitBy(pathsAny, pathsDelimiter, pathsDelimiterPattern);
+    // Preserve exactOptionalPropertyTypes: only include keys when defined.
+    return {
+        ...restObj,
+        ...(pathsOut.length > 0 ? { paths: pathsOut } : {}),
+        ...(parsedVars !== undefined ? { vars: parsedVars } : {}),
+    };
+};
+const resolveGetDotenvOptions = async (customOptions) => {
+    /**
+     * Resolve {@link GetDotenvOptions} by layering defaults in ascending precedence:
+     *
+     * 1. Base defaults derived from the CLI generator defaults
+     *    ({@link baseGetDotenvCliOptions}).
+     * 2. Local project overrides from a `getdotenv.config.json` in the nearest
+     *    package root (if present).
+     * 3. The provided {@link customOptions}.
+     *
+     * The result preserves explicit empty values and drops only `undefined`.
+     *
+     * @returns Fully-resolved {@link GetDotenvOptions}.
+     *
+     * @example
+     * ```ts
+     * const options = await resolveGetDotenvOptions({ env: 'dev' });
+     * ```
+     */
+    const localPkgDir = await packageDirectory();
+    const localOptionsPath = localPkgDir
+        ? join(localPkgDir, getDotenvOptionsFilename)
+        : undefined;
+    const localOptions = (localOptionsPath && (await fs.exists(localOptionsPath))
+        ? JSON.parse((await fs.readFile(localOptionsPath)).toString())
+        : {});
+    // Merge order: base < local < custom (custom has highest precedence)
+    const mergedCli = defaultsDeep(baseGetDotenvCliOptions, localOptions);
+    const defaultsFromCli = getDotenvCliOptions2Options(mergedCli);
+    const result = defaultsDeep(defaultsFromCli, customOptions);
+    return {
+        ...result, // Keep explicit empty strings/zeros; drop only undefined
+        vars: Object.fromEntries(Object.entries(result.vars ?? {}).filter(([, v]) => v !== undefined)),
+    };
+};
+
+/**
+ * Zod schemas for programmatic GetDotenv options.
+ *
+ * NOTE: These schemas are introduced without wiring to avoid behavior changes.
+ * Legacy paths continue to use existing types/logic. The new plugin host will
+ * use these schemas in strict mode; legacy paths will adopt them in warn mode
+ * later per the staged plan.
+ */
+// Minimal process env representation: string values or undefined to indicate "unset".
+const processEnvSchema = z.record(z.string(), z.string().optional());
+// RAW: all fields optional — undefined means "inherit" from lower layers.
+const getDotenvOptionsSchemaRaw = z.object({
+    defaultEnv: z.string().optional(),
+    dotenvToken: z.string().optional(),
+    dynamicPath: z.string().optional(),
+    // Dynamic map is intentionally wide for now; refine once sources are normalized.
+    dynamic: z.record(z.string(), z.unknown()).optional(),
+    env: z.string().optional(),
+    excludeDynamic: z.boolean().optional(),
+    excludeEnv: z.boolean().optional(),
+    excludeGlobal: z.boolean().optional(),
+    excludePrivate: z.boolean().optional(),
+    excludePublic: z.boolean().optional(),
+    loadProcess: z.boolean().optional(),
+    log: z.boolean().optional(),
+    outputPath: z.string().optional(),
+    paths: z.array(z.string()).optional(),
+    privateToken: z.string().optional(),
+    vars: processEnvSchema.optional(),
+    // Host-only feature flag: guarded integration of config loader/overlay
+    useConfigLoader: z.boolean().optional(),
+});
+// RESOLVED: service-boundary contract (post-inheritance).
+// For Step A, keep identical to RAW (no behavior change). Later stages will// materialize required defaults and narrow shapes as resolution is wired.
+const getDotenvOptionsSchemaResolved = getDotenvOptionsSchemaRaw;
+
+/**
+ * Zod schemas for configuration files discovered by the new loader.
+ *
+ * Notes:
+ * - RAW: all fields optional; shapes are stringly-friendly (paths may be string[] or string).
+ * - RESOLVED: normalized shapes (paths always string[]).
+ * - For JSON/YAML configs, the loader rejects "dynamic" and "schema" (JS/TS-only).
+ */
+// String-only env value map
+const stringMap = z.record(z.string(), z.string());
+const envStringMap = z.record(z.string(), stringMap);
+// Allow string[] or single string for "paths" in RAW; normalize later.
+const rawPathsSchema = z.union([z.array(z.string()), z.string()]).optional();
+const getDotenvConfigSchemaRaw = z.object({
+    dotenvToken: z.string().optional(),
+    privateToken: z.string().optional(),
+    paths: rawPathsSchema,
+    loadProcess: z.boolean().optional(),
+    log: z.boolean().optional(),
+    shell: z.union([z.string(), z.boolean()]).optional(),
+    scripts: z.record(z.string(), z.unknown()).optional(), // Scripts validation left wide; generator validates elsewhere
+    requiredKeys: z.array(z.string()).optional(),
+    schema: z.unknown().optional(), // JS/TS-only; loader rejects in JSON/YAML
+    vars: stringMap.optional(), // public, global
+    envVars: envStringMap.optional(), // public, per-env
+    // Dynamic in config (JS/TS only). JSON/YAML loader will reject if set.
+    dynamic: z.unknown().optional(),
+    // Per-plugin config bag; validated by plugins/host when used.
+    plugins: z.record(z.string(), z.unknown()).optional(),
+});
+// Normalize paths to string[]
+const normalizePaths = (p) => p === undefined ? undefined : Array.isArray(p) ? p : [p];
+const getDotenvConfigSchemaResolved = getDotenvConfigSchemaRaw.transform((raw) => ({
+    ...raw,
+    paths: normalizePaths(raw.paths),
+}));
+
+// Discovery candidates (first match wins per scope/privacy).
+// Order preserves historical JSON/YAML precedence; JS/TS added afterwards.
+const PUBLIC_FILENAMES = [
+    'getdotenv.config.json',
+    'getdotenv.config.yaml',
+    'getdotenv.config.yml',
+    'getdotenv.config.js',
+    'getdotenv.config.mjs',
+    'getdotenv.config.cjs',
+    'getdotenv.config.ts',
+    'getdotenv.config.mts',
+    'getdotenv.config.cts',
+];
+const LOCAL_FILENAMES = [
+    'getdotenv.config.local.json',
+    'getdotenv.config.local.yaml',
+    'getdotenv.config.local.yml',
+    'getdotenv.config.local.js',
+    'getdotenv.config.local.mjs',
+    'getdotenv.config.local.cjs',
+    'getdotenv.config.local.ts',
+    'getdotenv.config.local.mts',
+    'getdotenv.config.local.cts',
+];
+const isYaml = (p) => ['.yaml', '.yml'].includes(extname(p).toLowerCase());
+const isJson = (p) => extname(p).toLowerCase() === '.json';
+const isJsOrTs = (p) => ['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts'].includes(extname(p).toLowerCase());
+// --- Internal JS/TS module loader helpers (default export) ---
+const importDefault$1 = async (fileUrl) => {
+    const mod = (await import(fileUrl));
+    return mod.default;
+};
+const cacheName = (absPath, suffix) => {
+    // sanitized filename with suffix; recompile on mtime changes not tracked here (simplified)
+    const base = path.basename(absPath).replace(/[^a-zA-Z0-9._-]/g, '_');
+    return `${base}.${suffix}.mjs`;
+};
+const ensureDir = async (dir) => {
+    await fs.ensureDir(dir);
+    return dir;
+};
+const loadJsTsDefault = async (absPath) => {
+    const fileUrl = pathToFileURL(absPath).toString();
+    const ext = extname(absPath).toLowerCase();
+    if (ext === '.js' || ext === '.mjs' || ext === '.cjs') {
+        return importDefault$1(fileUrl);
+    }
+    // Try direct import first in case a TS loader is active.
+    try {
+        const val = await importDefault$1(fileUrl);
+        if (val)
+            return val;
+    }
+    catch {
+        /* fallthrough */
+    }
+    // esbuild bundle to a temp ESM file
+    try {
+        const esbuild = (await import('esbuild'));
+        const outDir = await ensureDir(path.resolve('.tsbuild', 'getdotenv-config'));
+        const outfile = path.join(outDir, cacheName(absPath, 'bundle'));
+        await esbuild.build({
+            entryPoints: [absPath],
+            bundle: true,
+            platform: 'node',
+            format: 'esm',
+            target: 'node20',
+            outfile,
+            sourcemap: false,
+            logLevel: 'silent',
+        });
+        return await importDefault$1(pathToFileURL(outfile).toString());
+    }
+    catch {
+        /* fallthrough to TS transpile */
+    }
+    // typescript.transpileModule simple transpile (single-file)
+    try {
+        const ts = (await import('typescript'));
+        const src = await fs.readFile(absPath, 'utf-8');
+        const out = ts.transpileModule(src, {
+            compilerOptions: {
+                module: 'ESNext',
+                target: 'ES2022',
+                moduleResolution: 'NodeNext',
+            },
+        }).outputText;
+        const outDir = await ensureDir(path.resolve('.tsbuild', 'getdotenv-config'));
+        const outfile = path.join(outDir, cacheName(absPath, 'ts'));
+        await fs.writeFile(outfile, out, 'utf-8');
+        return await importDefault$1(pathToFileURL(outfile).toString());
+    }
+    catch {
+        throw new Error(`Unable to load JS/TS config: ${absPath}. Install 'esbuild' for robust bundling or ensure a TS loader.`);
+    }
+};
+/**
+ * Discover JSON/YAML config files in the packaged root and project root.
+ * Order: packaged public → project public → project local. */
+const discoverConfigFiles = async (importMetaUrl) => {
+    const files = [];
+    // Packaged root via importMetaUrl (optional)
+    if (importMetaUrl) {
+        const fromUrl = 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 robust pipeline.
+            const mod = await loadJsTsDefault(abs);
+            raw = mod ?? {};
+        }
+        else {
+            const txt = await fs.readFile(abs, 'utf-8');
+            raw = isJson(abs) ? JSON.parse(txt) : isYaml(abs) ? YAML.parse(txt) : {};
+        }
+    }
+    catch (err) {
+        throw new Error(`Failed to read/parse config: ${filePath}. ${String(err)}`);
+    }
+    // Validate RAW
+    const parsed = getDotenvConfigSchemaRaw.safeParse(raw);
+    if (!parsed.success) {
+        const msgs = parsed.error.issues
+            .map((i) => `${i.path.join('.')}: ${i.message}`)
+            .join('\n');
+        throw new Error(`Invalid config ${filePath}:\n${msgs}`);
+    }
+    // Disallow dynamic and schema in JSON/YAML; allow both in JS/TS.
+    if (!isJsOrTs(filePath) &&
+        (parsed.data.dynamic !== undefined || parsed.data.schema !== undefined)) {
+        throw new Error(`Config ${filePath} specifies unsupported keys for JSON/YAML. ` +
+            `Use JS/TS config for "dynamic" or "schema".`);
+    }
+    return getDotenvConfigSchemaResolved.parse(parsed.data);
+};
+/**
+ * Discover and load configs into resolved shapes, ordered by scope/privacy.
+ * JSON/YAML/JS/TS supported; first match per scope/privacy applies.
+ */
+const resolveGetDotenvConfigSources = async (importMetaUrl) => {
+    const discovered = await discoverConfigFiles(importMetaUrl);
+    const result = {};
+    for (const f of discovered) {
+        const cfg = await loadConfigFile(f.path);
+        if (f.scope === 'packaged') {
+            // packaged public only
+            result.packaged = cfg;
+        }
+        else {
+            result.project ??= {};
+            if (f.privacy === 'public')
+                result.project.public = cfg;
+            else
+                result.project.local = cfg;
+        }
+    }
+    return result;
+};
+
+/**
+ * Dotenv expansion utilities.
+ *
+ * This module implements recursive expansion of environment-variable
+ * references in strings and records. It supports both whitespace and
+ * bracket syntaxes with optional defaults:
+ *
+ * - Whitespace: `$VAR[:default]`
+ * - Bracketed: `${VAR[:default]}`
+ *
+ * Escaped dollar signs (`\$`) are preserved.
+ * Unknown variables resolve to empty string unless a default is provided.
+ */
+/**
+ * Like String.prototype.search but returns the last index.
+ * @internal
+ */
+const searchLast = (str, rgx) => {
+    const matches = Array.from(str.matchAll(rgx));
+    return matches.length > 0 ? (matches.slice(-1)[0]?.index ?? -1) : -1;
+};
+const replaceMatch = (value, match, ref) => {
+    /**
+     * @internal
+     */
+    const group = match[0];
+    const key = match[1];
+    const defaultValue = match[2];
+    if (!key)
+        return value;
+    const replacement = value.replace(group, ref[key] ?? defaultValue ?? '');
+    return interpolate(replacement, ref);
+};
+const interpolate = (value = '', ref = {}) => {
+    /**
+     * @internal
+     */
+    // if value is falsy, return it as is
+    if (!value)
+        return value;
+    // get position of last unescaped dollar sign
+    const lastUnescapedDollarSignIndex = searchLast(value, /(?!(?<=\\))\$/g);
+    // return value if none found
+    if (lastUnescapedDollarSignIndex === -1)
+        return value;
+    // evaluate the value tail
+    const tail = value.slice(lastUnescapedDollarSignIndex);
+    // find whitespace pattern: $KEY:DEFAULT
+    const whitespacePattern = /^\$([\w]+)(?::([^\s]*))?/;
+    const whitespaceMatch = whitespacePattern.exec(tail);
+    if (whitespaceMatch != null)
+        return replaceMatch(value, whitespaceMatch, ref);
+    else {
+        // find bracket pattern: ${KEY:DEFAULT}
+        const bracketPattern = /^\${([\w]+)(?::([^}]*))?}/;
+        const bracketMatch = bracketPattern.exec(tail);
+        if (bracketMatch != null)
+            return replaceMatch(value, bracketMatch, ref);
+    }
+    return value;
+};
+/**
+ * Recursively expands environment variables in a string. Variables may be
+ * presented with optional default as `$VAR[:default]` or `${VAR[:default]}`.
+ * Unknown variables will expand to an empty string.
+ *
+ * @param value - The string to expand.
+ * @param ref - The reference object to use for variable expansion.
+ * @returns The expanded string.
+ *
+ * @example
+ * ```ts
+ * process.env.FOO = 'bar';
+ * dotenvExpand('Hello $FOO'); // "Hello bar"
+ * dotenvExpand('Hello $BAZ:world'); // "Hello world"
+ * ```
+ *
+ * @remarks
+ * The expansion is recursive. If a referenced variable itself contains
+ * references, those will also be expanded until a stable value is reached.
+ * Escaped references (e.g. `\$FOO`) are preserved as literals.
+ */
+const dotenvExpand = (value, ref = process.env) => {
+    const result = interpolate(value, ref);
+    return result ? result.replace(/\\\$/g, '$') : undefined;
+};
+/**
+ * Recursively expands environment variables in the values of a JSON object.
+ * Variables may be presented with optional default as `$VAR[:default]` or
+ * `${VAR[:default]}`. Unknown variables will expand to an empty string.
+ *
+ * @param values - The values object to expand.
+ * @param options - Expansion options.
+ * @returns The value object with expanded string values.
+ *
+ * @example
+ * ```ts
+ * process.env.FOO = 'bar';
+ * dotenvExpandAll({ A: '$FOO', B: 'x${FOO}y' });
+ * // => { A: "bar", B: "xbary" }
+ * ```
+ *
+ * @remarks
+ * Options:
+ * - ref: The reference object to use for expansion (defaults to process.env).
+ * - progressive: Whether to progressively add expanded values to the set of
+ *   reference keys.
+ *
+ * When `progressive` is true, each expanded key becomes available for
+ * subsequent expansions in the same object (left-to-right by object key order).
+ */
+const dotenvExpandAll = (values = {}, options = {}) => Object.keys(values).reduce((acc, key) => {
+    const { ref = process.env, progressive = false } = options;
+    acc[key] = dotenvExpand(values[key], {
+        ...ref,
+        ...(progressive ? acc : {}),
+    });
+    return acc;
+}, {});
+/**
+ * Recursively expands environment variables in a string using `process.env` as
+ * the expansion reference. Variables may be presented with optional default as
+ * `$VAR[:default]` or `${VAR[:default]}`. Unknown variables will expand to an
+ * empty string.
+ *
+ * @param value - The string to expand.
+ * @returns The expanded string.
+ *
+ * @example
+ * ```ts
+ * process.env.FOO = 'bar';
+ * dotenvExpandFromProcessEnv('Hello $FOO'); // "Hello bar"
+ * ```
+ */
+const dotenvExpandFromProcessEnv = (value) => dotenvExpand(value, process.env);
+
+const applyKv = (current, kv) => {
+    if (!kv || Object.keys(kv).length === 0)
+        return current;
+    const expanded = dotenvExpandAll(kv, { ref: current, progressive: true });
+    return { ...current, ...expanded };
+};
+const applyConfigSlice = (current, cfg, env) => {
+    if (!cfg)
+        return current;
+    // kind axis: global then env (env overrides global)
+    const afterGlobal = applyKv(current, cfg.vars);
+    const envKv = env && cfg.envVars ? cfg.envVars[env] : undefined;
+    return applyKv(afterGlobal, envKv);
+};
+/**
+ * Overlay config-provided values onto a base ProcessEnv using precedence axes:
+ * - kind: env \> global
+ * - privacy: local \> public
+ * - source: project \> packaged \> base
+ *
+ * Programmatic explicit vars (if provided) override all config slices.
+ * Progressive expansion is applied within each slice.
+ */
+const overlayEnv = ({ base, env, configs, programmaticVars, }) => {
+    let current = { ...base };
+    // Source: packaged (public -> local)
+    current = applyConfigSlice(current, configs.packaged, env);
+    // Packaged "local" is not expected by policy; if present, honor it.
+    // We do not have a separate object for packaged.local in sources, keep as-is.
+    // Source: project (public -> local)
+    current = applyConfigSlice(current, configs.project?.public, env);
+    current = applyConfigSlice(current, configs.project?.local, env);
+    // Programmatic explicit vars (top of static tier)
+    if (programmaticVars) {
+        const toApply = Object.fromEntries(Object.entries(programmaticVars).filter(([_k, v]) => typeof v === 'string'));
+        current = applyKv(current, toApply);
+    }
+    return current;
+};
+
+/**
+ * Asynchronously read a dotenv file & parse it into an object.
+ *
+ * @param path - Path to dotenv file.
+ * @returns The parsed dotenv object.
+ */
+const readDotenv = async (path) => {
+    try {
+        return (await fs.exists(path)) ? parse(await fs.readFile(path)) : {};
+    }
+    catch {
+        return {};
+    }
+};
+
+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:
+ * - .js/.mjs/.cjs: direct import * - .ts/.mts/.cts/.tsx:
+ *   1) try direct import (if a TS loader is active),
+ *   2) esbuild bundle to a temp ESM file,
+ *   3) typescript.transpileModule fallback for simple modules.
+ *
+ * @param absPath - absolute path to source file
+ * @param cacheDirName - cache subfolder under .tsbuild
+ */
+const loadModuleDefault = async (absPath, cacheDirName) => {
+    const ext = path.extname(absPath).toLowerCase();
+    const fileUrl = url.pathToFileURL(absPath).toString();
+    if (!['.ts', '.mts', '.cts', '.tsx'].includes(ext)) {
+        return importDefault(fileUrl);
+    }
+    // Try direct import first (TS loader active)
+    try {
+        const dyn = await importDefault(fileUrl);
+        if (dyn)
+            return dyn;
+    }
+    catch {
+        /* fall through */
+    }
+    const stat = await fs.stat(absPath);
+    const hash = cacheHash(absPath, stat.mtimeMs);
+    const cacheDir = path.resolve('.tsbuild', cacheDirName);
+    await fs.ensureDir(cacheDir);
+    const cacheFile = path.join(cacheDir, `${path.basename(absPath)}.${hash}.mjs`);
+    // Try esbuild
+    try {
+        const esbuild = (await import('esbuild'));
+        await esbuild.build({
+            entryPoints: [absPath],
+            bundle: true,
+            platform: 'node',
+            format: 'esm',
+            target: 'node20',
+            outfile: cacheFile,
+            sourcemap: false,
+            logLevel: 'silent',
+        });
+        const result = await importDefault(url.pathToFileURL(cacheFile).toString());
+        // Best-effort: trim older cache files for this source.
+        await cleanupOldCacheFiles(cacheDir, path.basename(absPath));
+        return result;
+    }
+    catch {
+        /* fall through to TS transpile */
+    }
+    // TypeScript transpile fallback
+    try {
+        const ts = (await import('typescript'));
+        const code = await fs.readFile(absPath, 'utf-8');
+        const out = ts.transpileModule(code, {
+            compilerOptions: {
+                module: 'ESNext',
+                target: 'ES2022',
+                moduleResolution: 'NodeNext',
+            },
+        }).outputText;
+        await fs.writeFile(cacheFile, out, 'utf-8');
+        const result = await importDefault(url.pathToFileURL(cacheFile).toString());
+        // Best-effort: trim older cache files for this source.
+        await cleanupOldCacheFiles(cacheDir, path.basename(absPath));
+        return result;
+    }
+    catch {
+        // Caller decides final error wording; rethrow for upstream mapping.
+        throw new Error(`Unable to load JS/TS module: ${absPath}. Install 'esbuild' or ensure a TS loader.`);
+    }
+};
+
+/**
+ * Asynchronously process dotenv files of the form `.env[.<ENV>][.<PRIVATE_TOKEN>]`
+ *
+ * @param options - `GetDotenvOptions` object
+ * @returns The combined parsed dotenv object.
+ * * @example Load from the project root with default tokens
+ * ```ts
+ * const vars = await getDotenv();
+ * console.log(vars.MY_SETTING);
+ * ```
+ *
+ * @example Load from multiple paths and a specific environment
+ * ```ts
+ * const vars = await getDotenv({
+ *   env: 'dev',
+ *   dotenvToken: '.testenv',
+ *   privateToken: 'secret',
+ *   paths: ['./', './packages/app'],
+ * });
+ * ```
+ *
+ * @example Use dynamic variables
+ * ```ts
+ * // .env.js default-exports: { DYNAMIC: ({ PREV }) => `${PREV}-suffix` }
+ * const vars = await getDotenv({ dynamicPath: '.env.js' });
+ * ```
+ *
+ * @remarks
+ * - When {@link GetDotenvOptions.loadProcess} is true, the resulting variables are merged
+ *   into `process.env` as a side effect.
+ * - When {@link GetDotenvOptions.outputPath} is provided, a consolidated dotenv file is written.
+ *   The path is resolved after expansion, so it may reference previously loaded vars.
+ *
+ * @throws Error when a dynamic module is present but cannot be imported.
+ * @throws Error when an output path was requested but could not be resolved.
+ */
+const getDotenv = async (options = {}) => {
+    // Apply defaults.
+    const { defaultEnv, dotenvToken = '.env', dynamicPath, env, excludeDynamic = false, excludeEnv = false, excludeGlobal = false, excludePrivate = false, excludePublic = false, loadProcess = false, log = false, logger = console, outputPath, paths = [], privateToken = 'local', vars = {}, } = await resolveGetDotenvOptions(options);
+    // Read .env files.
+    const loaded = paths.length
+        ? await paths.reduce(async (e, p) => {
+            const publicGlobal = excludePublic || excludeGlobal
+                ? Promise.resolve({})
+                : readDotenv(path.resolve(p, dotenvToken));
+            const publicEnv = excludePublic || excludeEnv || (!env && !defaultEnv)
+                ? Promise.resolve({})
+                : readDotenv(path.resolve(p, `${dotenvToken}.${env ?? defaultEnv ?? ''}`));
+            const privateGlobal = excludePrivate || excludeGlobal
+                ? Promise.resolve({})
+                : readDotenv(path.resolve(p, `${dotenvToken}.${privateToken}`));
+            const privateEnv = excludePrivate || excludeEnv || (!env && !defaultEnv)
+                ? Promise.resolve({})
+                : readDotenv(path.resolve(p, `${dotenvToken}.${env ?? defaultEnv ?? ''}.${privateToken}`));
+            const [eResolved, publicGlobalResolved, publicEnvResolved, privateGlobalResolved, privateEnvResolved,] = await Promise.all([
+                e,
+                publicGlobal,
+                publicEnv,
+                privateGlobal,
+                privateEnv,
+            ]);
+            return {
+                ...eResolved,
+                ...publicGlobalResolved,
+                ...publicEnvResolved,
+                ...privateGlobalResolved,
+                ...privateEnvResolved,
+            };
+        }, Promise.resolve({}))
+        : {};
+    const outputKey = nanoid();
+    const dotenv = dotenvExpandAll({
+        ...loaded,
+        ...vars,
+        ...(outputPath ? { [outputKey]: outputPath } : {}),
+    }, { progressive: true });
+    // Process dynamic variables. Programmatic option takes precedence over path.
+    if (!excludeDynamic) {
+        let dynamic = undefined;
+        if (options.dynamic && Object.keys(options.dynamic).length > 0) {
+            dynamic = options.dynamic;
+        }
+        else if (dynamicPath) {
+            const absDynamicPath = path.resolve(dynamicPath);
+            if (await fs.exists(absDynamicPath)) {
+                try {
+                    dynamic = await loadModuleDefault(absDynamicPath, 'getdotenv-dynamic');
+                }
+                catch {
+                    // Preserve legacy error text for compatibility with tests/docs.
+                    throw new Error(`Unable to load dynamic TypeScript file: ${absDynamicPath}. ` +
+                        `Install 'esbuild' (devDependency) to enable TypeScript dynamic modules.`);
+                }
+            }
+        }
+        if (dynamic) {
+            try {
+                for (const key in dynamic)
+                    Object.assign(dotenv, {
+                        [key]: typeof dynamic[key] === 'function'
+                            ? dynamic[key](dotenv, env ?? defaultEnv)
+                            : dynamic[key],
+                    });
+            }
+            catch {
+                throw new Error(`Unable to evaluate dynamic variables.`);
+            }
+        }
+    }
+    // Write output file.
+    let resultDotenv = dotenv;
+    if (outputPath) {
+        const outputPathResolved = dotenv[outputKey];
+        if (!outputPathResolved)
+            throw new Error('Output path not found.');
+        const { [outputKey]: _omitted, ...dotenvForOutput } = dotenv;
+        await fs.writeFile(outputPathResolved, Object.keys(dotenvForOutput).reduce((contents, key) => {
+            const value = dotenvForOutput[key] ?? '';
+            return `${contents}${key}=${value.includes('\n') ? `"${value}"` : value}\n`;
+        }, ''), { encoding: 'utf-8' });
+        resultDotenv = dotenvForOutput;
+    }
+    // Log result.
+    if (log) {
+        const redactFlag = options.redact ?? false;
+        const redactPatterns = options.redactPatterns ?? undefined;
+        const redOpts = {};
+        if (redactFlag)
+            redOpts.redact = true;
+        if (redactFlag && Array.isArray(redactPatterns))
+            redOpts.redactPatterns = redactPatterns;
+        const bag = redactFlag
+            ? redactObject(resultDotenv, redOpts)
+            : { ...resultDotenv };
+        logger.log(bag);
+        // Entropy warnings: once-per-key-per-run (presentation only)
+        const warnEntropyVal = options.warnEntropy ?? true;
+        const entropyThresholdVal = options
+            .entropyThreshold;
+        const entropyMinLengthVal = options
+            .entropyMinLength;
+        const entropyWhitelistVal = options
+            .entropyWhitelist;
+        const entOpts = {};
+        if (typeof warnEntropyVal === 'boolean')
+            entOpts.warnEntropy = warnEntropyVal;
+        if (typeof entropyThresholdVal === 'number')
+            entOpts.entropyThreshold = entropyThresholdVal;
+        if (typeof entropyMinLengthVal === 'number')
+            entOpts.entropyMinLength = entropyMinLengthVal;
+        if (Array.isArray(entropyWhitelistVal))
+            entOpts.entropyWhitelist = entropyWhitelistVal;
+        for (const [k, v] of Object.entries(resultDotenv)) {
+            maybeWarnEntropy(k, v, v !== undefined ? 'dotenv' : 'unset', entOpts, (line) => {
+                logger.log(line);
+            });
+        }
+    }
+    // Load process.env.
+    if (loadProcess)
+        Object.assign(process.env, resultDotenv);
+    return resultDotenv;
+};
+
+/**
+ * Deep interpolation utility for string leaves.
+ * - Expands string values using dotenv-style expansion against the provided envRef.
+ * - Preserves non-strings as-is.
+ * - Does not recurse into arrays (arrays are returned unchanged).
+ *
+ * Intended for:
+ * - Phase C option/config interpolation after composing ctx.dotenv.
+ * - Per-plugin config slice interpolation before afterResolve.
+ */
+/** @internal */
+const isPlainObject = (v) => v !== null &&
+    typeof v === 'object' &&
+    !Array.isArray(v) &&
+    Object.getPrototypeOf(v) === Object.prototype;
+/**
+ * Deeply interpolate string leaves against envRef.
+ * Arrays are not recursed into; they are returned unchanged.
+ *
+ * @typeParam T - Shape of the input value.
+ * @param value - Input value (object/array/primitive).
+ * @param envRef - Reference environment for interpolation.
+ * @returns A new value with string leaves interpolated.
+ */
+const interpolateDeep = (value, envRef) => {
+    // Strings: expand and return
+    if (typeof value === 'string') {
+        const out = dotenvExpand(value, envRef);
+        // dotenvExpand returns string | undefined; preserve original on undefined
+        return (out ?? value);
+    }
+    // Arrays: return as-is (no recursion)
+    if (Array.isArray(value)) {
+        return value;
+    }
+    // Plain objects: shallow clone and recurse into values
+    if (isPlainObject(value)) {
+        const src = value;
+        const out = {};
+        for (const [k, v] of Object.entries(src)) {
+            // Recurse for strings/objects; keep arrays as-is; preserve other scalars
+            if (typeof v === 'string')
+                out[k] = dotenvExpand(v, envRef) ?? v;
+            else if (Array.isArray(v))
+                out[k] = v;
+            else if (isPlainObject(v))
+                out[k] = interpolateDeep(v, envRef);
+            else
+                out[k] = v;
+        }
+        return out;
+    }
+    // Other primitives/types: return as-is
+    return value;
+};
+
+/**
+ * Compute the dotenv context for the host (uses the config loader/overlay path).
+ * - Resolves and validates options strictly (host-only).
+ * - Applies file cascade, overlays, dynamics, and optional effects.
+ * - Merges and validates per-plugin config slices (when provided).
+ *
+ * @param customOptions - Partial options from the current invocation.
+ * @param plugins - Installed plugins (for config validation).
+ * @param hostMetaUrl - import.meta.url of the host module (for packaged root discovery). */
+const computeContext = async (customOptions, plugins, hostMetaUrl) => {
+    const optionsResolved = await resolveGetDotenvOptions(customOptions);
+    const validated = getDotenvOptionsSchemaResolved.parse(optionsResolved);
+    // Always-on loader path
+    // 1) Base from files only (no dynamic, no programmatic vars)
+    const base = await getDotenv({
+        ...validated,
+        // Build a pure base without side effects or logging.
+        excludeDynamic: true,
+        vars: {},
+        log: false,
+        loadProcess: false,
+        outputPath: undefined,
+    });
+    // 2) Discover config sources and overlay
+    const sources = await resolveGetDotenvConfigSources(hostMetaUrl);
+    const dotenvOverlaid = overlayEnv({
+        base,
+        env: validated.env ?? validated.defaultEnv,
+        configs: sources,
+        ...(validated.vars ? { programmaticVars: validated.vars } : {}),
+    });
+    // Helper to apply a dynamic map progressively.
+    const applyDynamic = (target, dynamic, env) => {
+        if (!dynamic)
+            return;
+        for (const key of Object.keys(dynamic)) {
+            const value = typeof dynamic[key] === 'function'
+                ? dynamic[key](target, env)
+                : dynamic[key];
+            Object.assign(target, { [key]: value });
+        }
+    };
+    // 3) Apply dynamics in order
+    const dotenv = { ...dotenvOverlaid };
+    applyDynamic(dotenv, validated.dynamic, validated.env ?? validated.defaultEnv);
+    applyDynamic(dotenv, (sources.packaged?.dynamic ?? undefined), validated.env ?? validated.defaultEnv);
+    applyDynamic(dotenv, (sources.project?.public?.dynamic ?? undefined), validated.env ?? validated.defaultEnv);
+    applyDynamic(dotenv, (sources.project?.local?.dynamic ?? undefined), validated.env ?? validated.defaultEnv);
+    // file dynamicPath (lowest)
+    if (validated.dynamicPath) {
+        const absDynamicPath = path.resolve(validated.dynamicPath);
+        try {
+            const dyn = await loadModuleDefault(absDynamicPath, 'getdotenv-dynamic-host');
+            applyDynamic(dotenv, dyn, validated.env ?? validated.defaultEnv);
+        }
+        catch {
+            throw new Error(`Unable to load dynamic from ${validated.dynamicPath}`);
+        }
+    }
+    // 4) Output/log/process merge
+    if (validated.outputPath) {
+        await fs.writeFile(validated.outputPath, Object.keys(dotenv).reduce((contents, key) => {
+            const value = dotenv[key] ?? '';
+            return `${contents}${key}=${value.includes('\n') ? `"${value}"` : value}\n`;
+        }, ''), { encoding: 'utf-8' });
+    }
+    const logger = validated.logger ?? console;
+    if (validated.log)
+        logger.log(dotenv);
+    if (validated.loadProcess)
+        Object.assign(process.env, dotenv);
+    // 5) Merge and validate per-plugin config (packaged < project.public < project.local)
+    const packagedPlugins = (sources.packaged &&
+        sources.packaged.plugins) ??
+        {};
+    const publicPlugins = (sources.project?.public &&
+        sources.project.public.plugins) ??
+        {};
+    const localPlugins = (sources.project?.local &&
+        sources.project.local.plugins) ??
+        {};
+    const mergedPluginConfigs = defaultsDeep({}, packagedPlugins, publicPlugins, localPlugins);
+    for (const p of plugins) {
+        if (!p.id)
+            continue;
+        const slice = mergedPluginConfigs[p.id];
+        if (slice === undefined)
+            continue;
+        // Per-plugin interpolation just before validation/afterResolve:
+        // precedence: process.env wins over ctx.dotenv for slice defaults.
+        const envRef = {
+            ...dotenv,
+            ...process.env,
+        };
+        const interpolated = interpolateDeep(slice, envRef);
+        // Validate if a schema is provided; otherwise accept interpolated slice as-is.
+        if (p.configSchema) {
+            const parsed = p.configSchema.safeParse(interpolated);
+            if (!parsed.success) {
+                const msgs = parsed.error.issues
+                    .map((i) => `${i.path.join('.')}: ${i.message}`)
+                    .join('\n');
+                throw new Error(`Invalid config for plugin '${p.id}':\n${msgs}`);
+            }
+            mergedPluginConfigs[p.id] = parsed.data;
+        }
+        else {
+            mergedPluginConfigs[p.id] = interpolated;
+        }
+    }
+    return {
+        optionsResolved: validated,
+        dotenv: dotenv,
+        plugins: {},
+        pluginConfigs: mergedPluginConfigs,
+    };
+};
+
+const HOST_META_URL = 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.
+ *
+ * NOTE: This host is additive and does not alter the legacy CLI.
+ */
+class GetDotenvCli extends Command {
+    /** Registered top-level plugins (composition happens via .use()) */
+    _plugins = [];
+    /** One-time installation guard */
+    _installed = false;
+    /** Optional header line to prepend in help output */
+    [HELP_HEADER_SYMBOL];
+    constructor(alias = 'getdotenv') {
+        super(alias);
+        // Ensure subcommands that use passThroughOptions can be attached safely.
+        // Commander requires parent commands to enable positional options when a
+        // child uses passThroughOptions.
+        this.enablePositionalOptions();
+        // Configure grouped help: show only base options in default "Options";
+        // append App/Plugin sections after default help.
+        this.configureHelp({
+            visibleOptions: (cmd) => {
+                const all = cmd.options ??
+                    [];
+                const base = all.filter((opt) => {
+                    const group = opt.__group;
+                    return group === 'base';
+                });
+                // Sort: short-aliased options first, then long-only; stable by flags.
+                const hasShort = (opt) => {
+                    const flags = opt.flags ?? '';
+                    // Matches "-x," or starting "-x " before any long
+                    return /(^|\s|,)-[A-Za-z]/.test(flags);
+                };
+                const byFlags = (opt) => opt.flags ?? '';
+                base.sort((a, b) => {
+                    const aS = hasShort(a) ? 1 : 0;
+                    const bS = hasShort(b) ? 1 : 0;
+                    return bS - aS || byFlags(a).localeCompare(byFlags(b));
+                });
+                return base;
+            },
+        });
+        this.addHelpText('beforeAll', () => {
+            const header = this[HELP_HEADER_SYMBOL];
+            return header && header.length > 0 ? `${header}\n\n` : '';
+        });
+        this.addHelpText('afterAll', (ctx) => this.#renderOptionGroups(ctx.command));
+        // Skeleton preSubcommand hook: produce a context if absent, without
+        // mutating process.env. The passOptions hook (when installed) will    // compute the final context using merged CLI options; keeping
+        // loadProcess=false here avoids leaking dotenv values into the parent
+        // process env before subcommands execute.
+        this.hook('preSubcommand', async () => {
+            if (this.getCtx())
+                return;
+            await this.resolveAndLoad({ loadProcess: false });
+        });
+    }
+    /**
+     * Resolve options (strict) and compute dotenv context.   * Stores the context on the instance under a symbol.
+     */
+    async resolveAndLoad(customOptions = {}) {
+        // Resolve defaults, then validate strictly under the new host.
+        const optionsResolved = await resolveGetDotenvOptions(customOptions);
+        getDotenvOptionsSchemaResolved.parse(optionsResolved);
+        // Delegate the heavy lifting to the shared helper (guarded path supported).
+        const ctx = await computeContext(optionsResolved, this._plugins, HOST_META_URL);
+        // Persist context on the instance for later access.
+        this[CTX_SYMBOL] =
+            ctx;
+        // Ensure plugins are installed exactly once, then run afterResolve.
+        await this.install();
+        await this._runAfterResolve(ctx);
+        return ctx;
+    }
+    /**
+     * Retrieve the current invocation context (if any).
+     */
+    getCtx() {
+        return this[CTX_SYMBOL];
+    }
+    /**
+     * Retrieve the merged root CLI options bag (if set by passOptions()).
+     * Downstream-safe: no generics required.
+     */
+    getOptions() {
+        return this[OPTS_SYMBOL];
+    }
+    /** Internal: set the merged root options bag for this run. */
+    _setOptionsBag(bag) {
+        this[OPTS_SYMBOL] = bag;
+    }
+    /**   * Convenience helper to create a namespaced subcommand.
+     */
+    ns(name) {
+        return this.command(name);
+    }
+    /**
+     * Tag options added during the provided callback as 'app' for grouped help.
+     * Allows downstream apps to demarcate their root-level options.
+     */
+    tagAppOptions(fn) {
+        const root = this;
+        const originalAddOption = root.addOption.bind(root);
+        const originalOption = root.option.bind(root);
+        const tagLatest = (cmd, group) => {
+            const optsArr = cmd.options;
+            if (Array.isArray(optsArr) && optsArr.length > 0) {
+                const last = optsArr[optsArr.length - 1];
+                last.__group = group;
+            }
+        };
+        root.addOption = function patchedAdd(opt) {
+            opt.__group = 'app';
+            return originalAddOption(opt);
+        };
+        root.option = function patchedOption(...args) {
+            const ret = originalOption(...args);
+            tagLatest(this, 'app');
+            return ret;
+        };
+        try {
+            return fn(root);
+        }
+        finally {
+            root.addOption = originalAddOption;
+            root.option = originalOption;
+        }
+    }
+    /**
+     * Branding helper: set CLI name/description/version and optional help header.
+     * If version is omitted and importMetaUrl is provided, attempts to read the
+     * nearest package.json version (best-effort; non-fatal on failure).
+     */
+    async brand(args) {
+        const { name, description, version, importMetaUrl, helpHeader } = args;
+        if (typeof name === 'string' && name.length > 0)
+            this.name(name);
+        if (typeof description === 'string')
+            this.description(description);
+        let v = version;
+        if (!v && importMetaUrl) {
+            try {
+                const fromUrl = fileURLToPath(importMetaUrl);
+                const pkgDir = await packageDirectory({ cwd: fromUrl });
+                if (pkgDir) {
+                    const txt = await fs.readFile(`${pkgDir}/package.json`, 'utf-8');
+                    const pkg = JSON.parse(txt);
+                    if (pkg.version)
+                        v = pkg.version;
+                }
+            }
+            catch {
+                // best-effort only
+            }
+        }
+        if (v)
+            this.version(v);
+        // Help header:
+        // - If caller provides helpHeader, use it.
+        // - Otherwise, when a version is known, default to "<name> v<version>".
+        if (typeof helpHeader === 'string') {
+            this[HELP_HEADER_SYMBOL] = helpHeader;
+        }
+        else if (v) {
+            // Use the current command name (possibly overridden by 'name' above).
+            const header = `${this.name()} v${v}`;
+            this[HELP_HEADER_SYMBOL] = header;
+        }
+        return this;
+    }
+    /**
+     * Register a plugin for installation (parent level).
+     * Installation occurs on first resolveAndLoad() (or explicit install()).
+     */
+    use(plugin) {
+        this._plugins.push(plugin);
+        // Immediately run setup so subcommands exist before parsing.
+        const setupOne = (p) => {
+            p.setup(this);
+            for (const child of p.children)
+                setupOne(child);
+        };
+        setupOne(plugin);
+        return this;
+    }
+    /**
+     * Install all registered plugins in parent → children (pre-order).
+     * Runs only once per CLI instance.
+     */
+    async install() {
+        // Setup is performed immediately in use(); here we only guard for afterResolve.
+        this._installed = true;
+        // Satisfy require-await without altering behavior.
+        await Promise.resolve();
+    }
+    /**
+     * Run afterResolve hooks for all plugins (parent → children).
+     */
+    async _runAfterResolve(ctx) {
+        const run = async (p) => {
+            if (p.afterResolve)
+                await p.afterResolve(this, ctx);
+            for (const child of p.children)
+                await run(child);
+        };
+        for (const p of this._plugins)
+            await run(p);
+    }
+    // Render App/Plugin grouped options appended after default help.
+    #renderOptionGroups(cmd) {
+        const all = cmd.options ?? [];
+        const byGroup = new Map();
+        for (const o of all) {
+            const opt = o;
+            const g = opt.__group;
+            if (!g || g === 'base')
+                continue; // base handled by default help
+            const rows = byGroup.get(g) ?? [];
+            rows.push({
+                flags: opt.flags ?? '',
+                description: opt.description ?? '',
+            });
+            byGroup.set(g, rows);
+        }
+        if (byGroup.size === 0)
+            return '';
+        const renderRows = (title, rows) => {
+            const width = Math.min(40, rows.reduce((m, r) => Math.max(m, r.flags.length), 0));
+            // Sort within group: short-aliased flags first
+            rows.sort((a, b) => {
+                const aS = /(^|\s|,)-[A-Za-z]/.test(a.flags) ? 1 : 0;
+                const bS = /(^|\s|,)-[A-Za-z]/.test(b.flags) ? 1 : 0;
+                return bS - aS || a.flags.localeCompare(b.flags);
+            });
+            const lines = rows
+                .map((r) => {
+                const pad = ' '.repeat(Math.max(2, width - r.flags.length + 2));
+                return `  ${r.flags}${pad}${r.description}`.trimEnd();
+            })
+                .join('\n');
+            return `\n${title}:\n${lines}\n`;
+        };
+        let out = '';
+        // App options (if any)
+        const app = byGroup.get('app');
+        if (app && app.length > 0) {
+            out += renderRows('App options', app);
+        }
+        // Plugin groups sorted by id
+        const pluginKeys = Array.from(byGroup.keys()).filter((k) => k.startsWith('plugin:'));
+        pluginKeys.sort((a, b) => a.localeCompare(b));
+        for (const k of pluginKeys) {
+            const id = k.slice('plugin:'.length) || '(unknown)';
+            const rows = byGroup.get(k) ?? [];
+            if (rows.length > 0) {
+                out += renderRows(`Plugin options — ${id}`, rows);
+            }
+        }
+        return out;
+    }
+}
+
+/**
+ * Validate a composed env against config-provided validation surfaces.
+ * Precedence for validation definitions:
+ *   project.local -\> project.public -\> packaged
+ *
+ * Behavior:
+ * - If a JS/TS `schema` is present, use schema.safeParse(finalEnv).
+ * - Else if `requiredKeys` is present, check presence (value !== undefined).
+ * - Returns a flat list of issue strings; caller decides warn vs fail.
+ */
+const validateEnvAgainstSources = (finalEnv, sources) => {
+    const pick = (getter) => {
+        const pl = sources.project?.local;
+        const pp = sources.project?.public;
+        const pk = sources.packaged;
+        return ((pl && getter(pl)) ||
+            (pp && getter(pp)) ||
+            (pk && getter(pk)) ||
+            undefined);
+    };
+    const schema = pick((cfg) => cfg['schema']);
+    if (schema &&
+        typeof schema.safeParse === 'function') {
+        try {
+            const parsed = schema.safeParse(finalEnv);
+            if (!parsed.success) {
+                // Try to render zod-style issues when available.
+                const err = parsed.error;
+                const issues = Array.isArray(err.issues) && err.issues.length > 0
+                    ? err.issues.map((i) => {
+                        const path = Array.isArray(i.path) ? i.path.join('.') : '';
+                        const msg = i.message ?? 'Invalid value';
+                        return path ? `[schema] ${path}: ${msg}` : `[schema] ${msg}`;
+                    })
+                    : ['[schema] validation failed'];
+                return issues;
+            }
+            return [];
+        }
+        catch {
+            // If schema invocation fails, surface a single diagnostic.
+            return [
+                '[schema] validation failed (unable to execute schema.safeParse)',
+            ];
+        }
+    }
+    const requiredKeys = pick((cfg) => cfg['requiredKeys']);
+    if (Array.isArray(requiredKeys) && requiredKeys.length > 0) {
+        const missing = requiredKeys.filter((k) => finalEnv[k] === undefined);
+        if (missing.length > 0) {
+            return missing.map((k) => `[requiredKeys] missing: ${k}`);
+        }
+    }
+    return [];
+};
+
+/**
+ * Attach legacy root flags to a Commander program.
+ * Uses provided defaults to render help labels without coupling to generators.
+ */
+const attachRootOptions = (program, defaults, opts) => {
+    // Install temporary wrappers to tag all options added here as "base".
+    const GROUP = 'base';
+    const tagLatest = (cmd, group) => {
+        const optsArr = cmd.options;
+        if (Array.isArray(optsArr) && optsArr.length > 0) {
+            const last = optsArr[optsArr.length - 1];
+            last.__group = group;
+        }
+    };
+    const originalAddOption = program.addOption.bind(program);
+    const originalOption = program.option.bind(program);
+    program.addOption = function patchedAdd(opt) {
+        // Tag before adding, in case consumers inspect the Option directly.
+        opt.__group = GROUP;
+        const ret = originalAddOption(opt);
+        return ret;
+    };
+    program.option = function patchedOption(...args) {
+        const ret = originalOption(...args);
+        tagLatest(this, GROUP);
+        return ret;
+    };
+    const { defaultEnv, dotenvToken, dynamicPath, env, excludeDynamic, excludeEnv, excludeGlobal, excludePrivate, excludePublic, loadProcess, log, outputPath, paths, pathsDelimiter, pathsDelimiterPattern, privateToken, scripts, shell, varsAssignor, varsAssignorPattern, varsDelimiter, varsDelimiterPattern, } = defaults ?? {};
+    const va = typeof defaults?.varsAssignor === 'string' ? defaults.varsAssignor : '=';
+    const vd = typeof defaults?.varsDelimiter === 'string' ? defaults.varsDelimiter : ' ';
+    // Build initial chain.
+    let p = program
+        .enablePositionalOptions()
+        .passThroughOptions()
+        .option('-e, --env <string>', `target environment (dotenv-expanded)`, dotenvExpandFromProcessEnv, env);
+    p = p.option('-v, --vars <string>', `extra variables expressed as delimited key-value pairs (dotenv-expanded): ${[
+        ['KEY1', 'VAL1'],
+        ['KEY2', 'VAL2'],
+    ]
+        .map((v) => v.join(va))
+        .join(vd)}`, dotenvExpandFromProcessEnv);
+    // Optional legacy root command flag (kept for generated CLI compatibility).
+    // Default is OFF; the generator opts in explicitly.
+    if (opts?.includeCommandOption === true) {
+        p = p.option('-c, --command <string>', 'command executed according to the --shell option, conflicts with cmd subcommand (dotenv-expanded)', dotenvExpandFromProcessEnv);
+    }
+    p = p
+        .option('-o, --output-path <string>', 'consolidated output file  (dotenv-expanded)', dotenvExpandFromProcessEnv, outputPath)
+        .addOption(new Option('-s, --shell [string]', (() => {
+        let defaultLabel = '';
+        if (shell !== undefined) {
+            if (typeof shell === 'boolean') {
+                defaultLabel = ' (default OS shell)';
+            }
+            else if (typeof shell === 'string') {
+                // Safe string interpolation
+                defaultLabel = ` (default ${shell})`;
+            }
+        }
+        return `command execution shell, no argument for default OS shell or provide shell string${defaultLabel}`;
+    })()).conflicts('shellOff'))
+        .addOption(new Option('-S, --shell-off', `command execution shell OFF${!shell ? ' (default)' : ''}`).conflicts('shell'))
+        .addOption(new Option('-p, --load-process', `load variables to process.env ON${loadProcess ? ' (default)' : ''}`).conflicts('loadProcessOff'))
+        .addOption(new Option('-P, --load-process-off', `load variables to process.env OFF${!loadProcess ? ' (default)' : ''}`).conflicts('loadProcess'))
+        .addOption(new Option('-a, --exclude-all', `exclude all dotenv variables from loading ON${excludeDynamic &&
+        ((excludeEnv && excludeGlobal) || (excludePrivate && excludePublic))
+        ? ' (default)'
+        : ''}`).conflicts('excludeAllOff'))
+        .addOption(new Option('-A, --exclude-all-off', `exclude all dotenv variables from loading OFF (default)`).conflicts('excludeAll'))
+        .addOption(new Option('-z, --exclude-dynamic', `exclude dynamic dotenv variables from loading ON${excludeDynamic ? ' (default)' : ''}`).conflicts('excludeDynamicOff'))
+        .addOption(new Option('-Z, --exclude-dynamic-off', `exclude dynamic dotenv variables from loading OFF${!excludeDynamic ? ' (default)' : ''}`).conflicts('excludeDynamic'))
+        .addOption(new Option('-n, --exclude-env', `exclude environment-specific dotenv variables from loading${excludeEnv ? ' (default)' : ''}`).conflicts('excludeEnvOff'))
+        .addOption(new Option('-N, --exclude-env-off', `exclude environment-specific dotenv variables from loading OFF${!excludeEnv ? ' (default)' : ''}`).conflicts('excludeEnv'))
+        .addOption(new Option('-g, --exclude-global', `exclude global dotenv variables from loading ON${excludeGlobal ? ' (default)' : ''}`).conflicts('excludeGlobalOff'))
+        .addOption(new Option('-G, --exclude-global-off', `exclude global dotenv variables from loading OFF${!excludeGlobal ? ' (default)' : ''}`).conflicts('excludeGlobal'))
+        .addOption(new Option('-r, --exclude-private', `exclude private dotenv variables from loading ON${excludePrivate ? ' (default)' : ''}`).conflicts('excludePrivateOff'))
+        .addOption(new Option('-R, --exclude-private-off', `exclude private dotenv variables from loading OFF${!excludePrivate ? ' (default)' : ''}`).conflicts('excludePrivate'))
+        .addOption(new Option('-u, --exclude-public', `exclude public dotenv variables from loading ON${excludePublic ? ' (default)' : ''}`).conflicts('excludePublicOff'))
+        .addOption(new Option('-U, --exclude-public-off', `exclude public dotenv variables from loading OFF${!excludePublic ? ' (default)' : ''}`).conflicts('excludePublic'))
+        .addOption(new Option('-l, --log', `console log loaded variables ON${log ? ' (default)' : ''}`).conflicts('logOff'))
+        .addOption(new Option('-L, --log-off', `console log loaded variables OFF${!log ? ' (default)' : ''}`).conflicts('log'))
+        .option('--capture', 'capture child process stdio for commands (tests/CI)')
+        .option('--redact', 'mask secret-like values in logs/trace (presentation-only)')
+        .option('--default-env <string>', 'default target environment', dotenvExpandFromProcessEnv, defaultEnv)
+        .option('--dotenv-token <string>', 'dotenv-expanded token indicating a dotenv file', dotenvExpandFromProcessEnv, dotenvToken)
+        .option('--dynamic-path <string>', 'dynamic variables path (.js or .ts; .ts is auto-compiled when esbuild is available, otherwise precompile)', dotenvExpandFromProcessEnv, dynamicPath)
+        .option('--paths <string>', 'dotenv-expanded delimited list of paths to dotenv directory', dotenvExpandFromProcessEnv, paths)
+        .option('--paths-delimiter <string>', 'paths delimiter string', pathsDelimiter)
+        .option('--paths-delimiter-pattern <string>', 'paths delimiter regex pattern', pathsDelimiterPattern)
+        .option('--private-token <string>', 'dotenv-expanded token indicating private variables', dotenvExpandFromProcessEnv, privateToken)
+        .option('--vars-delimiter <string>', 'vars delimiter string', varsDelimiter)
+        .option('--vars-delimiter-pattern <string>', 'vars delimiter regex pattern', varsDelimiterPattern)
+        .option('--vars-assignor <string>', 'vars assignment operator string', varsAssignor)
+        .option('--vars-assignor-pattern <string>', 'vars assignment operator regex pattern', varsAssignorPattern)
+        // Hidden scripts pipe-through (stringified)
+        .addOption(new Option('--scripts <string>')
+        .default(JSON.stringify(scripts))
+        .hideHelp());
+    // Diagnostics: opt-in tracing; optional variadic keys after the flag.
+    p = p.option('--trace [keys...]', 'emit diagnostics for child env composition (optional keys)');
+    // Validation: strict mode fails on env validation issues (warn by default).
+    p = p.option('--strict', 'fail on env validation errors (schema/requiredKeys)');
+    // Entropy diagnostics (presentation-only)
+    p = p
+        .addOption(new Option('--entropy-warn', 'enable entropy warnings (default on)').conflicts('entropyWarnOff'))
+        .addOption(new Option('--entropy-warn-off', 'disable entropy warnings').conflicts('entropyWarn'))
+        .option('--entropy-threshold <number>', 'entropy bits/char threshold (default 3.8)')
+        .option('--entropy-min-length <number>', 'min length to examine for entropy (default 16)')
+        .option('--entropy-whitelist <pattern...>', 'suppress entropy warnings when key matches any regex pattern')
+        .option('--redact-pattern <pattern...>', 'additional key-match regex patterns to trigger redaction');
+    // Restore original methods to avoid tagging future additions outside base.
+    program.addOption = originalAddOption;
+    program.option = originalOption;
+    return p;
+};
+
+/**
+ * Resolve a tri-state optional boolean flag under exactOptionalPropertyTypes.
+ * - If the user explicitly enabled the flag, return true.
+ * - If the user explicitly disabled (the "...-off" variant), return undefined (unset).
+ * - Otherwise, adopt the default (true → set; false/undefined → unset).
+ *
+ * @param exclude - The "on" flag value as parsed by Commander.
+ * @param excludeOff - The "off" toggle (present when specified) as parsed by Commander.
+ * @param defaultValue - The generator default to adopt when no explicit toggle is present.
+ * @returns boolean | undefined — use `undefined` to indicate "unset" (do not emit).
+ *
+ * @example
+ * ```ts
+ * resolveExclusion(undefined, undefined, true); // => true
+ * ```
+ */
+const resolveExclusion = (exclude, excludeOff, defaultValue) => exclude ? true : excludeOff ? undefined : defaultValue ? true : undefined;
+/**
+ * Resolve an optional flag with "--exclude-all" overrides.
+ * If excludeAll is set and the individual "...-off" is not, force true.
+ * If excludeAllOff is set and the individual flag is not explicitly set, unset.
+ * Otherwise, adopt the default (true → set; false/undefined → unset).
+ *
+ * @param exclude - Individual include/exclude flag.
+ * @param excludeOff - Individual "...-off" flag.
+ * @param defaultValue - Default for the individual flag.
+ * @param excludeAll - Global "exclude-all" flag.
+ * @param excludeAllOff - Global "exclude-all-off" flag.
+ *
+ * @example
+ * resolveExclusionAll(undefined, undefined, false, true, undefined) =\> true
+ */
+const resolveExclusionAll = (exclude, excludeOff, defaultValue, excludeAll, excludeAllOff) => 
+// Order of precedence:
+// 1) Individual explicit "on" wins outright.
+// 2) Individual explicit "off" wins over any global.
+// 3) Global exclude-all forces true when not explicitly turned off.
+// 4) Global exclude-all-off unsets when the individual wasn't explicitly enabled.
+// 5) Fall back to the default (true => set; false/undefined => unset).
+(() => {
+    // Individual "on"
+    if (exclude === true)
+        return true;
+    // Individual "off"
+    if (excludeOff === true)
+        return undefined;
+    // Global "exclude-all" ON (unless explicitly turned off)
+    if (excludeAll === true)
+        return true;
+    // Global "exclude-all-off" (unless explicitly enabled)
+    if (excludeAllOff === true)
+        return undefined;
+    // Default
+    return defaultValue ? true : undefined;
+})();
+/**
+ * exactOptionalPropertyTypes-safe setter for optional boolean flags:
+ * delete when undefined; assign when defined — without requiring an index signature on T.
+ *
+ * @typeParam T - Target object type.
+ * @param obj - The object to write to.
+ * @param key - The optional boolean property key of {@link T}.
+ * @param value - The value to set or `undefined` to unset.
+ *
+ * @remarks
+ * Writes through a local `Record<string, unknown>` view to avoid requiring an index signature on {@link T}.
+ */
+const setOptionalFlag = (obj, key, value) => {
+    const target = obj;
+    const k = key;
+    // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+    if (value === undefined)
+        delete target[k];
+    else
+        target[k] = value;
+};
+
+/**
+ * Merge and normalize raw Commander options (current + parent + defaults)
+ * into a GetDotenvCliOptions-like object. Types are intentionally wide to
+ * avoid cross-layer coupling; callers may cast as needed.
+ */
+const resolveCliOptions = (rawCliOptions, defaults, parentJson) => {
+    const parent = typeof parentJson === 'string' && parentJson.length > 0
+        ? JSON.parse(parentJson)
+        : undefined;
+    const { command, debugOff, excludeAll, excludeAllOff, excludeDynamicOff, excludeEnvOff, excludeGlobalOff, excludePrivateOff, excludePublicOff, loadProcessOff, logOff, entropyWarn, entropyWarnOff, scripts, shellOff, ...rest } = rawCliOptions;
+    const current = { ...rest };
+    if (typeof scripts === 'string') {
+        try {
+            current.scripts = JSON.parse(scripts);
+        }
+        catch {
+            // ignore parse errors; leave scripts undefined
+        }
+    }
+    const merged = defaultsDeep({}, defaults, parent ?? {}, current);
+    const d = defaults;
+    setOptionalFlag(merged, 'debug', resolveExclusion(merged.debug, debugOff, d.debug));
+    setOptionalFlag(merged, 'excludeDynamic', resolveExclusionAll(merged.excludeDynamic, excludeDynamicOff, d.excludeDynamic, excludeAll, excludeAllOff));
+    setOptionalFlag(merged, 'excludeEnv', resolveExclusionAll(merged.excludeEnv, excludeEnvOff, d.excludeEnv, excludeAll, excludeAllOff));
+    setOptionalFlag(merged, 'excludeGlobal', resolveExclusionAll(merged.excludeGlobal, excludeGlobalOff, d.excludeGlobal, excludeAll, excludeAllOff));
+    setOptionalFlag(merged, 'excludePrivate', resolveExclusionAll(merged.excludePrivate, excludePrivateOff, d.excludePrivate, excludeAll, excludeAllOff));
+    setOptionalFlag(merged, 'excludePublic', resolveExclusionAll(merged.excludePublic, excludePublicOff, d.excludePublic, excludeAll, excludeAllOff));
+    setOptionalFlag(merged, 'log', resolveExclusion(merged.log, logOff, d.log));
+    setOptionalFlag(merged, 'loadProcess', resolveExclusion(merged.loadProcess, loadProcessOff, d.loadProcess));
+    // warnEntropy (tri-state)
+    setOptionalFlag(merged, 'warnEntropy', resolveExclusion(merged.warnEntropy, entropyWarnOff, d.warnEntropy));
+    // Normalize shell for predictability: explicit default shell per OS.
+    const defaultShell = process.platform === 'win32' ? 'powershell.exe' : '/bin/bash';
+    let resolvedShell = merged.shell;
+    if (shellOff)
+        resolvedShell = false;
+    else if (resolvedShell === true || resolvedShell === undefined) {
+        resolvedShell = defaultShell;
+    }
+    else if (typeof resolvedShell !== 'string' &&
+        typeof defaults.shell === 'string') {
+        resolvedShell = defaults.shell;
+    }
+    merged.shell = resolvedShell;
+    const cmd = typeof command === 'string' ? command : undefined;
+    return cmd !== undefined ? { merged, command: cmd } : { merged };
+};
+
+GetDotenvCli.prototype.attachRootOptions = function (defaults, opts) {
+    const d = (defaults ?? baseRootOptionDefaults);
+    attachRootOptions(this, d, opts);
+    return this;
+};
+GetDotenvCli.prototype.passOptions = function (defaults) {
+    const d = (defaults ?? baseRootOptionDefaults);
+    this.hook('preSubcommand', async (thisCommand) => {
+        const raw = thisCommand.opts();
+        const { merged } = resolveCliOptions(raw, d, process.env.getDotenvCliOptions);
+        // Persist merged options for nested invocations (batch exec).
+        thisCommand.getDotenvCliOptions =
+            merged;
+        // Also store on the host for downstream ergonomic accessors.
+        this._setOptionsBag(merged);
+        // Build service options and compute context (always-on config loader path).
+        const serviceOptions = getDotenvCliOptions2Options(merged);
+        await this.resolveAndLoad(serviceOptions);
+        // Global validation: once after Phase C using config sources.
+        try {
+            const ctx = this.getCtx();
+            const dotenv = (ctx?.dotenv ?? {});
+            const sources = await resolveGetDotenvConfigSources(import.meta.url);
+            const issues = validateEnvAgainstSources(dotenv, sources);
+            if (Array.isArray(issues) && issues.length > 0) {
+                const logger = (merged.logger ??
+                    console);
+                const emit = logger.error ?? logger.log;
+                issues.forEach((m) => {
+                    emit(m);
+                });
+                if (merged.strict) {
+                    // Deterministic failure under strict mode
+                    process.exit(1);
+                }
+            }
+        }
+        catch {
+            // Be tolerant: validation errors reported above; unexpected failures here
+            // should not crash non-strict flows.
+        }
+    });
+    // Also handle root-level flows (no subcommand) so option-aliases can run
+    // with the same merged options and context without duplicating logic.
+    this.hook('preAction', async (thisCommand) => {
+        const raw = thisCommand.opts();
+        const { merged } = resolveCliOptions(raw, d, process.env.getDotenvCliOptions);
+        thisCommand.getDotenvCliOptions =
+            merged;
+        this._setOptionsBag(merged);
+        // Avoid duplicate heavy work if a context is already present.
+        if (!this.getCtx()) {
+            const serviceOptions = getDotenvCliOptions2Options(merged);
+            await this.resolveAndLoad(serviceOptions);
+            try {
+                const ctx = this.getCtx();
+                const dotenv = (ctx?.dotenv ?? {});
+                const sources = await resolveGetDotenvConfigSources(import.meta.url);
+                const issues = validateEnvAgainstSources(dotenv, sources);
+                if (Array.isArray(issues) && issues.length > 0) {
+                    const logger = (merged
+                        .logger ?? console);
+                    const emit = logger.error ?? logger.log;
+                    issues.forEach((m) => {
+                        emit(m);
+                    });
+                    if (merged.strict) {
+                        process.exit(1);
+                    }
+                }
+            }
+            catch {
+                // Tolerate validation side-effects in non-strict mode
+            }
+        }
+    });
+    return this;
+};
+
+const dbg = (...args) => {
+    if (process.env.GETDOTENV_DEBUG) {
+        // Use stderr to avoid interfering with stdout assertions
+        console.error('[getdotenv:alias]', ...args);
+    }
+};
+const attachParentAlias = (cli, options, _cmd) => {
+    const aliasSpec = typeof options.optionAlias === 'string'
+        ? { flags: options.optionAlias, description: undefined, expand: true }
+        : options.optionAlias;
+    if (!aliasSpec)
+        return;
+    const deriveKey = (flags) => {
+        dbg('install alias option', flags);
+        const long = flags.split(/[ ,|]+/).find((f) => f.startsWith('--')) ?? '--cmd';
+        const name = long.replace(/^--/, '');
+        return name.replace(/-([a-z])/g, (_m, c) => c.toUpperCase());
+    };
+    const aliasKey = deriveKey(aliasSpec.flags);
+    // Expose the option on the parent.
+    const desc = aliasSpec.description ??
+        'alias of cmd subcommand; provide command tokens (variadic)';
+    cli.option(aliasSpec.flags, desc);
+    // Tag the just-added parent option for grouped help rendering.
+    try {
+        const optsArr = cli.options;
+        if (Array.isArray(optsArr) && optsArr.length > 0) {
+            const last = optsArr[optsArr.length - 1];
+            last.__group = 'plugin:cmd';
+        }
+    }
+    catch {
+        /* noop */
+    }
+    // Shared alias executor for either preAction or preSubcommand hooks.
+    // Ensure we only execute once even if both hooks fire in a single parse.
+    let aliasHandled = false;
+    const maybeRunAlias = async (thisCommand) => {
+        dbg('alias:maybe:start');
+        const raw = thisCommand.rawArgs ?? [];
+        const childNames = thisCommand.commands.flatMap((c) => [
+            c.name(),
+            ...c.aliases(),
+        ]);
+        const hasSub = childNames.some((n) => raw.includes(n));
+        // Read alias value from parent opts.
+        const o = thisCommand.opts();
+        const val = o[aliasKey];
+        const provided = typeof val === 'string'
+            ? val.length > 0
+            : Array.isArray(val)
+                ? val.length > 0
+                : false;
+        if (!provided || hasSub) {
+            dbg('alias:maybe:skip', { provided, hasSub });
+            return; // not an alias-only invocation
+        }
+        if (aliasHandled) {
+            dbg('alias:maybe:already-handled');
+            return;
+        }
+        aliasHandled = true;
+        dbg('alias-only invocation detected');
+        // Merge CLI options and resolve dotenv context.
+        const { merged } = resolveCliOptions(o, 
+        // cast through unknown to avoid readonly -> mutable incompatibilities
+        baseRootOptionDefaults, process.env.getDotenvCliOptions);
+        const logger = merged.logger ?? console;
+        const serviceOptions = getDotenvCliOptions2Options(merged);
+        await cli.resolveAndLoad(serviceOptions);
+        // Normalize alias value.
+        const joined = typeof val === 'string'
+            ? val
+            : Array.isArray(val)
+                ? val.map(String).join(' ')
+                : '';
+        const input = aliasSpec.expand === false
+            ? joined
+            : (dotenvExpandFromProcessEnv(joined) ?? joined);
+        dbg('resolved input', { input });
+        const resolved = resolveCommand(merged.scripts, input);
+        const lg = logger;
+        if (merged.debug) {
+            (lg.debug ?? lg.log)('\n*** command ***\n', `'${resolved}'`);
+        }
+        const { logger: _omit, ...envBag } = merged;
+        // Test guard: when running under tests, prefer stdio: 'inherit' to avoid
+        // assertions depending on captured stdio; ignore GETDOTENV_STDIO/capture.
+        const underTests = process.env.GETDOTENV_TEST === '1' ||
+            typeof process.env.VITEST_WORKER_ID === 'string';
+        const forceExit = process.env.GETDOTENV_FORCE_EXIT === '1';
+        const capture = !underTests &&
+            (process.env.GETDOTENV_STDIO === 'pipe' ||
+                Boolean(merged.capture));
+        dbg('run:start', { capture, shell: merged.shell });
+        // Prefer explicit env injection: include resolved dotenv map to avoid leaking
+        // parent process.env secrets when exclusions are set.
+        const ctx = cli.getCtx();
+        const dotenv = (ctx?.dotenv ?? {});
+        // Diagnostics: --trace [keys...]
+        const traceOpt = merged.trace;
+        if (traceOpt) {
+            const parentKeys = Object.keys(process.env);
+            const dotenvKeys = Object.keys(dotenv);
+            const allKeys = Array.from(new Set([...parentKeys, ...dotenvKeys])).sort();
+            const keys = Array.isArray(traceOpt) ? traceOpt : allKeys;
+            const childEnvPreview = {
+                ...process.env,
+                ...dotenv,
+            };
+            for (const k of keys) {
+                const parent = process.env[k];
+                const dot = dotenv[k];
+                const final = childEnvPreview[k];
+                const origin = dot !== undefined
+                    ? 'dotenv'
+                    : parent !== undefined
+                        ? 'parent'
+                        : 'unset';
+                // Build redact options and triple bag without undefined-valued fields
+                const redOpts = {};
+                const redFlag = merged.redact;
+                const redPatterns = merged
+                    .redactPatterns;
+                if (redFlag)
+                    redOpts.redact = true;
+                if (redFlag && Array.isArray(redPatterns))
+                    redOpts.redactPatterns = redPatterns;
+                const tripleBag = {};
+                if (parent !== undefined)
+                    tripleBag.parent = parent;
+                if (dot !== undefined)
+                    tripleBag.dotenv = dot;
+                if (final !== undefined)
+                    tripleBag.final = final;
+                const triple = redactTriple(k, tripleBag, redOpts);
+                process.stderr.write(`[trace] key=${k} origin=${origin} parent=${triple.parent ?? ''} dotenv=${triple.dotenv ?? ''} final=${triple.final ?? ''}\n`);
+                const entOpts = {};
+                const warnEntropy = merged.warnEntropy;
+                const entropyThreshold = merged
+                    .entropyThreshold;
+                const entropyMinLength = merged
+                    .entropyMinLength;
+                const entropyWhitelist = merged
+                    .entropyWhitelist;
+                if (typeof warnEntropy === 'boolean')
+                    entOpts.warnEntropy = warnEntropy;
+                if (typeof entropyThreshold === 'number')
+                    entOpts.entropyThreshold = entropyThreshold;
+                if (typeof entropyMinLength === 'number')
+                    entOpts.entropyMinLength = entropyMinLength;
+                if (Array.isArray(entropyWhitelist))
+                    entOpts.entropyWhitelist = entropyWhitelist;
+                maybeWarnEntropy(k, final, origin, entOpts, (line) => process.stderr.write(line + '\n'));
+            }
+        }
+        let exitCode = Number.NaN;
+        try {
+            // Resolve shell and preserve argv for Node -e snippets under shell-off.
+            const shellSetting = resolveShell(merged.scripts, input, merged.shell);
+            let commandArg = resolved;
+            /**       * Special-case: when shell is OFF and no script alias remap occurred
+             * (resolved === input), treat a Node eval payload as an argv array to
+             * avoid lossy re-tokenization of the code string.
+             *
+             * Examples handled:
+             *   "node -e \"console.log(JSON.stringify(...))\""
+             *   "node --eval 'console.log(...)'"
+             *
+             * We peel exactly one pair of symmetric outer quotes from the code
+             * argument when present; inner quotes remain untouched.
+             */
+            if (shellSetting === false && resolved === input) {
+                // Helper: strip one symmetric outer quote layer
+                const stripOne = (s) => {
+                    if (s.length < 2)
+                        return s;
+                    const a = s.charAt(0);
+                    const b = s.charAt(s.length - 1);
+                    const symmetric = (a === '"' && b === '"') || (a === "'" && b === "'");
+                    return symmetric ? s.slice(1, -1) : s;
+                };
+                // Normalize whole input once for robust matching
+                const normalized = stripOne(input.trim());
+                // First try a lightweight regex on the normalized string
+                const m = /^\s*node\s+(--eval|-e)\s+([\s\S]+)$/i.exec(normalized);
+                if (m && typeof m[1] === 'string' && typeof m[2] === 'string') {
+                    const evalFlag = m[1];
+                    let codeArg = m[2].trim();
+                    codeArg = stripOne(codeArg);
+                    const flag = evalFlag.startsWith('--') ? '--eval' : '-e';
+                    commandArg = ['node', flag, codeArg];
+                }
+                else {
+                    // Fallback: tokenize and detect node -e/--eval form
+                    const parts = tokenize(input);
+                    if (parts.length >= 3) {
+                        // Narrow under noUncheckedIndexedAccess
+                        const p0 = parts[0];
+                        const p1 = parts[1];
+                        if (p0?.toLowerCase() === 'node' &&
+                            (p1 === '-e' || p1 === '--eval')) {
+                            commandArg = parts;
+                        }
+                    }
+                }
+            }
+            exitCode = await runCommand(commandArg, shellSetting, {
+                env: buildSpawnEnv(process.env, {
+                    ...dotenv,
+                    getDotenvCliOptions: JSON.stringify(envBag),
+                }),
+                stdio: capture ? 'pipe' : 'inherit',
+            });
+            dbg('run:done', { exitCode });
+        }
+        catch (err) {
+            const code = typeof err.exitCode === 'number'
+                ? err.exitCode
+                : 1;
+            dbg('run:error', { exitCode: code, error: String(err) });
+            if (!underTests) {
+                dbg('process.exit (error path)', { exitCode: code });
+                process.exit(code);
+            }
+            else {
+                dbg('process.exit suppressed for tests (error path)', {
+                    exitCode: code,
+                });
+            }
+            return;
+        }
+        if (!Number.isNaN(exitCode)) {
+            dbg('process.exit', { exitCode });
+            process.exit(exitCode);
+        }
+        // Fallback: Some environments may not surface a numeric exitCode even on success.
+        // Always terminate alias-only invocations outside tests to avoid hanging the process,
+        // regardless of capture/GETDOTENV_STDIO. Under tests, suppress to keep the runner alive.
+        if (!underTests) {
+            dbg('process.exit (fallback: non-numeric exitCode)', { exitCode: 0 });
+            process.exit(0);
+        }
+        else {
+            dbg('process.exit (fallback suppressed for tests: non-numeric exitCode)', { exitCode: 0 });
+        }
+        // Optional last-resort guard: force an exit on the next tick when enabled.
+        // Intended for diagnosing environments where the process appears to linger
+        // despite reaching the success/error handlers above. Disabled under tests.
+        if (forceExit) {
+            try {
+                if (process.env.GETDOTENV_DEBUG_VERBOSE) {
+                    const getHandles = process._getActiveHandles;
+                    const handles = typeof getHandles === 'function' ? getHandles() : [];
+                    dbg('active handles before forced exit', {
+                        count: Array.isArray(handles) ? handles.length : undefined,
+                    });
+                }
+            }
+            catch {
+                // best-effort only
+            }
+            const code = Number.isNaN(exitCode) ? 0 : exitCode;
+            dbg('process.exit (forced)', { exitCode: code });
+            setImmediate(() => process.exit(code));
+        }
+    };
+    // Execute alias-only invocations whether the root handles the action  // itself (preAction) or Commander routes to a default subcommand (preSubcommand).
+    cli.hook('preAction', async (thisCommand, _actionCommand) => {
+        await maybeRunAlias(thisCommand);
+    });
+    cli.hook('preSubcommand', async (thisCommand) => {
+        await maybeRunAlias(thisCommand);
+    });
+};
+
+/**+ Cmd plugin: executes a command using the current getdotenv CLI context.
+ *
+ * - Joins positional args into a single command string.
+ * - Resolves scripts and shell settings using shared helpers.
+ * - Forwards merged CLI options to subprocesses via
+ *   process.env.getDotenvCliOptions for nested CLI behavior. */
+const cmdPlugin = (options = {}) => definePlugin({
+    id: 'cmd',
+    setup(cli) {
+        const aliasSpec = typeof options.optionAlias === 'string'
+            ? { flags: options.optionAlias}
+            : options.optionAlias;
+        const deriveKey = (flags) => {
+            const long = flags.split(/[ ,|]+/).find((f) => f.startsWith('--')) ?? '--cmd';
+            const name = long.replace(/^--/, '');
+            return name.replace(/-([a-z])/g, (_m, c) => c.toUpperCase());
+        };
+        const aliasKey = aliasSpec ? deriveKey(aliasSpec.flags) : undefined;
+        const cmd = new Command()
+            .name('cmd')
+            .description('Batch execute command according to the --shell option, conflicts with --command option (default subcommand)')
+            .configureHelp({ showGlobalOptions: true })
+            .enablePositionalOptions()
+            .passThroughOptions()
+            .argument('[command...]')
+            .action(async (commandParts, _opts, thisCommand) => {
+            // Commander passes positional tokens as the first action argument
+            const args = Array.isArray(commandParts) ? commandParts : [];
+            // No-op when invoked as the default command with no args.
+            if (args.length === 0)
+                return;
+            const parent = thisCommand.parent;
+            if (!parent)
+                throw new Error('parent command not found'); // Conflict detection: if an alias option is present on parent, do not
+            // also accept positional cmd args.
+            if (aliasKey) {
+                const pv = parent.opts();
+                const ov = pv[aliasKey];
+                if (ov !== undefined) {
+                    const merged = parent.getDotenvCliOptions ?? {};
+                    const logger = merged.logger ?? console;
+                    const lr = logger;
+                    const emit = lr.error ?? lr.log;
+                    emit(`--${aliasKey} option conflicts with cmd subcommand.`);
+                    process.exit(0);
+                }
+            }
+            // Merged CLI options are persisted by the shipped CLI preSubcommand hook.
+            const merged = parent.getDotenvCliOptions ?? {};
+            const logger = merged.logger ?? console;
+            // Join positional args into the command string.
+            const input = args.map(String).join(' ');
+            // Resolve command and shell using shared helpers.
+            const scripts = merged.scripts;
+            const shell = merged.shell;
+            const resolved = resolveCommand(scripts, input);
+            if (merged.debug) {
+                const lg = logger;
+                (lg.debug ?? lg.log)('\n*** command ***\n', `'${resolved}'`);
+            }
+            // Round-trip CLI options for nested getdotenv invocations.
+            // Omit logger (functions are not serializable).
+            const { logger: _omit, ...envBag } = merged;
+            const capture = process.env.GETDOTENV_STDIO === 'pipe' ||
+                Boolean(merged.capture);
+            // Prefer explicit env injection: pass the resolved dotenv map to the child.
+            // This avoids leaking prior secrets from the parent process.env when
+            // exclusions (e.g., --exclude-private) are in effect.
+            const host = cli;
+            const ctx = host.getCtx();
+            const dotenv = (ctx?.dotenv ?? {});
+            // Diagnostics: --trace [keys...] (space-delimited keys if provided; all keys when true)
+            const traceOpt = merged.trace;
+            if (traceOpt) {
+                // Determine keys to trace: all keys (parent ∪ dotenv) or selected.
+                const parentKeys = Object.keys(process.env);
+                const dotenvKeys = Object.keys(dotenv);
+                const allKeys = Array.from(new Set([...parentKeys, ...dotenvKeys])).sort();
+                const keys = Array.isArray(traceOpt) ? traceOpt : allKeys;
+                // Child env preview (as composed below; excluding getDotenvCliOptions)
+                const childEnvPreview = {
+                    ...process.env,
+                    ...dotenv,
+                };
+                for (const k of keys) {
+                    const parent = process.env[k];
+                    const dot = dotenv[k];
+                    const final = childEnvPreview[k];
+                    const origin = dot !== undefined
+                        ? 'dotenv'
+                        : parent !== undefined
+                            ? 'parent'
+                            : 'unset';
+                    // Apply presentation-time redaction (if enabled)
+                    const redFlag = merged.redact;
+                    const redPatterns = merged
+                        .redactPatterns;
+                    const redOpts = {};
+                    if (redFlag)
+                        redOpts.redact = true;
+                    if (redFlag && Array.isArray(redPatterns))
+                        redOpts.redactPatterns = redPatterns;
+                    const tripleBag = {};
+                    if (parent !== undefined)
+                        tripleBag.parent = parent;
+                    if (dot !== undefined)
+                        tripleBag.dotenv = dot;
+                    if (final !== undefined)
+                        tripleBag.final = final;
+                    const triple = redactTriple(k, tripleBag, redOpts);
+                    // Emit concise diagnostic line to stderr.
+                    process.stderr.write(`[trace] key=${k} origin=${origin} parent=${triple.parent ?? ''} dotenv=${triple.dotenv ?? ''} final=${triple.final ?? ''}\n`);
+                    // Optional entropy warning (once-per-key)
+                    const entOpts = {};
+                    const warnEntropy = merged
+                        .warnEntropy;
+                    const entropyThreshold = merged.entropyThreshold;
+                    const entropyMinLength = merged.entropyMinLength;
+                    const entropyWhitelist = merged.entropyWhitelist;
+                    if (typeof warnEntropy === 'boolean')
+                        entOpts.warnEntropy = warnEntropy;
+                    if (typeof entropyThreshold === 'number')
+                        entOpts.entropyThreshold = entropyThreshold;
+                    if (typeof entropyMinLength === 'number')
+                        entOpts.entropyMinLength = entropyMinLength;
+                    if (Array.isArray(entropyWhitelist))
+                        entOpts.entropyWhitelist = entropyWhitelist;
+                    maybeWarnEntropy(k, final, origin, entOpts, (line) => process.stderr.write(line + '\n'));
+                }
+            }
+            const shellSetting = resolveShell(scripts, input, shell);
+            /**
+             * Preserve original argv array when:
+             * - shell is OFF (plain execa), and
+             * - no script alias remap occurred (resolved === input).
+             *
+             * This avoids lossy re-tokenization of code snippets such as:
+             *   node -e "console.log(process.env.APP_SECRET ?? '')"
+             * where quotes may have been stripped by the parent shell and
+             * spaces inside the code must remain a single argument.
+             */
+            const commandArg = shellSetting === false && resolved === input
+                ? args.map(String)
+                : resolved;
+            await runCommand(commandArg, shellSetting, {
+                env: buildSpawnEnv(process.env, {
+                    ...dotenv,
+                    getDotenvCliOptions: JSON.stringify(envBag),
+                }),
+                stdio: capture ? 'pipe' : 'inherit',
+            });
+        });
+        if (options.asDefault)
+            cli.addCommand(cmd, { isDefault: true });
+        else
+            cli.addCommand(cmd);
+        // Parent-attached option alias (optional).
+        if (aliasSpec)
+            attachParentAlias(cli, options);
+    },
+});
+
+export { cmdPlugin };