@karmaniverous/get-dotenv 6.3.0 → 6.4.0

package/dist/index.d.ts

@@ -2,6 +2,218 @@ import { z, ZodObject } from 'zod';
 export { z } from 'zod';
 import { OptionValues, Command, InferCommandArguments, Option, CommandUnknownOpts } from '@commander-js/extra-typings';
 
+/**
+ * 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[]>;
+
+/**
+ * Resolved CLI options schema.
+ * For the current step this mirrors the RAW schema; later stages may further
+ * narrow types post-resolution in the host pipeline.
+ */
+/**
+ * CLI options schema (resolved).
+ *
+ * Today this mirrors {@link getDotenvCliOptionsSchemaRaw}, but is kept as a distinct export
+ * so future resolution steps can narrow or materialize defaults without breaking the API.
+ *
+ * @public
+ */
+declare const getDotenvCliOptionsSchemaResolved: z.ZodObject<{
+    defaultEnv: z.ZodOptional<z.ZodString>;
+    dotenvToken: z.ZodOptional<z.ZodString>;
+    dynamicPath: z.ZodOptional<z.ZodString>;
+    dynamic: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    env: z.ZodOptional<z.ZodString>;
+    excludeDynamic: z.ZodOptional<z.ZodBoolean>;
+    excludeEnv: z.ZodOptional<z.ZodBoolean>;
+    excludeGlobal: z.ZodOptional<z.ZodBoolean>;
+    excludePrivate: z.ZodOptional<z.ZodBoolean>;
+    excludePublic: z.ZodOptional<z.ZodBoolean>;
+    loadProcess: z.ZodOptional<z.ZodBoolean>;
+    log: z.ZodOptional<z.ZodBoolean>;
+    logger: z.ZodDefault<z.ZodUnknown>;
+    outputPath: z.ZodOptional<z.ZodString>;
+    privateToken: z.ZodOptional<z.ZodString>;
+    debug: z.ZodOptional<z.ZodBoolean>;
+    strict: z.ZodOptional<z.ZodBoolean>;
+    capture: z.ZodOptional<z.ZodBoolean>;
+    trace: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodArray<z.ZodString>]>>;
+    redact: z.ZodOptional<z.ZodBoolean>;
+    warnEntropy: z.ZodOptional<z.ZodBoolean>;
+    entropyThreshold: z.ZodOptional<z.ZodNumber>;
+    entropyMinLength: z.ZodOptional<z.ZodNumber>;
+    entropyWhitelist: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    redactPatterns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    paths: z.ZodOptional<z.ZodString>;
+    pathsDelimiter: z.ZodOptional<z.ZodString>;
+    pathsDelimiterPattern: z.ZodOptional<z.ZodString>;
+    scripts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    shell: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+    vars: z.ZodOptional<z.ZodString>;
+    varsAssignor: z.ZodOptional<z.ZodString>;
+    varsAssignorPattern: z.ZodOptional<z.ZodString>;
+    varsDelimiter: z.ZodOptional<z.ZodString>;
+    varsDelimiterPattern: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+
+/**
+ * Resolved programmatic options schema (post-inheritance).
+ * For now, this mirrors the RAW schema; future stages may materialize defaults
+ * and narrow shapes as resolution is wired into the host.
+ */
+/**
+ * Programmatic options schema (resolved).
+ *
+ * Today this mirrors {@link getDotenvOptionsSchemaRaw}, but is kept as a distinct export
+ * so future resolution steps can narrow or materialize defaults without breaking the API.
+ *
+ * @public
+ */
+declare const getDotenvOptionsSchemaResolved: z.ZodObject<{
+    defaultEnv: z.ZodOptional<z.ZodString>;
+    dotenvToken: z.ZodOptional<z.ZodString>;
+    dynamicPath: z.ZodOptional<z.ZodString>;
+    dynamic: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    env: z.ZodOptional<z.ZodString>;
+    excludeDynamic: z.ZodOptional<z.ZodBoolean>;
+    excludeEnv: z.ZodOptional<z.ZodBoolean>;
+    excludeGlobal: z.ZodOptional<z.ZodBoolean>;
+    excludePrivate: z.ZodOptional<z.ZodBoolean>;
+    excludePublic: z.ZodOptional<z.ZodBoolean>;
+    loadProcess: z.ZodOptional<z.ZodBoolean>;
+    log: z.ZodOptional<z.ZodBoolean>;
+    logger: z.ZodDefault<z.ZodUnknown>;
+    outputPath: z.ZodOptional<z.ZodString>;
+    paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    privateToken: z.ZodOptional<z.ZodString>;
+    vars: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodOptional<z.ZodString>>>;
+}, z.core.$strip>;
+
 /**
  * Minimal root options shape shared by CLI and generator layers.
  * Keep keys optional to respect exactOptionalPropertyTypes semantics.
@@ -121,6 +333,12 @@ interface GetDotenvCliCtx<TOptions extends GetDotenvOptions = GetDotenvOptions>
      * Final composed dotenv environment for this invocation.
      */
     dotenv: ProcessEnv;
