envilder 0.13.2 → 0.15.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 (128) hide show
  1. package/README.md +27 -5
  2. package/ROADMAP.md +1 -1
  3. package/docs/changelogs/cli.md +110 -0
  4. package/docs/changelogs/gha.md +47 -1
  5. package/docs/changelogs/sdk-dotnet.md +10 -0
  6. package/docs/changelogs/sdk-nodejs.md +10 -0
  7. package/docs/changelogs/sdk-python.md +10 -0
  8. package/docs/exec-command.md +313 -0
  9. package/lib/envilder/apps/cli/Startup.d.ts +9 -0
  10. package/lib/envilder/apps/cli/Startup.d.ts.map +1 -1
  11. package/lib/envilder/apps/cli/Startup.js +39 -0
  12. package/lib/envilder/apps/cli/Startup.js.map +1 -1
  13. package/lib/envilder/apps/cli/entry/Cli.d.ts.map +1 -1
  14. package/lib/envilder/apps/cli/entry/Cli.js +423 -27
  15. package/lib/envilder/apps/cli/entry/Cli.js.map +1 -1
  16. package/lib/envilder/apps/cli/errors/CliErrorPresenter.d.ts.map +1 -1
  17. package/lib/envilder/apps/cli/errors/CliErrorPresenter.js +4 -1
  18. package/lib/envilder/apps/cli/errors/CliErrorPresenter.js.map +1 -1
  19. package/lib/envilder/apps/cli/errors/ParseErrorRedactor.d.ts +33 -0
  20. package/lib/envilder/apps/cli/errors/ParseErrorRedactor.d.ts.map +1 -0
  21. package/lib/envilder/apps/cli/errors/ParseErrorRedactor.js +121 -0
  22. package/lib/envilder/apps/cli/errors/ParseErrorRedactor.js.map +1 -0
  23. package/lib/envilder/apps/cli/recovery/SsoLoginRecovery.d.ts +13 -0
  24. package/lib/envilder/apps/cli/recovery/SsoLoginRecovery.d.ts.map +1 -1
  25. package/lib/envilder/apps/cli/recovery/SsoLoginRecovery.js +29 -13
  26. package/lib/envilder/apps/cli/recovery/SsoLoginRecovery.js.map +1 -1
  27. package/lib/envilder/apps/shared/ContainerConfiguration.d.ts +2 -1
  28. package/lib/envilder/apps/shared/ContainerConfiguration.d.ts.map +1 -1
  29. package/lib/envilder/apps/shared/ContainerConfiguration.js +4 -2
  30. package/lib/envilder/apps/shared/ContainerConfiguration.js.map +1 -1
  31. package/lib/envilder/core/application/dispatch/DispatchActionCommand.d.ts +19 -2
  32. package/lib/envilder/core/application/dispatch/DispatchActionCommand.d.ts.map +1 -1
  33. package/lib/envilder/core/application/dispatch/DispatchActionCommand.js +17 -1
  34. package/lib/envilder/core/application/dispatch/DispatchActionCommand.js.map +1 -1
  35. package/lib/envilder/core/application/dispatch/DispatchActionCommandHandler.d.ts +9 -2
  36. package/lib/envilder/core/application/dispatch/DispatchActionCommandHandler.d.ts.map +1 -1
  37. package/lib/envilder/core/application/dispatch/DispatchActionCommandHandler.js +28 -3
  38. package/lib/envilder/core/application/dispatch/DispatchActionCommandHandler.js.map +1 -1
  39. package/lib/envilder/core/application/execWithSecrets/CommandLineFormatter.d.ts +13 -0
  40. package/lib/envilder/core/application/execWithSecrets/CommandLineFormatter.d.ts.map +1 -0
  41. package/lib/envilder/core/application/execWithSecrets/CommandLineFormatter.js +19 -0
  42. package/lib/envilder/core/application/execWithSecrets/CommandLineFormatter.js.map +1 -0
  43. package/lib/envilder/core/application/execWithSecrets/ExecWithSecretsCommand.d.ts +20 -0
  44. package/lib/envilder/core/application/execWithSecrets/ExecWithSecretsCommand.d.ts.map +1 -0
  45. package/lib/envilder/core/application/execWithSecrets/ExecWithSecretsCommand.js +19 -0
  46. package/lib/envilder/core/application/execWithSecrets/ExecWithSecretsCommand.js.map +1 -0
  47. package/lib/envilder/core/application/execWithSecrets/ExecWithSecretsCommandHandler.d.ts +61 -0
  48. package/lib/envilder/core/application/execWithSecrets/ExecWithSecretsCommandHandler.d.ts.map +1 -0
  49. package/lib/envilder/core/application/execWithSecrets/ExecWithSecretsCommandHandler.js +159 -0
  50. package/lib/envilder/core/application/execWithSecrets/ExecWithSecretsCommandHandler.js.map +1 -0
  51. package/lib/envilder/core/application/pullSecretsToEnv/PullSecretsToEnvCommandHandler.d.ts +1 -9
  52. package/lib/envilder/core/application/pullSecretsToEnv/PullSecretsToEnvCommandHandler.d.ts.map +1 -1
  53. package/lib/envilder/core/application/pullSecretsToEnv/PullSecretsToEnvCommandHandler.js +9 -79
  54. package/lib/envilder/core/application/pullSecretsToEnv/PullSecretsToEnvCommandHandler.js.map +1 -1
  55. package/lib/envilder/core/application/secretResolution/SecretResolver.d.ts +66 -0
  56. package/lib/envilder/core/application/secretResolution/SecretResolver.d.ts.map +1 -0
  57. package/lib/envilder/core/application/secretResolution/SecretResolver.js +132 -0
  58. package/lib/envilder/core/application/secretResolution/SecretResolver.js.map +1 -0
  59. package/lib/envilder/core/domain/ChildEnvironment.d.ts +22 -0
  60. package/lib/envilder/core/domain/ChildEnvironment.d.ts.map +1 -0
  61. package/lib/envilder/core/domain/ChildEnvironment.js +50 -0
  62. package/lib/envilder/core/domain/ChildEnvironment.js.map +1 -0
  63. package/lib/envilder/core/domain/EnvironmentVariable.d.ts.map +1 -1
  64. package/lib/envilder/core/domain/EnvironmentVariable.js +4 -2
  65. package/lib/envilder/core/domain/EnvironmentVariable.js.map +1 -1
  66. package/lib/envilder/core/domain/EnvironmentVariableName.d.ts +9 -0
  67. package/lib/envilder/core/domain/EnvironmentVariableName.d.ts.map +1 -0
  68. package/lib/envilder/core/domain/EnvironmentVariableName.js +70 -0
  69. package/lib/envilder/core/domain/EnvironmentVariableName.js.map +1 -0
  70. package/lib/envilder/core/domain/ExecExitCode.d.ts +14 -0
  71. package/lib/envilder/core/domain/ExecExitCode.d.ts.map +1 -0
  72. package/lib/envilder/core/domain/ExecExitCode.js +23 -0
  73. package/lib/envilder/core/domain/ExecExitCode.js.map +1 -0
  74. package/lib/envilder/core/domain/OperationMode.d.ts +2 -1
  75. package/lib/envilder/core/domain/OperationMode.d.ts.map +1 -1
  76. package/lib/envilder/core/domain/OperationMode.js +1 -0
  77. package/lib/envilder/core/domain/OperationMode.js.map +1 -1
  78. package/lib/envilder/core/domain/errors/DomainErrors.d.ts +44 -0
  79. package/lib/envilder/core/domain/errors/DomainErrors.d.ts.map +1 -1
  80. package/lib/envilder/core/domain/errors/DomainErrors.js +57 -0
  81. package/lib/envilder/core/domain/errors/DomainErrors.js.map +1 -1
  82. package/lib/envilder/core/domain/ports/IProcessContext.d.ts +14 -0
  83. package/lib/envilder/core/domain/ports/IProcessContext.d.ts.map +1 -0
  84. package/lib/envilder/core/domain/ports/IProcessContext.js +2 -0
  85. package/lib/envilder/core/domain/ports/IProcessContext.js.map +1 -0
  86. package/lib/envilder/core/domain/ports/IProcessRunner.d.ts +27 -0
  87. package/lib/envilder/core/domain/ports/IProcessRunner.d.ts.map +1 -0
  88. package/lib/envilder/core/domain/ports/IProcessRunner.js +2 -0
  89. package/lib/envilder/core/domain/ports/IProcessRunner.js.map +1 -0
  90. package/lib/envilder/core/domain/ports/ISecretMasker.d.ts +7 -0
  91. package/lib/envilder/core/domain/ports/ISecretMasker.d.ts.map +1 -1
  92. package/lib/envilder/core/infrastructure/aws/AwsSecretProviderFactory.d.ts +5 -1
  93. package/lib/envilder/core/infrastructure/aws/AwsSecretProviderFactory.d.ts.map +1 -1
  94. package/lib/envilder/core/infrastructure/aws/AwsSecretProviderFactory.js +3 -2
  95. package/lib/envilder/core/infrastructure/aws/AwsSecretProviderFactory.js.map +1 -1
  96. package/lib/envilder/core/infrastructure/aws/AwsSsmSecretProvider.d.ts +6 -1
  97. package/lib/envilder/core/infrastructure/aws/AwsSsmSecretProvider.d.ts.map +1 -1
  98. package/lib/envilder/core/infrastructure/aws/AwsSsmSecretProvider.js +10 -3
  99. package/lib/envilder/core/infrastructure/aws/AwsSsmSecretProvider.js.map +1 -1
  100. package/lib/envilder/core/infrastructure/github/GitHubActionsSecretMasker.d.ts +22 -0
  101. package/lib/envilder/core/infrastructure/github/GitHubActionsSecretMasker.d.ts.map +1 -1
  102. package/lib/envilder/core/infrastructure/github/GitHubActionsSecretMasker.js +38 -1
  103. package/lib/envilder/core/infrastructure/github/GitHubActionsSecretMasker.js.map +1 -1
  104. package/lib/envilder/core/infrastructure/github/NoOpSecretMasker.d.ts +1 -0
  105. package/lib/envilder/core/infrastructure/github/NoOpSecretMasker.d.ts.map +1 -1
  106. package/lib/envilder/core/infrastructure/github/NoOpSecretMasker.js +3 -0
  107. package/lib/envilder/core/infrastructure/github/NoOpSecretMasker.js.map +1 -1
  108. package/lib/envilder/core/infrastructure/logger/StderrConsoleLogger.d.ts +11 -0
  109. package/lib/envilder/core/infrastructure/logger/StderrConsoleLogger.d.ts.map +1 -0
  110. package/lib/envilder/core/infrastructure/logger/StderrConsoleLogger.js +27 -0
  111. package/lib/envilder/core/infrastructure/logger/StderrConsoleLogger.js.map +1 -0
  112. package/lib/envilder/core/infrastructure/process/CrossSpawnProcessRunner.d.ts +15 -0
  113. package/lib/envilder/core/infrastructure/process/CrossSpawnProcessRunner.d.ts.map +1 -0
  114. package/lib/envilder/core/infrastructure/process/CrossSpawnProcessRunner.js +145 -0
  115. package/lib/envilder/core/infrastructure/process/CrossSpawnProcessRunner.js.map +1 -0
  116. package/lib/envilder/core/infrastructure/process/NodeProcessContext.d.ts +11 -0
  117. package/lib/envilder/core/infrastructure/process/NodeProcessContext.d.ts.map +1 -0
  118. package/lib/envilder/core/infrastructure/process/NodeProcessContext.js +18 -0
  119. package/lib/envilder/core/infrastructure/process/NodeProcessContext.js.map +1 -0
  120. package/lib/envilder/core/infrastructure/variableStore/FileVariableStore.d.ts +69 -2
  121. package/lib/envilder/core/infrastructure/variableStore/FileVariableStore.d.ts.map +1 -1
  122. package/lib/envilder/core/infrastructure/variableStore/FileVariableStore.js +294 -55
  123. package/lib/envilder/core/infrastructure/variableStore/FileVariableStore.js.map +1 -1
  124. package/lib/envilder/core/types.d.ts +6 -0
  125. package/lib/envilder/core/types.d.ts.map +1 -1
  126. package/lib/envilder/core/types.js +3 -0
  127. package/lib/envilder/core/types.js.map +1 -1
  128. package/package.json +6 -2
