@karmaniverous/get-dotenv 6.3.0 → 6.5.0

package/dist/plugins-batch.d.ts

@@ -2,41 +2,132 @@ import { OptionValues, Command, InferCommandArguments, Option } from '@commander
 import { z, ZodObject } from 'zod';
 
 /**
- * Definition for a single script entry.
+ * 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.
  */
-interface ScriptDef<TShell extends string | boolean = string | boolean> {
-    /** The command string to execute. */
-    cmd: string;
-    /** Shell override for this script. */
-    shell?: TShell | undefined;
-}
 /**
- * Scripts table shape.
+ * Provenance kind for an entry in {@link DotenvProvenance}.
+ *
+ * @public
  */
-type ScriptsTable<TShell extends string | boolean = string | boolean> = Record<string, string | ScriptDef<TShell>>;
+type DotenvProvenanceKind = 'file' | 'config' | 'vars' | 'dynamic';
 /**
- * Per-invocation context shared with plugins and actions.
+ * Operation represented by a provenance entry.
  *
  * @public
  */
-interface GetDotenvCliCtx<TOptions extends GetDotenvOptions = GetDotenvOptions> {
+type DotenvProvenanceOp = 'set' | 'unset';
+/**
+ * Base shape for all provenance entries.
+ *
+ * @public
+ */
+interface DotenvProvenanceEntryBase {
     /**
-     * Fully resolved option bag used to compute this context.
+     * The kind of provenance entry.
      */
-    optionsResolved: TOptions;
+    kind: DotenvProvenanceKind;
     /**
-     * Final composed dotenv environment for this invocation.
+     * The operation applied at this layer.
      */
-    dotenv: ProcessEnv;
+    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;
     /**
-     * Optional runtime plugin state bag. Plugins may publish non-sensitive metadata here.
+     * The corresponding `paths[]` entry as provided by the caller/CLI.
+     * This is not an absolute path by policy.
      */
-    plugins?: Record<string, unknown>;
+    path: string;
     /**
-     * Per-plugin validated configuration slices keyed by realized mount path.
+     * The computed dotenv filename token (e.g., `.env`, `.env.dev`, `.env.local`, `.env.dev.local`).
      */
-    pluginConfigs?: Record<string, unknown>;
+    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.
@@ -123,14 +214,47 @@ declare const getDotenvOptionsSchemaResolved: z.ZodObject<{
 }, z.core.$strip>;
 
 /**
- * Canonical programmatic options and helpers for get-dotenv.
+ * Definition for a single script entry.
+ */
+interface ScriptDef<TShell extends string | boolean = string | boolean> {
+    /** The command string to execute. */
+    cmd: string;
+    /** Shell override for this script. */
+    shell?: TShell | undefined;
+}
+/**
+ * Scripts table shape.
+ */
+type ScriptsTable<TShell extends string | boolean = string | boolean> = Record<string, string | ScriptDef<TShell>>;
+/**
+ * Per-invocation context shared with plugins and actions.
  *
- * Requirements addressed:
- * - GetDotenvOptions derives from the Zod schema output (single source of truth).
- * - Removed deprecated/compat flags from the public shape (e.g., useConfigLoader).
- * - Provide Vars-aware defineDynamic and a typed config builder defineGetDotenvConfig\<Vars, Env\>().
- * - Preserve existing behavior for defaults resolution and compat converters.
+ * @public
  */
+interface GetDotenvCliCtx<TOptions extends GetDotenvOptions = GetDotenvOptions> {
+    /**
+     * Fully resolved option bag used to compute this context.
+     */
+    optionsResolved: TOptions;
+    /**
+     * 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.
+     */
+    plugins?: Record<string, unknown>;
+    /**
+     * Per-plugin validated configuration slices keyed by realized mount path.
+     */
+    pluginConfigs?: Record<string, unknown>;
+}
 
 /**
  * A minimal representation of an environment key/value mapping.
@@ -426,7 +550,7 @@ interface ExecShellCommandBatchOptions {
     /**
      * Composed dotenv environment (string | undefined values) to inject into each child.
      */
-    dotenvEnv?: Record<string, string | undefined>;
+    dotenvEnv?: ProcessEnv;
     /**
      * Space‑delimited patterns used to discover target working directories.
      */

package/dist/plugins-batch.mjs

@@ -1,5 +1,7 @@
-import { r as readMergedOptions, d as definePlugin } from './chunks/readMergedOptions-DLBDzpXX.mjs';
+import { r as readMergedOptions, d as definePlugin } from './chunks/readMergedOptions-DLRFU2qO.mjs';
 import 'execa';
+import 'radash';
+import 'node:buffer';
 import 'fs-extra';
 import 'node:path';
 import 'crypto';
@@ -8,14 +10,14 @@ import 'url';
 import { Command } from '@commander-js/extra-typings';
 import 'nanoid';
 import 'dotenv';
-import './chunks/loader-CePOf74i.mjs';
+import './chunks/loader-CE4HSRN4.mjs';
 import { packageDirectory } from 'package-directory';
 import 'yaml';
 import { z } from 'zod';
 import { c as composeNestedEnv, m as maybePreserveNodeEvalArgv } from './chunks/invoke-DuRPU1oC.mjs';
-import { r as runCommand, d as buildSpawnEnv, c as resolveShell, b as resolveCommand } from './chunks/spawnEnv-CQwFu7ZJ.mjs';
+import { r as runCommand, d as buildSpawnEnv, c as resolveShell, b as resolveCommand } from './chunks/spawnEnv-5kdIVv0x.mjs';
 import { globby } from 'globby';
-import './chunks/overlayEnv-Bqh_kPGA.mjs';
+import './chunks/readDotenvCascade-Bymjvyit.mjs';
 import './chunks/loadModuleDefault-Dj8B3Stt.mjs';
 
 const globPaths = async ({ globs, logger, pkgCwd, rootPath, }) => {

package/dist/plugins-cmd.d.ts

@@ -2,41 +2,132 @@ import { OptionValues, Command, InferCommandArguments, Option } from '@commander
 import { z, ZodObject } from 'zod';
 
 /**
- * Definition for a single script entry.
+ * 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.
  */
-interface ScriptDef<TShell extends string | boolean = string | boolean> {
-    /** The command string to execute. */
-    cmd: string;
-    /** Shell override for this script. */
-    shell?: TShell | undefined;
-}
 /**
- * Scripts table shape.
+ * Provenance kind for an entry in {@link DotenvProvenance}.
+ *
+ * @public
  */
-type ScriptsTable<TShell extends string | boolean = string | boolean> = Record<string, string | ScriptDef<TShell>>;
+type DotenvProvenanceKind = 'file' | 'config' | 'vars' | 'dynamic';
 /**
- * Per-invocation context shared with plugins and actions.
+ * Operation represented by a provenance entry.
  *
  * @public
  */
-interface GetDotenvCliCtx<TOptions extends GetDotenvOptions = GetDotenvOptions> {
+type DotenvProvenanceOp = 'set' | 'unset';
+/**
+ * Base shape for all provenance entries.
+ *
+ * @public
+ */
+interface DotenvProvenanceEntryBase {
     /**
-     * Fully resolved option bag used to compute this context.
+     * The kind of provenance entry.
      */
-    optionsResolved: TOptions;
+    kind: DotenvProvenanceKind;
     /**
-     * Final composed dotenv environment for this invocation.
+     * The operation applied at this layer.
      */
-    dotenv: ProcessEnv;
+    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;
     /**
-     * Optional runtime plugin state bag. Plugins may publish non-sensitive metadata here.
+     * The corresponding `paths[]` entry as provided by the caller/CLI.
+     * This is not an absolute path by policy.
      */
-    plugins?: Record<string, unknown>;
+    path: string;
     /**
-     * Per-plugin validated configuration slices keyed by realized mount path.
+     * The computed dotenv filename token (e.g., `.env`, `.env.dev`, `.env.local`, `.env.dev.local`).
      */
-    pluginConfigs?: Record<string, unknown>;
+    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.
@@ -123,14 +214,47 @@ declare const getDotenvOptionsSchemaResolved: z.ZodObject<{
 }, z.core.$strip>;
 
 /**
- * Canonical programmatic options and helpers for get-dotenv.
+ * Definition for a single script entry.
+ */
+interface ScriptDef<TShell extends string | boolean = string | boolean> {
+    /** The command string to execute. */
+    cmd: string;
+    /** Shell override for this script. */
+    shell?: TShell | undefined;
+}
+/**
+ * Scripts table shape.
+ */
+type ScriptsTable<TShell extends string | boolean = string | boolean> = Record<string, string | ScriptDef<TShell>>;
+/**
+ * Per-invocation context shared with plugins and actions.
  *
- * Requirements addressed:
- * - GetDotenvOptions derives from the Zod schema output (single source of truth).
- * - Removed deprecated/compat flags from the public shape (e.g., useConfigLoader).
- * - Provide Vars-aware defineDynamic and a typed config builder defineGetDotenvConfig\<Vars, Env\>().
- * - Preserve existing behavior for defaults resolution and compat converters.
+ * @public
  */
+interface GetDotenvCliCtx<TOptions extends GetDotenvOptions = GetDotenvOptions> {
+    /**
+     * Fully resolved option bag used to compute this context.
+     */
+    optionsResolved: TOptions;
+    /**
+     * 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.
+     */
+    plugins?: Record<string, unknown>;
+    /**
+     * Per-plugin validated configuration slices keyed by realized mount path.
+     */
+    pluginConfigs?: Record<string, unknown>;
+}
 
 /**
  * A minimal representation of an environment key/value mapping.

package/dist/plugins-cmd.mjs

@@ -1,5 +1,7 @@
-import './chunks/readMergedOptions-DLBDzpXX.mjs';
+import 'radash';
+import './chunks/readMergedOptions-DLRFU2qO.mjs';
 import 'execa';
+import 'node:buffer';
 import 'fs-extra';
 import 'node:path';
 import 'crypto';
@@ -8,13 +10,13 @@ import 'url';
 import '@commander-js/extra-typings';
 import 'nanoid';
 import 'dotenv';
-import './chunks/loader-CePOf74i.mjs';
+import './chunks/loader-CE4HSRN4.mjs';
 import 'package-directory';
 import 'yaml';
 import 'zod';
-export { c as cmdPlugin } from './chunks/index-BqZ3PB6c.mjs';
-import './chunks/overlayEnv-Bqh_kPGA.mjs';
+export { c as cmdPlugin } from './chunks/index-BzOeGJbq.mjs';
+import './chunks/readDotenvCascade-Bymjvyit.mjs';
 import './chunks/loadModuleDefault-Dj8B3Stt.mjs';
-import './chunks/spawnEnv-CQwFu7ZJ.mjs';
+import './chunks/spawnEnv-5kdIVv0x.mjs';
 import './chunks/invoke-DuRPU1oC.mjs';
-import './chunks/resolveCliOptions-_qtsVxda.mjs';
+import './chunks/resolveCliOptions-C6oeNl9S.mjs';

package/dist/plugins-init.d.ts

@@ -2,41 +2,132 @@ import { OptionValues, Command, InferCommandArguments, Option } from '@commander
 import { z, ZodObject } from 'zod';
 
 /**
- * Definition for a single script entry.
+ * 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.
  */
-interface ScriptDef<TShell extends string | boolean = string | boolean> {
-    /** The command string to execute. */
-    cmd: string;
-    /** Shell override for this script. */
-    shell?: TShell | undefined;
-}
 /**
- * Scripts table shape.
+ * Provenance kind for an entry in {@link DotenvProvenance}.
+ *
+ * @public
  */
-type ScriptsTable<TShell extends string | boolean = string | boolean> = Record<string, string | ScriptDef<TShell>>;
+type DotenvProvenanceKind = 'file' | 'config' | 'vars' | 'dynamic';
 /**
- * Per-invocation context shared with plugins and actions.
+ * Operation represented by a provenance entry.
  *
  * @public
  */
-interface GetDotenvCliCtx<TOptions extends GetDotenvOptions = GetDotenvOptions> {
+type DotenvProvenanceOp = 'set' | 'unset';
+/**
+ * Base shape for all provenance entries.
+ *
+ * @public
+ */
+interface DotenvProvenanceEntryBase {
     /**
-     * Fully resolved option bag used to compute this context.
+     * The kind of provenance entry.
      */
-    optionsResolved: TOptions;
+    kind: DotenvProvenanceKind;
     /**
-     * Final composed dotenv environment for this invocation.
+     * The operation applied at this layer.
      */
-    dotenv: ProcessEnv;
+    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;
     /**
-     * Optional runtime plugin state bag. Plugins may publish non-sensitive metadata here.
+     * The corresponding `paths[]` entry as provided by the caller/CLI.
+     * This is not an absolute path by policy.
      */
-    plugins?: Record<string, unknown>;
+    path: string;
     /**
-     * Per-plugin validated configuration slices keyed by realized mount path.
+     * The computed dotenv filename token (e.g., `.env`, `.env.dev`, `.env.local`, `.env.dev.local`).
      */
-    pluginConfigs?: Record<string, unknown>;
+    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.
@@ -123,14 +214,47 @@ declare const getDotenvOptionsSchemaResolved: z.ZodObject<{
 }, z.core.$strip>;
 
 /**
- * Canonical programmatic options and helpers for get-dotenv.
+ * Definition for a single script entry.
+ */
+interface ScriptDef<TShell extends string | boolean = string | boolean> {
+    /** The command string to execute. */
+    cmd: string;
+    /** Shell override for this script. */
+    shell?: TShell | undefined;
+}
+/**
+ * Scripts table shape.
+ */
+type ScriptsTable<TShell extends string | boolean = string | boolean> = Record<string, string | ScriptDef<TShell>>;
+/**
+ * Per-invocation context shared with plugins and actions.
  *
- * Requirements addressed:
- * - GetDotenvOptions derives from the Zod schema output (single source of truth).
- * - Removed deprecated/compat flags from the public shape (e.g., useConfigLoader).
- * - Provide Vars-aware defineDynamic and a typed config builder defineGetDotenvConfig\<Vars, Env\>().
- * - Preserve existing behavior for defaults resolution and compat converters.
+ * @public
  */
+interface GetDotenvCliCtx<TOptions extends GetDotenvOptions = GetDotenvOptions> {
+    /**
+     * Fully resolved option bag used to compute this context.
+     */
+    optionsResolved: TOptions;
+    /**
+     * 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.
+     */
+    plugins?: Record<string, unknown>;
+    /**
+     * Per-plugin validated configuration slices keyed by realized mount path.
+     */
+    pluginConfigs?: Record<string, unknown>;
+}
 
 /**
  * A minimal representation of an environment key/value mapping.