@karmaniverous/get-dotenv 6.0.0-1 → 6.0.0

package/dist/cliHost.mjs

@@ -1,41 +1,125 @@
 import { z } from 'zod';
 export { z } from 'zod';
+import path, { join, extname } from 'path';
 import fs from 'fs-extra';
 import { packageDirectory } from 'package-directory';
-import path, { join, extname } from 'path';
-import url, { fileURLToPath, pathToFileURL } from 'url';
+import url, { fileURLToPath } from 'url';
 import YAML from 'yaml';
-import { Option, Command } from 'commander';
+import { createHash } from 'crypto';
 import { nanoid } from 'nanoid';
 import { parse } from 'dotenv';
-import { createHash } from 'crypto';
+import { execa, execaCommand } from 'execa';
+import { Option, Command } from '@commander-js/extra-typings';
 
-// 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)
-};
+/**
+ * Zod schemas for programmatic GetDotenv options.
+ *
+ * Canonical source of truth for options shape. Public types are derived
+ * from these schemas (see consumers via z.output\<\>).
+ */
+/**
+ * Minimal process env representation used by options and helpers.
+ * Values may be `undefined` to indicate "unset".
+ */
+const processEnvSchema = z.record(z.string(), z.string().optional());
+// RAW: all fields optional — undefined means "inherit" from lower layers.
+const getDotenvOptionsSchemaRaw = z.object({
+    defaultEnv: z.string().optional(),
+    dotenvToken: z.string().optional(),
+    dynamicPath: z.string().optional(),
+    // Dynamic map is intentionally wide for now; refine once sources are normalized.
+    dynamic: z.record(z.string(), z.unknown()).optional(),
+    env: z.string().optional(),
+    excludeDynamic: z.boolean().optional(),
+    excludeEnv: z.boolean().optional(),
+    excludeGlobal: z.boolean().optional(),
+    excludePrivate: z.boolean().optional(),
+    excludePublic: z.boolean().optional(),
+    loadProcess: z.boolean().optional(),
+    log: z.boolean().optional(),
+    logger: z.unknown().default(console),
+    outputPath: z.string().optional(),
+    paths: z.array(z.string()).optional(),
+    privateToken: z.string().optional(),
+    vars: processEnvSchema.optional(),
+});
+/**
+ * Resolved programmatic options schema (post-inheritance).
+ * For now, this mirrors the RAW schema; future stages may materialize defaults
+ * and narrow shapes as resolution is wired into the host.
+ */
+const getDotenvOptionsSchemaResolved = getDotenvOptionsSchemaRaw;
+
+/**
+ * Zod schemas for CLI-facing GetDotenv options (raw/resolved stubs).
+ *
+ * RAW allows stringly inputs (paths/vars + splitters). RESOLVED will later
+ * reflect normalized types (paths: string[], vars: ProcessEnv), applied in the
+ * CLI resolution pipeline.
+ */
+const getDotenvCliOptionsSchemaRaw = getDotenvOptionsSchemaRaw.extend({
+    // CLI-specific fields (stringly inputs before preprocessing)
+    debug: z.boolean().optional(),
+    strict: z.boolean().optional(),
+    capture: z.boolean().optional(),
+    trace: z.union([z.boolean(), z.array(z.string())]).optional(),
+    redact: z.boolean().optional(),
+    warnEntropy: z.boolean().optional(),
+    entropyThreshold: z.number().optional(),
+    entropyMinLength: z.number().optional(),
+    entropyWhitelist: z.array(z.string()).optional(),
+    redactPatterns: z.array(z.string()).optional(),
+    paths: z.string().optional(),
+    pathsDelimiter: z.string().optional(),
+    pathsDelimiterPattern: z.string().optional(),
+    scripts: z.record(z.string(), z.unknown()).optional(),
+    shell: z.union([z.boolean(), z.string()]).optional(),
+    vars: z.string().optional(),
+    varsAssignor: z.string().optional(),
+    varsAssignorPattern: z.string().optional(),
+    varsDelimiter: z.string().optional(),
+    varsDelimiterPattern: z.string().optional(),
+});
+
+const visibilityMap = z.record(z.string(), z.boolean());
+/**
+ * Zod schemas for configuration files discovered by the new loader.
+ *
+ * Notes:
+ * - RAW: all fields optional; only allowed top-level keys are:
+ *   - rootOptionDefaults, rootOptionVisibility
+ *   - scripts, vars, envVars
+ *   - dynamic (JS/TS only), schema (JS/TS only)
+ *   - plugins, requiredKeys
+ * - RESOLVED: mirrors RAW (no path normalization).
+ * - For JSON/YAML configs, the loader rejects "dynamic" and "schema" (JS/TS only).
+ */
+// String-only env value map
+const stringMap = z.record(z.string(), z.string());
+const envStringMap = z.record(z.string(), stringMap);
+/**
+ * Raw configuration schema for get‑dotenv config files (JSON/YAML/JS/TS).
+ * Validates allowed top‑level keys without performing path normalization.
+ */
+const getDotenvConfigSchemaRaw = z.object({
+    rootOptionDefaults: getDotenvCliOptionsSchemaRaw.optional(),
+    rootOptionVisibility: visibilityMap.optional(),
+    scripts: z.record(z.string(), z.unknown()).optional(), // Scripts validation left wide; generator validates elsewhere
+    requiredKeys: z.array(z.string()).optional(),
+    schema: z.unknown().optional(), // JS/TS-only; loader rejects in JSON/YAML
+    vars: stringMap.optional(), // public, global
+    envVars: envStringMap.optional(), // public, per-env
+    // Dynamic in config (JS/TS only). JSON/YAML loader will reject if set.
+    dynamic: z.unknown().optional(),
+    // Per-plugin config bag; validated by plugins/host when used.
+    plugins: z.record(z.string(), z.unknown()).optional(),
+});
+/**
+ * Resolved configuration schema which preserves the raw shape while narrowing
+ * the output to {@link GetDotenvConfigResolved}. Consumers get a strongly typed
+ * object, while the underlying validation remains Zod‑driven.
+ */
+const getDotenvConfigSchemaResolved = getDotenvConfigSchemaRaw.transform((raw) => raw);
 
 /** @internal */
 const isPlainObject$1 = (value) => value !== null &&
@@ -66,167 +150,404 @@ function defaultsDeep(...layers) {
 }
 
 /**
- * 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).
+ * Serialize a dotenv record to a file with minimal quoting (multiline values are quoted).
+ * Future-proofs for ordering/sorting changes (currently insertion order).
+ */
+async function writeDotenvFile(filename, data) {
+    // Serialize: key=value with quotes only for multiline values.
+    const body = Object.keys(data).reduce((acc, key) => {
+        const v = data[key] ?? '';
+        const val = v.includes('\n') ? `"${v}"` : v;
+        return `${acc}${key}=${val}\n`;
+    }, '');
+    await fs.writeFile(filename, body, { encoding: 'utf-8' });
+}
+
+/**
+ * Dotenv expansion utilities.
  *
- * @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).
+ * This module implements recursive expansion of environment-variable
+ * references in strings and records. It supports both whitespace and
+ * bracket syntaxes with optional defaults:
  *
- * @example
- * ```ts
- * resolveExclusion(undefined, undefined, true); // => true
- * ```
+ * - Whitespace: `$VAR[:default]`
+ * - Bracketed: `${VAR[:default]}`
+ *
+ * Escaped dollar signs (`\$`) are preserved.
+ * Unknown variables resolve to empty string unless a default is provided.
  */
-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).
+ * 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 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.
+ * @param value - The string to expand.
+ * @param ref - The reference object to use for variable expansion.
+ * @returns The expanded string.
  *
  * @example
- * resolveExclusionAll(undefined, undefined, false, true, undefined) =\> true
+ * ```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 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;
-})();
+const dotenvExpand = (value, ref = process.env) => {
+    const result = interpolate(value, ref);
+    return result ? result.replace(/\\\$/g, '$') : undefined;
+};
 /**
- * exactOptionalPropertyTypes-safe setter for optional boolean flags:
- * delete when undefined; assign when defined — without requiring an index signature on T.
+ * 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.
  *
- * @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.
+ * @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
- * Writes through a local `Record<string, unknown>` view to avoid requiring an index signature on {@link T}.
+ * 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 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.
+function dotenvExpandAll(values, options = {}) {
+    const { ref = process.env, progressive = false, } = options;
+    const out = Object.keys(values).reduce((acc, key) => {
+        acc[key] = dotenvExpand(values[key], {
+            ...ref,
+            ...(progressive ? acc : {}),
+        });
+        return acc;
+    }, {});
+    // Key-preserving return with a permissive index signature to allow later additions.
+    return out;
+}
+/**
+ * Recursively expands environment variables in a string using `process.env` as
+ * the expansion reference. Variables may be presented with optional default as
+ * `$VAR[:default]` or `${VAR[:default]}`. Unknown variables will expand to an
+ * empty string.
+ *
+ * @param value - The string to expand.
+ * @returns The expanded string.
+ *
+ * @example
+ * ```ts
+ * process.env.FOO = 'bar';
+ * dotenvExpandFromProcessEnv('Hello $FOO'); // "Hello bar"
+ * ```
  */
-const resolveCliOptions = (rawCliOptions, defaults, parentJson) => {
-    const parent = typeof parentJson === 'string' && parentJson.length > 0
-        ? JSON.parse(parentJson)
-        : undefined;
-    const { command, debugOff, excludeAll, excludeAllOff, excludeDynamicOff, excludeEnvOff, excludeGlobalOff, excludePrivateOff, excludePublicOff, loadProcessOff, logOff, entropyWarn, entropyWarnOff, scripts, shellOff, ...rest } = rawCliOptions;
-    const current = { ...rest };
-    if (typeof scripts === 'string') {
-        try {
-            current.scripts = JSON.parse(scripts);
-        }
-        catch {
-            // ignore parse errors; leave scripts undefined
+const dotenvExpandFromProcessEnv = (value) => dotenvExpand(value, process.env);
+
+/** @internal */
+const isPlainObject = (v) => v !== null &&
+    typeof v === 'object' &&
+    !Array.isArray(v) &&
+    Object.getPrototypeOf(v) === Object.prototype;
+/**
+ * Deeply interpolate string leaves against envRef.
+ * Arrays are not recursed into; they are returned unchanged.
+ *
+ * @typeParam T - Shape of the input value.
+ * @param value - Input value (object/array/primitive).
+ * @param envRef - Reference environment for interpolation.
+ * @returns A new value with string leaves interpolated.
+ */
+const interpolateDeep = (value, envRef) => {
+    // Strings: expand and return
+    if (typeof value === 'string') {
+        const out = dotenvExpand(value, envRef);
+        // dotenvExpand returns string | undefined; preserve original on undefined
+        return (out ?? value);
+    }
+    // Arrays: return as-is (no recursion)
+    if (Array.isArray(value)) {
+        return value;
+    }
+    // Plain objects: shallow clone and recurse into values
+    if (isPlainObject(value)) {
+        const src = value;
+        const out = {};
+        for (const [k, v] of Object.entries(src)) {
+            // Recurse for strings/objects; keep arrays as-is; preserve other scalars
+            if (typeof v === 'string')
+                out[k] = dotenvExpand(v, envRef) ?? v;
+            else if (Array.isArray(v))
+                out[k] = v;
+            else if (isPlainObject(v))
+                out[k] = interpolateDeep(v, envRef);
+            else
+                out[k] = v;
         }
+        return out;
     }
-    const merged = defaultsDeep({}, defaults, parent ?? {}, current);
-    const d = defaults;
-    setOptionalFlag(merged, 'debug', resolveExclusion(merged.debug, debugOff, d.debug));
-    setOptionalFlag(merged, 'excludeDynamic', resolveExclusionAll(merged.excludeDynamic, excludeDynamicOff, d.excludeDynamic, excludeAll, excludeAllOff));
-    setOptionalFlag(merged, 'excludeEnv', resolveExclusionAll(merged.excludeEnv, excludeEnvOff, d.excludeEnv, excludeAll, excludeAllOff));
-    setOptionalFlag(merged, 'excludeGlobal', resolveExclusionAll(merged.excludeGlobal, excludeGlobalOff, d.excludeGlobal, excludeAll, excludeAllOff));
-    setOptionalFlag(merged, 'excludePrivate', resolveExclusionAll(merged.excludePrivate, excludePrivateOff, d.excludePrivate, excludeAll, excludeAllOff));
-    setOptionalFlag(merged, 'excludePublic', resolveExclusionAll(merged.excludePublic, excludePublicOff, d.excludePublic, excludeAll, excludeAllOff));
-    setOptionalFlag(merged, 'log', resolveExclusion(merged.log, logOff, d.log));
-    setOptionalFlag(merged, 'loadProcess', resolveExclusion(merged.loadProcess, loadProcessOff, d.loadProcess));
-    // warnEntropy (tri-state)
-    setOptionalFlag(merged, 'warnEntropy', resolveExclusion(merged.warnEntropy, entropyWarnOff, d.warnEntropy));
-    // Normalize shell for predictability: explicit default shell per OS.
-    const defaultShell = process.platform === 'win32' ? 'powershell.exe' : '/bin/bash';
-    let resolvedShell = merged.shell;
-    if (shellOff)
-        resolvedShell = false;
-    else if (resolvedShell === true || resolvedShell === undefined) {
-        resolvedShell = defaultShell;
+    // Other primitives/types: return as-is
+    return value;
+};
+
+const importDefault = async (fileUrl) => {
+    const mod = (await import(fileUrl));
+    return mod.default;
+};
+const cacheHash = (absPath, mtimeMs) => createHash('sha1')
+    .update(absPath)
+    .update(String(mtimeMs))
+    .digest('hex')
+    .slice(0, 12);
+/**
+ * Remove older compiled cache files for a given source base name, keeping
+ * at most `keep` most-recent files. Errors are ignored by design.
+ */
+const cleanupOldCacheFiles = async (cacheDir, baseName, keep = Math.max(1, Number.parseInt(process.env.GETDOTENV_CACHE_KEEP ?? '2'))) => {
+    try {
+        const entries = await fs.readdir(cacheDir);
+        const mine = entries
+            .filter((f) => f.startsWith(`${baseName}.`) && f.endsWith('.mjs'))
+            .map((f) => path.join(cacheDir, f));
+        if (mine.length <= keep)
+            return;
+        const stats = await Promise.all(mine.map(async (p) => ({ p, mtimeMs: (await fs.stat(p)).mtimeMs })));
+        stats.sort((a, b) => b.mtimeMs - a.mtimeMs);
+        const toDelete = stats.slice(keep).map((s) => s.p);
+        await Promise.all(toDelete.map(async (p) => {
+            try {
+                await fs.remove(p);
+            }
+            catch {
+                // best-effort cleanup
+            }
+        }));
     }
-    else if (typeof resolvedShell !== 'string' &&
-        typeof defaults.shell === 'string') {
-        resolvedShell = defaults.shell;
+    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.`);
     }
-    merged.shell = resolvedShell;
-    const cmd = typeof command === 'string' ? command : undefined;
-    return cmd !== undefined ? { merged, command: cmd } : { merged };
 };
 
+/** src/util/omitUndefined.ts
+ * Helpers to drop undefined-valued properties in a typed-friendly way.
+ */
 /**
- * Zod schemas for configuration files discovered by the new loader.
+ * Omit keys whose runtime value is undefined from a shallow object.
+ * Returns a Partial with non-undefined value types preserved.
+ */
+function omitUndefined(obj) {
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+        if (v !== undefined)
+            out[k] = v;
+    }
+    return out;
+}
+/**
+ * Specialized helper for env-like maps: drop undefined and return string-only.
+ */
+function omitUndefinedRecord(obj) {
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+        if (v !== undefined)
+            out[k] = v;
+    }
+    return out;
+}
+
+/**
+ * Minimal tokenizer for shell-off execution.
+ * Splits by whitespace while preserving quoted segments (single or double quotes).
  *
- * 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).
+ * @param command - The command string to tokenize.
+ * @param opts - Tokenization options (e.g. quote handling).
  */
