@karmaniverous/get-dotenv 6.2.4 → 6.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/README.md +1 -0
  2. package/dist/chunks/{AwsRestJsonProtocol-Bq1HE-Ln.mjs → AwsRestJsonProtocol-fYZqn-kW.mjs} +2 -2
  3. package/dist/chunks/{createCli-BY6_cfZr.mjs → createCli-BnRdfRRL.mjs} +7 -6
  4. package/dist/chunks/{externalDataInterceptor-CbsdEYa-.mjs → externalDataInterceptor-CILOLqbB.mjs} +2 -2
  5. package/dist/chunks/{getSSOTokenFromFile-hUSpR7Wf.mjs → getSSOTokenFromFile-BwMkZ_yT.mjs} +1 -1
  6. package/dist/chunks/{index-C_wqbTwI.mjs → index-0-nP97ri.mjs} +7 -6
  7. package/dist/chunks/{index-CeCufHlm.mjs → index-70Dm0f1N.mjs} +11 -10
  8. package/dist/chunks/{index-BPYF6K_G.mjs → index-BhVOypA1.mjs} +9 -8
  9. package/dist/chunks/{index-cIunyiUQ.mjs → index-CcwT4HJK.mjs} +6 -5
  10. package/dist/chunks/{index-BpCF5UKx.mjs → index-D8UL3w94.mjs} +6 -5
  11. package/dist/chunks/{index-Cu7rdyqN.mjs → index-DLNhHC15.mjs} +9 -8
  12. package/dist/chunks/{index-Dp1Ip6Ra.mjs → index-DWqbxY8Y.mjs} +11 -10
  13. package/dist/chunks/{index-c7zKtEuy.mjs → index-Du51s-Z0.mjs} +8 -7
  14. package/dist/chunks/{index-B5JKTBOL.mjs → index-DuSz0ul6.mjs} +8 -7
  15. package/dist/chunks/{index-DWAtHEA-.mjs → index-OeNCYa8T.mjs} +6 -5
  16. package/dist/chunks/{index-DyU5pKKi.mjs → index-_FP0whjC.mjs} +6 -5
  17. package/dist/chunks/{index-BEJFiHMX.mjs → index-o5zJ9PWL.mjs} +15 -15
  18. package/dist/chunks/{index-Bc3h0a95.mjs → index-r0Me7-sT.mjs} +112 -6
  19. package/dist/chunks/{loadSso-w1eTVg0O.mjs → loadSso-CLR1fKci.mjs} +8 -7
  20. package/dist/chunks/{loader-DnhPeGfq.mjs → loader-CePOf74i.mjs} +1 -0
  21. package/dist/chunks/{parseKnownFiles-B9cDK21V.mjs → parseKnownFiles-BQvmJ0HK.mjs} +1 -1
  22. package/dist/chunks/readDotenvCascade-DfFkWMjs.mjs +546 -0
  23. package/dist/chunks/{readMergedOptions-Nt0TR7dX.mjs → readMergedOptions-B7VdLROn.mjs} +62 -272
  24. package/dist/chunks/{resolveCliOptions-TFRzhB2c.mjs → resolveCliOptions-pgUXHJtj.mjs} +2 -1
  25. package/dist/chunks/{sdk-stream-mixin-BZoJ5jy9.mjs → sdk-stream-mixin-ecbbBR0l.mjs} +1 -1
  26. package/dist/chunks/{spawnEnv-CN8a7cNR.mjs → spawnEnv-CQwFu7ZJ.mjs} +2 -1
  27. package/dist/chunks/{types-DJ-BGABd.mjs → types-CVDR-Sjk.mjs} +1 -1
  28. package/dist/cli.d.ts +218 -84
  29. package/dist/cli.mjs +10 -10
  30. package/dist/cliHost.d.ts +218 -84
  31. package/dist/cliHost.mjs +8 -7
  32. package/dist/config.mjs +2 -1
  33. package/dist/env-overlay.d.ts +304 -2
  34. package/dist/env-overlay.mjs +38 -1
  35. package/dist/getdotenv.cli.mjs +10 -10
  36. package/dist/index.d.ts +703 -86
  37. package/dist/index.mjs +862 -13
  38. package/dist/plugins-aws.d.ts +153 -19
  39. package/dist/plugins-aws.mjs +5 -4
  40. package/dist/plugins-batch.d.ts +153 -19
  41. package/dist/plugins-batch.mjs +5 -4
  42. package/dist/plugins-cmd.d.ts +153 -19
  43. package/dist/plugins-cmd.mjs +7 -6
  44. package/dist/plugins-init.d.ts +153 -19
  45. package/dist/plugins-init.mjs +4 -4
  46. package/dist/plugins.d.ts +153 -19
  47. package/dist/plugins.mjs +9 -9
  48. package/package.json +1 -1
  49. package/dist/chunks/overlayEnv-Bs2kVayG.mjs +0 -234
