@karmaniverous/get-dotenv 5.2.5 → 6.0.0-0

package/dist/plugins.cjs

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