@maverickcer/env-cap 0.7.7 → 0.8.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 (183) hide show
  1. package/ADOPTION.md +4 -4
  2. package/AGENTS.md +2 -3
  3. package/CHANGELOG.md +27 -0
  4. package/CODE_REVIEW.md +1 -1
  5. package/CONTRIBUTING.md +1 -1
  6. package/GUIDE.md +12 -12
  7. package/README.md +11 -12
  8. package/VERSIONING.md +2 -1
  9. package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts +3 -4
  10. package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts.map +1 -1
  11. package/dist/.dts/build/assemble-project.d.ts +3 -3
  12. package/dist/.dts/build/change-model.d.ts +9 -11
  13. package/dist/.dts/build/change-model.d.ts.map +1 -1
  14. package/dist/.dts/build/check-artifacts.d.ts +5 -6
  15. package/dist/.dts/build/check-artifacts.d.ts.map +1 -1
  16. package/dist/.dts/build/citation-verification.d.ts +6 -7
  17. package/dist/.dts/build/citation-verification.d.ts.map +1 -1
  18. package/dist/.dts/build/contract-model.d.ts +7 -8
  19. package/dist/.dts/build/contract-model.d.ts.map +1 -1
  20. package/dist/.dts/build/deep-equal.d.ts +3 -3
  21. package/dist/.dts/build/deep-freeze.d.ts +5 -7
  22. package/dist/.dts/build/deep-freeze.d.ts.map +1 -1
  23. package/dist/.dts/build/dependency-model.d.ts +2 -2
  24. package/dist/.dts/build/dependency-model.d.ts.map +1 -1
  25. package/dist/.dts/build/discover.d.ts +6 -6
  26. package/dist/.dts/build/discover.d.ts.map +1 -1
  27. package/dist/.dts/build/env-example.d.ts +6 -7
  28. package/dist/.dts/build/env-example.d.ts.map +1 -1
  29. package/dist/.dts/build/errors.d.ts +4 -4
  30. package/dist/.dts/build/evidence-cache.d.ts +12 -14
  31. package/dist/.dts/build/evidence-cache.d.ts.map +1 -1
  32. package/dist/.dts/build/evidence-model.d.ts +6 -7
  33. package/dist/.dts/build/evidence-model.d.ts.map +1 -1
  34. package/dist/.dts/build/evidence-reference.d.ts +6 -6
  35. package/dist/.dts/build/evidence-reference.d.ts.map +1 -1
  36. package/dist/.dts/build/exclusive-group.d.ts +3 -3
  37. package/dist/.dts/build/finding-model.d.ts +12 -13
  38. package/dist/.dts/build/finding-model.d.ts.map +1 -1
  39. package/dist/.dts/build/generate-documentation.d.ts +6 -7
  40. package/dist/.dts/build/generate-documentation.d.ts.map +1 -1
  41. package/dist/.dts/build/generate-evidence.d.ts +13 -15
  42. package/dist/.dts/build/generate-evidence.d.ts.map +1 -1
  43. package/dist/.dts/build/generate-manifest.d.ts +14 -16
  44. package/dist/.dts/build/generate-manifest.d.ts.map +1 -1
  45. package/dist/.dts/build/generated-banner.d.ts +3 -3
  46. package/dist/.dts/build/governance-fields.d.ts +3 -3
  47. package/dist/.dts/build/humanize-key.d.ts +3 -3
  48. package/dist/.dts/build/lifecycle-model.d.ts +3 -3
  49. package/dist/.dts/build/literal-eval.d.ts +2 -2
  50. package/dist/.dts/build/literal-eval.d.ts.map +1 -1
  51. package/dist/.dts/build/live-expirations.d.ts +9 -9
  52. package/dist/.dts/build/manifest.d.ts +7 -8
  53. package/dist/.dts/build/manifest.d.ts.map +1 -1
  54. package/dist/.dts/build/merge-documentation.d.ts +4 -5
  55. package/dist/.dts/build/merge-documentation.d.ts.map +1 -1
  56. package/dist/.dts/build/resolution/resolve-import.d.ts +8 -9
  57. package/dist/.dts/build/resolution/resolve-import.d.ts.map +1 -1
  58. package/dist/.dts/build/resolution/resolve-within-root.d.ts +4 -4
  59. package/dist/.dts/build/sarif.d.ts +9 -11
  60. package/dist/.dts/build/sarif.d.ts.map +1 -1
  61. package/dist/.dts/build/source-position.d.ts +14 -17
  62. package/dist/.dts/build/source-position.d.ts.map +1 -1
  63. package/dist/.dts/build/usage-report.d.ts +16 -17
  64. package/dist/.dts/build/usage-report.d.ts.map +1 -1
  65. package/dist/.dts/cli/filesystem.d.ts.map +1 -1
  66. package/dist/.dts/eslint-plugin/glob.d.ts +2 -2
  67. package/dist/.dts/eslint-plugin/index.d.ts +2 -1
  68. package/dist/.dts/eslint-plugin/index.d.ts.map +1 -1
  69. package/dist/.dts/eslint-plugin/no-node-fs.d.ts +5 -5
  70. package/dist/.dts/eslint-plugin/no-raw-process-env.d.ts +4 -4
  71. package/dist/.dts/evidence/define-projection.d.ts +6 -6
  72. package/dist/.dts/runtime/create.d.ts +2 -3
  73. package/dist/.dts/runtime/create.d.ts.map +1 -1
  74. package/dist/.dts/runtime/errors.d.ts +7 -8
  75. package/dist/.dts/runtime/errors.d.ts.map +1 -1
  76. package/dist/.dts/runtime/index.d.ts +2 -2
  77. package/dist/.dts/runtime/types.d.ts +18 -20
  78. package/dist/.dts/runtime/types.d.ts.map +1 -1
  79. package/dist/.dts/runtime/validate.d.ts +2 -2
  80. package/dist/.dts/runtime/validate.d.ts.map +1 -1
  81. package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts +3 -4
  82. package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts.map +1 -1
  83. package/dist/.dts7/build/assemble-project.d.ts +3 -3
  84. package/dist/.dts7/build/change-model.d.ts +9 -11
  85. package/dist/.dts7/build/change-model.d.ts.map +1 -1
  86. package/dist/.dts7/build/check-artifacts.d.ts +5 -6
  87. package/dist/.dts7/build/check-artifacts.d.ts.map +1 -1
  88. package/dist/.dts7/build/citation-verification.d.ts +6 -7
  89. package/dist/.dts7/build/citation-verification.d.ts.map +1 -1
  90. package/dist/.dts7/build/contract-model.d.ts +7 -8
  91. package/dist/.dts7/build/contract-model.d.ts.map +1 -1
  92. package/dist/.dts7/build/deep-equal.d.ts +3 -3
  93. package/dist/.dts7/build/deep-freeze.d.ts +5 -7
  94. package/dist/.dts7/build/deep-freeze.d.ts.map +1 -1
  95. package/dist/.dts7/build/dependency-model.d.ts +2 -2
  96. package/dist/.dts7/build/dependency-model.d.ts.map +1 -1
  97. package/dist/.dts7/build/discover.d.ts +6 -6
  98. package/dist/.dts7/build/discover.d.ts.map +1 -1
  99. package/dist/.dts7/build/env-example.d.ts +6 -7
  100. package/dist/.dts7/build/env-example.d.ts.map +1 -1
  101. package/dist/.dts7/build/errors.d.ts +4 -4
  102. package/dist/.dts7/build/evidence-cache.d.ts +12 -14
  103. package/dist/.dts7/build/evidence-cache.d.ts.map +1 -1
  104. package/dist/.dts7/build/evidence-model.d.ts +6 -7
  105. package/dist/.dts7/build/evidence-model.d.ts.map +1 -1
  106. package/dist/.dts7/build/evidence-reference.d.ts +6 -6
  107. package/dist/.dts7/build/evidence-reference.d.ts.map +1 -1
  108. package/dist/.dts7/build/exclusive-group.d.ts +3 -3
  109. package/dist/.dts7/build/finding-model.d.ts +12 -13
  110. package/dist/.dts7/build/finding-model.d.ts.map +1 -1
  111. package/dist/.dts7/build/generate-documentation.d.ts +6 -7
  112. package/dist/.dts7/build/generate-documentation.d.ts.map +1 -1
  113. package/dist/.dts7/build/generate-evidence.d.ts +13 -15
  114. package/dist/.dts7/build/generate-evidence.d.ts.map +1 -1
  115. package/dist/.dts7/build/generate-manifest.d.ts +14 -16
  116. package/dist/.dts7/build/generate-manifest.d.ts.map +1 -1
  117. package/dist/.dts7/build/generated-banner.d.ts +3 -3
  118. package/dist/.dts7/build/governance-fields.d.ts +3 -3
  119. package/dist/.dts7/build/humanize-key.d.ts +3 -3
  120. package/dist/.dts7/build/lifecycle-model.d.ts +3 -3
  121. package/dist/.dts7/build/literal-eval.d.ts +2 -2
  122. package/dist/.dts7/build/literal-eval.d.ts.map +1 -1
  123. package/dist/.dts7/build/live-expirations.d.ts +9 -9
  124. package/dist/.dts7/build/manifest.d.ts +7 -8
  125. package/dist/.dts7/build/manifest.d.ts.map +1 -1
  126. package/dist/.dts7/build/merge-documentation.d.ts +4 -5
  127. package/dist/.dts7/build/merge-documentation.d.ts.map +1 -1
  128. package/dist/.dts7/build/resolution/resolve-import.d.ts +8 -9
  129. package/dist/.dts7/build/resolution/resolve-import.d.ts.map +1 -1
  130. package/dist/.dts7/build/resolution/resolve-within-root.d.ts +4 -4
  131. package/dist/.dts7/build/sarif.d.ts +9 -11
  132. package/dist/.dts7/build/sarif.d.ts.map +1 -1
  133. package/dist/.dts7/build/source-position.d.ts +14 -17
  134. package/dist/.dts7/build/source-position.d.ts.map +1 -1
  135. package/dist/.dts7/build/usage-report.d.ts +16 -17
  136. package/dist/.dts7/build/usage-report.d.ts.map +1 -1
  137. package/dist/.dts7/cli/filesystem.d.ts.map +1 -1
  138. package/dist/.dts7/eslint-plugin/glob.d.ts +2 -2
  139. package/dist/.dts7/eslint-plugin/index.d.ts +2 -1
  140. package/dist/.dts7/eslint-plugin/index.d.ts.map +1 -1
  141. package/dist/.dts7/eslint-plugin/no-node-fs.d.ts +5 -5
  142. package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts +4 -4
  143. package/dist/.dts7/evidence/define-projection.d.ts +6 -6
  144. package/dist/.dts7/runtime/create.d.ts +2 -3
  145. package/dist/.dts7/runtime/create.d.ts.map +1 -1
  146. package/dist/.dts7/runtime/errors.d.ts +7 -8
  147. package/dist/.dts7/runtime/errors.d.ts.map +1 -1
  148. package/dist/.dts7/runtime/index.d.ts +2 -2
  149. package/dist/.dts7/runtime/types.d.ts +18 -20
  150. package/dist/.dts7/runtime/types.d.ts.map +1 -1
  151. package/dist/.dts7/runtime/validate.d.ts +2 -2
  152. package/dist/.dts7/runtime/validate.d.ts.map +1 -1
  153. package/dist/{build-33O5SDTC.js → build-Z76NCC65.js} +7 -10
  154. package/dist/build-Z76NCC65.js.map +1 -0
  155. package/dist/build.cjs +6 -9
  156. package/dist/build.cjs.map +1 -1
  157. package/dist/build.js +6 -9
  158. package/dist/build.js.map +1 -1
  159. package/dist/{chunk-4D67AQFY.js → chunk-JRCMG4FQ.js} +2 -2
  160. package/dist/cli/index.js +3 -3
  161. package/dist/cli/index.js.map +1 -1
  162. package/dist/eslint-plugin/index.cjs.map +1 -1
  163. package/dist/eslint-plugin/index.js.map +1 -1
  164. package/dist/evidence.cjs.map +1 -1
  165. package/dist/evidence.js.map +1 -1
  166. package/dist/index.cjs.map +1 -1
  167. package/dist/index.js.map +1 -1
  168. package/dist/node.cjs.map +1 -1
  169. package/dist/node.js.map +1 -1
  170. package/package.json +6 -4
  171. package/schemas/env-cap-report.schema.json +11 -11
  172. package/skills/env-cap/SKILL.md +1 -1
  173. package/skills/env-cap/references/api.md +1 -1
  174. package/specs/architecture.md +6 -6
  175. package/specs/migrations/README.md +9 -9
  176. package/specs/migrations/from-centralized-schema.md +28 -28
  177. package/specs/migrations/from-dotenv.md +11 -11
  178. package/specs/migrations/from-envalid.md +16 -16
  179. package/specs/migrations/from-process-env.md +19 -19
  180. package/specs/migrations/from-t3-env.md +24 -24
  181. package/specs/migrations/from-zod.md +21 -21
  182. package/dist/build-33O5SDTC.js.map +0 -1
  183. /package/dist/{chunk-4D67AQFY.js.map → chunk-JRCMG4FQ.js.map} +0 -0
