@karmaniverous/get-dotenv 5.2.5 → 6.0.0-0

package/dist/index.mjs

@@ -1,10 +1,10 @@
-import { Command, Option } from 'commander';
 import fs from 'fs-extra';
 import { packageDirectory } from 'package-directory';
-import url, { fileURLToPath, pathToFileURL } from 'url';
 import path, { join, extname } from 'path';
-import { z } from 'zod';
+import url, { fileURLToPath, pathToFileURL } from 'url';
 import YAML from 'yaml';
+import { z } from 'zod';
+import { Option, Command } from 'commander';
 import { nanoid } from 'nanoid';
 import { parse } from 'dotenv';
 import { createHash } from 'crypto';
@@ -40,8 +40,6 @@ const baseRootOptionDefaults = {
     // (debug/log/exclude* resolved via flag utils)
 };
 
-const baseGetDotenvCliOptions = baseRootOptionDefaults;
-
 /** @internal */
 const isPlainObject$1 = (value) => value !== null &&
     typeof value === 'object' &&
@@ -84,141 +82,130 @@ const defaultsDeep = (...layers) => {
     return result;
 };
 
-// src/GetDotenvOptions.ts
-const getDotenvOptionsFilename = 'getdotenv.config.json';
 /**
- * Helper to define a dynamic map with strong inference.
+ * Resolve a tri-state optional boolean flag under exactOptionalPropertyTypes.
+ * - If the user explicitly enabled the flag, return true.
+ * - If the user explicitly disabled (the "...-off" variant), return undefined (unset).
+ * - Otherwise, adopt the default (true → set; false/undefined → unset).
+ *
+ * @param exclude - The "on" flag value as parsed by Commander.
+ * @param excludeOff - The "off" toggle (present when specified) as parsed by Commander.
+ * @param defaultValue - The generator default to adopt when no explicit toggle is present.
+ * @returns boolean | undefined — use `undefined` to indicate "unset" (do not emit).
  *
  * @example
- * const dynamic = defineDynamic(\{ KEY: (\{ FOO = '' \}) =\> FOO + '-x' \});
+ * ```ts
+ * resolveExclusion(undefined, undefined, true); // => true
+ * ```
  */
-const defineDynamic = (d) => d;
+const resolveExclusion = (exclude, excludeOff, defaultValue) => exclude ? true : excludeOff ? undefined : defaultValue ? true : undefined;
 /**
- * Converts programmatic CLI options to `getDotenv` options. *
- * @param cliOptions - CLI options. Defaults to `{}`.
+ * Resolve an optional flag with "--exclude-all" overrides.
+ * If excludeAll is set and the individual "...-off" is not, force true.
+ * If excludeAllOff is set and the individual flag is not explicitly set, unset.
+ * Otherwise, adopt the default (true → set; false/undefined → unset).
  *
- * @returns `getDotenv` options.
+ * @param exclude - Individual include/exclude flag.
+ * @param excludeOff - Individual "...-off" flag.
+ * @param defaultValue - Default for the individual flag.
+ * @param excludeAll - Global "exclude-all" flag.
+ * @param excludeAllOff - Global "exclude-all-off" flag.
+ *
+ * @example
+ * resolveExclusionAll(undefined, undefined, false, true, undefined) =\> true
  */