-// String-only env value map
-const stringMap = z.record(z.string(), z.string());
-const envStringMap = z.record(z.string(), stringMap);
-// Allow string[] or single string for "paths" in RAW; normalize later.
-const rawPathsSchema = z.union([z.array(z.string()), z.string()]).optional();
-const getDotenvConfigSchemaRaw = z.object({
-    dotenvToken: z.string().optional(),
-    privateToken: z.string().optional(),
-    paths: rawPathsSchema,
-    loadProcess: z.boolean().optional(),
-    log: z.boolean().optional(),
-    shell: z.union([z.string(), z.boolean()]).optional(),
-    scripts: z.record(z.string(), z.unknown()).optional(), // Scripts validation left wide; generator validates elsewhere
-    requiredKeys: z.array(z.string()).optional(),
-    schema: z.unknown().optional(), // JS/TS-only; loader rejects in JSON/YAML
-    vars: stringMap.optional(), // public, global
-    envVars: envStringMap.optional(), // public, per-env
-    // Dynamic in config (JS/TS only). JSON/YAML loader will reject if set.
-    dynamic: z.unknown().optional(),
-    // Per-plugin config bag; validated by plugins/host when used.
-    plugins: z.record(z.string(), z.unknown()).optional(),
-});
-// Normalize paths to string[]
-const normalizePaths = (p) => p === undefined ? undefined : Array.isArray(p) ? p : [p];
-const getDotenvConfigSchemaResolved = getDotenvConfigSchemaRaw.transform((raw) => ({
-    ...raw,
-    paths: normalizePaths(raw.paths),
-}));
+const tokenize = (command, opts) => {
+    const out = [];
+    let cur = '';
+    let quote = null;
+    for (let i = 0; i < command.length; i++) {
+        const c = command.charAt(i);
+        if (quote) {
+            if (c === quote) {
+                // Support doubled quotes inside a quoted segment:
+                // default: "" -> " and '' -> ' (Windows/PowerShell style)
+                // preserve: keep as "" to allow empty string literals in Node -e payloads
+                const next = command.charAt(i + 1);
+                if (next === quote) {
+                    {
+                        // Collapse to a single literal quote
+                        cur += quote;
+                        i += 1; // skip the second quote
+                    }
+                }
+                else {
+                    // end of quoted segment
+                    quote = null;
+                }
+            }
+            else {
+                cur += c;
+            }
+        }
+        else {
+            if (c === '"' || c === "'") {
+                quote = c;
+            }
+            else if (/\s/.test(c)) {
+                if (cur) {
+                    out.push(cur);
+                    cur = '';
+                }
+            }
+            else {
+                cur += c;
+            }
+        }
+    }
+    if (cur)
+        out.push(cur);
+    return out;
+};
 