@@ -1,6 +1,6 @@
1
1
  # Migrating from a Centralized Environment Schema
2
2
 
3
- This guide explains how to migrate from a centralized environment configuration model into capability-owned environment contracts.
3
+ This guide explains how to migrate from a centralized environment configuration model into feature-owned environment contracts.
4
4
 
5
5
  Examples of centralized schemas include:
6
6
 
@@ -26,15 +26,15 @@ Centralized schemas are a reasonable starting point. They provide a clear locati
26
26
 
27
27
  As applications grow, however, the centralized file becomes a shared ownership boundary:
28
28
 
29
- - Every capability change modifies the same file.
29
+ - Every feature change modifies the same file.
30
30
  - Teams become dependent on whoever owns the schema.
31
- - Removing capabilities requires finding unused configuration manually.
32
- - Configuration ownership becomes separated from capability ownership.
31
+ - Removing features requires finding unused configuration manually.
32
+ - Configuration ownership becomes separated from feature ownership.
33
33
  - Merge conflicts increase as the application grows.
34
34
 
35
35
  `env-cap` does not replace your validation system. It changes where environment ownership lives.
36
36
 
37
- You can continue using Zod, Valibot, Joi, custom validators, or simple functions inside capability contracts.
37
+ You can continue using Zod, Valibot, Joi, custom validators, or simple functions inside feature contracts.
38
38
 