-const getDotenvCliOptions2Options = ({ paths, pathsDelimiter, pathsDelimiterPattern, vars, varsAssignor, varsAssignorPattern, varsDelimiter, varsDelimiterPattern, ...rest }) => {
-    /**
-     * Convert CLI-facing string options into {@link GetDotenvOptions}.
-     *
-     * - Splits {@link GetDotenvCliOptions.paths} using either a delimiter   *   or a regular expression pattern into a string array.   * - Parses {@link GetDotenvCliOptions.vars} as space-separated `KEY=VALUE`
-     *   pairs (configurable delimiters) into a {@link ProcessEnv}.
-     * - Drops CLI-only keys that have no programmatic equivalent.
-     *
-     * @remarks
-     * Follows exact-optional semantics by not emitting undefined-valued entries.
-     */
-    // Drop CLI-only keys (debug/scripts) without relying on Record casts.
-    // Create a shallow copy then delete optional CLI-only keys if present.
-    const restObj = { ...rest };
-    delete restObj.debug;
-    delete restObj.scripts;
-    const splitBy = (value, delim, pattern) => (value ? value.split(pattern ? RegExp(pattern) : (delim ?? ' ')) : []);
-    // Tolerate vars as either a CLI string ("A=1 B=2") or an object map.
-    let parsedVars;
-    if (typeof vars === 'string') {
-        const kvPairs = splitBy(vars, varsDelimiter, varsDelimiterPattern).map((v) => v.split(varsAssignorPattern
-            ? RegExp(varsAssignorPattern)
-            : (varsAssignor ?? '=')));
-        parsedVars = Object.fromEntries(kvPairs);
-    }
-    else if (vars && typeof vars === 'object' && !Array.isArray(vars)) {
-        // Keep only string or undefined values to match ProcessEnv.
-        const entries = Object.entries(vars).filter(([k, v]) => typeof k === 'string' && (typeof v === 'string' || v === undefined));
-        parsedVars = Object.fromEntries(entries);
-    }
-    // Drop undefined-valued entries at the converter stage to match ProcessEnv
-    // expectations and the compat test assertions.
-    if (parsedVars) {
-        parsedVars = Object.fromEntries(Object.entries(parsedVars).filter(([, v]) => v !== undefined));
-    }
-    // Tolerate paths as either a delimited string or string[]
-    // Use a locally cast union type to avoid lint warnings about always-falsy conditions
-    // under the RootOptionsShape (which declares paths as string | undefined).
-    const pathsAny = paths;
-    const pathsOut = Array.isArray(pathsAny)
-        ? pathsAny.filter((p) => typeof p === 'string')
-        : splitBy(pathsAny, pathsDelimiter, pathsDelimiterPattern);
-    // Preserve exactOptionalPropertyTypes: only include keys when defined.
-    return {
-        ...restObj,
-        ...(pathsOut.length > 0 ? { paths: pathsOut } : {}),
-        ...(parsedVars !== undefined ? { vars: parsedVars } : {}),
-    };
-};
-const resolveGetDotenvOptions = async (customOptions) => {
-    /**
-     * Resolve {@link GetDotenvOptions} by layering defaults in ascending precedence:
-     *
-     * 1. Base defaults derived from the CLI generator defaults
-     *    ({@link baseGetDotenvCliOptions}).
-     * 2. Local project overrides from a `getdotenv.config.json` in the nearest
-     *    package root (if present).
-     * 3. The provided {@link customOptions}.
-     *
-     * The result preserves explicit empty values and drops only `undefined`.
-     *
-     * @returns Fully-resolved {@link GetDotenvOptions}.
-     *
-     * @example
-     * ```ts
-     * const options = await resolveGetDotenvOptions({ env: 'dev' });
-     * ```
-     */
-    const localPkgDir = await packageDirectory();
-    const localOptionsPath = localPkgDir
-        ? join(localPkgDir, getDotenvOptionsFilename)
-        : undefined;
-    const localOptions = (localOptionsPath && (await fs.exists(localOptionsPath))
-        ? JSON.parse((await fs.readFile(localOptionsPath)).toString())
-        : {});
-    // Merge order: base < local < custom (custom has highest precedence)
-    const mergedCli = defaultsDeep(baseGetDotenvCliOptions, localOptions);
-    const defaultsFromCli = getDotenvCliOptions2Options(mergedCli);
-    const result = defaultsDeep(defaultsFromCli, customOptions);
-    return {
-        ...result, // Keep explicit empty strings/zeros; drop only undefined
-        vars: Object.fromEntries(Object.entries(result.vars ?? {}).filter(([, v]) => v !== undefined)),
-    };
+const resolveExclusionAll = (exclude, excludeOff, defaultValue, excludeAll, excludeAllOff) => 
+// Order of precedence:
+// 1) Individual explicit "on" wins outright.
+// 2) Individual explicit "off" wins over any global.
+// 3) Global exclude-all forces true when not explicitly turned off.
+// 4) Global exclude-all-off unsets when the individual wasn't explicitly enabled.
+// 5) Fall back to the default (true => set; false/undefined => unset).
+(() => {
+    // Individual "on"
+    if (exclude === true)
+        return true;
+    // Individual "off"
+    if (excludeOff === true)
+        return undefined;
+    // Global "exclude-all" ON (unless explicitly turned off)
+    if (excludeAll === true)
+        return true;
+    // Global "exclude-all-off" (unless explicitly enabled)
+    if (excludeAllOff === true)
+        return undefined;
+    // Default
+    return defaultValue ? true : undefined;
+})();
+/**
+ * exactOptionalPropertyTypes-safe setter for optional boolean flags:
+ * delete when undefined; assign when defined — without requiring an index signature on T.
+ *
+ * @typeParam T - Target object type.
+ * @param obj - The object to write to.
+ * @param key - The optional boolean property key of {@link T}.
+ * @param value - The value to set or `undefined` to unset.
+ *
+ * @remarks
+ * Writes through a local `Record<string, unknown>` view to avoid requiring an index signature on {@link T}.
+ */
+const setOptionalFlag = (obj, key, value) => {
+    const target = obj;
+    const k = key;
+    // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+    if (value === undefined)
+        delete target[k];
+    else
+        target[k] = value;
 };
 
 /**
- * Zod schemas for programmatic GetDotenv options.
- *
- * NOTE: These schemas are introduced without wiring to avoid behavior changes.
- * Legacy paths continue to use existing types/logic. The new plugin host will
- * use these schemas in strict mode; legacy paths will adopt them in warn mode
- * later per the staged plan.
+ * Merge and normalize raw Commander options (current + parent + defaults)
+ * into a GetDotenvCliOptions-like object. Types are intentionally wide to
+ * avoid cross-layer coupling; callers may cast as needed.
  */
-// Minimal process env representation: string values or undefined to indicate "unset".
-const processEnvSchema = z.record(z.string(), z.string().optional());
-// RAW: all fields optional — undefined means "inherit" from lower layers.
-const getDotenvOptionsSchemaRaw = z.object({
-    defaultEnv: z.string().optional(),
-    dotenvToken: z.string().optional(),
-    dynamicPath: z.string().optional(),
-    // Dynamic map is intentionally wide for now; refine once sources are normalized.
-    dynamic: z.record(z.string(), z.unknown()).optional(),
-    env: z.string().optional(),
-    excludeDynamic: z.boolean().optional(),
-    excludeEnv: z.boolean().optional(),
-    excludeGlobal: z.boolean().optional(),
-    excludePrivate: z.boolean().optional(),
-    excludePublic: z.boolean().optional(),
-    loadProcess: z.boolean().optional(),
-    log: z.boolean().optional(),
-    outputPath: z.string().optional(),
-    paths: z.array(z.string()).optional(),
-    privateToken: z.string().optional(),
-    vars: processEnvSchema.optional(),
-    // Host-only feature flag: guarded integration of config loader/overlay
-    useConfigLoader: z.boolean().optional(),
-});
-// RESOLVED: service-boundary contract (post-inheritance).
-// For Step A, keep identical to RAW (no behavior change). Later stages will// materialize required defaults and narrow shapes as resolution is wired.
-const getDotenvOptionsSchemaResolved = getDotenvOptionsSchemaRaw;
+const resolveCliOptions = (rawCliOptions, defaults, parentJson) => {
+    const parent = typeof parentJson === 'string' && parentJson.length > 0
+        ? JSON.parse(parentJson)
+        : undefined;
+    const { command, debugOff, excludeAll, excludeAllOff, excludeDynamicOff, excludeEnvOff, excludeGlobalOff, excludePrivateOff, excludePublicOff, loadProcessOff, logOff, entropyWarn, entropyWarnOff, scripts, shellOff, ...rest } = rawCliOptions;
+    const current = { ...rest };
+    if (typeof scripts === 'string') {
+        try {
+            current.scripts = JSON.parse(scripts);
+        }
+        catch {
+            // ignore parse errors; leave scripts undefined
+        }
+    }
+    const merged = defaultsDeep({}, defaults, parent ?? {}, current);
+    const d = defaults;
+    setOptionalFlag(merged, 'debug', resolveExclusion(merged.debug, debugOff, d.debug));
+    setOptionalFlag(merged, 'excludeDynamic', resolveExclusionAll(merged.excludeDynamic, excludeDynamicOff, d.excludeDynamic, excludeAll, excludeAllOff));
+    setOptionalFlag(merged, 'excludeEnv', resolveExclusionAll(merged.excludeEnv, excludeEnvOff, d.excludeEnv, excludeAll, excludeAllOff));
+    setOptionalFlag(merged, 'excludeGlobal', resolveExclusionAll(merged.excludeGlobal, excludeGlobalOff, d.excludeGlobal, excludeAll, excludeAllOff));
+    setOptionalFlag(merged, 'excludePrivate', resolveExclusionAll(merged.excludePrivate, excludePrivateOff, d.excludePrivate, excludeAll, excludeAllOff));
+    setOptionalFlag(merged, 'excludePublic', resolveExclusionAll(merged.excludePublic, excludePublicOff, d.excludePublic, excludeAll, excludeAllOff));
+    setOptionalFlag(merged, 'log', resolveExclusion(merged.log, logOff, d.log));
+    setOptionalFlag(merged, 'loadProcess', resolveExclusion(merged.loadProcess, loadProcessOff, d.loadProcess));
+    // warnEntropy (tri-state)
+    setOptionalFlag(merged, 'warnEntropy', resolveExclusion(merged.warnEntropy, entropyWarnOff, d.warnEntropy));
+    // Normalize shell for predictability: explicit default shell per OS.
+    const defaultShell = process.platform === 'win32' ? 'powershell.exe' : '/bin/bash';
+    let resolvedShell = merged.shell;
+    if (shellOff)
+        resolvedShell = false;
+    else if (resolvedShell === true || resolvedShell === undefined) {
+        resolvedShell = defaultShell;
+    }
+    else if (typeof resolvedShell !== 'string' &&
+        typeof defaults.shell === 'string') {
+        resolvedShell = defaults.shell;
+    }
+    merged.shell = resolvedShell;
+    const cmd = typeof command === 'string' ? command : undefined;
+    return cmd !== undefined ? { merged, command: cmd } : { merged };
+};
 
 /**
  * Zod schemas for configuration files discovered by the new loader.
@@ -458,20 +445,190 @@ const resolveGetDotenvConfigSources = async (importMetaUrl) => {
 };
 
 /**
- * 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]}`
+ * Validate a composed env against config-provided validation surfaces.
+ * Precedence for validation definitions:
+ *   project.local -\> project.public -\> packaged
  *
- * 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.
+ * Behavior:
+ * - If a JS/TS `schema` is present, use schema.safeParse(finalEnv).
+ * - Else if `requiredKeys` is present, check presence (value !== undefined).
+ * - Returns a flat list of issue strings; caller decides warn vs fail.
+ */
+const validateEnvAgainstSources = (finalEnv, sources) => {
+    const pick = (getter) => {
+        const pl = sources.project?.local;
+        const pp = sources.project?.public;
+        const pk = sources.packaged;
+        return ((pl && getter(pl)) ||
+            (pp && getter(pp)) ||
+            (pk && getter(pk)) ||
+            undefined);
+    };
+    const schema = pick((cfg) => cfg['schema']);
+    if (schema &&
+        typeof schema.safeParse === 'function') {
+        try {
+            const parsed = schema.safeParse(finalEnv);
+            if (!parsed.success) {
+                // Try to render zod-style issues when available.
+                const err = parsed.error;
+                const issues = Array.isArray(err.issues) && err.issues.length > 0
+                    ? err.issues.map((i) => {
+                        const path = Array.isArray(i.path) ? i.path.join('.') : '';
+                        const msg = i.message ?? 'Invalid value';
+                        return path ? `[schema] ${path}: ${msg}` : `[schema] ${msg}`;
+                    })
+                    : ['[schema] validation failed'];
+                return issues;
+            }
+            return [];
+        }
+        catch {
+            // If schema invocation fails, surface a single diagnostic.
+            return [
+                '[schema] validation failed (unable to execute schema.safeParse)',
+            ];
+        }
+    }
+    const requiredKeys = pick((cfg) => cfg['requiredKeys']);
+    if (Array.isArray(requiredKeys) && requiredKeys.length > 0) {
+        const missing = requiredKeys.filter((k) => finalEnv[k] === undefined);
+        if (missing.length > 0) {
+            return missing.map((k) => `[requiredKeys] missing: ${k}`);
+        }
+    }
+    return [];
+};
+
+const baseGetDotenvCliOptions = baseRootOptionDefaults;
+
+// src/GetDotenvOptions.ts
+const getDotenvOptionsFilename = 'getdotenv.config.json';
+/**
+ * Helper to define a dynamic map with strong inference.
+ *
+ * @example
+ * const dynamic = defineDynamic(\{ KEY: (\{ FOO = '' \}) =\> FOO + '-x' \});
+ */
+const defineDynamic = (d) => d;
+/**
+ * Converts programmatic CLI options to `getDotenv` options. *
+ * @param cliOptions - CLI options. Defaults to `{}`.
+ *
+ * @returns `getDotenv` options.
+ */
+const getDotenvCliOptions2Options = ({ paths, pathsDelimiter, pathsDelimiterPattern, vars, varsAssignor, varsAssignorPattern, varsDelimiter, varsDelimiterPattern, ...rest }) => {
+    /**
+     * Convert CLI-facing string options into {@link GetDotenvOptions}.
+     *
+     * - Splits {@link GetDotenvCliOptions.paths} using either a delimiter   *   or a regular expression pattern into a string array.   * - Parses {@link GetDotenvCliOptions.vars} as space-separated `KEY=VALUE`
+     *   pairs (configurable delimiters) into a {@link ProcessEnv}.
+     * - Drops CLI-only keys that have no programmatic equivalent.
+     *
+     * @remarks
+     * Follows exact-optional semantics by not emitting undefined-valued entries.
+     */
+    // Drop CLI-only keys (debug/scripts) without relying on Record casts.
+    // Create a shallow copy then delete optional CLI-only keys if present.
+    const restObj = { ...rest };
+    delete restObj.debug;
+    delete restObj.scripts;
+    const splitBy = (value, delim, pattern) => (value ? value.split(pattern ? RegExp(pattern) : (delim ?? ' ')) : []);
+    // Tolerate vars as either a CLI string ("A=1 B=2") or an object map.
+    let parsedVars;
+    if (typeof vars === 'string') {
+        const kvPairs = splitBy(vars, varsDelimiter, varsDelimiterPattern).map((v) => v.split(varsAssignorPattern
+            ? RegExp(varsAssignorPattern)
+            : (varsAssignor ?? '=')));
+        parsedVars = Object.fromEntries(kvPairs);
+    }
+    else if (vars && typeof vars === 'object' && !Array.isArray(vars)) {
+        // Keep only string or undefined values to match ProcessEnv.
+        const entries = Object.entries(vars).filter(([k, v]) => typeof k === 'string' && (typeof v === 'string' || v === undefined));
+        parsedVars = Object.fromEntries(entries);
+    }
+    // Drop undefined-valued entries at the converter stage to match ProcessEnv
+    // expectations and the compat test assertions.
+    if (parsedVars) {
+        parsedVars = Object.fromEntries(Object.entries(parsedVars).filter(([, v]) => v !== undefined));
+    }
+    // Tolerate paths as either a delimited string or string[]
+    // Use a locally cast union type to avoid lint warnings about always-falsy conditions
+    // under the RootOptionsShape (which declares paths as string | undefined).
+    const pathsAny = paths;
+    const pathsOut = Array.isArray(pathsAny)
+        ? pathsAny.filter((p) => typeof p === 'string')
+        : splitBy(pathsAny, pathsDelimiter, pathsDelimiterPattern);
+    // Preserve exactOptionalPropertyTypes: only include keys when defined.
+    return {
+        ...restObj,
+        ...(pathsOut.length > 0 ? { paths: pathsOut } : {}),
+        ...(parsedVars !== undefined ? { vars: parsedVars } : {}),
+    };
+};
+const resolveGetDotenvOptions = async (customOptions) => {
+    /**
+     * Resolve {@link GetDotenvOptions} by layering defaults in ascending precedence:
+     *
+     * 1. Base defaults derived from the CLI generator defaults
+     *    ({@link baseGetDotenvCliOptions}).
+     * 2. Local project overrides from a `getdotenv.config.json` in the nearest
+     *    package root (if present).
+     * 3. The provided {@link customOptions}.
+     *
+     * The result preserves explicit empty values and drops only `undefined`.
+     *
+     * @returns Fully-resolved {@link GetDotenvOptions}.
+     *
+     * @example
+     * ```ts
+     * const options = await resolveGetDotenvOptions({ env: 'dev' });
+     * ```
+     */
+    const localPkgDir = await packageDirectory();
+    const localOptionsPath = localPkgDir
+        ? join(localPkgDir, getDotenvOptionsFilename)
+        : undefined;
+    // Safely read local CLI-facing defaults (defensive typing to satisfy strict linting).
+    let localOptions = {};
+    if (localOptionsPath && (await fs.exists(localOptionsPath))) {
+        try {
+            const txt = await fs.readFile(localOptionsPath, 'utf-8');
+            const parsed = JSON.parse(txt);
+            if (parsed && typeof parsed === 'object') {
+                localOptions = parsed;
+            }
+        }
+        catch {
+            // Malformed or unreadable local options are treated as absent.
+            localOptions = {};
+        }
+    }
+    // Merge order: base < local < custom (custom has highest precedence)
+    const mergedCli = defaultsDeep(baseGetDotenvCliOptions, localOptions);
+    const defaultsFromCli = getDotenvCliOptions2Options(mergedCli);
+    const result = defaultsDeep(defaultsFromCli, customOptions);
+    return {
+        ...result, // Keep explicit empty strings/zeros; drop only undefined
+        vars: Object.fromEntries(Object.entries(result.vars ?? {}).filter(([, v]) => v !== undefined)),
+    };
+};
+
+/**
+ * Dotenv expansion utilities.
+ *
+ * This module implements recursive expansion of environment-variable
+ * references in strings and records. It supports both whitespace and
+ * bracket syntaxes with optional defaults:
+ *
+ * - Whitespace: `$VAR[:default]`
+ * - Bracketed: `${VAR[:default]}`
+ *
+ * Escaped dollar signs (`\$`) are preserved.
+ * Unknown variables resolve to empty string unless a default is provided.
+ */
+/**
+ * Like String.prototype.search but returns the last index.
  * @internal
  */
 const searchLast = (str, rgx) => {
@@ -593,61 +750,271 @@ const dotenvExpandAll = (values = {}, options = {}) => Object.keys(values).reduc
  */
 const dotenvExpandFromProcessEnv = (value) => dotenvExpand(value, process.env);
 
-const applyKv = (current, kv) => {
-    if (!kv || Object.keys(kv).length === 0)
-        return current;
-    const expanded = dotenvExpandAll(kv, { ref: current, progressive: true });
-    return { ...current, ...expanded };
-};
-const applyConfigSlice = (current, cfg, env) => {
-    if (!cfg)
-        return current;
-    // kind axis: global then env (env overrides global)
-    const afterGlobal = applyKv(current, cfg.vars);
-    const envKv = env && cfg.envVars ? cfg.envVars[env] : undefined;
-    return applyKv(afterGlobal, envKv);
-};
+/* eslint-disable @typescript-eslint/no-deprecated */
 /**
- * Overlay config-provided values onto a base ProcessEnv using precedence axes:
- * - kind: env \> global
- * - privacy: local \> public
- * - source: project \> packaged \> base
- *
- * Programmatic explicit vars (if provided) override all config slices.
- * Progressive expansion is applied within each slice.
+ * 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 overlayEnv = ({ base, env, configs, programmaticVars, }) => {
-    let current = { ...base };
-    // Source: packaged (public -> local)
-    current = applyConfigSlice(current, configs.packaged, env);
-    // Packaged "local" is not expected by policy; if present, honor it.
-    // We do not have a separate object for packaged.local in sources, keep as-is.
-    // Source: project (public -> local)
-    current = applyConfigSlice(current, configs.project?.public, env);
-    current = applyConfigSlice(current, configs.project?.local, env);
-    // Programmatic explicit vars (top of static tier)
-    if (programmaticVars) {
-        const toApply = Object.fromEntries(Object.entries(programmaticVars).filter(([_k, v]) => typeof v === 'string'));
-        current = applyKv(current, toApply);
+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);
     }
-    return current;
-};
-
-/** src/diagnostics/entropy.ts
- * Entropy diagnostics (presentation-only).
- * - Gated by min length and printable ASCII.
- * - Warn once per key per run when bits/char \>= threshold.
- * - Supports whitelist patterns to suppress known-noise keys.
- */
-const warned = new Set();
-const isPrintableAscii = (s) => /^[\x20-\x7E]+$/.test(s);
-const compile$1 = (patterns) => (patterns ?? []).map((p) => new RegExp(p, 'i'));
-const whitelisted = (key, regs) => regs.some((re) => re.test(key));
-const shannonBitsPerChar = (s) => {
-    const freq = new Map();
-    for (const ch of s)
-        freq.set(ch, (freq.get(ch) ?? 0) + 1);
-    const n = s.length;
+    // 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 Option('-A, --exclude-all-off', `exclude all dotenv variables from loading OFF (default)`).conflicts('excludeAll'));
+    // Per-family exclusions (dynamic defaults)
+    p = p
+        .addOption(program
+        .createDynamicOption('-z, --exclude-dynamic', (cfg) => `exclude dynamic dotenv variables from loading ${onOff(true, Boolean(cfg.excludeDynamic))}`)
+        .conflicts('excludeDynamicOff'))
+        .addOption(program
+        .createDynamicOption('-Z, --exclude-dynamic-off', (cfg) => `exclude dynamic dotenv variables from loading ${onOff(false, !cfg.excludeDynamic)}`)
+        .conflicts('excludeDynamic'))
+        .addOption(program
+        .createDynamicOption('-n, --exclude-env', (cfg) => `exclude environment-specific dotenv variables from loading ${onOff(true, Boolean(cfg.excludeEnv))}`)
+        .conflicts('excludeEnvOff'))
+        .addOption(program
+        .createDynamicOption('-N, --exclude-env-off', (cfg) => `exclude environment-specific dotenv variables from loading ${onOff(false, !cfg.excludeEnv)}`)
+        .conflicts('excludeEnv'))
+        .addOption(program
+        .createDynamicOption('-g, --exclude-global', (cfg) => `exclude global dotenv variables from loading ${onOff(true, Boolean(cfg.excludeGlobal))}`)
+        .conflicts('excludeGlobalOff'))
+        .addOption(program
+        .createDynamicOption('-G, --exclude-global-off', (cfg) => `exclude global dotenv variables from loading ${onOff(false, !cfg.excludeGlobal)}`)
+        .conflicts('excludeGlobal'))
+        .addOption(program
+        .createDynamicOption('-r, --exclude-private', (cfg) => `exclude private dotenv variables from loading ${onOff(true, Boolean(cfg.excludePrivate))}`)
+        .conflicts('excludePrivateOff'))
+        .addOption(program
+        .createDynamicOption('-R, --exclude-private-off', (cfg) => `exclude private dotenv variables from loading ${onOff(false, !cfg.excludePrivate)}`)
+        .conflicts('excludePrivate'))
+        .addOption(program
+        .createDynamicOption('-u, --exclude-public', (cfg) => `exclude public dotenv variables from loading ${onOff(true, Boolean(cfg.excludePublic))}`)
+        .conflicts('excludePublicOff'))
+        .addOption(program
+        .createDynamicOption('-U, --exclude-public-off', (cfg) => `exclude public dotenv variables from loading ${onOff(false, !cfg.excludePublic)}`)
+        .conflicts('excludePublic'));
+    // Log ON/OFF (dynamic)
+    p = p
+        .addOption(program
+        .createDynamicOption('-l, --log', (cfg) => `console log loaded variables ${onOff(true, Boolean(cfg.log))}`)
+        .conflicts('logOff'))
+        .addOption(program
+        .createDynamicOption('-L, --log-off', (cfg) => `console log loaded variables ${onOff(false, !cfg.log)}`)
+        .conflicts('log'));
+    // Capture flag (no default display; static)
+    p = p.option('--capture', 'capture child process stdio for commands (tests/CI)');
+    // Core bootstrap/static flags (kept static in help)
+    p = p
+        .option('--default-env <string>', 'default target environment', dotenvExpandFromProcessEnv, defaultEnv)
+        .option('--dotenv-token <string>', 'dotenv-expanded token indicating a dotenv file', dotenvExpandFromProcessEnv, dotenvToken)
+        .option('--dynamic-path <string>', 'dynamic variables path (.js or .ts; .ts is auto-compiled when esbuild is available, otherwise precompile)', dotenvExpandFromProcessEnv, dynamicPath)
+        .option('--paths <string>', 'dotenv-expanded delimited list of paths to dotenv directory', dotenvExpandFromProcessEnv, paths)
+        .option('--paths-delimiter <string>', 'paths delimiter string', pathsDelimiter)
+        .option('--paths-delimiter-pattern <string>', 'paths delimiter regex pattern', pathsDelimiterPattern)
+        .option('--private-token <string>', 'dotenv-expanded token indicating private variables', dotenvExpandFromProcessEnv, privateToken)
+        .option('--vars-delimiter <string>', 'vars delimiter string', varsDelimiter)
+        .option('--vars-delimiter-pattern <string>', 'vars delimiter regex pattern', varsDelimiterPattern)
+        .option('--vars-assignor <string>', 'vars assignment operator string', varsAssignor)
+        .option('--vars-assignor-pattern <string>', 'vars assignment operator regex pattern', varsAssignorPattern)
+        // Hidden scripts pipe-through (stringified)
+        .addOption(new Option('--scripts <string>')
+        .default(JSON.stringify(scripts))
+        .hideHelp());
+    // Diagnostics / validation / entropy
+    p = p
+        .option('--trace [keys...]', 'emit diagnostics for child env composition (optional keys)')
+        .option('--strict', 'fail on env validation errors (schema/requiredKeys)');
+    p = p
+        .addOption(program
+        .createDynamicOption('--entropy-warn', (cfg) => {
+        const warn = cfg.warnEntropy;
+        // Default is effectively ON when warnEntropy is true or undefined.
+        return `enable entropy warnings${warn === false ? '' : ' (default on)'}`;
+    })
+        .conflicts('entropyWarnOff'))
+        .addOption(program
+        .createDynamicOption('--entropy-warn-off', (cfg) => `disable entropy warnings${cfg.warnEntropy === false ? ' (default)' : ''}`)
+        .conflicts('entropyWarn'))
+        .option('--entropy-threshold <number>', 'entropy bits/char threshold (default 3.8)')
+        .option('--entropy-min-length <number>', 'min length to examine for entropy (default 16)')
+        .option('--entropy-whitelist <pattern...>', 'suppress entropy warnings when key matches any regex pattern')
+        .option('--redact-pattern <pattern...>', 'additional key-match regex patterns to trigger redaction');
+    // Restore original methods
+    program.addOption = originalAddOption;
+    program.option = originalOption;
+    return p;
+};
+
+/**
+ * Zod schemas for programmatic GetDotenv options.
+ *
+ * NOTE: These schemas are introduced without wiring to avoid behavior changes.
+ * Legacy paths continue to use existing types/logic. The new plugin host will
+ * use these schemas in strict mode; legacy paths will adopt them in warn mode
+ * later per the staged plan.
+ */
+// Minimal process env representation: string values or undefined to indicate "unset".
+const processEnvSchema = z.record(z.string(), z.string().optional());
+// RAW: all fields optional — undefined means "inherit" from lower layers.
+const getDotenvOptionsSchemaRaw = z.object({
+    defaultEnv: z.string().optional(),
+    dotenvToken: z.string().optional(),
+    dynamicPath: z.string().optional(),
+    // Dynamic map is intentionally wide for now; refine once sources are normalized.
+    dynamic: z.record(z.string(), z.unknown()).optional(),
+    env: z.string().optional(),
+    excludeDynamic: z.boolean().optional(),
+    excludeEnv: z.boolean().optional(),
+    excludeGlobal: z.boolean().optional(),
+    excludePrivate: z.boolean().optional(),
+    excludePublic: z.boolean().optional(),
+    loadProcess: z.boolean().optional(),
+    log: z.boolean().optional(),
+    outputPath: z.string().optional(),
+    paths: z.array(z.string()).optional(),
+    privateToken: z.string().optional(),
+    vars: processEnvSchema.optional(),
+    // Host-only feature flag: guarded integration of config loader/overlay
+    useConfigLoader: z.boolean().optional(),
+});
+// RESOLVED: service-boundary contract (post-inheritance).
+// For Step A, keep identical to RAW (no behavior change). Later stages will// materialize required defaults and narrow shapes as resolution is wired.
+const getDotenvOptionsSchemaResolved = getDotenvOptionsSchemaRaw;
+
+const applyKv = (current, kv) => {
+    if (!kv || Object.keys(kv).length === 0)
+        return current;
+    const expanded = dotenvExpandAll(kv, { ref: current, progressive: true });
+    return { ...current, ...expanded };
+};
+const applyConfigSlice = (current, cfg, env) => {
+    if (!cfg)
+        return current;
+    // kind axis: global then env (env overrides global)
+    const afterGlobal = applyKv(current, cfg.vars);
+    const envKv = env && cfg.envVars ? cfg.envVars[env] : undefined;
+    return applyKv(afterGlobal, envKv);
+};
+/**
+ * Overlay config-provided values onto a base ProcessEnv using precedence axes:
+ * - kind: env \> global
+ * - privacy: local \> public
+ * - source: project \> packaged \> base
+ *
+ * Programmatic explicit vars (if provided) override all config slices.
+ * Progressive expansion is applied within each slice.
+ */
+const overlayEnv = ({ base, env, configs, programmaticVars, }) => {
+    let current = { ...base };
+    // Source: packaged (public -> local)
+    current = applyConfigSlice(current, configs.packaged, env);
+    // Packaged "local" is not expected by policy; if present, honor it.
+    // We do not have a separate object for packaged.local in sources, keep as-is.
+    // Source: project (public -> local)
+    current = applyConfigSlice(current, configs.project?.public, env);
+    current = applyConfigSlice(current, configs.project?.local, env);
+    // Programmatic explicit vars (top of static tier)
+    if (programmaticVars) {
+        const toApply = Object.fromEntries(Object.entries(programmaticVars).filter(([_k, v]) => typeof v === 'string'));
+        current = applyKv(current, toApply);
+    }
+    return current;
+};
+
+/** src/diagnostics/entropy.ts
+ * Entropy diagnostics (presentation-only).
+ * - Gated by min length and printable ASCII.
+ * - Warn once per key per run when bits/char \>= threshold.
+ * - Supports whitelist patterns to suppress known-noise keys.
+ */
+const warned = new Set();
+const isPrintableAscii = (s) => /^[\x20-\x7E]+$/.test(s);
+const compile$1 = (patterns) => (patterns ?? []).map((p) => new RegExp(p, 'i'));
+const whitelisted = (key, regs) => regs.some((re) => re.test(key));
+const shannonBitsPerChar = (s) => {
+    const freq = new Map();
+    for (const ch of s)
+        freq.set(ch, (freq.get(ch) ?? 0) + 1);
+    const n = s.length;
     let h = 0;
     for (const c of freq.values()) {
         const p = c / n;
@@ -1190,6 +1557,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 = import.meta.url;
 const CTX_SYMBOL = Symbol('GetDotenvCli.ctx');
 const OPTS_SYMBOL = Symbol('GetDotenvCli.options');
@@ -1205,13 +1574,20 @@ const HELP_HEADER_SYMBOL = Symbol('GetDotenvCli.helpHeader');
  *
  * NOTE: This host is additive and does not alter the legacy CLI.
  */
-class GetDotenvCli extends Command {
+let GetDotenvCli$1 = class GetDotenvCli extends Command {
     /** Registered top-level plugins (composition happens via .use()) */
     _plugins = [];
     /** One-time installation guard */
     _installed = false;
     /** Optional header line to prepend in help output */
     [HELP_HEADER_SYMBOL];
+    /**
+     * Create a subcommand using the same subclass, preserving helpers like
+     * dynamicOption on children.
+     */
+    createCommand(name) {
+        return new this.constructor(name);
+    }
     constructor(alias = 'getdotenv') {
         super(alias);
         // Ensure subcommands that use passThroughOptions can be attached safely.
@@ -1219,15 +1595,18 @@ class GetDotenvCli extends 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 ?? '';
@@ -1235,19 +1614,18 @@ class GetDotenvCli extends 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
@@ -1259,9 +1637,15 @@ class GetDotenvCli extends 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);
@@ -1272,9 +1656,64 @@ class GetDotenvCli extends 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 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).
      */
@@ -1304,6 +1743,7 @@ class GetDotenvCli extends 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;
@@ -1316,6 +1756,7 @@ class GetDotenvCli extends 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');
@@ -1326,6 +1767,7 @@ class GetDotenvCli extends Command {
         }
         finally {
             root.addOption = originalAddOption;
+            // eslint-disable-next-line @typescript-eslint/no-deprecated
             root.option = originalOption;
         }
     }
@@ -1371,6 +1813,40 @@ class GetDotenvCli extends 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()).
@@ -1409,7 +1885,7 @@ class GetDotenvCli extends 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();
@@ -1451,369 +1927,96 @@ class GetDotenvCli extends 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);
             }
         }
         return out;
     }