+/**
+ * @packageDocumentation
+ * Configuration discovery and loading for get‑dotenv. Discovers config files
+ * in the packaged root and project root, loads JSON/YAML/JS/TS documents, and
+ * validates them against Zod schemas.
+ */
 // Discovery candidates (first match wins per scope/privacy).
 // Order preserves historical JSON/YAML precedence; JS/TS added afterwards.
 const PUBLIC_FILENAMES = [
@@ -254,75 +575,6 @@ const LOCAL_FILENAMES = [
 const isYaml = (p) => ['.yaml', '.yml'].includes(extname(p).toLowerCase());
 const isJson = (p) => extname(p).toLowerCase() === '.json';
 const isJsOrTs = (p) => ['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts'].includes(extname(p).toLowerCase());
-// --- Internal JS/TS module loader helpers (default export) ---
-const importDefault$1 = async (fileUrl) => {
-    const mod = (await import(fileUrl));
-    return mod.default;
-};
-const cacheName = (absPath, suffix) => {
-    // sanitized filename with suffix; recompile on mtime changes not tracked here (simplified)
-    const base = path.basename(absPath).replace(/[^a-zA-Z0-9._-]/g, '_');
-    return `${base}.${suffix}.mjs`;
-};
-const ensureDir = async (dir) => {
-    await fs.ensureDir(dir);
-    return dir;
-};
-const loadJsTsDefault = async (absPath) => {
-    const fileUrl = pathToFileURL(absPath).toString();
-    const ext = extname(absPath).toLowerCase();
-    if (ext === '.js' || ext === '.mjs' || ext === '.cjs') {
-        return importDefault$1(fileUrl);
-    }
-    // Try direct import first in case a TS loader is active.
-    try {
-        const val = await importDefault$1(fileUrl);
-        if (val)
-            return val;
-    }
-    catch {
-        /* fallthrough */
-    }
-    // esbuild bundle to a temp ESM file
-    try {
-        const esbuild = (await import('esbuild'));
-        const outDir = await ensureDir(path.resolve('.tsbuild', 'getdotenv-config'));
-        const outfile = path.join(outDir, cacheName(absPath, 'bundle'));
-        await esbuild.build({
-            entryPoints: [absPath],
-            bundle: true,
-            platform: 'node',
-            format: 'esm',
-            target: 'node20',
-            outfile,
-            sourcemap: false,
-            logLevel: 'silent',
-        });
-        return await importDefault$1(pathToFileURL(outfile).toString());
-    }
-    catch {
-        /* fallthrough to TS transpile */
-    }
-    // typescript.transpileModule simple transpile (single-file)
-    try {
-        const ts = (await import('typescript'));
-        const src = await fs.readFile(absPath, 'utf-8');
-        const out = ts.transpileModule(src, {
-            compilerOptions: {
-                module: 'ESNext',
-                target: 'ES2022',
-                moduleResolution: 'NodeNext',
-            },
-        }).outputText;
-        const outDir = await ensureDir(path.resolve('.tsbuild', 'getdotenv-config'));
-        const outfile = path.join(outDir, cacheName(absPath, 'ts'));
-        await fs.writeFile(outfile, out, 'utf-8');
-        return await importDefault$1(pathToFileURL(outfile).toString());
-    }
-    catch {
-        throw new Error(`Unable to load JS/TS config: ${absPath}. Install 'esbuild' for robust bundling or ensure a TS loader.`);
-    }
-};
 /**
  * Discover JSON/YAML config files in the packaged root and project root.
  * Order: packaged public → project public → project local. */
@@ -375,8 +627,8 @@ const loadConfigFile = async (filePath) => {
     try {
         const abs = path.resolve(filePath);
         if (isJsOrTs(abs)) {
-            // JS/TS support: load default export via robust pipeline.
-            const mod = await loadJsTsDefault(abs);
+            // JS/TS support: load default export via shared robust pipeline.
+            const mod = await loadModuleDefault(abs, 'getdotenv-config');
             raw = mod ?? {};
         }
         else {
@@ -392,571 +644,87 @@ const loadConfigFile = async (filePath) => {
     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;
-};
-
-/**
- * Validate a composed env against config-provided validation surfaces.
- * Precedence for validation definitions:
- *   project.local -\> project.public -\> packaged
- *
- * Behavior:
- * - If a JS/TS `schema` is present, use schema.safeParse(finalEnv).
- * - Else if `requiredKeys` is present, check presence (value !== undefined).
- * - Returns a flat list of issue strings; caller decides warn vs fail.
- */
-const validateEnvAgainstSources = (finalEnv, sources) => {
-    const pick = (getter) => {
-        const pl = sources.project?.local;
-        const pp = sources.project?.public;
-        const pk = sources.packaged;
-        return ((pl && getter(pl)) ||
-            (pp && getter(pp)) ||
-            (pk && getter(pk)) ||
-            undefined);
-    };
-    const schema = pick((cfg) => cfg['schema']);
-    if (schema &&
-        typeof schema.safeParse === 'function') {
-        try {
-            const parsed = schema.safeParse(finalEnv);
-            if (!parsed.success) {
-                // Try to render zod-style issues when available.
-                const err = parsed.error;
-                const issues = Array.isArray(err.issues) && err.issues.length > 0
-                    ? err.issues.map((i) => {
-                        const path = Array.isArray(i.path) ? i.path.join('.') : '';
-                        const msg = i.message ?? 'Invalid value';
-                        return path ? `[schema] ${path}: ${msg}` : `[schema] ${msg}`;
-                    })
-                    : ['[schema] validation failed'];
-                return issues;
-            }
-            return [];
-        }
-        catch {
-            // If schema invocation fails, surface a single diagnostic.
-            return [
-                '[schema] validation failed (unable to execute schema.safeParse)',
-            ];
-        }
-    }
-    const requiredKeys = pick((cfg) => cfg['requiredKeys']);
-    if (Array.isArray(requiredKeys) && requiredKeys.length > 0) {
-        const missing = requiredKeys.filter((k) => finalEnv[k] === undefined);
-        if (missing.length > 0) {
-            return missing.map((k) => `[requiredKeys] missing: ${k}`);
-        }
-    }
-    return [];
-};
-
-const baseGetDotenvCliOptions = baseRootOptionDefaults;
-
-/** src/util/omitUndefined.ts
- * Helpers to drop undefined-valued properties in a typed-friendly way.
- */
-/**
- * Omit keys whose runtime value is undefined from a shallow object.
- * Returns a Partial with non-undefined value types preserved.
- */
-function omitUndefined(obj) {
-    const out = {};
-    for (const [k, v] of Object.entries(obj)) {
-        if (v !== undefined)
-            out[k] = v;
-    }
-    return out;
-}
-/**
- * Specialized helper for env-like maps: drop undefined and return string-only.
- */
-function omitUndefinedRecord(obj) {
-    const out = {};
-    for (const [k, v] of Object.entries(obj)) {
-        if (v !== undefined)
-            out[k] = v;
-    }
-    return out;
-}
-
-// src/GetDotenvOptions.ts
-/**
- * Canonical programmatic options and helpers for get-dotenv.
- *
- * Requirements addressed:
- * - GetDotenvOptions derives from the Zod schema output (single source of truth).
- * - Removed deprecated/compat flags from the public shape (e.g., useConfigLoader).
- * - Provide Vars-aware defineDynamic and a typed config builder defineGetDotenvConfig\<Vars, Env\>().
- * - Preserve existing behavior for defaults resolution and compat converters.
- */
-const getDotenvOptionsFilename = 'getdotenv.config.json';
-/**
- * Converts programmatic CLI options to `getDotenv` options.
- *
- * Accepts "stringly" CLI inputs for vars/paths and normalizes them into
- * the programmatic shape. Preserves exactOptionalPropertyTypes semantics by
- * omitting keys when undefined.
- */
-const getDotenvCliOptions2Options = ({ paths, pathsDelimiter, pathsDelimiterPattern, vars, varsAssignor, varsAssignorPattern, varsDelimiter, varsDelimiterPattern, 
-// drop CLI-only keys from the pass-through bag
-debug: _debug, scripts: _scripts, ...rest }) => {
-    // Split helper for delimited strings or regex patterns
-    const splitBy = (value, delim, pattern) => {
-        if (!value)
-            return [];
-        if (pattern)
-            return value.split(RegExp(pattern));
-        if (typeof delim === 'string')
-            return value.split(delim);
-        return value.split(' ');
-    };
-    // Tolerate vars as either a CLI string ("A=1 B=2") or an object map.
-    let parsedVars;
-    if (typeof vars === 'string') {
-        const kvPairs = splitBy(vars, varsDelimiter, varsDelimiterPattern)
-            .map((v) => v.split(varsAssignorPattern
-            ? RegExp(varsAssignorPattern)
-            : (varsAssignor ?? '=')))
-            .filter(([k]) => typeof k === 'string' && k.length > 0);
-        parsedVars = Object.fromEntries(kvPairs);
-    }
-    else if (vars && typeof vars === 'object' && !Array.isArray(vars)) {
-        // Accept provided object map of string | undefined; drop undefined values
-        // in the normalization step below to produce a ProcessEnv-compatible bag.
-        parsedVars = Object.fromEntries(Object.entries(vars));
-    }
-    // Drop undefined-valued entries at the converter stage to match ProcessEnv
-    // expectations and the compat test assertions.
-    if (parsedVars) {
-        parsedVars = omitUndefinedRecord(parsedVars);
-    }
-    // Tolerate paths as either a delimited string or string[]
-    const pathsOut = Array.isArray(paths)
-        ? paths.filter((p) => typeof p === 'string')
-        : splitBy(paths, pathsDelimiter, pathsDelimiterPattern);
-    // Preserve exactOptionalPropertyTypes: only include keys when defined.
-    return {
-        ...rest,
-        ...(pathsOut.length > 0 ? { paths: pathsOut } : {}),
-        ...(parsedVars !== undefined ? { vars: parsedVars } : {}),
-    };
-};
-/**
- * Resolve {@link GetDotenvOptions} by layering defaults in ascending precedence:
- *
- * 1. Base defaults derived from the CLI generator defaults
- *    ({@link baseGetDotenvCliOptions}).
- * 2. Local project overrides from a `getdotenv.config.json` in the nearest
- *    package root (if present).
- * 3. The provided customOptions.
- *
- * The result preserves explicit empty values and drops only `undefined`.
- */
-const resolveGetDotenvOptions = async (customOptions) => {
-    const localPkgDir = await packageDirectory();
-    const localOptionsPath = localPkgDir
-        ? join(localPkgDir, getDotenvOptionsFilename)
-        : undefined;
-    // Safely read local CLI-facing defaults (defensive typing to satisfy strict linting).
-    let localOptions = {};
-    if (localOptionsPath && (await fs.exists(localOptionsPath))) {
-        try {
-            const txt = await fs.readFile(localOptionsPath, 'utf-8');
-            const parsed = JSON.parse(txt);
-            if (parsed && typeof parsed === 'object') {
-                localOptions = parsed;
-            }
-        }
-        catch {
-            // Malformed or unreadable local options are treated as absent.
-            localOptions = {};
-        }
-    }
-    // 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: omitUndefinedRecord(result.vars ?? {}),
-    };
-};
-
-/**
- * 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);
+            .join('\n');
+        throw new Error(`Invalid config ${filePath}:\n${msgs}`);
     }
-    return value;
+    // 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);
 };
 /**
- * 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.
+ * Discover and load configs into resolved shapes, ordered by scope/privacy.
+ * JSON/YAML/JS/TS supported; first match per scope/privacy applies.
  */
-const dotenvExpand = (value, ref = process.env) => {
-    const result = interpolate(value, ref);
-    return result ? result.replace(/\\\$/g, '$') : 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;
 };
-/**
- * Recursively expands environment variables in the values of a JSON object.
- * Variables may be presented with optional default as `$VAR[:default]` or
- * `${VAR[:default]}`. Unknown variables will expand to an empty string.
- *
- * @param values - The values object to expand.
- * @param options - Expansion options.
- * @returns The value object with expanded string values.
- *
- * @example
- * ```ts
- * process.env.FOO = 'bar';
- * dotenvExpandAll({ A: '$FOO', B: 'x${FOO}y' });
- * // => { A: "bar", B: "xbary" }
- * ```
- *
- * @remarks
- * Options:
- * - ref: The reference object to use for expansion (defaults to process.env).
- * - progressive: Whether to progressively add expanded values to the set of
- *   reference keys.
- *
- * When `progressive` is true, each expanded key becomes available for
- * subsequent expansions in the same object (left-to-right by object key order).
- */
-function dotenvExpandAll(values, options = {}) {
-    const { ref = process.env, progressive = false, } = options;
-    const out = Object.keys(values).reduce((acc, key) => {
-        acc[key] = dotenvExpand(values[key], {
-            ...ref,
-            ...(progressive ? acc : {}),
-        });
-        return acc;
-    }, {});
-    // Key-preserving return with a permissive index signature to allow later additions.
-    return out;
-}
-/**
- * Recursively expands environment variables in a string using `process.env` as
- * the expansion reference. Variables may be presented with optional default as
- * `$VAR[:default]` or `${VAR[:default]}`. Unknown variables will expand to an
- * empty string.
- *
- * @param value - The string to expand.
- * @returns The expanded string.
+
+/** src/env/dynamic.ts
+ * Helpers for applying and loading dynamic variables (JS/TS).
  *
- * @example
- * ```ts
- * process.env.FOO = 'bar';
- * dotenvExpandFromProcessEnv('Hello $FOO'); // "Hello bar"
- * ```
+ * Requirements addressed:
+ * - Single service to apply a dynamic map progressively.
+ * - Single service to load a JS/TS dynamic module with robust fallbacks (util/loadModuleDefault).
+ * - Unify error messaging so callers show consistent guidance.
  */
-const dotenvExpandFromProcessEnv = (value) => dotenvExpand(value, process.env);
-
-/* eslint-disable @typescript-eslint/no-deprecated */
 /**
- * Attach root flags to a GetDotenvCli instance.
- * - Host-only: program is typed as GetDotenvCli and supports dynamicOption/createDynamicOption.
- * - Any flag that displays an effective default in help uses dynamic descriptions.
+ * Apply a dynamic map to the target progressively.
+ * - Functions receive (target, env) and may return string | undefined.
+ * - Literals are assigned directly (including undefined).
  */
-const attachRootOptions = (program, defaults) => {
-    // Install temporary wrappers to tag all options added here as "base" for grouped help.
-    const GROUP = 'base';
-    const tagLatest = (cmd, group) => {
-        const optsArr = cmd.options ?? [];
-        if (Array.isArray(optsArr) && optsArr.length > 0) {
-            const last = optsArr[optsArr.length - 1];
-            program.setOptionGroup(last, group);
-        }
-    };
-    const originalAddOption = program.addOption.bind(program);
-    const originalOption = program.option.bind(program);
-    program.addOption = function patchedAdd(opt) {
-        program.setOptionGroup(opt, GROUP);
-        return originalAddOption(opt);
-    };
-    program.option = function patchedOption(...args) {
-        const ret = originalOption(...args);
-        tagLatest(this, GROUP);
-        return ret;
-    };
-    const { defaultEnv, dotenvToken, dynamicPath, env, outputPath, paths, pathsDelimiter, pathsDelimiterPattern, privateToken, scripts, varsAssignor, varsAssignorPattern, varsDelimiter, varsDelimiterPattern, } = defaults ?? {};
-    const va = typeof defaults?.varsAssignor === 'string' ? defaults.varsAssignor : '=';
-    const vd = typeof defaults?.varsDelimiter === 'string' ? defaults.varsDelimiter : ' ';
-    // Helper: append (default) tags for ON/OFF toggles
-    const onOff = (on, isDefault) => on
-        ? `ON${isDefault ? ' (default)' : ''}`
-        : `OFF${isDefault ? ' (default)' : ''}`;
-    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);
-    // Output path (interpolated later; help can remain static)
-    p = p.option('-o, --output-path <string>', 'consolidated output file  (dotenv-expanded)', dotenvExpandFromProcessEnv, outputPath);
-    // Shell ON (string or boolean true => default shell)
-    p = p
-        .addOption(program
-        .createDynamicOption('-s, --shell [string]', (cfg) => {
-        const s = cfg.shell;
-        let tag = '';
-        if (typeof s === 'boolean' && s)
-            tag = ' (default OS shell)';
-        else if (typeof s === 'string' && s.length > 0)
-            tag = ` (default ${s})`;
-        return `command execution shell, no argument for default OS shell or provide shell string${tag}`;
-    })
-        .conflicts('shellOff'))
-        // Shell OFF
-        .addOption(program
-        .createDynamicOption('-S, --shell-off', (cfg) => {
-        const s = cfg.shell;
-        return `command execution shell OFF${s === false ? ' (default)' : ''}`;
-    })
-        .conflicts('shell'));
-    // Load process ON/OFF (dynamic defaults)
-    p = p
-        .addOption(program
-        .createDynamicOption('-p, --load-process', (cfg) => `load variables to process.env ${onOff(true, Boolean(cfg.loadProcess))}`)
-        .conflicts('loadProcessOff'))
-        .addOption(program
-        .createDynamicOption('-P, --load-process-off', (cfg) => `load variables to process.env ${onOff(false, !cfg.loadProcess)}`)
-        .conflicts('loadProcess'));
-    // Exclusion master toggle (dynamic)
-    p = p
-        .addOption(program
-        .createDynamicOption('-a, --exclude-all', (cfg) => {
-        const allOn = !!cfg.excludeDynamic &&
-            ((!!cfg.excludeEnv && !!cfg.excludeGlobal) ||
-                (!!cfg.excludePrivate && !!cfg.excludePublic));
-        const suffix = allOn ? ' (default)' : '';
-        return `exclude all dotenv variables from loading ON${suffix}`;
-    })
-        .conflicts('excludeAllOff'))
-        .addOption(new Option('-A, --exclude-all-off', `exclude all dotenv variables from loading OFF (default)`).conflicts('excludeAll'));
-    // Per-family exclusions (dynamic defaults)
-    p = p
-        .addOption(program
-        .createDynamicOption('-z, --exclude-dynamic', (cfg) => `exclude dynamic dotenv variables from loading ${onOff(true, Boolean(cfg.excludeDynamic))}`)
-        .conflicts('excludeDynamicOff'))
-        .addOption(program
-        .createDynamicOption('-Z, --exclude-dynamic-off', (cfg) => `exclude dynamic dotenv variables from loading ${onOff(false, !cfg.excludeDynamic)}`)
-        .conflicts('excludeDynamic'))
-        .addOption(program
-        .createDynamicOption('-n, --exclude-env', (cfg) => `exclude environment-specific dotenv variables from loading ${onOff(true, Boolean(cfg.excludeEnv))}`)
-        .conflicts('excludeEnvOff'))
-        .addOption(program
-        .createDynamicOption('-N, --exclude-env-off', (cfg) => `exclude environment-specific dotenv variables from loading ${onOff(false, !cfg.excludeEnv)}`)
-        .conflicts('excludeEnv'))
-        .addOption(program
-        .createDynamicOption('-g, --exclude-global', (cfg) => `exclude global dotenv variables from loading ${onOff(true, Boolean(cfg.excludeGlobal))}`)
-        .conflicts('excludeGlobalOff'))
-        .addOption(program
-        .createDynamicOption('-G, --exclude-global-off', (cfg) => `exclude global dotenv variables from loading ${onOff(false, !cfg.excludeGlobal)}`)
-        .conflicts('excludeGlobal'))
-        .addOption(program
-        .createDynamicOption('-r, --exclude-private', (cfg) => `exclude private dotenv variables from loading ${onOff(true, Boolean(cfg.excludePrivate))}`)
-        .conflicts('excludePrivateOff'))
-        .addOption(program
-        .createDynamicOption('-R, --exclude-private-off', (cfg) => `exclude private dotenv variables from loading ${onOff(false, !cfg.excludePrivate)}`)
-        .conflicts('excludePrivate'))
-        .addOption(program
-        .createDynamicOption('-u, --exclude-public', (cfg) => `exclude public dotenv variables from loading ${onOff(true, Boolean(cfg.excludePublic))}`)
-        .conflicts('excludePublicOff'))
-        .addOption(program
-        .createDynamicOption('-U, --exclude-public-off', (cfg) => `exclude public dotenv variables from loading ${onOff(false, !cfg.excludePublic)}`)
-        .conflicts('excludePublic'));
-    // Log ON/OFF (dynamic)
-    p = p
-        .addOption(program
-        .createDynamicOption('-l, --log', (cfg) => `console log loaded variables ${onOff(true, Boolean(cfg.log))}`)
-        .conflicts('logOff'))
-        .addOption(program
-        .createDynamicOption('-L, --log-off', (cfg) => `console log loaded variables ${onOff(false, !cfg.log)}`)
-        .conflicts('log'));
-    // Capture flag (no default display; static)
-    p = p.option('--capture', 'capture child process stdio for commands (tests/CI)');
-    // Core bootstrap/static flags (kept static in help)
-    p = p
-        .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 / validation / entropy
-    p = p
-        .option('--trace [keys...]', 'emit diagnostics for child env composition (optional keys)')
-        .option('--strict', 'fail on env validation errors (schema/requiredKeys)');
-    p = p
-        .addOption(program
-        .createDynamicOption('--entropy-warn', (cfg) => {
-        const warn = cfg.warnEntropy;
-        // Default is effectively ON when warnEntropy is true or undefined.
-        return `enable entropy warnings${warn === false ? '' : ' (default on)'}`;
-    })
-        .conflicts('entropyWarnOff'))
-        .addOption(program
-        .createDynamicOption('--entropy-warn-off', (cfg) => `disable entropy warnings${cfg.warnEntropy === false ? ' (default)' : ''}`)
-        .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
-    program.addOption = originalAddOption;
-    program.option = originalOption;
-    return p;
-};
-
+function applyDynamicMap(target, map, env) {
+    if (!map)
+        return;
+    for (const key of Object.keys(map)) {
+        const val = typeof map[key] === 'function'
+            ? map[key](target, env)
+            : map[key];
+        Object.assign(target, { [key]: val });
+    }
+}
 /**
- * Zod schemas for programmatic GetDotenv options.
+ * Load a default-export dynamic map from a JS/TS file and apply it.
+ * Uses util/loadModuleDefault for robust TS handling (direct import, esbuild,
+ * typescript.transpile fallback).
  *
- * Canonical source of truth for options shape. Public types are derived
- * from these schemas (see consumers via z.output\<\>).
+ * Error behavior:
+ * - On failure to load/compile/evaluate the module, throws a unified message:
+ *   "Unable to load dynamic TypeScript file: <absPath>. Install 'esbuild'..."
  */
-// Minimal process env representation: string values or undefined to indicate "unset".
-const processEnvSchema = z.record(z.string(), z.string().optional());
-// RAW: all fields optional — undefined means "inherit" from lower layers.
-const getDotenvOptionsSchemaRaw = z.object({
-    defaultEnv: z.string().optional(),
-    dotenvToken: z.string().optional(),
-    dynamicPath: z.string().optional(),
-    // Dynamic map is intentionally wide for now; refine once sources are normalized.
-    dynamic: z.record(z.string(), z.unknown()).optional(),
-    env: z.string().optional(),
-    excludeDynamic: z.boolean().optional(),
-    excludeEnv: z.boolean().optional(),
-    excludeGlobal: z.boolean().optional(),
-    excludePrivate: z.boolean().optional(),
-    excludePublic: z.boolean().optional(),
-    loadProcess: z.boolean().optional(),
-    log: z.boolean().optional(),
-    logger: z.unknown().optional(),
-    outputPath: z.string().optional(),
-    paths: z.array(z.string()).optional(),
-    privateToken: z.string().optional(),
-    vars: processEnvSchema.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;
+async function loadAndApplyDynamic(target, absPath, env, cacheDirName) {
+    if (!(await fs.exists(absPath)))
+        return;
+    let dyn;
+    try {
+        dyn = await loadModuleDefault(absPath, cacheDirName);
+    }
+    catch {
+        // Preserve legacy/clear guidance used by tests and docs.
+        throw new Error(`Unable to load dynamic TypeScript file: ${absPath}. ` +
+            `Install 'esbuild' (devDependency) to enable TypeScript dynamic modules.`);
+    }
+    applyDynamicMap(target, dyn, env);
+}
 
 const applyKv = (current, kv) => {
     if (!kv || Object.keys(kv).length === 0)
@@ -972,7 +740,8 @@ const applyConfigSlice = (current, cfg, env) => {
     const envKv = env && cfg.envVars ? cfg.envVars[env] : undefined;
     return applyKv(afterGlobal, envKv);
 };
-function overlayEnv({ base, env, configs, programmaticVars, }) {
+function overlayEnv(args) {
+    const { base, env, configs } = args;
     let current = { ...base };
     // Source: packaged (public -> local)
     current = applyConfigSlice(current, configs.packaged, env);
@@ -982,8 +751,8 @@ function overlayEnv({ base, env, configs, programmaticVars, }) {
     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'));
+    if ('programmaticVars' in args) {
+        const toApply = Object.fromEntries(Object.entries(args.programmaticVars).filter(([_k, v]) => typeof v === 'string'));
         current = applyKv(current, toApply);
     }
     return current;
@@ -1036,29 +805,145 @@ const maybeWarnEntropy = (key, value, origin, opts, emit) => {
         emit(`[entropy] key=${key} score=${bpc.toFixed(2)} len=${String(v.length)} origin=${origin}`);
     }
 };
-
-const DEFAULT_PATTERNS = [
-    '\\bsecret\\b',
-    '\\btoken\\b',
-    '\\bpass(word)?\\b',
-    '\\bapi[_-]?key\\b',
-    '\\bkey\\b',
-];
-const compile = (patterns) => (patterns && patterns.length > 0 ? patterns : DEFAULT_PATTERNS).map((p) => typeof p === 'string' ? new RegExp(p, 'i') : p);
-const shouldRedactKey = (key, regs) => regs.some((re) => re.test(key));
-const MASK = '[redacted]';
+
+const DEFAULT_PATTERNS = [
+    '\\bsecret\\b',
+    '\\btoken\\b',
+    '\\bpass(word)?\\b',
+    '\\bapi[_-]?key\\b',
+    '\\bkey\\b',
+];
+const compile = (patterns) => (patterns && patterns.length > 0 ? patterns : DEFAULT_PATTERNS).map((p) => typeof p === 'string' ? new RegExp(p, 'i') : p);
+const shouldRedactKey = (key, regs) => regs.some((re) => re.test(key));
+const MASK = '[redacted]';
+/**
+ * Produce a shallow redacted copy of an env-like object for display.
+ */
+const redactObject = (obj, opts) => {
+    if (!opts?.redact)
+        return { ...obj };
+    const regs = compile(opts.redactPatterns);
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+        out[k] = v && shouldRedactKey(k, regs) ? MASK : v;
+    }
+    return out;
+};
+
+/**
+ * Base root CLI defaults (shared; kept untyped here to avoid cross-layer deps).
+ * Used as the bottom layer for CLI option resolution.
+ */
+/**
+ * Default values for root CLI options used by the host and helpers as the
+ * baseline layer during option resolution.
+ *
+ * These defaults correspond to the "stringly" root surface (see `RootOptionsShape`)
+ * and are merged by precedence with create-time overrides and any discovered
+ * configuration `rootOptionDefaults` before CLI flags are applied.
+ */
+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)
+};
+
+/**
+ * Converts programmatic CLI options to `getDotenv` options.
+ *
+ * Accepts "stringly" CLI inputs for vars/paths and normalizes them into
+ * the programmatic shape. Preserves exactOptionalPropertyTypes semantics by
+ * omitting keys when undefined.
+ */
+const getDotenvCliOptions2Options = ({ paths, pathsDelimiter, pathsDelimiterPattern, vars, varsAssignor, varsAssignorPattern, varsDelimiter, varsDelimiterPattern, 
+// drop CLI-only keys from the pass-through bag
+debug: _debug, scripts: _scripts, ...rest }) => {
+    // Split helper for delimited strings or regex patterns
+    const splitBy = (value, delim, pattern) => {
+        if (!value)
+            return [];
+        if (pattern)
+            return value.split(RegExp(pattern));
+        if (typeof delim === 'string')
+            return value.split(delim);
+        return value.split(' ');
+    };
+    // Tolerate vars as either a CLI string ("A=1 B=2") or an object map.
+    let parsedVars;
+    if (typeof vars === 'string') {
+        const kvPairs = splitBy(vars, varsDelimiter, varsDelimiterPattern)
+            .map((v) => v.split(varsAssignorPattern
+            ? RegExp(varsAssignorPattern)
+            : (varsAssignor ?? '=')))
+            .filter(([k]) => typeof k === 'string' && k.length > 0);
+        parsedVars = Object.fromEntries(kvPairs);
+    }
+    else if (vars && typeof vars === 'object' && !Array.isArray(vars)) {
+        // Accept provided object map of string | undefined; drop undefined values
+        // in the normalization step below to produce a ProcessEnv-compatible bag.
+        parsedVars = Object.fromEntries(Object.entries(vars));
+    }
+    // Drop undefined-valued entries at the converter stage to match ProcessEnv
+    // expectations and the compat test assertions.
+    if (parsedVars) {
+        parsedVars = omitUndefinedRecord(parsedVars);
+    }
+    // Tolerate paths as either a delimited string or string[]
+    const pathsOut = Array.isArray(paths)
+        ? paths.filter((p) => typeof p === 'string')
+        : splitBy(paths, pathsDelimiter, pathsDelimiterPattern);
+    // Preserve exactOptionalPropertyTypes: only include keys when defined.
+    return {
+        // Ensure the required logger property is present. The base CLI defaults
+        // specify console as the logger; callers can override upstream if desired.
+        logger: console,
+        ...rest,
+        ...(pathsOut.length > 0 ? { paths: pathsOut } : {}),
+        ...(parsedVars !== undefined ? { vars: parsedVars } : {}),
+    };
+};
 /**
- * Produce a shallow redacted copy of an env-like object for display.
+ * Resolve {@link GetDotenvOptions} by layering defaults in ascending precedence:
+ *
+ * 1. Base defaults derived from the CLI generator defaults
+ *    ({@link baseGetDotenvCliOptions}).
+ * 2. Local project overrides from a `getdotenv.config.json` in the nearest
+ *    package root (if present).
+ * 3. The provided customOptions.
+ *
+ * The result preserves explicit empty values and drops only `undefined`.
  */
-const 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;
+const resolveGetDotenvOptions = (customOptions) => {
+    // Programmatic callers use neutral defaults only. Do not read local packaged
+    // getdotenv.config.json here; the host path applies packaged/project configs
+    // via the dedicated loader/overlay pipeline.
+    const mergedDefaults = baseRootOptionDefaults;
+    const defaultsFromCli = getDotenvCliOptions2Options(mergedDefaults);
+    const result = defaultsDeep(defaultsFromCli, customOptions);
+    return Promise.resolve({
+        ...result, // Keep explicit empty strings/zeros; drop only undefined
+        vars: omitUndefinedRecord(result.vars ?? {}),
+    });
 };
 
 /**
@@ -1076,117 +961,6 @@ const readDotenv = async (path) => {
     }
 };
 
-const importDefault = async (fileUrl) => {
-    const mod = (await import(fileUrl));
-    return mod.default;
-};
-const cacheHash = (absPath, mtimeMs) => createHash('sha1')
-    .update(absPath)
-    .update(String(mtimeMs))
-    .digest('hex')
-    .slice(0, 12);
-/**
- * Remove older compiled cache files for a given source base name, keeping
- * at most `keep` most-recent files. Errors are ignored by design.
- */
-const cleanupOldCacheFiles = async (cacheDir, baseName, keep = Math.max(1, Number.parseInt(process.env.GETDOTENV_CACHE_KEEP ?? '2'))) => {
-    try {
-        const entries = await fs.readdir(cacheDir);
-        const mine = entries
-            .filter((f) => f.startsWith(`${baseName}.`) && f.endsWith('.mjs'))
-            .map((f) => path.join(cacheDir, f));
-        if (mine.length <= keep)
-            return;
-        const stats = await Promise.all(mine.map(async (p) => ({ p, mtimeMs: (await fs.stat(p)).mtimeMs })));
-        stats.sort((a, b) => b.mtimeMs - a.mtimeMs);
-        const toDelete = stats.slice(keep).map((s) => s.p);
-        await Promise.all(toDelete.map(async (p) => {
-            try {
-                await fs.remove(p);
-            }
-            catch {
-                // best-effort cleanup
-            }
-        }));
-    }
-    catch {
-        // best-effort cleanup
-    }
-};
-/**
- * Load a module default export from a JS/TS file with robust fallbacks:
- * - .js/.mjs/.cjs: direct import * - .ts/.mts/.cts/.tsx:
- *   1) try direct import (if a TS loader is active),
- *   2) esbuild bundle to a temp ESM file,
- *   3) typescript.transpileModule fallback for simple modules.
- *
- * @param absPath - absolute path to source file
- * @param cacheDirName - cache subfolder under .tsbuild
- */
-const loadModuleDefault = async (absPath, cacheDirName) => {
-    const ext = path.extname(absPath).toLowerCase();
-    const fileUrl = url.pathToFileURL(absPath).toString();
-    if (!['.ts', '.mts', '.cts', '.tsx'].includes(ext)) {
-        return importDefault(fileUrl);
-    }
-    // Try direct import first (TS loader active)
-    try {
-        const dyn = await importDefault(fileUrl);
-        if (dyn)
-            return dyn;
-    }
-    catch {
-        /* fall through */
-    }
-    const stat = await fs.stat(absPath);
-    const hash = cacheHash(absPath, stat.mtimeMs);
-    const cacheDir = path.resolve('.tsbuild', cacheDirName);
-    await fs.ensureDir(cacheDir);
-    const cacheFile = path.join(cacheDir, `${path.basename(absPath)}.${hash}.mjs`);
-    // Try esbuild
-    try {
-        const esbuild = (await import('esbuild'));
-        await esbuild.build({
-            entryPoints: [absPath],
-            bundle: true,
-            platform: 'node',
-            format: 'esm',
-            target: 'node20',
-            outfile: cacheFile,
-            sourcemap: false,
-            logLevel: 'silent',
-        });
-        const result = await importDefault(url.pathToFileURL(cacheFile).toString());
-        // Best-effort: trim older cache files for this source.
-        await cleanupOldCacheFiles(cacheDir, path.basename(absPath));
-        return result;
-    }
-    catch {
-        /* fall through to TS transpile */
-    }
-    // TypeScript transpile fallback
-    try {
-        const ts = (await import('typescript'));
-        const code = await fs.readFile(absPath, 'utf-8');
-        const out = ts.transpileModule(code, {
-            compilerOptions: {
-                module: 'ESNext',
-                target: 'ES2022',
-                moduleResolution: 'NodeNext',
-            },
-        }).outputText;
-        await fs.writeFile(cacheFile, out, 'utf-8');
-        const result = await importDefault(url.pathToFileURL(cacheFile).toString());
-        // Best-effort: trim older cache files for this source.
-        await cleanupOldCacheFiles(cacheDir, path.basename(absPath));
-        return result;
-    }
-    catch {
-        // Caller decides final error wording; rethrow for upstream mapping.
-        throw new Error(`Unable to load JS/TS module: ${absPath}. Install 'esbuild' or ensure a TS loader.`);
-    }
-};
-
 async function getDotenv(options = {}) {
     // Apply defaults.
     const { defaultEnv, dotenvToken = '.env', dynamicPath, env, excludeDynamic = false, excludeEnv = false, excludeGlobal = false, excludePrivate = false, excludePublic = false, loadProcess = false, log = false, logger = console, outputPath, paths = [], privateToken = 'local', vars = {}, } = await resolveGetDotenvOptions(options);
@@ -1235,25 +1009,11 @@ async function getDotenv(options = {}) {
         }
         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.`);
-                }
-            }
+            await loadAndApplyDynamic(dotenv, absDynamicPath, env ?? defaultEnv, 'getdotenv-dynamic');
         }
         if (dynamic) {
             try {
-                for (const key in dynamic)
-                    Object.assign(dotenv, {
-                        [key]: typeof dynamic[key] === 'function'
-                            ? dynamic[key](dotenv, env ?? defaultEnv)
-                            : dynamic[key],
-                    });
+                applyDynamicMap(dotenv, dynamic, env ?? defaultEnv);
             }
             catch {
                 throw new Error(`Unable to evaluate dynamic variables.`);
@@ -1267,10 +1027,7 @@ async function getDotenv(options = {}) {
         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' });
+        await writeDotenvFile(outputPathResolved, dotenvForOutput);
         resultDotenv = dotenvForOutput;
     }
     // Log result.
@@ -1315,60 +1072,26 @@ async function getDotenv(options = {}) {
 }
 
 /**
- * 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).
+ * Compute the realized path for a command mount (leaf-up to root).
+ * Excludes the root application alias.
  *
- * Intended for:
- * - Phase C option/config interpolation after composing ctx.dotenv.
- * - Per-plugin config slice interpolation before afterResolve.
+ * @param cli - The mounted command instance.
  */
-/** @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.
+ * Flatten a plugin tree into a list of `{ plugin, path }` entries.
+ * Traverses the namespace chain in pre-order.
  */
-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;
+function flattenPluginTreeByPath(plugins, prefix) {
+    const out = [];
+    for (const p of plugins) {
+        const here = prefix && prefix.length > 0 ? `${prefix}/${p.ns}` : p.ns;
+        out.push({ plugin: p, path: here });
+        if (Array.isArray(p.children) && p.children.length > 0) {
+            out.push(...flattenPluginTreeByPath(p.children.map((c) => c.plugin), here));
         }
-        return out;
     }
-    // Other primitives/types: return as-is
-    return value;
-};
+    return out;
+}
 
 /**
  * Instance-bound plugin config store.
@@ -1378,15 +1101,26 @@ const interpolateDeep = (value, envRef) => {
  * plugin instance.
  */
 const PLUGIN_CONFIG_STORE = new WeakMap();
-const _setPluginConfigForInstance = (plugin, cfg) => {
+/**
+ * Store a validated, interpolated config slice for a specific plugin instance.
+ * Generic on both the host options type and the plugin config type to avoid
+ * defaulting to GetDotenvOptions under exactOptionalPropertyTypes.
+ */
+const setPluginConfig = (plugin, cfg) => {
     PLUGIN_CONFIG_STORE.set(plugin, cfg);
 };
-const _getPluginConfigForInstance = (plugin) => PLUGIN_CONFIG_STORE.get(plugin);
+/**
+ * Retrieve the validated/interpolated config slice for a plugin instance.
+ */
+const getPluginConfig = (plugin) => {
+    return PLUGIN_CONFIG_STORE.get(plugin);
+};
 /**
  * Compute the dotenv context for the host (uses the config loader/overlay path).
  * - Resolves and validates options strictly (host-only).
  * - Applies file cascade, overlays, dynamics, and optional effects.
- * - Merges and validates per-plugin config slices (when provided).
+ * - Merges and validates per-plugin config slices (when provided), keyed by
+ *   realized mount path (ns chain).
  *
  * @param customOptions - Partial options from the current invocation.
  * @param plugins - Installed plugins (for config validation).
@@ -1397,21 +1131,16 @@ const computeContext = async (customOptions, plugins, hostMetaUrl) => {
     // Zod boundary: parse returns the schema-derived shape; we adopt our public
     // GetDotenvOptions overlay (logger/dynamic typing) for internal processing.
     const validated = getDotenvOptionsSchemaResolved.parse(optionsResolved);
-    // Always-on loader path
-    // 1) Base from files only (no dynamic, no programmatic vars)
-    // Sanitize to avoid passing properties explicitly set to undefined.
+    // Build a pure base without side effects or logging (no dynamics, no programmatic vars).
     const cleanedValidated = omitUndefined(validated);
     const base = await getDotenv({
         ...cleanedValidated,
-        // Build a pure base without side effects or logging.
         excludeDynamic: true,
         vars: {},
         log: false,
         loadProcess: false,
-        // Intentionally omit outputPath for the base pass; including a key with
-        // undefined would violate exactOptionalPropertyTypes on the Partial target.
     });
-    // 2) Discover config sources and overlay
+    // Discover config sources and overlay with progressive expansion per slice.
     const sources = await resolveGetDotenvConfigSources(hostMetaUrl);
     const dotenvOverlaid = overlayEnv({
         base,
@@ -1419,47 +1148,31 @@ const computeContext = async (customOptions, plugins, hostMetaUrl) => {
         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);
+    // Programmatic dynamic variables (when provided)
+    applyDynamicMap(dotenv, validated.dynamic, validated.env ?? validated.defaultEnv);
+    // Packaged/project dynamics
+    const packagedDyn = (sources.packaged?.dynamic ?? undefined);
+    const publicDyn = (sources.project?.public?.dynamic ?? undefined);
+    const localDyn = (sources.project?.local?.dynamic ?? undefined);
+    applyDynamicMap(dotenv, packagedDyn, validated.env ?? validated.defaultEnv);
+    applyDynamicMap(dotenv, publicDyn, validated.env ?? validated.defaultEnv);
+    applyDynamicMap(dotenv, localDyn, validated.env ?? validated.defaultEnv);
     // file dynamicPath (lowest)
     if (validated.dynamicPath) {
         const absDynamicPath = path.resolve(validated.dynamicPath);
-        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}`);
-        }
+        await loadAndApplyDynamic(dotenv, absDynamicPath, validated.env ?? validated.defaultEnv, 'getdotenv-dynamic-host');
     }
-    // 4) Output/log/process merge
+    // Effects:
     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' });
+        await writeDotenvFile(validated.outputPath, dotenv);
     }
-    const logger = customOptions.logger ?? console;
+    const logger = validated.logger;
     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)
+    // Merge and validate per-plugin config keyed by realized path (ns chain).
     const packagedPlugins = (sources.packaged &&
         sources.packaged.plugins) ??
         {};
@@ -1469,95 +1182,563 @@ const computeContext = async (customOptions, plugins, hostMetaUrl) => {
     const localPlugins = (sources.project?.local &&
         sources.project.local.plugins) ??
         {};
-    // The by-id map is retained only for backwards-compat rendering paths
-    // (root help dynamic evaluation). Instance-bound access is the source
-    // of truth going forward and is populated below.
-    const mergedPluginConfigsById = defaultsDeep({}, packagedPlugins, publicPlugins, localPlugins);
-    for (const p of plugins) {
-        if (!p.id)
-            continue;
-        const slice = mergedPluginConfigsById[p.id];
-        // Build interpolation reference once per plugin:
-        const envRef = {
-            ...dotenv,
-            ...process.env,
-        };
-        const interpolated = slice && typeof slice === 'object'
-            ? interpolateDeep(slice, envRef)
+    const entries = flattenPluginTreeByPath(plugins);
+    const mergedPluginConfigsByPath = {};
+    const envRef = {
+        ...dotenv,
+        ...process.env,
+    };
+    for (const e of entries) {
+        const pathKey = e.path;
+        const mergedRaw = defaultsDeep({}, packagedPlugins[pathKey] ?? {}, publicPlugins[pathKey] ?? {}, localPlugins[pathKey] ?? {});
+        const interpolated = mergedRaw && typeof mergedRaw === 'object'
+            ? interpolateDeep(mergedRaw, envRef)
             : {};
-        // Enforced: plugins always carry a schema (strict empty by default).
-        // Zod v4: avoid legacy multi-generic usage; treat as generic ZodObject.
-        const schema = p.configSchema;
-        const toParse = interpolated;
-        const parsed = schema.safeParse(toParse);
-        if (!parsed.success) {
-            const err = parsed.error;
-            const msgs = err.issues
-                .map((i) => {
-                const path = Array.isArray(i.path) ? i.path.join('.') : '';
-                const msg = typeof i.message === 'string' ? i.message : 'Invalid value';
-                return path ? `${path}: ${msg}` : msg;
-            })
-                .join('\n');
-            throw new Error(`Invalid config for plugin '${p.id}':\n${msgs}`);
+        const schema = e.plugin.configSchema;
+        if (schema) {
+            const parsed = schema.safeParse(interpolated);
+            if (!parsed.success) {
+                const err = parsed.error;
+                const msgs = err.issues
+                    .map((i) => {
+                    const pth = Array.isArray(i.path) ? i.path.join('.') : '';
+                    const msg = typeof i.message === 'string' ? i.message : 'Invalid value';
+                    return pth ? `${pth}: ${msg}` : msg;
+                })
+                    .join('\n');
+                throw new Error(`Invalid config for plugin at '${pathKey}':\n${msgs}`);
+            }
+            const frozen = Object.freeze(parsed.data);
+            setPluginConfig(e.plugin, frozen);
+            mergedPluginConfigsByPath[pathKey] = frozen;
+        }
+        else {
+            const frozen = Object.freeze(interpolated);
+            setPluginConfig(e.plugin, frozen);
+            mergedPluginConfigsByPath[pathKey] = frozen;
+        }
+    }
+    return {
+        optionsResolved: validated,
+        dotenv,
+        plugins: {},
+        pluginConfigs: mergedPluginConfigsByPath,
+    };
+};
+
+// Implementation
+function definePlugin(spec) {
+    const { ...rest } = spec;
+    const effectiveSchema = spec.configSchema ?? z.object({}).strict();
+    const base = {
+        ...rest,
+        configSchema: effectiveSchema,
+        children: [],
+        use(child, override) {
+            // Enforce sibling uniqueness at composition time.
+            const desired = (override && typeof override.ns === 'string' && override.ns.length > 0
+                ? override.ns
+                : child.ns).trim();
+            const collision = this.children.some((c) => {
+                const ns = (c.override &&
+                    typeof c.override.ns === 'string' &&
+                    c.override.ns.length > 0
+                    ? c.override.ns
+                    : c.plugin.ns).trim();
+                return ns === desired;
+            });
+            if (collision) {
+                const under = this.ns && this.ns.length > 0 ? this.ns : 'root';
+                throw new Error(`Duplicate namespace '${desired}' under '${under}'. ` +
+                    `Override via .use(plugin, { ns: '...' }).`);
+            }
+            this.children.push({ plugin: child, override });
+            return this;
+        },
+    };
+    const extended = base;
+    extended.readConfig = function (_cli) {
+        const value = getPluginConfig(extended);
+        if (value === undefined) {
+            throw new Error('Plugin config not available. Ensure resolveAndLoad() has been called before readConfig().');
         }
-        // Store a readonly (shallow-frozen) value for runtime safety.
-        const frozen = Object.freeze(parsed.data);
-        _setPluginConfigForInstance(p, frozen);
-        mergedPluginConfigsById[p.id] = frozen;
+        return value;
+    };
+    extended.createPluginDynamicOption = function (cli, flags, desc, parser, defaultValue) {
+        // Derive realized path strictly from the provided mount (leaf-up).
+        const realizedPath = (() => {
+            const parts = [];
+            let node = cli;
+            while (node.parent) {
+                parts.push(node.name());
+                node = node.parent;
+            }
+            return parts.reverse().join('/');
+        })();
+        return cli.createDynamicOption(flags, (c) => {
+            const fromStore = getPluginConfig(extended);
+            let cfgVal = fromStore ?? {};
+            // Strict fallback only by realized path for help-time synthetic usage.
+            if (!fromStore && realizedPath.length > 0) {
+                const bag = c.plugins;
+                const maybe = bag[realizedPath];
+                if (maybe && typeof maybe === 'object') {
+                    cfgVal = maybe;
+                }
+            }
+            // c is strictly typed as ResolvedHelpConfig from cli.createDynamicOption
+            return desc(c, cfgVal);
+        }, parser, defaultValue);
+    };
+    return extended;
+}
+
+const dbg = (...args) => {
+    if (process.env.GETDOTENV_DEBUG) {
+        // Use stderr to avoid interfering with stdout assertions
+        console.error('[getdotenv:run]', ...args);
+    }
+};
+// Strip repeated symmetric outer quotes (single or double) until stable.
+// This is safe for argv arrays passed to execa (no quoting needed) and avoids
+// passing quote characters through to Node (e.g., for `node -e "<code>"`).
+// Handles stacked quotes from shells like PowerShell: """code""" -> code.
+const stripOuterQuotes = (s) => {
+    let out = s;
+    // Repeatedly trim only when the entire string is wrapped in matching quotes.
+    // Stop as soon as the ends are asymmetric or no quotes remain.
+    while (out.length >= 2) {
+        const a = out.charAt(0);
+        const b = out.charAt(out.length - 1);
+        const symmetric = (a === '"' && b === '"') || (a === "'" && b === "'");
+        if (!symmetric)
+            break;
+        out = out.slice(1, -1);
     }
+    return out;
+};
+// Extract exitCode/stdout/stderr from execa result or error in a tolerant way.
+const pickResult = (r) => {
+    const exit = r.exitCode;
+    const stdoutVal = r.stdout;
+    const stderrVal = r.stderr;
     return {
-        optionsResolved: validated,
-        dotenv: dotenv,
-        plugins: {},
-        // Retained for legacy root help dynamic evaluation only. Instance-bound
-        // access is used by plugins themselves and tests/docs moving forward.
-        pluginConfigs: mergedPluginConfigsById,
+        exitCode: typeof exit === 'number' ? exit : Number.NaN,
+        stdout: typeof stdoutVal === 'string' ? stdoutVal : '',
+        stderr: typeof stderrVal === 'string' ? stderrVal : '',
     };
 };
-
-// Registry for dynamic descriptions keyed by Option (WeakMap so GC-friendly)
-const DYN_DESC = new WeakMap();
+// 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;
+};
 /**
- * Create an Option with a dynamic description callback stored in DYN_DESC.
+ * Core executor that normalizes shell/plain forms and capture/inherit modes.
+ * Returns captured buffers; callers may stream stdout when desired.
  */
-function makeDynamicOption(flags, desc, parser, defaultValue) {
-    const opt = new Option(flags, '');
-    DYN_DESC.set(opt, desc);
-    if (parser) {
-        opt.argParser((value, previous) => parser(value, previous));
+async function _execNormalized(command, shell, opts = {}) {
+    const envSan = sanitizeEnv(opts.env);
+    const timeoutBits = typeof opts.timeoutMs === 'number'
+        ? { timeout: opts.timeoutMs, killSignal: 'SIGKILL' }
+        : {};
+    const stdio = opts.stdio ?? 'pipe';
+    if (shell === false) {
+        let file;
+        let args = [];
+        if (typeof command === 'string') {
+            const tokens = tokenize(command);
+            file = tokens[0];
+            args = tokens.slice(1);
+        }
+        else {
+            file = command[0];
+            args = command.slice(1).map(stripOuterQuotes);
+        }
+        if (!file)
+            return { exitCode: 0, stdout: '', stderr: '' };
+        dbg('exec (plain)', { file, args, stdio });
+        try {
+            const ok = pickResult((await execa(file, args, {
+                ...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),
+                ...(envSan !== undefined ? { env: envSan } : {}),
+                stdio,
+                ...timeoutBits,
+            })));
+            dbg('exit (plain)', { exitCode: ok.exitCode });
+            return ok;
+        }
+        catch (e) {
+            const out = pickResult(e);
+            dbg('exit:error (plain)', { exitCode: out.exitCode });
+            return out;
+        }
     }
-    if (defaultValue !== undefined)
-        opt.default(defaultValue);
-    return opt;
+    // Shell path (string|true|URL): execaCommand handles shell resolution.
+    const commandStr = typeof command === 'string' ? command : command.join(' ');
+    dbg('exec (shell)', {
+        command: commandStr,
+        shell: typeof shell === 'string' ? shell : 'custom',
+        stdio,
+    });
+    try {
+        const ok = pickResult((await execaCommand(commandStr, {
+            shell,
+            ...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),
+            ...(envSan !== undefined ? { env: envSan } : {}),
+            stdio,
+            ...timeoutBits,
+        })));
+        dbg('exit (shell)', { exitCode: ok.exitCode });
+        return ok;
+    }
+    catch (e) {
+        const out = pickResult(e);
+        dbg('exit:error (shell)', { exitCode: out.exitCode });
+        return out;
+    }
+}
+async function runCommandResult(command, shell, opts = {}) {
+    // Build opts without injecting undefined (exactOptionalPropertyTypes-safe)
+    const coreOpts = { stdio: 'pipe' };
+    if (opts.cwd !== undefined) {
+        coreOpts.cwd = opts.cwd;
+    }
+    if (opts.env !== undefined) {
+        coreOpts.env = opts.env;
+    }
+    if (opts.timeoutMs !== undefined) {
+        coreOpts.timeoutMs = opts.timeoutMs;
+    }
+    return _execNormalized(command, shell, coreOpts);
 }
+async function runCommand(command, shell, opts) {
+    // Build opts without injecting undefined (exactOptionalPropertyTypes-safe)
+    const callOpts = {};
+    if (opts.cwd !== undefined) {
+        callOpts.cwd = opts.cwd;
+    }
+    if (opts.env !== undefined) {
+        callOpts.env = opts.env;
+    }
+    if (opts.stdio !== undefined)
+        callOpts.stdio = opts.stdio;
+    const ok = await _execNormalized(command, shell, callOpts);
+    if (opts.stdio === 'pipe' && ok.stdout) {
+        process.stdout.write(ok.stdout + (ok.stdout.endsWith('\n') ? '' : '\n'));
+    }
+    return typeof ok.exitCode === 'number' ? ok.exitCode : Number.NaN;
+}
+
 /**
- * Evaluate dynamic descriptions across a command tree using the resolved config.
+ * Attach root flags to a {@link GetDotenvCli} instance.
+ *
+ * Program is typed as {@link GetDotenvCli} and supports {@link GetDotenvCli.createDynamicOption | createDynamicOption}.
  */
-function evaluateDynamicOptions(root, resolved) {
-    const visit = (cmd) => {
-        const arr = cmd.options;
-        for (const o of arr) {
-            const dyn = DYN_DESC.get(o);
-            if (typeof dyn === 'function') {
-                try {
-                    const txt = dyn(resolved);
-                    // Commander uses Option.description during help rendering.
-                    o.description = txt;
-                }
-                catch {
-                    /* best-effort; leave as-is */
-                }
-            }
+const attachRootOptions = (program, defaults) => {
+    const GROUP = 'base';
+    const { defaultEnv, dotenvToken, dynamicPath, env, outputPath, paths, pathsDelimiter, pathsDelimiterPattern, privateToken, varsAssignor, varsAssignorPattern, varsDelimiter, varsDelimiterPattern, } = defaults ?? {};
+    const va = typeof defaults?.varsAssignor === 'string' ? defaults.varsAssignor : '=';
+    const vd = typeof defaults?.varsDelimiter === 'string' ? defaults.varsDelimiter : ' ';
+    // Helper: append (default) tags for ON/OFF toggles
+    const onOff = (on, isDefault) => on
+        ? `ON${isDefault ? ' (default)' : ''}`
+        : `OFF${isDefault ? ' (default)' : ''}`;
+    program.enablePositionalOptions().passThroughOptions();
+    // -e, --env <string>
+    {
+        const opt = new Option('-e, --env <string>', 'target environment (dotenv-expanded)');
+        opt.argParser(dotenvExpandFromProcessEnv);
+        if (env !== undefined)
+            opt.default(env);
+        program.addOption(opt);
+        program.setOptionGroup(opt, GROUP);
+    }
+    // -v, --vars <string>
+    {
+        const examples = [
+            ['KEY1', 'VAL1'],
+            ['KEY2', 'VAL2'],
+        ]
+            .map((v) => v.join(va))
+            .join(vd);
+        const opt = new Option('-v, --vars <string>', `extra variables expressed as delimited key-value pairs (dotenv-expanded): ${examples}`);
+        opt.argParser(dotenvExpandFromProcessEnv);
+        program.addOption(opt);
+        program.setOptionGroup(opt, GROUP);
+    }
+    // Output path (interpolated later; help can remain static)
+    {
+        const opt = new Option('-o, --output-path <string>', 'consolidated output file  (dotenv-expanded)');
+        opt.argParser(dotenvExpandFromProcessEnv);
+        if (outputPath !== undefined)
+            opt.default(outputPath);
+        program.addOption(opt);
+        program.setOptionGroup(opt, GROUP);
+    }
+    // Shell ON (string or boolean true => default shell)
+    {
+        const opt = program
+            .createDynamicOption('-s, --shell [string]', (cfg) => {
+            const s = cfg.shell;
+            let tag = '';
+            if (typeof s === 'boolean' && s)
+                tag = ' (default OS shell)';
+            else if (typeof s === 'string' && s.length > 0)
+                tag = ` (default ${s})`;
+            return `command execution shell, no argument for default OS shell or provide shell string${tag}`;
+        })
+            .conflicts('shellOff');
+        program.addOption(opt);
+        program.setOptionGroup(opt, GROUP);
+    }
+    // Shell OFF
+    {
+        const opt = program
+            .createDynamicOption('-S, --shell-off', (cfg) => {
+            const s = cfg.shell;
+            return `command execution shell OFF${s === false ? ' (default)' : ''}`;
+        })
+            .conflicts('shell');
+        program.addOption(opt);
+        program.setOptionGroup(opt, GROUP);
+    }
+    // Load process ON/OFF (dynamic defaults)
+    {
+        const optOn = program
+            .createDynamicOption('-p, --load-process', (cfg) => `load variables to process.env ${onOff(true, Boolean(cfg.loadProcess))}`)
+            .conflicts('loadProcessOff');
+        program.addOption(optOn);
+        program.setOptionGroup(optOn, GROUP);
+        const optOff = program
+            .createDynamicOption('-P, --load-process-off', (cfg) => `load variables to process.env ${onOff(false, !cfg.loadProcess)}`)
+            .conflicts('loadProcess');
+        program.addOption(optOff);
+        program.setOptionGroup(optOff, GROUP);
+    }
+    // Exclusion master toggle (dynamic)
+    {
+        const optAll = program
+            .createDynamicOption('-a, --exclude-all', (cfg) => {
+            const allOn = !!cfg.excludeDynamic &&
+                ((!!cfg.excludeEnv && !!cfg.excludeGlobal) ||
+                    (!!cfg.excludePrivate && !!cfg.excludePublic));
+            const suffix = allOn ? ' (default)' : '';
+            return `exclude all dotenv variables from loading ON${suffix}`;
+        })
+            .conflicts('excludeAllOff');
+        program.addOption(optAll);
+        program.setOptionGroup(optAll, GROUP);
+        const optAllOff = new Option('-A, --exclude-all-off', 'exclude all dotenv variables from loading OFF (default)').conflicts('excludeAll');
+        program.addOption(optAllOff);
+        program.setOptionGroup(optAllOff, GROUP);
+    }
+    // Per-family exclusions (dynamic defaults)
+    {
+        const o1 = program
+            .createDynamicOption('-z, --exclude-dynamic', (cfg) => `exclude dynamic dotenv variables from loading ${onOff(true, Boolean(cfg.excludeDynamic))}`)
+            .conflicts('excludeDynamicOff');
+        program.addOption(o1);
+        program.setOptionGroup(o1, GROUP);
+        const o2 = program
+            .createDynamicOption('-Z, --exclude-dynamic-off', (cfg) => `exclude dynamic dotenv variables from loading ${onOff(false, !cfg.excludeDynamic)}`)
+            .conflicts('excludeDynamic');
+        program.addOption(o2);
+        program.setOptionGroup(o2, GROUP);
+    }
+    {
+        const o1 = program
+            .createDynamicOption('-n, --exclude-env', (cfg) => `exclude environment-specific dotenv variables from loading ${onOff(true, Boolean(cfg.excludeEnv))}`)
+            .conflicts('excludeEnvOff');
+        program.addOption(o1);
+        program.setOptionGroup(o1, GROUP);
+        const o2 = program
+            .createDynamicOption('-N, --exclude-env-off', (cfg) => `exclude environment-specific dotenv variables from loading ${onOff(false, !cfg.excludeEnv)}`)
+            .conflicts('excludeEnv');
+        program.addOption(o2);
+        program.setOptionGroup(o2, GROUP);
+    }
+    {
+        const o1 = program
+            .createDynamicOption('-g, --exclude-global', (cfg) => `exclude global dotenv variables from loading ${onOff(true, Boolean(cfg.excludeGlobal))}`)
+            .conflicts('excludeGlobalOff');
+        program.addOption(o1);
+        program.setOptionGroup(o1, GROUP);
+        const o2 = program
+            .createDynamicOption('-G, --exclude-global-off', (cfg) => `exclude global dotenv variables from loading ${onOff(false, !cfg.excludeGlobal)}`)
+            .conflicts('excludeGlobal');
+        program.addOption(o2);
+        program.setOptionGroup(o2, GROUP);
+    }
+    {
+        const p1 = program
+            .createDynamicOption('-r, --exclude-private', (cfg) => `exclude private dotenv variables from loading ${onOff(true, Boolean(cfg.excludePrivate))}`)
+            .conflicts('excludePrivateOff');
+        program.addOption(p1);
+        program.setOptionGroup(p1, GROUP);
+        const p2 = program
+            .createDynamicOption('-R, --exclude-private-off', (cfg) => `exclude private dotenv variables from loading ${onOff(false, !cfg.excludePrivate)}`)
+            .conflicts('excludePrivate');
+        program.addOption(p2);
+        program.setOptionGroup(p2, GROUP);
+        const pu1 = program
+            .createDynamicOption('-u, --exclude-public', (cfg) => `exclude public dotenv variables from loading ${onOff(true, Boolean(cfg.excludePublic))}`)
+            .conflicts('excludePublicOff');
+        program.addOption(pu1);
+        program.setOptionGroup(pu1, GROUP);
+        const pu2 = program
+            .createDynamicOption('-U, --exclude-public-off', (cfg) => `exclude public dotenv variables from loading ${onOff(false, !cfg.excludePublic)}`)
+            .conflicts('excludePublic');
+        program.addOption(pu2);
+        program.setOptionGroup(pu2, GROUP);
+    }
+    // Log ON/OFF (dynamic)
+    {
+        const lo = program
+            .createDynamicOption('-l, --log', (cfg) => `console log loaded variables ${onOff(true, Boolean(cfg.log))}`)
+            .conflicts('logOff');
+        program.addOption(lo);
+        program.setOptionGroup(lo, GROUP);
+        const lf = program
+            .createDynamicOption('-L, --log-off', (cfg) => `console log loaded variables ${onOff(false, !cfg.log)}`)
+            .conflicts('log');
+        program.addOption(lf);
+        program.setOptionGroup(lf, GROUP);
+    }
+    // Capture flag (no default display; static)
+    {
+        const opt = new Option('--capture', 'capture child process stdio for commands (tests/CI)');
+        program.addOption(opt);
+        program.setOptionGroup(opt, GROUP);
+    }
+    // Core bootstrap/static flags (kept static in help)
+    {
+        const o1 = new Option('--default-env <string>', 'default target environment');
+        o1.argParser(dotenvExpandFromProcessEnv);
+        if (defaultEnv !== undefined)
+            o1.default(defaultEnv);
+        program.addOption(o1);
+        program.setOptionGroup(o1, GROUP);
+        const o2 = new Option('--dotenv-token <string>', 'dotenv-expanded token indicating a dotenv file');
+        o2.argParser(dotenvExpandFromProcessEnv);
+        if (dotenvToken !== undefined)
+            o2.default(dotenvToken);
+        program.addOption(o2);
+        program.setOptionGroup(o2, GROUP);
+        const o3 = new Option('--dynamic-path <string>', 'dynamic variables path (.js or .ts; .ts is auto-compiled when esbuild is available, otherwise precompile)');
+        o3.argParser(dotenvExpandFromProcessEnv);
+        if (dynamicPath !== undefined)
+            o3.default(dynamicPath);
+        program.addOption(o3);
+        program.setOptionGroup(o3, GROUP);
+        const o4 = new Option('--paths <string>', 'dotenv-expanded delimited list of paths to dotenv directory');
+        o4.argParser(dotenvExpandFromProcessEnv);
+        if (paths !== undefined)
+            o4.default(paths);
+        program.addOption(o4);
+        program.setOptionGroup(o4, GROUP);
+        const o5 = new Option('--paths-delimiter <string>', 'paths delimiter string');
+        if (pathsDelimiter !== undefined)
+            o5.default(pathsDelimiter);
+        program.addOption(o5);
+        program.setOptionGroup(o5, GROUP);
+        const o6 = new Option('--paths-delimiter-pattern <string>', 'paths delimiter regex pattern');
+        if (pathsDelimiterPattern !== undefined)
+            o6.default(pathsDelimiterPattern);
+        program.addOption(o6);
+        program.setOptionGroup(o6, GROUP);
+        const o7 = new Option('--private-token <string>', 'dotenv-expanded token indicating private variables');
+        o7.argParser(dotenvExpandFromProcessEnv);
+        if (privateToken !== undefined)
+            o7.default(privateToken);
+        program.addOption(o7);
+        program.setOptionGroup(o7, GROUP);
+        const o8 = new Option('--vars-delimiter <string>', 'vars delimiter string');
+        if (varsDelimiter !== undefined)
+            o8.default(varsDelimiter);
+        program.addOption(o8);
+        program.setOptionGroup(o8, GROUP);
+        const o9 = new Option('--vars-delimiter-pattern <string>', 'vars delimiter regex pattern');
+        if (varsDelimiterPattern !== undefined)
+            o9.default(varsDelimiterPattern);
+        program.addOption(o9);
+        program.setOptionGroup(o9, GROUP);
+        const o10 = new Option('--vars-assignor <string>', 'vars assignment operator string');
+        if (varsAssignor !== undefined)
+            o10.default(varsAssignor);
+        program.addOption(o10);
+        program.setOptionGroup(o10, GROUP);
+        const o11 = new Option('--vars-assignor-pattern <string>', 'vars assignment operator regex pattern');
+        if (varsAssignorPattern !== undefined)
+            o11.default(varsAssignorPattern);
+        program.addOption(o11);
+        program.setOptionGroup(o11, GROUP);
+    }
+    // Diagnostics / validation / entropy
+    {
+        const tr = new Option('--trace [keys...]', 'emit diagnostics for child env composition (optional keys)');
+        program.addOption(tr);
+        program.setOptionGroup(tr, GROUP);
+        const st = new Option('--strict', 'fail on env validation errors (schema/requiredKeys)');
+        program.addOption(st);
+        program.setOptionGroup(st, GROUP);
+    }
+    {
+        const w = program
+            .createDynamicOption('--entropy-warn', (cfg) => {
+            const warn = cfg.warnEntropy;
+            // Default is effectively ON when warnEntropy is true or undefined.
+            return `enable entropy warnings${warn === false ? '' : ' (default on)'}`;
+        })
+            .conflicts('entropyWarnOff');
+        program.addOption(w);
+        program.setOptionGroup(w, GROUP);
+        const woff = program
+            .createDynamicOption('--entropy-warn-off', (cfg) => `disable entropy warnings${cfg.warnEntropy === false ? ' (default)' : ''}`)
+            .conflicts('entropyWarn');
+        program.addOption(woff);
+        program.setOptionGroup(woff, GROUP);
+        const th = new Option('--entropy-threshold <number>', 'entropy bits/char threshold (default 3.8)');
+        program.addOption(th);
+        program.setOptionGroup(th, GROUP);
+        const ml = new Option('--entropy-min-length <number>', 'min length to examine for entropy (default 16)');
+        program.addOption(ml);
+        program.setOptionGroup(ml, GROUP);
+        const wl = new Option('--entropy-whitelist <pattern...>', 'suppress entropy warnings when key matches any regex pattern');
+        program.addOption(wl);
+        program.setOptionGroup(wl, GROUP);
+        const rp = new Option('--redact-pattern <pattern...>', 'additional key-match regex patterns to trigger redaction');
+        program.addOption(rp);
+        program.setOptionGroup(rp, GROUP);
+        // Redact ON/OFF (dynamic)
+        {
+            const rOn = program
+                .createDynamicOption('--redact', (cfg) => `presentation-time redaction for secret-like keys ON${cfg.redact ? ' (default)' : ''}`)
+                .conflicts('redactOff');
+            program.addOption(rOn);
+            program.setOptionGroup(rOn, GROUP);
+            const rOff = program
+                .createDynamicOption('--redact-off', (cfg) => `presentation-time redaction for secret-like keys OFF${cfg.redact === false ? ' (default)' : ''}`)
+                .conflicts('redact');
+            program.addOption(rOff);
+            program.setOptionGroup(rOff, GROUP);
         }
-        for (const c of cmd.commands)
-            visit(c);
-    };
-    visit(root);
-}
+    }
+    return program;
+};
 
-// Registry for grouping; root help renders groups between Options and Commands.
+/**
+ * Registry for option grouping.
+ * Root help renders these groups between "Options" and "Commands".
+ */
 const GROUP_TAG = new WeakMap();
+/**
+ * Render help option groups (App/Plugins) for a given command.
+ * Groups are injected between Options and Commands in the help output.
+ */
 function renderOptionGroups(cmd) {
     const all = cmd.options;
     const byGroup = new Map();
@@ -1611,6 +1792,271 @@ function renderOptionGroups(cmd) {
     return out;
 }
 
+/**
+ * Compose root/parent help output by inserting grouped sections between
+ * Options and Commands, ensuring a trailing blank line.
+ */
+function buildHelpInformation(base, cmd) {
+    const groups = renderOptionGroups(cmd);
+    const block = typeof groups === 'string' ? groups.trim() : '';
+    if (!block) {
+        return base.endsWith('\n\n')
+            ? base
+            : base.endsWith('\n')
+                ? `${base}\n`
+                : `${base}\n\n`;
+    }
+    const marker = '\nCommands:';
+    const idx = base.indexOf(marker);
+    let out = base;
+    if (idx >= 0) {
+        const toInsert = groups.startsWith('\n') ? groups : `\n${groups}`;
+        out = `${base.slice(0, idx)}${toInsert}${base.slice(idx)}`;
+    }
+    else {
+        const sep = base.endsWith('\n') || groups.startsWith('\n') ? '' : '\n';
+        out = `${base}${sep}${groups}`;
+    }
+    return out.endsWith('\n\n')
+        ? out
+        : out.endsWith('\n')
+            ? `${out}\n`
+            : `${out}\n\n`;
+}
+
+/** src/cliHost/GetDotenvCli/dynamicOptions.ts
+ * Helpers for dynamic option descriptions and evaluation.
+ */
+/**
+ * Registry for dynamic descriptions keyed by Option (WeakMap for GC safety).
+ */
+const DYN_DESC = new WeakMap();
+/**
+ * Create an Option with a dynamic description callback stored in DYN_DESC.
+ */
+function makeDynamicOption(flags, desc, parser, defaultValue) {
+    const opt = new Option(flags, '');
+    DYN_DESC.set(opt, desc);
+    if (parser) {
+        opt.argParser((value, previous) => parser(value, previous));
+    }
+    if (defaultValue !== undefined)
+        opt.default(defaultValue);
+    // Commander.Option is structurally compatible; help-time wiring is stored in DYN_DESC.
+    return opt;
+}
+/**
+ * Evaluate dynamic descriptions across a command tree using the resolved config.
+ */
+function evaluateDynamicOptions(root, resolved) {
+    const visit = (cmd) => {
+        const arr = cmd.options;
+        for (const o of arr) {
+            const dyn = DYN_DESC.get(o);
+            if (typeof dyn === 'function') {
+                try {
+                    const txt = dyn(resolved);
+                    // Commander uses Option.description during help rendering.
+                    o.description = txt;
+                }
+                catch {
+                    /* best-effort; leave as-is */
+                }
+            }
+        }
+        for (const c of cmd.commands)
+            visit(c);
+    };
+    visit(root);
+}
+
+function initializeInstance(cli, headerGetter) {
+    // Configure grouped help: show only base options in default "Options";
+    // subcommands show all of their own options.
+    cli.configureHelp({
+        visibleOptions: (cmd) => {
+            const all = cmd.options;
+            const isRoot = cmd.parent === null;
+            const list = isRoot
+                ? all.filter((opt) => {
+                    const group = GROUP_TAG.get(opt);
+                    return group === 'base';
+                })
+                : all.slice();
+            // Sort: short-aliased options first, then long-only; stable by flags.
+            const hasShort = (opt) => {
+                const flags = opt.flags;
+                return /(^|\s|,)-[A-Za-z]/.test(flags);
+            };
+            const byFlags = (opt) => opt.flags;
+            list.sort((a, b) => {
+                const aS = hasShort(a) ? 1 : 0;
+                const bS = hasShort(b) ? 1 : 0;
+                return bS - aS || byFlags(a).localeCompare(byFlags(b));
+            });
+            return list;
+        },
+    });
+    // Optional branded header before help text (kept minimal and deterministic).
+    cli.addHelpText('beforeAll', () => {
+        const header = headerGetter();
+        return header && header.length > 0 ? `${header}\n\n` : '';
+    });
+    // Tests-only: suppress process.exit during help/version flows under Vitest.
+    // Unit tests often construct GetDotenvCli directly (bypassing createCli),
+    // so install a local exitOverride when a test environment is detected.
+    const underTests = process.env.GETDOTENV_TEST === '1' ||
+        typeof process.env.VITEST_WORKER_ID === 'string';
+    if (underTests) {
+        cli.exitOverride((err) => {
+            const code = err?.code;
+            if (code === 'commander.helpDisplayed' ||
+                code === 'commander.version' ||
+                code === 'commander.help')
+                return;
+            throw err;
+        });
+    }
+    // Ensure the root has a no-op action so preAction hooks installed by
+    // passOptions() fire for root-only invocations (no subcommand).
+    // Subcommands still take precedence and will not hit this action.
+    // This keeps root-side effects (e.g., --log) working in direct hosts/tests.
+    cli.action(() => {
+        /* no-op */
+    });
+    // PreSubcommand hook: compute a context if absent, without mutating process.env.
+    // The passOptions() helper, when installed, resolves the final context.
+    cli.hook('preSubcommand', async () => {
+        if (cli.hasCtx())
+            return;
+        await cli.resolveAndLoad({ loadProcess: false });
+    });
+}
+
+/**
+ * Determine the effective namespace for a child plugin (override \> default).
+ */
+const effectiveNs = (child) => {
+    const o = child.override;
+    return (o && typeof o.ns === 'string' && o.ns.length > 0 ? o.ns : child.plugin.ns).trim();
+};
+const isPromise = (v) => !!v && typeof v.then === 'function';
+function runInstall(parentCli, plugin) {
+    // Create mount and run setup
+    const mount = parentCli.ns(plugin.ns);
+    const setupRet = plugin.setup(mount);
+    const pending = [];
+    if (isPromise(setupRet))
+        pending.push(setupRet.then(() => undefined));
+    // Enforce sibling uniqueness before creating children
+    const names = new Set();
+    for (const entry of plugin.children) {
+        const ns = effectiveNs(entry);
+        if (names.has(ns)) {
+            const under = mount.name();
+            throw new Error(`Duplicate namespace '${ns}' under '${under || 'root'}'. Override via .use(plugin, { ns: '...' }).`);
+        }
+        names.add(ns);
+    }
+    // Install children (pre-order), synchronously when possible
+    for (const entry of plugin.children) {
+        const childRet = runInstall(mount, entry.plugin);
+        if (isPromise(childRet))
+            pending.push(childRet);
+    }
+    if (pending.length > 0)
+        return Promise.all(pending).then(() => undefined);
+    return;
+}
+/**
+ * Install a plugin and its children (pre-order setup phase).
+ * Enforces sibling namespace uniqueness.
+ */
+function setupPluginTree(cli, plugin) {
+    const ret = runInstall(cli, plugin);
+    return isPromise(ret) ? ret : Promise.resolve();
+}
+
+/**
+ * Resolve options strictly and compute the dotenv context via the loader/overlay path.
+ *
+ * @param customOptions - Partial options overlay.
+ * @param plugins - Plugins list for config validation.
+ * @param hostMetaUrl - Import URL for resolving the packaged root.
+ */
+async function resolveAndComputeContext(customOptions, plugins, hostMetaUrl) {
+    const optionsResolved = await resolveGetDotenvOptions(customOptions);
+    // Strict schema validation
+    getDotenvOptionsSchemaResolved.parse(optionsResolved);
+    const ctx = await computeContext(optionsResolved, plugins, hostMetaUrl);
+    return ctx;
+}
+
+/**
+ * Run afterResolve hooks for a plugin tree (parent → children).
+ */
+async function runAfterResolveTree(cli, plugins, ctx) {
+    const run = async (p) => {
+        if (p.afterResolve)
+            await p.afterResolve(cli, ctx);
+        for (const child of p.children)
+            await run(child.plugin);
+    };
+    for (const p of plugins)
+        await run(p);
+}
+
+/**
+ * Temporarily tag options added during a callback as 'app' for grouped help.
+ * Wraps `addOption` on the command instance.
+ */
+function tagAppOptionsAround(root, setOptionGroup, fn) {
+    const originalAddOption = root.addOption.bind(root);
+    root.addOption = ((opt) => {
+        setOptionGroup(opt, 'app');
+        return originalAddOption(opt);
+    });
+    try {
+        return fn(root);
+    }
+    finally {
+        root.addOption = originalAddOption;
+    }
+}
+
+/**
+ * Read the version from the nearest `package.json` relative to the provided import URL.
+ *
+ * @param importMetaUrl - The `import.meta.url` of the calling module.
+ * @returns The version string or undefined if not found.
+ */
+async function readPkgVersion(importMetaUrl) {
+    if (!importMetaUrl)
+        return undefined;
+    try {
+        const fromUrl = fileURLToPath(importMetaUrl);
+        const pkgDir = await packageDirectory({ cwd: fromUrl });
+        if (!pkgDir)
+            return undefined;
+        const txt = await fs.readFile(`${pkgDir}/package.json`, 'utf-8');
+        const pkg = JSON.parse(txt);
+        return pkg.version ?? undefined;
+    }
+    catch {
+        // best-effort only
+        return undefined;
+    }
+}
+
+/** src/cliHost/GetDotenvCli.ts
+ * Plugin-first CLI host for get-dotenv with Commander generics preserved.
+ * Public surface implements GetDotenvCliPublic and provides:
+ *  - attachRootOptions (builder-only; no public override wiring)
+ *  - resolveAndLoad (strict resolve + context compute)
+ *  - getCtx/hasCtx accessors
+ *  - ns() for typed subcommand creation with duplicate-name guard
+ *  - grouped help rendering with dynamic option descriptions
+ */
 const HOST_META_URL = import.meta.url;
 const CTX_SYMBOL = Symbol('GetDotenvCli.ctx');
 const OPTS_SYMBOL = Symbol('GetDotenvCli.options');
@@ -1624,11 +2070,13 @@ const HELP_HEADER_SYMBOL = Symbol('GetDotenvCli.helpHeader');
  * - Provide a namespacing helper (ns).
  * - Support composable plugins with parent → children install and afterResolve.
  */
-let GetDotenvCli$1 = class GetDotenvCli extends Command {
+class GetDotenvCli extends Command {
     /** Registered top-level plugins (composition happens via .use()) */
     _plugins = [];
     /** One-time installation guard */
     _installed = false;
+    /** In-flight installation promise to guard against concurrent installs */
+    _installing;
     /** Optional header line to prepend in help output */
     [HELP_HEADER_SYMBOL];
     /** Context/options stored under symbols (typed) */
@@ -1639,56 +2087,23 @@ let GetDotenvCli$1 = class GetDotenvCli extends Command {
      * dynamicOption on children.
      */
     createCommand(name) {
-        // Explicitly construct a GetDotenvCli (drop subclass constructor semantics).
+        // Explicitly construct a GetDotenvCli for children to preserve helpers.
         return new GetDotenvCli(name);
     }
     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";
-        // we will insert App/Plugin sections before Commands in helpInformation().
-        this.configureHelp({
-            visibleOptions: (cmd) => {
-                const all = cmd.options;
-                const isRoot = cmd.parent === null;
-                const list = isRoot
-                    ? all.filter((opt) => {
-                        const group = GROUP_TAG.get(opt);
-                        return group === 'base';
-                    })
-                    : all.slice(); // subcommands: show all options (their own "Options:" block)
-                // 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;
-                list.sort((a, b) => {
-                    const aS = hasShort(a) ? 1 : 0;
-                    const bS = hasShort(b) ? 1 : 0;
-                    return bS - aS || byFlags(a).localeCompare(byFlags(b));
-                });
-                return list;
-            },
-        });
-        this.addHelpText('beforeAll', () => {
-            const header = this[HELP_HEADER_SYMBOL];
-            return header && header.length > 0 ? `${header}\n\n` : '';
-        });
-        // 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 });
-        });
+        // Delegate the heavy setup to a helper to keep the constructor lean.
+        initializeInstance(this, () => this[HELP_HEADER_SYMBOL]);
+    }
+    /**
+     * Attach legacy/base root flags to this CLI instance.
+     * Delegates to the pure builder in attachRootOptions.ts.
+     */
+    attachRootOptions(defaults) {
+        const d = (defaults ?? baseRootOptionDefaults);
+        attachRootOptions(this, d);
+        return this;
     }
     /**
      * Resolve options (strict) and compute dotenv context.
@@ -1700,11 +2115,9 @@ let GetDotenvCli$1 = class GetDotenvCli extends Command {
      *   long-running side-effects while still evaluating dynamic help text.
      */
     async resolveAndLoad(customOptions = {}, opts) {
-        // 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);
+        const ctx = await resolveAndComputeContext(customOptions, 
+        // Pass only plugin instances to the resolver (not entries with overrides)
+        this._plugins.map((e) => e.plugin), HOST_META_URL);
         // Persist context on the instance for later access.
         this[CTX_SYMBOL] = ctx;
         // Ensure plugins are installed exactly once, then run afterResolve.
@@ -1718,14 +2131,6 @@ let GetDotenvCli$1 = class GetDotenvCli extends Command {
     createDynamicOption(flags, desc, parser, defaultValue) {
         return makeDynamicOption(flags, (c) => desc(c), parser, defaultValue);
     }
-    /**
-     * Chainable helper mirroring .option(), but with a dynamic description.
-     * Equivalent to addOption(createDynamicOption(...)).
-     */
-    dynamicOption(flags, desc, parser, defaultValue) {
-        this.addOption(this.createDynamicOption(flags, desc, parser, defaultValue));
-        return this;
-    }
     /**
      * Evaluate dynamic descriptions for this command and all descendants using
      * the provided resolved configuration. Mutates the Option.description in
@@ -1734,24 +2139,58 @@ let GetDotenvCli$1 = class GetDotenvCli extends Command {
     evaluateDynamicOptions(resolved) {
         evaluateDynamicOptions(this, resolved);
     }
+    /** Internal: climb to the true root (host) command. */
+    _root() {
+        let node = this;
+        while (node.parent) {
+            node = node.parent;
+        }
+        return node;
+    }
     /**
      * Retrieve the current invocation context (if any).
      */
     getCtx() {
-        return this[CTX_SYMBOL];
+        let ctx = this[CTX_SYMBOL];
+        if (!ctx) {
+            const root = this._root();
+            ctx = root[CTX_SYMBOL];
+        }
+        if (!ctx) {
+            throw new Error('Dotenv context unavailable. Ensure resolveAndLoad() has been called or the host is wired with passOptions() before invoking commands.');
+        }
+        return ctx;
+    }
+    /**
+     * Check whether a context has been resolved (non-throwing guard).
+     */
+    hasCtx() {
+        if (this[CTX_SYMBOL] !== undefined)
+            return true;
+        const root = this._root();
+        return root[CTX_SYMBOL] !== undefined;
     }
     /**
      * Retrieve the merged root CLI options bag (if set by passOptions()).
      * Downstream-safe: no generics required.
      */
     getOptions() {
-        return this[OPTS_SYMBOL];
+        if (this[OPTS_SYMBOL])
+            return this[OPTS_SYMBOL];
+        const root = this._root();
+        const bag = root[OPTS_SYMBOL];
+        if (bag)
+            return bag;
+        return undefined;
     }
     /** Internal: set the merged root options bag for this run. */
     _setOptionsBag(bag) {
         this[OPTS_SYMBOL] = bag;
     }
-    /** Convenience helper to create a namespaced subcommand. */
+    /**
+     * Convenience helper to create a namespaced subcommand with argument inference.
+     * This mirrors Commander generics so downstream chaining stays fully typed.
+     */
     ns(name) {
         // Guard against same-level duplicate command names for clearer diagnostics.
         const exists = this.commands.some((c) => c.name() === name);
@@ -1765,18 +2204,7 @@ let GetDotenvCli$1 = class GetDotenvCli extends Command {
      * Allows downstream apps to demarcate their root-level options.
      */
     tagAppOptions(fn) {
-        const root = this;
-        const originalAddOption = root.addOption.bind(root);
-        root.addOption = function patchedAdd(opt) {
-            root.setOptionGroup(opt, 'app');
-            return originalAddOption(opt);
-        };
-        try {
-            return fn(root);
-        }
-        finally {
-            root.addOption = originalAddOption;
-        }
+        return tagAppOptionsAround(this, this.setOptionGroup.bind(this), fn);
     }
     /**
      * Branding helper: set CLI name/description/version and optional help header.
@@ -1785,26 +2213,11 @@ let GetDotenvCli$1 = class GetDotenvCli extends Command {
      */
     async brand(args) {
         const { name, description, version, importMetaUrl, helpHeader } = args;
-        if (typeof name === 'string' && name.length > 0)
-            this.name(name);
-        if (typeof description === 'string')
-            this.description(description);
-        let v = version;
-        if (!v && importMetaUrl) {
-            try {
-                const fromUrl = fileURLToPath(importMetaUrl);
-                const pkgDir = await packageDirectory({ cwd: fromUrl });
-                if (pkgDir) {
-                    const txt = await fs.readFile(`${pkgDir}/package.json`, 'utf-8');
-                    const pkg = JSON.parse(txt);
-                    if (pkg.version)
-                        v = pkg.version;
-                }
-            }
-            catch {
-                // best-effort only
-            }
-        }
+        if (typeof name === 'string' && name.length > 0)
+            this.name(name);
+        if (typeof description === 'string')
+            this.description(description);
+        const v = version ?? (await readPkgVersion(importMetaUrl));
         if (v)
             this.version(v);
         // Help header:
@@ -1824,34 +2237,7 @@ let GetDotenvCli$1 = class GetDotenvCli extends Command {
      * hybrid ordering. Applies to root and any parent command.
      */
     helpInformation() {
-        // Base help text first (includes beforeAll/after hooks).
-        const base = super.helpInformation();
-        const groups = renderOptionGroups(this);
-        const block = typeof groups === 'string' ? groups.trim() : '';
-        let out = base;
-        if (!block) {
-            // Ensure a trailing blank line even when no extra groups render.
-            if (!out.endsWith('\n\n'))
-                out = out.endsWith('\n') ? `${out}\n` : `${out}\n\n`;
-            return out;
-        }
-        // Insert just before "Commands:" when present.
-        const marker = '\nCommands:';
-        const idx = base.indexOf(marker);
-        if (idx >= 0) {
-            const toInsert = groups.startsWith('\n') ? groups : `\n${groups}`;
-            out = `${base.slice(0, idx)}${toInsert}${base.slice(idx)}`;
-        }
-        else {
-            // Otherwise append.
-            const sep = base.endsWith('\n') || groups.startsWith('\n') ? '' : '\n';
-            out = `${base}${sep}${groups}`;
-        }
-        // Ensure a trailing blank line for prompt separation.
-        if (!out.endsWith('\n\n')) {
-            out = out.endsWith('\n') ? `${out}\n` : `${out}\n\n`;
-        }
-        return out;
+        return buildHelpInformation(super.helpInformation(), this);
     }
     /**
      * Public: tag an Option with a display group for help (root/app/plugin:<id>).
@@ -1863,15 +2249,8 @@ let GetDotenvCli$1 = class GetDotenvCli extends Command {
      * 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);
+    use(plugin, override) {
+        this._plugins.push({ plugin, override });
         return this;
     }
     /**
@@ -1879,24 +2258,52 @@ let GetDotenvCli$1 = class GetDotenvCli extends Command {
      * 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();
+        if (this._installed)
+            return;
+        if (this._installing) {
+            await this._installing;
+            return;
+        }
+        this._installing = (async () => {
+            // Install parent → children with host-created mounts (async-aware).
+            for (const entry of this._plugins) {
+                const p = entry.plugin;
+                await setupPluginTree(this, p);
+            }
+            this._installed = true;
+        })();
+        try {
+            await this._installing;
+        }
+        finally {
+            // leave _installing as resolved; subsequent calls return early via _installed
+        }
     }
     /**
      * Run afterResolve hooks for all plugins (parent → children).
      */
     async _runAfterResolve(ctx) {
-        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);
+        await runAfterResolveTree(this, this._plugins.map((e) => e.plugin), ctx);
     }
+}
+
+/**
+ * Base CLI options derived from the shared root option defaults.
+ * Used for type-safe initialization of CLI options bags.
+ */
+const baseGetDotenvCliOptions = baseRootOptionDefaults;
+
+/**
+ * Return the top-level root command for a given mount or action's thisCommand.
+ *
+ * @param cmd - any command (mount or thisCommand inside an action)
+ * @returns the root command instance
+ */
+const getRootCommand = (cmd) => {
+    let node = cmd;
+    while (node.parent)
+        node = node.parent;
+    return node;
 };
 
 /**
@@ -1904,199 +2311,295 @@ let GetDotenvCli$1 = class GetDotenvCli extends Command {
  * Centralizes construction and reduces inline casts at call sites.
  */
 const toHelpConfig = (merged, plugins) => {
-    const bag = {
+    return {
         ...merged,
         plugins: plugins ?? {},
     };
-    return bag;
 };
 
-/** src/cliHost/definePlugin.ts
- * Plugin contracts for the GetDotenv CLI host.
- *
- * This module exposes a structural public interface for the host that plugins
- * should use (GetDotenvCliPublic). Using a structural type at the seam avoids
- * nominal class identity issues (private fields) in downstream consumers.
+/**
+ * Compose a child-process env overlay from dotenv and the merged CLI options bag.
+ * Returns a shallow object including getDotenvCliOptions when serializable.
  */
-/* eslint-disable tsdoc/syntax */
-function definePlugin(spec) {
-    const { children = [], ...rest } = spec;
-    // Default to a strict empty-object schema so “no-config” plugins fail fast
-    // on unknown keys and provide a concrete {} at runtime.
-    const effectiveSchema = spec.configSchema ?? z.object({}).strict();
-    // Build base plugin first, then extend with instance-bound helpers.
-    const base = {
-        ...rest,
-        // Always carry a schema (strict empty by default) to simplify host logic
-        // and improve inference/ergonomics for plugin authors.
-        configSchema: effectiveSchema,
-        children: [...children],
-        use(child) {
-            this.children.push(child);
-            return this;
-        },
-    };
-    // Attach instance-bound helpers on the returned plugin object.
-    const extended = base;
-    extended.readConfig = function (_cli) {
-        // Config is stored per-plugin-instance by the host (WeakMap in computeContext).
-        const value = _getPluginConfigForInstance(extended);
-        if (value === undefined) {
-            // Guard: host has not resolved config yet (incorrect lifecycle usage).
-            throw new Error('Plugin config not available. Ensure resolveAndLoad() has been called before readConfig().');
-        }
-        return value;
-    };
-    // Plugin-bound dynamic option factory
-    extended.createPluginDynamicOption = function (cli, flags, desc, parser, defaultValue) {
-        return cli.createDynamicOption(flags, (cfg) => {
-            // Prefer the validated slice stored per instance; fallback to help-bag
-            // (by-id) so top-level `-h` can render effective defaults before resolve.
-            const fromStore = _getPluginConfigForInstance(extended);
-            const id = extended.id;
-            let fromBag;
-            if (!fromStore && id) {
-                const maybe = cfg.plugins[id];
-                if (maybe && typeof maybe === 'object') {
-                    fromBag = maybe;
-                }
-            }
-            // Always provide a concrete object to dynamic callbacks:
-            // - With a schema: computeContext stores the parsed object.
-            // - Without a schema: computeContext stores {}.
-            // - Help-time fallback: coalesce to {} when only a by-id bag exists.
-            const cfgVal = (fromStore ?? fromBag ?? {});
-            return desc(cfg, cfgVal);
-        }, parser, defaultValue);
-    };
-    return extended;
+function composeNestedEnv(merged, dotenv) {
+    const out = {};
+    for (const [k, v] of Object.entries(dotenv)) {
+        if (typeof v === 'string')
+            out[k] = v;
+    }
+    try {
+        const { logger: _omit, ...bag } = merged;
+        const txt = JSON.stringify(bag);
+        if (typeof txt === 'string')
+            out.getDotenvCliOptions = txt;
+    }
+    catch {
+        /* best-effort only */
+    }
+    return out;
 }
-
 /**
- * GetDotenvCli with root helpers as real class methods.
- * - attachRootOptions: installs legacy/base root flags on the command.
- * - passOptions: merges flags (parent \< current), computes dotenv context once,
- *   runs validation, and persists merged options for nested flows.
+ * Strip one layer of symmetric outer quotes (single or double) from a string.
+ *
+ * @param s - Input string.
+ */
+const stripOne = (s) => {
+    if (s.length < 2)
+        return s;
+    const a = s.charAt(0);
+    const b = s.charAt(s.length - 1);
+    const symmetric = (a === '"' && b === '"') || (a === "'" && b === "'");
+    return symmetric ? s.slice(1, -1) : s;
+};
+/**
+ * Preserve argv array for Node -e/--eval payloads under shell-off and
+ * peel one symmetric outer quote layer from the code argument.
  */
-class GetDotenvCli extends GetDotenvCli$1 {
-    /**
-     * Attach legacy root flags to this CLI instance. Defaults come from
-     * baseRootOptionDefaults when none are provided.
-     */
-    attachRootOptions(defaults) {
-        const d = (defaults ?? baseRootOptionDefaults);
-        attachRootOptions(this, d);
-        return this;
-    }
-    /**
-     * Install preSubcommand/preAction hooks that:
-     * - Merge options (parent round-trip + current invocation) using resolveCliOptions.
-     * - Persist the merged bag on the current command and on the host (for ergonomics).
-     * - Compute the dotenv context once via resolveAndLoad(serviceOptions).
-     * - Validate the composed env against discovered config (warn or --strict fail).
-     */
-    passOptions(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 behavior and ergonomic access).
-            thisCommand.getDotenvCliOptions =
-                merged;
-            this._setOptionsBag(merged);
-            // Build service options and compute context (always-on loader path).
-            const serviceOptions = getDotenvCliOptions2Options(merged);
-            await this.resolveAndLoad(serviceOptions);
-            // Refresh dynamic option descriptions using resolved config + plugin slices
-            try {
-                const ctx = this.getCtx();
-                const helpCfg = toHelpConfig(merged, ctx?.pluginConfigs ?? {});
-                this.evaluateDynamicOptions(helpCfg);
-            }
-            catch {
-                /* best-effort */
-            }
-            // Global validation: once after Phase C using config sources.
-            try {
-                const ctx = this.getCtx();
-                const dotenv = ctx?.dotenv ?? {};
-                const sources = await resolveGetDotenvConfigSources(import.meta.url);
-                const issues = validateEnvAgainstSources(dotenv, sources);
-                if (Array.isArray(issues) && issues.length > 0) {
-                    const logger = (merged
-                        .logger ?? console);
-                    const emit = logger.error ?? logger.log;
-                    issues.forEach((m) => {
-                        emit(m);
-                    });
-                    if (merged.strict)
-                        process.exit(1);
-                }
-            }
-            catch {
-                // Be tolerant: do not crash non-strict flows on unexpected validator failures.
-            }
-        });
-        // 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 helpCfg = toHelpConfig(merged, ctx?.pluginConfigs ?? {});
-                    this.evaluateDynamicOptions(helpCfg);
-                }
-                catch {
-                    /* tolerate */
-                }
-                try {
-                    const ctx = this.getCtx();
-                    const dotenv = (ctx?.dotenv ?? {});
-                    const sources = await resolveGetDotenvConfigSources(import.meta.url);
-                    const issues = validateEnvAgainstSources(dotenv, sources);
-                    if (Array.isArray(issues) && issues.length > 0) {
-                        const logger = (merged
-                            .logger ?? console);
-                        const emit = logger.error ?? logger.log;
-                        issues.forEach((m) => {
-                            emit(m);
-                        });
-                        if (merged.strict) {
-                            process.exit(1);
-                        }
-                    }
-                }
-                catch {
-                    // Tolerate validation side-effects in non-strict mode.
-                }
-            }
-        });
-        return this;
+function maybePreserveNodeEvalArgv(args) {
+    if (args.length >= 3) {
+        const first = (args[0] ?? '').toLowerCase();
+        const hasEval = args[1] === '-e' || args[1] === '--eval';
+        if (first === 'node' && hasEval) {
+            const copy = args.slice();
+            copy[2] = stripOne(copy[2] ?? '');
+            return copy;
+        }
     }
+    return args;
 }
+
 /**
- * Helper to retrieve the merged root options bag from any action handler
- * that only has access to thisCommand. Avoids structural casts.
+ * Retrieve the merged root options bag from the current command context.
+ * Climbs to the root `GetDotenvCli` instance to access the persisted options.
+ *
+ * @param cmd - The current command instance (thisCommand).
+ * @throws Error if the root is not a GetDotenvCli or options are missing.
  */
 const readMergedOptions = (cmd) => {
-    // Ascend to the root command
+    // Climb to the true root
     let root = cmd;
-    while (root.parent) {
+    while (root.parent)
         root = root.parent;
+    // Assert we ended at our host
+    if (!(root instanceof GetDotenvCli)) {
+        throw new Error('readMergedOptions: root command is not a GetDotenvCli.' +
+            'Ensure your CLI is constructed with GetDotenvCli.');
+    }
+    // Require passOptions() to have persisted the bag
+    const bag = root.getOptions();
+    if (!bag || typeof bag !== 'object') {
+        throw new Error('readMergedOptions: merged options are unavailable. ' +
+            'Call .passOptions() on the host before parsing.');
+    }
+    return bag;
+};
+
+/**
+ * Batch services (neutral): resolve command and shell settings.
+ * Shared by the generator path and the batch plugin to avoid circular deps.
+ */
+/**
+ * Resolve a command string from the {@link ScriptsTable} table.
+ * A script may be expressed as a string or an object with a `cmd` property.
+ *
+ * @param scripts - Optional scripts table.
+ * @param command - User-provided command name or string.
+ * @returns Resolved command string (falls back to the provided command).
+ */
+const resolveCommand = (scripts, command) => scripts && typeof scripts[command] === 'object'
+    ? scripts[command].cmd
+    : (scripts?.[command] ?? command);
+/**
+ * Resolve the shell setting for a given command:
+ * - If the script entry is an object, prefer its `shell` override.
+ * - Otherwise use the provided `shell` (string | boolean).
+ *
+ * @param scripts - Optional scripts table.
+ * @param command - User-provided command name or string.
+ * @param shell - Global shell preference (string | boolean).
+ */
+const resolveShell = (scripts, command, shell) => scripts && typeof scripts[command] === 'object'
+    ? (scripts[command].shell ?? false)
+    : (shell ?? false);
+
+/**
+ * Resolve a tri-state optional boolean flag under exactOptionalPropertyTypes.
+ * - If the user explicitly enabled the flag, return true.
+ * - If the user explicitly disabled (the "...-off" variant), return undefined (unset).
+ * - Otherwise, adopt the default (true → set; false/undefined → unset).
+ *
+ * @param exclude - The "on" flag value as parsed by Commander.
+ * @param excludeOff - The "off" toggle (present when specified) as parsed by Commander.
+ * @param defaultValue - The generator default to adopt when no explicit toggle is present.
+ * @returns boolean | undefined — use `undefined` to indicate "unset" (do not emit).
+ *
+ * @example
+ * ```ts
+ * resolveExclusion(undefined, undefined, true); // => true
+ * ```
+ */
+const resolveExclusion = (exclude, excludeOff, defaultValue) => exclude ? true : excludeOff ? undefined : defaultValue ? true : undefined;
+/**
+ * Resolve an optional flag with "--exclude-all" overrides.
+ * If excludeAll is set and the individual "...-off" is not, force true.
+ * If excludeAllOff is set and the individual flag is not explicitly set, unset.
+ * Otherwise, adopt the default (true → set; false/undefined → unset).
+ *
+ * @param exclude - Individual include/exclude flag.
+ * @param excludeOff - Individual "...-off" flag.
+ * @param defaultValue - Default for the individual flag.
+ * @param excludeAll - Global "exclude-all" flag.
+ * @param excludeAllOff - Global "exclude-all-off" flag.
+ *
+ * @example
+ * resolveExclusionAll(undefined, undefined, false, true, undefined) =\> true
+ */
+const resolveExclusionAll = (exclude, excludeOff, defaultValue, excludeAll, excludeAllOff) => 
+// Order of precedence:
+// 1) Individual explicit "on" wins outright.
+// 2) Individual explicit "off" wins over any global.
+// 3) Global exclude-all forces true when not explicitly turned off.
+// 4) Global exclude-all-off unsets when the individual wasn't explicitly enabled.
+// 5) Fall back to the default (true => set; false/undefined => unset).
+(() => {
+    // Individual "on"
+    if (exclude === true)
+        return true;
+    // Individual "off"
+    if (excludeOff === true)
+        return undefined;
+    // Global "exclude-all" ON (unless explicitly turned off)
+    if (excludeAll === true)
+        return true;
+    // Global "exclude-all-off" (unless explicitly enabled)
+    if (excludeAllOff === true)
+        return undefined;
+    // Default
+    return defaultValue ? true : undefined;
+})();
+/**
+ * exactOptionalPropertyTypes-safe setter for optional boolean flags:
+ * delete when undefined; assign when defined — without requiring an index signature on T.
+ *
+ * @typeParam T - Target object type.
+ * @param obj - The object to write to.
+ * @param key - The optional boolean property key of {@link T}.
+ * @param value - The value to set or `undefined` to unset.
+ *
+ * @remarks
+ * Writes through a local `Record<string, unknown>` view to avoid requiring an index signature on {@link T}.
+ */
+const setOptionalFlag = (obj, key, value) => {
+    const target = obj;
+    const k = key;
+    // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+    if (value === undefined)
+        delete target[k];
+    else
+        target[k] = value;
+};
+
+/**
+ * Merge and normalize raw Commander options (current + parent + defaults)
+ * into a GetDotenvCliOptions-like object. Types are intentionally wide to
+ * avoid cross-layer coupling; callers may cast as needed.
+ */
+const resolveCliOptions = (rawCliOptions, defaults, parentJson) => {
+    const parent = typeof parentJson === 'string' && parentJson.length > 0
+        ? JSON.parse(parentJson)
+        : undefined;
+    const { command, debugOff, excludeAll, excludeAllOff, excludeDynamicOff, excludeEnvOff, excludeGlobalOff, excludePrivateOff, excludePublicOff, loadProcessOff, logOff, entropyWarn, entropyWarnOff, scripts, shellOff, ...rest } = rawCliOptions;
+    const current = { ...rest };
+    if (typeof scripts === 'string') {
+        try {
+            current.scripts = JSON.parse(scripts);
+        }
+        catch {
+            // ignore parse errors; leave scripts undefined
+        }
+    }
+    const merged = defaultsDeep({}, defaults, parent ?? {}, current);
+    const d = defaults;
+    setOptionalFlag(merged, 'debug', resolveExclusion(merged.debug, debugOff, d.debug));
+    setOptionalFlag(merged, 'excludeDynamic', resolveExclusionAll(merged.excludeDynamic, excludeDynamicOff, d.excludeDynamic, excludeAll, excludeAllOff));
+    setOptionalFlag(merged, 'excludeEnv', resolveExclusionAll(merged.excludeEnv, excludeEnvOff, d.excludeEnv, excludeAll, excludeAllOff));
+    setOptionalFlag(merged, 'excludeGlobal', resolveExclusionAll(merged.excludeGlobal, excludeGlobalOff, d.excludeGlobal, excludeAll, excludeAllOff));
+    setOptionalFlag(merged, 'excludePrivate', resolveExclusionAll(merged.excludePrivate, excludePrivateOff, d.excludePrivate, excludeAll, excludeAllOff));
+    setOptionalFlag(merged, 'excludePublic', resolveExclusionAll(merged.excludePublic, excludePublicOff, d.excludePublic, excludeAll, excludeAllOff));
+    setOptionalFlag(merged, 'log', resolveExclusion(merged.log, logOff, d.log));
+    setOptionalFlag(merged, 'loadProcess', resolveExclusion(merged.loadProcess, loadProcessOff, d.loadProcess));
+    // warnEntropy (tri-state)
+    setOptionalFlag(merged, 'warnEntropy', resolveExclusion(merged.warnEntropy, entropyWarnOff, d.warnEntropy));
+    // Normalize shell for predictability: explicit default shell per OS.
+    const defaultShell = process.platform === 'win32' ? 'powershell.exe' : '/bin/bash';
+    let resolvedShell = merged.shell;
+    if (shellOff)
+        resolvedShell = false;
+    else if (resolvedShell === true || resolvedShell === undefined) {
+        resolvedShell = defaultShell;
+    }
+    else if (typeof resolvedShell !== 'string' &&
+        typeof defaults.shell === 'string') {
+        resolvedShell = defaults.shell;
+    }
+    merged.shell = resolvedShell;
+    const cmd = typeof command === 'string' ? command : undefined;
+    return cmd !== undefined ? { merged, command: cmd } : { merged };
+};
+
+const dropUndefined = (bag) => Object.fromEntries(Object.entries(bag).filter((e) => typeof e[1] === 'string'));
+/**
+ * Build a sanitized environment object for spawning child processes.
+ * Merges `base` and `overlay`, drops undefined values, and handles platform-specific
+ * normalization (e.g. case-insensitivity on Windows).
+ *
+ * @param base - Base environment (usually `process.env`).
+ * @param overlay - Environment variables to overlay.
+ */
+const buildSpawnEnv = (base, overlay) => {
+    const raw = {
+        ...(base ?? {}),
+        ...(overlay ?? {}),
+    };
+    // Drop undefined first
+    const entries = Object.entries(dropUndefined(raw));
+    if (process.platform === 'win32') {
+        // Windows: keys are case-insensitive; collapse duplicates
+        const byLower = new Map();
+        for (const [k, v] of entries) {
+            byLower.set(k.toLowerCase(), [k, v]); // last wins; preserve latest casing
+        }
+        const out = {};
+        for (const [, [k, v]] of byLower)
+            out[k] = v;
+        // HOME fallback from USERPROFILE (common expectation)
+        if (!Object.prototype.hasOwnProperty.call(out, 'HOME')) {
+            const up = out['USERPROFILE'];
+            if (typeof up === 'string' && up.length > 0)
+                out['HOME'] = up;
+        }
+        // Normalize TMP/TEMP coherence (pick any present; reflect to both)
+        const tmp = out['TMP'] ?? out['TEMP'];
+        if (typeof tmp === 'string' && tmp.length > 0) {
+            out['TMP'] = tmp;
+            out['TEMP'] = tmp;
+        }
+        return out;
+    }
+    // POSIX: keep keys as-is
+    const out = Object.fromEntries(entries);
+    // Ensure TMPDIR exists when any temp key is present (best-effort)
+    const tmpdir = out['TMPDIR'] ?? out['TMP'] ?? out['TEMP'];
+    if (typeof tmpdir === 'string' && tmpdir.length > 0) {
+        out['TMPDIR'] = tmpdir;
     }
-    const hostAny = root;
-    return typeof hostAny.getOptions === 'function'
-        ? hostAny.getOptions()
-        : root
-            .getDotenvCliOptions;
+    return out;
 };
 
-export { GetDotenvCli, definePlugin, readMergedOptions };
+/**
+ * Identity helper to define a scripts table while preserving a concrete TShell
+ * type parameter in downstream inference.
+ */
+const defineScripts = () => (t) => t;
+
+export { GetDotenvCli, baseGetDotenvCliOptions, buildSpawnEnv, composeNestedEnv, definePlugin, defineScripts, getRootCommand, maybePreserveNodeEvalArgv, readMergedOptions, resolveCliOptions, resolveCommand, resolveShell, runCommand, runCommandResult, stripOne, toHelpConfig };