package/README.md CHANGED
@@ -7,7 +7,7 @@
7
7
  <p align="center">
8
8
  <b>One secret mapping for local dev, CI/CD, and runtime.</b><br>
9
9
  <span>Define secrets once in <code>envilder.json</code>. Resolve them consistently from AWS SSM or Azure Key Vault.</span><br>
10
- <a href="https://envilder.com"><strong>Website & docs → envilder.com</strong></a>
10
+ <a href="https://envilder.com/?utm_source=npm&utm_medium=readme&utm_campaign=root"><strong>Website & docs → envilder.com</strong></a>
11
11
  </p>
12
12
 
13
13
  [![npm version](https://img.shields.io/npm/v/envilder.svg)](https://www.npmjs.com/package/envilder)
@@ -15,6 +15,7 @@
15
15
  [![CI Tests](https://github.com/macalbert/envilder/actions/workflows/tests.yml/badge.svg)](https://github.com/macalbert/envilder/actions/workflows/tests.yml)
16
16
  [![Overall Coverage](https://macalbert.github.io/envilder/badge_combined.svg)](https://macalbert.github.io/envilder/)
17
17
  [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
18
+ [![Context7](https://img.shields.io/badge/Context7-docs_for_AI_agents-blue.svg)](https://context7.com/macalbert/envilder)
18
19
 
19
20
  ## Why Envilder?
20
21
 
@@ -29,6 +30,10 @@ them from AWS SSM or Azure Key Vault. The same mapping file works in local dev (
29
30
  CI/CD (GitHub Action), and application startup (runtime SDKs).
30
31
 
31
32
  ```bash
33
+ # Zero-config: uses envilder.json and .env by default
34
+ npx envilder
35
+
36
+ # Or with explicit paths
32
37
  npx envilder --map=envilder.json --envfile=.env
33
38
  ```
34
39
 
@@ -100,15 +105,29 @@ npm install -g envilder
100
105
  ### 3. Generate your `.env` file
101
106
 
102
107
  ```bash
103
- npx envilder --map=envilder.json --envfile=.env
108
+ npx envilder
104
109
  ```
105
110
 
106
- That's it. Your secrets are pulled from AWS SSM and written to `.env`.
111
+ That's it. With `envilder.json` in your current directory, no flags are needed — `--map` defaults to `envilder.json` and
112
+ `--envfile` defaults to `.env`. Your secrets are pulled from AWS SSM and written to `.env`.
107
113
  Add `.env` to `.gitignore`. The mapping file is versioned and reviewable in PRs.
108
114
 
109
115
  > 💡 Using Azure Key Vault? Add a `$config` section to your mapping file.
110
116
  > See [Mapping File Format](#️-mapping-file-format) below.
111
117
 
118
+ ### 4. Or skip the `.env` file entirely
119
+
120
+ ```bash
121
+ npx envilder exec -- npm run dev
122
+ ```
123
+
124
+ `envilder exec` resolves the same mapping and starts your command with the secrets in its environment.
125
+ Nothing is written to disk. Envilder options go before the command (or before an optional `--`); everything
126
+ after belongs to your command. Exec mode is fail-closed: the command does not start if any secret is missing.
127
+ It is not a sandbox: your command and everything it starts can read the secrets.
128
+
129
+ 📖 See the [Exec Command Guide](docs/exec-command.md) for exit codes, signals and GitHub Actions masking.
130
+
112
131
  ### 🎥 See it in action
113
132
 
114
133
  Watch how easy it is to automate your `.env` management in less than 1 minute:
@@ -198,7 +217,7 @@ This means you can set a default provider in `$config` and override it per invoc
198
217
 
199
218
  ```bash
200
219
  # Uses $config from the map file
201
- envilder --map=envilder.json --envfile=.env
220
+ envilder
202
221
 
203
222
  # Overrides provider and vault URL from the map file
204
223
  envilder --provider=azure --vault-url=https://other-vault.vault.azure.net --map=envilder.json --envfile=.env
@@ -342,9 +361,12 @@ prebuilt action, so consumers do not need an Envilder build step.
342
361
 
343
362
  ### 📚 More resources
344
363
 
345
- - [📖 Full Documentation](https://envilder.com): the complete guide at envilder.com
364
+ - [📖 Full Documentation](https://envilder.com/docs/getting-started/?utm_source=npm&utm_medium=readme&utm_campaign=root-docs): the complete guide at envilder.com
346
365
  - [Push Command Guide](docs/push-command.md)
347
366
  - [Pull Command Guide](docs/pull-command.md)
367
+ - [Exec Command Guide](docs/exec-command.md)
368
+ - [🤖 Envilder on Context7](https://context7.com/macalbert/envilder): up-to-date docs for AI coding assistants
369
+ (Claude Code, Cursor, Copilot). Add `use context7` to your prompt, or reference the library ID `/macalbert/envilder`.
348
370
 
349
371
  ## 🛠️ How it works
350
372
 
package/ROADMAP.md CHANGED
@@ -89,7 +89,7 @@ All five SDKs are developed **in parallel**: same map-file contract, same confor
89
89
  - **One map-file spec**: formal JSON Schema at `spec/` is the source of truth for all SDKs
90
90
  - **Conformance tests**: language-agnostic fixtures that every SDK must pass
91
91
  - **Independent versioning**: each SDK has its own semver (`sdk-node@1.2.0`, `sdk-py@0.3.0`)
92
- - **Shared test infrastructure**: LocalStack (AWS) and Lowkey Vault (Azure) via Docker Compose serve all SDKs
92
+ - **Shared test infrastructure**: LocalStack for AWS and Azure via Docker Compose serve all SDKs
93
93
 
94
94
  ---
95
95
 
@@ -5,6 +5,116 @@ For SDK-specific changes, see `sdk-dotnet.md`, `sdk-python.md`, or `sdk-nodejs.m
5
5
 
6
6
  ---
7
7
 
8
+ ## [0.15.0] - 2026-10-16
9
+
10
+ ### Added
11
+
12
+ * **`envilder exec`: run a command with resolved secrets, without a `.env`
13
+ file**: `envilder exec [options] [--] <command> [args...]` resolves every
14
+ secret in the map file and starts the command with those values in its
15
+ environment. Nothing is written to disk. The command starts at the first
16
+ argument that is not an Envilder option (`--` is optional), arguments are
17
+ passed verbatim without a shell, and Windows `npm`/`npx` shims are supported.
18
+ Resolution is fail-closed: the command never starts when a secret is missing,
19
+ empty or unreadable. Mapped values override inherited variables, naming the
20
+ overridden variables on stderr. All Envilder output goes to stderr as a
21
+ single summary line that names the program but never its arguments, so
22
+ stdout carries only the command's output. Inside GitHub Actions every value
23
+ is registered for masking, and every registration is written to stderr
24
+ before the command starts. Exit codes follow GNU `env`: the command's own
25
+ code, `128+n` for signals, `125` for Envilder errors, `126` and `127` when
26
+ the command cannot be executed or found. `SIGTERM` and `SIGHUP` are
27
+ forwarded and the command is awaited without a timeout, even if a signal
28
+ cannot be delivered. Exec mode is not a sandbox: see
29
+ [docs/exec-command.md](../exec-command.md)
30
+ ([#550](https://github.com/macalbert/envilder/issues/550))
31
+
32
+ ### Security
33
+
34
+ * **Parse errors no longer echo option values or arguments**: parse errors
35
+ are rebuilt from safe forms, so option values and extra arguments are never
36
+ printed. An unknown long option is named only when it is a near-typo of a
37
+ real option, together with the suggestion (`--valeu=<value>` is shown as
38
+ `unknown option '--valeu' (Did you mean --value?)`); any other unknown long
39
+ option gets a generic message, so a mistyped secret is never echoed. An
40
+ unknown short option is named by its single character, "too many
41
+ arguments" shows only the counts, and any other parse error is replaced
42
+ with a generic message. Exit codes are unchanged
43
+ ([#554](https://github.com/macalbert/envilder/issues/554))
44
+
45
+ * **Path and name options never swallow the next option**: `--map`,
46
+ `--envfile`, `--profile`, `--provider`, `--vault-url`, `--key`,
47
+ `--secret-path` and `--ssm-path` (and their `exec` counterparts) reject a
48
+ value that starts with `-` as a missing argument, before any map file is
49
+ read, instead of taking the following option as their value. `--value` is
50
+ exempt, so a secret may still start with `-`
51
+ ([#554](https://github.com/macalbert/envilder/issues/554))
52
+
53
+ ---
54
+
55
+ ## [0.14.0] - 2026-09-26
56
+
57
+ ### Added
58
+
59
+ * **Zero-config defaults for `--map` and `--envfile`**: Running `envilder` with
60
+ no flags now resolves `envilder.json` from the current directory and writes
61
+ to `.env`. Both flags still override the defaults, and an empty `--map` value
62
+ is rejected rather than silently treated as absent
63
+ ([#314](https://github.com/macalbert/envilder/pull/314))
64
+
65
+ ### Changed
66
+
67
+ * **Push-single resolves `$config` from the default map file**: A
68
+ single-variable push (`--key` + `--value` + `--secret-path`) now reads the
69
+ `$config` section (`provider`, `vaultUrl`, `profile`) of `envilder.json` when
70
+ one is present, so it targets the same provider as the rest of the project
71
+ instead of silently defaulting to AWS SSM. A missing `envilder.json` is not
72
+ an error for push-single, `--push` is no longer required, and CLI flags still
73
+ override `$config`. The resolved provider is logged before the push
74
+ ([#314](https://github.com/macalbert/envilder/pull/314))
75
+
76
+ * **Reject empty single-secret options**: `--key`, `--value` and
77
+ `--secret-path` must now be non-empty whenever any of them is supplied.
78
+ Previously an explicitly empty value such as `--key ''` passed the
79
+ partial-option guard and fell through to a full `.env` push or pull
80
+ ([#314](https://github.com/macalbert/envilder/pull/314))
81
+
82
+ ### Fixed
83
+
84
+ * **Preserve secret values when writing `.env` files**: Values with hashes,
85
+ leading or trailing whitespace, quotes, backslashes or line breaks now
86
+ round-trip exactly, and updating a multi-line value no longer leaves the
87
+ rest of the old secret in the file. Unchanged assignments are kept byte for
88
+ byte, and a write that would not read back correctly aborts, naming only
89
+ the affected keys ([#515](https://github.com/macalbert/envilder/pull/515))
90
+
91
+ ### Security
92
+
93
+ * **Reject map-file mapping keys a `.env` file cannot represent**: Variable
94
+ names must now match `^[A-Za-z0-9_.-]+$`, checked when parsing a map file
95
+ and again before writing an environment file. This is exactly the key
96
+ grammar `.env` parsers recognize, so an accepted name reads back as itself.
97
+ Previously a name containing `=`, a carriage return, a newline or the
98
+ `U+2028`/`U+2029` line separators could smuggle an extra `key=value`
99
+ assignment into the generated file, and a name containing a space, `#`, a
100
+ tab or a non-Latin letter was written and then silently lost while the run
101
+ reported success. Dotted and hyphenated names remain valid
102
+ ([#511](https://github.com/macalbert/envilder/issues/511))
103
+
104
+ * **Reject the mapping key `__proto__`**: No `.env` parser can read this name
105
+ back, so the CLI previously resolved the secret and wrote a line that
106
+ silently never loaded. It is now rejected at map-file ingestion with an
107
+ explicit message ([#511](https://github.com/macalbert/envilder/issues/511))
108
+
109
+ ### Documentation
110
+
111
+ * **Point README links at specific docs pages with UTM tags**: The header link
112
+ and "Full Documentation" link in the README now carry UTM tags and the
113
+ latter lands on `envilder.com/docs/getting-started/`, so visits from GitHub
114
+ and npm to envilder.com can be measured
115
+
116
+ ---
117
+
8
118
  ## [0.13.2] - 2026-08-14
9
119
 
10
120
  ### Changed
@@ -1,4 +1,50 @@
1
- ## [Unreleased]
1
+ ## [0.15.0] - 2026-10-16
2
+
3
+ ### Changed
4
+
5
+ * **Shared secret masker can report when registrations are written**: The
6
+ masker the Action shares with the CLI gained an internal capability to
7
+ report when its `::add-mask::` writes have completed, used by the new
8
+ CLI-only `envilder exec` command. The Action's pull flow does not use it,
9
+ and the registrations it prints are unchanged
10
+ ([#550](https://github.com/macalbert/envilder/issues/550))
11
+
12
+ ---
13
+
14
+ ## [0.14.0] - 2026-09-26
15
+
16
+ ### Fixed
17
+
18
+ * **Preserve secret values when writing `.env` files**: Values with hashes,
19
+ leading or trailing whitespace, quotes, backslashes or line breaks now
20
+ round-trip exactly, and updating a multi-line value no longer leaves the
21
+ rest of the old secret in the file. Unchanged assignments are kept byte for
22
+ byte, and a write that would not read back correctly aborts, naming only
23
+ the affected keys ([#515](https://github.com/macalbert/envilder/pull/515))
24
+
25
+ ### Security
26
+
27
+ * **Reject map-file mapping keys a `.env` file cannot represent**: Variable
28
+ names must now match `^[A-Za-z0-9_.-]+$`, checked when parsing a map file
29
+ and again before writing an environment file. This is exactly the key
30
+ grammar `.env` parsers recognize, so an accepted name reads back as itself.
31
+ Previously a name containing `=`, a carriage return, a newline or the
32
+ `U+2028`/`U+2029` line separators could smuggle an extra `key=value`
33
+ assignment into the generated file, and a name containing a space, `#`, a
34
+ tab or a non-Latin letter was written and then silently lost while the run
35
+ reported success. Dotted and hyphenated names remain valid
36
+ ([#511](https://github.com/macalbert/envilder/issues/511))
37
+
38
+ * **Reject the mapping key `__proto__`**: No `.env` parser can read this name
39
+ back, so the Action previously resolved the secret and wrote a line that
40
+ silently never loaded. It is now rejected at map-file ingestion with an
41
+ explicit message ([#511](https://github.com/macalbert/envilder/issues/511))
42
+
43
+ ### Documentation
44
+
45
+ * **Point the README "Learn more" link at the Action docs**: It now lands on
46
+ `envilder.com/docs/github-action/` with UTM tags, so visits from the Action
47
+ README to envilder.com can be measured
2
48
 
3
49
  ---
4
50
 
@@ -1,3 +1,13 @@
1
+ ## [0.5.1] - 2026-09-26
2
+
3
+ ### Documentation
4
+
5
+ * **Link the NuGet page to the .NET SDK docs**: The README's "Official
6
+ Website" link now points to `envilder.com/docs/sdks/dotnet/` with UTM tags,
7
+ so visits from NuGet to envilder.com can be measured
8
+
9
+ ---
10
+
1
11
  ## [0.5.0] - 2026-06-26
2
12
 
3
13
  ### Added
@@ -1,3 +1,13 @@
1
+ ## [0.4.1] - 2026-09-26
2
+
3
+ ### Documentation
4
+
5
+ * **Add a Links section to the npm README**: The `@envilder/sdk` page on npm
6
+ now links to the changelog and to `envilder.com/docs/sdks/nodejs/` with UTM
7
+ tags, so visits from npm to envilder.com can be measured
8
+
9
+ ---
10
+
1
11
  ## [0.4.0] - 2026-06-26
2
12
 
3
13
  ### Added
@@ -1,3 +1,13 @@
1
+ ## [0.5.1] - 2026-09-26
2
+
3
+ ### Documentation
4
+
5
+ * **Link the PyPI page to the Python SDK docs**: The README's "Official
6
+ Website" link now points to `envilder.com/docs/sdks/python/` with UTM tags,
7
+ so visits from PyPI to envilder.com can be measured
8
+
9
+ ---
10
+
1
11
  ## [0.5.0] - 2026-06-26
2
12
 
3
13
  ### Added
@@ -0,0 +1,313 @@
1
+ # Envilder: Exec Command
2
+
3
+ ## Overview
4
+
5
+ `envilder exec` resolves every secret declared in the map file and starts a
6
+ command with those values in its environment, **without writing anything to
7
+ disk**.
8
+
9
+ ```bash
10
+ envilder exec -- npm run dev
11
+ envilder exec --map=config/envilder.json -- node server.js
12
+ envilder exec --provider=azure --vault-url=https://my-vault.vault.azure.net -- dotnet run
13
+ ```
14
+
15
+ The map file stays in Git and the values stay in your cloud provider. The only
16
+ difference with pull mode is where the values end up:
17
+
18
+ ```text
19
+ pull mode: provider -> .env on disk -> process
20
+ exec mode: provider -> memory -> child process environment
21
+ ```
22
+
23
+ There is no `.env` file to gitignore, keep in sync or clean up, and nothing in
24
+ the working tree for editors, indexers, build tools or install scripts to read.
25
+
26
+ ```mermaid
27
+ graph LR
28
+ A[Mapping File] --> |Secret Paths| B[Envilder]:::core
29
+ D[Cloud Credentials]:::cloud --> B
30
+ B --> E[AWS SSM / Azure Key Vault]:::cloud
31
+ B --> |Environment| F[Your command]
32
+
33
+ classDef cloud fill:#ffcc66,color:#000000,stroke:#333,stroke-width:1.5px;
34
+ classDef core fill:#1f3b57,color:#fff,stroke:#ccc,stroke-width:2px;
35
+ ```
36
+
37
+ ## Usage
38
+
39
+ ```text
40
+ envilder exec [options] [--] <command> [args...]
41
+ ```
42
+
43
+ | Option | Description |
44
+ | ------ | ----------- |
45
+ | `--map <path>` | Path to the map file. Defaults to `envilder.json` in the current directory. |
46
+ | `--profile <name>` | AWS CLI profile. Overrides `$config.profile`. |
47
+ | `--provider <name>` | `aws` or `azure`. Overrides `$config.provider`. |
48
+ | `--vault-url <url>` | Azure Key Vault URL. Overrides `$config.vaultUrl`. |
49
+
50
+ The map file and its `$config` section work exactly as in pull mode. See
51
+ [Mapping File Format](../README.md#️-mapping-file-format).
52
+
53
+ ### Where the command starts: the `--` rule
54
+
55
+ Envilder options come first. The command starts at the **first argument that
56
+ is not an Envilder option**, or right after `--` when present. Everything from
57
+ there on is passed to the command verbatim, even if it looks like an Envilder
58
+ option.
59
+
60
+ ```bash
61
+ envilder exec npm run dev # everything belongs to npm
62
+ envilder exec --map=cfg.json npm run dev # --map is Envilder's, the rest is npm's
63
+ envilder exec npm run dev --map=x # --map=x belongs to npm (it comes after the command)
64
+ envilder exec --map=cfg.json -- npm run dev # same, with an explicit separator
65
+ envilder exec -- -weird-program-name # use -- when the command itself starts with -
66
+ ```
67
+
68
+ An unknown option before the command is an error (exit code `125`), so a typo
69
+ such as `--mapp` never reaches your command by accident. Error messages never
70
+ repeat what you typed beyond a safe option name: an unknown option is named
71
+ only when it is a near-typo of a real option, with a suggestion, and gets a
72
+ generic message otherwise. Options such as `--map` or `--profile` never take a
73
+ value that starts with `-`: `envilder exec --map --profile dev node` is
74
+ reported as `error: option '--map <path>' argument missing` instead of
75
+ treating `--profile` as the map path.
76
+
77
+ Envilder options also go **after** `exec`, never before it. An option written
78
+ before `exec` is rejected with exit code `125` instead of being silently
79
+ ignored, and Envilder shows the corrected command:
80
+
81
+ ```text
82
+ $ envilder --map=config/prod.json exec -- npm start
83
+ error: Put envilder options after "exec": envilder exec --map=config/prod.json -- npm …
84
+ ```
85
+
86
+ The suggestion shows your command by program name only, followed by `…` when
87
+ it has arguments: arguments can carry secrets (for example an
88
+ `Authorization` header), so Envilder never prints them.
89
+
90
+ Only the options exec supports (`--map`, `--profile`, `--provider`,
91
+ `--vault-url`) are moved into the suggested command. Options exec does not
92
+ support (`--envfile`, `--push`, `--key`, `--value`, `--secret-path`,
93
+ `--ssm-path`) are named but **their values are never printed**, because a
94
+ value such as `--value` can be a secret:
95
+
96
+ ```text
97
+ $ envilder --value=s3cret exec -- node app.js
98
+ error: Put envilder options after "exec".
99
+ --value cannot be used with exec.
100
+ ```
101
+
102
+ ### Options that are rejected
103
+
104
+ Exec mode never reads or writes a `.env` file and never pushes secrets. These
105
+ options are rejected before any provider call, with exit code `125`:
106
+
107
+ | Option | Message |
108
+ | ------ | ------- |
109
+ | `--envfile` | `--envfile cannot be used with exec: exec mode never reads or writes a .env file.` |
110
+ | `--push` | `--push cannot be used with exec.` |
111
+ | `--key`, `--value`, `--secret-path`, `--ssm-path` | `Single-secret push options cannot be used with exec.` |
112
+
113
+ ### No shell
114
+
115
+ Arguments are passed to the command as an argument list, without a shell. The
116
+ command receives `$DB_URL`, `%PATH%` or `&&` literally. If you need shell
117
+ features, start a shell explicitly:
118
+
119
+ ```bash
120
+ envilder exec -- sh -c 'echo $DB_URL'
121
+ ```
122
+
123
+ On Windows, npm-style `.cmd`/`.bat` shims such as `npm` and `npx` work without
124
+ enabling shell interpretation of the arguments. To do this, Envilder (through
125
+ `cross-spawn`) runs shims, and commands it cannot resolve to an executable,
126
+ via `cmd.exe /d /s /c` with every argument escaped. Two visible consequences:
127
+
128
+ * When the command does not exist, `cmd.exe` prints its own "is not
129
+ recognized as an internal or external command" line (in the system
130
+ language) before Envilder's `Command not found: <command>`. The exit code is
131
+ still `127`.
132
+ * `cmd.exe` builtins such as `echo` or `dir` resolve and run.
133
+
134
+ ## Exit codes
135
+
136
+ Exit codes follow GNU `env` and `docker run`, so you can tell an Envilder
137
+ failure apart from your command's own exit code:
138
+
139
+ | Code | Meaning |
140
+ | ---- | ------- |
141
+ | `n` | Your command exited with code `n` |
142
+ | `128 + n` | Your command was killed by signal `n` (for example `137` for `SIGKILL`) |
143
+ | `125` | Envilder failed before starting the command: bad options, missing command, no map file, unresolved secrets, expired credentials, an environment too large for the OS (`E2BIG`), or exhausted system resources (`Cannot start <command>: system resources unavailable`, for example `EAGAIN`, `EMFILE`, `ENFILE`, `ENOMEM`) |
144
+ | `126` | The command exists but the operating system refused to execute it: `Permission denied` (no executable bit, `EACCES`), or `Cannot execute <command>: <reason> (<code>)` for any other reason, for example a busy executable (`ETXTBSY`), a symbolic link loop (`ELOOP`), an unknown executable format (`ENOEXEC`), a directory (`EISDIR`), a path component that is not a directory (`ENOTDIR`) or a name that is too long (`ENAMETOOLONG`) |
145
+ | `127` | The command was not found |
146
+
147
+ On Windows, a signal that Envilder forwards to the command is still reported
148
+ as a signal, so `128 + n` applies: `SIGTERM` gives `143`, `SIGINT` gives `130`,
149
+ and `SIGHUP` is reported as `SIGKILL`, giving `137`. A command terminated from
150
+ outside Envilder (for example by Task Manager or `taskkill /F`) typically exits
151
+ with code `1` instead.
152
+
153
+ Options written before `exec` are also an Envilder error (`125`); see
154
+ [Where the command starts](#where-the-command-starts-the----rule).
155
+
156
+ Other modes (pull and push) keep exiting with `1` on failure.
157
+
158
+ ## Fail-closed resolution
159
+
160
+ Pull mode warns and skips a secret that is missing or empty. **Exec mode never
161
+ starts the command with an incomplete set of secrets**: if any secret is
162
+ missing, empty or cannot be read (for example, access denied), the command is
163
+ not started, Envilder lists the affected variables with their masked paths and
164
+ exits with `125`.
165
+
166
+ Other conditions that stop the command from starting:
167
+
168
+ * A secret value contains a NUL byte, which cannot be passed in an environment
169
+ variable.
170
+ * The AWS credentials or SSO session expired. In an interactive terminal
171
+ Envilder offers to run `aws sso login` and then retries **only the secret
172
+ resolution**: your command is started at most once. If you decline or the
173
+ login fails, the exit code is `125`. The prompt and the login output go to
174
+ stderr, so the prompt also works when stdout is redirected
175
+ (`envilder exec -- node print.js > out.json`); it needs stdin and stderr to
176
+ be a terminal. Recovery only happens **before** the command starts: an SSO
177
+ or credentials error reported after that point is never retried, Envilder
178
+ prints `The command could not be supervised after it started: <reason>` and
179
+ exits with `125`.
180
+ * On Windows, the map file declares names that differ only by case (for
181
+ example `Path` and `PATH`). Windows treats them as the same variable, so
182
+ Envilder exits with `125` before any provider call instead of silently
183
+ dropping one. On Linux and macOS both names are kept.
184
+
185
+ A map file that declares no variables (only `$config`) is not an error: the
186
+ command starts with the inherited environment and Envilder prints
187
+ `Map file declares no variables.`
188
+
189
+ ## Environment composition
190
+
191
+ The command inherits the full environment of the shell that runs Envilder,
192
+ plus every variable declared in the map file.
193
+
194
+ **The map file wins.** When an inherited variable has the same name as a mapped
195
+ one, the command sees the value from the provider, and Envilder prints the
196
+ names (never the values) on stderr:
197
+
198
+ ```text
199
+ Overriding inherited variables: API_KEY
200
+ ```
201
+
202
+ On Windows, names are compared case-insensitively: an inherited `Path` and a
203
+ mapped `PATH` are the same variable, the mapped value wins, and the command
204
+ gets exactly one entry. Within the map file itself, names that differ only by
205
+ case are rejected on Windows (see
206
+ [Fail-closed resolution](#fail-closed-resolution)).
207
+
208
+ Values reach the command byte for byte: multi-line values (such as PEM keys),
209
+ `=`, quotes, `#`, `$` and non-ASCII characters are not escaped, quoted or
210
+ expanded.
211
+
212
+ ## Output
213
+
214
+ Your command owns stdout. All Envilder output goes to **stderr**, so
215
+ `envilder exec -- node print.js > out.json` writes only your command's output
216
+ to `out.json`. This holds in every environment, GitHub Actions included.
217
+
218
+ On success Envilder prints a single summary line, for example:
219
+
220
+ ```text
221
+ envilder: 2 secrets resolved (aws, profile=dev) → npm …
222
+ ```
223
+
224
+ The summary names your command by program name only, followed by `…` when it
225
+ has arguments (a command without arguments shows as `→ node`). Arguments are
226
+ never printed by Envilder because they can carry secrets; your command still
227
+ receives them unchanged.
228
+
229
+ The per-secret block is shown only when something fails. Secret values are
230
+ never printed; resolved values appear masked. The ASCII banner only appears in
231
+ `envilder --help`.
232
+
233
+ ### GitHub Actions masking
234
+
235
+ When `GITHUB_ACTIONS=true`, Envilder registers every resolved value with
236
+ GitHub's log masking (`::add-mask::`) so values your command prints are masked
237
+ in the job log. **Every registration is written to stderr before the command
238
+ starts**: Envilder waits for each write to complete, and if one cannot be
239
+ written the command is not started (exit code `125`). Outside GitHub Actions
240
+ nothing is emitted.
241
+
242
+ The registrations go to stderr, which the runner reads workflow commands from
243
+ just like stdout, because writing them to stdout would put the secret values
244
+ into any file your command's output is redirected to. stdout therefore carries
245
+ only your command's output.
246
+
247
+ Limitations:
248
+
249
+ * Envilder's stderr must reach the runner for the masks to be registered: do
250
+ not redirect the stderr of `envilder exec` away from the step log (for
251
+ example with `2> file` or `2>/dev/null`).
252
+ * The runner reads stdout and stderr through separate pipes, so strict
253
+ ordering between the two streams in the job log cannot be guaranteed.
254
+ Envilder guarantees what it controls: the registrations are written before
255
+ the command starts.
256
+
257
+ ```yaml
258
+ - run: npx envilder exec -- npm test
259
+ ```
260
+
261
+ ## Signals
262
+
263
+ * **Ctrl+C** in an interactive terminal: the terminal already sends `SIGINT` to
264
+ your command, so Envilder does not forward it a second time. Envilder stays
265
+ alive until your command exits and returns its exit code. A `SIGINT` sent to
266
+ Envilder when it is not attached to a terminal is forwarded.
267
+ Envilder decides this by checking whether its **stdin** is a terminal. With
268
+ piped stdin (`producer | envilder exec -- app`) a Ctrl+C in the terminal can
269
+ therefore reach your command twice: once from the terminal and once
270
+ forwarded by Envilder. On Windows a forwarded `SIGINT` terminates the
271
+ command instead of interrupting it.
272
+ * **`SIGTERM` and `SIGHUP`** (for example from `docker stop`, Kubernetes or a
273
+ process manager): Envilder forwards the signal to your command and **waits
274
+ for it to exit, with no timeout of its own**. Escalating to `SIGKILL` after a
275
+ grace period is left to the process manager.
276
+ * **What is guaranteed**: like `chamber exec` and `op run`, Envilder forwards
277
+ signals to its **direct child only**; it does not signal the child's process
278
+ group. Envilder never exits before its direct child, even when delivering a
279
+ signal to it fails (for example `EPERM`): it keeps waiting for the command
280
+ to exit. Stopping the processes that child started is the child's
281
+ responsibility: a launcher (`npm`, a shell script) that exits on `SIGTERM`
282
+ without stopping its own children can leave them running, on any operating
283
+ system. On Windows the same applies to `.cmd`/`.bat` shims such as `npm`: a
284
+ forwarded signal terminates the `cmd.exe` shim and the shim's own child may
285
+ keep running. Console Ctrl+C and closing the console reach the whole console
286
+ group.
287
+ * stdin, stdout and stderr are inherited and the TTY is preserved, so
288
+ interactive commands (REPLs, shells, prompts) work as usual.
289
+
290
+ ## Not a sandbox
291
+
292
+ Exec mode removes the `.env` file from disk. **It does not isolate the
293
+ process.**
294
+
295
+ * Your command and **every process it starts** have the secrets in their
296
+ environment and can read them. That includes any tool or AI coding agent that
297
+ runs `env`, `printenv` or similar through it.
298
+ * On Linux, other processes running as the same user can read
299
+ `/proc/<pid>/environ`.
300
+ * Exec mode does not restrict network access, file access or what your command
301
+ does with the values.
302
+
303
+ Only run commands you trust with the secrets you map.
304
+
305
+ ## What exec mode does not do
306
+
307
+ * **No live refresh.** Values are resolved once, when the command starts.
308
+ * **No `.env` fallback or merge.** Exec mode never reads a `.env` file, even if
309
+ one exists in the current directory, and never creates one.
310
+ * **No temporary files.** Nothing is written to the working directory, the OS
311
+ temp directory or any Envilder configuration directory.
312
+ * The GitHub Action and the runtime SDKs do not offer exec mode. The SDKs
313
+ already resolve secrets in-process.
@@ -6,6 +6,15 @@ export declare class Startup {
6
6
  constructor();
7
7
  static build(): Startup;
8
8
  configureServices(): this;
9
+ /**
10
+ * Wires the services specific to `envilder exec`: its handler, a logger that keeps
11
+ * stdout free for the child, the process runner, and the GitHub Actions
12
+ * secret masker when running inside a workflow. Call it before
13
+ * `configureInfrastructure`, which only binds the defaults left unbound.
14
+ */
15
+ configureExec(options: {
16
+ githubActions: boolean;
17
+ }): this;
9
18
  configureInfrastructure(config?: MapFileConfig, options?: InfrastructureOptions): this;
10
19
  create(): Container;
11
20
  getServiceProvider(): Container;
@@ -1 +1 @@
1
- {"version":3,"file":"Startup.d.ts","sourceRoot":"","sources":["../../../../src/envilder/apps/cli/Startup.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AACxE,OAAO,EAGL,KAAK,qBAAqB,EAC3B,MAAM,qCAAqC,CAAC;AAE7C,qBAAa,OAAO;IAClB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IAEtC,cAEC;IAED,MAAM,CAAC,KAAK,IAAI,OAAO,CAEtB;IAED,iBAAiB,IAAI,IAAI,CAGxB;IAED,uBAAuB,CACrB,MAAM,CAAC,EAAE,aAAa,EACtB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CAGN;IAED,MAAM,IAAI,SAAS,CAElB;IAED,kBAAkB,IAAI,SAAS,CAE9B;CACF"}
1
+ {"version":3,"file":"Startup.d.ts","sourceRoot":"","sources":["../../../../src/envilder/apps/cli/Startup.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AAWxE,OAAO,EAGL,KAAK,qBAAqB,EAC3B,MAAM,qCAAqC,CAAC;AAE7C,qBAAa,OAAO;IAClB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IAEtC,cAEC;IAED,MAAM,CAAC,KAAK,IAAI,OAAO,CAEtB;IAED,iBAAiB,IAAI,IAAI,CAGxB;IAED;;;;;OAKG;IACH,aAAa,CAAC,OAAO,EAAE;QAAE,aAAa,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CA2BvD;IAED,uBAAuB,CACrB,MAAM,CAAC,EAAE,aAAa,EACtB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CAGN;IAED,MAAM,IAAI,SAAS,CAElB;IAED,kBAAkB,IAAI,SAAS,CAE9B;CACF"}