@karmaniverous/get-dotenv 5.0.0 → 5.2.0

package/dist/getdotenv.cli.mjs

@@ -2,9 +2,9 @@
 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 { nanoid } from 'nanoid';
 import { parse } from 'dotenv';
@@ -19,6 +19,11 @@ const baseRootOptionDefaults = {
     dotenvToken: '.env',
     loadProcess: true,
     logger: console,
+    // Diagnostics defaults
+    warnEntropy: true,
+    entropyThreshold: 3.8,
+    entropyMinLength: 16,
+    entropyWhitelist: ['^GIT_', '^npm_', '^CI$', 'SHLVL'],
     paths: './',
     pathsDelimiter: ' ',
     privateToken: 'local',
@@ -39,7 +44,7 @@ const baseRootOptionDefaults = {
 const baseGetDotenvCliOptions = baseRootOptionDefaults;
 
 /** @internal */
-const isPlainObject = (value) => value !== null &&
+const isPlainObject$1 = (value) => value !== null &&
     typeof value === 'object' &&
     Object.getPrototypeOf(value) === Object.prototype;
 const mergeInto = (target, source) => {
@@ -47,10 +52,10 @@ const mergeInto = (target, source) => {
         if (sVal === undefined)
             continue; // do not overwrite with undefined
         const tVal = target[key];
-        if (isPlainObject(tVal) && isPlainObject(sVal)) {
+        if (isPlainObject$1(tVal) && isPlainObject$1(sVal)) {
             target[key] = mergeInto({ ...tVal }, sVal);
         }
-        else if (isPlainObject(sVal)) {
+        else if (isPlainObject$1(sVal)) {
             target[key] = mergeInto({}, sVal);
         }
         else {
@@ -210,11 +215,12 @@ const getDotenvOptionsSchemaRaw = z.object({
 const getDotenvOptionsSchemaResolved = getDotenvOptionsSchemaRaw;
 
 /**
- * Zod schemas for configuration files discovered by the new loader. *
+ * Zod schemas for configuration files discovered by the new loader.
+ *
  * Notes:
  * - RAW: all fields optional; shapes are stringly-friendly (paths may be string[] or string).
  * - RESOLVED: normalized shapes (paths always string[]).
- * - For this step (JSON/YAML only), any defined `dynamic` will be rejected by the loader.
+ * - For JSON/YAML configs, the loader rejects "dynamic" and "schema" (JS/TS-only).
  */
 // String-only env value map
 const stringMap = z.record(z.string(), z.string());
@@ -229,6 +235,8 @@ const getDotenvConfigSchemaRaw = z.object({
     log: z.boolean().optional(),
     shell: z.union([z.string(), z.boolean()]).optional(),
     scripts: z.record(z.string(), z.unknown()).optional(), // Scripts validation left wide; generator validates elsewhere
+    requiredKeys: z.array(z.string()).optional(),
+    schema: z.unknown().optional(), // JS/TS-only; loader rejects in JSON/YAML
     vars: stringMap.optional(), // public, global
     envVars: envStringMap.optional(), // public, per-env
     // Dynamic in config (JS/TS only). JSON/YAML loader will reject if set.
@@ -411,9 +419,11 @@ const loadConfigFile = async (filePath) => {
             .join('\n');
         throw new Error(`Invalid config ${filePath}:\n${msgs}`);
     }
-    // Disallow dynamic in JSON/YAML; allow in JS/TS
-    if (!isJsOrTs(filePath) && parsed.data.dynamic !== undefined) {
-        throw new Error(`Config ${filePath} specifies "dynamic"; JSON/YAML configs cannot include dynamic in this step. Use JS/TS config.`);
+    // Disallow dynamic and schema in JSON/YAML; allow both in JS/TS.
+    if (!isJsOrTs(filePath) &&
+        (parsed.data.dynamic !== undefined || parsed.data.schema !== undefined)) {
+        throw new Error(`Config ${filePath} specifies unsupported keys for JSON/YAML. ` +
+            `Use JS/TS config for "dynamic" or "schema".`);
     }
     return getDotenvConfigSchemaResolved.parse(parsed.data);
 };
@@ -617,6 +627,99 @@ const overlayEnv = ({ base, env, configs, programmaticVars, }) => {
     return current;
 };
 
+/** src/diagnostics/entropy.ts
+ * Entropy diagnostics (presentation-only).
+ * - Gated by min length and printable ASCII.
+ * - Warn once per key per run when bits/char \>= threshold.
+ * - Supports whitelist patterns to suppress known-noise keys.
+ */
+const warned = new Set();
+const isPrintableAscii = (s) => /^[\x20-\x7E]+$/.test(s);
+const compile$1 = (patterns) => (patterns ?? []).map((p) => new RegExp(p, 'i'));
+const whitelisted = (key, regs) => regs.some((re) => re.test(key));
+const shannonBitsPerChar = (s) => {
+    const freq = new Map();
+    for (const ch of s)
+        freq.set(ch, (freq.get(ch) ?? 0) + 1);
+    const n = s.length;
+    let h = 0;
+    for (const c of freq.values()) {
+        const p = c / n;
+        h -= p * Math.log2(p);
+    }
+    return h;
+};
+/**
+ * Maybe emit a one-line entropy warning for a key.
+ * Caller supplies an `emit(line)` function; the helper ensures once-per-key.
+ */
+const maybeWarnEntropy = (key, value, origin, opts, emit) => {
+    if (!opts || opts.warnEntropy === false)
+        return;
+    if (warned.has(key))
+        return;
+    const v = value ?? '';
+    const minLen = Math.max(0, opts.entropyMinLength ?? 16);
+    const threshold = opts.entropyThreshold ?? 3.8;
+    if (v.length < minLen)
+        return;
+    if (!isPrintableAscii(v))
+        return;
+    const wl = compile$1(opts.entropyWhitelist);
+    if (whitelisted(key, wl))
+        return;
+    const bpc = shannonBitsPerChar(v);
+    if (bpc >= threshold) {
+        warned.add(key);
+        emit(`[entropy] key=${key} score=${bpc.toFixed(2)} len=${String(v.length)} origin=${origin}`);
+    }
+};
+
+const DEFAULT_PATTERNS = [
+    '\\bsecret\\b',
+    '\\btoken\\b',
+    '\\bpass(word)?\\b',
+    '\\bapi[_-]?key\\b',
+    '\\bkey\\b',
+];
+const compile = (patterns) => (patterns && patterns.length > 0 ? patterns : DEFAULT_PATTERNS).map((p) => new RegExp(p, 'i'));
+const shouldRedactKey = (key, regs) => regs.some((re) => re.test(key));
+const MASK = '[redacted]';
+/**
+ * Produce a shallow redacted copy of an env-like object for display.
+ */
+const redactObject = (obj, opts) => {
+    if (!opts?.redact)
+        return { ...obj };
+    const regs = compile(opts.redactPatterns);
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+        out[k] = v && shouldRedactKey(k, regs) ? MASK : v;
+    }
+    return out;
+};
+/**
+ * Utility to redact three related displayed values (parent/dotenv/final)
+ * consistently for trace lines.
+ */
+const redactTriple = (key, triple, opts) => {
+    if (!opts?.redact)
+        return triple;
+    const regs = compile(opts.redactPatterns);
+    const maskIf = (v) => (v && shouldRedactKey(key, regs) ? MASK : v);
+    const out = {};
+    const p = maskIf(triple.parent);
+    const d = maskIf(triple.dotenv);
+    const f = maskIf(triple.final);
+    if (p !== undefined)
+        out.parent = p;
+    if (d !== undefined)
+        out.dotenv = d;
+    if (f !== undefined)
+        out.final = f;
+    return out;
+};
+
 /**
  * Asynchronously read a dotenv file & parse it into an object.
  *
@@ -866,14 +969,103 @@ const getDotenv = async (options = {}) => {
         resultDotenv = dotenvForOutput;
     }
     // Log result.
-    if (log)
-        logger.log(resultDotenv);
+    if (log) {
+        const redactFlag = options.redact ?? false;
+        const redactPatterns = options.redactPatterns ?? undefined;
+        const redOpts = {};
+        if (redactFlag)
+            redOpts.redact = true;
+        if (redactFlag && Array.isArray(redactPatterns))
+            redOpts.redactPatterns = redactPatterns;
+        const bag = redactFlag
+            ? redactObject(resultDotenv, redOpts)
+            : { ...resultDotenv };
+        logger.log(bag);
+        // Entropy warnings: once-per-key-per-run (presentation only)
+        const warnEntropyVal = options.warnEntropy ?? true;
+        const entropyThresholdVal = options
+            .entropyThreshold;
+        const entropyMinLengthVal = options
+            .entropyMinLength;
+        const entropyWhitelistVal = options
+            .entropyWhitelist;
+        const entOpts = {};
+        if (typeof warnEntropyVal === 'boolean')
+            entOpts.warnEntropy = warnEntropyVal;
+        if (typeof entropyThresholdVal === 'number')
+            entOpts.entropyThreshold = entropyThresholdVal;
+        if (typeof entropyMinLengthVal === 'number')
+            entOpts.entropyMinLength = entropyMinLengthVal;
+        if (Array.isArray(entropyWhitelistVal))
+            entOpts.entropyWhitelist = entropyWhitelistVal;
+        for (const [k, v] of Object.entries(resultDotenv)) {
+            maybeWarnEntropy(k, v, v !== undefined ? 'dotenv' : 'unset', entOpts, (line) => {
+                logger.log(line);
+            });
+        }
+    }
     // Load process.env.
     if (loadProcess)
         Object.assign(process.env, resultDotenv);
     return resultDotenv;
 };
 
+/**
+ * Deep interpolation utility for string leaves.
+ * - Expands string values using dotenv-style expansion against the provided envRef.
+ * - Preserves non-strings as-is.
+ * - Does not recurse into arrays (arrays are returned unchanged).
+ *
+ * Intended for:
+ * - Phase C option/config interpolation after composing ctx.dotenv.
+ * - Per-plugin config slice interpolation before afterResolve.
+ */
+/** @internal */
+const isPlainObject = (v) => v !== null &&
+    typeof v === 'object' &&
+    !Array.isArray(v) &&
+    Object.getPrototypeOf(v) === Object.prototype;
+/**
+ * Deeply interpolate string leaves against envRef.
+ * Arrays are not recursed into; they are returned unchanged.
+ *
+ * @typeParam T - Shape of the input value.
+ * @param value - Input value (object/array/primitive).
+ * @param envRef - Reference environment for interpolation.
+ * @returns A new value with string leaves interpolated.
+ */
+const interpolateDeep = (value, envRef) => {
+    // Strings: expand and return
+    if (typeof value === 'string') {
+        const out = dotenvExpand(value, envRef);
+        // dotenvExpand returns string | undefined; preserve original on undefined
+        return (out ?? value);
+    }
+    // Arrays: return as-is (no recursion)
+    if (Array.isArray(value)) {
+        return value;
+    }
+    // Plain objects: shallow clone and recurse into values
+    if (isPlainObject(value)) {
+        const src = value;
+        const out = {};
+        for (const [k, v] of Object.entries(src)) {
+            // Recurse for strings/objects; keep arrays as-is; preserve other scalars
+            if (typeof v === 'string')
+                out[k] = dotenvExpand(v, envRef) ?? v;
+            else if (Array.isArray(v))
+                out[k] = v;
+            else if (isPlainObject(v))
+                out[k] = interpolateDeep(v, envRef);
+            else
+                out[k] = v;
+        }
+        return out;
+    }
+    // Other primitives/types: return as-is
+    return value;
+};
+
 /**
  * Compute the dotenv context for the host (uses the config loader/overlay path).
  * - Resolves and validates options strictly (host-only).
@@ -957,19 +1149,32 @@ const computeContext = async (customOptions, plugins, hostMetaUrl) => {
         {};
     const mergedPluginConfigs = defaultsDeep({}, packagedPlugins, publicPlugins, localPlugins);
     for (const p of plugins) {
-        if (!p.id || !p.configSchema)
+        if (!p.id)
             continue;
         const slice = mergedPluginConfigs[p.id];
         if (slice === undefined)
             continue;
-        const parsed = p.configSchema.safeParse(slice);
-        if (!parsed.success) {
-            const msgs = parsed.error.issues
-                .map((i) => `${i.path.join('.')}: ${i.message}`)
-                .join('\n');
-            throw new Error(`Invalid config for plugin '${p.id}':\n${msgs}`);
+        // Per-plugin interpolation just before validation/afterResolve:
+        // precedence: process.env wins over ctx.dotenv for slice defaults.
+        const envRef = {
+            ...dotenv,
+            ...process.env,
+        };
+        const interpolated = interpolateDeep(slice, envRef);
+        // Validate if a schema is provided; otherwise accept interpolated slice as-is.
+        if (p.configSchema) {
+            const parsed = p.configSchema.safeParse(interpolated);
+            if (!parsed.success) {
+                const msgs = parsed.error.issues
+                    .map((i) => `${i.path.join('.')}: ${i.message}`)
+                    .join('\n');
+                throw new Error(`Invalid config for plugin '${p.id}':\n${msgs}`);
+            }
+            mergedPluginConfigs[p.id] = parsed.data;
+        }
+        else {
+            mergedPluginConfigs[p.id] = interpolated;
         }
-        mergedPluginConfigs[p.id] = parsed.data;
     }
     return {
         optionsResolved: validated,
@@ -981,6 +1186,8 @@ const computeContext = async (customOptions, plugins, hostMetaUrl) => {
 
 const HOST_META_URL = import.meta.url;
 const CTX_SYMBOL = Symbol('GetDotenvCli.ctx');
+const OPTS_SYMBOL = Symbol('GetDotenvCli.options');
+const HELP_HEADER_SYMBOL = Symbol('GetDotenvCli.helpHeader');
 /**
  * Plugin-first CLI host for get-dotenv. Extends Commander.Command.
  *
@@ -997,15 +1204,46 @@ class GetDotenvCli extends Command {
     _plugins = [];
     /** One-time installation guard */
     _installed = false;
+    /** Optional header line to prepend in help output */
+    [HELP_HEADER_SYMBOL];
     constructor(alias = 'getdotenv') {
         super(alias);
         // Ensure subcommands that use passThroughOptions can be attached safely.
         // Commander requires parent commands to enable positional options when a
         // child uses passThroughOptions.
         this.enablePositionalOptions();
+        // Configure grouped help: show only base options in default "Options";
+        // append App/Plugin sections after default help.
+        this.configureHelp({
+            visibleOptions: (cmd) => {
+                const all = cmd.options ??
+                    [];
+                const base = all.filter((opt) => {
+                    const group = opt.__group;
+                    return group === 'base';
+                });
+                // Sort: short-aliased options first, then long-only; stable by flags.
+                const hasShort = (opt) => {
+                    const flags = opt.flags ?? '';
+                    // Matches "-x," or starting "-x " before any long
+                    return /(^|\s|,)-[A-Za-z]/.test(flags);
+                };
+                const byFlags = (opt) => opt.flags ?? '';
+                base.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;
+            },
+        });
+        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
+        // mutating process.env. The passOptions hook (when installed) will    // compute the final context using merged CLI options; keeping
         // loadProcess=false here avoids leaking dotenv values into the parent
         // process env before subcommands execute.
         this.hook('preSubcommand', async () => {
@@ -1037,11 +1275,96 @@ class GetDotenvCli extends Command {
     getCtx() {
         return this[CTX_SYMBOL];
     }
+    /**
+     * Retrieve the merged root CLI options bag (if set by passOptions()).
+     * Downstream-safe: no generics required.
+     */
+    getOptions() {
+        return this[OPTS_SYMBOL];
+    }
+    /** Internal: set the merged root options bag for this run. */
+    _setOptionsBag(bag) {
+        this[OPTS_SYMBOL] = bag;
+    }
     /**   * Convenience helper to create a namespaced subcommand.
      */
     ns(name) {
         return this.command(name);
     }
+    /**
+     * Tag options added during the provided callback as 'app' for grouped help.
+     * Allows downstream apps to demarcate their root-level options.
+     */
+    tagAppOptions(fn) {
+        const root = this;
+        const originalAddOption = root.addOption.bind(root);
+        const originalOption = root.option.bind(root);
+        const tagLatest = (cmd, group) => {
+            const optsArr = cmd.options;
+            if (Array.isArray(optsArr) && optsArr.length > 0) {
+                const last = optsArr[optsArr.length - 1];
+                last.__group = group;
+            }
+        };
+        root.addOption = function patchedAdd(opt) {
+            opt.__group = 'app';
+            return originalAddOption(opt);
+        };
+        root.option = function patchedOption(...args) {
+            const ret = originalOption(...args);
+            tagLatest(this, 'app');
+            return ret;
+        };
+        try {
+            return fn(root);
+        }
+        finally {
+            root.addOption = originalAddOption;
+            root.option = originalOption;
+        }
+    }
+    /**
+     * Branding helper: set CLI name/description/version and optional help header.
+     * If version is omitted and importMetaUrl is provided, attempts to read the
+     * nearest package.json version (best-effort; non-fatal on failure).
+     */
+    async brand(args) {
+        const { name, description, version, importMetaUrl, helpHeader } = args;
+        if (typeof name === 'string' && name.length > 0)
+            this.name(name);
+        if (typeof description === 'string')
+            this.description(description);
+        let v = version;
+        if (!v && importMetaUrl) {
+            try {
+                const fromUrl = fileURLToPath(importMetaUrl);
+                const pkgDir = await packageDirectory({ cwd: fromUrl });
+                if (pkgDir) {
+                    const txt = await fs.readFile(`${pkgDir}/package.json`, 'utf-8');
+                    const pkg = JSON.parse(txt);
+                    if (pkg.version)
+                        v = pkg.version;
+                }
+            }
+            catch {
+                // best-effort only
+            }
+        }
+        if (v)
+            this.version(v);
+        // Help header:
+        // - If caller provides helpHeader, use it.
+        // - Otherwise, when a version is known, default to "<name> v<version>".
+        if (typeof helpHeader === 'string') {
+            this[HELP_HEADER_SYMBOL] = helpHeader;
+        }
+        else if (v) {
+            // Use the current command name (possibly overridden by 'name' above).
+            const header = `${this.name()} v${v}`;
+            this[HELP_HEADER_SYMBOL] = header;
+        }
+        return this;
+    }
     /**
      * Register a plugin for installation (parent level).
      * Installation occurs on first resolveAndLoad() (or explicit install()).
@@ -1080,13 +1403,143 @@ class GetDotenvCli extends Command {
         for (const p of this._plugins)
             await run(p);
     }
+    // Render App/Plugin grouped options appended after default help.
+    #renderOptionGroups(cmd) {
+        const all = cmd.options ?? [];
+        const byGroup = new Map();
+        for (const o of all) {
+            const opt = o;
+            const g = opt.__group;
+            if (!g || g === 'base')
+                continue; // base handled by default help
+            const rows = byGroup.get(g) ?? [];
+            rows.push({
+                flags: opt.flags ?? '',
+                description: opt.description ?? '',
+            });
+            byGroup.set(g, rows);
+        }
+        if (byGroup.size === 0)
+            return '';
+        const renderRows = (title, rows) => {
+            const width = Math.min(40, rows.reduce((m, r) => Math.max(m, r.flags.length), 0));
+            // Sort within group: short-aliased flags first
+            rows.sort((a, b) => {
+                const aS = /(^|\s|,)-[A-Za-z]/.test(a.flags) ? 1 : 0;
+                const bS = /(^|\s|,)-[A-Za-z]/.test(b.flags) ? 1 : 0;
+                return bS - aS || a.flags.localeCompare(b.flags);
+            });
+            const lines = rows
+                .map((r) => {
+                const pad = ' '.repeat(Math.max(2, width - r.flags.length + 2));
+                return `  ${r.flags}${pad}${r.description}`.trimEnd();
+            })
+                .join('\n');
+            return `\n${title}:\n${lines}\n`;
+        };
+        let out = '';
+        // App options (if any)
+        const app = byGroup.get('app');
+        if (app && app.length > 0) {
+            out += renderRows('App options', app);
+        }
+        // Plugin groups sorted by id
+        const pluginKeys = Array.from(byGroup.keys()).filter((k) => k.startsWith('plugin:'));
+        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) {
+                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 : ' ';
@@ -1142,6 +1595,7 @@ const attachRootOptions = (program, defaults, opts) => {
         .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)
@@ -1159,6 +1613,19 @@ const attachRootOptions = (program, defaults, opts) => {
         .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;
 };
 
@@ -1248,7 +1715,7 @@ 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, scripts, shellOff, ...rest } = rawCliOptions;
+    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 {
@@ -1268,6 +1735,8 @@ const resolveCliOptions = (rawCliOptions, defaults, parentJson) => {
     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;
@@ -1298,9 +1767,34 @@ GetDotenvCli.prototype.passOptions = function (defaults) {
         // 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.
@@ -1309,10 +1803,31 @@ GetDotenvCli.prototype.passOptions = function (defaults) {
         const { merged } = resolveCliOptions(raw, d, process.env.getDotenvCliOptions);
         thisCommand.getDotenvCliOptions =
             merged;
+        this._setOptionsBag(merged);
         // Avoid duplicate heavy work if a context is already present.
         if (!this.getCtx()) {
             const serviceOptions = getDotenvCliOptions2Options(merged);
             await this.resolveAndLoad(serviceOptions);
+            try {
+                const ctx = this.getCtx();
+                const 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;
@@ -1509,6 +2024,48 @@ const runCommand = async (command, shell, opts) => {
     }
 };
 
+const dropUndefined = (bag) => Object.fromEntries(Object.entries(bag).filter((e) => typeof e[1] === 'string'));
+/** Build a sanitized env for child processes from base + overlay. */
+const buildSpawnEnv = (base, overlay) => {
+    const raw = {
+        ...(base ?? {}),
+        ...(overlay ?? {}),
+    };
+    // Drop undefined first
+    const entries = Object.entries(dropUndefined(raw));
+    if (process.platform === 'win32') {
+        // Windows: keys are case-insensitive; collapse duplicates
+        const byLower = new Map();
+        for (const [k, v] of entries) {
+            byLower.set(k.toLowerCase(), [k, v]); // last wins; preserve latest casing
+        }
+        const out = {};
+        for (const [, [k, v]] of byLower)
+            out[k] = v;
+        // HOME fallback from USERPROFILE (common expectation)
+        if (!Object.prototype.hasOwnProperty.call(out, 'HOME')) {
+            const up = out['USERPROFILE'];
+            if (typeof up === 'string' && up.length > 0)
+                out['HOME'] = up;
+        }
+        // Normalize TMP/TEMP coherence (pick any present; reflect to both)
+        const tmp = out['TMP'] ?? out['TEMP'];
+        if (typeof tmp === 'string' && tmp.length > 0) {
+            out['TMP'] = tmp;
+            out['TEMP'] = tmp;
+        }
+        return out;
+    }
+    // POSIX: keep keys as-is
+    const out = Object.fromEntries(entries);
+    // Ensure TMPDIR exists when any temp key is present (best-effort)
+    const tmpdir = out['TMPDIR'] ?? out['TMP'] ?? out['TEMP'];
+    if (typeof tmpdir === 'string' && tmpdir.length > 0) {
+        out['TMPDIR'] = tmpdir;
+    }
+    return out;
+};
+
 /**
  * Define a GetDotenv CLI plugin with compositional helpers.
  *
@@ -1866,7 +2423,7 @@ const awsPlugin = () => definePlugin({
                 const shellSetting = resolveShell(rootOpts?.scripts, 'aws', rootOpts?.shell);
                 const ctxDotenv = (ctx?.dotenv ?? {});
                 const exit = await runCommand(argv, shellSetting, {
-                    env: { ...process.env, ...ctxDotenv },
+                    env: buildSpawnEnv(process.env, ctxDotenv),
                     stdio: capture ? 'pipe' : 'inherit',
                 });
                 // Deterministic termination (suppressed under tests)
@@ -2005,14 +2562,12 @@ 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;
                 await runCommand(command, shell, {
                     cwd: path,
-                    env: {
-                        ...process.env,
-                        getDotenvCliOptions: getDotenvCliOptions
-                            ? JSON.stringify(getDotenvCliOptions)
-                            : undefined,
-                    },
+                    env: buildSpawnEnv(process.env, envBag),
                     stdio: capture ? 'pipe' : 'inherit',
                 });
             }
@@ -2329,6 +2884,17 @@ const attachParentAlias = (cli, options, _cmd) => {
     const desc = aliasSpec.description ??
         'alias of cmd subcommand; provide command tokens (variadic)';
     cli.option(aliasSpec.flags, desc);
+    // Tag the just-added parent option for grouped help rendering.
+    try {
+        const optsArr = cli.options;
+        if (Array.isArray(optsArr) && optsArr.length > 0) {
+            const last = optsArr[optsArr.length - 1];
+            last.__group = 'plugin:cmd';
+        }
+    }
+    catch {
+        /* noop */
+    }
     // Shared alias executor for either preAction or preSubcommand hooks.
     // Ensure we only execute once even if both hooks fire in a single parse.
     let aliasHandled = false;
@@ -2359,7 +2925,9 @@ const attachParentAlias = (cli, options, _cmd) => {
         aliasHandled = true;
         dbg('alias-only invocation detected');
         // Merge CLI options and resolve dotenv context.
-        const { merged } = resolveCliOptions(o, baseRootOptionDefaults, process.env.getDotenvCliOptions);
+        const { merged } = resolveCliOptions(o, 
+        // cast through unknown to avoid readonly -> mutable incompatibilities
+        baseRootOptionDefaults, process.env.getDotenvCliOptions);
         const logger = merged.logger ?? console;
         const serviceOptions = getDotenvCliOptions2Options(merged);
         await cli.resolveAndLoad(serviceOptions);
@@ -2412,7 +2980,41 @@ const attachParentAlias = (cli, options, _cmd) => {
                     : parent !== undefined
                         ? 'parent'
                         : 'unset';
-                process.stderr.write(`[trace] key=${k} origin=${origin} parent=${parent ?? ''} dotenv=${dot ?? ''} final=${final ?? ''}\n`);
+                // Build redact options and triple bag without undefined-valued fields
+                const redOpts = {};
+                const redFlag = merged.redact;
+                const redPatterns = merged
+                    .redactPatterns;
+                if (redFlag)
+                    redOpts.redact = true;
+                if (redFlag && Array.isArray(redPatterns))
+                    redOpts.redactPatterns = redPatterns;
+                const tripleBag = {};
+                if (parent !== undefined)
+                    tripleBag.parent = parent;
+                if (dot !== undefined)
+                    tripleBag.dotenv = dot;
+                if (final !== undefined)
+                    tripleBag.final = final;
+                const triple = redactTriple(k, tripleBag, redOpts);
+                process.stderr.write(`[trace] key=${k} origin=${origin} parent=${triple.parent ?? ''} dotenv=${triple.dotenv ?? ''} final=${triple.final ?? ''}\n`);
+                const entOpts = {};
+                const warnEntropy = merged.warnEntropy;
+                const entropyThreshold = merged
+                    .entropyThreshold;
+                const entropyMinLength = merged
+                    .entropyMinLength;
+                const entropyWhitelist = merged
+                    .entropyWhitelist;
+                if (typeof warnEntropy === 'boolean')
+                    entOpts.warnEntropy = warnEntropy;
+                if (typeof entropyThreshold === 'number')
+                    entOpts.entropyThreshold = entropyThreshold;
+                if (typeof entropyMinLength === 'number')
+                    entOpts.entropyMinLength = entropyMinLength;
+                if (Array.isArray(entropyWhitelist))
+                    entOpts.entropyWhitelist = entropyWhitelist;
+                maybeWarnEntropy(k, final, origin, entOpts, (line) => process.stderr.write(line + '\n'));
             }
         }
         let exitCode = Number.NaN;
@@ -2467,11 +3069,10 @@ const attachParentAlias = (cli, options, _cmd) => {
                 }
             }
             exitCode = await runCommand(commandArg, shellSetting, {
-                env: {
-                    ...process.env,
+                env: buildSpawnEnv(process.env, {
                     ...dotenv,
                     getDotenvCliOptions: JSON.stringify(envBag),
-                },
+                }),
                 stdio: capture ? 'pipe' : 'inherit',
             });
             dbg('run:done', { exitCode });
@@ -2629,8 +3230,41 @@ const cmdPlugin = (options = {}) => definePlugin({
                         : parent !== undefined
                             ? 'parent'
                             : 'unset';
+                    // Apply presentation-time redaction (if enabled)
+                    const redFlag = merged.redact;
+                    const redPatterns = merged
+                        .redactPatterns;
+                    const redOpts = {};
+                    if (redFlag)
+                        redOpts.redact = true;
+                    if (redFlag && Array.isArray(redPatterns))
+                        redOpts.redactPatterns = redPatterns;
+                    const tripleBag = {};
+                    if (parent !== undefined)
+                        tripleBag.parent = parent;
+                    if (dot !== undefined)
+                        tripleBag.dotenv = dot;
+                    if (final !== undefined)
+                        tripleBag.final = final;
+                    const triple = redactTriple(k, tripleBag, redOpts);
                     // Emit concise diagnostic line to stderr.
-                    process.stderr.write(`[trace] key=${k} origin=${origin} parent=${parent ?? ''} dotenv=${dot ?? ''} final=${final ?? ''}\n`);
+                    process.stderr.write(`[trace] key=${k} origin=${origin} parent=${triple.parent ?? ''} dotenv=${triple.dotenv ?? ''} final=${triple.final ?? ''}\n`);
+                    // Optional entropy warning (once-per-key)
+                    const entOpts = {};
+                    const warnEntropy = merged
+                        .warnEntropy;
+                    const entropyThreshold = merged.entropyThreshold;
+                    const entropyMinLength = merged.entropyMinLength;
+                    const entropyWhitelist = merged.entropyWhitelist;
+                    if (typeof warnEntropy === 'boolean')
+                        entOpts.warnEntropy = warnEntropy;
+                    if (typeof entropyThreshold === 'number')
+                        entOpts.entropyThreshold = entropyThreshold;
+                    if (typeof entropyMinLength === 'number')
+                        entOpts.entropyMinLength = entropyMinLength;
+                    if (Array.isArray(entropyWhitelist))
+                        entOpts.entropyWhitelist = entropyWhitelist;
+                    maybeWarnEntropy(k, final, origin, entOpts, (line) => process.stderr.write(line + '\n'));
                 }
             }
             const shellSetting = resolveShell(scripts, input, shell);
@@ -2648,11 +3282,10 @@ const cmdPlugin = (options = {}) => definePlugin({
                 ? args.map(String)
                 : resolved;
             await runCommand(commandArg, shellSetting, {
-                env: {
-                    ...process.env,
+                env: buildSpawnEnv(process.env, {
                     ...dotenv,
                     getDotenvCliOptions: JSON.stringify(envBag),
-                },
+                }),
                 stdio: capture ? 'pipe' : 'inherit',
             });
         });
@@ -3059,7 +3692,13 @@ const initPlugin = (opts = {}) => definePlugin({
 });
 
 // Shipped CLI rebased on plugin-first host.
-const program = new GetDotenvCli('getdotenv')
+const program = new GetDotenvCli('getdotenv');
+// Brand the shipped CLI so help shows the package version (e.g., "getdotenv v5.0.0").
+await program.brand({
+    importMetaUrl: import.meta.url,
+    description: 'Base CLI.',
+});
+program
     .attachRootOptions({ loadProcess: false })
     .use(cmdPlugin({ asDefault: true, optionAlias: '-c, --cmd <command...>' }))
     .use(batchPlugin())