@karmaniverous/get-dotenv 5.0.0 → 5.2.0

package/dist/index.mjs

@@ -5,11 +5,11 @@ import path, { join, extname } from 'path';
 import { execa, execaCommand } from 'execa';
 import fs from 'fs-extra';
 import url, { fileURLToPath, pathToFileURL } from 'url';
+import YAML from 'yaml';
+import { z } from 'zod';
 import { nanoid } from 'nanoid';
 import { parse } from 'dotenv';
 import { createHash } from 'crypto';
-import YAML from 'yaml';
-import { z } from 'zod';
 
 /**
  * Dotenv expansion utilities.
@@ -152,6 +152,28 @@ const dotenvExpandFromProcessEnv = (value) => dotenvExpand(value, process.env);
  * 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 : ' ';
@@ -207,6 +229,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)
@@ -224,6 +247,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;
 };
 
@@ -392,6 +428,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;
+};
+
 const globPaths = async ({ globs, logger, pkgCwd, rootPath, }) => {
     let cwd = process.cwd();
     if (pkgCwd) {
@@ -464,14 +542,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',
                 });
             }
@@ -624,6 +700,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',
@@ -644,7 +725,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) => {
@@ -652,10 +733,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 {
@@ -905,7 +986,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 {
@@ -925,6 +1006,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;
@@ -942,6 +1025,315 @@ const resolveCliOptions = (rawCliOptions, defaults, parentJson) => {
     return cmd !== undefined ? { merged, command: cmd } : { merged };
 };
 
+/**
+ * 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 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());
+const envStringMap = z.record(z.string(), stringMap);
+// Allow string[] or single string for "paths" in RAW; normalize later.
+const rawPathsSchema = z.union([z.array(z.string()), z.string()]).optional();
+const getDotenvConfigSchemaRaw = z.object({
+    dotenvToken: z.string().optional(),
+    privateToken: z.string().optional(),
+    paths: rawPathsSchema,
+    loadProcess: z.boolean().optional(),
+    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.
+    dynamic: z.unknown().optional(),
+    // Per-plugin config bag; validated by plugins/host when used.
+    plugins: z.record(z.string(), z.unknown()).optional(),
+});
+// Normalize paths to string[]
+const normalizePaths = (p) => p === undefined ? undefined : Array.isArray(p) ? p : [p];
+const getDotenvConfigSchemaResolved = getDotenvConfigSchemaRaw.transform((raw) => ({
+    ...raw,
+    paths: normalizePaths(raw.paths),
+}));
+
+// Discovery candidates (first match wins per scope/privacy).
+// Order preserves historical JSON/YAML precedence; JS/TS added afterwards.
+const PUBLIC_FILENAMES = [
+    'getdotenv.config.json',
+    'getdotenv.config.yaml',
+    'getdotenv.config.yml',
+    'getdotenv.config.js',
+    'getdotenv.config.mjs',
+    'getdotenv.config.cjs',
+    'getdotenv.config.ts',
+    'getdotenv.config.mts',
+    'getdotenv.config.cts',
+];
+const LOCAL_FILENAMES = [
+    'getdotenv.config.local.json',
+    'getdotenv.config.local.yaml',
+    'getdotenv.config.local.yml',
+    'getdotenv.config.local.js',
+    'getdotenv.config.local.mjs',
+    'getdotenv.config.local.cjs',
+    'getdotenv.config.local.ts',
+    'getdotenv.config.local.mts',
+    'getdotenv.config.local.cts',
+];
+const isYaml = (p) => ['.yaml', '.yml'].includes(extname(p).toLowerCase());
+const isJson = (p) => extname(p).toLowerCase() === '.json';
+const isJsOrTs = (p) => ['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts'].includes(extname(p).toLowerCase());
+// --- Internal JS/TS module loader helpers (default export) ---
+const importDefault$1 = async (fileUrl) => {
+    const mod = (await import(fileUrl));
+    return mod.default;
+};
+const cacheName = (absPath, suffix) => {
+    // sanitized filename with suffix; recompile on mtime changes not tracked here (simplified)
+    const base = path.basename(absPath).replace(/[^a-zA-Z0-9._-]/g, '_');
+    return `${base}.${suffix}.mjs`;
+};
+const ensureDir = async (dir) => {
+    await fs.ensureDir(dir);
+    return dir;
+};
+const loadJsTsDefault = async (absPath) => {
+    const fileUrl = pathToFileURL(absPath).toString();
+    const ext = extname(absPath).toLowerCase();
+    if (ext === '.js' || ext === '.mjs' || ext === '.cjs') {
+        return importDefault$1(fileUrl);
+    }
+    // Try direct import first in case a TS loader is active.
+    try {
+        const val = await importDefault$1(fileUrl);
+        if (val)
+            return val;
+    }
+    catch {
+        /* fallthrough */
+    }
+    // esbuild bundle to a temp ESM file
+    try {
+        const esbuild = (await import('esbuild'));
+        const outDir = await ensureDir(path.resolve('.tsbuild', 'getdotenv-config'));
+        const outfile = path.join(outDir, cacheName(absPath, 'bundle'));
+        await esbuild.build({
+            entryPoints: [absPath],
+            bundle: true,
+            platform: 'node',
+            format: 'esm',
+            target: 'node20',
+            outfile,
+            sourcemap: false,
+            logLevel: 'silent',
+        });
+        return await importDefault$1(pathToFileURL(outfile).toString());
+    }
+    catch {
+        /* fallthrough to TS transpile */
+    }
+    // typescript.transpileModule simple transpile (single-file)
+    try {
+        const ts = (await import('typescript'));
+        const src = await fs.readFile(absPath, 'utf-8');
+        const out = ts.transpileModule(src, {
+            compilerOptions: {
+                module: 'ESNext',
+                target: 'ES2022',
+                moduleResolution: 'NodeNext',
+            },
+        }).outputText;
+        const outDir = await ensureDir(path.resolve('.tsbuild', 'getdotenv-config'));
+        const outfile = path.join(outDir, cacheName(absPath, 'ts'));
+        await fs.writeFile(outfile, out, 'utf-8');
+        return await importDefault$1(pathToFileURL(outfile).toString());
+    }
+    catch {
+        throw new Error(`Unable to load JS/TS config: ${absPath}. Install 'esbuild' for robust bundling or ensure a TS loader.`);
+    }
+};
+/**
+ * Discover JSON/YAML config files in the packaged root and project root.
+ * Order: packaged public → project public → project local. */
+const discoverConfigFiles = async (importMetaUrl) => {
+    const files = [];
+    // Packaged root via importMetaUrl (optional)
+    if (importMetaUrl) {
+        const fromUrl = fileURLToPath(importMetaUrl);
+        const packagedRoot = await packageDirectory({ cwd: fromUrl });
+        if (packagedRoot) {
+            for (const name of PUBLIC_FILENAMES) {
+                const p = join(packagedRoot, name);
+                if (await fs.pathExists(p)) {
+                    files.push({ path: p, privacy: 'public', scope: 'packaged' });
+                    break; // only one public file expected per scope
+                }
+            }
+            // By policy, packaged .local is not expected; skip even if present.
+        }
+    }
+    // Project root (from current working directory)
+    const projectRoot = await packageDirectory();
+    if (projectRoot) {
+        for (const name of PUBLIC_FILENAMES) {
+            const p = join(projectRoot, name);
+            if (await fs.pathExists(p)) {
+                files.push({ path: p, privacy: 'public', scope: 'project' });
+                break;
+            }
+        }
+        for (const name of LOCAL_FILENAMES) {
+            const p = join(projectRoot, name);
+            if (await fs.pathExists(p)) {
+                files.push({ path: p, privacy: 'local', scope: 'project' });
+                break;
+            }
+        }
+    }
+    return files;
+};
+/**
+ * Load a single config file (JSON/YAML). JS/TS is not supported in this step.
+ * Validates with Zod RAW schema, then normalizes to RESOLVED.
+ *
+ * For JSON/YAML: if a "dynamic" property is present, throws with guidance.
+ * For JS/TS: default export is loaded; "dynamic" is allowed.
+ */
+const loadConfigFile = async (filePath) => {
+    let raw = {};
+    try {
+        const abs = path.resolve(filePath);
+        if (isJsOrTs(abs)) {
+            // JS/TS support: load default export via robust pipeline.
+            const mod = await loadJsTsDefault(abs);
+            raw = mod ?? {};
+        }
+        else {
+            const txt = await fs.readFile(abs, 'utf-8');
+            raw = isJson(abs) ? JSON.parse(txt) : isYaml(abs) ? YAML.parse(txt) : {};
+        }
+    }
+    catch (err) {
+        throw new Error(`Failed to read/parse config: ${filePath}. ${String(err)}`);
+    }
+    // Validate RAW
+    const parsed = getDotenvConfigSchemaRaw.safeParse(raw);
+    if (!parsed.success) {
+        const msgs = parsed.error.issues
+            .map((i) => `${i.path.join('.')}: ${i.message}`)
+            .join('\n');
+        throw new Error(`Invalid config ${filePath}:\n${msgs}`);
+    }
+    // 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);
+};
+/**
+ * Discover and load configs into resolved shapes, ordered by scope/privacy.
+ * JSON/YAML/JS/TS supported; first match per scope/privacy applies.
+ */
+const resolveGetDotenvConfigSources = async (importMetaUrl) => {
+    const discovered = await discoverConfigFiles(importMetaUrl);
+    const result = {};
+    for (const f of discovered) {
+        const cfg = await loadConfigFile(f.path);
+        if (f.scope === 'packaged') {
+            // packaged public only
+            result.packaged = cfg;
+        }
+        else {
+            result.project ??= {};
+            if (f.privacy === 'public')
+                result.project.public = cfg;
+            else
+                result.project.local = cfg;
+        }
+    }
+    return result;
+};
+
+/** 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;
+};
+
 const applyKv = (current, kv) => {
     if (!kv || Object.keys(kv).length === 0)
         return current;
@@ -997,7 +1389,7 @@ const readDotenv = async (path) => {
     }
 };
 
-const importDefault$1 = async (fileUrl) => {
+const importDefault = async (fileUrl) => {
     const mod = (await import(fileUrl));
     return mod.default;
 };
@@ -1048,11 +1440,11 @@ const loadModuleDefault = async (absPath, cacheDirName) => {
     const ext = path.extname(absPath).toLowerCase();
     const fileUrl = url.pathToFileURL(absPath).toString();
     if (!['.ts', '.mts', '.cts', '.tsx'].includes(ext)) {
-        return importDefault$1(fileUrl);
+        return importDefault(fileUrl);
     }
     // Try direct import first (TS loader active)
     try {
-        const dyn = await importDefault$1(fileUrl);
+        const dyn = await importDefault(fileUrl);
         if (dyn)
             return dyn;
     }
@@ -1077,7 +1469,7 @@ const loadModuleDefault = async (absPath, cacheDirName) => {
             sourcemap: false,
             logLevel: 'silent',
         });
-        const result = await importDefault$1(url.pathToFileURL(cacheFile).toString());
+        const result = await importDefault(url.pathToFileURL(cacheFile).toString());
         // Best-effort: trim older cache files for this source.
         await cleanupOldCacheFiles(cacheDir, path.basename(absPath));
         return result;
@@ -1097,7 +1489,7 @@ const loadModuleDefault = async (absPath, cacheDirName) => {
             },
         }).outputText;
         await fs.writeFile(cacheFile, out, 'utf-8');
-        const result = await importDefault$1(url.pathToFileURL(cacheFile).toString());
+        const result = await importDefault(url.pathToFileURL(cacheFile).toString());
         // Best-effort: trim older cache files for this source.
         await cleanupOldCacheFiles(cacheDir, path.basename(absPath));
         return result;
@@ -1231,8 +1623,41 @@ 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);
@@ -1240,235 +1665,59 @@ const getDotenv = async (options = {}) => {
 };
 
 /**
- * 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.
+ * 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.
  */
