envilder 0.14.0 → 0.15.1

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 (118) hide show
  1. package/README.md +55 -13
  2. package/ROADMAP.md +50 -23
  3. package/docs/SECURITY.md +35 -9
  4. package/docs/changelogs/cli.md +139 -3
  5. package/docs/changelogs/gha.md +45 -2
  6. package/docs/changelogs/sdk-dotnet.md +34 -2
  7. package/docs/changelogs/sdk-nodejs.md +22 -5
  8. package/docs/changelogs/sdk-python.md +19 -2
  9. package/docs/exec-command.md +492 -0
  10. package/lib/envilder/apps/cli/Startup.d.ts +9 -0
  11. package/lib/envilder/apps/cli/Startup.d.ts.map +1 -1
  12. package/lib/envilder/apps/cli/Startup.js +39 -0
  13. package/lib/envilder/apps/cli/Startup.js.map +1 -1
  14. package/lib/envilder/apps/cli/entry/Cli.d.ts.map +1 -1
  15. package/lib/envilder/apps/cli/entry/Cli.js +346 -13
  16. package/lib/envilder/apps/cli/entry/Cli.js.map +1 -1
  17. package/lib/envilder/apps/cli/errors/CliErrorPresenter.d.ts.map +1 -1
  18. package/lib/envilder/apps/cli/errors/CliErrorPresenter.js +4 -1
  19. package/lib/envilder/apps/cli/errors/CliErrorPresenter.js.map +1 -1
  20. package/lib/envilder/apps/cli/errors/ParseErrorRedactor.d.ts +33 -0
  21. package/lib/envilder/apps/cli/errors/ParseErrorRedactor.d.ts.map +1 -0
  22. package/lib/envilder/apps/cli/errors/ParseErrorRedactor.js +121 -0
  23. package/lib/envilder/apps/cli/errors/ParseErrorRedactor.js.map +1 -0
  24. package/lib/envilder/apps/cli/recovery/SsoLoginRecovery.d.ts +13 -0
  25. package/lib/envilder/apps/cli/recovery/SsoLoginRecovery.d.ts.map +1 -1
  26. package/lib/envilder/apps/cli/recovery/SsoLoginRecovery.js +29 -13
  27. package/lib/envilder/apps/cli/recovery/SsoLoginRecovery.js.map +1 -1
  28. package/lib/envilder/apps/shared/ContainerConfiguration.d.ts +2 -1
  29. package/lib/envilder/apps/shared/ContainerConfiguration.d.ts.map +1 -1
  30. package/lib/envilder/apps/shared/ContainerConfiguration.js +4 -2
  31. package/lib/envilder/apps/shared/ContainerConfiguration.js.map +1 -1
  32. package/lib/envilder/core/application/dispatch/DispatchActionCommand.d.ts +18 -1
  33. package/lib/envilder/core/application/dispatch/DispatchActionCommand.d.ts.map +1 -1
  34. package/lib/envilder/core/application/dispatch/DispatchActionCommand.js +17 -1
  35. package/lib/envilder/core/application/dispatch/DispatchActionCommand.js.map +1 -1
  36. package/lib/envilder/core/application/dispatch/DispatchActionCommandHandler.d.ts +9 -2
  37. package/lib/envilder/core/application/dispatch/DispatchActionCommandHandler.d.ts.map +1 -1
  38. package/lib/envilder/core/application/dispatch/DispatchActionCommandHandler.js +28 -3
  39. package/lib/envilder/core/application/dispatch/DispatchActionCommandHandler.js.map +1 -1
  40. package/lib/envilder/core/application/execWithSecrets/CommandLineFormatter.d.ts +13 -0
  41. package/lib/envilder/core/application/execWithSecrets/CommandLineFormatter.d.ts.map +1 -0
  42. package/lib/envilder/core/application/execWithSecrets/CommandLineFormatter.js +19 -0
  43. package/lib/envilder/core/application/execWithSecrets/CommandLineFormatter.js.map +1 -0
  44. package/lib/envilder/core/application/execWithSecrets/ExecWithSecretsCommand.d.ts +20 -0
  45. package/lib/envilder/core/application/execWithSecrets/ExecWithSecretsCommand.d.ts.map +1 -0
  46. package/lib/envilder/core/application/execWithSecrets/ExecWithSecretsCommand.js +19 -0
  47. package/lib/envilder/core/application/execWithSecrets/ExecWithSecretsCommand.js.map +1 -0
  48. package/lib/envilder/core/application/execWithSecrets/ExecWithSecretsCommandHandler.d.ts +61 -0
  49. package/lib/envilder/core/application/execWithSecrets/ExecWithSecretsCommandHandler.d.ts.map +1 -0
  50. package/lib/envilder/core/application/execWithSecrets/ExecWithSecretsCommandHandler.js +159 -0
  51. package/lib/envilder/core/application/execWithSecrets/ExecWithSecretsCommandHandler.js.map +1 -0
  52. package/lib/envilder/core/application/pullSecretsToEnv/PullSecretsToEnvCommandHandler.d.ts +1 -9
  53. package/lib/envilder/core/application/pullSecretsToEnv/PullSecretsToEnvCommandHandler.d.ts.map +1 -1
  54. package/lib/envilder/core/application/pullSecretsToEnv/PullSecretsToEnvCommandHandler.js +9 -79
  55. package/lib/envilder/core/application/pullSecretsToEnv/PullSecretsToEnvCommandHandler.js.map +1 -1
  56. package/lib/envilder/core/application/secretResolution/SecretResolver.d.ts +66 -0
  57. package/lib/envilder/core/application/secretResolution/SecretResolver.d.ts.map +1 -0
  58. package/lib/envilder/core/application/secretResolution/SecretResolver.js +132 -0
  59. package/lib/envilder/core/application/secretResolution/SecretResolver.js.map +1 -0
  60. package/lib/envilder/core/domain/ChildEnvironment.d.ts +22 -0
  61. package/lib/envilder/core/domain/ChildEnvironment.d.ts.map +1 -0
  62. package/lib/envilder/core/domain/ChildEnvironment.js +50 -0
  63. package/lib/envilder/core/domain/ChildEnvironment.js.map +1 -0
  64. package/lib/envilder/core/domain/ExecExitCode.d.ts +14 -0
  65. package/lib/envilder/core/domain/ExecExitCode.d.ts.map +1 -0
  66. package/lib/envilder/core/domain/ExecExitCode.js +23 -0
  67. package/lib/envilder/core/domain/ExecExitCode.js.map +1 -0
  68. package/lib/envilder/core/domain/OperationMode.d.ts +2 -1
  69. package/lib/envilder/core/domain/OperationMode.d.ts.map +1 -1
  70. package/lib/envilder/core/domain/OperationMode.js +1 -0
  71. package/lib/envilder/core/domain/OperationMode.js.map +1 -1
  72. package/lib/envilder/core/domain/errors/DomainErrors.d.ts +44 -0
  73. package/lib/envilder/core/domain/errors/DomainErrors.d.ts.map +1 -1
  74. package/lib/envilder/core/domain/errors/DomainErrors.js +57 -0
  75. package/lib/envilder/core/domain/errors/DomainErrors.js.map +1 -1
  76. package/lib/envilder/core/domain/ports/IProcessContext.d.ts +14 -0
  77. package/lib/envilder/core/domain/ports/IProcessContext.d.ts.map +1 -0
  78. package/lib/envilder/core/domain/ports/IProcessContext.js +2 -0
  79. package/lib/envilder/core/domain/ports/IProcessContext.js.map +1 -0
  80. package/lib/envilder/core/domain/ports/IProcessRunner.d.ts +27 -0
  81. package/lib/envilder/core/domain/ports/IProcessRunner.d.ts.map +1 -0
  82. package/lib/envilder/core/domain/ports/IProcessRunner.js +2 -0
  83. package/lib/envilder/core/domain/ports/IProcessRunner.js.map +1 -0
  84. package/lib/envilder/core/domain/ports/ISecretMasker.d.ts +7 -0
  85. package/lib/envilder/core/domain/ports/ISecretMasker.d.ts.map +1 -1
  86. package/lib/envilder/core/infrastructure/aws/AwsSecretProviderFactory.d.ts +5 -1
  87. package/lib/envilder/core/infrastructure/aws/AwsSecretProviderFactory.d.ts.map +1 -1
  88. package/lib/envilder/core/infrastructure/aws/AwsSecretProviderFactory.js +3 -2
  89. package/lib/envilder/core/infrastructure/aws/AwsSecretProviderFactory.js.map +1 -1
  90. package/lib/envilder/core/infrastructure/aws/AwsSsmSecretProvider.d.ts +6 -1
  91. package/lib/envilder/core/infrastructure/aws/AwsSsmSecretProvider.d.ts.map +1 -1
  92. package/lib/envilder/core/infrastructure/aws/AwsSsmSecretProvider.js +10 -3
  93. package/lib/envilder/core/infrastructure/aws/AwsSsmSecretProvider.js.map +1 -1
  94. package/lib/envilder/core/infrastructure/github/GitHubActionsSecretMasker.d.ts +22 -0
  95. package/lib/envilder/core/infrastructure/github/GitHubActionsSecretMasker.d.ts.map +1 -1
  96. package/lib/envilder/core/infrastructure/github/GitHubActionsSecretMasker.js +38 -1
  97. package/lib/envilder/core/infrastructure/github/GitHubActionsSecretMasker.js.map +1 -1
  98. package/lib/envilder/core/infrastructure/github/NoOpSecretMasker.d.ts +1 -0
  99. package/lib/envilder/core/infrastructure/github/NoOpSecretMasker.d.ts.map +1 -1
  100. package/lib/envilder/core/infrastructure/github/NoOpSecretMasker.js +3 -0
  101. package/lib/envilder/core/infrastructure/github/NoOpSecretMasker.js.map +1 -1
  102. package/lib/envilder/core/infrastructure/logger/StderrConsoleLogger.d.ts +11 -0
  103. package/lib/envilder/core/infrastructure/logger/StderrConsoleLogger.d.ts.map +1 -0
  104. package/lib/envilder/core/infrastructure/logger/StderrConsoleLogger.js +27 -0
  105. package/lib/envilder/core/infrastructure/logger/StderrConsoleLogger.js.map +1 -0
  106. package/lib/envilder/core/infrastructure/process/CrossSpawnProcessRunner.d.ts +15 -0
  107. package/lib/envilder/core/infrastructure/process/CrossSpawnProcessRunner.d.ts.map +1 -0
  108. package/lib/envilder/core/infrastructure/process/CrossSpawnProcessRunner.js +145 -0
  109. package/lib/envilder/core/infrastructure/process/CrossSpawnProcessRunner.js.map +1 -0
  110. package/lib/envilder/core/infrastructure/process/NodeProcessContext.d.ts +11 -0
  111. package/lib/envilder/core/infrastructure/process/NodeProcessContext.d.ts.map +1 -0
  112. package/lib/envilder/core/infrastructure/process/NodeProcessContext.js +18 -0
  113. package/lib/envilder/core/infrastructure/process/NodeProcessContext.js.map +1 -0
  114. package/lib/envilder/core/types.d.ts +6 -0
  115. package/lib/envilder/core/types.d.ts.map +1 -1
  116. package/lib/envilder/core/types.js +3 -0
  117. package/lib/envilder/core/types.js.map +1 -1
  118. package/package.json +15 -8
