@karmaniverous/get-dotenv 5.0.0 → 5.2.0

package/dist/cliHost.mjs

@@ -1,9 +1,9 @@
 import { Command } 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';
@@ -35,6 +35,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',
@@ -55,7 +60,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) => {
@@ -63,10 +68,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 {
@@ -226,11 +231,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());
@@ -245,6 +251,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.
@@ -427,9 +435,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,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.
  *
@@ -866,14 +948,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 +1128,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 +1165,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 +1183,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 +1254,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,6 +1382,75 @@ 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;
+    }
 }
 
-export { GetDotenvCli, definePlugin };
+/**
+ * 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;
+};
+
+export { GetDotenvCli, definePlugin, readMergedOptions };

package/dist/config.cjs

@@ -8,11 +8,12 @@ var YAML = require('yaml');
 var zod = require('zod');
 
 /**
- * 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());
@@ -27,6 +28,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.
@@ -209,9 +212,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);
 };

package/dist/config.d.cts

@@ -11,6 +11,8 @@ type GetDotenvConfigResolved = {
     log?: boolean;
     shell?: string | boolean;
     scripts?: Scripts;
+    requiredKeys?: string[];
+    schema?: unknown;
     vars?: Record<string, string>;
     envVars?: Record<string, Record<string, string>>;
     dynamic?: unknown;

package/dist/config.d.mts

@@ -11,6 +11,8 @@ type GetDotenvConfigResolved = {
     log?: boolean;
     shell?: string | boolean;
     scripts?: Scripts;
+    requiredKeys?: string[];
+    schema?: unknown;
     vars?: Record<string, string>;
     envVars?: Record<string, Record<string, string>>;
     dynamic?: unknown;

package/dist/config.d.ts

@@ -11,6 +11,8 @@ type GetDotenvConfigResolved = {
     log?: boolean;
     shell?: string | boolean;
     scripts?: Scripts;
+    requiredKeys?: string[];
+    schema?: unknown;
     vars?: Record<string, string>;
     envVars?: Record<string, Record<string, string>>;
     dynamic?: unknown;

package/dist/config.mjs

@@ -6,11 +6,12 @@ import YAML from 'yaml';
 import { z } from 'zod';
 
 /**
- * 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());
@@ -25,6 +26,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.
@@ -207,9 +210,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);
 };

package/dist/env-overlay.d.cts

@@ -15,6 +15,8 @@ type GetDotenvConfigResolved = {
     log?: boolean;
     shell?: string | boolean;
     scripts?: Scripts;
+    requiredKeys?: string[];
+    schema?: unknown;
     vars?: Record<string, string>;
     envVars?: Record<string, Record<string, string>>;
     dynamic?: unknown;

package/dist/env-overlay.d.mts

@@ -15,6 +15,8 @@ type GetDotenvConfigResolved = {
     log?: boolean;
     shell?: string | boolean;
     scripts?: Scripts;
+    requiredKeys?: string[];
+    schema?: unknown;
     vars?: Record<string, string>;
     envVars?: Record<string, Record<string, string>>;
     dynamic?: unknown;

package/dist/env-overlay.d.ts

@@ -15,6 +15,8 @@ type GetDotenvConfigResolved = {
     log?: boolean;
     shell?: string | boolean;
     scripts?: Scripts;
+    requiredKeys?: string[];
+    schema?: unknown;
     vars?: Record<string, string>;
     envVars?: Record<string, Record<string, string>>;
     dynamic?: unknown;