-}
-
-/**
- * Validate a composed env against config-provided validation surfaces.
- * Precedence for validation definitions:
- *   project.local -\> project.public -\> packaged
- *
- * Behavior:
- * - If a JS/TS `schema` is present, use schema.safeParse(finalEnv).
- * - Else if `requiredKeys` is present, check presence (value !== undefined).
- * - Returns a flat list of issue strings; caller decides warn vs fail.
- */
-const validateEnvAgainstSources = (finalEnv, sources) => {
-    const pick = (getter) => {
-        const pl = sources.project?.local;
-        const pp = sources.project?.public;
-        const pk = sources.packaged;
-        return ((pl && getter(pl)) ||
-            (pp && getter(pp)) ||
-            (pk && getter(pk)) ||
-            undefined);
-    };
-    const schema = pick((cfg) => cfg['schema']);
-    if (schema &&
-        typeof schema.safeParse === 'function') {
-        try {
-            const parsed = schema.safeParse(finalEnv);
-            if (!parsed.success) {
-                // Try to render zod-style issues when available.
-                const err = parsed.error;
-                const issues = Array.isArray(err.issues) && err.issues.length > 0
-                    ? err.issues.map((i) => {
-                        const path = Array.isArray(i.path) ? i.path.join('.') : '';
-                        const msg = i.message ?? 'Invalid value';
-                        return path ? `[schema] ${path}: ${msg}` : `[schema] ${msg}`;
-                    })
-                    : ['[schema] validation failed'];
-                return issues;
-            }
-            return [];
-        }
-        catch {
-            // If schema invocation fails, surface a single diagnostic.
-            return [
-                '[schema] validation failed (unable to execute schema.safeParse)',
-            ];
-        }
-    }
-    const requiredKeys = pick((cfg) => cfg['requiredKeys']);
-    if (Array.isArray(requiredKeys) && requiredKeys.length > 0) {
-        const missing = requiredKeys.filter((k) => finalEnv[k] === undefined);
-        if (missing.length > 0) {
-            return missing.map((k) => `[requiredKeys] missing: ${k}`);
-        }
-    }
-    return [];
-};
-
-/**
- * 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 Option('-s, --shell [string]', (() => {
-        let defaultLabel = '';
-        if (shell !== undefined) {
-            if (typeof shell === 'boolean') {
-                defaultLabel = ' (default OS shell)';
-            }
-            else if (typeof shell === 'string') {
-                // Safe string interpolation
-                defaultLabel = ` (default ${shell})`;
-            }
-        }
-        return `command execution shell, no argument for default OS shell or provide shell string${defaultLabel}`;
-    })()).conflicts('shellOff'))
-        .addOption(new Option('-S, --shell-off', `command execution shell OFF${!shell ? ' (default)' : ''}`).conflicts('shell'))
-        .addOption(new Option('-p, --load-process', `load variables to process.env ON${loadProcess ? ' (default)' : ''}`).conflicts('loadProcessOff'))
-        .addOption(new Option('-P, --load-process-off', `load variables to process.env OFF${!loadProcess ? ' (default)' : ''}`).conflicts('loadProcess'))
-        .addOption(new Option('-a, --exclude-all', `exclude all dotenv variables from loading ON${excludeDynamic &&
-        ((excludeEnv && excludeGlobal) || (excludePrivate && excludePublic))
-        ? ' (default)'
-        : ''}`).conflicts('excludeAllOff'))
-        .addOption(new Option('-A, --exclude-all-off', `exclude all dotenv variables from loading OFF (default)`).conflicts('excludeAll'))
-        .addOption(new Option('-z, --exclude-dynamic', `exclude dynamic dotenv variables from loading ON${excludeDynamic ? ' (default)' : ''}`).conflicts('excludeDynamicOff'))
-        .addOption(new Option('-Z, --exclude-dynamic-off', `exclude dynamic dotenv variables from loading OFF${!excludeDynamic ? ' (default)' : ''}`).conflicts('excludeDynamic'))
-        .addOption(new Option('-n, --exclude-env', `exclude environment-specific dotenv variables from loading${excludeEnv ? ' (default)' : ''}`).conflicts('excludeEnvOff'))
-        .addOption(new Option('-N, --exclude-env-off', `exclude environment-specific dotenv variables from loading OFF${!excludeEnv ? ' (default)' : ''}`).conflicts('excludeEnv'))
-        .addOption(new Option('-g, --exclude-global', `exclude global dotenv variables from loading ON${excludeGlobal ? ' (default)' : ''}`).conflicts('excludeGlobalOff'))
-        .addOption(new Option('-G, --exclude-global-off', `exclude global dotenv variables from loading OFF${!excludeGlobal ? ' (default)' : ''}`).conflicts('excludeGlobal'))
-        .addOption(new Option('-r, --exclude-private', `exclude private dotenv variables from loading ON${excludePrivate ? ' (default)' : ''}`).conflicts('excludePrivateOff'))
-        .addOption(new Option('-R, --exclude-private-off', `exclude private dotenv variables from loading OFF${!excludePrivate ? ' (default)' : ''}`).conflicts('excludePrivate'))
-        .addOption(new Option('-u, --exclude-public', `exclude public dotenv variables from loading ON${excludePublic ? ' (default)' : ''}`).conflicts('excludePublicOff'))
-        .addOption(new Option('-U, --exclude-public-off', `exclude public dotenv variables from loading OFF${!excludePublic ? ' (default)' : ''}`).conflicts('excludePublic'))
-        .addOption(new Option('-l, --log', `console log loaded variables ON${log ? ' (default)' : ''}`).conflicts('logOff'))
-        .addOption(new Option('-L, --log-off', `console log loaded variables OFF${!log ? ' (default)' : ''}`).conflicts('log'))
-        .option('--capture', 'capture child process stdio for commands (tests/CI)')
-        .option('--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 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 Option('--entropy-warn', 'enable entropy warnings (default on)').conflicts('entropyWarnOff'))
-        .addOption(new 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;
 };
 
-/**
- * Resolve a tri-state optional boolean flag under exactOptionalPropertyTypes.
- * - If the user explicitly enabled the flag, return true.
- * - If the user explicitly disabled (the "...-off" variant), return undefined (unset).
- * - Otherwise, adopt the default (true → set; false/undefined → unset).
- *
- * @param exclude - The "on" flag value as parsed by Commander.
- * @param excludeOff - The "off" toggle (present when specified) as parsed by Commander.
- * @param defaultValue - The generator default to adopt when no explicit toggle is present.
- * @returns boolean | undefined — use `undefined` to indicate "unset" (do not emit).
+/** src/cliHost/definePlugin.ts
+ * Plugin contracts for the GetDotenv CLI host.
  *
- * @example
- * ```ts
- * resolveExclusion(undefined, undefined, true); // => true
- * ```
+ * This module exposes a structural public interface for the host that plugins
+ * should use (GetDotenvCliPublic). Using a structural type at the seam avoids
+ * nominal class identity issues (private fields) in downstream consumers.
  */