@@ -1,3 +1,17 @@
1
+ ## [0.5.2] - 2026-10-16
2
+
3
+ ### Fixed
4
+
5
+ * **AWS SSO / IAM Identity Center profiles resolve again**: The
6
+ `AWSSDK.SSO` and `AWSSDK.SSOOIDC` dependencies added in 0.4.1 were lost in
7
+ 0.5.0, so SSO profiles (via `WithProfile()` or `$config.profile`) could fail
8
+ with `Assembly AWSSDK.SSOOIDC could not be found` instead of resolving
9
+ credentials. Both packages are referenced again, and a regression test now
10
+ fails the build if the SDK stops shipping them
11
+ ([#364](https://github.com/macalbert/envilder/issues/364))
12
+
13
+ ---
14
+
1
15
  ## [0.5.1] - 2026-09-26
2
16
 
3
17
  ### Documentation
@@ -8,7 +22,7 @@
8
22
 
9
23
  ---
10
24
 
11
- ## [0.5.0] - 2026-06-26
25
+ ## [0.5.0] - 2026-07-11
12
26
 
13
27
  ### Added
14
28
 
@@ -26,6 +40,19 @@
26
40
 
27
41
  ---
28
42
 
43
+ ## [0.4.1] - 2026-06-25
44
+
45
+ ### Fixed
46
+
47
+ * **AWS SSO / assumed-role profiles now resolve at runtime**: Added the
48
+ `AWSSDK.SSO` and `AWSSDK.SSOOIDC` dependencies so SSO and IAM Identity
49
+ Center profiles (via `WithProfile()` or `$config.profile`) build their
50
+ credentials at runtime. Previously these profiles threw
51
+ `Assembly AWSSDK.SSOOIDC could not be found`
52
+ ([#364](https://github.com/macalbert/envilder/issues/364))
53
+
54
+ ---
55
+
29
56
  ## [0.4.0] - 2026-05-18
30
57
 
31
58
  ### Changed
@@ -159,7 +186,7 @@ may need to add them explicitly.
159
186
  ### Added
160
187
 
161
188
  * **Initial release**: Runtime library for loading secrets from AWS SSM Parameter Store or Azure Key Vault
162
- directly into .NET applications ([#147](https://github.com/macalbert/envilder/pull/147))
189
+ directly into .NET applications ([#146](https://github.com/macalbert/envilder/pull/146))
163
190
  * `EnvilderClient`: Resolves secrets from a map-file and returns them as a dictionary
164
191
  * `MapFileParser`: Parses `envilder.json` files with `$config` section and variable mappings
165
192
  * `SecretProviderFactory`: Creates the appropriate secret provider based on configuration
@@ -171,6 +198,11 @@ may need to add them explicitly.
171
198
  * Targets .NET Standard 2.0 (compatible with .NET 6+, .NET Framework 4.6.1+)
172
199
  * Published to NuGet as `Envilder`
173
200
 
201
+ ### Fixed
202
+
203
+ * **Default AWS region**: `SecretProviderFactory` provides a default AWS region
204
+ when none is configured ([#147](https://github.com/macalbert/envilder/pull/147))
205
+
174
206
  ### Testing
175
207
 
176
208
  * Unit tests with xUnit, NSubstitute, AwesomeAssertions, and AutoFixture
@@ -6,9 +6,15 @@
6
6
  now links to the changelog and to `envilder.com/docs/sdks/nodejs/` with UTM
7
7
  tags, so visits from npm to envilder.com can be measured
8
8
 
9
+ ### Dependencies
10
+
11
+ * Raise the minimum AWS SDK versions: `@aws-sdk/client-ssm` and
12
+ `@aws-sdk/credential-providers` now require `^3.1101.0` (previously
13
+ `^3.700.0`)
14
+
9
15
  ---
10
16
 
11
- ## [0.4.0] - 2026-06-26
17
+ ## [0.4.0] - 2026-07-11
12
18
 
13
19
  ### Added
14
20
 
@@ -24,10 +30,6 @@
24
30
  session token still throws `ExpiredCredentialsError`
25
31
  ([#379](https://github.com/macalbert/envilder/issues/379))
26
32
 
27
- ---
28
-
29
- ## [0.3.1] - 2026-06-26
30
-
31
33
  ### Fixed
32
34
 
33
35
  * **Honor the `profile` option for the AWS region, not just credentials**:
@@ -42,6 +44,19 @@
42
44
 
43
45
  ---
44
46
 
47
+ ## [0.3.1] - 2026-06-25
48
+
49
+ ### Fixed
50
+
51
+ * **AWS SSO / assumed-role profiles now resolve correctly**: `withProfile()`
52
+ and `$config.profile` now resolve credentials through the full AWS provider
53
+ chain (`fromNodeProviderChain`), including SSO token resolution. Previously
54
+ SSO and assumed-role profiles were silently ignored, falling back to the
55
+ default credentials
56
+ ([#364](https://github.com/macalbert/envilder/issues/364))
57
+
58
+ ---
59
+
45
60
  ## [0.3.0] - 2026-05-31
46
61
 
47
62
  ### Changed
@@ -91,6 +106,8 @@
91
106
  * **Initial release**: Node.js runtime SDK for loading secrets directly
92
107
  into `process.env` from a map file. Supports AWS SSM Parameter Store and
93
108
  Azure Key Vault
109
+ * **Batched AWS fetching**: Up to 10 SSM parameters per request
110
+ ([#170](https://github.com/macalbert/envilder/pull/170))
94
111
  * **Envilder facade**: `load()`, `resolveFile()`, `fromMapFile()` fluent
95
112
  builder for one-liner or fine-grained secret loading
96
113
  * **EnvilderClient**: Core resolver with `resolveSecrets()` and
@@ -1,3 +1,21 @@
1
+ ## [0.5.2] - 2026-10-22
2
+
3
+ ### Security
4
+
5
+ * Update `certifi` from 2026.2.25 to 2026.10.19 in the SDK lockfile to
6
+ resolve GHSA-6q48-6c7w-9gw2. `certifi` is a transitive dependency (via
7
+ `requests` in the Azure clients); the package's declared dependency ranges are
8
+ unchanged ([#609](https://github.com/macalbert/envilder/pull/609))
9
+
10
+ ### Dependencies
11
+
12
+ * Bump `pyjwt` from 2.13.0 to 2.15.0 in the SDK lockfile
13
+ ([#534](https://github.com/macalbert/envilder/pull/534))
14
+ * Bump `urllib3` from 2.7.0 to 2.8.0 in the SDK lockfile
15
+ ([#535](https://github.com/macalbert/envilder/pull/535))
16
+
17
+ ---
18
+
1
19
  ## [0.5.1] - 2026-09-26
2
20
 
3
21
  ### Documentation
@@ -8,7 +26,7 @@
8
26
 
9
27
  ---
10
28
 
11
- ## [0.5.0] - 2026-06-26
29
+ ## [0.5.0] - 2026-07-11
12
30
 
13
31
  ### Added
14
32
 
@@ -108,7 +126,6 @@
108
126
  * **Initial release**: Runtime library for loading secrets from AWS SSM Parameter Store or
109
127
  Azure Key Vault directly into Python applications
110
128
  ([#157](https://github.com/macalbert/envilder/pull/157))
111
- * `Envilder` facade: High-level entry point with `load()`, `resolve_file()`, and `from_map_file()` methods
112
129
  * `EnvilderClient`: Resolves secrets from a map-file and injects them into `os.environ`
113
130
  * `MapFileParser`: Parses `envilder.json` files with `$config` section and variable mappings
114
131
  * `SecretProviderFactory`: Creates the appropriate secret provider based on configuration
@@ -0,0 +1,492 @@
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
+ Envilder does not start an extra shell: arguments are passed to the command as
116
+ an argument list. Your own shell still parses the command line first, so quote
117
+ what it should not interpret. `'$DB_URL'` or `'&&'` in single quotes reach the
118
+ command literally, while an unquoted `$DB_URL` expands to your shell's value
119
+ (not the resolved secret) and an unquoted `&&` runs a second command outside
120
+ `envilder exec`. If you need shell features with the secrets, start a shell
121
+ explicitly:
122
+
123
+ ```bash
124
+ envilder exec -- sh -c 'echo $DB_URL'
125
+ ```
126
+
127
+ On Windows, npm-style `.cmd`/`.bat` shims such as `npm` and `npx` work without
128
+ enabling shell interpretation of the arguments. To do this, Envilder (through
129
+ `cross-spawn`) runs shims, and commands it cannot resolve to an executable,
130
+ via `cmd.exe /d /s /c` with every argument escaped. Two visible consequences:
131
+
132
+ * When the command does not exist, `cmd.exe` prints its own "is not
133
+ recognized as an internal or external command" line (in the system
134
+ language) before Envilder's `Command not found: <command>`. The exit code is
135
+ still `127`.
136
+ * `cmd.exe` builtins such as `echo` or `dir` resolve and run.
137
+
138
+ ## Common use cases
139
+
140
+ In every case Envilder passes the values to the command and the processes it
141
+ starts without creating a `.env` file, and the command's exit code becomes
142
+ Envilder's exit code. What the command does with the values afterwards is up
143
+ to it: Docker, for example, stores a container's environment in its on-disk
144
+ container metadata (visible with `docker inspect`) until the container is
145
+ removed, and a stopped `docker compose up` leaves its containers behind until
146
+ `docker compose down`. The paths follow the
147
+ `/<project>/<environment>/<service>/<key>` style used in
148
+ [envilder-examples](https://github.com/macalbert/envilder-examples).
149
+
150
+ ### Start LocalStack with its auth token
151
+
152
+ When you need it: LocalStack needs `LOCALSTACK_AUTH_TOKEN` and you do not want
153
+ the token in a `.env` file or in your shell history.
154
+
155
+ ```json
156
+ {
157
+ "LOCALSTACK_AUTH_TOKEN": "/envilder/development/localstack/authToken"
158
+ }
159
+ ```
160
+
161
+ With Docker Compose, reference the variable in `compose.yaml`. Compose
162
+ interpolates `${...}` from the environment it runs in, so no `.env` file is
163
+ needed:
164
+
165
+ ```yaml
166
+ services:
167
+ localstack:
168
+ image: localstack/localstack:stable
169
+ ports:
170
+ - "4566:4566"
171
+ environment:
172
+ LOCALSTACK_AUTH_TOKEN: ${LOCALSTACK_AUTH_TOKEN}
173
+ ```
174
+
175
+ ```bash
176
+ envilder exec -- docker compose up
177
+ ```
178
+
179
+ With plain Docker, `-e NAME` without a value copies the variable from the
180
+ environment of the `docker` client, so the token never appears on the command
181
+ line:
182
+
183
+ ```bash
184
+ envilder exec -- docker run --rm -e LOCALSTACK_AUTH_TOKEN -p 4566:4566 localstack/localstack:stable
185
+ ```
186
+
187
+ [envilder-examples](https://github.com/macalbert/envilder-examples) has the
188
+ same setup with Testcontainers (TypeScript, Python, .NET) and Aspire.
189
+
190
+ ### Integration tests that start containers
191
+
192
+ When you need it: your tests start containers (for example with
193
+ Testcontainers) and read a token or credentials from the environment
194
+ (`process.env`, `os.environ`, `Environment.GetEnvironmentVariable`) to pass
195
+ them in.
196
+
197
+ ```bash
198
+ envilder exec -- npm test
199
+ envilder exec -- dotnet test
200
+ envilder exec -- pytest
201
+ ```
202
+
203
+ A failing test run keeps its exit code, so CI still fails. If a secret cannot
204
+ be resolved, the tests do not start and the exit code is `125`.
205
+
206
+ ### Database migrations and one-off scripts
207
+
208
+ When you need it: a migration tool or a script needs `DATABASE_URL` once, and
209
+ you do not want the connection string on disk.
210
+
211
+ ```json
212
+ {
213
+ "DATABASE_URL": "/my-app/development/database/url"
214
+ }
215
+ ```
216
+
217
+ ```bash
218
+ envilder exec -- npx prisma migrate deploy
219
+ envilder exec -- python scripts/backfill.py
220
+ ```
221
+
222
+ Use `--map` to run the same command against another environment, for example
223
+ `envilder exec --map=config/envilder.staging.json -- npx prisma migrate deploy`.
224
+
225
+ ### Terraform and other IaC tools
226
+
227
+ When you need it: a Terraform input variable holds a secret. Terraform reads
228
+ `TF_VAR_<name>` environment variables as values for the input variable
229
+ `<name>`.
230
+
231
+ ```json
232
+ {
233
+ "TF_VAR_db_password": "/my-app/development/database/password"
234
+ }
235
+ ```
236
+
237
+ ```bash
238
+ envilder exec -- terraform plan
239
+ ```
240
+
241
+ Declare the variable with `sensitive = true` so Terraform hides it in plan
242
+ output. Terraform still stores values it writes into resources in its state,
243
+ so protect the state as usual.
244
+
245
+ ### Local dev server through package scripts
246
+
247
+ When you need it: everyone on the team should start the app with the same
248
+ secrets by running `npm run dev`.
249
+
250
+ ```json
251
+ {
252
+ "scripts": {
253
+ "dev": "envilder exec -- next dev"
254
+ }
255
+ }
256
+ ```
257
+
258
+ Add `envilder` as a dev dependency (`npm install --save-dev envilder`) so the
259
+ script finds it in `node_modules/.bin`.
260
+
261
+ ### A step in GitHub Actions
262
+
263
+ When you need it: one step of a workflow needs the secrets, and only that step.
264
+ Configure AWS credentials with OIDC, then run the command through
265
+ `npx envilder exec`:
266
+
267
+ ```yaml
268
+ permissions:
269
+ id-token: write # Required for OIDC
270
+ contents: read
271
+
272
+ steps:
273
+ - uses: actions/checkout@v5
274
+ - uses: aws-actions/configure-aws-credentials@v5
275
+ with:
276
+ role-to-assume: arn:aws:iam::123456789012:role/GitHubActionsRole
277
+ aws-region: us-east-1
278
+ - run: npx envilder exec -- npm test
279
+ ```
280
+
281
+ Resolved values are registered with GitHub's log masking before the command
282
+ starts, and the next steps do not see them. See
283
+ [GitHub Actions masking](#github-actions-masking).
284
+
285
+ ### Several commands with the same secrets
286
+
287
+ When you need it: you want to chain commands or keep working in a shell that
288
+ has the secrets.
289
+
290
+ ```bash
291
+ envilder exec -- sh -c 'npm run migrate && exec npm start'
292
+ envilder exec -- bash
293
+ ```
294
+
295
+ Quote the whole `sh -c` script in single quotes so your own shell does not run
296
+ `&&` outside `envilder exec` (see [No shell](#no-shell)). The `exec` before
297
+ the last command replaces the shell with it, so signals forwarded by Envilder
298
+ reach `npm start` directly. In the interactive shell every command you run sees
299
+ the secrets; type `exit` to leave it.
300
+
301
+ ## Exit codes
302
+
303
+ Exit codes follow GNU `env` and `docker run`, so you can tell an Envilder
304
+ failure apart from your command's own exit code:
305
+
306
+ | Code | Meaning |
307
+ | ---- | ------- |
308
+ | `n` | Your command exited with code `n` |
309
+ | `128 + n` | Your command was killed by signal `n` (for example `137` for `SIGKILL`) |
310
+ | `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`) |
311
+ | `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`) |
312
+ | `127` | The command was not found |
313
+
314
+ On Windows, a signal that Envilder forwards to the command is still reported
315
+ as a signal, so `128 + n` applies: `SIGTERM` gives `143`, `SIGINT` gives `130`,
316
+ and `SIGHUP` is reported as `SIGKILL`, giving `137`. A command terminated from
317
+ outside Envilder (for example by Task Manager or `taskkill /F`) typically exits
318
+ with code `1` instead.
319
+
320
+ Options written before `exec` are also an Envilder error (`125`); see
321
+ [Where the command starts](#where-the-command-starts-the----rule).
322
+
323
+ Other modes (pull and push) keep exiting with `1` on failure.
324
+
325
+ ## Fail-closed resolution
326
+
327
+ Pull mode warns and skips a secret that is missing or empty. **Exec mode never
328
+ starts the command with an incomplete set of secrets**: if any secret is
329
+ missing, empty or cannot be read (for example, access denied), the command is
330
+ not started, Envilder lists the affected variables with their masked paths and
331
+ exits with `125`.
332
+
333
+ Other conditions that stop the command from starting:
334
+
335
+ * A secret value contains a NUL byte, which cannot be passed in an environment
336
+ variable.
337
+ * The AWS credentials or SSO session expired. In an interactive terminal
338
+ Envilder offers to run `aws sso login` and then retries **only the secret
339
+ resolution**: your command is started at most once. If you decline or the
340
+ login fails, the exit code is `125`. The prompt and the login output go to
341
+ stderr, so the prompt also works when stdout is redirected
342
+ (`envilder exec -- node print.js > out.json`); it needs stdin and stderr to
343
+ be a terminal. Recovery only happens **before** the command starts: an SSO
344
+ or credentials error reported after that point is never retried, Envilder
345
+ prints `The command could not be supervised after it started: <reason>` and
346
+ exits with `125`.
347
+ * On Windows, the map file declares names that differ only by case (for
348
+ example `Path` and `PATH`). Windows treats them as the same variable, so
349
+ Envilder exits with `125` before any provider call instead of silently
350
+ dropping one. On Linux and macOS both names are kept.
351
+
352
+ A map file that declares no variables (only `$config`) is not an error: the
353
+ command starts with the inherited environment and Envilder prints
354
+ `Map file declares no variables.`
355
+
356
+ ## Environment composition
357
+
358
+ The command inherits the full environment of the shell that runs Envilder,
359
+ plus every variable declared in the map file.
360
+
361
+ **The map file wins.** When an inherited variable has the same name as a mapped
362
+ one, the command sees the value from the provider, and Envilder prints the
363
+ names (never the values) on stderr:
364
+
365
+ ```text
366
+ Overriding inherited variables: API_KEY
367
+ ```
368
+
369
+ On Windows, names are compared case-insensitively: an inherited `Path` and a
370
+ mapped `PATH` are the same variable, the mapped value wins, and the command
371
+ gets exactly one entry. Within the map file itself, names that differ only by
372
+ case are rejected on Windows (see
373
+ [Fail-closed resolution](#fail-closed-resolution)).
374
+
375
+ Values reach the command byte for byte: multi-line values (such as PEM keys),
376
+ `=`, quotes, `#`, `$` and non-ASCII characters are not escaped, quoted or
377
+ expanded.
378
+
379
+ ## Output
380
+
381
+ Your command owns stdout. All Envilder output goes to **stderr**, so
382
+ `envilder exec -- node print.js > out.json` writes only your command's output
383
+ to `out.json`. This holds in every environment, GitHub Actions included.
384
+
385
+ On success Envilder prints a single summary line, for example:
386
+
387
+ ```text
388
+ envilder: 2 secrets resolved (aws, profile=dev) → npm …
389
+ ```
390
+
391
+ The summary names your command by program name only, followed by `…` when it
392
+ has arguments (a command without arguments shows as `→ node`). Arguments are
393
+ never printed by Envilder because they can carry secrets; your command still
394
+ receives them unchanged.
395
+
396
+ The per-secret block is shown only when something fails. Secret values are
397
+ never printed; resolved values appear masked. The ASCII banner only appears in
398
+ `envilder --help`.
399
+
400
+ ### GitHub Actions masking
401
+
402
+ When `GITHUB_ACTIONS=true`, Envilder registers every resolved value with
403
+ GitHub's log masking (`::add-mask::`) so values your command prints are masked
404
+ in the job log. **Every registration is written to stderr before the command
405
+ starts**: Envilder waits for each write to complete, and if one cannot be
406
+ written the command is not started (exit code `125`). Outside GitHub Actions
407
+ nothing is emitted.
408
+
409
+ The registrations go to stderr, which the runner reads workflow commands from
410
+ just like stdout, because writing them to stdout would put the secret values
411
+ into any file your command's output is redirected to. stdout therefore carries
412
+ only your command's output.
413
+
414
+ Limitations:
415
+
416
+ * Envilder's stderr must reach the runner for the masks to be registered: do
417
+ not redirect the stderr of `envilder exec` away from the step log (for
418
+ example with `2> file` or `2>/dev/null`).
419
+ * The runner reads stdout and stderr through separate pipes, so strict
420
+ ordering between the two streams in the job log cannot be guaranteed.
421
+ Envilder guarantees what it controls: the registrations are written before
422
+ the command starts.
423
+
424
+ ```yaml
425
+ - run: npx envilder exec -- npm test
426
+ ```
427
+
428
+ ## Signals
429
+
430
+ * **Ctrl+C** in an interactive terminal: the terminal already sends `SIGINT` to
431
+ your command, so Envilder does not forward it a second time. Envilder stays
432
+ alive until your command exits and returns its exit code. A `SIGINT` sent to
433
+ Envilder when it is not attached to a terminal is forwarded.
434
+ Envilder decides this by checking whether its **stdin** is a terminal. With
435
+ piped stdin (`producer | envilder exec -- app`) a Ctrl+C in the terminal can
436
+ therefore reach your command twice: once from the terminal and once
437
+ forwarded by Envilder. On Windows a forwarded `SIGINT` terminates the
438
+ command instead of interrupting it.
439
+ * **`SIGTERM` and `SIGHUP`** (for example from `docker stop`, Kubernetes or a
440
+ process manager): Envilder forwards the signal to your command and **waits
441
+ for it to exit, with no timeout of its own**. Escalating to `SIGKILL` after a
442
+ grace period is left to the process manager.
443
+ * **What is guaranteed**: like `chamber exec` and `op run`, Envilder forwards
444
+ signals to its **direct child only**; it does not signal the child's process
445
+ group. Envilder never exits before its direct child, even when delivering a
446
+ signal to it fails (for example `EPERM`): it keeps waiting for the command
447
+ to exit. Stopping the processes that child started is the child's
448
+ responsibility: a launcher (`npm`, a shell script) that exits on `SIGTERM`
449
+ without stopping its own children can leave them running, on any operating
450
+ system. On Windows the same applies to `.cmd`/`.bat` shims such as `npm`: a
451
+ forwarded signal terminates the `cmd.exe` shim and the shim's own child may
452
+ keep running. Console Ctrl+C and closing the console reach the whole console
453
+ group.
454
+ * stdin, stdout and stderr are inherited and the TTY is preserved, so
455
+ interactive commands (REPLs, shells, prompts) work as usual.
456
+
457
+ ## Not a sandbox
458
+
459
+ Exec mode never creates a `.env` file, and it leaves any existing one
460
+ untouched: if you are moving from pull mode, delete your old `.env`
461
+ yourself. **It does not isolate the process.**
462
+
463
+ * Your command and **every process it starts** have the secrets in their
464
+ environment and can read them. That includes any tool or AI coding agent that
465
+ runs `env`, `printenv` or similar through it.
466
+ * On Linux, other processes running as the same user can read
467
+ `/proc/<pid>/environ`.
468
+ * Exec mode does not restrict network access, file access or what your command
469
+ does with the values.
470
+
471
+ Only run commands you trust with the secrets you map.
472
+
473
+ ## What exec mode does not do
474
+
475
+ * **No live refresh.** Values are resolved once, when the command starts.
476
+ * **No `.env` fallback or merge.** Exec mode never reads a `.env` file, even if
477
+ one exists in the current directory, and never creates one.
478
+ * **No temporary files.** Nothing is written to the working directory, the OS
479
+ temp directory or any Envilder configuration directory.
480
+ * The GitHub Action and the runtime SDKs do not offer exec mode. The SDKs
481
+ already resolve secrets in-process.
482
+
483
+ ## Examples
484
+
485
+ [envilder-examples](https://github.com/macalbert/envilder-examples) has runnable setups:
486
+
487
+ * The repository README starts LocalStack with `envilder exec docker run ...`,
488
+ passing the auth token from AWS SSM into the container without a `.env`
489
+ file. Docker itself keeps the container's environment in its metadata until
490
+ the container is removed.
491
+ * The [`cli`](https://github.com/macalbert/envilder-examples/tree/main/cli)
492
+ folder walks through push, pull and exec with `npx envilder`.
@@ -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"}