-// String-only env value map
-const stringMap = z.record(z.string(), z.string());
-const envStringMap = z.record(z.string(), stringMap);
-// Allow string[] or single string for "paths" in RAW; normalize later.
-const rawPathsSchema = z.union([z.array(z.string()), z.string()]).optional();
-const getDotenvConfigSchemaRaw = z.object({
-    dotenvToken: z.string().optional(),
-    privateToken: z.string().optional(),
-    paths: rawPathsSchema,
-    loadProcess: z.boolean().optional(),
-    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
-    vars: stringMap.optional(), // public, global
-    envVars: envStringMap.optional(), // public, per-env
-    // Dynamic in config (JS/TS only). JSON/YAML loader will reject if set.
-    dynamic: z.unknown().optional(),
-    // Per-plugin config bag; validated by plugins/host when used.
-    plugins: z.record(z.string(), z.unknown()).optional(),
-});
-// Normalize paths to string[]
-const normalizePaths = (p) => p === undefined ? undefined : Array.isArray(p) ? p : [p];
-const getDotenvConfigSchemaResolved = getDotenvConfigSchemaRaw.transform((raw) => ({
-    ...raw,
-    paths: normalizePaths(raw.paths),
-}));
-
-// Discovery candidates (first match wins per scope/privacy).
-// Order preserves historical JSON/YAML precedence; JS/TS added afterwards.
-const PUBLIC_FILENAMES = [
-    'getdotenv.config.json',
-    'getdotenv.config.yaml',
-    'getdotenv.config.yml',
-    'getdotenv.config.js',
-    'getdotenv.config.mjs',
-    'getdotenv.config.cjs',
-    'getdotenv.config.ts',
-    'getdotenv.config.mts',
-    'getdotenv.config.cts',
-];
-const LOCAL_FILENAMES = [
-    'getdotenv.config.local.json',
-    'getdotenv.config.local.yaml',
-    'getdotenv.config.local.yml',
-    'getdotenv.config.local.js',
-    'getdotenv.config.local.mjs',
-    'getdotenv.config.local.cjs',
-    'getdotenv.config.local.ts',
-    'getdotenv.config.local.mts',
-    'getdotenv.config.local.cts',
-];
-const isYaml = (p) => ['.yaml', '.yml'].includes(extname(p).toLowerCase());
-const isJson = (p) => extname(p).toLowerCase() === '.json';
-const isJsOrTs = (p) => ['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts'].includes(extname(p).toLowerCase());
-// --- Internal JS/TS module loader helpers (default export) ---
-const importDefault = async (fileUrl) => {
-    const mod = (await import(fileUrl));
-    return mod.default;
-};
-const cacheName = (absPath, suffix) => {
-    // sanitized filename with suffix; recompile on mtime changes not tracked here (simplified)
-    const base = path.basename(absPath).replace(/[^a-zA-Z0-9._-]/g, '_');
-    return `${base}.${suffix}.mjs`;
-};
-const ensureDir = async (dir) => {
-    await fs.ensureDir(dir);
-    return dir;
-};
-const loadJsTsDefault = async (absPath) => {
-    const fileUrl = pathToFileURL(absPath).toString();
-    const ext = extname(absPath).toLowerCase();
-    if (ext === '.js' || ext === '.mjs' || ext === '.cjs') {
-        return importDefault(fileUrl);
-    }
-    // Try direct import first in case a TS loader is active.
-    try {
-        const val = await importDefault(fileUrl);
-        if (val)
-            return val;
-    }
-    catch {
-        /* fallthrough */
-    }
-    // esbuild bundle to a temp ESM file
-    try {
-        const esbuild = (await import('esbuild'));
-        const outDir = await ensureDir(path.resolve('.tsbuild', 'getdotenv-config'));
-        const outfile = path.join(outDir, cacheName(absPath, 'bundle'));
-        await esbuild.build({
-            entryPoints: [absPath],
-            bundle: true,
-            platform: 'node',
-            format: 'esm',
-            target: 'node20',
-            outfile,
-            sourcemap: false,
-            logLevel: 'silent',
-        });
-        return await importDefault(pathToFileURL(outfile).toString());
-    }
-    catch {
-        /* fallthrough to TS transpile */
-    }
-    // typescript.transpileModule simple transpile (single-file)
-    try {
-        const ts = (await import('typescript'));
-        const src = await fs.readFile(absPath, 'utf-8');
-        const out = ts.transpileModule(src, {
-            compilerOptions: {
-                module: 'ESNext',
-                target: 'ES2022',
-                moduleResolution: 'NodeNext',
-            },
-        }).outputText;
-        const outDir = await ensureDir(path.resolve('.tsbuild', 'getdotenv-config'));
-        const outfile = path.join(outDir, cacheName(absPath, 'ts'));
-        await fs.writeFile(outfile, out, 'utf-8');
-        return await importDefault(pathToFileURL(outfile).toString());
-    }
-    catch {
-        throw new Error(`Unable to load JS/TS config: ${absPath}. Install 'esbuild' for robust bundling or ensure a TS loader.`);
-    }
-};
-/**
- * Discover JSON/YAML config files in the packaged root and project root.
- * Order: packaged public → project public → project local. */
-const discoverConfigFiles = async (importMetaUrl) => {
-    const files = [];
-    // Packaged root via importMetaUrl (optional)
-    if (importMetaUrl) {
-        const fromUrl = fileURLToPath(importMetaUrl);
-        const packagedRoot = await packageDirectory({ cwd: fromUrl });
-        if (packagedRoot) {
-            for (const name of PUBLIC_FILENAMES) {
-                const p = join(packagedRoot, name);
-                if (await fs.pathExists(p)) {
-                    files.push({ path: p, privacy: 'public', scope: 'packaged' });
-                    break; // only one public file expected per scope
-                }
-            }
-            // By policy, packaged .local is not expected; skip even if present.
-        }
-    }
-    // Project root (from current working directory)
-    const projectRoot = await packageDirectory();
-    if (projectRoot) {
-        for (const name of PUBLIC_FILENAMES) {
-            const p = join(projectRoot, name);
-            if (await fs.pathExists(p)) {
-                files.push({ path: p, privacy: 'public', scope: 'project' });
-                break;
-            }
-        }
-        for (const name of LOCAL_FILENAMES) {
-            const p = join(projectRoot, name);
-            if (await fs.pathExists(p)) {
-                files.push({ path: p, privacy: 'local', scope: 'project' });
-                break;
-            }
-        }
-    }
-    return files;
-};
+/** @internal */
+const isPlainObject = (v) => v !== null &&
+    typeof v === 'object' &&
+    !Array.isArray(v) &&
+    Object.getPrototypeOf(v) === Object.prototype;
 /**
- * Load a single config file (JSON/YAML). JS/TS is not supported in this step.
- * Validates with Zod RAW schema, then normalizes to RESOLVED.
+ * Deeply interpolate string leaves against envRef.
+ * Arrays are not recursed into; they are returned unchanged.
  *
- * For JSON/YAML: if a "dynamic" property is present, throws with guidance.
- * For JS/TS: default export is loaded; "dynamic" is allowed.
+ * @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 loadConfigFile = async (filePath) => {
-    let raw = {};
-    try {
-        const abs = path.resolve(filePath);
-        if (isJsOrTs(abs)) {
-            // JS/TS support: load default export via robust pipeline.
-            const mod = await loadJsTsDefault(abs);
-            raw = mod ?? {};
-        }
-        else {
-            const txt = await fs.readFile(abs, 'utf-8');
-            raw = isJson(abs) ? JSON.parse(txt) : isYaml(abs) ? YAML.parse(txt) : {};
-        }
-    }
-    catch (err) {
-        throw new Error(`Failed to read/parse config: ${filePath}. ${String(err)}`);
-    }
-    // Validate RAW
-    const parsed = getDotenvConfigSchemaRaw.safeParse(raw);
-    if (!parsed.success) {
-        const msgs = parsed.error.issues
-            .map((i) => `${i.path.join('.')}: ${i.message}`)
-            .join('\n');
-        throw new Error(`Invalid config ${filePath}:\n${msgs}`);
+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);
     }
-    // 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.`);
+    // Arrays: return as-is (no recursion)
+    if (Array.isArray(value)) {
+        return value;
     }
-    return getDotenvConfigSchemaResolved.parse(parsed.data);
-};
-/**
- * Discover and load configs into resolved shapes, ordered by scope/privacy.
- * JSON/YAML/JS/TS supported; first match per scope/privacy applies.
- */
-const resolveGetDotenvConfigSources = async (importMetaUrl) => {
-    const discovered = await discoverConfigFiles(importMetaUrl);
-    const result = {};
-    for (const f of discovered) {
-        const cfg = await loadConfigFile(f.path);
-        if (f.scope === 'packaged') {
-            // packaged public only
-            result.packaged = cfg;
-        }
-        else {
-            result.project ??= {};
-            if (f.privacy === 'public')
-                result.project.public = cfg;
+    // 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
-                result.project.local = cfg;
+                out[k] = v;
         }
+        return out;
     }
-    return result;
+    // Other primitives/types: return as-is
+    return value;
 };
 
 /**
@@ -1480,7 +1729,9 @@ const resolveGetDotenvConfigSources = async (importMetaUrl) => {
  * 2) Discover packaged + project config sources and overlay onto base.
  * 3) Apply dynamics in order:
  *    programmatic dynamic \> config dynamic (packaged → project public → project local)
- *    \> file dynamicPath. * 4) Optionally write outputPath, log, and merge into process.env.
+ *    \> file dynamicPath.
+ * 4) Phase C interpolation of remaining string options (e.g., outputPath).
+ * 5) Optionally write outputPath, log, and merge into process.env.
  */
 const resolveDotenvWithConfigLoader = async (validated) => {
     // 1) Base from files, no dynamic, no programmatic vars
@@ -1528,21 +1779,112 @@ const resolveDotenvWithConfigLoader = async (validated) => {
             throw new Error(`Unable to load dynamic from ${validated.dynamicPath}`);
         }
     }
