@karmaniverous/get-dotenv 6.2.3 → 6.3.0

package/dist/config.mjs

@@ -1,509 +1,11 @@
-import fs from 'fs-extra';
-import { packageDirectory } from 'package-directory';
-import path, { join, extname } from 'path';
-import url, { pathToFileURL, fileURLToPath } from 'url';
-import YAML from 'yaml';
-import { z } from 'zod';
-import { createHash } from 'crypto';
-
-/**
- * Zod schemas for programmatic GetDotenv options.
- *
- * Canonical source of truth for options shape. Public types are derived
- * from these schemas (see consumers via z.output\<\>).
- */
-/**
- * Minimal process env representation used by options and helpers.
- * Values may be `undefined` to indicate "unset".
- */
-/**
- * Schema for an env-like record.
- *
- * Keys are environment variable names and values are either strings or `undefined`
- * (to represent “unset”).
- *
- * @public
- */
-const processEnvSchema = z.record(z.string(), z.string().optional());
-// RAW: all fields optional — undefined means "inherit" from lower layers.
-/**
- * Programmatic options schema (raw).
- *
- * This schema is the canonical runtime source of truth for the `getDotenv()` programmatic API.
- * All fields are optional; `undefined` generally means “inherit default/lower layer”.
- *
- * @public
- */
-const getDotenvOptionsSchemaRaw = z.object({
-    /** Default environment name when `env` is not provided. */
-    defaultEnv: z.string().optional(),
-    /** Base dotenv filename token (default `.env`). */
-    dotenvToken: z.string().optional(),
-    /** Path to a dynamic variables module (JS/TS) to load and apply. */
-    dynamicPath: z.string().optional(),
-    /** Dynamic map is intentionally wide for now; refine once sources are normalized. */
-    dynamic: z.record(z.string(), z.unknown()).optional(),
-    /** Selected environment name for this invocation (for env-scoped files and overlays). */
-    env: z.string().optional(),
-    /** When true, skip applying dynamic variables. */
-    excludeDynamic: z.boolean().optional(),
-    /** When true, skip environment-scoped dotenv files. */
-    excludeEnv: z.boolean().optional(),
-    /** When true, skip global dotenv files. */
-    excludeGlobal: z.boolean().optional(),
-    /** When true, skip private dotenv files. */
-    excludePrivate: z.boolean().optional(),
-    /** When true, skip public dotenv files. */
-    excludePublic: z.boolean().optional(),
-    /** When true, merge the final composed environment into `process.env`. */
-    loadProcess: z.boolean().optional(),
-    /** When true, log the final environment map via `logger`. */
-    log: z.boolean().optional(),
-    /** Logger used when `log` is enabled (console-compatible). */
-    logger: z.unknown().default(console),
-    /** Optional output dotenv file path to write after composition. */
-    outputPath: z.string().optional(),
-    /** Dotenv search paths (ordered). */
-    paths: z.array(z.string()).optional(),
-    /** Private token suffix for private dotenv files (default `local`). */
-    privateToken: z.string().optional(),
-    /** Explicit variables to overlay onto the composed dotenv map. */
-    vars: processEnvSchema.optional(),
-});
-
-/**
- * Zod schemas for CLI-facing GetDotenv options (raw/resolved stubs).
- *
- * RAW allows stringly inputs (paths/vars + splitters). RESOLVED will later
- * reflect normalized types (paths: string[], vars: ProcessEnv), applied in the
- * CLI resolution pipeline.
- */
-/**
- * CLI options schema (raw).
- *
- * Extends the programmatic options schema with CLI-only flags and stringly inputs
- * which are normalized later by the host resolution pipeline.
- *
- * @public
- */
-const getDotenvCliOptionsSchemaRaw = getDotenvOptionsSchemaRaw.extend({
-    // CLI-specific fields (stringly inputs before preprocessing)
-    /** Enable verbose debug output (host-specific). */
-    debug: z.boolean().optional(),
-    /** Fail on validation errors (schema/requiredKeys). */
-    strict: z.boolean().optional(),
-    /** Capture child process stdio (useful for CI/tests). */
-    capture: z.boolean().optional(),
-    /** Emit child env diagnostics (boolean or selected keys). */
-    trace: z.union([z.boolean(), z.array(z.string())]).optional(),
-    /** Enable presentation-time redaction in trace/log output. */
-    redact: z.boolean().optional(),
-    /** Enable entropy warnings in trace/log output. */
-    warnEntropy: z.boolean().optional(),
-    /** Entropy threshold (bits/char) for warnings. */
-    entropyThreshold: z.number().optional(),
-    /** Minimum value length to consider for entropy warnings. */
-    entropyMinLength: z.number().optional(),
-    /** Regex patterns (strings) to suppress entropy warnings by key. */
-    entropyWhitelist: z.array(z.string()).optional(),
-    /** Additional key-match patterns (strings) for redaction. */
-    redactPatterns: z.array(z.string()).optional(),
-    /** Dotenv search paths provided as a single delimited string. */
-    paths: z.string().optional(),
-    /** Delimiter string used to split `paths`. */
-    pathsDelimiter: z.string().optional(),
-    /** Regex pattern used to split `paths` (takes precedence over delimiter). */
-    pathsDelimiterPattern: z.string().optional(),
-    /** Scripts table in a permissive shape at parse time (validated elsewhere). */
-    scripts: z.record(z.string(), z.unknown()).optional(),
-    /** Shell selection (`false` for shell-off, string for explicit shell). */
-    shell: z.union([z.boolean(), z.string()]).optional(),
-    /** Extra variables expressed as a single delimited string of assignments. */
-    vars: z.string().optional(),
-    /** Assignment operator used when parsing `vars`. */
-    varsAssignor: z.string().optional(),
-    /** Regex pattern used as the assignment operator for `vars` parsing. */
-    varsAssignorPattern: z.string().optional(),
-    /** Delimiter string used to split `vars`. */
-    varsDelimiter: z.string().optional(),
-    /** Regex pattern used to split `vars` (takes precedence over delimiter). */
-    varsDelimiterPattern: z.string().optional(),
-});
-
-const visibilityMap = z.record(z.string(), z.boolean());
-/**
- * Zod schemas for configuration files discovered by the new loader.
- *
- * Notes:
- * - RAW: all fields optional; only allowed top-level keys are:
- *   - rootOptionDefaults, rootOptionVisibility
- *   - scripts, vars, envVars
- *   - dynamic (JS/TS only), schema (JS/TS only)
- *   - plugins, requiredKeys
- * - RESOLVED: mirrors RAW (no path normalization).
- * - 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);
-/**
- * Raw configuration schema for get‑dotenv config files (JSON/YAML/JS/TS).
- * Validates allowed top‑level keys without performing path normalization.
- */
-/**
- * Config schema for discovered get-dotenv configuration documents (raw).
- *
- * This schema validates the allowed top-level keys for configuration files.
- * It does not normalize paths or coerce types beyond Zod’s parsing.
- *
- * @public
- */
-const getDotenvConfigSchemaRaw = z.object({
-    /** Root option defaults applied by the host (CLI-like, collapsed families). */
-    rootOptionDefaults: getDotenvCliOptionsSchemaRaw.optional(),
-    /** Help-time visibility map for root flags (false hides). */
-    rootOptionVisibility: visibilityMap.optional(),
-    /** Scripts table used by cmd/batch resolution (validation intentionally permissive here). */
-    scripts: z.record(z.string(), z.unknown()).optional(),
-    /** Keys required to be present in the final composed environment. */
-    requiredKeys: z.array(z.string()).optional(),
-    /** Validation schema (JS/TS only; JSON/YAML loader rejects). */
-    schema: z.unknown().optional(), // JS/TS-only; loader rejects in JSON/YAML
-    /** Public global variables (string-only). */
-    vars: stringMap.optional(), // public, global
-    /** Public per-environment variables (string-only). */
-    envVars: envStringMap.optional(), // public, per-env
-    // Dynamic in config (JS/TS only). JSON/YAML loader will reject if set.
-    /** Dynamic variable definitions (JS/TS only). */
-    dynamic: z.unknown().optional(),
-    // Per-plugin config bag; validated by plugins/host when used.
-    /** Per-plugin config slices keyed by realized mount path (for example, `aws/whoami`). */
-    plugins: z.record(z.string(), z.unknown()).optional(),
-});
-/**
- * Resolved configuration schema which preserves the raw shape while narrowing
- * the output to {@link GetDotenvConfigResolved}. Consumers get a strongly typed
- * object, while the underlying validation remains Zod‑driven.
- */
-const getDotenvConfigSchemaResolved = getDotenvConfigSchemaRaw.transform((raw) => raw);
-
-const importDefault = async (fileUrl) => {
-    const mod = (await import(fileUrl));
-    return mod.default;
-};
-const cacheHash = (absPath, mtimeMs) => createHash('sha1')
-    .update(absPath)
-    .update(String(mtimeMs))
-    .digest('hex')
-    .slice(0, 12);
-/**
- * Remove older compiled cache files for a given source base name, keeping
- * at most `keep` most-recent files. Errors are ignored by design.
- */
-const cleanupOldCacheFiles = async (cacheDir, baseName, keep = Math.max(1, Number.parseInt(process.env.GETDOTENV_CACHE_KEEP ?? '2'))) => {
-    try {
-        const entries = await fs.readdir(cacheDir);
-        const mine = entries
-            .filter((f) => f.startsWith(`${baseName}.`) && f.endsWith('.mjs'))
-            .map((f) => path.join(cacheDir, f));
-        if (mine.length <= keep)
-            return;
-        const stats = await Promise.all(mine.map(async (p) => ({ p, mtimeMs: (await fs.stat(p)).mtimeMs })));
-        stats.sort((a, b) => b.mtimeMs - a.mtimeMs);
-        const toDelete = stats.slice(keep).map((s) => s.p);
-        await Promise.all(toDelete.map(async (p) => {
-            try {
-                await fs.remove(p);
-            }
-            catch {
-                // best-effort cleanup
-            }
-        }));
-    }
-    catch {
-        // best-effort cleanup
-    }
-};
-/**
- * Load a module default export from a JS/TS file with robust fallbacks.
- *
- * Behavior by extension:
- *
- * - `.js`/`.mjs`/`.cjs`: direct dynamic import.
- * - `.ts`/`.mts`/`.cts`/`.tsx`:
- *   - try direct dynamic import (when a TS loader is active),
- *   - else compile via `esbuild` to a cached `.mjs` file and import,
- *   - else fallback to `typescript.transpileModule` for simple modules.
- *
- * @typeParam T - Type of the expected default export.
- * @param absPath - Absolute path to the source file.
- * @param cacheDirName - Cache subfolder under `.tsbuild/`.
- * @returns A `Promise\<T | undefined\>` resolving to the default export (if any).
- */
-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(fileUrl);
-    }
-    // Try direct import first (TS loader active)
-    try {
-        const dyn = await importDefault(fileUrl);
-        if (dyn)
-            return dyn;
-    }
-    catch {
-        /* fall through */
-    }
-    const stat = await fs.stat(absPath);
-    const hash = cacheHash(absPath, stat.mtimeMs);
-    const cacheDir = path.resolve('.tsbuild', cacheDirName);
-    await fs.ensureDir(cacheDir);
-    const cacheFile = path.join(cacheDir, `${path.basename(absPath)}.${hash}.mjs`);
-    // Try esbuild
-    try {
-        const esbuild = (await import('esbuild'));
-        await esbuild.build({
-            entryPoints: [absPath],
-            bundle: true,
-            platform: 'node',
-            format: 'esm',
-            target: 'node20',
-            outfile: cacheFile,
-            sourcemap: false,
-            logLevel: 'silent',
-        });
-        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;
-    }
-    catch {
-        /* fall through to TS transpile */
-    }
-    // TypeScript transpile fallback
-    try {
-        const ts = (await import('typescript'));
-        const code = await fs.readFile(absPath, 'utf-8');
-        const out = ts.transpileModule(code, {
-            compilerOptions: {
-                module: 'ESNext',
-                target: 'ES2022',
-                moduleResolution: 'NodeNext',
-            },
-        }).outputText;
-        await fs.writeFile(cacheFile, out, 'utf-8');
-        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;
-    }
-    catch {
-        // Caller decides final error wording; rethrow for upstream mapping.
-        throw new Error(`Unable to load JS/TS module: ${absPath}. Install 'esbuild' or ensure a TS loader.`);
-    }
-};
-
-/**
- * @packageDocumentation
- * Configuration discovery and loading for get‑dotenv. Discovers config files
- * in the packaged root and project root, loads JSON/YAML/JS/TS documents, and
- * validates them against Zod schemas.
- */
-// 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());
-/**
- * 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 shared robust pipeline.
-            const mod = await loadModuleDefault(abs, 'getdotenv-config');
-            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;
-};
-/**
- * Utility primarily for tests: create a file: URL string from a path.
- * @param p - File path.
- */
-const toFileUrl = (p) => pathToFileURL(path.resolve(p)).toString();
-
-/**
- * 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.
- *
- * @param finalEnv - Final composed environment to validate.
- * @param sources - Resolved config sources providing `schema` and/or `requiredKeys`.
- * @returns A list of human-readable issue strings (empty when valid).
- */
-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 [];
-};
-
-export { discoverConfigFiles, loadConfigFile, resolveGetDotenvConfigSources, toFileUrl, validateEnvAgainstSources };
+export { d as discoverConfigFiles, l as loadConfigFile, r as resolveGetDotenvConfigSources, t as toFileUrl } from './chunks/loader-CePOf74i.mjs';
+export { v as validateEnvAgainstSources } from './chunks/validate-CDl0rE6k.mjs';
+import 'fs-extra';
+import 'package-directory';
+import 'path';
+import 'url';
+import 'yaml';
+import 'zod';
+import 'node:path';
+import './chunks/loadModuleDefault-Dj8B3Stt.mjs';
+import 'crypto';