@karmaniverous/get-dotenv 6.2.4 → 6.4.0

package/dist/cliHost.mjs

@@ -1,20 +1,21 @@
-export { G as GetDotenvCli, d as definePlugin, r as readMergedOptions } from './chunks/readMergedOptions-Nt0TR7dX.mjs';
-export { b as buildSpawnEnv, c as resolveCommand, d as resolveShell, r as runCommand, a as runCommandResult, s as shouldCapture } from './chunks/spawnEnv-CN8a7cNR.mjs';
-export { b as baseGetDotenvCliOptions, r as resolveCliOptions } from './chunks/resolveCliOptions-TFRzhB2c.mjs';
-export { d as defineScripts, g as groupPlugins } from './chunks/types-DJ-BGABd.mjs';
+export { G as GetDotenvCli, d as definePlugin, r as readMergedOptions } from './chunks/readMergedOptions-B7VdLROn.mjs';
+export { d as buildSpawnEnv, b as resolveCommand, c as resolveShell, r as runCommand, a as runCommandResult, s as shouldCapture } from './chunks/spawnEnv-CQwFu7ZJ.mjs';
+export { b as baseGetDotenvCliOptions, r as resolveCliOptions } from './chunks/resolveCliOptions-pgUXHJtj.mjs';
+export { d as defineScripts, g as groupPlugins } from './chunks/types-CVDR-Sjk.mjs';
 export { t as toHelpConfig } from './chunks/helpConfig-CGejgwWW.mjs';
 export { c as composeNestedEnv, m as maybePreserveNodeEvalArgv, s as stripOne } from './chunks/invoke-DuRPU1oC.mjs';
 export { z } from 'zod';
 import '@commander-js/extra-typings';
-import './chunks/overlayEnv-Bs2kVayG.mjs';
+import './chunks/readDotenvCascade-DfFkWMjs.mjs';
 import 'fs-extra';
+import 'node:path';
 import './chunks/loadModuleDefault-Dj8B3Stt.mjs';
 import 'crypto';
 import 'path';
 import 'url';
-import 'nanoid';
 import 'dotenv';
-import './chunks/loader-DnhPeGfq.mjs';
+import 'nanoid';
+import './chunks/loader-CePOf74i.mjs';
 import 'package-directory';
 import 'yaml';
 import 'execa';

package/dist/config.mjs

@@ -1,4 +1,4 @@
-export { d as discoverConfigFiles, l as loadConfigFile, r as resolveGetDotenvConfigSources, t as toFileUrl } from './chunks/loader-DnhPeGfq.mjs';
+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';
@@ -6,5 +6,6 @@ import 'path';
 import 'url';
 import 'yaml';
 import 'zod';
+import 'node:path';
 import './chunks/loadModuleDefault-Dj8B3Stt.mjs';
 import 'crypto';

package/dist/env-overlay.d.ts

@@ -180,6 +180,150 @@ type GetDotenvDynamicFunction = (vars: ProcessEnv, env: string | undefined) => s
  */
 type GetDotenvDynamic = Record<string, GetDotenvDynamicFunction | ReturnType<GetDotenvDynamicFunction>>;
 
