@karmaniverous/get-dotenv 5.1.0 → 5.2.0

package/dist/getdotenv.cli.mjs

@@ -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,
@@ -1013,10 +1218,23 @@ class GetDotenvCli extends Command {
             visibleOptions: (cmd) => {
                 const all = cmd.options ??
                     [];
-                return all.filter((opt) => {
+                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', () => {
@@ -1205,6 +1423,12 @@ class GetDotenvCli extends Command {
             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));
@@ -1233,6 +1457,62 @@ class GetDotenvCli extends Command {
     }
 }
 
+/**
+ * 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.
@@ -1315,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)
@@ -1332,6 +1613,16 @@ 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;
@@ -1424,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 {
@@ -1444,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;
@@ -1479,6 +1772,29 @@ GetDotenvCli.prototype.passOptions = function (defaults) {
         // 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.
@@ -1492,6 +1808,26 @@ GetDotenvCli.prototype.passOptions = function (defaults) {
         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;
@@ -1688,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.
  *
@@ -2045,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)
@@ -2184,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',
                 });
             }
@@ -2549,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);
@@ -2602,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;
@@ -2657,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 });
@@ -2819,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);
@@ -2838,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',
             });
         });