@@ -2,41 +2,132 @@ import { OptionValues, Command, InferCommandArguments, Option } from '@commander
2
2
  import { z, ZodObject } from 'zod';
3
3
 
4
4
  /**
5
- * Definition for a single script entry.
5
+ * Dotenv provenance model (descriptor-only).
6
+ *
7
+ * Requirements addressed:
8
+ * - Host ctx carries a dotenv provenance mapping describing per-key origin and override history.
9
+ * - Provenance is descriptor-only (no value payloads).
10
+ * - Provenance is an ordered stack per key in ascending precedence; the last entry is effective.
11
+ * - Explicit unsets are represented as `op: 'unset'` without requiring deletion of keys from the env map.
6
12
  */
7
- interface ScriptDef<TShell extends string | boolean = string | boolean> {
8
- /** The command string to execute. */
9
- cmd: string;
10
- /** Shell override for this script. */
11
- shell?: TShell | undefined;
12
- }
13
13
  /**
14
- * Scripts table shape.
14
+ * Provenance kind for an entry in {@link DotenvProvenance}.
15
+ *
16
+ * @public
15
17
  */
16
- type ScriptsTable<TShell extends string | boolean = string | boolean> = Record<string, string | ScriptDef<TShell>>;
18
+ type DotenvProvenanceKind = 'file' | 'config' | 'vars' | 'dynamic';
17
19
  /**
18
- * Per-invocation context shared with plugins and actions.
20
+ * Operation represented by a provenance entry.
19
21
  *
20
22
  * @public
21
23
  */