+/**
+ * Dotenv provenance model (descriptor-only).
+ *
+ * Requirements addressed:
+ * - Host ctx carries a dotenv provenance mapping describing per-key origin and override history.
+ * - Provenance is descriptor-only (no value payloads).
+ * - Provenance is an ordered stack per key in ascending precedence; the last entry is effective.
+ * - Explicit unsets are represented as `op: 'unset'` without requiring deletion of keys from the env map.
+ */
+/**
+ * Provenance kind for an entry in {@link DotenvProvenance}.
+ *
+ * @public
+ */
+type DotenvProvenanceKind = 'file' | 'config' | 'vars' | 'dynamic';
+/**
+ * Operation represented by a provenance entry.
+ *
+ * @public
+ */
+type DotenvProvenanceOp = 'set' | 'unset';
+/**
+ * Base shape for all provenance entries.
+ *
+ * @public
+ */
+interface DotenvProvenanceEntryBase {
+    /**
+     * The kind of provenance entry.
+     */
+    kind: DotenvProvenanceKind;
+    /**
+     * The operation applied at this layer.
+     */
+    op: DotenvProvenanceOp;
+}
+/**
+ * Provenance entry representing a value sourced from a dotenv file in the cascade.
+ *
+ * @public
+ */
+interface DotenvFileProvenanceEntry extends DotenvProvenanceEntryBase {
+    /** Discriminator. */
+    kind: 'file';
+    /** Global vs env-scoped file. */
+    scope: 'global' | 'env';
+    /** Public vs private file. */
+    privacy: 'public' | 'private';
+    /** Environment name (required when scope is `env`). */
+    env?: string;
+    /**
+     * The corresponding `paths[]` entry as provided by the caller/CLI.
+     * This is not an absolute path by policy.
+     */
+    path: string;
+    /**
+     * The computed dotenv filename token (e.g., `.env`, `.env.dev`, `.env.local`, `.env.dev.local`).
+     */
+    file: string;
+}
+/**
+ * Provenance entry representing a value sourced from config overlays (`vars` / `envVars`).
+ *
+ * @public
+ */
+interface DotenvConfigProvenanceEntry extends DotenvProvenanceEntryBase {
+    /** Discriminator. */
+    kind: 'config';
+    /** Global vs env-scoped config slice. */
+    scope: 'global' | 'env';
+    /** Public vs private on the privacy axis (`local` config maps to `private`). */
+    privacy: 'public' | 'private';
+    /** Environment name (required when scope is `env`). */
+    env?: string;
+    /** Packaged vs project config origin. */
+    configScope: 'packaged' | 'project';
+    /** Public vs local config file. */
+    configPrivacy: 'public' | 'local';
+}
+/**
+ * Provenance entry representing explicit variables overrides.
+ *
+ * Notes:
+ * - This kind represents values injected via `vars` (CLI/programmatic), not dotenv files.
+ *
+ * @public
+ */
+interface DotenvVarsProvenanceEntry extends DotenvProvenanceEntryBase {
+    /** Discriminator. */
+    kind: 'vars';
+}
+/**
+ * Source tier for dynamic variables.
+ *
+ * @public
+ */
+type DotenvDynamicSource = 'config' | 'programmatic' | 'dynamicPath';
+/**
+ * Provenance entry representing dynamic variables.
+ *
+ * @public
+ */
+interface DotenvDynamicProvenanceEntry extends DotenvProvenanceEntryBase {
+    /** Discriminator. */
+    kind: 'dynamic';
+    /** Dynamic source tier. */
+    dynamicSource: DotenvDynamicSource;
+    /**
+     * The `dynamicPath` value as provided by the caller/CLI when `dynamicSource` is `dynamicPath`.
+     * This is not resolved to an absolute path by provenance policy.
+     */
+    dynamicPath?: string;
+}
+/**
+ * Union of all supported provenance entry shapes.
+ *
+ * @public
+ */
+type DotenvProvenanceEntry = DotenvFileProvenanceEntry | DotenvConfigProvenanceEntry | DotenvVarsProvenanceEntry | DotenvDynamicProvenanceEntry;
+/**
+ * Per-key provenance history.
+ *
+ * Each key maps to an array of entries ordered in ascending precedence (lower to higher).
+ *
+ * @public
+ */
+type DotenvProvenance = Record<string, DotenvProvenanceEntry[]>;
+/**
+ * Create an empty provenance map.
+ *
+ * @public
+ */
+declare function createDotenvProvenance(): DotenvProvenance;
+/**
+ * Append a provenance entry for a key.
+ *
+ * @param prov - Provenance map to mutate.
+ * @param key - Variable name.
+ * @param entry - Descriptor-only provenance entry.
+ *
+ * @public
+ */
+declare function pushDotenvProvenance(prov: DotenvProvenance, key: string, entry: DotenvProvenanceEntry): void;
+
 /**
  * Apply a dynamic map to the target progressively.
  * - Functions receive (target, env) and may return string | undefined.
@@ -191,6 +335,42 @@ type GetDotenvDynamic = Record<string, GetDotenvDynamicFunction | ReturnType<Get
  * @returns Nothing.
  */
 declare function applyDynamicMap(target: ProcessEnv, map?: GetDotenvDynamic, env?: string): void;
