@karmaniverous/get-dotenv 6.0.0-0 → 6.0.0

package/dist/cliHost.cjs

@@ -1,2078 +0,0 @@
-'use strict';
-
-var fs = require('fs-extra');
-var packageDirectory = require('package-directory');
-var path = require('path');
-var url = require('url');
-var YAML = require('yaml');
-var zod = require('zod');
-var commander = require('commander');
-var nanoid = require('nanoid');
-var dotenv = require('dotenv');
-var crypto = require('crypto');
-
-var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
-// 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)
-};
-
-/** @internal */
-const isPlainObject$1 = (value) => value !== null &&
-    typeof value === 'object' &&
-    Object.getPrototypeOf(value) === Object.prototype;
-const mergeInto = (target, source) => {
-    for (const [key, sVal] of Object.entries(source)) {
-        if (sVal === undefined)
-            continue; // do not overwrite with undefined
-        const tVal = target[key];
-        if (isPlainObject$1(tVal) && isPlainObject$1(sVal)) {
-            target[key] = mergeInto({ ...tVal }, sVal);
-        }
-        else if (isPlainObject$1(sVal)) {
-            target[key] = mergeInto({}, sVal);
-        }
-        else {
-            target[key] = sVal;
-        }
-    }
-    return target;
-};
-/**
- * Perform a deep defaults-style merge across plain objects. *
- * - Only merges plain objects (prototype === Object.prototype).
- * - Arrays and non-objects are replaced, not merged.
- * - `undefined` values are ignored and do not overwrite prior values.
- *
- * @typeParam T - The resulting shape after merging all layers.
- * @param layers - Zero or more partial layers in ascending precedence order.
- * @returns The merged object typed as {@link T}.
- *
- * @example
- * defaultsDeep(\{ a: 1, nested: \{ b: 2 \} \}, \{ nested: \{ b: 3, c: 4 \} \})
- * =\> \{ a: 1, nested: \{ b: 3, c: 4 \} \}
- */
-const defaultsDeep = (...layers) => {
-    const result = layers
-        .filter(Boolean)
-        .reduce((acc, layer) => mergeInto(acc, layer), {});
-    return result;
-};
-
-/**
- * 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 };
-};
-
-/**
- * Zod schemas for configuration files discovered by the new loader.
- *
- * Notes:
- * - RAW: all fields optional; shapes are stringly-friendly (paths may be string[] or string).
- * - RESOLVED: normalized shapes (paths always string[]).
- * - For JSON/YAML configs, the loader rejects "dynamic" and "schema" (JS/TS-only).
- */
-// String-only env value map
-const stringMap = zod.z.record(zod.z.string(), zod.z.string());
-const envStringMap = zod.z.record(zod.z.string(), stringMap);
-// Allow string[] or single string for "paths" in RAW; normalize later.
-const rawPathsSchema = zod.z.union([zod.z.array(zod.z.string()), zod.z.string()]).optional();
-const getDotenvConfigSchemaRaw = zod.z.object({
-    dotenvToken: zod.z.string().optional(),
-    privateToken: zod.z.string().optional(),
-    paths: rawPathsSchema,
-    loadProcess: zod.z.boolean().optional(),
-    log: zod.z.boolean().optional(),
-    shell: zod.z.union([zod.z.string(), zod.z.boolean()]).optional(),
-    scripts: zod.z.record(zod.z.string(), zod.z.unknown()).optional(), // Scripts validation left wide; generator validates elsewhere
-    requiredKeys: zod.z.array(zod.z.string()).optional(),
-    schema: zod.z.unknown().optional(), // JS/TS-only; loader rejects in JSON/YAML
-    vars: stringMap.optional(), // public, global
-    envVars: envStringMap.optional(), // public, per-env
-    // Dynamic in config (JS/TS only). JSON/YAML loader will reject if set.
-    dynamic: zod.z.unknown().optional(),
-    // Per-plugin config bag; validated by plugins/host when used.
-    plugins: zod.z.record(zod.z.string(), zod.z.unknown()).optional(),
-});
-// Normalize paths to string[]
-const normalizePaths = (p) => p === undefined ? undefined : Array.isArray(p) ? p : [p];
-const getDotenvConfigSchemaResolved = getDotenvConfigSchemaRaw.transform((raw) => ({
-    ...raw,
-    paths: normalizePaths(raw.paths),
-}));
-
-// Discovery candidates (first match wins per scope/privacy).
-// Order preserves historical JSON/YAML precedence; JS/TS added afterwards.
-const PUBLIC_FILENAMES = [
-    'getdotenv.config.json',
-    'getdotenv.config.yaml',
-    'getdotenv.config.yml',
-    'getdotenv.config.js',
-    'getdotenv.config.mjs',
-    'getdotenv.config.cjs',
-    'getdotenv.config.ts',
-    'getdotenv.config.mts',
-    'getdotenv.config.cts',
-];
-const LOCAL_FILENAMES = [
-    'getdotenv.config.local.json',
-    'getdotenv.config.local.yaml',
-    'getdotenv.config.local.yml',
-    'getdotenv.config.local.js',
-    'getdotenv.config.local.mjs',
-    'getdotenv.config.local.cjs',
-    'getdotenv.config.local.ts',
-    'getdotenv.config.local.mts',
-    'getdotenv.config.local.cts',
-];
-const isYaml = (p) => ['.yaml', '.yml'].includes(path.extname(p).toLowerCase());
-const isJson = (p) => path.extname(p).toLowerCase() === '.json';
-const isJsOrTs = (p) => ['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts'].includes(path.extname(p).toLowerCase());
-// --- Internal JS/TS module loader helpers (default export) ---
-const importDefault$1 = async (fileUrl) => {
-    const mod = (await import(fileUrl));
-    return mod.default;
-};
-const cacheName = (absPath, suffix) => {
-    // sanitized filename with suffix; recompile on mtime changes not tracked here (simplified)
-    const base = path.basename(absPath).replace(/[^a-zA-Z0-9._-]/g, '_');
-    return `${base}.${suffix}.mjs`;
-};
-const ensureDir = async (dir) => {
-    await fs.ensureDir(dir);
-    return dir;
-};
-const loadJsTsDefault = async (absPath) => {
-    const fileUrl = url.pathToFileURL(absPath).toString();
-    const ext = path.extname(absPath).toLowerCase();
-    if (ext === '.js' || ext === '.mjs' || ext === '.cjs') {
-        return importDefault$1(fileUrl);
-    }
-    // Try direct import first in case a TS loader is active.
-    try {
-        const val = await importDefault$1(fileUrl);
-        if (val)
-            return val;
-    }
-    catch {
-        /* fallthrough */
-    }
-    // esbuild bundle to a temp ESM file
-    try {
-        const esbuild = (await import('esbuild'));
-        const outDir = await ensureDir(path.resolve('.tsbuild', 'getdotenv-config'));
-        const outfile = path.join(outDir, cacheName(absPath, 'bundle'));
-        await esbuild.build({
-            entryPoints: [absPath],
-            bundle: true,
-            platform: 'node',
-            format: 'esm',
-            target: 'node20',
-            outfile,
-            sourcemap: false,
-            logLevel: 'silent',
-        });
-        return await importDefault$1(url.pathToFileURL(outfile).toString());
-    }
-    catch {
-        /* fallthrough to TS transpile */
-    }
-    // typescript.transpileModule simple transpile (single-file)
-    try {
-        const ts = (await import('typescript'));
-        const src = await fs.readFile(absPath, 'utf-8');
-        const out = ts.transpileModule(src, {
-            compilerOptions: {
-                module: 'ESNext',
-                target: 'ES2022',
-                moduleResolution: 'NodeNext',
-            },
-        }).outputText;
-        const outDir = await ensureDir(path.resolve('.tsbuild', 'getdotenv-config'));
-        const outfile = path.join(outDir, cacheName(absPath, 'ts'));
-        await fs.writeFile(outfile, out, 'utf-8');
-        return await importDefault$1(url.pathToFileURL(outfile).toString());
-    }
-    catch {
-        throw new Error(`Unable to load JS/TS config: ${absPath}. Install 'esbuild' for robust bundling or ensure a TS loader.`);
-    }
-};
-/**
- * Discover JSON/YAML config files in the packaged root and project root.
- * Order: packaged public → project public → project local. */
-const discoverConfigFiles = async (importMetaUrl) => {
-    const files = [];
-    // Packaged root via importMetaUrl (optional)
-    if (importMetaUrl) {
-        const fromUrl = url.fileURLToPath(importMetaUrl);
-        const packagedRoot = await packageDirectory.packageDirectory({ cwd: fromUrl });
-        if (packagedRoot) {
-            for (const name of PUBLIC_FILENAMES) {
-                const p = path.join(packagedRoot, name);
-                if (await fs.pathExists(p)) {
-                    files.push({ path: p, privacy: 'public', scope: 'packaged' });
-                    break; // only one public file expected per scope
-                }
-            }
-            // By policy, packaged .local is not expected; skip even if present.
-        }
-    }
-    // Project root (from current working directory)
-    const projectRoot = await packageDirectory.packageDirectory();
-    if (projectRoot) {
-        for (const name of PUBLIC_FILENAMES) {
-            const p = path.join(projectRoot, name);
-            if (await fs.pathExists(p)) {
-                files.push({ path: p, privacy: 'public', scope: 'project' });
-                break;
-            }
-        }
-        for (const name of LOCAL_FILENAMES) {
-            const p = path.join(projectRoot, name);
-            if (await fs.pathExists(p)) {
-                files.push({ path: p, privacy: 'local', scope: 'project' });
-                break;
-            }
-        }
-    }
-    return files;
-};
-/**
- * Load a single config file (JSON/YAML). JS/TS is not supported in this step.
- * Validates with Zod RAW schema, then normalizes to RESOLVED.
- *
- * For JSON/YAML: if a "dynamic" property is present, throws with guidance.
- * For JS/TS: default export is loaded; "dynamic" is allowed.
- */
-const loadConfigFile = async (filePath) => {
-    let raw = {};
-    try {
-        const abs = path.resolve(filePath);
-        if (isJsOrTs(abs)) {
-            // JS/TS support: load default export via robust pipeline.
-            const mod = await loadJsTsDefault(abs);
-            raw = mod ?? {};
-        }
-        else {
-            const txt = await fs.readFile(abs, 'utf-8');
-            raw = isJson(abs) ? JSON.parse(txt) : isYaml(abs) ? YAML.parse(txt) : {};
-        }
-    }
-    catch (err) {
-        throw new Error(`Failed to read/parse config: ${filePath}. ${String(err)}`);
-    }
-    // Validate RAW
-    const parsed = getDotenvConfigSchemaRaw.safeParse(raw);
-    if (!parsed.success) {
-        const msgs = parsed.error.issues
-            .map((i) => `${i.path.join('.')}: ${i.message}`)
-            .join('\n');
-        throw new Error(`Invalid config ${filePath}:\n${msgs}`);
-    }
-    // Disallow dynamic and schema in JSON/YAML; allow both in JS/TS.
-    if (!isJsOrTs(filePath) &&
-        (parsed.data.dynamic !== undefined || parsed.data.schema !== undefined)) {
-        throw new Error(`Config ${filePath} specifies unsupported keys for JSON/YAML. ` +
-            `Use JS/TS config for "dynamic" or "schema".`);
-    }
-    return getDotenvConfigSchemaResolved.parse(parsed.data);
-};
-/**
- * Discover and load configs into resolved shapes, ordered by scope/privacy.
- * JSON/YAML/JS/TS supported; first match per scope/privacy applies.
- */
-const resolveGetDotenvConfigSources = async (importMetaUrl) => {
-    const discovered = await discoverConfigFiles(importMetaUrl);
-    const result = {};
-    for (const f of discovered) {
-        const cfg = await loadConfigFile(f.path);
-        if (f.scope === 'packaged') {
-            // packaged public only
-            result.packaged = cfg;
-        }
-        else {
-            result.project ??= {};
-            if (f.privacy === 'public')
-                result.project.public = cfg;
-            else
-                result.project.local = cfg;
-        }
-    }
-    return result;
-};
-
-/**
- * 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/GetDotenvOptions.ts
-const getDotenvOptionsFilename = 'getdotenv.config.json';
-/**
- * Converts programmatic CLI options to `getDotenv` options. *
- * @param cliOptions - CLI options. Defaults to `{}`.
- *
- * @returns `getDotenv` options.
- */
-const getDotenvCliOptions2Options = ({ paths, pathsDelimiter, pathsDelimiterPattern, vars, varsAssignor, varsAssignorPattern, varsDelimiter, varsDelimiterPattern, ...rest }) => {
-    /**
-     * Convert CLI-facing string options into {@link GetDotenvOptions}.
-     *
-     * - Splits {@link GetDotenvCliOptions.paths} using either a delimiter   *   or a regular expression pattern into a string array.   * - Parses {@link GetDotenvCliOptions.vars} as space-separated `KEY=VALUE`
-     *   pairs (configurable delimiters) into a {@link ProcessEnv}.
-     * - Drops CLI-only keys that have no programmatic equivalent.
-     *
-     * @remarks
-     * Follows exact-optional semantics by not emitting undefined-valued entries.
-     */
-    // Drop CLI-only keys (debug/scripts) without relying on Record casts.
-    // Create a shallow copy then delete optional CLI-only keys if present.
-    const restObj = { ...rest };
-    delete restObj.debug;
-    delete restObj.scripts;
-    const splitBy = (value, delim, pattern) => (value ? value.split(pattern ? RegExp(pattern) : (delim ?? ' ')) : []);
-    // Tolerate vars as either a CLI string ("A=1 B=2") or an object map.
-    let parsedVars;
-    if (typeof vars === 'string') {
-        const kvPairs = splitBy(vars, varsDelimiter, varsDelimiterPattern).map((v) => v.split(varsAssignorPattern
-            ? RegExp(varsAssignorPattern)
-            : (varsAssignor ?? '=')));
-        parsedVars = Object.fromEntries(kvPairs);
-    }
-    else if (vars && typeof vars === 'object' && !Array.isArray(vars)) {
-        // Keep only string or undefined values to match ProcessEnv.
-        const entries = Object.entries(vars).filter(([k, v]) => typeof k === 'string' && (typeof v === 'string' || v === undefined));
-        parsedVars = Object.fromEntries(entries);
-    }
-    // Drop undefined-valued entries at the converter stage to match ProcessEnv
-    // expectations and the compat test assertions.
-    if (parsedVars) {
-        parsedVars = Object.fromEntries(Object.entries(parsedVars).filter(([, v]) => v !== undefined));
-    }
-    // Tolerate paths as either a delimited string or string[]
-    // Use a locally cast union type to avoid lint warnings about always-falsy conditions
-    // under the RootOptionsShape (which declares paths as string | undefined).
-    const pathsAny = paths;
-    const pathsOut = Array.isArray(pathsAny)
-        ? pathsAny.filter((p) => typeof p === 'string')
-        : splitBy(pathsAny, pathsDelimiter, pathsDelimiterPattern);
-    // Preserve exactOptionalPropertyTypes: only include keys when defined.
-    return {
-        ...restObj,
-        ...(pathsOut.length > 0 ? { paths: pathsOut } : {}),
-        ...(parsedVars !== undefined ? { vars: parsedVars } : {}),
-    };
-};
-const resolveGetDotenvOptions = async (customOptions) => {
-    /**
-     * Resolve {@link GetDotenvOptions} by layering defaults in ascending precedence:
-     *
-     * 1. Base defaults derived from the CLI generator defaults
-     *    ({@link baseGetDotenvCliOptions}).
-     * 2. Local project overrides from a `getdotenv.config.json` in the nearest
-     *    package root (if present).
-     * 3. The provided {@link customOptions}.
-     *
-     * The result preserves explicit empty values and drops only `undefined`.
-     *
-     * @returns Fully-resolved {@link GetDotenvOptions}.
-     *
-     * @example
-     * ```ts
-     * const options = await resolveGetDotenvOptions({ env: 'dev' });
-     * ```
-     */
-    const localPkgDir = await packageDirectory.packageDirectory();
-    const localOptionsPath = localPkgDir
-        ? path.join(localPkgDir, getDotenvOptionsFilename)
-        : undefined;
-    // 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: Object.fromEntries(Object.entries(result.vars ?? {}).filter(([, v]) => v !== undefined)),
-    };
-};
-
-/**
- * Dotenv expansion utilities.
- *
- * This module implements recursive expansion of environment-variable
- * references in strings and records. It supports both whitespace and
- * bracket syntaxes with optional defaults:
- *
- * - Whitespace: `$VAR[:default]`
- * - Bracketed: `${VAR[:default]}`
- *
- * Escaped dollar signs (`\$`) are preserved.
- * Unknown variables resolve to empty string unless a default is provided.
- */
-/**
- * Like String.prototype.search but returns the last index.
- * @internal
- */
-const searchLast = (str, rgx) => {
-    const matches = Array.from(str.matchAll(rgx));
-    return matches.length > 0 ? (matches.slice(-1)[0]?.index ?? -1) : -1;
-};
-const replaceMatch = (value, match, ref) => {
-    /**
-     * @internal
-     */
-    const group = match[0];
-    const key = match[1];
-    const defaultValue = match[2];
-    if (!key)
-        return value;
-    const replacement = value.replace(group, ref[key] ?? defaultValue ?? '');
-    return interpolate(replacement, ref);
-};
-const interpolate = (value = '', ref = {}) => {
-    /**
-     * @internal
-     */
-    // if value is falsy, return it as is
-    if (!value)
-        return value;
-    // get position of last unescaped dollar sign
-    const lastUnescapedDollarSignIndex = searchLast(value, /(?!(?<=\\))\$/g);
-    // return value if none found
-    if (lastUnescapedDollarSignIndex === -1)
-        return value;
-    // evaluate the value tail
-    const tail = value.slice(lastUnescapedDollarSignIndex);
-    // find whitespace pattern: $KEY:DEFAULT
-    const whitespacePattern = /^\$([\w]+)(?::([^\s]*))?/;
-    const whitespaceMatch = whitespacePattern.exec(tail);
-    if (whitespaceMatch != null)
-        return replaceMatch(value, whitespaceMatch, ref);
-    else {
-        // find bracket pattern: ${KEY:DEFAULT}
-        const bracketPattern = /^\${([\w]+)(?::([^}]*))?}/;
-        const bracketMatch = bracketPattern.exec(tail);
-        if (bracketMatch != null)
-            return replaceMatch(value, bracketMatch, ref);
-    }
-    return value;
-};
-/**
- * Recursively expands environment variables in a string. Variables may be
- * presented with optional default as `$VAR[:default]` or `${VAR[:default]}`.
- * Unknown variables will expand to an empty string.
- *
- * @param value - The string to expand.
- * @param ref - The reference object to use for variable expansion.
- * @returns The expanded string.
- *
- * @example
- * ```ts
- * process.env.FOO = 'bar';
- * dotenvExpand('Hello $FOO'); // "Hello bar"
- * dotenvExpand('Hello $BAZ:world'); // "Hello world"
- * ```
- *
- * @remarks
- * The expansion is recursive. If a referenced variable itself contains
- * references, those will also be expanded until a stable value is reached.
- * Escaped references (e.g. `\$FOO`) are preserved as literals.
- */
-const dotenvExpand = (value, ref = process.env) => {
-    const result = interpolate(value, ref);
-    return result ? result.replace(/\\\$/g, '$') : undefined;
-};
-/**
- * Recursively expands environment variables in the values of a JSON object.
- * Variables may be presented with optional default as `$VAR[:default]` or
- * `${VAR[:default]}`. Unknown variables will expand to an empty string.
- *
- * @param values - The values object to expand.
- * @param options - Expansion options.
- * @returns The value object with expanded string values.
- *
- * @example
- * ```ts
- * process.env.FOO = 'bar';
- * dotenvExpandAll({ A: '$FOO', B: 'x${FOO}y' });
- * // => { A: "bar", B: "xbary" }
- * ```
- *
- * @remarks
- * Options:
- * - ref: The reference object to use for expansion (defaults to process.env).
- * - progressive: Whether to progressively add expanded values to the set of
- *   reference keys.
- *
- * When `progressive` is true, each expanded key becomes available for
- * subsequent expansions in the same object (left-to-right by object key order).
- */
-const dotenvExpandAll = (values = {}, options = {}) => Object.keys(values).reduce((acc, key) => {
-    const { ref = process.env, progressive = false } = options;
-    acc[key] = dotenvExpand(values[key], {
-        ...ref,
-        ...(progressive ? acc : {}),
-    });
-    return acc;
-}, {});
-/**
- * Recursively expands environment variables in a string using `process.env` as
- * the expansion reference. Variables may be presented with optional default as
- * `$VAR[:default]` or `${VAR[:default]}`. Unknown variables will expand to an
- * empty string.
- *
- * @param value - The string to expand.
- * @returns The expanded string.
- *
- * @example
- * ```ts
- * process.env.FOO = 'bar';
- * dotenvExpandFromProcessEnv('Hello $FOO'); // "Hello bar"
- * ```
- */
-const dotenvExpandFromProcessEnv = (value) => dotenvExpand(value, process.env);
-
-/* 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.
- */
-const attachRootOptions = (program, defaults, opts) => {
-    // 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];
-            last.__group = group;
-        }
-    };
-    const originalAddOption = program.addOption.bind(program);
-    const originalOption = program.option.bind(program);
-    program.addOption = function patchedAdd(opt) {
-        opt.__group = 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);
-    if (opts?.includeCommandOption === true) {
-        p = p.option('-c, --command <string>', 'command executed according to the --shell option, conflicts with cmd subcommand (dotenv-expanded)', 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 c = cfg;
-        const allOn = !!c.excludeDynamic &&
-            ((!!c.excludeEnv && !!c.excludeGlobal) ||
-                (!!c.excludePrivate && !!c.excludePublic));
-        const suffix = allOn ? ' (default)' : '';
-        return `exclude all dotenv variables from loading ON${suffix}`;
-    })
-        .conflicts('excludeAllOff'))
-        .addOption(new commander.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 commander.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;
-};
-
-/**
- * Zod schemas for programmatic GetDotenv options.
- *
- * NOTE: These schemas are introduced without wiring to avoid behavior changes.
- * Legacy paths continue to use existing types/logic. The new plugin host will
- * use these schemas in strict mode; legacy paths will adopt them in warn mode
- * later per the staged plan.
- */
-// Minimal process env representation: string values or undefined to indicate "unset".
-const processEnvSchema = zod.z.record(zod.z.string(), zod.z.string().optional());
-// RAW: all fields optional — undefined means "inherit" from lower layers.
-const getDotenvOptionsSchemaRaw = zod.z.object({
-    defaultEnv: zod.z.string().optional(),
-    dotenvToken: zod.z.string().optional(),
-    dynamicPath: zod.z.string().optional(),
-    // Dynamic map is intentionally wide for now; refine once sources are normalized.
-    dynamic: zod.z.record(zod.z.string(), zod.z.unknown()).optional(),
-    env: zod.z.string().optional(),
-    excludeDynamic: zod.z.boolean().optional(),
-    excludeEnv: zod.z.boolean().optional(),
-    excludeGlobal: zod.z.boolean().optional(),
-    excludePrivate: zod.z.boolean().optional(),
-    excludePublic: zod.z.boolean().optional(),
-    loadProcess: zod.z.boolean().optional(),
-    log: zod.z.boolean().optional(),
-    outputPath: zod.z.string().optional(),
-    paths: zod.z.array(zod.z.string()).optional(),
-    privateToken: zod.z.string().optional(),
-    vars: processEnvSchema.optional(),
-    // Host-only feature flag: guarded integration of config loader/overlay
-    useConfigLoader: zod.z.boolean().optional(),
-});
-// RESOLVED: service-boundary contract (post-inheritance).
-// For Step A, keep identical to RAW (no behavior change). Later stages will// materialize required defaults and narrow shapes as resolution is wired.
-const getDotenvOptionsSchemaResolved = getDotenvOptionsSchemaRaw;
-
-const applyKv = (current, kv) => {
-    if (!kv || Object.keys(kv).length === 0)
-        return current;
-    const expanded = dotenvExpandAll(kv, { ref: current, progressive: true });
-    return { ...current, ...expanded };
-};
-const applyConfigSlice = (current, cfg, env) => {
-    if (!cfg)
-        return current;
-    // kind axis: global then env (env overrides global)
-    const afterGlobal = applyKv(current, cfg.vars);
-    const envKv = env && cfg.envVars ? cfg.envVars[env] : undefined;
-    return applyKv(afterGlobal, envKv);
-};
-/**
- * Overlay config-provided values onto a base ProcessEnv using precedence axes:
- * - kind: env \> global
- * - privacy: local \> public
- * - source: project \> packaged \> base
- *
- * Programmatic explicit vars (if provided) override all config slices.
- * Progressive expansion is applied within each slice.
- */
-const overlayEnv = ({ base, env, configs, programmaticVars, }) => {
-    let current = { ...base };
-    // Source: packaged (public -> local)
-    current = applyConfigSlice(current, configs.packaged, env);
-    // Packaged "local" is not expected by policy; if present, honor it.
-    // We do not have a separate object for packaged.local in sources, keep as-is.
-    // Source: project (public -> local)
-    current = applyConfigSlice(current, configs.project?.public, env);
-    current = applyConfigSlice(current, configs.project?.local, env);
-    // Programmatic explicit vars (top of static tier)
-    if (programmaticVars) {
-        const toApply = Object.fromEntries(Object.entries(programmaticVars).filter(([_k, v]) => typeof v === 'string'));
-        current = applyKv(current, toApply);
-    }
-    return current;
-};
-
-/** src/diagnostics/entropy.ts
- * Entropy diagnostics (presentation-only).
- * - Gated by min length and printable ASCII.
- * - Warn once per key per run when bits/char \>= threshold.
- * - Supports whitelist patterns to suppress known-noise keys.
- */
-const warned = new Set();
-const isPrintableAscii = (s) => /^[\x20-\x7E]+$/.test(s);
-const compile$1 = (patterns) => (patterns ?? []).map((p) => new RegExp(p, 'i'));
-const whitelisted = (key, regs) => regs.some((re) => re.test(key));
-const shannonBitsPerChar = (s) => {
-    const freq = new Map();
-    for (const ch of s)
-        freq.set(ch, (freq.get(ch) ?? 0) + 1);
-    const n = s.length;
-    let h = 0;
-    for (const c of freq.values()) {
-        const p = c / n;
-        h -= p * Math.log2(p);
-    }
-    return h;
-};
-/**
- * Maybe emit a one-line entropy warning for a key.
- * Caller supplies an `emit(line)` function; the helper ensures once-per-key.
- */
-const maybeWarnEntropy = (key, value, origin, opts, emit) => {
-    if (!opts || opts.warnEntropy === false)
-        return;
-    if (warned.has(key))
-        return;
-    const v = value ?? '';
-    const minLen = Math.max(0, opts.entropyMinLength ?? 16);
-    const threshold = opts.entropyThreshold ?? 3.8;
-    if (v.length < minLen)
-        return;
-    if (!isPrintableAscii(v))
-        return;
-    const wl = compile$1(opts.entropyWhitelist);
-    if (whitelisted(key, wl))
-        return;
-    const bpc = shannonBitsPerChar(v);
-    if (bpc >= threshold) {
-        warned.add(key);
-        emit(`[entropy] key=${key} score=${bpc.toFixed(2)} len=${String(v.length)} origin=${origin}`);
-    }
-};
-
-const DEFAULT_PATTERNS = [
-    '\\bsecret\\b',
-    '\\btoken\\b',
-    '\\bpass(word)?\\b',
-    '\\bapi[_-]?key\\b',
-    '\\bkey\\b',
-];
-const compile = (patterns) => (patterns && patterns.length > 0 ? patterns : DEFAULT_PATTERNS).map((p) => new RegExp(p, 'i'));
-const shouldRedactKey = (key, regs) => regs.some((re) => re.test(key));
-const MASK = '[redacted]';
-/**
- * Produce a shallow redacted copy of an env-like object for display.
- */
-const redactObject = (obj, opts) => {
-    if (!opts?.redact)
-        return { ...obj };
-    const regs = compile(opts.redactPatterns);
-    const out = {};
-    for (const [k, v] of Object.entries(obj)) {
-        out[k] = v && shouldRedactKey(k, regs) ? MASK : v;
-    }
-    return out;
-};
-
-/**
- * Asynchronously read a dotenv file & parse it into an object.
- *
- * @param path - Path to dotenv file.
- * @returns The parsed dotenv object.
- */
-const readDotenv = async (path) => {
-    try {
-        return (await fs.exists(path)) ? dotenv.parse(await fs.readFile(path)) : {};
-    }
-    catch {
-        return {};
-    }
-};
-
-const importDefault = async (fileUrl) => {
-    const mod = (await import(fileUrl));
-    return mod.default;
-};
-const cacheHash = (absPath, mtimeMs) => crypto.createHash('sha1')
-    .update(absPath)
-    .update(String(mtimeMs))
-    .digest('hex')
-    .slice(0, 12);
-/**
- * Remove older compiled cache files for a given source base name, keeping
- * at most `keep` most-recent files. Errors are ignored by design.
- */
-const cleanupOldCacheFiles = async (cacheDir, baseName, keep = Math.max(1, Number.parseInt(process.env.GETDOTENV_CACHE_KEEP ?? '2'))) => {
-    try {
-        const entries = await fs.readdir(cacheDir);
-        const mine = entries
-            .filter((f) => f.startsWith(`${baseName}.`) && f.endsWith('.mjs'))
-            .map((f) => path.join(cacheDir, f));
-        if (mine.length <= keep)
-            return;
-        const stats = await Promise.all(mine.map(async (p) => ({ p, mtimeMs: (await fs.stat(p)).mtimeMs })));
-        stats.sort((a, b) => b.mtimeMs - a.mtimeMs);
-        const toDelete = stats.slice(keep).map((s) => s.p);
-        await Promise.all(toDelete.map(async (p) => {
-            try {
-                await fs.remove(p);
-            }
-            catch {
-                // best-effort cleanup
-            }
-        }));
-    }
-    catch {
-        // best-effort cleanup
-    }
-};
-/**
- * Load a module default export from a JS/TS file with robust fallbacks:
- * - .js/.mjs/.cjs: direct import * - .ts/.mts/.cts/.tsx:
- *   1) try direct import (if a TS loader is active),
- *   2) esbuild bundle to a temp ESM file,
- *   3) typescript.transpileModule fallback for simple modules.
- *
- * @param absPath - absolute path to source file
- * @param cacheDirName - cache subfolder under .tsbuild
- */
-const loadModuleDefault = async (absPath, cacheDirName) => {
-    const ext = path.extname(absPath).toLowerCase();
-    const fileUrl = url.pathToFileURL(absPath).toString();
-    if (!['.ts', '.mts', '.cts', '.tsx'].includes(ext)) {
-        return importDefault(fileUrl);
-    }
-    // Try direct import first (TS loader active)
-    try {
-        const dyn = await importDefault(fileUrl);
-        if (dyn)
-            return dyn;
-    }
-    catch {
-        /* fall through */
-    }
-    const stat = await fs.stat(absPath);
-    const hash = cacheHash(absPath, stat.mtimeMs);
-    const cacheDir = path.resolve('.tsbuild', cacheDirName);
-    await fs.ensureDir(cacheDir);
-    const cacheFile = path.join(cacheDir, `${path.basename(absPath)}.${hash}.mjs`);
-    // Try esbuild
-    try {
-        const esbuild = (await import('esbuild'));
-        await esbuild.build({
-            entryPoints: [absPath],
-            bundle: true,
-            platform: 'node',
-            format: 'esm',
-            target: 'node20',
-            outfile: cacheFile,
-            sourcemap: false,
-            logLevel: 'silent',
-        });
-        const result = await importDefault(url.pathToFileURL(cacheFile).toString());
-        // Best-effort: trim older cache files for this source.
-        await cleanupOldCacheFiles(cacheDir, path.basename(absPath));
-        return result;
-    }
-    catch {
-        /* fall through to TS transpile */
-    }
-    // TypeScript transpile fallback
-    try {
-        const ts = (await import('typescript'));
-        const code = await fs.readFile(absPath, 'utf-8');
-        const out = ts.transpileModule(code, {
-            compilerOptions: {
-                module: 'ESNext',
-                target: 'ES2022',
-                moduleResolution: 'NodeNext',
-            },
-        }).outputText;
-        await fs.writeFile(cacheFile, out, 'utf-8');
-        const result = await importDefault(url.pathToFileURL(cacheFile).toString());
-        // Best-effort: trim older cache files for this source.
-        await cleanupOldCacheFiles(cacheDir, path.basename(absPath));
-        return result;
-    }
-    catch {
-        // Caller decides final error wording; rethrow for upstream mapping.
-        throw new Error(`Unable to load JS/TS module: ${absPath}. Install 'esbuild' or ensure a TS loader.`);
-    }
-};
-
-/**
- * Asynchronously process dotenv files of the form `.env[.<ENV>][.<PRIVATE_TOKEN>]`
- *
- * @param options - `GetDotenvOptions` object
- * @returns The combined parsed dotenv object.
- * * @example Load from the project root with default tokens
- * ```ts
- * const vars = await getDotenv();
- * console.log(vars.MY_SETTING);
- * ```
- *
- * @example Load from multiple paths and a specific environment
- * ```ts
- * const vars = await getDotenv({
- *   env: 'dev',
- *   dotenvToken: '.testenv',
- *   privateToken: 'secret',
- *   paths: ['./', './packages/app'],
- * });
- * ```
- *
- * @example Use dynamic variables
- * ```ts
- * // .env.js default-exports: { DYNAMIC: ({ PREV }) => `${PREV}-suffix` }
- * const vars = await getDotenv({ dynamicPath: '.env.js' });
- * ```
- *
- * @remarks
- * - When {@link GetDotenvOptions.loadProcess} is true, the resulting variables are merged
- *   into `process.env` as a side effect.
- * - When {@link GetDotenvOptions.outputPath} is provided, a consolidated dotenv file is written.
- *   The path is resolved after expansion, so it may reference previously loaded vars.
- *
- * @throws Error when a dynamic module is present but cannot be imported.
- * @throws Error when an output path was requested but could not be resolved.
- */
-const getDotenv = async (options = {}) => {
-    // Apply defaults.
-    const { defaultEnv, dotenvToken = '.env', dynamicPath, env, excludeDynamic = false, excludeEnv = false, excludeGlobal = false, excludePrivate = false, excludePublic = false, loadProcess = false, log = false, logger = console, outputPath, paths = [], privateToken = 'local', vars = {}, } = await resolveGetDotenvOptions(options);
-    // Read .env files.
-    const loaded = paths.length
-        ? await paths.reduce(async (e, p) => {
-            const publicGlobal = excludePublic || excludeGlobal
-                ? Promise.resolve({})
-                : readDotenv(path.resolve(p, dotenvToken));
-            const publicEnv = excludePublic || excludeEnv || (!env && !defaultEnv)
-                ? Promise.resolve({})
-                : readDotenv(path.resolve(p, `${dotenvToken}.${env ?? defaultEnv ?? ''}`));
-            const privateGlobal = excludePrivate || excludeGlobal
-                ? Promise.resolve({})
-                : readDotenv(path.resolve(p, `${dotenvToken}.${privateToken}`));
-            const privateEnv = excludePrivate || excludeEnv || (!env && !defaultEnv)
-                ? Promise.resolve({})
-                : readDotenv(path.resolve(p, `${dotenvToken}.${env ?? defaultEnv ?? ''}.${privateToken}`));
-            const [eResolved, publicGlobalResolved, publicEnvResolved, privateGlobalResolved, privateEnvResolved,] = await Promise.all([
-                e,
-                publicGlobal,
-                publicEnv,
-                privateGlobal,
-                privateEnv,
-            ]);
-            return {
-                ...eResolved,
-                ...publicGlobalResolved,
-                ...publicEnvResolved,
-                ...privateGlobalResolved,
-                ...privateEnvResolved,
-            };
-        }, Promise.resolve({}))
-        : {};
-    const outputKey = nanoid.nanoid();
-    const dotenv = dotenvExpandAll({
-        ...loaded,
-        ...vars,
-        ...(outputPath ? { [outputKey]: outputPath } : {}),
-    }, { progressive: true });
-    // Process dynamic variables. Programmatic option takes precedence over path.
-    if (!excludeDynamic) {
-        let dynamic = undefined;
-        if (options.dynamic && Object.keys(options.dynamic).length > 0) {
-            dynamic = options.dynamic;
-        }
-        else if (dynamicPath) {
-            const absDynamicPath = path.resolve(dynamicPath);
-            if (await fs.exists(absDynamicPath)) {
-                try {
-                    dynamic = await loadModuleDefault(absDynamicPath, 'getdotenv-dynamic');
-                }
-                catch {
-                    // Preserve legacy error text for compatibility with tests/docs.
-                    throw new Error(`Unable to load dynamic TypeScript file: ${absDynamicPath}. ` +
-                        `Install 'esbuild' (devDependency) to enable TypeScript dynamic modules.`);
-                }
-            }
-        }
-        if (dynamic) {
-            try {
-                for (const key in dynamic)
-                    Object.assign(dotenv, {
-                        [key]: typeof dynamic[key] === 'function'
-                            ? dynamic[key](dotenv, env ?? defaultEnv)
-                            : dynamic[key],
-                    });
-            }
-            catch {
-                throw new Error(`Unable to evaluate dynamic variables.`);
-            }
-        }
-    }
-    // Write output file.
-    let resultDotenv = dotenv;
-    if (outputPath) {
-        const outputPathResolved = dotenv[outputKey];
-        if (!outputPathResolved)
-            throw new Error('Output path not found.');
-        const { [outputKey]: _omitted, ...dotenvForOutput } = dotenv;
-        await fs.writeFile(outputPathResolved, Object.keys(dotenvForOutput).reduce((contents, key) => {
-            const value = dotenvForOutput[key] ?? '';
-            return `${contents}${key}=${value.includes('\n') ? `"${value}"` : value}\n`;
-        }, ''), { encoding: 'utf-8' });
-        resultDotenv = dotenvForOutput;
-    }
-    // Log result.
-    if (log) {
-        const redactFlag = options.redact ?? false;
-        const redactPatterns = options.redactPatterns ?? undefined;
-        const redOpts = {};
-        if (redactFlag)
-            redOpts.redact = true;
-        if (redactFlag && Array.isArray(redactPatterns))
-            redOpts.redactPatterns = redactPatterns;
-        const bag = redactFlag
-            ? redactObject(resultDotenv, redOpts)
-            : { ...resultDotenv };
-        logger.log(bag);
-        // Entropy warnings: once-per-key-per-run (presentation only)
-        const warnEntropyVal = options.warnEntropy ?? true;
-        const entropyThresholdVal = options
-            .entropyThreshold;
-        const entropyMinLengthVal = options
-            .entropyMinLength;
-        const entropyWhitelistVal = options
-            .entropyWhitelist;
-        const entOpts = {};
-        if (typeof warnEntropyVal === 'boolean')
-            entOpts.warnEntropy = warnEntropyVal;
-        if (typeof entropyThresholdVal === 'number')
-            entOpts.entropyThreshold = entropyThresholdVal;
-        if (typeof entropyMinLengthVal === 'number')
-            entOpts.entropyMinLength = entropyMinLengthVal;
-        if (Array.isArray(entropyWhitelistVal))
-            entOpts.entropyWhitelist = entropyWhitelistVal;
-        for (const [k, v] of Object.entries(resultDotenv)) {
-            maybeWarnEntropy(k, v, v !== undefined ? 'dotenv' : 'unset', entOpts, (line) => {
-                logger.log(line);
-            });
-        }
-    }
-    // Load process.env.
-    if (loadProcess)
-        Object.assign(process.env, resultDotenv);
-    return resultDotenv;
-};
-
-/**
- * Deep interpolation utility for string leaves.
- * - Expands string values using dotenv-style expansion against the provided envRef.
- * - Preserves non-strings as-is.
- * - Does not recurse into arrays (arrays are returned unchanged).
- *
- * Intended for:
- * - Phase C option/config interpolation after composing ctx.dotenv.
- * - Per-plugin config slice interpolation before afterResolve.
- */
-/** @internal */
-const isPlainObject = (v) => v !== null &&
-    typeof v === 'object' &&
-    !Array.isArray(v) &&
-    Object.getPrototypeOf(v) === Object.prototype;
-/**
- * Deeply interpolate string leaves against envRef.
- * Arrays are not recursed into; they are returned unchanged.
- *
- * @typeParam T - Shape of the input value.
- * @param value - Input value (object/array/primitive).
- * @param envRef - Reference environment for interpolation.
- * @returns A new value with string leaves interpolated.
- */
-const interpolateDeep = (value, envRef) => {
-    // Strings: expand and return
-    if (typeof value === 'string') {
-        const out = dotenvExpand(value, envRef);
-        // dotenvExpand returns string | undefined; preserve original on undefined
-        return (out ?? value);
-    }
-    // Arrays: return as-is (no recursion)
-    if (Array.isArray(value)) {
-        return value;
-    }
-    // Plain objects: shallow clone and recurse into values
-    if (isPlainObject(value)) {
-        const src = value;
-        const out = {};
-        for (const [k, v] of Object.entries(src)) {
-            // Recurse for strings/objects; keep arrays as-is; preserve other scalars
-            if (typeof v === 'string')
-                out[k] = dotenvExpand(v, envRef) ?? v;
-            else if (Array.isArray(v))
-                out[k] = v;
-            else if (isPlainObject(v))
-                out[k] = interpolateDeep(v, envRef);
-            else
-                out[k] = v;
-        }
-        return out;
-    }
-    // Other primitives/types: return as-is
-    return value;
-};
-
-/**
- * Compute the dotenv context for the host (uses the config loader/overlay path).
- * - Resolves and validates options strictly (host-only).
- * - Applies file cascade, overlays, dynamics, and optional effects.
- * - Merges and validates per-plugin config slices (when provided).
- *
- * @param customOptions - Partial options from the current invocation.
- * @param plugins - Installed plugins (for config validation).
- * @param hostMetaUrl - import.meta.url of the host module (for packaged root discovery). */
-const computeContext = async (customOptions, plugins, hostMetaUrl) => {
-    const optionsResolved = await resolveGetDotenvOptions(customOptions);
-    const validated = getDotenvOptionsSchemaResolved.parse(optionsResolved);
-    // Always-on loader path
-    // 1) Base from files only (no dynamic, no programmatic vars)
-    const base = await getDotenv({
-        ...validated,
-        // Build a pure base without side effects or logging.
-        excludeDynamic: true,
-        vars: {},
-        log: false,
-        loadProcess: false,
-        outputPath: undefined,
-    });
-    // 2) Discover config sources and overlay
-    const sources = await resolveGetDotenvConfigSources(hostMetaUrl);
-    const dotenvOverlaid = overlayEnv({
-        base,
-        env: validated.env ?? validated.defaultEnv,
-        configs: sources,
-        ...(validated.vars ? { programmaticVars: validated.vars } : {}),
-    });
-    // Helper to apply a dynamic map progressively.
-    const applyDynamic = (target, dynamic, env) => {
-        if (!dynamic)
-            return;
-        for (const key of Object.keys(dynamic)) {
-            const value = typeof dynamic[key] === 'function'
-                ? dynamic[key](target, env)
-                : dynamic[key];
-            Object.assign(target, { [key]: value });
-        }
-    };
-    // 3) Apply dynamics in order
-    const dotenv = { ...dotenvOverlaid };
-    applyDynamic(dotenv, validated.dynamic, validated.env ?? validated.defaultEnv);
-    applyDynamic(dotenv, (sources.packaged?.dynamic ?? undefined), validated.env ?? validated.defaultEnv);
-    applyDynamic(dotenv, (sources.project?.public?.dynamic ?? undefined), validated.env ?? validated.defaultEnv);
-    applyDynamic(dotenv, (sources.project?.local?.dynamic ?? undefined), validated.env ?? validated.defaultEnv);
-    // file dynamicPath (lowest)
-    if (validated.dynamicPath) {
-        const absDynamicPath = path.resolve(validated.dynamicPath);
-        try {
-            const dyn = await loadModuleDefault(absDynamicPath, 'getdotenv-dynamic-host');
-            applyDynamic(dotenv, dyn, validated.env ?? validated.defaultEnv);
-        }
-        catch {
-            throw new Error(`Unable to load dynamic from ${validated.dynamicPath}`);
-        }
-    }
-    // 4) Output/log/process merge
-    if (validated.outputPath) {
-        await fs.writeFile(validated.outputPath, Object.keys(dotenv).reduce((contents, key) => {
-            const value = dotenv[key] ?? '';
-            return `${contents}${key}=${value.includes('\n') ? `"${value}"` : value}\n`;
-        }, ''), { encoding: 'utf-8' });
-    }
-    const logger = validated.logger ?? console;
-    if (validated.log)
-        logger.log(dotenv);
-    if (validated.loadProcess)
-        Object.assign(process.env, dotenv);
-    // 5) Merge and validate per-plugin config (packaged < project.public < project.local)
-    const packagedPlugins = (sources.packaged &&
-        sources.packaged.plugins) ??
-        {};
-    const publicPlugins = (sources.project?.public &&
-        sources.project.public.plugins) ??
-        {};
-    const localPlugins = (sources.project?.local &&
-        sources.project.local.plugins) ??
-        {};
-    const mergedPluginConfigs = defaultsDeep({}, packagedPlugins, publicPlugins, localPlugins);
-    for (const p of plugins) {
-        if (!p.id)
-            continue;
-        const slice = mergedPluginConfigs[p.id];
-        if (slice === undefined)
-            continue;
-        // Per-plugin interpolation just before validation/afterResolve:
-        // precedence: process.env wins over ctx.dotenv for slice defaults.
-        const envRef = {
-            ...dotenv,
-            ...process.env,
-        };
-        const interpolated = interpolateDeep(slice, envRef);
-        // Validate if a schema is provided; otherwise accept interpolated slice as-is.
-        if (p.configSchema) {
-            const parsed = p.configSchema.safeParse(interpolated);
-            if (!parsed.success) {
-                const msgs = parsed.error.issues
-                    .map((i) => `${i.path.join('.')}: ${i.message}`)
-                    .join('\n');
-                throw new Error(`Invalid config for plugin '${p.id}':\n${msgs}`);
-            }
-            mergedPluginConfigs[p.id] = parsed.data;
-        }
-        else {
-            mergedPluginConfigs[p.id] = interpolated;
-        }
-    }
-    return {
-        optionsResolved: validated,
-        dotenv: dotenv,
-        plugins: {},
-        pluginConfigs: mergedPluginConfigs,
-    };
-};
-
-// Dynamic help support: attach a private symbol to Option for description fns.
-const DYN_DESC_SYM = Symbol('getdotenv.dynamic.description');
-const HOST_META_URL = (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cliHost.cjs', document.baseURI).href));
-const CTX_SYMBOL = Symbol('GetDotenvCli.ctx');
-const OPTS_SYMBOL = Symbol('GetDotenvCli.options');
-const HELP_HEADER_SYMBOL = Symbol('GetDotenvCli.helpHeader');
-/**
- * Plugin-first CLI host for get-dotenv. Extends Commander.Command.
- *
- * Responsibilities:
- * - Resolve options strictly and compute dotenv context (resolveAndLoad).
- * - Expose a stable accessor for the current context (getCtx).
- * - Provide a namespacing helper (ns).
- * - Support composable plugins with parent → children install and afterResolve.
- *
- * NOTE: This host is additive and does not alter the legacy CLI.
- */
-let GetDotenvCli$1 = class GetDotenvCli extends commander.Command {
-    /** Registered top-level plugins (composition happens via .use()) */
-    _plugins = [];
-    /** One-time installation guard */
-    _installed = false;
-    /** Optional header line to prepend in help output */
-    [HELP_HEADER_SYMBOL];
-    /**
-     * Create a subcommand using the same subclass, preserving helpers like
-     * dynamicOption on children.
-     */
-    createCommand(name) {
-        return new this.constructor(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 parent = cmd.parent ?? null;
-                const isRoot = parent === null;
-                const list = isRoot
-                    ? all.filter((opt) => {
-                        const group = opt.__group;
-                        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 });
-        });
-    }
-    /**
-     * Resolve options (strict) and compute dotenv context.
-     * Stores the context on the instance under a symbol.
-     *
-     * Options:
-     * - opts.runAfterResolve (default true): when false, skips running plugin
-     *   afterResolve hooks. Useful for top-level help rendering to avoid
-     *   long-running side-effects while still evaluating dynamic help text.
-     */
-    async resolveAndLoad(customOptions = {}, opts) {
-        // Resolve defaults, then validate strictly under the new host.
-        const optionsResolved = await resolveGetDotenvOptions(customOptions);
-        getDotenvOptionsSchemaResolved.parse(optionsResolved);
-        // Delegate the heavy lifting to the shared helper (guarded path supported).
-        const ctx = await computeContext(optionsResolved, this._plugins, HOST_META_URL);
-        // Persist context on the instance for later access.
-        this[CTX_SYMBOL] =
-            ctx;
-        // Ensure plugins are installed exactly once, then run afterResolve.
-        await this.install();
-        if (opts?.runAfterResolve ?? true) {
-            await this._runAfterResolve(ctx);
-        }
-        return ctx;
-    }
-    /**
-     * Create a Commander Option that computes its description at help time.
-     * The returned Option may be configured (conflicts, default, parser) and
-     * added via addOption().
-     */
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters
-    createDynamicOption(flags, desc, parser, defaultValue) {
-        const opt = new commander.Option(flags, '');
-        // Keep the function on a private symbol so it survives through Commander.
-        opt[DYN_DESC_SYM] = desc;
-        if (parser)
-            opt.argParser(parser);
-        if (defaultValue !== undefined)
-            opt.default(defaultValue);
-        return opt;
-    }
-    /**
-     * Chainable helper mirroring .option(), but with a dynamic description.
-     * Equivalent to addOption(createDynamicOption(...)).
-     */
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters
-    dynamicOption(flags, desc, parser, defaultValue) {
-        const opt = this.createDynamicOption(flags, desc, parser, defaultValue);
-        this.addOption(opt);
-        return this;
-    }
-    /**
-     * Evaluate dynamic descriptions for this command and all descendants using
-     * the provided resolved configuration. Mutates the Option.description in
-     * place so Commander help renders updated text.
-     */
-    evaluateDynamicOptions(resolved) {
-        const visit = (cmd) => {
-            const arr = cmd.options ?? [];
-            for (const o of arr) {
-                const dyn = o[DYN_DESC_SYM];
-                if (typeof dyn === 'function') {
-                    try {
-                        const txt = dyn(resolved);
-                        // Commander Option has a public "description" field used by help.
-                        o.description = txt;
-                    }
-                    catch {
-                        // Best-effort: leave description as-is on evaluation failure.
-                    }
-                }
-            }
-            const children = cmd.commands ?? [];
-            for (const c of children)
-                visit(c);
-        };
-        visit(this);
-    }
-    /**
-     * Retrieve the current invocation context (if any).
-     */
-    getCtx() {
-        return this[CTX_SYMBOL];
-    }
-    /**
-     * Retrieve the merged root CLI options bag (if set by passOptions()).
-     * Downstream-safe: no generics required.
-     */
-    getOptions() {
-        return this[OPTS_SYMBOL];
-    }
-    /** Internal: set the merged root options bag for this run. */
-    _setOptionsBag(bag) {
-        this[OPTS_SYMBOL] = bag;
-    }
-    /**   * Convenience helper to create a namespaced subcommand.
-     */
-    ns(name) {
-        return this.command(name);
-    }
-    /**
-     * Tag options added during the provided callback as 'app' for grouped help.
-     * Allows downstream apps to demarcate their root-level options.
-     */
-    tagAppOptions(fn) {
-        const root = this;
-        const originalAddOption = root.addOption.bind(root);
-        // eslint-disable-next-line @typescript-eslint/no-deprecated
-        const originalOption = root.option.bind(root);
-        const tagLatest = (cmd, group) => {
-            const optsArr = cmd.options;
-            if (Array.isArray(optsArr) && optsArr.length > 0) {
-                const last = optsArr[optsArr.length - 1];
-                last.__group = group;
-            }
-        };
-        root.addOption = function patchedAdd(opt) {
-            opt.__group = 'app';
-            return originalAddOption(opt);
-        };
-        // eslint-disable-next-line @typescript-eslint/no-deprecated
-        root.option = function patchedOption(...args) {
-            const ret = originalOption(...args);
-            tagLatest(this, 'app');
-            return ret;
-        };
-        try {
-            return fn(root);
-        }
-        finally {
-            root.addOption = originalAddOption;
-            // eslint-disable-next-line @typescript-eslint/no-deprecated
-            root.option = originalOption;
-        }
-    }
-    /**
-     * Branding helper: set CLI name/description/version and optional help header.
-     * If version is omitted and importMetaUrl is provided, attempts to read the
-     * nearest package.json version (best-effort; non-fatal on failure).
-     */
-    async brand(args) {
-        const { name, description, version, importMetaUrl, helpHeader } = args;
-        if (typeof name === 'string' && name.length > 0)
-            this.name(name);
-        if (typeof description === 'string')
-            this.description(description);
-        let v = version;
-        if (!v && importMetaUrl) {
-            try {
-                const fromUrl = url.fileURLToPath(importMetaUrl);
-                const pkgDir = await packageDirectory.packageDirectory({ cwd: fromUrl });
-                if (pkgDir) {
-                    const txt = await fs.readFile(`${pkgDir}/package.json`, 'utf-8');
-                    const pkg = JSON.parse(txt);
-                    if (pkg.version)
-                        v = pkg.version;
-                }
-            }
-            catch {
-                // best-effort only
-            }
-        }
-        if (v)
-            this.version(v);
-        // Help header:
-        // - If caller provides helpHeader, use it.
-        // - Otherwise, when a version is known, default to "<name> v<version>".
-        if (typeof helpHeader === 'string') {
-            this[HELP_HEADER_SYMBOL] = helpHeader;
-        }
-        else if (v) {
-            // Use the current command name (possibly overridden by 'name' above).
-            const header = `${this.name()} v${v}`;
-            this[HELP_HEADER_SYMBOL] = header;
-        }
-        return this;
-    }
-    /**
-     * Insert grouped plugin/app options between "Options" and "Commands" for
-     * hybrid ordering. Applies to root and any parent command.
-     */
-    helpInformation() {
-        // Base help text first (includes beforeAll/after hooks).
-        const base = super.helpInformation();
-        const groups = this.#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;
-    }
-    /**
-     * Register a plugin for installation (parent level).
-     * Installation occurs on first resolveAndLoad() (or explicit install()).
-     */
-    use(plugin) {
-        this._plugins.push(plugin);
-        // Immediately run setup so subcommands exist before parsing.
-        const setupOne = (p) => {
-            p.setup(this);
-            for (const child of p.children)
-                setupOne(child);
-        };
-        setupOne(plugin);
-        return this;
-    }
-    /**
-     * Install all registered plugins in parent → children (pre-order).
-     * Runs only once per CLI instance.
-     */
-    async install() {
-        // Setup is performed immediately in use(); here we only guard for afterResolve.
-        this._installed = true;
-        // Satisfy require-await without altering behavior.
-        await Promise.resolve();
-    }
-    /**
-     * Run afterResolve hooks for all plugins (parent → children).
-     */
-    async _runAfterResolve(ctx) {
-        const run = async (p) => {
-            if (p.afterResolve)
-                await p.afterResolve(this, ctx);
-            for (const child of p.children)
-                await run(child);
-        };
-        for (const p of this._plugins)
-            await run(p);
-    }
-    // Render App/Plugin grouped options (used by helpInformation override).
-    #renderOptionGroups(cmd) {
-        const all = cmd.options ?? [];
-        const byGroup = new Map();
-        for (const o of all) {
-            const opt = o;
-            const g = opt.__group;
-            if (!g || g === 'base')
-                continue; // base handled by default help
-            const rows = byGroup.get(g) ?? [];
-            rows.push({
-                flags: opt.flags ?? '',
-                description: opt.description ?? '',
-            });
-            byGroup.set(g, rows);
-        }
-        if (byGroup.size === 0)
-            return '';
-        const renderRows = (title, rows) => {
-            const width = Math.min(40, rows.reduce((m, r) => Math.max(m, r.flags.length), 0));
-            // Sort within group: short-aliased flags first
-            rows.sort((a, b) => {
-                const aS = /(^|\s|,)-[A-Za-z]/.test(a.flags) ? 1 : 0;
-                const bS = /(^|\s|,)-[A-Za-z]/.test(b.flags) ? 1 : 0;
-                return bS - aS || a.flags.localeCompare(b.flags);
-            });
-            const lines = rows
-                .map((r) => {
-                const pad = ' '.repeat(Math.max(2, width - r.flags.length + 2));
-                return `  ${r.flags}${pad}${r.description}`.trimEnd();
-            })
-                .join('\n');
-            return `\n${title}:\n${lines}\n`;
-        };
-        let out = '';
-        // App options (if any)
-        const app = byGroup.get('app');
-        if (app && app.length > 0) {
-            out += renderRows('App options', app);
-        }
-        // Plugin groups sorted by id
-        const pluginKeys = Array.from(byGroup.keys()).filter((k) => k.startsWith('plugin:'));
-        const currentName = cmd.name?.() ?? '';
-        pluginKeys.sort((a, b) => a.localeCompare(b));
-        for (const k of pluginKeys) {
-            const id = k.slice('plugin:'.length) || '(unknown)';
-            const rows = byGroup.get(k) ?? [];
-            // Do not show a "Plugin options — <self>" section on the command that owns those options.
-            // Only child-injected plugin groups should render at this level.
-            if (rows.length > 0 && id !== currentName) {
-                out += renderRows(`Plugin options — ${id}`, rows);
-            }
-        }
-        return out;
-    }
-};
-
-/** 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.
- */
-/**
- * Define a GetDotenv CLI plugin with compositional helpers.
- *
- * @example
- * const parent = definePlugin(\{ id: 'p', setup(cli) \{ /* ... *\/ \} \})
- *   .use(childA)
- *   .use(childB);
- */
-const definePlugin = (spec) => {
-    const { children = [], ...rest } = spec;
-    const plugin = {
-        ...rest,
-        children: [...children],
-        use(child) {
-            this.children.push(child);
-            return this;
-        },
-    };
-    return plugin;
-};
-
-/**
- * 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.
- */
-class GetDotenvCli extends GetDotenvCli$1 {
-    /**
-     * Attach legacy root flags to this CLI instance. Defaults come from
-     * baseRootOptionDefaults when none are provided.
-     */
-    attachRootOptions(defaults, opts) {
-        const d = (defaults ?? baseRootOptionDefaults);
-        attachRootOptions(this, d, opts);
-        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();
-                this.evaluateDynamicOptions({
-                    ...ctx?.optionsResolved,
-                    plugins: ctx?.pluginConfigs ?? {},
-                });
-            }
-            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((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cliHost.cjs', document.baseURI).href)));
-                const issues = validateEnvAgainstSources(dotenv, sources);
-                if (Array.isArray(issues) && issues.length > 0) {
-                    const logger = (merged
-                        .logger ?? console);
-                    const emit = logger.error ?? logger.log;
-                    issues.forEach((m) => {
-                        emit(m);
-                    });
-                    if (merged.strict) {
-                        process.exit(1);
-                    }
-                }
-            }
-            catch {
-                // 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();
-                    this.evaluateDynamicOptions({
-                        ...ctx?.optionsResolved,
-                        plugins: ctx?.pluginConfigs ?? {},
-                    });
-                }
-                catch {
-                    /* tolerate */
-                }
-                try {
-                    const ctx = this.getCtx();
-                    const dotenv = (ctx?.dotenv ?? {});
-                    const sources = await resolveGetDotenvConfigSources((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cliHost.cjs', document.baseURI).href)));
-                    const issues = validateEnvAgainstSources(dotenv, sources);
-                    if (Array.isArray(issues) && issues.length > 0) {
-                        const logger = (merged
-                            .logger ?? console);
-                        const emit = logger.error ?? logger.log;
-                        issues.forEach((m) => {
-                            emit(m);
-                        });
-                        if (merged.strict) {
-                            process.exit(1);
-                        }
-                    }
-                }
-                catch {
-                    // Tolerate validation side-effects in non-strict mode.
-                }
-            }
-        });
-        return this;
-    }
-}
-/**
- * Helper to retrieve the merged root options bag from any action handler
- * that only has access to thisCommand. Avoids structural casts.
- */
-const readMergedOptions = (cmd) => {
-    // Ascend to the root command
-    let root = cmd;
-    while (root.parent) {
-        root = root.parent;
-    }
-    const hostAny = root;
-    return typeof hostAny.getOptions === 'function'
-        ? hostAny.getOptions()
-        : root
-            .getDotenvCliOptions;
-};
-
-exports.GetDotenvCli = GetDotenvCli;
-exports.definePlugin = definePlugin;
-exports.readMergedOptions = readMergedOptions;