@maverickcer/env-cap 0.6.0 → 0.7.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.
- package/ADOPTION.md +144 -0
- package/AGENTS.md +146 -0
- package/CHANGELOG.md +449 -0
- package/CODE_OF_CONDUCT.md +124 -0
- package/CODE_REVIEW.md +200 -0
- package/CONTRIBUTING.md +131 -0
- package/GUIDE.md +1214 -0
- package/PROMPT.md +89 -0
- package/README.md +92 -200
- package/RELEASING.md +160 -0
- package/SECURITY.md +270 -0
- package/SUPPORT.md +76 -0
- package/VERSIONING.md +118 -0
- package/benchmarks/READING-BENCHMARKS.md +197 -0
- package/benchmarks/README.md +126 -0
- package/benchmarks/WRITING-BENCHMARKS.md +252 -0
- package/benchmarks/performance-buildtime/BENCHMARKS.md +889 -0
- package/benchmarks/performance-runtime/BENCHMARKS.md +1988 -0
- package/dist/.dts/_ipc/build-fs.d.ts +53 -0
- package/dist/.dts/_ipc/build-fs.d.ts.map +1 -0
- package/dist/.dts/_ipc/compiler-api.d.ts +17 -0
- package/dist/.dts/_ipc/compiler-api.d.ts.map +1 -0
- package/dist/.dts/_ipc/display-path.d.ts +27 -0
- package/dist/.dts/_ipc/display-path.d.ts.map +1 -0
- package/dist/.dts/_ipc/generated-banner.d.ts +58 -0
- package/dist/.dts/_ipc/generated-banner.d.ts.map +1 -0
- package/dist/.dts/_ipc/glob.d.ts +22 -0
- package/dist/.dts/_ipc/glob.d.ts.map +1 -0
- package/dist/.dts/_ipc/no-node-fs.d.ts +35 -0
- package/dist/.dts/_ipc/no-node-fs.d.ts.map +1 -0
- package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts +134 -0
- package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts.map +1 -0
- package/dist/.dts/_ipc/typescript.d.ts +20 -0
- package/dist/.dts/_ipc/typescript.d.ts.map +1 -0
- package/dist/.dts/build/compatibility.d.ts.map +1 -1
- package/dist/.dts/build/compiler-api.d.ts +3 -6
- package/dist/.dts/build/compiler-api.d.ts.map +1 -1
- package/dist/.dts/build/display-path.d.ts +3 -21
- package/dist/.dts/build/display-path.d.ts.map +1 -1
- package/dist/.dts/build/generated-banner.d.ts +21 -42
- package/dist/.dts/build/generated-banner.d.ts.map +1 -1
- package/dist/.dts/build/glob.d.ts +3 -15
- package/dist/.dts/build/glob.d.ts.map +1 -1
- package/dist/.dts/build/index.d.ts +3 -3
- package/dist/.dts/build/link.d.ts.map +1 -1
- package/dist/.dts/build/merge-documentation.d.ts +35 -0
- package/dist/.dts/build/merge-documentation.d.ts.map +1 -0
- package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts +11 -112
- package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts.map +1 -1
- package/dist/.dts/build/types.d.ts +4 -53
- package/dist/.dts/build/types.d.ts.map +1 -1
- package/dist/.dts/build/typescript.d.ts +3 -17
- package/dist/.dts/build/typescript.d.ts.map +1 -1
- package/dist/.dts/eslint-plugin/glob.d.ts +4 -15
- package/dist/.dts/eslint-plugin/glob.d.ts.map +1 -1
- package/dist/.dts/eslint-plugin/index.d.ts +1 -1
- package/dist/.dts/eslint-plugin/no-node-fs.d.ts +8 -18
- package/dist/.dts/eslint-plugin/no-node-fs.d.ts.map +1 -1
- package/dist/.dts/eslint-plugin/no-raw-process-env.d.ts.map +1 -1
- package/dist/{build-H4KFV44Z.js → build-F3RQS7VE.js} +218 -63
- package/dist/build-F3RQS7VE.js.map +1 -0
- package/dist/build.cjs +257 -102
- package/dist/build.cjs.map +1 -1
- package/dist/build.js +256 -101
- package/dist/build.js.map +1 -1
- package/dist/{chunk-7GVPOHDU.js → chunk-QKIQ3LZP.js} +2 -2
- package/dist/cli/index.js +36 -29
- package/dist/cli/index.js.map +1 -1
- package/dist/eslint-plugin/index.cjs +95 -54
- package/dist/eslint-plugin/index.cjs.map +1 -1
- package/dist/eslint-plugin/index.js +94 -53
- package/dist/eslint-plugin/index.js.map +1 -1
- package/examples/README.md +95 -0
- package/package.json +53 -19
- package/skills/env-cap/SKILL.md +91 -0
- package/skills/env-cap/references/api.md +220 -0
- package/specs/architecture.md +634 -0
- package/specs/decisions/0001-runtime-documentation-separation.md +197 -0
- package/specs/decisions/0002-static-analysis-never-execution.md +233 -0
- package/specs/decisions/0003-no-global-env-object.md +172 -0
- package/specs/decisions/0004-no-client-server-package-split.md +116 -0
- package/specs/decisions/0005-warn-not-throw-by-default.md +93 -0
- package/specs/decisions/0006-self-redacting-contracts.md +124 -0
- package/specs/decisions/0007-processor-not-transformer.md +109 -0
- package/specs/decisions/0008-gzip-size-budget.md +173 -0
- package/specs/decisions/0009-exclusive-groups-are-always-errors.md +139 -0
- package/specs/decisions/0010-dependency-ownership-engine-scope-boundary.md +100 -0
- package/specs/decisions/0011-shared-discovery-compute-atomic-write-non-atomic.md +104 -0
- package/specs/decisions/0012-live-expiration-overrides-not-ast-functions.md +145 -0
- package/specs/decisions/0013-json-output-is-a-versioned-mirror.md +136 -0
- package/specs/decisions/0014-cross-package-schema-discovery.md +206 -0
- package/specs/decisions/0015-security-backport-window.md +60 -0
- package/specs/decisions/0016-check-mode-compute-before-compare-never-partial-write.md +113 -0
- package/specs/decisions/0017-eslint-plugin-entry-point.md +113 -0
- package/specs/decisions/0018-rotation-alert-issue-on-non-pr-runs.md +104 -0
- package/specs/decisions/0019-published-json-schema-generated-from-types.md +100 -0
- package/specs/decisions/0020-declaration-maps-via-separate-tsc-pass.md +101 -0
- package/specs/decisions/0021-manifest-change-report-persisted-snapshot.md +177 -0
- package/specs/decisions/0022-validation-contexts.md +267 -0
- package/specs/decisions/0023-tsconfig-path-alias-resolution.md +182 -0
- package/specs/decisions/0024-fact-model-architecture.md +144 -0
- package/specs/decisions/0025-contract-model-json-projection.md +105 -0
- package/specs/decisions/0026-finding-model-unifies-four-families.md +109 -0
- package/specs/decisions/0027-dependency-model-fact-shape-not-engine-access.md +98 -0
- package/specs/decisions/0028-ownership-model-shared-effective-owner.md +85 -0
- package/specs/decisions/0029-lifecycle-model-deprecation-rename-fields.md +98 -0
- package/specs/decisions/0030-change-model-wraps-manifest-change-report.md +97 -0
- package/specs/decisions/0031-evidence-entry-point.md +85 -0
- package/specs/decisions/0032-evidence-projection-provenance-mechanism.md +120 -0
- package/specs/decisions/0033-reference-projections-live-in-examples.md +81 -0
- package/specs/decisions/0034-three-tier-examples-restructuring.md +85 -0
- package/specs/decisions/0035-documentenv-metadata-generalization-and-compliance-fields.md +85 -0
- package/specs/decisions/0036-exact-source-position-evidence.md +122 -0
- package/specs/decisions/0037-developer-declared-dynamic-access-citations.md +114 -0
- package/specs/decisions/0038-always-computed-evidence-model-backs-generate-check-docs.md +244 -0
- package/specs/decisions/0039-scanner-local-dataflow-boundary.md +160 -0
- package/specs/decisions/0040-library-surfaces-do-not-acquire-node-fs.md +156 -0
- package/specs/decisions/0041-dual-package-hazard-checked-documented.md +75 -0
- package/specs/decisions/0042-init-cli-subcommand-scaffolds-only.md +95 -0
- package/specs/decisions/0043-env-cap-resolver-relocated-and-duplicated.md +71 -0
- package/specs/decisions/0044-strict-escalates-every-warning-family.md +88 -0
- package/specs/decisions/0045-promote-experimental-surfaces-to-stable.md +103 -0
- package/specs/decisions/0046-cli-restricted-to-runtime-and-evidence-output.md +177 -0
- package/specs/decisions/0047-supported-toolchain-node-22-and-typescript-5-6.md +30 -0
- package/specs/decisions/0048-eslint-plugin-does-not-vendor-typescript-eslint.md +25 -0
- package/specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md +87 -0
- package/specs/decisions/0050-a-variable-declared-twice-is-documented-once.md +55 -0
- package/specs/generated-artifacts.md +104 -0
- package/specs/migrations/README.md +30 -0
- package/specs/migrations/from-centralized-schema.md +503 -0
- package/specs/migrations/from-dotenv.md +352 -0
- package/specs/migrations/from-envalid.md +482 -0
- package/specs/migrations/from-process-env.md +398 -0
- package/specs/migrations/from-t3-env.md +416 -0
- package/specs/migrations/from-zod.md +303 -0
- package/dist/build-H4KFV44Z.js.map +0 -1
- /package/dist/{chunk-7GVPOHDU.js.map → chunk-QKIQ3LZP.js.map} +0 -0
|
@@ -0,0 +1,352 @@
|
|
|
1
|
+
# Migrating from dotenv
|
|
2
|
+
|
|
3
|
+
`dotenv` is one of the most common ways applications load environment variables.
|
|
4
|
+
|
|
5
|
+
A typical application starts with:
|
|
6
|
+
|
|
7
|
+
```ts
|
|
8
|
+
import "dotenv/config"
|
|
9
|
+
|
|
10
|
+
const databaseUrl = process.env.DATABASE_URL
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
This approach is intentionally simple:
|
|
14
|
+
|
|
15
|
+
- load values from a `.env` file
|
|
16
|
+
- expose them through `process.env`
|
|
17
|
+
- allow application code to consume them
|
|
18
|
+
|
|
19
|
+
`dotenv` solves environment loading. It does not solve:
|
|
20
|
+
|
|
21
|
+
- validation
|
|
22
|
+
- ownership
|
|
23
|
+
- discoverability
|
|
24
|
+
- lifecycle tracking
|
|
25
|
+
- configuration documentation
|
|
26
|
+
|
|
27
|
+
`env-cap` is designed to add those capabilities while allowing existing environment loading workflows to remain unchanged.
|
|
28
|
+
|
|
29
|
+
## Migration goals
|
|
30
|
+
|
|
31
|
+
Migrating from `dotenv` does not require replacing how secrets are injected.
|
|
32
|
+
|
|
33
|
+
You can continue using:
|
|
34
|
+
|
|
35
|
+
- `.env` files locally
|
|
36
|
+
- Docker environment variables
|
|
37
|
+
- Kubernetes secrets
|
|
38
|
+
- cloud provider environment configuration
|
|
39
|
+
- CI/CD injected variables
|
|
40
|
+
|
|
41
|
+
`env-cap` operates after values are loaded.
|
|
42
|
+
|
|
43
|
+
The migration path is:
|
|
44
|
+
|
|
45
|
+
1. Keep `dotenv` responsible for loading values.
|
|
46
|
+
2. Create capability-owned environment schemas.
|
|
47
|
+
3. Replace direct `process.env` access with validated contracts.
|
|
48
|
+
4. Add documentation metadata when needed.
|
|
49
|
+
5. Generate configuration artifacts through build tooling.
|
|
50
|
+
|
|
51
|
+
## Before: direct process.env access
|
|
52
|
+
|
|
53
|
+
A common application structure:
|
|
54
|
+
|
|
55
|
+
```ts
|
|
56
|
+
import "dotenv/config"
|
|
57
|
+
|
|
58
|
+
const stripeKey = process.env.STRIPE_SECRET_KEY
|
|
59
|
+
|
|
60
|
+
if (!stripeKey) {
|
|
61
|
+
throw new Error("Missing Stripe key")
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
initializeStripe(stripeKey)
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
As applications grow, environment usage becomes distributed:
|
|
68
|
+
|
|
69
|
+
```text
|
|
70
|
+
src/
|
|
71
|
+
|
|
72
|
+
├── payments/
|
|
73
|
+
│ └── stripe.ts -> process.env.STRIPE_SECRET_KEY
|
|
74
|
+
|
|
75
|
+
├── database/
|
|
76
|
+
│ └── connection.ts -> process.env.DATABASE_URL
|
|
77
|
+
|
|
78
|
+
├── cache/
|
|
79
|
+
│ └── redis.ts -> process.env.REDIS_URL
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
This creates several problems:
|
|
83
|
+
|
|
84
|
+
- validation logic is duplicated
|
|
85
|
+
- ownership is unclear
|
|
86
|
+
- variables can disappear from documentation
|
|
87
|
+
- unused variables remain after capabilities are removed
|
|
88
|
+
|
|
89
|
+
## After: capability-owned environment contracts
|
|
90
|
+
|
|
91
|
+
Move configuration requirements alongside the capability that uses them.
|
|
92
|
+
|
|
93
|
+
Example:
|
|
94
|
+
|
|
95
|
+
```ts
|
|
96
|
+
// features/payments/env.schema.ts
|
|
97
|
+
|
|
98
|
+
import { createEnv, documentEnv } from "@maverickcer/env-cap"
|
|
99
|
+
|
|
100
|
+
const paymentsSchema = {
|
|
101
|
+
STRIPE_SECRET_KEY: {
|
|
102
|
+
validator(value: string) {
|
|
103
|
+
return value.startsWith("sk_") || 'Expected a key starting with "sk_".'
|
|
104
|
+
},
|
|
105
|
+
},
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
export const paymentsEnv = createEnv(paymentsSchema, {
|
|
109
|
+
name: "payments",
|
|
110
|
+
})
|
|
111
|
+
|
|
112
|
+
documentEnv(paymentsSchema, {
|
|
113
|
+
owner: "payments-team",
|
|
114
|
+
variables: {
|
|
115
|
+
STRIPE_SECRET_KEY: {
|
|
116
|
+
description: "Stripe API credential used for payment processing",
|
|
117
|
+
},
|
|
118
|
+
},
|
|
119
|
+
})
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
The capability now owns its configuration:
|
|
123
|
+
|
|
124
|
+
```ts
|
|
125
|
+
import { paymentsEnv } from "./env.schema"
|
|
126
|
+
|
|
127
|
+
initializeStripe(paymentsEnv.STRIPE_SECRET_KEY)
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
## dotenv still loads the values
|
|
131
|
+
|
|
132
|
+
`env-cap` does not replace `dotenv`.
|
|
133
|
+
|
|
134
|
+
The loading flow remains:
|
|
135
|
+
|
|
136
|
+
```text
|
|
137
|
+
.env file
|
|
138
|
+
|
|
|
139
|
+
v
|
|
140
|
+
dotenv
|
|
141
|
+
|
|
|
142
|
+
v
|
|
143
|
+
process.env
|
|
144
|
+
|
|
|
145
|
+
v
|
|
146
|
+
env-cap validation
|
|
147
|
+
|
|
|
148
|
+
v
|
|
149
|
+
capability-owned environment contract
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
Example startup:
|
|
153
|
+
|
|
154
|
+
```ts
|
|
155
|
+
import "dotenv/config"
|
|
156
|
+
import { validateEnv } from "@maverickcer/env-cap"
|
|
157
|
+
import { manifest } from "./generated/env.manifest"
|
|
158
|
+
|
|
159
|
+
await validateEnv({
|
|
160
|
+
manifest,
|
|
161
|
+
values: process.env,
|
|
162
|
+
})
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
After validation:
|
|
166
|
+
|
|
167
|
+
```ts
|
|
168
|
+
paymentsEnv.STRIPE_SECRET_KEY
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
returns the validated value.
|
|
172
|
+
|
|
173
|
+
## Migrating incrementally
|
|
174
|
+
|
|
175
|
+
A complete rewrite is unnecessary.
|
|
176
|
+
|
|
177
|
+
### Step 1: Find existing environment usage
|
|
178
|
+
|
|
179
|
+
Search for:
|
|
180
|
+
|
|
181
|
+
```ts
|
|
182
|
+
process.env
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
Identify which capability owns each variable.
|
|
186
|
+
|
|
187
|
+
Example:
|
|
188
|
+
|
|
189
|
+
```ts
|
|
190
|
+
process.env.STRIPE_SECRET_KEY
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
belongs with:
|
|
194
|
+
|
|
195
|
+
```text
|
|
196
|
+
features/payments/
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
not a global configuration file.
|
|
200
|
+
|
|
201
|
+
### Step 2: Create capability schemas
|
|
202
|
+
|
|
203
|
+
Move variables into capability-owned schemas:
|
|
204
|
+
|
|
205
|
+
```text
|
|
206
|
+
features/
|
|
207
|
+
|
|
208
|
+
├── payments/
|
|
209
|
+
│ └── env.schema.ts
|
|
210
|
+
|
|
211
|
+
├── database/
|
|
212
|
+
│ └── env.schema.ts
|
|
213
|
+
|
|
214
|
+
└── notifications/
|
|
215
|
+
└── env.schema.ts
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
### Step 3: Replace direct access
|
|
219
|
+
|
|
220
|
+
Before:
|
|
221
|
+
|
|
222
|
+
```ts
|
|
223
|
+
const key = process.env.STRIPE_SECRET_KEY
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
After:
|
|
227
|
+
|
|
228
|
+
```ts
|
|
229
|
+
const key = paymentsEnv.STRIPE_SECRET_KEY
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
The capability now receives a validated value instead of an unknown string.
|
|
233
|
+
|
|
234
|
+
### Step 4: Add documentation metadata
|
|
235
|
+
|
|
236
|
+
Once ownership is established:
|
|
237
|
+
|
|
238
|
+
```ts
|
|
239
|
+
documentEnv(paymentsSchema, {
|
|
240
|
+
owner: "payments-team",
|
|
241
|
+
variables: {
|
|
242
|
+
STRIPE_SECRET_KEY: {
|
|
243
|
+
description: "Stripe production API credential",
|
|
244
|
+
expiresAt: "2027-01-01T00:00:00Z",
|
|
245
|
+
},
|
|
246
|
+
},
|
|
247
|
+
})
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
The same source that defines ownership can now generate operational documentation.
|
|
251
|
+
|
|
252
|
+
## Handling existing `.env.example` files
|
|
253
|
+
|
|
254
|
+
Many projects maintain:
|
|
255
|
+
|
|
256
|
+
```text
|
|
257
|
+
.env.example
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
manually:
|
|
261
|
+
|
|
262
|
+
```env
|
|
263
|
+
DATABASE_URL=
|
|
264
|
+
STRIPE_SECRET_KEY=
|
|
265
|
+
REDIS_URL=
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
As contracts are migrated, `env-cap` can generate this artifact from discovered schemas.
|
|
269
|
+
|
|
270
|
+
This allows:
|
|
271
|
+
|
|
272
|
+
- fewer missing variables
|
|
273
|
+
- fewer stale entries
|
|
274
|
+
- documentation closer to implementation
|
|
275
|
+
|
|
276
|
+
The generated file should be treated as a development artifact, not a source of secret values.
|
|
277
|
+
|
|
278
|
+
## Handling validation libraries
|
|
279
|
+
|
|
280
|
+
If your project already uses another validator, you do not need to remove it immediately.
|
|
281
|
+
|
|
282
|
+
Examples:
|
|
283
|
+
|
|
284
|
+
- Zod
|
|
285
|
+
- Joi
|
|
286
|
+
- Yup
|
|
287
|
+
- custom validators
|
|
288
|
+
|
|
289
|
+
The migration can focus first on ownership:
|
|
290
|
+
|
|
291
|
+
```ts
|
|
292
|
+
createEnv({
|
|
293
|
+
STRIPE_SECRET_KEY: {
|
|
294
|
+
validator(value) {
|
|
295
|
+
return existingValidationFunction(value)
|
|
296
|
+
},
|
|
297
|
+
},
|
|
298
|
+
})
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
The purpose of `env-cap` is not to replace every validation strategy. It provides a structure for organizing configuration ownership and visibility.
|
|
302
|
+
|
|
303
|
+
## When to keep dotenv alone
|
|
304
|
+
|
|
305
|
+
`dotenv` may be sufficient when:
|
|
306
|
+
|
|
307
|
+
- the application is small
|
|
308
|
+
- environment variables are few
|
|
309
|
+
- one team owns the entire application
|
|
310
|
+
- configuration changes are infrequent
|
|
311
|
+
|
|
312
|
+
Adding additional structure has a cost.
|
|
313
|
+
|
|
314
|
+
`env-cap` is designed for applications where configuration management becomes a coordination problem between developers, teams, and platform operations.
|
|
315
|
+
|
|
316
|
+
## Summary
|
|
317
|
+
|
|
318
|
+
Migrating from `dotenv` changes the role of environment variables.
|
|
319
|
+
|
|
320
|
+
Before:
|
|
321
|
+
|
|
322
|
+
```text
|
|
323
|
+
.env
|
|
324
|
+
|
|
|
325
|
+
v
|
|
326
|
+
process.env
|
|
327
|
+
|
|
|
328
|
+
v
|
|
329
|
+
application code
|
|
330
|
+
```
|
|
331
|
+
|
|
332
|
+
After:
|
|
333
|
+
|
|
334
|
+
```text
|
|
335
|
+
.env
|
|
336
|
+
|
|
|
337
|
+
v
|
|
338
|
+
dotenv
|
|
339
|
+
|
|
|
340
|
+
v
|
|
341
|
+
process.env
|
|
342
|
+
|
|
|
343
|
+
v
|
|
344
|
+
capability-owned env contracts
|
|
345
|
+
|
|
|
346
|
+
v
|
|
347
|
+
validated application code
|
|
348
|
+
```
|
|
349
|
+
|
|
350
|
+
`dotenv` remains responsible for loading configuration.
|
|
351
|
+
|
|
352
|
+
`env-cap` adds ownership, validation, and operational visibility without requiring a new secret-management system or deployment workflow.
|