+/**
+ * Load a default-export dynamic map from a JS/TS file (without applying it).
+ *
+ * Uses util/loadModuleDefault for robust TS handling (direct import, esbuild,
+ * typescript.transpile fallback).
+ *
+ * Error behavior:
+ * - On failure to load/compile/evaluate the module, throws a unified message:
+ *   "Unable to load dynamic TypeScript file: <absPath>. Install 'esbuild'..."
+ *
+ * @param absPath - Absolute path to the dynamic module file.
+ * @param cacheDirName - Cache subdirectory under `.tsbuild/` for compiled artifacts.
+ * @returns A `Promise\<GetDotenvDynamic | undefined\>` resolving to the module default export (if present).
+ *
+ * @public
+ */
+declare function loadDynamicModuleDefault(absPath: string, cacheDirName: string): Promise<GetDotenvDynamic | undefined>;
+/**
+ * Apply a dynamic map and append provenance entries per key.
+ *
+ * Requirements addressed:
+ * - Dynamic provenance entries record `dynamicSource` and optional `dynamicPath` (as provided).
+ * - Record `op: 'unset'` when the dynamic evaluation yields `undefined`.
+ *
+ * @param target - Mutable env map to assign into.
+ * @param map - Dynamic map (functions and/or literals).
+ * @param env - Selected environment name (if any).
+ * @param prov - Provenance map to append into.
+ * @param meta - Dynamic provenance metadata (source tier and optional dynamicPath).
+ *
+ * @public
+ */
+declare function applyDynamicMapWithProvenance(target: ProcessEnv, map: GetDotenvDynamic | undefined, env: string | undefined, prov: DotenvProvenance, meta: {
+    dynamicSource: DotenvDynamicSource;
+    dynamicPath?: string;
+}): void;
 /**
  * Load a default-export dynamic map from a JS/TS file and apply it.
  * Uses util/loadModuleDefault for robust TS handling (direct import, esbuild,
@@ -273,5 +453,127 @@ declare function overlayEnv<B extends ProcessEnv | Readonly<Record<string, strin
     programmaticVars: P;
 }): B & P;
 
-export { applyDynamicMap, loadAndApplyDynamic, overlayEnv };
-export type { OverlayConfigSources, OverlayEnvOptionsBase, OverlayEnvOptionsWithProgrammatic };
+/**
+ * Overlay config-provided values onto a base env while recording provenance.
+ *
+ * Requirements addressed:
+ * - Provenance entries for `kind: 'config'` include scope/privacy/env/configScope/configPrivacy.
+ * - Provenance entries for `kind: 'vars'` represent explicit vars overlays.
+ * - Provenance is recorded as layers are applied (no post-hoc reconstruction).
+ * - Record `op: 'unset'` when a layer writes an undefined result (e.g., expansion yields empty).
+ */
+
+/**
+ * Input options for {@link overlayEnvWithProvenance}.
+ *
+ * @public
+ */
+interface OverlayEnvWithProvenanceArgs {
+    /**
+     * Base environment variables.
+     */
+    base: ProcessEnv | Readonly<Record<string, string | undefined>>;
+    /**
+     * Target environment name.
+     */
+    env: string | undefined;
+    /**
+     * Configuration sources to overlay.
+     */
+    configs: OverlayConfigSources;
+    /**
+     * Explicit vars overlays applied at the highest static precedence tier.
+     */
+    programmaticVars?: ProcessEnv | Readonly<Record<string, string | undefined>>;
+    /**
+     * Existing provenance map to append into. When omitted, a new map is created.
+     */
+    provenance?: DotenvProvenance;
+}
+/**
+ * Output of {@link overlayEnvWithProvenance}.
+ *
+ * @public
+ */
+interface OverlayEnvWithProvenanceResult {
+    /**
+     * The overlaid environment.
+     */
+    env: ProcessEnv;
+    /**
+     * Provenance history for keys affected by overlays.
+     */
+    provenance: DotenvProvenance;
+}
+/**
+ * Overlay config-provided values onto a base ProcessEnv using precedence axes:
+ * - kind: env \> global
+ * - privacy: local \> public
+ * - source: project \> packaged \> base
+ *
+ * Programmatic explicit vars override all config slices.
+ *
+ * @param args - Overlay inputs.
+ * @returns The overlaid env and the updated provenance mapping.
+ *
+ * @public
+ */
+declare function overlayEnvWithProvenance(args: OverlayEnvWithProvenanceArgs): OverlayEnvWithProvenanceResult;
+
+/**
+ * Read dotenv files from the deterministic cascade and record provenance.
+ *
+ * Requirements addressed:
+ * - Provenance entries for `kind: 'file'` include scope/privacy/env/path/file (descriptor-only).
+ * - Provenance is ordered in ascending precedence as layers are applied.
+ * - Uses the same file naming convention as get-dotenv (public/private × global/env).
+ */
+
+/**
+ * Inputs for reading the dotenv cascade with provenance.
+ *
+ * @public
+ */
+interface ReadDotenvCascadeArgs {
+    /** Base dotenv filename token (default `.env`). */
+    dotenvToken?: string;
+    /** Private token suffix (default `local`). */
+    privateToken?: string;
+    /** Ordered search paths (directories). */
+    paths: string[];
+    /** Selected env name (used for env-scoped files). */
+    env?: string;
+    /** Default env name (used when `env` is not provided). */
+    defaultEnv?: string;
+    /** Exclude env-scoped files. */
+    excludeEnv?: boolean;
+    /** Exclude global files. */
+    excludeGlobal?: boolean;
+    /** Exclude private files. */
+    excludePrivate?: boolean;
+    /** Exclude public files. */
+    excludePublic?: boolean;
+}
+/**
+ * Result of reading the dotenv cascade with provenance.
+ *
+ * @public
+ */
+interface ReadDotenvCascadeResult {
+    /** Expanded dotenv map composed from file sources only. */
+    dotenv: ProcessEnv;
+    /** File-only provenance history for keys in {@link ReadDotenvCascadeResult.dotenv}. */
+    provenance: DotenvProvenance;
+}
+/**
+ * Read and expand dotenv vars from the deterministic file cascade, recording file provenance.
+ *
+ * @param args - Cascade selector options (tokens/paths/excludes/env).
+ * @returns Expanded dotenv and provenance.
+ *
+ * @public
+ */
+declare function readDotenvCascadeWithProvenance(args: ReadDotenvCascadeArgs): Promise<ReadDotenvCascadeResult>;
+
+export { applyDynamicMap, applyDynamicMapWithProvenance, createDotenvProvenance, loadAndApplyDynamic, loadDynamicModuleDefault, overlayEnv, overlayEnvWithProvenance, pushDotenvProvenance, readDotenvCascadeWithProvenance };
+export type { DotenvConfigProvenanceEntry, DotenvDynamicProvenanceEntry, DotenvDynamicSource, DotenvFileProvenanceEntry, DotenvProvenance, DotenvProvenanceEntry, DotenvProvenanceEntryBase, DotenvProvenanceKind, DotenvProvenanceOp, DotenvVarsProvenanceEntry, OverlayConfigSources, OverlayEnvOptionsBase, OverlayEnvOptionsWithProgrammatic, OverlayEnvWithProvenanceArgs, OverlayEnvWithProvenanceResult, ReadDotenvCascadeArgs, ReadDotenvCascadeResult };