+    /**
+     * Dotenv provenance history for {@link GetDotenvCliCtx.dotenv}.
+     *
+     * Descriptor-only: does not include value payloads.
+     */
+    dotenvProvenance: DotenvProvenance;
     /**
      * Optional runtime plugin state bag. Plugins may publish non-sensitive metadata here.
      */
@@ -148,90 +366,6 @@ interface BrandOptions {
     helpHeader?: string;
 }
 
-/**
- * Resolved CLI options schema.
- * For the current step this mirrors the RAW schema; later stages may further
- * narrow types post-resolution in the host pipeline.
- */
-/**
- * CLI options schema (resolved).
- *
- * Today this mirrors {@link getDotenvCliOptionsSchemaRaw}, but is kept as a distinct export
- * so future resolution steps can narrow or materialize defaults without breaking the API.
- *
- * @public
- */
-declare const getDotenvCliOptionsSchemaResolved: z.ZodObject<{
-    defaultEnv: z.ZodOptional<z.ZodString>;
-    dotenvToken: z.ZodOptional<z.ZodString>;
-    dynamicPath: z.ZodOptional<z.ZodString>;
-    dynamic: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    env: z.ZodOptional<z.ZodString>;
-    excludeDynamic: z.ZodOptional<z.ZodBoolean>;
-    excludeEnv: z.ZodOptional<z.ZodBoolean>;
-    excludeGlobal: z.ZodOptional<z.ZodBoolean>;
-    excludePrivate: z.ZodOptional<z.ZodBoolean>;
-    excludePublic: z.ZodOptional<z.ZodBoolean>;
-    loadProcess: z.ZodOptional<z.ZodBoolean>;
-    log: z.ZodOptional<z.ZodBoolean>;
-    logger: z.ZodDefault<z.ZodUnknown>;
-    outputPath: z.ZodOptional<z.ZodString>;
-    privateToken: z.ZodOptional<z.ZodString>;
-    debug: z.ZodOptional<z.ZodBoolean>;
-    strict: z.ZodOptional<z.ZodBoolean>;
-    capture: z.ZodOptional<z.ZodBoolean>;
-    trace: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodArray<z.ZodString>]>>;
-    redact: z.ZodOptional<z.ZodBoolean>;
-    warnEntropy: z.ZodOptional<z.ZodBoolean>;
-    entropyThreshold: z.ZodOptional<z.ZodNumber>;
-    entropyMinLength: z.ZodOptional<z.ZodNumber>;
-    entropyWhitelist: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    redactPatterns: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    paths: z.ZodOptional<z.ZodString>;
-    pathsDelimiter: z.ZodOptional<z.ZodString>;
-    pathsDelimiterPattern: z.ZodOptional<z.ZodString>;
-    scripts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    shell: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
-    vars: z.ZodOptional<z.ZodString>;
-    varsAssignor: z.ZodOptional<z.ZodString>;
-    varsAssignorPattern: z.ZodOptional<z.ZodString>;
-    varsDelimiter: z.ZodOptional<z.ZodString>;
-    varsDelimiterPattern: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-
-/**
- * Resolved programmatic options schema (post-inheritance).
- * For now, this mirrors the RAW schema; future stages may materialize defaults
- * and narrow shapes as resolution is wired into the host.
- */
-/**
- * Programmatic options schema (resolved).
- *
- * Today this mirrors {@link getDotenvOptionsSchemaRaw}, but is kept as a distinct export
- * so future resolution steps can narrow or materialize defaults without breaking the API.
- *
- * @public
- */
-declare const getDotenvOptionsSchemaResolved: z.ZodObject<{
-    defaultEnv: z.ZodOptional<z.ZodString>;
-    dotenvToken: z.ZodOptional<z.ZodString>;
-    dynamicPath: z.ZodOptional<z.ZodString>;
-    dynamic: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    env: z.ZodOptional<z.ZodString>;
-    excludeDynamic: z.ZodOptional<z.ZodBoolean>;
-    excludeEnv: z.ZodOptional<z.ZodBoolean>;
-    excludeGlobal: z.ZodOptional<z.ZodBoolean>;
-    excludePrivate: z.ZodOptional<z.ZodBoolean>;
-    excludePublic: z.ZodOptional<z.ZodBoolean>;
-    loadProcess: z.ZodOptional<z.ZodBoolean>;
-    log: z.ZodOptional<z.ZodBoolean>;
-    logger: z.ZodDefault<z.ZodUnknown>;
-    outputPath: z.ZodOptional<z.ZodString>;
-    paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    privateToken: z.ZodOptional<z.ZodString>;
-    vars: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodOptional<z.ZodString>>>;
-}, z.core.$strip>;
-
 /**
  * Canonical programmatic options and helpers for get-dotenv.
  *

package/dist/index.mjs

@@ -1,28 +1,31 @@
-export { c as createCli } from './chunks/createCli-BSn6Be40.mjs';
-export { G as GetDotenvCli, b as baseRootOptionDefaults, e as defineDynamic, f as defineGetDotenvConfig, d as definePlugin, h as getDotenv, g as getDotenvCliOptions2Options, k as interpolateDeep, m as maybeWarnEntropy, r as readMergedOptions, i as redactDisplay, j as redactObject } from './chunks/readMergedOptions-DLBDzpXX.mjs';
+export { c as createCli } from './chunks/createCli-BnRdfRRL.mjs';
+import { e as resolveGetDotenvOptions, w as writeDotenvFile } from './chunks/readMergedOptions-B7VdLROn.mjs';
+export { G as GetDotenvCli, b as baseRootOptionDefaults, f as defineDynamic, h as defineGetDotenvConfig, d as definePlugin, g as getDotenvCliOptions2Options, i as interpolateDeep, r as readMergedOptions } from './chunks/readMergedOptions-B7VdLROn.mjs';
 export { d as buildSpawnEnv, s as shouldCapture } from './chunks/spawnEnv-CQwFu7ZJ.mjs';
-export { d as defineScripts, g as groupPlugins } from './chunks/types-DdqcXCV1.mjs';
+export { d as defineScripts, g as groupPlugins } from './chunks/types-CVDR-Sjk.mjs';
 import fs from 'fs-extra';
 import 'crypto';
-import 'path';
+import path$1 from 'path';
 import 'url';
 export { z } from 'zod';
-import 'dotenv';
-export { t as traceChildEnv } from './chunks/index-BqZ3PB6c.mjs';
-export { d as dotenvExpand, b as dotenvExpandAll, c as dotenvExpandFromProcessEnv } from './chunks/overlayEnv-Bqh_kPGA.mjs';
+import { nanoid } from 'nanoid';
+import { r as redactObject, m as maybeWarnEntropy } from './chunks/index-r0Me7-sT.mjs';
+export { a as redactDisplay, t as traceChildEnv } from './chunks/index-r0Me7-sT.mjs';
+import { f as readDotenv, d as dotenvExpandAll, a as applyDynamicMap, c as loadAndApplyDynamic } from './chunks/readDotenvCascade-DfFkWMjs.mjs';
+export { g as dotenvExpand, h as dotenvExpandFromProcessEnv } from './chunks/readDotenvCascade-DfFkWMjs.mjs';
 import path from 'node:path';
+import 'dotenv';
 import './chunks/loader-CePOf74i.mjs';
 import 'package-directory';
 import 'yaml';
 import './chunks/loadModuleDefault-Dj8B3Stt.mjs';
-import 'nanoid';
 import 'execa';
 import './chunks/helpConfig-CGejgwWW.mjs';
-import './chunks/resolveCliOptions-_qtsVxda.mjs';
+import './chunks/resolveCliOptions-pgUXHJtj.mjs';
 import './chunks/validate-CDl0rE6k.mjs';
 import './plugins-aws.mjs';
 import '@commander-js/extra-typings';
-import './chunks/index-BNcKuiBy.mjs';
+import './chunks/index-70Dm0f1N.mjs';
 import 'buffer';
 import 'os';
 import 'node:fs/promises';
@@ -620,56 +623,100 @@ function editDotenvText(text, updates, options = {}) {
 }
 
 /**
- * FS-level dotenv editor adapter (target resolution + template bootstrap).
+ * @packageDocumentation
+ * Deterministic dotenv target selection across a multi-path cascade.
  *
- * Requirements addressed:
- * - Deterministic target selection across getdotenv `paths` only.
- * - Scope axis (global|env) × privacy axis (public|private).
- * - Template bootstrap: copy `<target>.<templateExtension>` to `<target>` when needed.
- * - Edit in place while preserving formatting via the pure text editor.
+ * This module extracts the “which file should we edit?” logic from the FS-level editor
+ * so plugins/tools can reuse the same selection semantics as {@link editDotenvFile}.
  *
- * @packageDocumentation
+ * Notes:
+ * - Selection is based on `paths` only (directories), consistent with get-dotenv overlay precedence.
+ * - Default search order is reverse (last path wins).
+ * - Template discovery is supported via `<target>.<templateExtension>` and returns the template path
+ *   when the concrete target is missing.
  */