-const resolveExclusion = (exclude, excludeOff, defaultValue) => exclude ? true : excludeOff ? undefined : defaultValue ? true : undefined;
 /**
- * Resolve an optional flag with "--exclude-all" overrides.
- * If excludeAll is set and the individual "...-off" is not, force true.
- * If excludeAllOff is set and the individual flag is not explicitly set, unset.
- * Otherwise, adopt the default (true → set; false/undefined → unset).
- *
- * @param exclude - Individual include/exclude flag.
- * @param excludeOff - Individual "...-off" flag.
- * @param defaultValue - Default for the individual flag.
- * @param excludeAll - Global "exclude-all" flag.
- * @param excludeAllOff - Global "exclude-all-off" flag.
+ * Define a GetDotenv CLI plugin with compositional helpers.
  *
  * @example
- * resolveExclusionAll(undefined, undefined, false, true, undefined) =\> true
- */
-const resolveExclusionAll = (exclude, excludeOff, defaultValue, excludeAll, excludeAllOff) => 
-// Order of precedence:
-// 1) Individual explicit "on" wins outright.
-// 2) Individual explicit "off" wins over any global.
-// 3) Global exclude-all forces true when not explicitly turned off.
-// 4) Global exclude-all-off unsets when the individual wasn't explicitly enabled.
-// 5) Fall back to the default (true => set; false/undefined => unset).
-(() => {
-    // Individual "on"
-    if (exclude === true)
-        return true;
-    // Individual "off"
-    if (excludeOff === true)
-        return undefined;
-    // Global "exclude-all" ON (unless explicitly turned off)
-    if (excludeAll === true)
-        return true;
-    // Global "exclude-all-off" (unless explicitly enabled)
-    if (excludeAllOff === true)
-        return undefined;
-    // Default
-    return defaultValue ? true : undefined;
-})();
-/**
- * exactOptionalPropertyTypes-safe setter for optional boolean flags:
- * delete when undefined; assign when defined — without requiring an index signature on T.
- *
- * @typeParam T - Target object type.
- * @param obj - The object to write to.
- * @param key - The optional boolean property key of {@link T}.
- * @param value - The value to set or `undefined` to unset.
- *
- * @remarks
- * Writes through a local `Record<string, unknown>` view to avoid requiring an index signature on {@link T}.
- */
-const setOptionalFlag = (obj, key, value) => {
-    const target = obj;
-    const k = key;
-    // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
-    if (value === undefined)
-        delete target[k];
-    else
-        target[k] = value;
-};
-
-/**
- * Merge and normalize raw Commander options (current + parent + defaults)
- * into a GetDotenvCliOptions-like object. Types are intentionally wide to
- * avoid cross-layer coupling; callers may cast as needed.
+ * const parent = definePlugin(\{ id: 'p', setup(cli) \{ /* ... *\/ \} \})
+ *   .use(childA)
+ *   .use(childB);
  */