package/dist/env-overlay.mjs

@@ -1,6 +1,43 @@
-export { c as applyDynamicMap, l as loadAndApplyDynamic, o as overlayEnv } from './chunks/overlayEnv-Bs2kVayG.mjs';
+import { d as dotenvExpandAll } from './chunks/readDotenvCascade-DfFkWMjs.mjs';
+export { a as applyDynamicMap, b as applyDynamicMapWithProvenance, e as createDotenvProvenance, c as loadAndApplyDynamic, l as loadDynamicModuleDefault, o as overlayEnvWithProvenance, p as pushDotenvProvenance, r as readDotenvCascadeWithProvenance } from './chunks/readDotenvCascade-DfFkWMjs.mjs';
 import 'fs-extra';
+import 'node:path';
 import './chunks/loadModuleDefault-Dj8B3Stt.mjs';
 import 'crypto';
 import 'path';
 import 'url';
+import 'dotenv';
+
+const applyKv = (current, kv) => {
+    if (!kv || Object.keys(kv).length === 0)
+        return current;
+    const expanded = dotenvExpandAll(kv, { ref: current, progressive: true });
+    return { ...current, ...expanded };
+};
+const applyConfigSlice = (current, cfg, env) => {
+    if (!cfg)
+        return current;
+    // kind axis: global then env (env overrides global)
+    const afterGlobal = applyKv(current, cfg.vars);
+    const envKv = env && cfg.envVars ? cfg.envVars[env] : undefined;
+    return applyKv(afterGlobal, envKv);
+};
+function overlayEnv(args) {
+    const { base, env, configs } = args;
+    let current = { ...base };
+    // Source: packaged (public -> local)
+    current = applyConfigSlice(current, configs.packaged, env);
+    // Packaged "local" is not expected by policy; if present, honor it.
+    // We do not have a separate object for packaged.local in sources, keep as-is.
+    // Source: project (public -> local)
+    current = applyConfigSlice(current, configs.project?.public, env);
+    current = applyConfigSlice(current, configs.project?.local, env);
+    // Programmatic explicit vars (top of static tier)
+    if ('programmaticVars' in args) {
+        const toApply = Object.fromEntries(Object.entries(args.programmaticVars).filter(([_k, v]) => typeof v === 'string'));
+        current = applyKv(current, toApply);
+    }
+    return current;
+}
+
+export { overlayEnv };