39
39
  The migration goal is:
40
40
 
@@ -42,7 +42,7 @@ The migration goal is:
42
42
  centralized configuration
43
43
  |
44
44
  v
45
- capability-owned contracts
45
+ feature-owned contracts
46
46
  |
47
47
  v
48
48
  generated project-wide visibility
@@ -78,7 +78,7 @@ export const env = createConfig({
78
78
  })
79
79
  ```
80
80
 
81
- Every capability imports the same object:
81
+ Every feature imports the same object:
82
82
 
83
83
  ```ts
84
84
  import { env } from "./env"
@@ -94,13 +94,13 @@ The problem is not the validation.
94
94
 
95
95
  The problem is ownership.
96
96
 
97
- The database capability owns `DATABASE_URL`, but the database configuration lives somewhere else.
97
+ The database feature owns `DATABASE_URL`, but the database configuration lives somewhere else.
98
98
 
99
99
  ---
100
100
 
101
101
  ## Migration strategy
102
102
 
103
- Migrate one capability at a time.
103
+ Migrate one feature at a time.
104
104
 
105
105
  Do not move every variable into `env-cap` immediately.
106
106
 
@@ -134,7 +134,7 @@ The application can temporarily support both approaches.
134
134
 
135
135
  ## Step 1: Identify ownership
