@karmaniverous/get-dotenv 6.2.2 → 6.2.4

package/dist/chunks/readMergedOptions-Nt0TR7dX.mjs

@@ -0,0 +1,1626 @@
+import { z } from 'zod';
+import { Option, Command } from '@commander-js/extra-typings';
+import { d as dotenvExpand, a as dotenvExpandAll, l as loadAndApplyDynamic, c as applyDynamicMap, o as overlayEnv, b as dotenvExpandFromProcessEnv } from './overlayEnv-Bs2kVayG.mjs';
+import { nanoid } from 'nanoid';
+import path from 'path';
+import fs from 'fs-extra';
+import 'crypto';
+import { fileURLToPath } from 'url';
+import { parse } from 'dotenv';
+import { g as getDotenvOptionsSchemaResolved, r as resolveGetDotenvConfigSources } from './loader-DnhPeGfq.mjs';
+import { packageDirectory } from 'package-directory';
+
+/** @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;
+};
+function defaultsDeep(...layers) {
+    const result = layers
+        .filter(Boolean)
+        .reduce((acc, layer) => mergeInto(acc, layer), {});
+    return result;
+}
+
+/**
+ * Serialize a dotenv record to a file with minimal quoting (multiline values are quoted).
+ * Future-proofs for ordering/sorting changes (currently insertion order).
+ *
+ * @param filename - Destination dotenv file path.
+ * @param data - Env-like map of values to write (values may be `undefined`).
+ * @returns A `Promise\<void\>` which resolves when the file has been written.
+ */
+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' });
+}
+
+/** @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;
+};
+
+/** 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.
+ *
+ * @typeParam T - Input object shape.
+ * @param obj - Object to filter.
+ * @returns A shallow copy of `obj` without keys whose value is `undefined`.
+ */
+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.
+ *
+ * @typeParam V - Value type for present entries (must extend `string`).
+ * @param obj - Env-like record containing `string | undefined` values.
+ * @returns A new record containing only the keys with defined values.
+ */
+function omitUndefinedRecord(obj) {
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+        if (v !== undefined)
+            out[k] = v;
+    }
+    return out;
+}
+
+/** 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) => (typeof p === 'string' ? new RegExp(p, 'i') : p));
+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) => typeof p === 'string' ? new RegExp(p, 'i') : p);
+const shouldRedactKey = (key, regs) => regs.some((re) => re.test(key));
+const MASK = '[redacted]';
+/**
+ * Redact a single displayed value according to key/patterns.
+ * Returns the original value when redaction is disabled or key is not matched.
+ */
+const redactDisplay = (key, value, opts) => {
+    if (!value)
+        return value;
+    if (!opts?.redact)
+        return value;
+    const regs = compile(opts.redactPatterns);
+    return shouldRedactKey(key, regs) ? MASK : value;
+};
+/**
+ * Produce a shallow redacted copy of an env-like object for display.
+ */
+const redactObject = (obj, opts) => {
+    if (!opts?.redact)
+        return { ...obj };
+    const regs = compile(opts.redactPatterns);
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+        out[k] = v && shouldRedactKey(k, regs) ? MASK : v;
+    }
+    return out;
+};
+/**
+ * Utility to redact three related displayed values (parent/dotenv/final)
+ * consistently for trace lines.
+ */
+const redactTriple = (key, triple, opts) => {
+    if (!opts?.redact)
+        return triple;
+    const regs = compile(opts.redactPatterns);
+    const maskIf = (v) => (v && shouldRedactKey(key, regs) ? MASK : v);
+    const out = {};
+    const p = maskIf(triple.parent);
+    const d = maskIf(triple.dotenv);
+    const f = maskIf(triple.final);
+    if (p !== undefined)
+        out.parent = p;
+    if (d !== undefined)
+        out.dotenv = d;
+    if (f !== undefined)
+        out.final = f;
+    return out;
+};
+
+/**
+ * Base root CLI defaults (shared; kept untyped here to avoid cross-layer deps).
+ * Used as the bottom layer for CLI option resolution.
+ */
+const baseScripts = {
+    'git-status': {
+        cmd: 'git branch --show-current && git status -s -u',
+        shell: true,
+    },
+};
+/**
+ * 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
+ * - any discovered configuration `rootOptionDefaults`
+ * - and finally CLI flags at runtime
+ *
+ * @public
+ */
+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: baseScripts,
+    shell: true,
+    vars: '',
+    varsAssignor: '=',
+    varsDelimiter: ' ',
+    // tri-state flags default to unset unless explicitly provided
+    // (debug/log/exclude* resolved via flag utils)
+};
+
+function defineDynamic(d) {
+    return d;
+}
+/**
+ * Define a strongly‑typed get‑dotenv configuration document for JS/TS authoring.
+ *
+ * This helper is compile‑time only: it returns the input unchanged at runtime,
+ * but enables rich TypeScript inference for `vars`, `envVars`, and `dynamic`,
+ * and validates property names and value shapes as you author the config.
+ *
+ * @typeParam Vars - The string‑valued env map your project uses (for example,
+ *   `{ APP_SETTING?: string }`). Keys propagate to `dynamic` function arguments.
+ * @typeParam Env - Allowed environment names used for `envVars` (defaults to `string`).
+ * @typeParam T - The full config type being produced (defaults to `GetDotenvConfig<Vars, Env>`).
+ *   This type parameter is rarely supplied explicitly.
+ * @param cfg - The configuration object literal.
+ * @returns The same `cfg` value, with its type preserved for inference.
+ */
+function defineGetDotenvConfig(cfg) {
+    return cfg;
+}
+/**
+ * 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 } : {}),
+    };
+};
+/**
+ * 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 = (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 ?? {}),
+    });
+};
+
+/**
+ * Asynchronously read a dotenv file & parse it into an object.
+ *
+ * @param path - Path to dotenv file.
+ * @returns The parsed dotenv object.
+ */
+const readDotenv = async (path) => {
+    try {
+        return (await fs.exists(path)) ? parse(await fs.readFile(path)) : {};
+    }
+    catch {
+        return {};
+    }
+};
+
+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);
+    // Read .env files.
+    const loaded = paths.length
+        ? await paths.reduce(async (e, p) => {
+            const publicGlobal = excludePublic || excludeGlobal
+                ? Promise.resolve({})
+                : readDotenv(path.resolve(p, dotenvToken));
+            const publicEnv = excludePublic || excludeEnv || (!env && !defaultEnv)
+                ? Promise.resolve({})
+                : readDotenv(path.resolve(p, `${dotenvToken}.${env ?? defaultEnv ?? ''}`));
+            const privateGlobal = excludePrivate || excludeGlobal
+                ? Promise.resolve({})
+                : readDotenv(path.resolve(p, `${dotenvToken}.${privateToken}`));
+            const privateEnv = excludePrivate || excludeEnv || (!env && !defaultEnv)
+                ? Promise.resolve({})
+                : readDotenv(path.resolve(p, `${dotenvToken}.${env ?? defaultEnv ?? ''}.${privateToken}`));
+            const [eResolved, publicGlobalResolved, publicEnvResolved, privateGlobalResolved, privateEnvResolved,] = await Promise.all([
+                e,
+                publicGlobal,
+                publicEnv,
+                privateGlobal,
+                privateEnv,
+            ]);
+            return {
+                ...eResolved,
+                ...publicGlobalResolved,
+                ...publicEnvResolved,
+                ...privateGlobalResolved,
+                ...privateEnvResolved,
+            };
+        }, Promise.resolve({}))
+        : {};
+    const outputKey = nanoid();
+    const dotenv = dotenvExpandAll({
+        ...loaded,
+        ...vars,
+        ...(outputPath ? { [outputKey]: outputPath } : {}),
+    }, { progressive: true });
+    // Process dynamic variables. Programmatic option takes precedence over path.
+    if (!excludeDynamic) {
+        let dynamic = undefined;
+        if (options.dynamic && Object.keys(options.dynamic).length > 0) {
+            dynamic = options.dynamic;
+        }
+        else if (dynamicPath) {
+            const absDynamicPath = path.resolve(dynamicPath);
+            await loadAndApplyDynamic(dotenv, absDynamicPath, env ?? defaultEnv, 'getdotenv-dynamic');
+        }
+        if (dynamic) {
+            try {
+                applyDynamicMap(dotenv, dynamic, env ?? defaultEnv);
+            }
+            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 writeDotenvFile(outputPathResolved, dotenvForOutput);
+        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;
+}
+
+/**
+ * Compute the realized path for a command mount (leaf-up to root).
+ * Excludes the root application alias.
+ *
+ * @param cli - The mounted command instance.
+ */
+/**
+ * Flatten a plugin tree into a list of `{ plugin, path }` entries.
+ * Traverses the namespace chain in pre-order.
+ */
+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;
+}
+
+/**
+ * Instance-bound plugin config store.
+ * Host stores the validated/interpolated slice per plugin instance.
+ * The store is intentionally private to this module; definePlugin()
+ * provides a typed accessor that reads from this store for the calling
+ * plugin instance.
+ */
+const PLUGIN_CONFIG_STORE = new WeakMap();
+/**
+ * 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);
+};
+/**
+ * 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), keyed by
+ *   realized mount path (ns chain).
+ *
+ * @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);
+    // 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);
+    // Build a pure base without side effects or logging (no dynamics, no programmatic vars).
+    const cleanedValidated = omitUndefined(validated);
+    const base = await getDotenv({
+        ...cleanedValidated,
+        excludeDynamic: true,
+        vars: {},
+        log: false,
+        loadProcess: false,
+    });
+    // Discover config sources and overlay with progressive expansion per slice.
+    const sources = await resolveGetDotenvConfigSources(hostMetaUrl);
+    const dotenvOverlaid = overlayEnv({
+        base,
+        env: validated.env ?? validated.defaultEnv,
+        configs: sources,
+        ...(validated.vars ? { programmaticVars: validated.vars } : {}),
+    });
+    const dotenv = { ...dotenvOverlaid };
+    // 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);
+        await loadAndApplyDynamic(dotenv, absDynamicPath, validated.env ?? validated.defaultEnv, 'getdotenv-dynamic-host');
+    }
+    // Effects:
+    if (validated.outputPath) {
+        await writeDotenvFile(validated.outputPath, dotenv);
+    }
+    const logger = validated.logger;
+    if (validated.log)
+        logger.log(dotenv);
+    if (validated.loadProcess)
+        Object.assign(process.env, dotenv);
+    // Merge and validate per-plugin config keyed by realized path (ns chain).
+    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 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)
+            : {};
+        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().');
+        }
+        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;
+}
+
+/**
+ * Attach root flags to a {@link GetDotenvCli} instance.
+ *
+ * Program is typed as {@link GetDotenvCli} and supports {@link GetDotenvCli.createDynamicOption | createDynamicOption}.
+ */
+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);
+        }
+    }
+    return program;
+};
+
+/**
+ * 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();
+    for (const o of all) {
+        const opt = o;
+        const g = GROUP_TAG.get(opt);
+        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; suppress self group on the owning command name.
+    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) ?? [];
+        if (rows.length > 0 && id !== currentName) {
+            out += renderRows(`Plugin options — ${id}`, rows);
+        }
+    }
+    return out;
+}
+
+/**
+ * Compose root/parent help output by inserting grouped sections between
+ * Options and Commands, ensuring a trailing blank line.
+ *
+ * @param base - Base help text produced by Commander.
+ * @param cmd - Command instance whose grouped options should be rendered.
+ * @returns The modified help text with grouped blocks inserted.
+ */
+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);
+}
+
+/**
+ * Initialize a {@link GetDotenvCli} instance with help configuration and safe defaults.
+ *
+ * @remarks
+ * This is a low-level initializer used by the host constructor to keep `GetDotenvCli.ts`
+ * small and to centralize help/output behavior.
+ *
+ * @param cli - The CLI instance to initialize.
+ * @param headerGetter - Callback returning an optional help header string.
+ */
+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');
+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.
+ */
+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) */
+    [CTX_SYMBOL];
+    [OPTS_SYMBOL];
+    /**
+     * Create a subcommand using the same subclass, preserving helpers like
+     * dynamicOption on children.
+     */
+    createCommand(name) {
+        // Explicitly construct a GetDotenvCli for children to preserve helpers.
+        return new GetDotenvCli(name);
+    }
+    constructor(alias = 'getdotenv') {
+        super(alias);
+        this.enablePositionalOptions();
+        // 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.
+     * 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) {
+        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.
+        await this.install();
+        if (opts?.runAfterResolve ?? true) {
+            await this._runAfterResolve(ctx);
+        }
+        return ctx;
+    }
+    // Implementation
+    createDynamicOption(flags, desc, parser, defaultValue) {
+        return makeDynamicOption(flags, (c) => desc(c), parser, defaultValue);
+    }
+    /**
+     * 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) {
+        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() {
+        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() {
+        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 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);
+        if (exists) {
+            throw new Error(`Duplicate command name: ${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) {
+        return tagAppOptionsAround(this, this.setOptionGroup.bind(this), fn);
+    }
+    /**
+     * 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);
+        const v = version ?? (await readPkgVersion(importMetaUrl));
+        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) {
+            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() {
+        return buildHelpInformation(super.helpInformation(), this);
+    }
+    /**
+     * Public: tag an Option with a display group for help (root/app/plugin:<id>).
+     */
+    setOptionGroup(opt, group) {
+        GROUP_TAG.set(opt, group);
+    }
+    /**
+     * Register a plugin for installation (parent level).
+     * Installation occurs on first resolveAndLoad() (or explicit install()).
+     */
+    use(plugin, override) {
+        this._plugins.push({ plugin, override });
+        return this;
+    }
+    /**
+     * Install all registered plugins in parent → children (pre-order).
+     * Runs only once per CLI instance.
+     */
+    async install() {
+        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) {
+        await runAfterResolveTree(this, this._plugins.map((e) => e.plugin), ctx);
+    }
+}
+
+/**
+ * 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) => {
+    // Climb to the true root
+    let root = cmd;
+    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;
+};
+
+export { GetDotenvCli as G, defineDynamic as a, defineGetDotenvConfig as b, getDotenvCliOptions2Options as c, definePlugin as d, baseRootOptionDefaults as e, redactDisplay as f, getDotenv as g, redactObject as h, interpolateDeep as i, defaultsDeep as j, attachRootOptions as k, redactTriple as l, maybeWarnEntropy as m, readMergedOptions as r };