package/dist/getdotenv.cli.mjs

@@ -1,26 +1,27 @@
 #!/usr/bin/env node
-import { c as createCli } from './chunks/createCli-BY6_cfZr.mjs';
+import { c as createCli } from './chunks/createCli-BnRdfRRL.mjs';
 import 'zod';
 import 'path';
-import './chunks/loader-DnhPeGfq.mjs';
+import './chunks/loader-CePOf74i.mjs';
 import 'fs-extra';
 import 'package-directory';
 import 'url';
 import 'yaml';
+import 'node:path';
 import './chunks/loadModuleDefault-Dj8B3Stt.mjs';
 import 'crypto';
-import './chunks/readMergedOptions-Nt0TR7dX.mjs';
-import '@commander-js/extra-typings';
-import './chunks/overlayEnv-Bs2kVayG.mjs';
 import 'nanoid';
+import './chunks/readMergedOptions-B7VdLROn.mjs';
+import '@commander-js/extra-typings';
+import './chunks/readDotenvCascade-DfFkWMjs.mjs';
 import 'dotenv';
 import 'execa';
 import './chunks/helpConfig-CGejgwWW.mjs';
-import './chunks/resolveCliOptions-TFRzhB2c.mjs';
+import './chunks/resolveCliOptions-pgUXHJtj.mjs';
 import './chunks/validate-CDl0rE6k.mjs';
 import './plugins-aws.mjs';
-import './chunks/spawnEnv-CN8a7cNR.mjs';
-import './chunks/index-CeCufHlm.mjs';
+import './chunks/spawnEnv-CQwFu7ZJ.mjs';
+import './chunks/index-70Dm0f1N.mjs';
 import 'buffer';
 import 'os';
 import 'node:fs/promises';
@@ -32,11 +33,10 @@ import 'node:fs';
 import './plugins-batch.mjs';
 import './chunks/invoke-DuRPU1oC.mjs';
 import 'globby';
-import './chunks/index-Bc3h0a95.mjs';
+import './chunks/index-r0Me7-sT.mjs';
 import './plugins-init.mjs';
 import 'node:process';
 import 'readline/promises';
-import 'node:path';
 import 'node:url';
 
 // Delegate to the canonical host factory.