-const resolveCliOptions = (rawCliOptions, defaults, parentJson) => {
-    const parent = typeof parentJson === 'string' && parentJson.length > 0
-        ? JSON.parse(parentJson)
-        : undefined;
-    const { command, debugOff, excludeAll, excludeAllOff, excludeDynamicOff, excludeEnvOff, excludeGlobalOff, excludePrivateOff, excludePublicOff, loadProcessOff, logOff, entropyWarn, entropyWarnOff, scripts, shellOff, ...rest } = rawCliOptions;
-    const current = { ...rest };
-    if (typeof scripts === 'string') {
-        try {
-            current.scripts = JSON.parse(scripts);
-        }
-        catch {
-            // ignore parse errors; leave scripts undefined
-        }
-    }
-    const merged = defaultsDeep({}, defaults, parent ?? {}, current);
-    const d = defaults;
-    setOptionalFlag(merged, 'debug', resolveExclusion(merged.debug, debugOff, d.debug));
-    setOptionalFlag(merged, 'excludeDynamic', resolveExclusionAll(merged.excludeDynamic, excludeDynamicOff, d.excludeDynamic, excludeAll, excludeAllOff));
-    setOptionalFlag(merged, 'excludeEnv', resolveExclusionAll(merged.excludeEnv, excludeEnvOff, d.excludeEnv, excludeAll, excludeAllOff));
-    setOptionalFlag(merged, 'excludeGlobal', resolveExclusionAll(merged.excludeGlobal, excludeGlobalOff, d.excludeGlobal, excludeAll, excludeAllOff));
-    setOptionalFlag(merged, 'excludePrivate', resolveExclusionAll(merged.excludePrivate, excludePrivateOff, d.excludePrivate, excludeAll, excludeAllOff));
-    setOptionalFlag(merged, 'excludePublic', resolveExclusionAll(merged.excludePublic, excludePublicOff, d.excludePublic, excludeAll, excludeAllOff));
-    setOptionalFlag(merged, 'log', resolveExclusion(merged.log, logOff, d.log));
-    setOptionalFlag(merged, 'loadProcess', resolveExclusion(merged.loadProcess, loadProcessOff, d.loadProcess));
-    // warnEntropy (tri-state)
-    setOptionalFlag(merged, 'warnEntropy', resolveExclusion(merged.warnEntropy, entropyWarnOff, d.warnEntropy));
-    // Normalize shell for predictability: explicit default shell per OS.
-    const defaultShell = process.platform === 'win32' ? 'powershell.exe' : '/bin/bash';
-    let resolvedShell = merged.shell;
-    if (shellOff)
-        resolvedShell = false;
-    else if (resolvedShell === true || resolvedShell === undefined) {
-        resolvedShell = defaultShell;
-    }
-    else if (typeof resolvedShell !== 'string' &&
-        typeof defaults.shell === 'string') {
-        resolvedShell = defaults.shell;
-    }
-    merged.shell = resolvedShell;
-    const cmd = typeof command === 'string' ? command : undefined;
-    return cmd !== undefined ? { merged, command: cmd } : { merged };
+const definePlugin = (spec) => {
+    const { children = [], ...rest } = spec;
+    const plugin = {
+        ...rest,
+        children: [...children],
+        use(child) {
+            this.children.push(child);
+            return this;
+        },
+    };
+    return plugin;
 };
 
-GetDotenvCli.prototype.attachRootOptions = function (defaults, opts) {
-    const d = (defaults ?? baseRootOptionDefaults);
-    attachRootOptions(this, d, opts);
-    return this;
-};
-GetDotenvCli.prototype.passOptions = function (defaults) {
-    const d = (defaults ?? baseRootOptionDefaults);
-    this.hook('preSubcommand', async (thisCommand) => {
-        const raw = thisCommand.opts();
-        const { merged } = resolveCliOptions(raw, d, process.env.getDotenvCliOptions);
-        // Persist merged options for nested invocations (batch exec).
-        thisCommand.getDotenvCliOptions =
-            merged;
-        // Also store on the host for downstream ergonomic accessors.
-        this._setOptionsBag(merged);
-        // Build service options and compute context (always-on config loader path).
-        const serviceOptions = getDotenvCliOptions2Options(merged);
-        await this.resolveAndLoad(serviceOptions);
-        // Global validation: once after Phase C using config sources.
-        try {
-            const ctx = this.getCtx();
-            const dotenv = (ctx?.dotenv ?? {});
-            const sources = await resolveGetDotenvConfigSources(import.meta.url);
-            const issues = validateEnvAgainstSources(dotenv, sources);
-            if (Array.isArray(issues) && issues.length > 0) {
-                const logger = (merged.logger ??
-                    console);
-                const emit = logger.error ?? logger.log;
-                issues.forEach((m) => {
-                    emit(m);
-                });
-                if (merged.strict) {
-                    // Deterministic failure under strict mode
-                    process.exit(1);
-                }
-            }
-        }
-        catch {
-            // Be tolerant: validation errors reported above; unexpected failures here
-            // should not crash non-strict flows.
-        }
-    });
-    // Also handle root-level flows (no subcommand) so option-aliases can run
-    // with the same merged options and context without duplicating logic.
-    this.hook('preAction', async (thisCommand) => {
-        const raw = thisCommand.opts();
-        const { merged } = resolveCliOptions(raw, d, process.env.getDotenvCliOptions);
-        thisCommand.getDotenvCliOptions =
-            merged;
-        this._setOptionsBag(merged);
-        // Avoid duplicate heavy work if a context is already present.
-        if (!this.getCtx()) {
+/**
+ * GetDotenvCli with root helpers as real class methods.
+ * - attachRootOptions: installs legacy/base root flags on the command.
+ * - passOptions: merges flags (parent \< current), computes dotenv context once,
+ *   runs validation, and persists merged options for nested flows.
+ */
+class GetDotenvCli extends GetDotenvCli$1 {
+    /**
+     * Attach legacy root flags to this CLI instance. Defaults come from
+     * baseRootOptionDefaults when none are provided.
+     */
+    attachRootOptions(defaults, opts) {
+        const d = (defaults ?? baseRootOptionDefaults);
+        attachRootOptions(this, d, opts);
+        return this;
+    }
+    /**
+     * Install preSubcommand/preAction hooks that:
+     * - Merge options (parent round-trip + current invocation) using resolveCliOptions.
+     * - Persist the merged bag on the current command and on the host (for ergonomics).
+     * - Compute the dotenv context once via resolveAndLoad(serviceOptions).
+     * - Validate the composed env against discovered config (warn or --strict fail).
+     */
+    passOptions(defaults) {
+        const d = (defaults ?? baseRootOptionDefaults);
+        this.hook('preSubcommand', async (thisCommand) => {
+            const raw = thisCommand.opts();
+            const { merged } = resolveCliOptions(raw, d, process.env.getDotenvCliOptions);
+            // Persist merged options (for nested behavior and ergonomic access).
+            thisCommand.getDotenvCliOptions =
+                merged;
+            this._setOptionsBag(merged);
+            // Build service options and compute context (always-on loader path).
             const serviceOptions = getDotenvCliOptions2Options(merged);
             await this.resolveAndLoad(serviceOptions);
+            // Refresh dynamic option descriptions using resolved config + plugin slices
+            try {
+                const ctx = this.getCtx();
+                this.evaluateDynamicOptions({
+                    ...ctx?.optionsResolved,
+                    plugins: ctx?.pluginConfigs ?? {},
+                });
+            }
+            catch {
+                /* best-effort */
+            }
+            // Global validation: once after Phase C using config sources.
             try {
                 const ctx = this.getCtx();
                 const dotenv = (ctx?.dotenv ?? {});
@@ -1832,12 +2035,56 @@ GetDotenvCli.prototype.passOptions = function (defaults) {
                 }
             }
             catch {
-                // Tolerate validation side-effects in non-strict mode
+                // Be tolerant: do not crash non-strict flows on unexpected validator failures.
             }
-        }
-    });
-    return this;
-};
+        });
+        // Also handle root-level flows (no subcommand) so option-aliases can run
+        // with the same merged options and context without duplicating logic.
+        this.hook('preAction', async (thisCommand) => {
+            const raw = thisCommand.opts();
+            const { merged } = resolveCliOptions(raw, d, process.env.getDotenvCliOptions);
+            thisCommand.getDotenvCliOptions =
+                merged;
+            this._setOptionsBag(merged);
+            // Avoid duplicate heavy work if a context is already present.
+            if (!this.getCtx()) {
+                const serviceOptions = getDotenvCliOptions2Options(merged);
+                await this.resolveAndLoad(serviceOptions);
+                try {
+                    const ctx = this.getCtx();
+                    this.evaluateDynamicOptions({
+                        ...ctx?.optionsResolved,
+                        plugins: ctx?.pluginConfigs ?? {},
+                    });
+                }
+                catch {
+                    /* tolerate */
+                }
+                try {
+                    const ctx = this.getCtx();
+                    const dotenv = (ctx?.dotenv ?? {});
+                    const sources = await resolveGetDotenvConfigSources(import.meta.url);
+                    const issues = validateEnvAgainstSources(dotenv, sources);
+                    if (Array.isArray(issues) && issues.length > 0) {
+                        const logger = (merged
+                            .logger ?? console);
+                        const emit = logger.error ?? logger.log;
+                        issues.forEach((m) => {
+                            emit(m);
+                        });
+                        if (merged.strict) {
+                            process.exit(1);
+                        }
+                    }
+                }
+                catch {
+                    // Tolerate validation side-effects in non-strict mode.
+                }
+            }
+        });
+        return this;
+    }
+}
 
 // Minimal tokenizer for shell-off execution:
 // Splits by whitespace while preserving quoted segments (single or double quotes).
@@ -2072,34 +2319,6 @@ const buildSpawnEnv = (base, overlay) => {
     return out;
 };
 
-/** src/cliHost/definePlugin.ts
- * Plugin contracts for the GetDotenv CLI host.
- *
- * This module exposes a structural public interface for the host that plugins
- * should use (GetDotenvCliPublic). Using a structural type at the seam avoids
- * nominal class identity issues (private fields) in downstream consumers.
- */
-/**
- * Define a GetDotenv CLI plugin with compositional helpers.
- *
- * @example
- * const parent = definePlugin(\{ id: 'p', setup(cli) \{ /* ... *\/ \} \})
- *   .use(childA)
- *   .use(childB);
- */
-const definePlugin = (spec) => {
-    const { children = [], ...rest } = spec;
-    const plugin = {
-        ...rest,
-        children: [...children],
-        use(child) {
-            this.children.push(child);
-            return this;
-        },
-    };
-    return plugin;
-};
-
 /**
  * Batch services (neutral): resolve command and shell settings.
  * Shared by the generator path and the batch plugin to avoid circular deps.
@@ -2335,7 +2554,6 @@ const awsPlugin = () => definePlugin({
         cli
             .ns('aws')
             .description('Establish an AWS session and optionally forward to the AWS CLI')
-            .configureHelp({ showGlobalOptions: true })
             .enablePositionalOptions()
             .passThroughOptions()
             .allowUnknownOption(true)
@@ -2526,9 +2744,10 @@ const globPaths = async ({ globs, logger, pkgCwd, rootPath, }) => {
     }
     return { absRootPath, paths };
 };
-const execShellCommandBatch = async ({ command, getDotenvCliOptions, globs, ignoreErrors, list, logger, pkgCwd, rootPath, shell, }) => {
+const execShellCommandBatch = async ({ command, getDotenvCliOptions, dotenvEnv, globs, ignoreErrors, list, logger, pkgCwd, rootPath, shell, }) => {
     const capture = process.env.GETDOTENV_STDIO === 'pipe' ||
-        Boolean(getDotenvCliOptions?.capture); // Require a command only when not listing. In list mode, a command is optional.
+        Boolean(getDotenvCliOptions?.capture);
+    // Require a command only when not listing. In list mode, a command is optional.
     if (!command && !list) {
         logger.error(`No command provided. Use --command or --list.`);
         process.exit(0);
@@ -2575,12 +2794,25 @@ const execShellCommandBatch = async ({ command, getDotenvCliOptions, globs, igno
             const hasCmd = (typeof command === 'string' && command.length > 0) ||
                 (Array.isArray(command) && command.length > 0);
             if (hasCmd) {
-                const envBag = getDotenvCliOptions !== undefined
-                    ? { getDotenvCliOptions: JSON.stringify(getDotenvCliOptions) }
-                    : undefined;
+                // Compose child env overlay from dotenv (drop undefined) and merged options
+                const overlay = {};
+                if (dotenvEnv) {
+                    for (const [k, v] of Object.entries(dotenvEnv)) {
+                        if (typeof v === 'string')
+                            overlay[k] = v;
+                    }
+                }
+                if (getDotenvCliOptions !== undefined) {
+                    try {
+                        overlay.getDotenvCliOptions = JSON.stringify(getDotenvCliOptions);
+                    }
+                    catch {
+                        // best-effort: omit if serialization fails
+                    }
+                }
                 await runCommand(command, shell, {
                     cwd: path,
-                    env: buildSpawnEnv(process.env, envBag),
+                    env: buildSpawnEnv(process.env, overlay),
                     stdio: capture ? 'pipe' : 'inherit',
                 });
             }
@@ -2618,6 +2850,7 @@ const buildDefaultCmdAction = (cli, batchCmd, opts) => async (commandParts, _sub
     const ctx = cli.getCtx();
     const cfgRaw = (ctx?.pluginConfigs?.['batch'] ?? {});
     const cfg = (cfgRaw || {});
+    const dotenvEnv = (ctx?.dotenv ?? {});
     // Resolve batch flags from the captured parent (batch) command.
     const raw = batchCmd.opts();
     const listFromParent = !!raw.list;
@@ -2636,6 +2869,7 @@ const buildDefaultCmdAction = (cli, batchCmd, opts) => async (commandParts, _sub
         if (typeof commandOpt === 'string') {
             await execShellCommandBatch({
                 command: resolveCommand(scripts, commandOpt),
+                dotenvEnv,
                 globs,
                 ignoreErrors,
                 list: false,
@@ -2647,6 +2881,7 @@ const buildDefaultCmdAction = (cli, batchCmd, opts) => async (commandParts, _sub
             return;
         }
         if (raw.list || localList) {
+            const shellBag = ((batchCmd.parent ?? undefined)?.getDotenvCliOptions ?? {});
             await execShellCommandBatch({
                 globs,
                 ignoreErrors,
@@ -2654,7 +2889,7 @@ const buildDefaultCmdAction = (cli, batchCmd, opts) => async (commandParts, _sub
                 logger: loggerLocal,
                 ...(pkgCwd ? { pkgCwd } : {}),
                 rootPath,
-                shell: (shell ?? false),
+                shell: (shell ?? shellBag.shell ?? false),
             });
             return;
         }
@@ -2721,6 +2956,7 @@ const buildDefaultCmdAction = (cli, batchCmd, opts) => async (commandParts, _sub
     }
     await execShellCommandBatch({
         command: commandArg,
+        dotenvEnv,
         ...(envBag ? { getDotenvCliOptions: envBag } : {}),
         globs,
         ignoreErrors,
@@ -2739,6 +2975,7 @@ const buildParentAction = (cli, opts) => async (commandParts, thisCommand) => {
     const logger = opts.logger ?? console;
     // Ensure context exists (host preSubcommand on root creates if missing).
     const ctx = cli.getCtx();
+    const dotenvEnv = (ctx?.dotenv ?? {});
     const cfgRaw = (ctx?.pluginConfigs?.['batch'] ?? {});
     const cfg = (cfgRaw || {});
     const raw = thisCommand.opts();
@@ -2761,6 +2998,7 @@ const buildParentAction = (cli, opts) => async (commandParts, thisCommand) => {
         const commandArg = resolved;
         await execShellCommandBatch({
             command: commandArg,
+            dotenvEnv,
             globs,
             ignoreErrors,
             list: false,
@@ -2798,6 +3036,7 @@ const buildParentAction = (cli, opts) => async (commandParts, thisCommand) => {
         const shellOpt = opts.shell ?? cfg.shell ?? mergedBag.shell;
         await execShellCommandBatch({
             command: resolveCommand(scriptsOpt, commandOpt),
+            dotenvEnv,
             globs,
             ignoreErrors,
             list,
@@ -2841,7 +3080,8 @@ const BatchConfigSchema = z.object({
 /**
  * Batch plugin for the GetDotenv CLI host.
  *
- * Mirrors the legacy batch subcommand behavior without altering the shipped CLI. * Options:
+ * Mirrors the legacy batch subcommand behavior without altering the shipped CLI.
+ * Options:
  * - scripts/shell: used to resolve command and shell behavior per script or global default.
  * - logger: defaults to console.
  */
@@ -2853,12 +3093,32 @@ const batchPlugin = (opts = {}) => definePlugin({
     setup(cli) {
         const ns = cli.ns('batch');
         const batchCmd = ns; // capture the parent "batch" command for default-subcommand context
+        const host = cli;
+        const pluginId = 'batch';
+        const GROUP = `plugin:${pluginId}`;
         ns.description('Batch command execution across multiple working directories.')
             .enablePositionalOptions()
             .passThroughOptions()
-            .option('-p, --pkg-cwd', 'use nearest package directory as current working directory')
-            .option('-r, --root-path <string>', 'path to batch root directory from current working directory', './')
-            .option('-g, --globs <string>', 'space-delimited globs from root path', '*')
+            // Dynamic help: show effective defaults from the merged/interpolated plugin config slice.
+            .addOption((() => {
+            const opt = host.createDynamicOption('-p, --pkg-cwd', (cfg) => {
+                const slice = cfg.plugins.batch ?? {};
+                const on = !!slice.pkgCwd;
+                return `use nearest package directory as current working directory${on ? ' (default)' : ''}`;
+            });
+            opt.__group = GROUP;
+            return opt;
+        })())
+            .addOption((() => {
+            const opt = host.createDynamicOption('-r, --root-path <string>', (cfg) => `path to batch root directory from current working directory (default: ${JSON.stringify(cfg.plugins.batch?.rootPath || './')})`);
+            opt.__group = GROUP;
+            return opt;
+        })())
+            .addOption((() => {
+            const opt = host.createDynamicOption('-g, --globs <string>', (cfg) => `space-delimited globs from root path (default: ${JSON.stringify(cfg.plugins.batch?.globs || '*')})`);
+            opt.__group = GROUP;
+            return opt;
+        })())
             .option('-c, --command <string>', 'command executed according to the base shell resolution')
             .option('-l, --list', 'list working directories without executing command')
             .option('-e, --ignore-errors', 'ignore errors and continue with next path')
@@ -3168,10 +3428,10 @@ const cmdPlugin = (options = {}) => definePlugin({
             return name.replace(/-([a-z])/g, (_m, c) => c.toUpperCase());
         };
         const aliasKey = aliasSpec ? deriveKey(aliasSpec.flags) : undefined;
-        const cmd = new Command()
-            .name('cmd')
-            .description('Batch execute command according to the --shell option, conflicts with --command option (default subcommand)')
-            .configureHelp({ showGlobalOptions: true })
+        // Create as a GetDotenvCli child so helpInformation includes a trailing blank line.
+        const cmd = cli
+            .createCommand('cmd')
+            .description('Execute command according to the --shell option, conflicts with --command option (default subcommand)')
             .enablePositionalOptions()
             .passThroughOptions()
             .argument('[command...]')
@@ -3363,7 +3623,7 @@ const demoPlugin = () => definePlugin({
             const dotenv = (ctx?.dotenv ?? {});
             // Inherit stdio for an interactive demo. Use --capture for CI.
             await runCommand(['node', '-e', code], false, {
-                env: { ...process.env, ...dotenv },
+                env: buildSpawnEnv(process.env, dotenv),
                 stdio: 'inherit',
             });
         });
@@ -3400,20 +3660,23 @@ const demoPlugin = () => definePlugin({
             const ctx = cli.getCtx();
             const dotenv = (ctx?.dotenv ?? {});
             await runCommand(resolved, shell, {
-                env: { ...process.env, ...dotenv },
+                env: buildSpawnEnv(process.env, dotenv),
                 stdio: 'inherit',
             });
         });
     },
     /**
      * Optional: afterResolve can initialize per-plugin state using ctx.dotenv.
-     * For the demo we just log once to hint where such logic would live.
+     * For the demo we emit a single breadcrumb only when GETDOTENV_DEBUG is set,
+     * keeping default runs (tests/CI/smoke) quiet.
      */
     afterResolve(_cli, ctx) {
-        const keys = Object.keys(ctx.dotenv);
-        if (keys.length > 0) {
-            // Keep noise low; a single-line breadcrumb is sufficient for the demo.
-            console.error('[demo] afterResolve: dotenv keys loaded:', keys.length);
+        if (process.env.GETDOTENV_DEBUG) {
+            const keys = Object.keys(ctx.dotenv);
+            if (keys.length > 0) {
+                // Keep noise low; a single-line breadcrumb is sufficient for the demo.
+                console.error('[demo] afterResolve: dotenv keys loaded:', keys.length);
+            }
         }
     },
 });
@@ -3671,402 +3934,40 @@ const initPlugin = (opts = {}) => definePlugin({
     },
 });
 
-const cmdCommand$1 = new Command()
-    .name('cmd')
-    .description('execute command, conflicts with --command option (default subcommand)')
-    .enablePositionalOptions()
-    .passThroughOptions()
-    .argument('[command...]')
-    .action(async (commandParts, _options, thisCommand) => {
-    if (!thisCommand.parent)
-        throw new Error(`unable to resolve parent command`);
-    if (!thisCommand.parent.parent)
-        throw new Error(`unable to resolve root command`);
-    const { getDotenvCliOptions: { logger = console, ...getDotenvCliOptions }, } = thisCommand.parent.parent;
-    const raw = thisCommand.parent.opts();
-    const ignoreErrors = !!raw.ignoreErrors;
-    const globs = typeof raw.globs === 'string' ? raw.globs : '*';
-    const list = !!raw.list;
-    const pkgCwd = !!raw.pkgCwd;
-    const rootPath = typeof raw.rootPath === 'string' ? raw.rootPath : './';
-    // Execute command.
-    const args = Array.isArray(commandParts) ? commandParts : [];
-    // When no positional tokens are provided (e.g., option form `-c/--command`),
-    // the preSubcommand hook handles execution. Avoid a duplicate call here.
-    if (args.length === 0)
-        return;
-    const command = args.map(String).join(' ');
-    await execShellCommandBatch({
-        command: resolveCommand(getDotenvCliOptions.scripts, command),
-        getDotenvCliOptions,
-        globs,
-        ignoreErrors,
-        list,
-        logger,
-        pkgCwd,
-        rootPath,
-        // execa expects string | boolean | URL for `shell`. We normalize earlier;
-        // scripts[name].shell overrides take precedence and may be boolean or string.
-        shell: resolveShell(getDotenvCliOptions.scripts, command, getDotenvCliOptions.shell),
-    });
-});
-
-const batchCommand = new Command()
-    .name('batch')
-    .description('Batch command execution across multiple working directories.')
-    .enablePositionalOptions()
-    .passThroughOptions()
-    .option('-p, --pkg-cwd', 'use nearest package directory as current working directory')
-    .option('-r, --root-path <string>', 'path to batch root directory from current working directory', './')
-    .option('-g, --globs <string>', 'space-delimited globs from root path', '*')
-    .option('-c, --command <string>', 'command executed according to the base --shell option, conflicts with cmd subcommand (dotenv-expanded)', dotenvExpandFromProcessEnv)
-    .option('-l, --list', 'list working directories without executing command')
-    .option('-e, --ignore-errors', 'ignore errors and continue with next path')
-    .hook('preSubcommand', async (thisCommand) => {
-    if (!thisCommand.parent)
-        throw new Error(`unable to resolve root command`);
-    const { getDotenvCliOptions: { logger = console, ...getDotenvCliOptions }, } = thisCommand.parent;
-    const raw = thisCommand.opts();
-    const commandOpt = typeof raw.command === 'string' ? raw.command : undefined;
-    const ignoreErrors = !!raw.ignoreErrors;
-    const globs = typeof raw.globs === 'string' ? raw.globs : '*';
-    const list = !!raw.list;
-    const pkgCwd = !!raw.pkgCwd;
-    const rootPath = typeof raw.rootPath === 'string' ? raw.rootPath : './';
-    const argCount = thisCommand.args.length;
-    if (typeof commandOpt === 'string' && argCount > 0) {
-        logger.error(`--command option conflicts with cmd subcommand.`);
-        process.exit(0);
-    }
-    // Execute command.
-    if (typeof commandOpt === 'string')
-        await execShellCommandBatch({
-            command: resolveCommand(getDotenvCliOptions.scripts, commandOpt),
-            getDotenvCliOptions,
-            globs,
-            ignoreErrors,
-            list,
-            logger,
-            pkgCwd,
-            rootPath,
-            // execa expects string | boolean | URL for `shell`. We normalize earlier;
-            // scripts[name].shell overrides take precedence and may be boolean or string.
-            shell: resolveShell(getDotenvCliOptions.scripts, commandOpt, getDotenvCliOptions.shell),
-        });
-})
-    .addCommand(cmdCommand$1, { isDefault: true });
-
-const cmdCommand = new Command()
-    .name('cmd')
-    .description('Execute command according to the --shell option, conflicts with --command option (default subcommand)')
-    .configureHelp({ showGlobalOptions: true })
-    .enablePositionalOptions()
-    .passThroughOptions()
-    .argument('[command...]')
-    .action(async (commandParts, _options, thisCommand) => {
-    const args = Array.isArray(commandParts) ? commandParts : [];
-    if (args.length === 0)
-        return;
-    if (!thisCommand.parent)
-        throw new Error('parent command not found');
-    const { getDotenvCliOptions: { logger = console, ...getDotenvCliOptions }, } = thisCommand.parent;
-    const command = args.map(String).join(' ');
-    const cmd = resolveCommand(getDotenvCliOptions.scripts, command);
-    if (getDotenvCliOptions.debug)
-        logger.log('\n*** command ***\n', `'${cmd}'`);
-    await execaCommand(cmd, {
-        env: {
-            ...process.env,
-            getDotenvCliOptions: JSON.stringify(getDotenvCliOptions),
-        },
-        // execa expects string | boolean | URL; we normalize in generator
-        // and allow script-level overrides.
-        shell: resolveShell(getDotenvCliOptions.scripts, command, getDotenvCliOptions.shell),
-        stdio: 'inherit',
-    });
-});
-
-/**
- * Create the root Commander command with legacy root options (via cliCore)
- * and built-in subcommands. Pure builder: no side-effects; the caller attaches
- * lifecycle hooks separately.
- */
-const createRootCommand = (opts) => {
-    const program = new Command().name(opts.alias).description(opts.description);
-    // Attach legacy root flags using shared cliCore builder to keep parity.
-    attachRootOptions(program, opts, {
-        includeCommandOption: true,
-    });
-    // Subcommands
-    program.addCommand(batchCommand).addCommand(cmdCommand, { isDefault: true });
-    return program;
-};
-
-/**
- * Resolve `GetDotenvCliGenerateOptions` from `import.meta.url` and custom options.
- */
-const resolveGetDotenvCliGenerateOptions = async ({ importMetaUrl, ...customOptions }) => {
-    const baseOptions = {
-        ...baseGetDotenvCliOptions,
-        alias: 'getdotenv',
-        description: 'Base CLI.',
-    };
-    const globalPkgDir = importMetaUrl
-        ? await packageDirectory({
-            cwd: fileURLToPath(importMetaUrl),
-        })
-        : undefined;
-    const globalOptionsPath = globalPkgDir
-        ? join(globalPkgDir, getDotenvOptionsFilename)
-        : undefined;
-    const globalOptions = (globalOptionsPath && (await fs.exists(globalOptionsPath))
-        ? JSON.parse((await fs.readFile(globalOptionsPath)).toString())
-        : {});
-    const localPkgDir = await packageDirectory();
-    const localOptionsPath = localPkgDir
-        ? join(localPkgDir, getDotenvOptionsFilename)
-        : undefined;
-    const localOptions = (localOptionsPath &&
-        localOptionsPath !== globalOptionsPath &&
-        (await fs.exists(localOptionsPath))
-        ? JSON.parse((await fs.readFile(localOptionsPath)).toString())
-        : {});
-    // Merge order: base < global < local < custom
-    const merged = defaultsDeep(baseOptions, globalOptions, localOptions, customOptions);
-    return merged;
-};
-
-/**
- * Resolve dotenv values using the config-loader/overlay path (always-on in
- * host/generator flows; no-op when no config files are present).
- *
- * Order:
- * 1) Compute base from files only (exclude dynamic; ignore programmatic vars).
- * 2) Discover packaged + project config sources and overlay onto base.
- * 3) Apply dynamics in order:
- *    programmatic dynamic \> config dynamic (packaged → project public → project local)
- *    \> file dynamicPath.
- * 4) Phase C interpolation of remaining string options (e.g., outputPath).
- * 5) Optionally write outputPath, log, and merge into process.env.
- */
-const resolveDotenvWithConfigLoader = async (validated) => {
-    // 1) Base from files, no dynamic, no programmatic vars
-    const base = await getDotenv({
-        ...validated,
-        // Build a pure base without side effects or logging.
-        excludeDynamic: true,
-        vars: {},
-        log: false,
-        loadProcess: false,
-        outputPath: undefined,
-    });
-    // 2) Discover config sources (packaged via this module's import.meta.url)
-    const sources = await resolveGetDotenvConfigSources(import.meta.url);
-    const dotenv = overlayEnv({
-        base,
-        env: validated.env ?? validated.defaultEnv,
-        configs: sources,
-        ...(validated.vars ? { programmaticVars: validated.vars } : {}),
-    });
-    // Helper to apply a dynamic map progressively.
-    const applyDynamic = (target, dynamic, env) => {
-        if (!dynamic)
-            return;
-        for (const key of Object.keys(dynamic)) {
-            const value = typeof dynamic[key] === 'function'
-                ? dynamic[key](target, env)
-                : dynamic[key];
-            Object.assign(target, { [key]: value });
-        }
-    };
-    // 3) Apply dynamics in order
-    applyDynamic(dotenv, validated.dynamic, validated.env ?? validated.defaultEnv);
-    applyDynamic(dotenv, (sources.packaged?.dynamic ?? undefined), validated.env ?? validated.defaultEnv);
-    applyDynamic(dotenv, (sources.project?.public?.dynamic ?? undefined), validated.env ?? validated.defaultEnv);
-    applyDynamic(dotenv, (sources.project?.local?.dynamic ?? undefined), validated.env ?? validated.defaultEnv);
-    // file dynamicPath (lowest)
-    if (validated.dynamicPath) {
-        const absDynamicPath = path.resolve(validated.dynamicPath);
-        try {
-            const dyn = await loadModuleDefault(absDynamicPath, 'getdotenv-dynamic-host');
-            applyDynamic(dotenv, dyn, validated.env ?? validated.defaultEnv);
-        }
-        catch {
-            throw new Error(`Unable to load dynamic from ${validated.dynamicPath}`);
-        }
-    }
-    // 4) Phase C: interpolate remaining string options (exclude bootstrap set).
-    // For now, interpolate outputPath only; bootstrap keys are excluded by design.
-    const envRef = { ...process.env, ...dotenv };
-    const outputPathInterpolated = typeof validated.outputPath === 'string'
-        ? interpolateDeep(validated.outputPath, envRef)
-        : undefined;
-    // 5) Output/log/process merge (use interpolated outputPath if present)
-    if (outputPathInterpolated) {
-        await fs.writeFile(outputPathInterpolated, Object.keys(dotenv).reduce((contents, key) => {
-            const value = dotenv[key] ?? '';
-            return `${contents}${key}=${value.includes('\n') ? `"${value}"` : value}\n`;
-        }, ''), { encoding: 'utf-8' });
-    }
-    const logger = validated.logger ?? console;
-    if (validated.log) {
-        const redactFlag = validated.redact ?? false;
-        const redactPatterns = validated.redactPatterns;
-        const redOpts = {};
-        if (redactFlag)
-            redOpts.redact = true;
-        if (redactFlag && Array.isArray(redactPatterns))
-            redOpts.redactPatterns = redactPatterns;
-        const bag = redactFlag ? redactObject(dotenv, redOpts) : { ...dotenv };
-        logger.log(bag);
-        // Entropy warnings: once per key per run (presentation only)
-        const warnEntropyVal = validated.warnEntropy ?? true;
-        const entropyThresholdVal = validated.entropyThreshold;
-        const entropyMinLengthVal = validated.entropyMinLength;
-        const entropyWhitelistVal = validated.entropyWhitelist;
-        const entOpts = {};
-        // include keys only when defined to satisfy exactOptionalPropertyTypes
-        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(dotenv)) {
-            maybeWarnEntropy(k, v, v !== undefined ? 'dotenv' : 'unset', entOpts, (line) => {
-                logger.log(line);
-            });
-        }
-    }
-    if (validated.loadProcess)
-        Object.assign(process.env, dotenv);
-    return dotenv;
-};
-
-/**
- * Omit a "logger" key from an options object in a typed manner.
- */
-const omitLogger = (obj) => {
-    const { logger: _omitted, ...rest } = obj;
-    return rest;
-};
-/**
- * Build the Commander preSubcommand hook using the provided context.
- * * Responsibilities:
- * - Merge parent CLI options with current invocation (parent \< current). * - Resolve tri-state flags, including `--exclude-all` overrides.
- * - Normalize the shell setting to a concrete value (string | boolean).
- * - Persist merged options on the command instance and pass to subcommands.
- * - Execute {@link getDotenv} and optional post-hook.
- * - Either forward to the default `cmd` subcommand or execute `--command`.
- *
- * @param context - See {@link PreSubHookContext}.
- * @returns An async hook suitable for Commander’s `preSubcommand`.
- *
- * @example `program.hook('preSubcommand', makePreSubcommandHook(ctx));`
- */
-const makePreSubcommandHook = ({ logger, preHook, postHook, defaults, }) => {
-    return async (thisCommand) => {
-        // Get raw CLI options from commander.
-        const rawCliOptions = thisCommand.opts();
-        const { merged: mergedGetDotenvCliOptions, command: commandOpt } = resolveCliOptions(rawCliOptions, defaults, process.env.getDotenvCliOptions);
-        // Optional debug logging retained via mergedGetDotenvCliOptions.debug if desired.    // Execute pre-hook.
-        if (preHook) {
-            await preHook(mergedGetDotenvCliOptions);
-            if (mergedGetDotenvCliOptions.debug)
-                logger.debug('\n*** GetDotenvCliOptions after pre-hook ***\n', mergedGetDotenvCliOptions);
-        }
-        // Persist GetDotenvCliOptions in command for subcommand access.
-        thisCommand.getDotenvCliOptions =
-            mergedGetDotenvCliOptions;
-        // Execute getdotenv via always-on config loader/overlay path.
-        const serviceOptions = getDotenvCliOptions2Options(mergedGetDotenvCliOptions);
-        const dotenv = await resolveDotenvWithConfigLoader(serviceOptions);
-        // Global validation against config (warn by default; --strict fails).
-        try {
-            const sources = await resolveGetDotenvConfigSources(import.meta.url);
-            const issues = validateEnvAgainstSources(dotenv, sources);
-            if (Array.isArray(issues) && issues.length > 0) {
-                issues.forEach((m) => {
-                    logger.error(m);
-                });
-                if (mergedGetDotenvCliOptions.strict) {
-                    process.exit(1);
-                }
-            }
-        }
-        catch {
-            // Tolerate validator failures in non-strict mode
-        }
-        // Execute post-hook.
-        if (postHook)
-            await postHook(dotenv); // Execute command.
-        const args = thisCommand.args ?? [];
-        const isCommand = typeof commandOpt === 'string' && commandOpt.length > 0;
-        if (isCommand && args.length > 0) {
-            const lr = logger;
-            (lr.error ?? lr.log)(`--command option conflicts with cmd subcommand.`);
-            process.exit(0);
-        }
-        if (typeof commandOpt === 'string' && commandOpt.length > 0) {
-            const cmd = resolveCommand(mergedGetDotenvCliOptions.scripts, commandOpt);
-            if (mergedGetDotenvCliOptions.debug)
-                logger.debug('\n*** command ***\n', cmd);
-            // Build a logger-free bag for env round-trip.
-            const envSafe = omitLogger(mergedGetDotenvCliOptions);
-            await execaCommand(cmd, {
-                env: { ...process.env, getDotenvCliOptions: JSON.stringify(envSafe) },
-                shell: resolveShell(mergedGetDotenvCliOptions.scripts, commandOpt, mergedGetDotenvCliOptions.shell),
-                stdio: 'inherit',
-            });
-        }
-    };
-};
-
-/**
- * Generate a Commander CLI Command for get-dotenv.
- * Orchestration only: delegates building and lifecycle hooks.
- */
-const generateGetDotenvCli = async (customOptions) => {
-    const options = await resolveGetDotenvCliGenerateOptions(customOptions);
-    const program = createRootCommand(options);
-    const defaults = {};
-    if (options.debug !== undefined)
-        defaults.debug = options.debug;
-    if (options.excludeDynamic !== undefined)
-        defaults.excludeDynamic = options.excludeDynamic;
-    if (options.excludeEnv !== undefined)
-        defaults.excludeEnv = options.excludeEnv;
-    if (options.excludeGlobal !== undefined)
-        defaults.excludeGlobal = options.excludeGlobal;
-    if (options.excludePrivate !== undefined)
-        defaults.excludePrivate = options.excludePrivate;
-    if (options.excludePublic !== undefined)
-        defaults.excludePublic = options.excludePublic;
-    if (options.loadProcess !== undefined)
-        defaults.loadProcess = options.loadProcess;
-    if (options.log !== undefined)
-        defaults.log = options.log;
-    if (options.scripts !== undefined)
-        defaults.scripts = options.scripts;
-    if (options.shell !== undefined)
-        defaults.shell = options.shell;
-    const ctx = {
-        logger: options.logger,
-        defaults,
-        ...(options.preHook ? { preHook: options.preHook } : {}),
-        ...(options.postHook ? { postHook: options.postHook } : {}),
-    };
-    program.hook('preSubcommand', makePreSubcommandHook(ctx));
-    return program;
-};
-
 function createCli(opts = {}) {
     const alias = typeof opts.alias === 'string' && opts.alias.length > 0
         ? opts.alias
         : 'getdotenv';
     const program = new GetDotenvCli(alias);
+    // Normalize Commander output so help prints always end with a blank line.
+    // This keeps E2E assertions (CRLF and >=2 trailing newlines) portable across
+    // runtimes and capture modes without altering Commander internals.
+    const outputCfg = {
+        writeOut(str) {
+            const txt = typeof str === 'string' ? str : '';
+            const hasTwo = /(?:\r?\n){2,}$/.test(txt);
+            const hasOne = /\r?\n$/.test(txt);
+            const out = hasTwo ? txt : hasOne ? txt + '\n' : txt + '\n\n';
+            try {
+                process.stdout.write(out);
+            }
+            catch {
+                /* ignore */
+            }
+        },
+        writeErr(str) {
+            process.stderr.write(str);
+        },
+    };
+    // Apply to root and recursively to subcommands so all help paths are normalized.
+    program.configureOutput(outputCfg);
+    const applyOutputRecursively = (cmd) => {
+        cmd.configureOutput(outputCfg);
+        const kids = cmd.commands ?? [];
+        for (const child of kids)
+            applyOutputRecursively(child);
+    };
+    applyOutputRecursively(program);
     // Install base root flags and included plugins; resolve context once per run.
     program
         .attachRootOptions({ loadProcess: false })
@@ -4082,19 +3983,72 @@ function createCli(opts = {}) {
     if (underTests) {
         program.exitOverride((err) => {
             const code = err?.code;
-            if (code === 'commander.helpDisplayed' || code === 'commander.version')
+            // Commander printed help already; ensure a trailing blank line for tests/CI capture.
+            if (code === 'commander.helpDisplayed') {
+                try {
+                    process.stdout.write('\n');
+                }
+                catch {
+                    /* ignore */
+                }
+                return;
+            }
+            if (code === 'commander.version') {
                 return;
+            }
             throw err;
         });
     }
     return {
         async run(argv) {
-            // Always short-circuit help to avoid Commander-triggered process.exit
-            // across environments (CJS/ESM) and to return immediately under dynamic
-            // ESM without performing extra IO. Prints help and returns.
-            if (argv.some((a) => a === '-h' || a === '--help')) {
-                program.outputHelp();
-                return;
+            // Help handling:
+            // - Short-circuit ONLY for true top-level -h/--help (no subcommand before flag).
+            // - If a subcommand token appears before -h/--help, defer to Commander
+            //   to render that subcommand's help.
+            const helpIdx = argv.findIndex((a) => a === '-h' || a === '--help');
+            if (helpIdx >= 0) {
+                // Build a set of known subcommand names/aliases on the root.
+                const subs = new Set();
+                const cmds = program.commands ?? [];
+                for (const c of cmds) {
+                    subs.add(c.name());
+                    for (const a of c.aliases())
+                        subs.add(a);
+                }
+                const hasSubBeforeHelp = argv
+                    .slice(0, helpIdx)
+                    .some((tok) => subs.has(tok));
+                if (!hasSubBeforeHelp) {
+                    await program.brand({
+                        name: alias,
+                        importMetaUrl: import.meta.url,
+                        description: 'Base CLI.',
+                        ...(typeof opts.branding === 'string' && opts.branding.length > 0
+                            ? { helpHeader: opts.branding }
+                            : {}),
+                    });
+                    // Resolve context once without side effects for help rendering.
+                    const ctx = await program.resolveAndLoad({
+                        loadProcess: false,
+                        log: false,
+                    }, { runAfterResolve: false });
+                    program.evaluateDynamicOptions({
+                        ...ctx.optionsResolved,
+                        plugins: ctx.pluginConfigs ?? {},
+                    });
+                    // Suppress output only during unit tests; allow E2E to capture.
+                    const piping = process.env.GETDOTENV_STDIO === 'pipe' ||
+                        process.env.GETDOTENV_STDOUT === 'pipe';
+                    if (underTests && !piping) {
+                        void program.helpInformation();
+                    }
+                    else {
+                        program.outputHelp();
+                    }
+                    return;
+                }
+                // Subcommand token exists before -h: fall through to normal parsing,
+                // letting Commander print that subcommand's help.
             }
             await program.brand({
                 name: alias,
@@ -4109,4 +4063,4 @@ function createCli(opts = {}) {
     };
 }
 
-export { buildSpawnEnv, createCli, defineDynamic, dotenvExpand, dotenvExpandAll, dotenvExpandFromProcessEnv, generateGetDotenvCli, getDotenv, getDotenvCliOptions2Options, interpolateDeep };
+export { buildSpawnEnv, createCli, defineDynamic, dotenvExpand, dotenvExpandAll, dotenvExpandFromProcessEnv, getDotenv, getDotenvCliOptions2Options, interpolateDeep };