@karmaniverous/get-dotenv 5.0.0 → 5.2.0

package/README.md

@@ -34,6 +34,20 @@ Load environment variables with a cascade of environment-aware dotenv files. You
 
 ✅ Set defaults for all options in a `getdotenv.config.json` file in your project root directory.
 
+✅ Validate your final composed environment via config: JSON/YAML `requiredKeys` or a JS/TS Zod `schema`. Validation runs once after Phase C (interpolation). Use `--strict` to fail on issues; otherwise warnings are printed. See the [Config files and overlays](./guides/config.md) guide.
+
+✅ Diagnostics for safer visibility without altering runtime values:
+
+- Redaction at presentation time for secret-like keys (`--redact`, `--redact-pattern`).
+- Entropy warnings (on by default) for high-entropy strings; gated by length/printability and tunable via `--entropy-*` flags. See [Config files and overlays](./guides/config.md).
+
+✅ Clear tracing and CI-friendly capture:
+
+- `--trace [keys...]` shows per-key origin (parent | dotenv | unset) before spawning.
+- Set `GETDOTENV_STDIO=pipe` or use `--capture` to buffer child stdout/stderr deterministically. See [Shell execution behavior](./guides/shell.md).
+
+✅ Cross-platform shells and normalized child environments: defaults to `/bin/bash` on POSIX and `powershell.exe` on Windows; subprocess env is composed once via a unified helper that drops undefineds and normalizes temp/home variables. See [Shell execution behavior](./guides/shell.md).
+
 ✅ [Generate an extensible `getdotenv`-based CLI](https://github.com/karmaniverous/get-dotenv-child) for use in your own projects.
 
 `getdotenv` relies on the excellent [`dotenv`](https://www.npmjs.com/package/dotenv) parser and somewhat improves on [`dotenv-expand`](https://www.npmjs.com/package/dotenv-expand) for recursive variable expansion.

package/dist/cliHost.cjs

@@ -3,9 +3,9 @@
 var commander = require('commander');
 var fs = require('fs-extra');
 var packageDirectory = require('package-directory');
+var url = require('url');
 var path = require('path');
 var zod = require('zod');
-var url = require('url');
 var YAML = require('yaml');
 var nanoid = require('nanoid');
 var dotenv = require('dotenv');
@@ -38,6 +38,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',
@@ -58,7 +63,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) => {
@@ -66,10 +71,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 {
@@ -229,11 +234,12 @@ const getDotenvOptionsSchemaRaw = zod.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 = zod.z.record(zod.z.string(), zod.z.string());
@@ -248,6 +254,8 @@ const getDotenvConfigSchemaRaw = zod.z.object({
     log: zod.z.boolean().optional(),
     shell: zod.z.union([zod.z.string(), zod.z.boolean()]).optional(),
     scripts: zod.z.record(zod.z.string(), zod.z.unknown()).optional(), // Scripts validation left wide; generator validates elsewhere
+    requiredKeys: zod.z.array(zod.z.string()).optional(),
+    schema: zod.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.
@@ -430,9 +438,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);
 };
@@ -620,6 +630,78 @@ 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;
+};
+
 /**
  * Asynchronously read a dotenv file & parse it into an object.
  *
@@ -869,14 +951,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).
@@ -960,19 +1131,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,
@@ -984,6 +1168,8 @@ const computeContext = async (customOptions, plugins, hostMetaUrl) => {
 
 const HOST_META_URL = (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cliHost.cjs', document.baseURI).href));
 const CTX_SYMBOL = Symbol('GetDotenvCli.ctx');
+const OPTS_SYMBOL = Symbol('GetDotenvCli.options');
+const HELP_HEADER_SYMBOL = Symbol('GetDotenvCli.helpHeader');
 /**
  * Plugin-first CLI host for get-dotenv. Extends Commander.Command.
  *
@@ -1000,15 +1186,46 @@ class GetDotenvCli extends commander.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 () => {
@@ -1040,11 +1257,96 @@ class GetDotenvCli extends commander.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 = url.fileURLToPath(importMetaUrl);
+                const pkgDir = await packageDirectory.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()).
@@ -1083,7 +1385,77 @@ class GetDotenvCli extends commander.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;
+    }
 }
 
+/**
+ * Helper to retrieve the merged root options bag from any action handler
+ * that only has access to thisCommand. Avoids structural casts.
+ */
+const readMergedOptions = (cmd) => {
+    // Ascend to the root command
+    let root = cmd;
+    while (root.parent) {
+        root = root.parent;
+    }
+    const hostAny = root;
+    return typeof hostAny.getOptions === 'function'
+        ? hostAny.getOptions()
+        : root
+            .getDotenvCliOptions;
+};
+
 exports.GetDotenvCli = GetDotenvCli;
 exports.definePlugin = definePlugin;
+exports.readMergedOptions = readMergedOptions;