@karmaniverous/get-dotenv 5.2.6 → 6.0.0-0

package/dist/cliHost.cjs

@@ -1,269 +1,17 @@
 'use strict';
 
-var commander = require('commander');
 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;
-/**
- * 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);
-
-/**
- * Attach legacy root flags to a Commander program.
- * Uses provided defaults to render help labels without coupling to generators.
- */
-const attachRootOptions = (program, defaults, opts) => {
-    // Install temporary wrappers to tag all options added here as "base".
-    const GROUP = 'base';
-    const tagLatest = (cmd, group) => {
-        const optsArr = cmd.options;
-        if (Array.isArray(optsArr) && optsArr.length > 0) {
-            const last = optsArr[optsArr.length - 1];
-            last.__group = group;
-        }
-    };
-    const originalAddOption = program.addOption.bind(program);
-    const originalOption = program.option.bind(program);
-    program.addOption = function patchedAdd(opt) {
-        // Tag before adding, in case consumers inspect the Option directly.
-        opt.__group = GROUP;
-        const ret = originalAddOption(opt);
-        return ret;
-    };
-    program.option = function patchedOption(...args) {
-        const ret = originalOption(...args);
-        tagLatest(this, GROUP);
-        return ret;
-    };
-    const { defaultEnv, dotenvToken, dynamicPath, env, excludeDynamic, excludeEnv, excludeGlobal, excludePrivate, excludePublic, loadProcess, log, outputPath, paths, pathsDelimiter, pathsDelimiterPattern, privateToken, scripts, shell, varsAssignor, varsAssignorPattern, varsDelimiter, varsDelimiterPattern, } = defaults ?? {};
-    const va = typeof defaults?.varsAssignor === 'string' ? defaults.varsAssignor : '=';
-    const vd = typeof defaults?.varsDelimiter === 'string' ? defaults.varsDelimiter : ' ';
-    // Build initial chain.
-    let p = program
-        .enablePositionalOptions()
-        .passThroughOptions()
-        .option('-e, --env <string>', `target environment (dotenv-expanded)`, dotenvExpandFromProcessEnv, env);
-    p = p.option('-v, --vars <string>', `extra variables expressed as delimited key-value pairs (dotenv-expanded): ${[
-        ['KEY1', 'VAL1'],
-        ['KEY2', 'VAL2'],
-    ]
-        .map((v) => v.join(va))
-        .join(vd)}`, dotenvExpandFromProcessEnv);
-    // Optional legacy root command flag (kept for generated CLI compatibility).
-    // Default is OFF; the generator opts in explicitly.
-    if (opts?.includeCommandOption === true) {
-        p = p.option('-c, --command <string>', 'command executed according to the --shell option, conflicts with cmd subcommand (dotenv-expanded)', dotenvExpandFromProcessEnv);
-    }
-    p = p
-        .option('-o, --output-path <string>', 'consolidated output file  (dotenv-expanded)', dotenvExpandFromProcessEnv, outputPath)
-        .addOption(new commander.Option('-s, --shell [string]', (() => {
-        let defaultLabel = '';
-        if (shell !== undefined) {
-            if (typeof shell === 'boolean') {
-                defaultLabel = ' (default OS shell)';
-            }
-            else if (typeof shell === 'string') {
-                // Safe string interpolation
-                defaultLabel = ` (default ${shell})`;
-            }
-        }
-        return `command execution shell, no argument for default OS shell or provide shell string${defaultLabel}`;
-    })()).conflicts('shellOff'))
-        .addOption(new commander.Option('-S, --shell-off', `command execution shell OFF${!shell ? ' (default)' : ''}`).conflicts('shell'))
-        .addOption(new commander.Option('-p, --load-process', `load variables to process.env ON${loadProcess ? ' (default)' : ''}`).conflicts('loadProcessOff'))
-        .addOption(new commander.Option('-P, --load-process-off', `load variables to process.env OFF${!loadProcess ? ' (default)' : ''}`).conflicts('loadProcess'))
-        .addOption(new commander.Option('-a, --exclude-all', `exclude all dotenv variables from loading ON${excludeDynamic &&
-        ((excludeEnv && excludeGlobal) || (excludePrivate && excludePublic))
-        ? ' (default)'
-        : ''}`).conflicts('excludeAllOff'))
-        .addOption(new commander.Option('-A, --exclude-all-off', `exclude all dotenv variables from loading OFF (default)`).conflicts('excludeAll'))
-        .addOption(new commander.Option('-z, --exclude-dynamic', `exclude dynamic dotenv variables from loading ON${excludeDynamic ? ' (default)' : ''}`).conflicts('excludeDynamicOff'))
-        .addOption(new commander.Option('-Z, --exclude-dynamic-off', `exclude dynamic dotenv variables from loading OFF${!excludeDynamic ? ' (default)' : ''}`).conflicts('excludeDynamic'))
-        .addOption(new commander.Option('-n, --exclude-env', `exclude environment-specific dotenv variables from loading${excludeEnv ? ' (default)' : ''}`).conflicts('excludeEnvOff'))
-        .addOption(new commander.Option('-N, --exclude-env-off', `exclude environment-specific dotenv variables from loading OFF${!excludeEnv ? ' (default)' : ''}`).conflicts('excludeEnv'))
-        .addOption(new commander.Option('-g, --exclude-global', `exclude global dotenv variables from loading ON${excludeGlobal ? ' (default)' : ''}`).conflicts('excludeGlobalOff'))
-        .addOption(new commander.Option('-G, --exclude-global-off', `exclude global dotenv variables from loading OFF${!excludeGlobal ? ' (default)' : ''}`).conflicts('excludeGlobal'))
-        .addOption(new commander.Option('-r, --exclude-private', `exclude private dotenv variables from loading ON${excludePrivate ? ' (default)' : ''}`).conflicts('excludePrivateOff'))
-        .addOption(new commander.Option('-R, --exclude-private-off', `exclude private dotenv variables from loading OFF${!excludePrivate ? ' (default)' : ''}`).conflicts('excludePrivate'))
-        .addOption(new commander.Option('-u, --exclude-public', `exclude public dotenv variables from loading ON${excludePublic ? ' (default)' : ''}`).conflicts('excludePublicOff'))
-        .addOption(new commander.Option('-U, --exclude-public-off', `exclude public dotenv variables from loading OFF${!excludePublic ? ' (default)' : ''}`).conflicts('excludePublic'))
-        .addOption(new commander.Option('-l, --log', `console log loaded variables ON${log ? ' (default)' : ''}`).conflicts('logOff'))
-        .addOption(new commander.Option('-L, --log-off', `console log loaded variables OFF${!log ? ' (default)' : ''}`).conflicts('log'))
-        .option('--capture', 'capture child process stdio for commands (tests/CI)')
-        .option('--redact', 'mask secret-like values in logs/trace (presentation-only)')
-        .option('--default-env <string>', 'default target environment', dotenvExpandFromProcessEnv, defaultEnv)
-        .option('--dotenv-token <string>', 'dotenv-expanded token indicating a dotenv file', dotenvExpandFromProcessEnv, dotenvToken)
-        .option('--dynamic-path <string>', 'dynamic variables path (.js or .ts; .ts is auto-compiled when esbuild is available, otherwise precompile)', dotenvExpandFromProcessEnv, dynamicPath)
-        .option('--paths <string>', 'dotenv-expanded delimited list of paths to dotenv directory', dotenvExpandFromProcessEnv, paths)
-        .option('--paths-delimiter <string>', 'paths delimiter string', pathsDelimiter)
-        .option('--paths-delimiter-pattern <string>', 'paths delimiter regex pattern', pathsDelimiterPattern)
-        .option('--private-token <string>', 'dotenv-expanded token indicating private variables', dotenvExpandFromProcessEnv, privateToken)
-        .option('--vars-delimiter <string>', 'vars delimiter string', varsDelimiter)
-        .option('--vars-delimiter-pattern <string>', 'vars delimiter regex pattern', varsDelimiterPattern)
-        .option('--vars-assignor <string>', 'vars assignment operator string', varsAssignor)
-        .option('--vars-assignor-pattern <string>', 'vars assignment operator regex pattern', varsAssignorPattern)
-        // Hidden scripts pipe-through (stringified)
-        .addOption(new commander.Option('--scripts <string>')
-        .default(JSON.stringify(scripts))
-        .hideHelp());
-    // Diagnostics: opt-in tracing; optional variadic keys after the flag.
-    p = p.option('--trace [keys...]', 'emit diagnostics for child env composition (optional keys)');
-    // Validation: strict mode fails on env validation issues (warn by default).
-    p = p.option('--strict', 'fail on env validation errors (schema/requiredKeys)');
-    // Entropy diagnostics (presentation-only)
-    p = p
-        .addOption(new commander.Option('--entropy-warn', 'enable entropy warnings (default on)').conflicts('entropyWarnOff'))
-        .addOption(new commander.Option('--entropy-warn-off', 'disable entropy warnings').conflicts('entropyWarn'))
-        .option('--entropy-threshold <number>', 'entropy bits/char threshold (default 3.8)')
-        .option('--entropy-min-length <number>', 'min length to examine for entropy (default 16)')
-        .option('--entropy-whitelist <pattern...>', 'suppress entropy warnings when key matches any regex pattern')
-        .option('--redact-pattern <pattern...>', 'additional key-match regex patterns to trigger redaction');
-    // Restore original methods to avoid tagging future additions outside base.
-    program.addOption = originalAddOption;
-    program.option = originalOption;
-    return p;
-};
-
 // Base root CLI defaults (shared; kept untyped here to avoid cross-layer deps).
 const baseRootOptionDefaults = {
     dotenvToken: '.env',
@@ -833,9 +581,21 @@ const resolveGetDotenvOptions = async (customOptions) => {
     const localOptionsPath = localPkgDir
         ? path.join(localPkgDir, getDotenvOptionsFilename)
         : undefined;
-    const localOptions = (localOptionsPath && (await fs.exists(localOptionsPath))
-        ? JSON.parse((await fs.readFile(localOptionsPath)).toString())
-        : {});
+    // 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);
@@ -846,6 +606,316 @@ const resolveGetDotenvOptions = async (customOptions) => {
     };
 };
 
+/**
+ * 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.
  *
@@ -1458,6 +1528,8 @@ const computeContext = async (customOptions, plugins, hostMetaUrl) => {
     };
 };
 
+// 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');
@@ -1480,6 +1552,13 @@ let GetDotenvCli$1 = class GetDotenvCli extends commander.Command {
     _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.
@@ -1487,15 +1566,18 @@ let GetDotenvCli$1 = class GetDotenvCli extends commander.Command {
         // child uses passThroughOptions.
         this.enablePositionalOptions();
         // Configure grouped help: show only base options in default "Options";
-        // append App/Plugin sections after default help.
+        // we will insert App/Plugin sections before Commands in helpInformation().
         this.configureHelp({
             visibleOptions: (cmd) => {
-                const all = cmd.options ??
-                    [];
-                const base = all.filter((opt) => {
-                    const group = opt.__group;
-                    return group === 'base';
-                });
+                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 ?? '';
@@ -1503,19 +1585,18 @@ let GetDotenvCli$1 = class GetDotenvCli extends commander.Command {
                     return /(^|\s|,)-[A-Za-z]/.test(flags);
                 };
                 const byFlags = (opt) => opt.flags ?? '';
-                base.sort((a, b) => {
+                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 base;
+                return list;
             },
         });
         this.addHelpText('beforeAll', () => {
             const header = this[HELP_HEADER_SYMBOL];
             return header && header.length > 0 ? `${header}\n\n` : '';
         });
-        this.addHelpText('afterAll', (ctx) => this.#renderOptionGroups(ctx.command));
         // Skeleton preSubcommand hook: produce a context if absent, without
         // mutating process.env. The passOptions hook (when installed) will    // compute the final context using merged CLI options; keeping
         // loadProcess=false here avoids leaking dotenv values into the parent
@@ -1527,9 +1608,15 @@ let GetDotenvCli$1 = class GetDotenvCli extends commander.Command {
         });
     }
     /**
-     * Resolve options (strict) and compute dotenv context.   * Stores the context on the instance under a symbol.
+     * 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 = {}) {
+    async resolveAndLoad(customOptions = {}, opts) {
         // Resolve defaults, then validate strictly under the new host.
         const optionsResolved = await resolveGetDotenvOptions(customOptions);
         getDotenvOptionsSchemaResolved.parse(optionsResolved);
@@ -1540,9 +1627,64 @@ let GetDotenvCli$1 = class GetDotenvCli extends commander.Command {
             ctx;
         // Ensure plugins are installed exactly once, then run afterResolve.
         await this.install();
-        await this._runAfterResolve(ctx);
+        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).
      */
@@ -1572,6 +1714,7 @@ let GetDotenvCli$1 = class GetDotenvCli extends commander.Command {
     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;
@@ -1584,6 +1727,7 @@ let GetDotenvCli$1 = class GetDotenvCli extends commander.Command {
             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');
@@ -1594,6 +1738,7 @@ let GetDotenvCli$1 = class GetDotenvCli extends commander.Command {
         }
         finally {
             root.addOption = originalAddOption;
+            // eslint-disable-next-line @typescript-eslint/no-deprecated
             root.option = originalOption;
         }
     }
@@ -1639,6 +1784,40 @@ let GetDotenvCli$1 = class GetDotenvCli extends commander.Command {
         }
         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()).
@@ -1677,7 +1856,7 @@ let GetDotenvCli$1 = class GetDotenvCli extends commander.Command {
         for (const p of this._plugins)
             await run(p);
     }
-    // Render App/Plugin grouped options appended after default help.
+    // Render App/Plugin grouped options (used by helpInformation override).
     #renderOptionGroups(cmd) {
         const all = cmd.options ?? [];
         const byGroup = new Map();
@@ -1719,11 +1898,14 @@ let GetDotenvCli$1 = class GetDotenvCli extends commander.Command {
         }
         // 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) ?? [];
-            if (rows.length > 0) {
+            // 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);
             }
         }
@@ -1794,6 +1976,17 @@ class GetDotenvCli extends GetDotenvCli$1 {
             // 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();
@@ -1828,6 +2021,16 @@ class GetDotenvCli extends GetDotenvCli$1 {
             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 ?? {});