136
136
 
137
- For each variable, determine which capability requires it.
137
+ For each variable, determine which feature requires it.
138
138
 
139
139
  Example centralized schema:
140
140
 
@@ -160,13 +160,13 @@ Ownership should follow usage, not technical category.
160
160
 
161
161
  A variable is not "database configuration" because it contains `DATABASE`.
162
162
 
163
- It belongs to the capability that defines how it is consumed.
163
+ It belongs to the feature that defines how it is consumed.
164
164
 
165
165
  ---
166
166
 
167
- ## Step 2: Create capability schemas
167
+ ## Step 2: Create feature schemas
168
168
 
169
- Create a schema next to the capability.
169
+ Create a schema next to the feature.
170
170
 
171
171
  Example:
172
172
 
@@ -199,7 +199,7 @@ documentEnv(paymentsSchema, {
199
199
  })
200
200
  ```
201
201
 
202
- The capability now owns its configuration.
202
+ The feature now owns its configuration.
203
203
 
204
204
  ---
205
205
 
@@ -233,7 +233,7 @@ paymentsEnv
233
233
  payments schema
234
234
  ```
235
235
 
236
- The capability no longer depends on a global configuration object.
236
+ The feature no longer depends on a global configuration object.
237
237
 
238
238
  ---
239
239
 