22
- interface GetDotenvCliCtx<TOptions extends GetDotenvOptions = GetDotenvOptions> {
24
+ type DotenvProvenanceOp = 'set' | 'unset';
25
+ /**
26
+ * Base shape for all provenance entries.
27
+ *
28
+ * @public
29
+ */
30
+ interface DotenvProvenanceEntryBase {
23
31
  /**
24
- * Fully resolved option bag used to compute this context.
32
+ * The kind of provenance entry.
25
33
  */
26
- optionsResolved: TOptions;
34
+ kind: DotenvProvenanceKind;
27
35
  /**
28
- * Final composed dotenv environment for this invocation.
36
+ * The operation applied at this layer.
29
37
  */
30
- dotenv: ProcessEnv;
38
+ op: DotenvProvenanceOp;
39
+ }
40
+ /**
41
+ * Provenance entry representing a value sourced from a dotenv file in the cascade.
42
+ *
43
+ * @public
44
+ */
45
+ interface DotenvFileProvenanceEntry extends DotenvProvenanceEntryBase {
46
+ /** Discriminator. */
47
+ kind: 'file';
48
+ /** Global vs env-scoped file. */
49
+ scope: 'global' | 'env';
50
+ /** Public vs private file. */
51
+ privacy: 'public' | 'private';
52
+ /** Environment name (required when scope is `env`). */
53
+ env?: string;
31
54
  /**
32
- * Optional runtime plugin state bag. Plugins may publish non-sensitive metadata here.
55
+ * The corresponding `paths[]` entry as provided by the caller/CLI.
56
+ * This is not an absolute path by policy.
33
57
  */
34
- plugins?: Record<string, unknown>;
58
+ path: string;
35
59
  /**
36
- * Per-plugin validated configuration slices keyed by realized mount path.
60
+ * The computed dotenv filename token (e.g., `.env`, `.env.dev`, `.env.local`, `.env.dev.local`).
37
61
  */
38
- pluginConfigs?: Record<string, unknown>;
62
+ file: string;
63
+ }
64
+ /**
65
+ * Provenance entry representing a value sourced from config overlays (`vars` / `envVars`).
66
+ *
67
+ * @public
68
+ */
69
+ interface DotenvConfigProvenanceEntry extends DotenvProvenanceEntryBase {
70
+ /** Discriminator. */
71
+ kind: 'config';
72
+ /** Global vs env-scoped config slice. */
73
+ scope: 'global' | 'env';
74
+ /** Public vs private on the privacy axis (`local` config maps to `private`). */
75
+ privacy: 'public' | 'private';
76
+ /** Environment name (required when scope is `env`). */
77
+ env?: string;
78
+ /** Packaged vs project config origin. */
79
+ configScope: 'packaged' | 'project';
80
+ /** Public vs local config file. */
81
+ configPrivacy: 'public' | 'local';
82
+ }
83
+ /**
84
+ * Provenance entry representing explicit variables overrides.
85
+ *
86
+ * Notes:
87
+ * - This kind represents values injected via `vars` (CLI/programmatic), not dotenv files.
88
+ *
89
+ * @public
90
+ */
91
+ interface DotenvVarsProvenanceEntry extends DotenvProvenanceEntryBase {
92
+ /** Discriminator. */
93
+ kind: 'vars';
39
94
  }
95
+ /**
96
+ * Source tier for dynamic variables.
97
+ *
98
+ * @public
99
+ */
100
+ type DotenvDynamicSource = 'config' | 'programmatic' | 'dynamicPath';
101
+ /**
102
+ * Provenance entry representing dynamic variables.
103
+ *
104
+ * @public
105
+ */
106
+ interface DotenvDynamicProvenanceEntry extends DotenvProvenanceEntryBase {
107
+ /** Discriminator. */
108
+ kind: 'dynamic';
109
+ /** Dynamic source tier. */
110
+ dynamicSource: DotenvDynamicSource;
111
+ /**
112
+ * The `dynamicPath` value as provided by the caller/CLI when `dynamicSource` is `dynamicPath`.
113
+ * This is not resolved to an absolute path by provenance policy.
114
+ */
115
+ dynamicPath?: string;
116
+ }
117
+ /**
118
+ * Union of all supported provenance entry shapes.
119
+ *
120
+ * @public
121
+ */
122
+ type DotenvProvenanceEntry = DotenvFileProvenanceEntry | DotenvConfigProvenanceEntry | DotenvVarsProvenanceEntry | DotenvDynamicProvenanceEntry;
123
+ /**
124
+ * Per-key provenance history.
125
+ *
126
+ * Each key maps to an array of entries ordered in ascending precedence (lower to higher).
127
+ *
128
+ * @public
129
+ */
130
+ type DotenvProvenance = Record<string, DotenvProvenanceEntry[]>;
40
131
 
41
132
  /**
42
133
  * Resolved CLI options schema.
@@ -122,6 +213,49 @@ declare const getDotenvOptionsSchemaResolved: z.ZodObject<{
122
213
  vars: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodOptional<z.ZodString>>>;
123
214
  }, z.core.$strip>;
124
215
 
216
+ /**
217
+ * Definition for a single script entry.
218
+ */
219
+ interface ScriptDef<TShell extends string | boolean = string | boolean> {
220
+ /** The command string to execute. */
221
+ cmd: string;
222
+ /** Shell override for this script. */
223
+ shell?: TShell | undefined;
224
+ }
225
+ /**
226
+ * Scripts table shape.
227
+ */
228
+ type ScriptsTable<TShell extends string | boolean = string | boolean> = Record<string, string | ScriptDef<TShell>>;
229
+ /**
230
+ * Per-invocation context shared with plugins and actions.
231
+ *
232
+ * @public
233
+ */
234
+ interface GetDotenvCliCtx<TOptions extends GetDotenvOptions = GetDotenvOptions> {
235
+ /**
236
+ * Fully resolved option bag used to compute this context.
237
+ */
238
+ optionsResolved: TOptions;
239
+ /**
240
+ * Final composed dotenv environment for this invocation.
241
+ */
242
+ dotenv: ProcessEnv;
243
+ /**
244
+ * Dotenv provenance history for {@link GetDotenvCliCtx.dotenv}.
245
+ *
246
+ * Descriptor-only: does not include value payloads.
247
+ */
248
+ dotenvProvenance: DotenvProvenance;
249
+ /**
250
+ * Optional runtime plugin state bag. Plugins may publish non-sensitive metadata here.
251
+ */
252
+ plugins?: Record<string, unknown>;
253
+ /**
254
+ * Per-plugin validated configuration slices keyed by realized mount path.
255
+ */
256
+ pluginConfigs?: Record<string, unknown>;
257
+ }
258
+
125
259
  /**
126
260
  * Canonical programmatic options and helpers for get-dotenv.
127
261
  *
@@ -1,18 +1,19 @@
1
- import { r as readMergedOptions, d as definePlugin } from './chunks/readMergedOptions-Nt0TR7dX.mjs';
1
+ import { r as readMergedOptions, d as definePlugin } from './chunks/readMergedOptions-B7VdLROn.mjs';
2
2
  import 'execa';
3
3
  import 'fs-extra';
4
+ import 'node:path';
4
5
  import 'crypto';
5
6
  import 'path';
6
7
  import 'url';
7
8
  import '@commander-js/extra-typings';
8
9
  import 'nanoid';
9
10
  import 'dotenv';
10
- import './chunks/loader-DnhPeGfq.mjs';
11
+ import './chunks/loader-CePOf74i.mjs';
11
12
  import 'package-directory';
12
13
  import 'yaml';
13
14
  import { z } from 'zod';
14
- import { r as runCommand, a as runCommandResult, s as shouldCapture, d as resolveShell, b as buildSpawnEnv } from './chunks/spawnEnv-CN8a7cNR.mjs';
15
- import './chunks/overlayEnv-Bs2kVayG.mjs';
15
+ import { r as runCommand, a as runCommandResult, s as shouldCapture, c as resolveShell, d as buildSpawnEnv } from './chunks/spawnEnv-CQwFu7ZJ.mjs';
16
+ import './chunks/readDotenvCascade-DfFkWMjs.mjs';
16
17
  import './chunks/loadModuleDefault-Dj8B3Stt.mjs';
17
18
 
18
19
  /**
@@ -2,41 +2,132 @@ import { OptionValues, Command, InferCommandArguments, Option } from '@commander
2
2
  import { z, ZodObject } from 'zod';
3
3
 
4
4
  /**
5
- * Definition for a single script entry.
5
+ * Dotenv provenance model (descriptor-only).
6
+ *
7
+ * Requirements addressed:
8
+ * - Host ctx carries a dotenv provenance mapping describing per-key origin and override history.
9
+ * - Provenance is descriptor-only (no value payloads).
10
+ * - Provenance is an ordered stack per key in ascending precedence; the last entry is effective.
11
+ * - Explicit unsets are represented as `op: 'unset'` without requiring deletion of keys from the env map.
6
12
  */
7
- interface ScriptDef<TShell extends string | boolean = string | boolean> {
8
- /** The command string to execute. */
9
- cmd: string;
10
- /** Shell override for this script. */
11
- shell?: TShell | undefined;
12
- }
13
13
  /**
14
- * Scripts table shape.
14
+ * Provenance kind for an entry in {@link DotenvProvenance}.
15
+ *
16
+ * @public
15
17
  */
16
- type ScriptsTable<TShell extends string | boolean = string | boolean> = Record<string, string | ScriptDef<TShell>>;
18
+ type DotenvProvenanceKind = 'file' | 'config' | 'vars' | 'dynamic';
17
19
  /**
18
- * Per-invocation context shared with plugins and actions.
20
+ * Operation represented by a provenance entry.
19
21
  *
20
22
  * @public
21
23
  */
22
- interface GetDotenvCliCtx<TOptions extends GetDotenvOptions = GetDotenvOptions> {
24
+ type DotenvProvenanceOp = 'set' | 'unset';
25
+ /**
26
+ * Base shape for all provenance entries.
27
+ *
28
+ * @public
29
+ */
30
+ interface DotenvProvenanceEntryBase {
23
31
  /**
24
- * Fully resolved option bag used to compute this context.
32
+ * The kind of provenance entry.
25
33
  */
26
- optionsResolved: TOptions;
34
+ kind: DotenvProvenanceKind;
27
35
  /**
28
- * Final composed dotenv environment for this invocation.
36
+ * The operation applied at this layer.
29
37
  */
30
- dotenv: ProcessEnv;
38
+ op: DotenvProvenanceOp;
39
+ }
40
+ /**
41
+ * Provenance entry representing a value sourced from a dotenv file in the cascade.
42
+ *
43
+ * @public
44
+ */
45
+ interface DotenvFileProvenanceEntry extends DotenvProvenanceEntryBase {
46
+ /** Discriminator. */
47
+ kind: 'file';
48
+ /** Global vs env-scoped file. */
49
+ scope: 'global' | 'env';
50
+ /** Public vs private file. */
51
+ privacy: 'public' | 'private';
52
+ /** Environment name (required when scope is `env`). */
53
+ env?: string;
31
54
  /**
32
- * Optional runtime plugin state bag. Plugins may publish non-sensitive metadata here.
55
+ * The corresponding `paths[]` entry as provided by the caller/CLI.
56
+ * This is not an absolute path by policy.
33
57
  */
34
- plugins?: Record<string, unknown>;
58
+ path: string;
35
59
  /**
36
- * Per-plugin validated configuration slices keyed by realized mount path.
60
+ * The computed dotenv filename token (e.g., `.env`, `.env.dev`, `.env.local`, `.env.dev.local`).
37
61
  */
38
- pluginConfigs?: Record<string, unknown>;
62
+ file: string;
63
+ }
64
+ /**
65
+ * Provenance entry representing a value sourced from config overlays (`vars` / `envVars`).
66
+ *
67
+ * @public
68
+ */
69
+ interface DotenvConfigProvenanceEntry extends DotenvProvenanceEntryBase {
70
+ /** Discriminator. */
71
+ kind: 'config';
72
+ /** Global vs env-scoped config slice. */
73
+ scope: 'global' | 'env';
74
+ /** Public vs private on the privacy axis (`local` config maps to `private`). */
75
+ privacy: 'public' | 'private';
76
+ /** Environment name (required when scope is `env`). */
77
+ env?: string;
78
+ /** Packaged vs project config origin. */
79
+ configScope: 'packaged' | 'project';
80
+ /** Public vs local config file. */
81
+ configPrivacy: 'public' | 'local';
82
+ }
83
+ /**
84
+ * Provenance entry representing explicit variables overrides.
85
+ *
86
+ * Notes:
87
+ * - This kind represents values injected via `vars` (CLI/programmatic), not dotenv files.
88
+ *
89
+ * @public
90
+ */
91
+ interface DotenvVarsProvenanceEntry extends DotenvProvenanceEntryBase {
92
+ /** Discriminator. */
93
+ kind: 'vars';
39
94
  }
95
+ /**
96
+ * Source tier for dynamic variables.
97
+ *
98
+ * @public
99
+ */
100
+ type DotenvDynamicSource = 'config' | 'programmatic' | 'dynamicPath';
101
+ /**
102
+ * Provenance entry representing dynamic variables.
103
+ *
104
+ * @public
105
+ */
106
+ interface DotenvDynamicProvenanceEntry extends DotenvProvenanceEntryBase {
107
+ /** Discriminator. */
108
+ kind: 'dynamic';
109
+ /** Dynamic source tier. */
110
+ dynamicSource: DotenvDynamicSource;
111
+ /**
112
+ * The `dynamicPath` value as provided by the caller/CLI when `dynamicSource` is `dynamicPath`.
113
+ * This is not resolved to an absolute path by provenance policy.
114
+ */
115
+ dynamicPath?: string;
116
+ }
117
+ /**
118
+ * Union of all supported provenance entry shapes.
119
+ *
120
+ * @public
121
+ */
122
+ type DotenvProvenanceEntry = DotenvFileProvenanceEntry | DotenvConfigProvenanceEntry | DotenvVarsProvenanceEntry | DotenvDynamicProvenanceEntry;
123
+ /**
124
+ * Per-key provenance history.
125
+ *
126
+ * Each key maps to an array of entries ordered in ascending precedence (lower to higher).
127
+ *
128
+ * @public
129
+ */
130
+ type DotenvProvenance = Record<string, DotenvProvenanceEntry[]>;
40
131
 
41
132
  /**
42
133
  * Resolved CLI options schema.
@@ -122,6 +213,49 @@ declare const getDotenvOptionsSchemaResolved: z.ZodObject<{
122
213
  vars: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodOptional<z.ZodString>>>;
123
214
  }, z.core.$strip>;
124
215
 
216
+ /**
217
+ * Definition for a single script entry.
218
+ */
219
+ interface ScriptDef<TShell extends string | boolean = string | boolean> {
220
+ /** The command string to execute. */
221
+ cmd: string;
222
+ /** Shell override for this script. */
223
+ shell?: TShell | undefined;
224
+ }
225
+ /**
226
+ * Scripts table shape.
227
+ */
228
+ type ScriptsTable<TShell extends string | boolean = string | boolean> = Record<string, string | ScriptDef<TShell>>;
229
+ /**
230
+ * Per-invocation context shared with plugins and actions.
231
+ *
232
+ * @public
233
+ */
234
+ interface GetDotenvCliCtx<TOptions extends GetDotenvOptions = GetDotenvOptions> {
235
+ /**
236
+ * Fully resolved option bag used to compute this context.
237
+ */
238
+ optionsResolved: TOptions;
239
+ /**
240
+ * Final composed dotenv environment for this invocation.
241
+ */
242
+ dotenv: ProcessEnv;
243
+ /**
244
+ * Dotenv provenance history for {@link GetDotenvCliCtx.dotenv}.
245
+ *
246
+ * Descriptor-only: does not include value payloads.
247
+ */
248
+ dotenvProvenance: DotenvProvenance;
249
+ /**
250
+ * Optional runtime plugin state bag. Plugins may publish non-sensitive metadata here.
251
+ */
252
+ plugins?: Record<string, unknown>;
253
+ /**
254
+ * Per-plugin validated configuration slices keyed by realized mount path.
255
+ */
256
+ pluginConfigs?: Record<string, unknown>;
257
+ }
258
+
125
259
  /**
126
260
  * Canonical programmatic options and helpers for get-dotenv.
127
261
  *
@@ -1,20 +1,21 @@
1
- import { r as readMergedOptions, d as definePlugin } from './chunks/readMergedOptions-Nt0TR7dX.mjs';
1
+ import { r as readMergedOptions, d as definePlugin } from './chunks/readMergedOptions-B7VdLROn.mjs';
2
2
  import 'execa';
3
3
  import 'fs-extra';
4
+ import 'node:path';
4
5
  import 'crypto';
5
6
  import path from 'path';
6
7
  import 'url';
7
8
  import { Command } from '@commander-js/extra-typings';
8
9
  import 'nanoid';
9
10
  import 'dotenv';
10
- import './chunks/loader-DnhPeGfq.mjs';
11
+ import './chunks/loader-CePOf74i.mjs';
11
12
  import { packageDirectory } from 'package-directory';
12
13
  import 'yaml';
13
14
  import { z } from 'zod';
14
15
  import { c as composeNestedEnv, m as maybePreserveNodeEvalArgv } from './chunks/invoke-DuRPU1oC.mjs';
15
- import { r as runCommand, b as buildSpawnEnv, d as resolveShell, c as resolveCommand } from './chunks/spawnEnv-CN8a7cNR.mjs';
16
+ import { r as runCommand, d as buildSpawnEnv, c as resolveShell, b as resolveCommand } from './chunks/spawnEnv-CQwFu7ZJ.mjs';
16
17
  import { globby } from 'globby';
17
- import './chunks/overlayEnv-Bs2kVayG.mjs';
18
+ import './chunks/readDotenvCascade-DfFkWMjs.mjs';
18
19
  import './chunks/loadModuleDefault-Dj8B3Stt.mjs';
19
20
 
20
21
  const globPaths = async ({ globs, logger, pkgCwd, rootPath, }) => {
@@ -2,41 +2,132 @@ import { OptionValues, Command, InferCommandArguments, Option } from '@commander
2
2
  import { z, ZodObject } from 'zod';
3
3
 
4
4
  /**
5
- * Definition for a single script entry.
5
+ * Dotenv provenance model (descriptor-only).
6
+ *
7
+ * Requirements addressed:
8
+ * - Host ctx carries a dotenv provenance mapping describing per-key origin and override history.
9
+ * - Provenance is descriptor-only (no value payloads).
10
+ * - Provenance is an ordered stack per key in ascending precedence; the last entry is effective.
11
+ * - Explicit unsets are represented as `op: 'unset'` without requiring deletion of keys from the env map.
6
12
  */
7
- interface ScriptDef<TShell extends string | boolean = string | boolean> {
8
- /** The command string to execute. */
9
- cmd: string;
10
- /** Shell override for this script. */
11
- shell?: TShell | undefined;
12
- }
13
13
  /**
14
- * Scripts table shape.
14
+ * Provenance kind for an entry in {@link DotenvProvenance}.
15
+ *
16
+ * @public
15
17
  */
16
- type ScriptsTable<TShell extends string | boolean = string | boolean> = Record<string, string | ScriptDef<TShell>>;
18
+ type DotenvProvenanceKind = 'file' | 'config' | 'vars' | 'dynamic';
17
19
  /**
18
- * Per-invocation context shared with plugins and actions.
20
+ * Operation represented by a provenance entry.
19
21
  *
20
22
  * @public
21
23
  */
22
- interface GetDotenvCliCtx<TOptions extends GetDotenvOptions = GetDotenvOptions> {
24
+ type DotenvProvenanceOp = 'set' | 'unset';
25
+ /**
26
+ * Base shape for all provenance entries.
27
+ *
28
+ * @public
29
+ */
30
+ interface DotenvProvenanceEntryBase {
23
31
  /**
24
- * Fully resolved option bag used to compute this context.
32
+ * The kind of provenance entry.
25
33
  */
26
- optionsResolved: TOptions;
34
+ kind: DotenvProvenanceKind;
27
35
  /**
28
- * Final composed dotenv environment for this invocation.
36
+ * The operation applied at this layer.
29
37
  */
30
- dotenv: ProcessEnv;
38
+ op: DotenvProvenanceOp;
39
+ }
40
+ /**
41
+ * Provenance entry representing a value sourced from a dotenv file in the cascade.
42
+ *
43
+ * @public
44
+ */
45
+ interface DotenvFileProvenanceEntry extends DotenvProvenanceEntryBase {
46
+ /** Discriminator. */
47
+ kind: 'file';
48
+ /** Global vs env-scoped file. */
49
+ scope: 'global' | 'env';
50
+ /** Public vs private file. */
51
+ privacy: 'public' | 'private';
52
+ /** Environment name (required when scope is `env`). */
53
+ env?: string;
31
54
  /**
32
- * Optional runtime plugin state bag. Plugins may publish non-sensitive metadata here.
55
+ * The corresponding `paths[]` entry as provided by the caller/CLI.
56
+ * This is not an absolute path by policy.
33
57
  */
34
- plugins?: Record<string, unknown>;
58
+ path: string;
35
59
  /**
36
- * Per-plugin validated configuration slices keyed by realized mount path.
60
+ * The computed dotenv filename token (e.g., `.env`, `.env.dev`, `.env.local`, `.env.dev.local`).
37
61
  */
38
- pluginConfigs?: Record<string, unknown>;
62
+ file: string;
63
+ }
64
+ /**
65
+ * Provenance entry representing a value sourced from config overlays (`vars` / `envVars`).
66
+ *
67
+ * @public
68
+ */
69
+ interface DotenvConfigProvenanceEntry extends DotenvProvenanceEntryBase {
70
+ /** Discriminator. */
71
+ kind: 'config';
72
+ /** Global vs env-scoped config slice. */
73
+ scope: 'global' | 'env';
74
+ /** Public vs private on the privacy axis (`local` config maps to `private`). */
75
+ privacy: 'public' | 'private';
76
+ /** Environment name (required when scope is `env`). */
77
+ env?: string;
78
+ /** Packaged vs project config origin. */
79
+ configScope: 'packaged' | 'project';
80
+ /** Public vs local config file. */
81
+ configPrivacy: 'public' | 'local';
82
+ }
83
+ /**
84
+ * Provenance entry representing explicit variables overrides.
85
+ *
86
+ * Notes:
87
+ * - This kind represents values injected via `vars` (CLI/programmatic), not dotenv files.
88
+ *
89
+ * @public
90
+ */
91
+ interface DotenvVarsProvenanceEntry extends DotenvProvenanceEntryBase {
92
+ /** Discriminator. */
93
+ kind: 'vars';
39
94
  }
95
+ /**
96
+ * Source tier for dynamic variables.
97
+ *
98
+ * @public
99
+ */
100
+ type DotenvDynamicSource = 'config' | 'programmatic' | 'dynamicPath';
101
+ /**
102
+ * Provenance entry representing dynamic variables.
103
+ *
104
+ * @public
105
+ */
106
+ interface DotenvDynamicProvenanceEntry extends DotenvProvenanceEntryBase {
107
+ /** Discriminator. */
108
+ kind: 'dynamic';
109
+ /** Dynamic source tier. */
110
+ dynamicSource: DotenvDynamicSource;
111
+ /**
112
+ * The `dynamicPath` value as provided by the caller/CLI when `dynamicSource` is `dynamicPath`.
113
+ * This is not resolved to an absolute path by provenance policy.
114
+ */
115
+ dynamicPath?: string;
116
+ }
117
+ /**
118
+ * Union of all supported provenance entry shapes.
119
+ *
120
+ * @public
121
+ */
122
+ type DotenvProvenanceEntry = DotenvFileProvenanceEntry | DotenvConfigProvenanceEntry | DotenvVarsProvenanceEntry | DotenvDynamicProvenanceEntry;
123
+ /**
124
+ * Per-key provenance history.
125
+ *
126
+ * Each key maps to an array of entries ordered in ascending precedence (lower to higher).
127
+ *
128
+ * @public
129
+ */
130
+ type DotenvProvenance = Record<string, DotenvProvenanceEntry[]>;
40
131
 
41
132
  /**
42
133
  * Resolved CLI options schema.
@@ -122,6 +213,49 @@ declare const getDotenvOptionsSchemaResolved: z.ZodObject<{
122
213
  vars: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodOptional<z.ZodString>>>;
123
214
  }, z.core.$strip>;
124
215
 
216
+ /**
217
+ * Definition for a single script entry.
218
+ */
219
+ interface ScriptDef<TShell extends string | boolean = string | boolean> {
220
+ /** The command string to execute. */
221
+ cmd: string;
222
+ /** Shell override for this script. */
223
+ shell?: TShell | undefined;
224
+ }
225
+ /**
226
+ * Scripts table shape.
227
+ */
228
+ type ScriptsTable<TShell extends string | boolean = string | boolean> = Record<string, string | ScriptDef<TShell>>;
229
+ /**
230
+ * Per-invocation context shared with plugins and actions.
231
+ *
232
+ * @public
233
+ */
234
+ interface GetDotenvCliCtx<TOptions extends GetDotenvOptions = GetDotenvOptions> {
235
+ /**
236
+ * Fully resolved option bag used to compute this context.
237
+ */
238
+ optionsResolved: TOptions;
239
+ /**
240
+ * Final composed dotenv environment for this invocation.
241
+ */
242
+ dotenv: ProcessEnv;
243
+ /**
244
+ * Dotenv provenance history for {@link GetDotenvCliCtx.dotenv}.
245
+ *
246
+ * Descriptor-only: does not include value payloads.
247
+ */
248
+ dotenvProvenance: DotenvProvenance;
249
+ /**
250
+ * Optional runtime plugin state bag. Plugins may publish non-sensitive metadata here.
251
+ */
252
+ plugins?: Record<string, unknown>;
253
+ /**
254
+ * Per-plugin validated configuration slices keyed by realized mount path.
255
+ */
256
+ pluginConfigs?: Record<string, unknown>;
257
+ }
258
+
125
259
  /**
126
260
  * Canonical programmatic options and helpers for get-dotenv.
127
261
  *
@@ -1,19 +1,20 @@
1
- import './chunks/readMergedOptions-Nt0TR7dX.mjs';
1
+ import './chunks/readMergedOptions-B7VdLROn.mjs';
2
2
  import 'execa';
3
3
  import 'fs-extra';
4
+ import 'node:path';
4
5
  import 'crypto';
5
6
  import 'path';
6
7
  import 'url';
7
8
  import '@commander-js/extra-typings';
8
9
  import 'nanoid';
9
10
  import 'dotenv';
10
- import './chunks/loader-DnhPeGfq.mjs';
11
+ import './chunks/loader-CePOf74i.mjs';
11
12
  import 'package-directory';
12
13
  import 'yaml';
13
14
  import 'zod';
14
- export { c as cmdPlugin } from './chunks/index-Bc3h0a95.mjs';
15
- import './chunks/overlayEnv-Bs2kVayG.mjs';
15
+ export { c as cmdPlugin } from './chunks/index-r0Me7-sT.mjs';
16
+ import './chunks/readDotenvCascade-DfFkWMjs.mjs';
16
17
  import './chunks/loadModuleDefault-Dj8B3Stt.mjs';
17
- import './chunks/spawnEnv-CN8a7cNR.mjs';
18
+ import './chunks/spawnEnv-CQwFu7ZJ.mjs';
18
19
  import './chunks/invoke-DuRPU1oC.mjs';
19
- import './chunks/resolveCliOptions-TFRzhB2c.mjs';
20
+ import './chunks/resolveCliOptions-pgUXHJtj.mjs';