@karmaniverous/get-dotenv 4.6.0-0 → 5.0.0-0

package/dist/index.mjs

@@ -1,13 +1,15 @@
-import { Command, Option } from 'commander';
-import { execaCommand } from 'execa';
+import { Option, Command } from 'commander';
 import { globby } from 'globby';
 import { packageDirectory } from 'package-directory';
-import path, { join } from 'path';
+import path, { join, extname } from 'path';
+import { execa, execaCommand } from 'execa';
 import fs from 'fs-extra';
-import url, { fileURLToPath } from 'url';
-import { createHash } from 'crypto';
+import url, { fileURLToPath, pathToFileURL } from 'url';
 import { nanoid } from 'nanoid';
 import { parse } from 'dotenv';
+import { createHash } from 'crypto';
+import YAML from 'yaml';
+import { z } from 'zod';
 
 /**
  * Dotenv expansion utilities.
@@ -145,25 +147,90 @@ const dotenvExpandAll = (values = {}, options = {}) => Object.keys(values).reduc
  */
 const dotenvExpandFromProcessEnv = (value) => dotenvExpand(value, process.env);
 
-const baseGetDotenvCliOptions = {
-    dotenvToken: '.env',
-    loadProcess: true,
-    logger: console,
-    paths: './',
-    pathsDelimiter: ' ',
-    privateToken: 'local',
-    scripts: {
-        'git-status': {
-            cmd: 'git branch --show-current && git status -s -u',
-            shell: true,
-        },
-    },
-    shell: true,
-    vars: '',
-    varsAssignor: '=',
-    varsDelimiter: ' ',
+/**
+ * Attach legacy root flags to a Commander program.
+ * Uses provided defaults to render help labels without coupling to generators.
+ */
+const attachRootOptions = (program, defaults, opts) => {
+    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.
+    {
+        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('--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)');
+    return p;
 };
 
+/**
+ * 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.
@@ -188,6 +255,143 @@ const resolveShell = (scripts, command, shell) => scripts && typeof scripts[comm
     ? (scripts[command].shell ?? false)
     : (shell ?? false);
 
+// 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 = (...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('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('exit (plain)', { exitCode: exit });
+        return typeof exit === 'number' ? exit : Number.NaN;
+    }
+    else {
+        const commandStr = Array.isArray(command) ? command.join(' ') : command;
+        dbg('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('exit (shell)', { exitCode: exit });
+        return typeof exit === 'number' ? exit : Number.NaN;
+    }
+};
+
 const globPaths = async ({ globs, logger, pkgCwd, rootPath, }) => {
     let cwd = process.cwd();
     if (pkgCwd) {
@@ -212,8 +416,10 @@ const globPaths = async ({ globs, logger, pkgCwd, rootPath, }) => {
     return { absRootPath, paths };
 };
 const execShellCommandBatch = async ({ command, getDotenvCliOptions, globs, ignoreErrors, list, logger, pkgCwd, rootPath, shell, }) => {
-    if (!command) {
-        logger.error(`No command provided.`);
+    const capture = process.env.GETDOTENV_STDIO === 'pipe' ||
+        Boolean(getDotenvCliOptions?.capture); // Require a command only when not listing. In list mode, a command is optional.
+    if (!command && !list) {
+        logger.error(`No command provided. Use --command or --list.`);
         process.exit(0);
     }
     const { absRootPath, paths } = await globPaths({
@@ -229,7 +435,13 @@ const execShellCommandBatch = async ({ command, getDotenvCliOptions, globs, igno
     logger.info('');
     const headerRootPath = `ROOT:  ${absRootPath}`;
     const headerGlobs = `GLOBS: ${globs}`;
-    const headerCommand = `CMD:   ${command}`;
+    // Prepare a safe label for the header (avoid undefined in template)
+    const commandLabel = Array.isArray(command)
+        ? command.join(' ')
+        : typeof command === 'string' && command.length > 0
+            ? command
+            : '';
+    const headerCommand = list ? `CMD:   (list only)` : `CMD:   ${commandLabel}`;
     logger.info('*'.repeat(Math.max(headerTitle.length, headerRootPath.length, headerGlobs.length, headerCommand.length)));
     logger.info(headerTitle);
     logger.info('');
@@ -249,17 +461,25 @@ const execShellCommandBatch = async ({ command, getDotenvCliOptions, globs, igno
         logger.info(headerCommand);
         // Execute command.
         try {
-            await execaCommand(command, {
-                cwd: path,
-                env: {
-                    ...process.env,
-                    getDotenvCliOptions: getDotenvCliOptions
-                        ? JSON.stringify(getDotenvCliOptions)
-                        : undefined,
-                },
-                stdio: 'inherit',
-                shell, // already normalized to string | boolean | URL
-            });
+            const hasCmd = (typeof command === 'string' && command.length > 0) ||
+                (Array.isArray(command) && command.length > 0);
+            if (hasCmd) {
+                await runCommand(command, shell, {
+                    cwd: path,
+                    env: {
+                        ...process.env,
+                        getDotenvCliOptions: getDotenvCliOptions
+                            ? JSON.stringify(getDotenvCliOptions)
+                            : undefined,
+                    },
+                    stdio: capture ? 'pipe' : 'inherit',
+                });
+            }
+            else {
+                // Should not occur due to the early guard; retain for type safety.
+                logger.error(`No command provided. Use --command or --list.`);
+                process.exit(0);
+            }
         }
         catch (error) {
             if (!ignoreErrors) {
@@ -379,72 +599,43 @@ const cmdCommand = new Command()
 });
 
 /**
- * Create the root Commander command with all options and subcommands.
- * Pure builder: no side-effects; the caller attaches lifecycle hooks.
+ * Create the root Commander command with legacy root options (via cliCore)
+ * and built-in subcommands. Pure builder: no side-effects; the caller attaches
+ * lifecycle hooks separately.
  */
 const createRootCommand = (opts) => {
-    const { alias, debug, defaultEnv, description, dotenvToken, dynamicPath, env, excludeDynamic, excludeEnv, excludeGlobal, excludePrivate, excludePublic, loadProcess, log, outputPath, paths, pathsDelimiter, pathsDelimiterPattern, privateToken, scripts, shell, varsAssignor, varsAssignorPattern, varsDelimiter, varsDelimiterPattern, } = opts;
-    const excludeAll = !!excludeDynamic &&
-        ((!!excludeEnv && !!excludeGlobal) ||
-            (!!excludePrivate && !!excludePublic));
-    const program = new Command()
-        .name(alias)
-        .description(description)
-        .enablePositionalOptions()
-        .passThroughOptions()
-        .option('-e, --env <string>', `target environment (dotenv-expanded)`, dotenvExpandFromProcessEnv, env)
-        .option('-v, --vars <string>', `extra variables expressed as delimited key-value pairs (dotenv-expanded): ${[
-        ['KEY1', 'VAL1'],
-        ['KEY2', 'VAL2'],
-    ]
-        .map((v) => v.join(varsAssignor ?? '='))
-        .join(varsDelimiter ?? ' ')}`, dotenvExpandFromProcessEnv)
-        .option('-c, --command <string>', 'command executed according to the --shell option, conflicts with cmd subcommand (dotenv-expanded)', dotenvExpandFromProcessEnv)
-        .option('-o, --output-path <string>', 'consolidated output file  (dotenv-expanded)', dotenvExpandFromProcessEnv, outputPath)
-        .addOption(new Option('-s, --shell [string]', (() => {
-        const defaultLabel = shell
-            ? ` (default ${typeof shell === 'boolean' ? 'OS shell' : 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${excludeAll ? ' (default)' : ''}`).conflicts('excludeAllOff'))
-        .addOption(new Option('-A, --exclude-all-off', `exclude all dotenv variables from loading OFF${!excludeAll ? ' (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'))
-        .addOption(new Option('-d, --debug', `debug mode ON${debug ? ' (default)' : ''}`).conflicts('debugOff'))
-        .addOption(new Option('-D, --debug-off', `debug mode OFF${!debug ? ' (default)' : ''}`).conflicts('debug'))
-        .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)
-        .addOption(new Option('--scripts <string>')
-        .default(JSON.stringify(scripts))
-        .hideHelp())
-        .addCommand(batchCommand)
-        .addCommand(cmdCommand, { isDefault: true });
+    const program = new Command().name(opts.alias).description(opts.description);
+    // Attach legacy root flags using shared cliCore builder to keep parity.
+    attachRootOptions(program, opts);
+    // Subcommands
+    program.addCommand(batchCommand).addCommand(cmdCommand, { isDefault: true });
     return program;
 };
 
+// Base root CLI defaults (shared; kept untyped here to avoid cross-layer deps).
+const baseRootOptionDefaults = {
+    dotenvToken: '.env',
+    loadProcess: true,
+    logger: console,
+    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 = (value) => value !== null &&
     typeof value === 'object' &&
@@ -488,7 +679,10 @@ const defaultsDeep = (...layers) => {
 };
 
 // src/GetDotenvOptions.ts
-const getDotenvOptionsFilename = 'getdotenv.config.json';
+const getDotenvOptionsFilename = 'getdotenv.config.json'; /**
+ * A minimal representation of an environment key/value mapping.
+ * Values may be `undefined` to represent "unset".
+ */
 /**
  * Helper to define a dynamic map with strong inference.
  *
@@ -497,8 +691,7 @@ const getDotenvOptionsFilename = 'getdotenv.config.json';
  */
 const defineDynamic = (d) => d;
 /**
- * Converts programmatic CLI options to `getDotenv` options.
- *
+ * Converts programmatic CLI options to `getDotenv` options. *
  * @param cliOptions - CLI options. Defaults to `{}`.
  *
  * @returns `getDotenv` options.
@@ -508,16 +701,18 @@ const getDotenvCliOptions2Options = ({ paths, pathsDelimiter, pathsDelimiterPatt
      * 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`
+     *   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
-    const { debug, scripts, ...restFlags } = rest;
+    // 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 ?? ' ')) : []);
     const kvPairs = (vars
         ? splitBy(vars, varsDelimiter, varsDelimiterPattern).map((v) => v.split(varsAssignorPattern
@@ -525,10 +720,15 @@ const getDotenvCliOptions2Options = ({ paths, pathsDelimiter, pathsDelimiterPatt
             : (varsAssignor ?? '=')))
         : []);
     const parsedVars = Object.fromEntries(kvPairs);
+    // Preserve exactOptionalPropertyTypes: only include keys when defined.
     return {
-        ...restFlags,
-        paths: splitBy(paths, pathsDelimiter, pathsDelimiterPattern),
-        vars: parsedVars,
+        ...restObj,
+        ...(paths !== undefined
+            ? {
+                paths: splitBy(paths, pathsDelimiter, pathsDelimiterPattern),
+            }
+            : {}),
+        ...(vars !== undefined ? { vars: parsedVars } : {}),
     };
 };
 const resolveGetDotenvOptions = async (customOptions) => {
@@ -601,6 +801,169 @@ const resolveGetDotenvCliGenerateOptions = async ({ importMetaUrl, ...customOpti
     return merged;
 };
 
+/**
+ * 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, 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));
+    // Normalize shell for predictability: explicit default shell per OS.
+    const defaultShell = process.platform === 'win32' ? 'powershell.exe' : '/bin/bash';
+    let resolvedShell = merged.shell;
+    if (shellOff)
+        resolvedShell = false;
+    else if (resolvedShell === true || resolvedShell === undefined) {
+        resolvedShell = defaultShell;
+    }
+    else if (typeof resolvedShell !== 'string' &&
+        typeof defaults.shell === 'string') {
+        resolvedShell = defaults.shell;
+    }
+    merged.shell = resolvedShell;
+    const cmd = typeof command === 'string' ? command : undefined;
+    return cmd !== undefined ? { merged, command: cmd } : { merged };
+};
+
+const 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.
  *
@@ -616,65 +979,95 @@ const readDotenv = async (path) => {
     }
 };
 
-const importDefault = async (fileUrl) => {
+const importDefault$1 = async (fileUrl) => {
     const mod = (await import(fileUrl));
     return mod.default;
 };
-/**
- * @internal Compute a short hash from path + mtime for cache filenames.
- */
 const cacheHash = (absPath, mtimeMs) => createHash('sha1')
     .update(absPath)
     .update(String(mtimeMs))
     .digest('hex')
     .slice(0, 12);
 /**
- * @internal Load a dynamic module from path. Supports .js/.mjs/.ts/.tsx:
- * - .js/.mjs: direct import
- * - .ts/.tsx: try direct import (in case a TS loader is active), otherwise:
- *   - esbuild (if present): bundle to a temp ESM file and import it
- *   - fallback: typescript.transpileModule (single-file), then import temp file
+ * Remove older compiled cache files for a given source base name, keeping
+ * at most `keep` most-recent files. Errors are ignored by design.
  */
-const loadDynamicFromPath = async (absPath) => {
-    if (!(await fs.exists(absPath)))
-        return undefined;
+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 (ext !== '.ts' && ext !== '.tsx') {
-        return importDefault(fileUrl);
+    if (!['.ts', '.mts', '.cts', '.tsx'].includes(ext)) {
+        return importDefault$1(fileUrl);
     }
-    // Try direct import (in case user started Node with a TS loader).
+    // Try direct import first (TS loader active)
     try {
-        const dyn = await importDefault(fileUrl);
+        const dyn = await importDefault$1(fileUrl);
         if (dyn)
             return dyn;
     }
     catch {
-        // ignore; fall through to compile
+        /* fall through */
     }
     const stat = await fs.stat(absPath);
     const hash = cacheHash(absPath, stat.mtimeMs);
-    const cacheDir = path.resolve('.tsbuild', 'getdotenv-dynamic');
+    const cacheDir = path.resolve('.tsbuild', cacheDirName);
+    await fs.ensureDir(cacheDir);
     const cacheFile = path.join(cacheDir, `${path.basename(absPath)}.${hash}.mjs`);
-    // Try esbuild first
+    // Try esbuild
     try {
         const esbuild = (await import('esbuild'));
-        await fs.ensureDir(cacheDir);
         await esbuild.build({
             entryPoints: [absPath],
             bundle: true,
             platform: 'node',
             format: 'esm',
-            target: 'node22',
+            target: 'node20',
             outfile: cacheFile,
             sourcemap: false,
             logLevel: 'silent',
         });
-        return await importDefault(url.pathToFileURL(cacheFile).toString());
+        const result = await importDefault$1(url.pathToFileURL(cacheFile).toString());
+        // Best-effort: trim older cache files for this source.
+        await cleanupOldCacheFiles(cacheDir, path.basename(absPath));
+        return result;
     }
     catch {
-        // no esbuild; fall back to TS transpile for simple modules
+        /* fall through to TS transpile */
     }
+    // TypeScript transpile fallback
     try {
         const ts = (await import('typescript'));
         const code = await fs.readFile(absPath, 'utf-8');
@@ -684,16 +1077,19 @@ const loadDynamicFromPath = async (absPath) => {
                 target: 'ES2022',
                 moduleResolution: 'NodeNext',
             },
-        });
-        await fs.ensureDir(cacheDir);
-        await fs.writeFile(cacheFile, out.outputText, 'utf-8');
-        return await importDefault(url.pathToFileURL(cacheFile).toString());
+        }).outputText;
+        await fs.writeFile(cacheFile, out, 'utf-8');
+        const result = await importDefault$1(url.pathToFileURL(cacheFile).toString());
+        // Best-effort: trim older cache files for this source.
+        await cleanupOldCacheFiles(cacheDir, path.basename(absPath));
+        return result;
     }
     catch {
-        throw new Error(`Unable to load dynamic TypeScript file: ${absPath}. ` +
-            `Install 'esbuild' (devDependency) to enable TypeScript dynamic modules.`);
+        // 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>]`
  *
@@ -778,7 +1174,16 @@ const getDotenv = async (options = {}) => {
         }
         else if (dynamicPath) {
             const absDynamicPath = path.resolve(dynamicPath);
-            dynamic = await loadDynamicFromPath(absDynamicPath);
+            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 {
@@ -817,72 +1222,320 @@ const getDotenv = async (options = {}) => {
 };
 
 /**
- * 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
- * ```
+ * 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 this step (JSON/YAML only), any defined `dynamic` will be rejected by the loader.
  */
-const resolveExclusion = (exclude, excludeOff, defaultValue) => exclude ? true : excludeOff ? undefined : defaultValue ? true : undefined;
+// 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
+    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 = 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(fileUrl);
+    }
+    // Try direct import first in case a TS loader is active.
+    try {
+        const val = await importDefault(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(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(pathToFileURL(outfile).toString());
+    }
+    catch {
+        throw new Error(`Unable to load JS/TS config: ${absPath}. Install 'esbuild' for robust bundling or ensure a TS loader.`);
+    }
+};
 /**
- * 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.
+ * 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.
  *
- * @example
- * resolveExclusionAll(undefined, undefined, false, true, undefined) =\> true
+ * 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 in JSON/YAML; allow in JS/TS
+    if (!isJsOrTs(filePath) && parsed.data.dynamic !== undefined) {
+        throw new Error(`Config ${filePath} specifies "dynamic"; JSON/YAML configs cannot include dynamic in this step. Use JS/TS config.`);
+    }
+    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 resolveExclusionAll = (exclude, excludeOff, defaultValue, excludeAll, excludeAllOff) => excludeAll && !excludeOff
-    ? true
-    : excludeAllOff && !exclude
-        ? undefined
-        : defaultValue
-            ? true
-            : undefined;
+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;
+};
+
 /**
- * exactOptionalPropertyTypes-safe setter for optional boolean flags:
- * delete when undefined; assign when defined — without requiring an index signature on T.
+ * Resolve dotenv values using the config-loader/overlay path (always-on in
+ * host/generator flows; no-op when no config files are present).
  *
- * @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}.
+ * Order:
+ * 1) Compute base from files only (exclude dynamic; ignore programmatic vars).
+ * 2) Discover packaged + project config sources and overlay onto base.
+ * 3) Apply dynamics in order:
+ *    programmatic dynamic \> config dynamic (packaged → project public → project local)
+ *    \> file dynamicPath. * 4) Optionally write outputPath, log, and merge into process.env.
  */
-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;
+const resolveDotenvWithConfigLoader = async (validated) => {
+    // 1) Base from files, 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 (packaged via this module's import.meta.url)
+    const sources = await resolveGetDotenvConfigSources(import.meta.url);
+    const dotenv = 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
+    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);
+    return dotenv;
 };
 
+/**
+ * Omit a "logger" key from an options object in a typed manner.
+ */
+const omitLogger = (obj) => {
+    const { logger: _omitted, ...rest } = obj;
+    return rest;
+};
 /**
  * Build the Commander preSubcommand hook using the provided context.
- *
- * Responsibilities:
- * - Merge parent CLI options with current invocation (parent \< current).
- * - Resolve tri-state flags, including `--exclude-all` overrides.
+ * * Responsibilities:
+ * - Merge parent CLI options with current invocation (parent \< current). * - Resolve tri-state flags, including `--exclude-all` overrides.
  * - Normalize the shell setting to a concrete value (string | boolean).
  * - Persist merged options on the command instance and pass to subcommands.
  * - Execute {@link getDotenv} and optional post-hook.
@@ -892,95 +1545,52 @@ const setOptionalFlag = (obj, key, value) => {
  * @returns An async hook suitable for Commander’s `preSubcommand`.
  *
  * @example `program.hook('preSubcommand', makePreSubcommandHook(ctx));`
- */ const makePreSubcommandHook = ({ logger, preHook, postHook, defaults }) => async (thisCommand) => {
-    // Get parent command GetDotenvCliOptions.
-    const parentGetDotenvCliOptions = process.env.getDotenvCliOptions
-        ? JSON.parse(process.env.getDotenvCliOptions)
-        : undefined;
-    // Get raw CLI options from commander.
-    const rawCliOptions = thisCommand.opts();
-    // Extract current GetDotenvCliOptions from raw CLI options.
-    const { command, debugOff, excludeAll, excludeAllOff, excludeDynamicOff, excludeEnvOff, excludeGlobalOff, excludePrivateOff, excludePublicOff, loadProcessOff, logOff, scripts, shellOff, ...rawCliOptionsRest } = rawCliOptions;
-    const currentGetDotenvCliOptions = rawCliOptionsRest;
-    if (scripts)
-        currentGetDotenvCliOptions.scripts = JSON.parse(scripts);
-    // Merge current & parent GetDotenvCliOptions (parent < current).
-    const mergedGetDotenvCliOptions = defaultsDeep((parentGetDotenvCliOptions ?? {}), currentGetDotenvCliOptions);
-    // Resolve flags using defaults + current + exclude-all toggles.
-    setOptionalFlag(mergedGetDotenvCliOptions, 'debug', resolveExclusion(mergedGetDotenvCliOptions.debug, debugOff, defaults.debug));
-    setOptionalFlag(mergedGetDotenvCliOptions, 'excludeDynamic', resolveExclusionAll(mergedGetDotenvCliOptions.excludeDynamic, excludeDynamicOff, defaults.excludeDynamic, excludeAll, excludeAllOff));
-    setOptionalFlag(mergedGetDotenvCliOptions, 'excludeEnv', resolveExclusionAll(mergedGetDotenvCliOptions.excludeEnv, excludeEnvOff, defaults.excludeEnv, excludeAll, excludeAllOff));
-    setOptionalFlag(mergedGetDotenvCliOptions, 'excludeGlobal', resolveExclusionAll(mergedGetDotenvCliOptions.excludeGlobal, excludeGlobalOff, defaults.excludeGlobal, excludeAll, excludeAllOff));
-    setOptionalFlag(mergedGetDotenvCliOptions, 'excludePrivate', resolveExclusionAll(mergedGetDotenvCliOptions.excludePrivate, excludePrivateOff, defaults.excludePrivate, excludeAll, excludeAllOff));
-    setOptionalFlag(mergedGetDotenvCliOptions, 'excludePublic', resolveExclusionAll(mergedGetDotenvCliOptions.excludePublic, excludePublicOff, defaults.excludePublic, excludeAll, excludeAllOff));
-    setOptionalFlag(mergedGetDotenvCliOptions, 'log', resolveExclusion(mergedGetDotenvCliOptions.log, logOff, defaults.log));
-    setOptionalFlag(mergedGetDotenvCliOptions, 'loadProcess', resolveExclusion(mergedGetDotenvCliOptions.loadProcess, loadProcessOff, defaults.loadProcess));
-    // Normalize shell for predictability: explicit default shell per OS.
-    const defaultShell = process.platform === 'win32' ? 'powershell.exe' : '/bin/bash';
-    let resolvedShell = mergedGetDotenvCliOptions.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;
-    }
-    mergedGetDotenvCliOptions.shell = resolvedShell;
-    if (mergedGetDotenvCliOptions.debug && parentGetDotenvCliOptions) {
-        logger.debug('\n*** parent command GetDotenvCliOptions ***\n', parentGetDotenvCliOptions);
-    }
-    if (mergedGetDotenvCliOptions.debug)
-        logger.debug('\n*** current command raw options ***\n', rawCliOptions);
-    if (mergedGetDotenvCliOptions.debug)
-        logger.debug('\n*** merged GetDotenvCliOptions ***\n', {
-            mergedGetDotenvCliOptions,
-        });
-    // Execute pre-hook.
-    if (preHook) {
-        await preHook(mergedGetDotenvCliOptions);
-        if (mergedGetDotenvCliOptions.debug)
-            logger.debug('\n*** GetDotenvCliOptions after pre-hook ***\n', mergedGetDotenvCliOptions);
-    }
-    // Persist GetDotenvCliOptions in command for subcommand access.
-    thisCommand.getDotenvCliOptions = mergedGetDotenvCliOptions;
-    // Execute getdotenv.
-    const dotenv = await getDotenv(getDotenvCliOptions2Options(mergedGetDotenvCliOptions));
-    if (mergedGetDotenvCliOptions.debug)
-        logger.debug('\n*** getDotenv output ***\n', dotenv);
-    // Execute post-hook.
-    if (postHook)
-        await postHook(dotenv);
-    // Execute command.
-    const args = thisCommand.args ?? [];
-    const isCommand = typeof command === 'string' && command.length > 0;
-    if (isCommand && args.length > 0) {
-        const lr = logger;
-        (lr.error ?? lr.log)(`--command option conflicts with cmd subcommand.`);
-        process.exit(0);
-    }
-    if (typeof command === 'string' && command.length > 0) {
-        const cmd = resolveCommand(mergedGetDotenvCliOptions.scripts, command);
-        if (mergedGetDotenvCliOptions.debug)
-            logger.debug('\n*** command ***\n', cmd);
-        const envSafe = {
-            ...mergedGetDotenvCliOptions,
-        };
-        delete envSafe.logger;
-        await execaCommand(cmd, {
-            env: {
-                ...process.env,
-                getDotenvCliOptions: JSON.stringify(envSafe),
-            },
-            shell: resolveShell(mergedGetDotenvCliOptions.scripts, command, mergedGetDotenvCliOptions.shell),
-            stdio: 'inherit',
-        });
-    }
+ */
+const makePreSubcommandHook = ({ logger, preHook, postHook, defaults, }) => {
+    return async (thisCommand) => {
+        // Get raw CLI options from commander.
+        const rawCliOptions = thisCommand.opts();
+        const { merged: mergedGetDotenvCliOptions, command: commandOpt } = resolveCliOptions(rawCliOptions, defaults, process.env.getDotenvCliOptions);
+        // Optional debug logging retained via mergedGetDotenvCliOptions.debug if desired.    // Execute pre-hook.
+        if (preHook) {
+            await preHook(mergedGetDotenvCliOptions);
+            if (mergedGetDotenvCliOptions.debug)
+                logger.debug('\n*** GetDotenvCliOptions after pre-hook ***\n', mergedGetDotenvCliOptions);
+        }
+        // Persist GetDotenvCliOptions in command for subcommand access.
+        thisCommand.getDotenvCliOptions =
+            mergedGetDotenvCliOptions;
+        // Execute getdotenv via always-on config loader/overlay path.
+        const serviceOptions = getDotenvCliOptions2Options(mergedGetDotenvCliOptions);
+        const dotenv = await resolveDotenvWithConfigLoader(serviceOptions);
+        // Execute post-hook.
+        if (postHook)
+            await postHook(dotenv); // Execute command.
+        const args = thisCommand.args ?? [];
+        const isCommand = typeof commandOpt === 'string' && commandOpt.length > 0;
+        if (isCommand && args.length > 0) {
+            const lr = logger;
+            (lr.error ?? lr.log)(`--command option conflicts with cmd subcommand.`);
+            process.exit(0);
+        }
+        if (typeof commandOpt === 'string' && commandOpt.length > 0) {
+            const cmd = resolveCommand(mergedGetDotenvCliOptions.scripts, commandOpt);
+            if (mergedGetDotenvCliOptions.debug)
+                logger.debug('\n*** command ***\n', cmd);
+            // Build a logger-free bag for env round-trip.
+            const envSafe = omitLogger(mergedGetDotenvCliOptions);
+            await execaCommand(cmd, {
+                env: { ...process.env, getDotenvCliOptions: JSON.stringify(envSafe) },
+                shell: resolveShell(mergedGetDotenvCliOptions.scripts, commandOpt, mergedGetDotenvCliOptions.shell),
+                stdio: 'inherit',
+            });
+        }
+    };
 };
 
 /**
- * Generate a Commander CLI Command for get-dotenv. * Orchestration only: delegates building and lifecycle hooks.
+ * Generate a Commander CLI Command for get-dotenv.
+ * Orchestration only: delegates building and lifecycle hooks.
  */
 const generateGetDotenvCli = async (customOptions) => {
     const options = await resolveGetDotenvCliGenerateOptions(customOptions);