-    // 4) Output/log/process merge
-    if (validated.outputPath) {
-        await fs.writeFile(validated.outputPath, Object.keys(dotenv).reduce((contents, key) => {
+    // 4) Phase C: interpolate remaining string options (exclude bootstrap set).
+    // For now, interpolate outputPath only; bootstrap keys are excluded by design.
+    const envRef = { ...process.env, ...dotenv };
+    const outputPathInterpolated = typeof validated.outputPath === 'string'
+        ? interpolateDeep(validated.outputPath, envRef)
+        : undefined;
+    // 5) Output/log/process merge (use interpolated outputPath if present)
+    if (outputPathInterpolated) {
+        await fs.writeFile(outputPathInterpolated, Object.keys(dotenv).reduce((contents, key) => {
             const value = dotenv[key] ?? '';
             return `${contents}${key}=${value.includes('\n') ? `"${value}"` : value}\n`;
         }, ''), { encoding: 'utf-8' });
     }
     const logger = validated.logger ?? console;
-    if (validated.log)
-        logger.log(dotenv);
+    if (validated.log) {
+        const redactFlag = validated.redact ?? false;
+        const redactPatterns = validated.redactPatterns;
+        const redOpts = {};
+        if (redactFlag)
+            redOpts.redact = true;
+        if (redactFlag && Array.isArray(redactPatterns))
+            redOpts.redactPatterns = redactPatterns;
+        const bag = redactFlag ? redactObject(dotenv, redOpts) : { ...dotenv };
+        logger.log(bag);
+        // Entropy warnings: once per key per run (presentation only)
+        const warnEntropyVal = validated.warnEntropy ?? true;
+        const entropyThresholdVal = validated.entropyThreshold;
+        const entropyMinLengthVal = validated.entropyMinLength;
+        const entropyWhitelistVal = validated.entropyWhitelist;
+        const entOpts = {};
+        // include keys only when defined to satisfy exactOptionalPropertyTypes
+        if (typeof warnEntropyVal === 'boolean')
+            entOpts.warnEntropy = warnEntropyVal;
+        if (typeof entropyThresholdVal === 'number')
+            entOpts.entropyThreshold = entropyThresholdVal;
+        if (typeof entropyMinLengthVal === 'number')
+            entOpts.entropyMinLength = entropyMinLengthVal;
+        if (Array.isArray(entropyWhitelistVal))
+            entOpts.entropyWhitelist = entropyWhitelistVal;
+        for (const [k, v] of Object.entries(dotenv)) {
+            maybeWarnEntropy(k, v, v !== undefined ? 'dotenv' : 'unset', entOpts, (line) => {
+                logger.log(line);
+            });
+        }
+    }
     if (validated.loadProcess)
         Object.assign(process.env, dotenv);
     return dotenv;
 };
 
+/**
+ * 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 [];
+};
+
 /**
  * Omit a "logger" key from an options object in a typed manner.
  */
@@ -1581,6 +1923,22 @@ const makePreSubcommandHook = ({ logger, preHook, postHook, defaults, }) => {
         // Execute getdotenv via always-on config loader/overlay path.
         const serviceOptions = getDotenvCliOptions2Options(mergedGetDotenvCliOptions);
         const dotenv = await resolveDotenvWithConfigLoader(serviceOptions);
+        // Global validation against config (warn by default; --strict fails).
+        try {
+            const sources = await resolveGetDotenvConfigSources(import.meta.url);
+            const issues = validateEnvAgainstSources(dotenv, sources);
+            if (Array.isArray(issues) && issues.length > 0) {
+                issues.forEach((m) => {
+                    logger.error(m);
+                });
+                if (mergedGetDotenvCliOptions.strict) {
+                    process.exit(1);
+                }
+            }
+        }
+        catch {
+            // Tolerate validator failures in non-strict mode
+        }
         // Execute post-hook.
         if (postHook)
             await postHook(dotenv); // Execute command.
@@ -1644,4 +2002,4 @@ const generateGetDotenvCli = async (customOptions) => {
     return program;
 };
 
-export { defineDynamic, dotenvExpand, dotenvExpandAll, dotenvExpandFromProcessEnv, generateGetDotenvCli, getDotenv, getDotenvCliOptions2Options };
+export { defineDynamic, dotenvExpand, dotenvExpandAll, dotenvExpandFromProcessEnv, generateGetDotenvCli, getDotenv, getDotenvCliOptions2Options, interpolateDeep };