-const defaultFs = {
-    pathExists: async (p) => fs.pathExists(p),
-    readFile: async (p) => fs.readFile(p, 'utf-8'),
-    writeFile: async (p, contents) => fs.writeFile(p, contents, 'utf-8'),
-    copyFile: async (src, dest) => fs.copyFile(src, dest),
-};
 const resolveEnvName = (env, defaultEnv) => typeof env === 'string' && env.length > 0
     ? env
     : typeof defaultEnv === 'string' && defaultEnv.length > 0
         ? defaultEnv
         : undefined;
-const buildTargetFilename = (opts) => {
-    const { dotenvToken, privateToken, scope, privacy, envName } = opts;
+/**
+ * Build the dotenv filename for a selector (scope × privacy) using the same naming
+ * convention as get-dotenv.
+ *
+ * @param opts - Filename selector options.
+ * @returns The filename token (for example, `.env.dev.local`).
+ * @throws Error when `scope` is `'env'` and neither `env` nor `defaultEnv` is provided.
+ *
+ * @public
+ */
+function buildDotenvTargetFilename(opts) {
+    const dotenvToken = opts.dotenvToken ?? '.env';
+    const privateToken = opts.privateToken ?? 'local';
+    const envName = resolveEnvName(opts.env, opts.defaultEnv);
     const parts = [dotenvToken];
-    if (scope === 'env') {
+    if (opts.scope === 'env') {
         if (!envName) {
             throw new Error(`Unable to resolve env-scoped dotenv filename: env is required.`);
         }
         parts.push(envName);
     }
-    if (privacy === 'private')
+    if (opts.privacy === 'private')
         parts.push(privateToken);
     return parts.join('.');
-};
+}
 const orderedPaths = (pathsIn, order) => {
     const list = pathsIn.slice();
     return order === 'forward' ? list : list.reverse();
 };
-const resolveTargetAcrossPaths = async (fsPort, opts) => {
-    const { filename, templateExtension, searchOrder } = opts;
+/**
+ * Resolve a deterministic dotenv target across `paths` based on scope/privacy selectors.
+ *
+ * Selection rules:
+ * - Iterates `paths` in the requested search order.
+ * - Returns the first existing target file.
+ * - Otherwise, returns the first sibling template file (`<target>.<templateExtension>`) when present.
+ * - Throws when neither a target nor a template exists anywhere under `paths`.
+ *
+ * @param opts - Resolver options (paths + selector + fs port).
+ * @returns The resolved target path and optional template path.
+ *
+ * @public
+ */
+async function resolveDotenvTarget(opts) {
+    const filename = buildDotenvTargetFilename(opts);
+    const templateExtension = opts.templateExtension ?? 'template';
+    const searchOrder = opts.searchOrder ?? 'reverse';
     const pathsOrdered = orderedPaths(opts.paths, searchOrder);
     for (const dir of pathsOrdered) {
         const targetPath = path.resolve(dir, filename);
-        if (await fsPort.pathExists(targetPath))
-            return { targetPath };
+        if (await opts.fs.pathExists(targetPath)) {
+            return { targetPath, filename };
+        }
         const templatePath = `${targetPath}.${templateExtension}`;
-        if (await fsPort.pathExists(templatePath))
-            return { targetPath, templatePath };
+        if (await opts.fs.pathExists(templatePath)) {
+            return { targetPath, templatePath, filename };
+        }
     }
     throw new Error(`Unable to locate dotenv target "${filename}" under provided paths, and no template was found.`);
+}
+
+/**
+ * FS-level dotenv editor adapter (target resolution + template bootstrap).
+ *
+ * Requirements addressed:
+ * - Deterministic target selection across getdotenv `paths` only.
+ * - Scope axis (global|env) × privacy axis (public|private).
+ * - Template bootstrap: copy `<target>.<templateExtension>` to `<target>` when needed.
+ * - Edit in place while preserving formatting via the pure text editor.
+ *
+ * @packageDocumentation
+ */
+const defaultFs = {
+    pathExists: async (p) => fs.pathExists(p),
+    readFile: async (p) => fs.readFile(p, 'utf-8'),
+    writeFile: async (p, contents) => fs.writeFile(p, contents, 'utf-8'),
+    copyFile: async (src, dest) => fs.copyFile(src, dest),
 };
 /**
  * Edit a dotenv file selected by scope/privacy across a list of search paths.
@@ -686,17 +733,19 @@ async function editDotenvFile(updates, options) {
     const privateToken = options.privateToken ?? 'local';
     const templateExtension = options.templateExtension ?? 'template';
     const searchOrder = options.searchOrder ?? 'reverse';
-    const envName = resolveEnvName(options.env, options.defaultEnv);
-    const filename = buildTargetFilename({
+    const resolved = await resolveDotenvTarget({
+        fs: fsPort,
+        paths: options.paths,
         dotenvToken,
         privateToken,
+        ...(typeof options.env === 'string' && options.env.length > 0
+            ? { env: options.env }
+            : {}),
+        ...(typeof options.defaultEnv === 'string' && options.defaultEnv.length > 0
+            ? { defaultEnv: options.defaultEnv }
+            : {}),
         scope: options.scope,
         privacy: options.privacy,
-        ...(envName ? { envName } : {}),
-    });
-    const resolved = await resolveTargetAcrossPaths(fsPort, {
-        paths: options.paths,
-        filename,
         templateExtension,
         searchOrder,
     });
@@ -729,4 +778,112 @@ async function editDotenvFile(updates, options) {
     return { path: resolved.targetPath, createdFromTemplate, changed };
 }
 
-export { applyDotenvEdits, editDotenvFile, editDotenvText, parseDotenvDocument, renderDotenvDocument };
+async function getDotenv(options = {}) {
+    // Apply defaults.
+    const { defaultEnv, dotenvToken = '.env', dynamicPath, env, excludeDynamic = false, excludeEnv = false, excludeGlobal = false, excludePrivate = false, excludePublic = false, loadProcess = false, log = false, logger = console, outputPath, paths = [], privateToken = 'local', vars = {}, } = await resolveGetDotenvOptions(options);
+    // Read .env files.
+    const loaded = paths.length
+        ? await paths.reduce(async (e, p) => {
+            const publicGlobal = excludePublic || excludeGlobal
+                ? Promise.resolve({})
+                : readDotenv(path$1.resolve(p, dotenvToken));
+            const publicEnv = excludePublic || excludeEnv || (!env && !defaultEnv)
+                ? Promise.resolve({})
+                : readDotenv(path$1.resolve(p, `${dotenvToken}.${env ?? defaultEnv ?? ''}`));
+            const privateGlobal = excludePrivate || excludeGlobal
+                ? Promise.resolve({})
+                : readDotenv(path$1.resolve(p, `${dotenvToken}.${privateToken}`));
+            const privateEnv = excludePrivate || excludeEnv || (!env && !defaultEnv)
+                ? Promise.resolve({})
+                : readDotenv(path$1.resolve(p, `${dotenvToken}.${env ?? defaultEnv ?? ''}.${privateToken}`));
+            const [eResolved, publicGlobalResolved, publicEnvResolved, privateGlobalResolved, privateEnvResolved,] = await Promise.all([
+                e,
+                publicGlobal,
+                publicEnv,
+                privateGlobal,
+                privateEnv,
+            ]);
+            return {
+                ...eResolved,
+                ...publicGlobalResolved,
+                ...publicEnvResolved,
+                ...privateGlobalResolved,
+                ...privateEnvResolved,
+            };
+        }, Promise.resolve({}))
+        : {};
+    const outputKey = nanoid();
+    const dotenv = dotenvExpandAll({
+        ...loaded,
+        ...vars,
+        ...(outputPath ? { [outputKey]: outputPath } : {}),
+    }, { progressive: true });
+    // Process dynamic variables. Programmatic option takes precedence over path.
+    if (!excludeDynamic) {
+        // A2 precedence: programmatic dynamic < dynamicPath (dynamicPath wins when present)
+        if (options.dynamic && Object.keys(options.dynamic).length > 0) {
+            try {
+                applyDynamicMap(dotenv, options.dynamic, env ?? defaultEnv);
+            }
+            catch {
+                throw new Error(`Unable to evaluate dynamic variables.`);
+            }
+        }
+        // dynamicPath is evaluated even when programmatic `dynamic` is present.
+        if (dynamicPath) {
+            const absDynamicPath = path$1.resolve(dynamicPath);
+            await loadAndApplyDynamic(dotenv, absDynamicPath, env ?? defaultEnv, 'getdotenv-dynamic');
+        }
+    }
+    // Write output file.
+    let resultDotenv = dotenv;
+    if (outputPath) {
+        const outputPathResolved = dotenv[outputKey];
+        if (!outputPathResolved)
+            throw new Error('Output path not found.');
+        const { [outputKey]: _omitted, ...dotenvForOutput } = dotenv;
+        await writeDotenvFile(outputPathResolved, dotenvForOutput);
+        resultDotenv = dotenvForOutput;
+    }
+    // Log result.
+    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;
+}
+
+export { applyDotenvEdits, dotenvExpandAll, editDotenvFile, editDotenvText, getDotenv, maybeWarnEntropy, parseDotenvDocument, redactObject, renderDotenvDocument };