@@ -302,7 +302,7 @@ await generateEnvManifest({
302
302
  This allows tooling to answer:
303
303
 
304
304
  - Which variables exist?
305
- - Which capability owns them?
305
+ - Which feature owns them?
306
306
  - Which variables are undocumented?
307
307
  - Which variables are expiring?
308
308
  - Which variables have possible conflicts?
@@ -317,11 +317,11 @@ The platform view remains centralized.
317
317
 
318
318
  A common migration concern is:
319
319
 
320
- > "What happens if multiple capabilities use the same environment variable?"
320
+ > "What happens if multiple features use the same environment variable?"
321
321
 
322
322
  The answer depends on whether the value has the same meaning.
323
323
 
324
- If multiple capabilities consume the same value with identical requirements, create a shared ownership module:
324
+ If multiple features consume the same value with identical requirements, create a shared ownership module:
325
325
 
326
326
  ```text
327
327
  features/
@@ -329,7 +329,7 @@ features/
329
329
  └── env.schema.ts
330
330
  ```
331
331
 
332
- Other capabilities import the database contract:
332
+ Other features import the database contract:
333
333
 
334
334
  ```ts
335
335
  import { databaseEnv } from "../database/env.schema"
@@ -337,15 +337,15 @@ import { databaseEnv } from "../database/env.schema"
337
337
  databaseEnv.DATABASE_URL
338
338
  ```
339
339
 
340
- If different capabilities interpret the same raw value differently, keep those interpretations local.
340
+ If different features interpret the same raw value differently, keep those interpretations local.
341
341
 
342
342
  Example:
343
343
 
344
344
  ```ts
345
- // metrics capability
345
+ // metrics feature
346
346
  REPORT_INTERVAL_MS -> number
347
347
 
348
- // logging capability
348
+ // logging feature
349
349
  REPORT_INTERVAL_MS -> string identifier
350
350
  ```
351
351
 
@@ -353,7 +353,7 @@ Both consume the same underlying environment value, but their application requir
353
353
 
354
354
  A centralized schema must choose one global representation.
355
355
 
356
- Capability contracts allow each consumer to define its own validated view.
356
+ Feature contracts allow each consumer to define its own validated view.
357
357
 
358
358
  ---
359
359
 
@@ -411,7 +411,7 @@ features/
411
411
  └── env.schema.ts
412
412
  ```
413
413
 
414
- Configuration should follow capability ownership.
414
+ Configuration should follow feature ownership.
415
415
 
416
416
  ---
417
417
 
@@ -432,7 +432,7 @@ This recreates the same coupling:
432
432
  env.payments.STRIPE_SECRET_KEY
433
433
  ```
434
434
 
435
- The capability import itself should define the dependency.
435
+ The feature import itself should define the dependency.
436
436
 
437
437
  ---
438
438
 
@@ -481,9 +481,9 @@ After migration:
481
481
 
482
482
  | Responsibility | Location |
483
483
  | ------------------ | ------------------- |
484
- | Variable ownership | Capability schema |
485
- | Validation logic | Capability schema |
486
- | Runtime access | Capability contract |
484
+ | Variable ownership | Feature schema |
485
+ | Validation logic | Feature schema |
486
+ | Runtime access | Feature contract |
487
487
  | Documentation | `documentEnv()` |
488
488
  | Project visibility | Generated artifacts |
489
489
  | Platform reporting | Build tooling |
@@ -43,7 +43,7 @@ You can continue using:
43
43
  The migration path is:
44
44
 
45
45
  1. Keep `dotenv` responsible for loading values.
46
- 2. Create capability-owned environment schemas.
46
+ 2. Create feature-owned environment schemas.
47
47
  3. Replace direct `process.env` access with validated contracts.
48
48
  4. Add documentation metadata when needed.
49
49
  5. Generate configuration artifacts through build tooling.
@@ -84,11 +84,11 @@ This creates several problems:
84
84
  - validation logic is duplicated
85
85
  - ownership is unclear
86
86
  - variables can disappear from documentation
87
- - unused variables remain after capabilities are removed
87
+ - unused variables remain after features are removed
88
88
 
89
- ## After: capability-owned environment contracts
89
+ ## After: feature-owned environment contracts
90
90
 
91
- Move configuration requirements alongside the capability that uses them.
91
+ Move configuration requirements alongside the feature that uses them.
92
92
 
93
93
  Example:
94
94
 
@@ -119,7 +119,7 @@ documentEnv(paymentsSchema, {
119
119
  })
120
120
  ```
121
121
 
122
- The capability now owns its configuration:
122
+ The feature now owns its configuration:
123
123
 
124
124
  ```ts
125
125
  import { paymentsEnv } from "./env.schema"
@@ -146,7 +146,7 @@ process.env
146
146
  env-cap validation
147
147
  |
148
148
  v
149
- capability-owned environment contract
149
+ feature-owned environment contract
150
150
  ```
151
151
 
152
152
  Example startup:
@@ -182,7 +182,7 @@ Search for:
182
182
  process.env
183
183
  ```
184
184
 
185
- Identify which capability owns each variable.
185
+ Identify which feature owns each variable.
186
186
 
187
187
  Example:
188
188
 
@@ -198,9 +198,9 @@ features/payments/
198
198
 
199
199
  not a global configuration file.
200
200
 
201
- ### Step 2: Create capability schemas
201
+ ### Step 2: Create feature schemas
202
202
 
203
- Move variables into capability-owned schemas:
203
+ Move variables into feature-owned schemas:
204
204
 
205
205
  ```text
206
206
  features/
@@ -229,7 +229,7 @@ After:
229
229
  const key = paymentsEnv.STRIPE_SECRET_KEY
230
230
  ```
231
231
 
232
- The capability now receives a validated value instead of an unknown string.
232
+ The feature now receives a validated value instead of an unknown string.
233
233
 
234
234
  ### Step 4: Add documentation metadata
235
235
 
@@ -341,7 +341,7 @@ dotenv
341
341
  process.env
342
342
  |
343
343
  v
344
- capability-owned env contracts
344
+ feature-owned env contracts
345
345
  |
346
346
  v
347
347
  validated application code
@@ -13,7 +13,7 @@ The migration is not a replacement of validation capabilities. `envalid` and
13
13
 
14
14
  `env-cap` can use the same validation approach you already have today,
15
15
  including custom validators and processors. The primary change is moving
16
- from a centralized configuration object to capability-owned environment
16
+ from a centralized configuration object to feature-owned environment
17
17
  contracts.
18
18
 
19
19
  ## Before: centralized environment validation
@@ -50,18 +50,18 @@ src/
50
50
  └── notifications/
51
51
  ```
52
52
 
53
- Every capability that requires configuration modifies the same file.
53
+ Every feature that requires configuration modifies the same file.
54
54
 
55
55
  Common consequences:
56
56
 
57
57
  - configuration ownership becomes unclear
58
- - unrelated capabilities modify the same schema
59
- - removing capabilities requires cleaning up centralized variables
58
+ - unrelated features modify the same schema
59
+ - removing features requires cleaning up centralized variables
60
60
  - platform teams need separate tooling to understand ownership
61
61
 
62
- ## After: capability-owned contracts
62
+ ## After: feature-owned contracts
63
63
 
64
- With `env-cap`, move configuration ownership into the capability that uses
64
+ With `env-cap`, move configuration ownership into the feature that uses
65
65
  it.
66
66
 
67
67
  Example:
@@ -76,7 +76,7 @@ src/
76
76
  └── env.schema.ts
77
77
  ```
78
78
 
79
- The database capability owns database configuration:
79
+ The database feature owns database configuration:
80
80
 
81
81
  ```ts
82
82
  // database/env.schema.ts
@@ -96,7 +96,7 @@ export const databaseEnv = createEnv(databaseSchema, {
96
96
  })
97
97
  ```
98
98
 
99
- The payments capability owns payment configuration:
99
+ The payments feature owns payment configuration:
100
100
 
101
101
  ```ts
102
102
  // payments/env.schema.ts
@@ -116,7 +116,7 @@ export const paymentsEnv = createEnv(paymentsSchema, {
116
116
  })
117
117
  ```
118
118
 
119
- Application code imports configuration from the capability that owns it:
119
+ Application code imports configuration from the feature that owns it:
120
120
 
121
121
  ```ts
122
122
  import { databaseEnv } from "./database/env.schema"
@@ -161,7 +161,7 @@ The package only validates and exposes configuration.
161
161
 
162
162
  ---
163
163
 
164
- ### Step 2: Identify capability ownership
164
+ ### Step 2: Identify feature ownership
165
165
 
166
166
  Start by grouping existing variables by the code that consumes them.
167
167
 
@@ -252,7 +252,7 @@ PORT: {
252
252
 
253
253
  The important distinction is that transformation and validation are explicit.
254
254
 
255
- The runtime contract defines how the capability consumes the value.
255
+ The runtime contract defines how the feature consumes the value.
256
256
 
257
257
  ---
258
258
 
@@ -326,7 +326,7 @@ export function createPayment() {
326
326
  }
327
327
  ```
328
328
 
329
- Continue migrating capability by capability until the centralized environment object
329
+ Continue migrating feature by feature until the centralized environment object
330
330
  is no longer needed.
331
331
 
332
332
  ---
@@ -351,7 +351,7 @@ The difference is the ownership model.
351
351
 
352
352
  `env-cap` answers:
353
353
 
354
- > "Which capability owns this configuration, how is it validated, and how is it
354
+ > "Which feature owns this configuration, how is it validated, and how is it
355
355
  > operated over time?"
356
356
 
357
357
  ---
@@ -388,7 +388,7 @@ timeout: "5000"
388
388
  A library integration may require a string because it serializes directly into
389
389
  headers or configuration.
390
390
 
391
- Another capability may require:
391
+ Another feature may require:
392
392
 
393
393
  ```ts
394
394
  timeout: 5000
@@ -402,7 +402,7 @@ timeout + retryDelay
402
402
 
403
403
  The environment value is the same. The consumer requirement is different.
404
404
 
405
- `env-cap` allows each owning capability to define its own processing boundary:
405
+ `env-cap` allows each owning feature to define its own processing boundary:
406
406
 
407
407
  ```ts
408
408
  apiClientEnv.TIMEOUT
@@ -471,7 +471,7 @@ These tools solve environment parsing and validation.
471
471
 
472
472
  `env-cap` adds the organizational layer:
473
473
 
474
- - capability ownership
474
+ - feature ownership
475
475
  - static discovery
476
476
  - generated documentation
477
477
  - lifecycle visibility
@@ -10,7 +10,7 @@ const stripeKey = process.env.STRIPE_SECRET_KEY
10
10
  This approach is flexible and requires no additional tooling. However, as applications grow, direct `process.env` access creates several challenges:
11
11
 
12
12
  - Environment requirements are scattered throughout the codebase.
13
- - Validation logic is repeated across capabilities.
13
+ - Validation logic is repeated across features.
14
14
  - It is difficult to identify which part of the application owns a variable.
15
15
  - Removing unused configuration requires manually searching for references.
16
16
  - Platform teams lack a reliable inventory of application configuration.
@@ -26,7 +26,7 @@ process.env
26
26
  env-cap validation
27
27
  |
28
28
  v
29
- capability-owned environment contract
29
+ feature-owned environment contract
30
30
  |
31
31
  v
32
32
  application code
@@ -37,8 +37,8 @@ application code
37
37
  The recommended migration path is incremental:
38
38
 
39
39
  1. Find existing environment variable usage.
40
- 2. Group variables by the capability that consumes them.
41
- 3. Create capability-owned environment contracts.
40
+ 2. Group variables by the feature that consumes them.
41
+ 3. Create feature-owned environment contracts.
42
42
  4. Replace direct `process.env` reads with validated access.
43
43
  5. Generate project-wide configuration artifacts through build tooling.
44
44
 
@@ -86,9 +86,9 @@ process.env
86
86
 
87
87
  Any file can access any value.
88
88
 
89
- ## After: capability-owned environment contracts
89
+ ## After: feature-owned environment contracts
90
90
 
91
- Move configuration definitions next to the capability that uses them.
91
+ Move configuration definitions next to the feature that uses them.
92
92
 
93
93
  Example:
94
94
 
@@ -119,7 +119,7 @@ documentEnv(paymentsSchema, {
119
119
  })
120
120
  ```
121
121
 
122
- The capability now owns its requirement:
122
+ The feature now owns its requirement:
123
123
 
124
124
  ```ts
125
125
  import { paymentsEnv } from "./env.schema"
@@ -157,7 +157,7 @@ DATABASE_URL
157
157
 
158
158
  Do not move variables based only on their names. Move them based on the code that consumes them.
159
159
 
160
- ## Step 2: Create capability schemas
160
+ ## Step 2: Create feature schemas
161
161
 
162
162
  Create schemas alongside existing modules:
163
163
 
@@ -175,7 +175,7 @@ src/
175
175
  │ └── env.schema.ts
176
176
  ```
177
177
 
178
- Each schema defines only the variables required by that capability.
178
+ Each schema defines only the variables required by that feature.
179
179
 
180
180
  ## Step 3: Replace direct reads
181
181
 
@@ -191,7 +191,7 @@ After:
191
191
  const apiKey = paymentsEnv.STRIPE_SECRET_KEY
192
192
  ```
193
193
 
194
- The application no longer receives an unknown value. It receives a value that has passed the capability's validation rules.
194
+ The application no longer receives an unknown value. It receives a value that has passed the feature's validation rules.
195
195
 
196
196
  ## Step 4: Add startup validation
197
197
 
@@ -264,11 +264,11 @@ The validation remains near the code that understands the variable's purpose.
264
264
 
265
265
  A common concern during migration is:
266
266
 
267
- > "What if multiple capabilities use the same environment variable?"
267
+ > "What if multiple features use the same environment variable?"
268
268
 
269
269
  The answer depends on whether the variable represents the same concept.
270
270
 
271
- If multiple capabilities truly share the same configuration meaning:
271
+ If multiple features truly share the same configuration meaning:
272
272
 
273
273
  ```env
274
274
  LOG_LEVEL=info
@@ -281,13 +281,13 @@ loggingEnv.LOG_LEVEL
281
281
  apiEnv.LOG_LEVEL
282
282
  ```
283
283
 
284
- If capabilities process the same raw value differently, each capability can define its own contract:
284
+ If features process the same raw value differently, each feature can define its own contract:
285
285
 
286
286
  ```env
287
287
  CACHE_TIMEOUT=60000
288
288
  ```
289
289
 
290
- One capability may need:
290
+ One feature may need:
291
291
 
292
292
  ```ts
293
293
  cacheEnv.CACHE_TIMEOUT
@@ -355,7 +355,7 @@ src/
355
355
  └── env.schema.ts
356
356
  ```
357
357
 
358
- The environment requirements move with the capabilities that own them.
358
+ The environment requirements move with the features that own them.
359
359
 
360
360
  ## When direct process.env usage may be enough
361
361
 
@@ -370,12 +370,12 @@ Direct `process.env` access can be appropriate when:
370
370
 
371
371
  ## Summary
372
372
 
373
- Migrating from `process.env` changes configuration from an implicit global dependency into an explicit capability dependency.
373
+ Migrating from `process.env` changes configuration from an implicit global dependency into an explicit feature dependency.
374
374
 
375
375
  Before:
376
376
 
377
377
  ```text
378
- capability
378
+ feature
379
379
  |
380
380
  v
381
381
  process.env.SOME_VARIABLE
@@ -384,10 +384,10 @@ process.env.SOME_VARIABLE
384
384
  After:
385
385
 
386
386
  ```text
387
- capability
387
+ feature
388
388
  |
389
389
  v
390
- capabilityEnv.SOME_VARIABLE
390
+ featureEnv.SOME_VARIABLE
391
391
  |
392
392
  v
393
393
  validated configuration contract
@@ -32,7 +32,7 @@ This provides:
32
32
  The difference is architectural:
33
33
 
34
34
  - `t3-env` focuses on **validating an application's environment**.
35
- - `env-cap` focuses on **organizing configuration ownership across application capabilities**.
35
+ - `env-cap` focuses on **organizing configuration ownership across application features**.
36
36
 
37
37
  Both approaches solve real problems. The correct choice depends on the scale and structure of the application.
38
38
 
@@ -59,7 +59,7 @@ src/
59
59
 
60
60
  In this structure, a shared environment object is simple and effective.
61
61
 
62
- ## When capability ownership becomes important
62
+ ## When feature ownership becomes important
63
63
 
64
64
  As applications grow, configuration often follows business domains:
65
65
 
@@ -75,7 +75,7 @@ src/
75
75
  └── billing/
76
76
  ```
77
77
 
78
- Each capability has different owners, deployment concerns, and operational requirements.
78
+ Each feature has different owners, deployment concerns, and operational requirements.
79
79
 
80
80
  A centralized environment file becomes a shared coordination point:
81
81
 
@@ -93,7 +93,7 @@ env.ts
93
93
 
94
94
  The problem is not validation. The problem is ownership.
95
95
 
96
- Every capability change now modifies shared configuration code.
96
+ Every feature change now modifies shared configuration code.
97
97
 
98
98
  ## Migration strategy
99
99
 
@@ -102,8 +102,8 @@ Migrating from t3-env does not require removing Zod or rewriting validation logi
102
102
  The recommended migration is:
103
103
 
104
104
  1. Keep existing validation rules.
105
- 2. Move variables into capability-owned contracts.
106
- 3. Replace global `env` imports with capability-owned imports.
105
+ 2. Move variables into feature-owned contracts.
106
+ 3. Replace global `env` imports with feature-owned imports.
107
107
  4. Add documentation metadata where operational visibility is needed.
108
108
  5. Remove the centralized environment object after migration.
109
109
 
@@ -134,11 +134,11 @@ import { env } from "@/env"
134
134
  stripe.connect(env.STRIPE_SECRET_KEY)
135
135
  ```
136
136
 
137
- The capability depends on the application-wide environment object.
137
+ The feature depends on the application-wide environment object.
138
138
 
139
- ## After: capability-owned env-cap schema
139
+ ## After: feature-owned env-cap schema
140
140
 
141
- Move the configuration requirement into the owning capability:
141
+ Move the configuration requirement into the owning feature:
142
142
 
143
143
  ```ts
144
144
  // features/payments/env.schema.ts
@@ -181,7 +181,7 @@ stripe.connect(paymentsEnv.STRIPE_SECRET_KEY)
181
181
 
182
182
  The dependency is now explicit.
183
183
 
184
- The payments capability depends on payments configuration, not the entire application's configuration object.
184
+ The payments feature depends on payments configuration, not the entire application's configuration object.
185
185
 
186
186
  ## Reusing Zod validation
187
187
 
@@ -207,13 +207,13 @@ const paymentsSchema = {
207
207
 
208
208
  The responsibilities become:
209
209
 
210
- | Responsibility | Tool |
211
- | ---------------------- | -------------------- |
212
- | Environment validation | Zod |
213
- | Capability ownership | env-cap |
214
- | Runtime access | Capability contracts |
215
- | Documentation metadata | `documentEnv()` |
216
- | Project inventory | Build tooling |
210
+ | Responsibility | Tool |
211
+ | ---------------------- | ----------------- |
212
+ | Environment validation | Zod |
213
+ | Feature ownership | env-cap |
214
+ | Runtime access | Feature contracts |
215
+ | Documentation metadata | `documentEnv()` |
216
+ | Project inventory | Build tooling |
217
217
 
218
218
  ## Migrating client and server variables
219
219
 
@@ -298,7 +298,7 @@ export async function createPayment() {
298
298
  }
299
299
  ```
300
300
 
301
- The capability now declares its own configuration dependency.
301
+ The feature now declares its own configuration dependency.
302
302
 
303
303
  ## Handling shared variables
304
304
 
@@ -308,7 +308,7 @@ A centralized environment object assumes one global interpretation:
308
308
  env.SOME_VARIABLE
309
309
  ```
310
310
 
311
- However, different capabilities may require different transformations.
311
+ However, different features may require different transformations.
312
312
 
313
313
  Example:
314
314
 
@@ -316,7 +316,7 @@ Example:
316
316
  CACHE_TIMEOUT=60000
317
317
  ```
318
318
 
319
- A caching capability may require:
319
+ A caching feature may require:
320
320
 
321
321
  ```ts
322
322
  cacheEnv.CACHE_TIMEOUT
@@ -325,7 +325,7 @@ cacheEnv.CACHE_TIMEOUT
325
325
 
326
326
  because it performs calculations.
327
327
 
328
- A monitoring capability may require:
328
+ A monitoring feature may require:
329
329
 
330
330
  ```ts
331
331
  monitoringEnv.CACHE_TIMEOUT
@@ -336,7 +336,7 @@ because it reports configuration values.
336
336
 
337
337
  A single global object cannot represent both interpretations without choosing one as the default.
338
338
 
339
- Capability-owned contracts allow each capability to define the meaning it requires.
339
+ Feature-owned contracts allow each feature to define the meaning it requires.
340
340
 
341
341
  ## Generating project-wide visibility
342
342
 
@@ -367,7 +367,7 @@ t3-env may remain the better choice when:
367
367
 
368
368
  - your application has one configuration owner
369
369
  - the centralized schema stays maintainable
370
- - capability boundaries are not important
370
+ - feature boundaries are not important
371
371
  - documentation and lifecycle tracking are handled elsewhere
372
372
 
373
373
  `t3-env` is an excellent validation solution.
@@ -413,4 +413,4 @@ application
413
413
 
414
414
  > "Who owns these environment variables, where are they used, and how do we operate them as the system grows?"
415
415
 
416
- The two approaches can also coexist. Existing validation logic can remain while configuration ownership gradually moves closer to the capabilities that depend on it.
416
+ The two approaches can also coexist. Existing validation logic can remain while configuration ownership gradually moves closer to the features that depend on it.