@maverickcer/env-cap 0.7.5 → 0.7.6

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 (278) hide show
  1. package/ADOPTION.md +12 -12
  2. package/AGENTS.md +85 -120
  3. package/CHANGELOG.md +27 -0
  4. package/CODE_REVIEW.md +5 -5
  5. package/CONTRIBUTING.md +5 -5
  6. package/GUIDE.md +42 -24
  7. package/README.md +52 -34
  8. package/RELEASING.md +78 -64
  9. package/SECURITY.md +15 -15
  10. package/VERSIONING.md +16 -15
  11. package/benchmarks/READING-BENCHMARKS.md +101 -85
  12. package/benchmarks/README.md +12 -9
  13. package/benchmarks/WRITING-BENCHMARKS.md +89 -79
  14. package/benchmarks/performance-buildtime/BENCHMARKS.md +20 -20
  15. package/benchmarks/performance-runtime/BENCHMARKS.md +107 -107
  16. package/dist/.dts/_ipc/build-fs.d.ts +3 -3
  17. package/dist/.dts/_ipc/build-fs.d.ts.map +1 -1
  18. package/dist/.dts/_ipc/display-path.d.ts +1 -1
  19. package/dist/.dts/_ipc/glob.d.ts +3 -2
  20. package/dist/.dts/_ipc/glob.d.ts.map +1 -1
  21. package/dist/.dts/_ipc/no-node-fs.d.ts +2 -2
  22. package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts +16 -16
  23. package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts.map +1 -1
  24. package/dist/.dts/_ipc/typescript.d.ts +4 -4
  25. package/dist/.dts/build/assemble-project.d.ts +14 -15
  26. package/dist/.dts/build/assemble-project.d.ts.map +1 -1
  27. package/dist/.dts/build/change-model.d.ts +14 -14
  28. package/dist/.dts/build/change-model.d.ts.map +1 -1
  29. package/dist/.dts/build/check-artifacts.d.ts +4 -4
  30. package/dist/.dts/build/check-artifacts.d.ts.map +1 -1
  31. package/dist/.dts/build/citation-verification.d.ts +13 -14
  32. package/dist/.dts/build/citation-verification.d.ts.map +1 -1
  33. package/dist/.dts/build/compatibility.d.ts +24 -24
  34. package/dist/.dts/build/compatibility.d.ts.map +1 -1
  35. package/dist/.dts/build/contract-model.d.ts +10 -10
  36. package/dist/.dts/build/contract-model.d.ts.map +1 -1
  37. package/dist/.dts/build/deep-equal.d.ts +2 -2
  38. package/dist/.dts/build/deep-freeze.d.ts +2 -2
  39. package/dist/.dts/build/dependency-graph.d.ts +48 -55
  40. package/dist/.dts/build/dependency-graph.d.ts.map +1 -1
  41. package/dist/.dts/build/dependency-model.d.ts +18 -18
  42. package/dist/.dts/build/dependency-model.d.ts.map +1 -1
  43. package/dist/.dts/build/discover.d.ts +11 -11
  44. package/dist/.dts/build/discover.d.ts.map +1 -1
  45. package/dist/.dts/build/docs.d.ts +34 -38
  46. package/dist/.dts/build/docs.d.ts.map +1 -1
  47. package/dist/.dts/build/env-example.d.ts +13 -13
  48. package/dist/.dts/build/env-example.d.ts.map +1 -1
  49. package/dist/.dts/build/errors.d.ts +8 -8
  50. package/dist/.dts/build/evidence-cache.d.ts +23 -23
  51. package/dist/.dts/build/evidence-cache.d.ts.map +1 -1
  52. package/dist/.dts/build/evidence-model.d.ts +3 -3
  53. package/dist/.dts/build/evidence-reference.d.ts +15 -15
  54. package/dist/.dts/build/evidence-reference.d.ts.map +1 -1
  55. package/dist/.dts/build/evidence-snapshot.d.ts +47 -53
  56. package/dist/.dts/build/evidence-snapshot.d.ts.map +1 -1
  57. package/dist/.dts/build/exclusive-group.d.ts +4 -4
  58. package/dist/.dts/build/exclusive-group.d.ts.map +1 -1
  59. package/dist/.dts/build/finding-model.d.ts +12 -12
  60. package/dist/.dts/build/finding-model.d.ts.map +1 -1
  61. package/dist/.dts/build/generate-documentation.d.ts +19 -19
  62. package/dist/.dts/build/generate-documentation.d.ts.map +1 -1
  63. package/dist/.dts/build/generate-env-artifacts.d.ts +43 -43
  64. package/dist/.dts/build/generate-env-artifacts.d.ts.map +1 -1
  65. package/dist/.dts/build/generate-evidence.d.ts +19 -19
  66. package/dist/.dts/build/generate-evidence.d.ts.map +1 -1
  67. package/dist/.dts/build/generate-manifest.d.ts +11 -12
  68. package/dist/.dts/build/generate-manifest.d.ts.map +1 -1
  69. package/dist/.dts/build/generate-usage.d.ts +23 -24
  70. package/dist/.dts/build/generate-usage.d.ts.map +1 -1
  71. package/dist/.dts/build/generated-banner.d.ts +5 -5
  72. package/dist/.dts/build/governance-fields.d.ts +7 -7
  73. package/dist/.dts/build/humanize-key.d.ts +1 -1
  74. package/dist/.dts/build/humanize-key.d.ts.map +1 -1
  75. package/dist/.dts/build/index.d.ts +20 -36
  76. package/dist/.dts/build/index.d.ts.map +1 -1
  77. package/dist/.dts/build/lifecycle-model.d.ts +87 -85
  78. package/dist/.dts/build/lifecycle-model.d.ts.map +1 -1
  79. package/dist/.dts/build/link.d.ts +38 -39
  80. package/dist/.dts/build/link.d.ts.map +1 -1
  81. package/dist/.dts/build/literal-eval.d.ts +2 -2
  82. package/dist/.dts/build/literal-eval.d.ts.map +1 -1
  83. package/dist/.dts/build/live-expirations.d.ts +14 -13
  84. package/dist/.dts/build/live-expirations.d.ts.map +1 -1
  85. package/dist/.dts/build/manifest.d.ts +6 -6
  86. package/dist/.dts/build/map-utils.d.ts +4 -4
  87. package/dist/.dts/build/merge-documentation.d.ts +9 -8
  88. package/dist/.dts/build/merge-documentation.d.ts.map +1 -1
  89. package/dist/.dts/build/ownership-model.d.ts +14 -15
  90. package/dist/.dts/build/ownership-model.d.ts.map +1 -1
  91. package/dist/.dts/build/parse.d.ts +20 -21
  92. package/dist/.dts/build/parse.d.ts.map +1 -1
  93. package/dist/.dts/build/reference-projections.d.ts +36 -38
  94. package/dist/.dts/build/reference-projections.d.ts.map +1 -1
  95. package/dist/.dts/build/resolution/resolve-import.d.ts +18 -14
  96. package/dist/.dts/build/resolution/resolve-import.d.ts.map +1 -1
  97. package/dist/.dts/build/resolution/resolve-package-schema.d.ts +26 -26
  98. package/dist/.dts/build/resolution/resolve-package-schema.d.ts.map +1 -1
  99. package/dist/.dts/build/resolution/resolve-within-root.d.ts +9 -9
  100. package/dist/.dts/build/sarif.d.ts +5 -5
  101. package/dist/.dts/build/sarif.d.ts.map +1 -1
  102. package/dist/.dts/build/scan-dependencies.d.ts +17 -16
  103. package/dist/.dts/build/scan-dependencies.d.ts.map +1 -1
  104. package/dist/.dts/build/sort-by-identity.d.ts +1 -1
  105. package/dist/.dts/build/source-position.d.ts +13 -13
  106. package/dist/.dts/build/tool-version.d.ts +1 -1
  107. package/dist/.dts/build/usage-report.d.ts +19 -19
  108. package/dist/.dts/build/usage-report.d.ts.map +1 -1
  109. package/dist/.dts/eslint-plugin/index.d.ts +16 -5
  110. package/dist/.dts/eslint-plugin/index.d.ts.map +1 -1
  111. package/dist/.dts/eslint-plugin/no-raw-process-env.d.ts +4 -4
  112. package/dist/.dts/evidence/define-projection.d.ts +15 -16
  113. package/dist/.dts/evidence/define-projection.d.ts.map +1 -1
  114. package/dist/.dts/evidence/index.d.ts +11 -15
  115. package/dist/.dts/evidence/index.d.ts.map +1 -1
  116. package/dist/.dts/helpers/index.d.ts +15 -18
  117. package/dist/.dts/helpers/index.d.ts.map +1 -1
  118. package/dist/.dts/helpers/validators.d.ts +2 -2
  119. package/dist/.dts/helpers/validators.d.ts.map +1 -1
  120. package/dist/.dts/node/index.d.ts +19 -0
  121. package/dist/.dts/node/index.d.ts.map +1 -1
  122. package/dist/.dts/runtime/create.d.ts +3 -3
  123. package/dist/.dts/runtime/document.d.ts +90 -99
  124. package/dist/.dts/runtime/document.d.ts.map +1 -1
  125. package/dist/.dts/runtime/errors.d.ts +5 -5
  126. package/dist/.dts/runtime/reset.d.ts +1 -1
  127. package/dist/.dts/runtime/types.d.ts +23 -24
  128. package/dist/.dts/runtime/types.d.ts.map +1 -1
  129. package/dist/.dts/runtime/validate.d.ts +1 -1
  130. package/dist/.dts7/_ipc/build-fs.d.ts +3 -3
  131. package/dist/.dts7/_ipc/build-fs.d.ts.map +1 -1
  132. package/dist/.dts7/_ipc/display-path.d.ts +1 -1
  133. package/dist/.dts7/_ipc/glob.d.ts +3 -2
  134. package/dist/.dts7/_ipc/glob.d.ts.map +1 -1
  135. package/dist/.dts7/_ipc/no-node-fs.d.ts +2 -2
  136. package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts +16 -16
  137. package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts.map +1 -1
  138. package/dist/.dts7/_ipc/typescript.d.ts +4 -4
  139. package/dist/.dts7/build/assemble-project.d.ts +14 -15
  140. package/dist/.dts7/build/assemble-project.d.ts.map +1 -1
  141. package/dist/.dts7/build/change-model.d.ts +14 -14
  142. package/dist/.dts7/build/change-model.d.ts.map +1 -1
  143. package/dist/.dts7/build/check-artifacts.d.ts +4 -4
  144. package/dist/.dts7/build/check-artifacts.d.ts.map +1 -1
  145. package/dist/.dts7/build/citation-verification.d.ts +13 -14
  146. package/dist/.dts7/build/citation-verification.d.ts.map +1 -1
  147. package/dist/.dts7/build/compatibility.d.ts +24 -24
  148. package/dist/.dts7/build/compatibility.d.ts.map +1 -1
  149. package/dist/.dts7/build/contract-model.d.ts +10 -10
  150. package/dist/.dts7/build/contract-model.d.ts.map +1 -1
  151. package/dist/.dts7/build/deep-equal.d.ts +2 -2
  152. package/dist/.dts7/build/deep-freeze.d.ts +2 -2
  153. package/dist/.dts7/build/dependency-graph.d.ts +48 -55
  154. package/dist/.dts7/build/dependency-graph.d.ts.map +1 -1
  155. package/dist/.dts7/build/dependency-model.d.ts +18 -18
  156. package/dist/.dts7/build/dependency-model.d.ts.map +1 -1
  157. package/dist/.dts7/build/discover.d.ts +11 -11
  158. package/dist/.dts7/build/discover.d.ts.map +1 -1
  159. package/dist/.dts7/build/docs.d.ts +34 -38
  160. package/dist/.dts7/build/docs.d.ts.map +1 -1
  161. package/dist/.dts7/build/env-example.d.ts +13 -13
  162. package/dist/.dts7/build/env-example.d.ts.map +1 -1
  163. package/dist/.dts7/build/errors.d.ts +8 -8
  164. package/dist/.dts7/build/evidence-cache.d.ts +23 -23
  165. package/dist/.dts7/build/evidence-cache.d.ts.map +1 -1
  166. package/dist/.dts7/build/evidence-model.d.ts +3 -3
  167. package/dist/.dts7/build/evidence-reference.d.ts +15 -15
  168. package/dist/.dts7/build/evidence-reference.d.ts.map +1 -1
  169. package/dist/.dts7/build/evidence-snapshot.d.ts +47 -53
  170. package/dist/.dts7/build/evidence-snapshot.d.ts.map +1 -1
  171. package/dist/.dts7/build/exclusive-group.d.ts +4 -4
  172. package/dist/.dts7/build/exclusive-group.d.ts.map +1 -1
  173. package/dist/.dts7/build/finding-model.d.ts +12 -12
  174. package/dist/.dts7/build/finding-model.d.ts.map +1 -1
  175. package/dist/.dts7/build/generate-documentation.d.ts +19 -19
  176. package/dist/.dts7/build/generate-documentation.d.ts.map +1 -1
  177. package/dist/.dts7/build/generate-env-artifacts.d.ts +43 -43
  178. package/dist/.dts7/build/generate-env-artifacts.d.ts.map +1 -1
  179. package/dist/.dts7/build/generate-evidence.d.ts +19 -19
  180. package/dist/.dts7/build/generate-evidence.d.ts.map +1 -1
  181. package/dist/.dts7/build/generate-manifest.d.ts +11 -12
  182. package/dist/.dts7/build/generate-manifest.d.ts.map +1 -1
  183. package/dist/.dts7/build/generate-usage.d.ts +23 -24
  184. package/dist/.dts7/build/generate-usage.d.ts.map +1 -1
  185. package/dist/.dts7/build/generated-banner.d.ts +5 -5
  186. package/dist/.dts7/build/governance-fields.d.ts +7 -7
  187. package/dist/.dts7/build/humanize-key.d.ts +1 -1
  188. package/dist/.dts7/build/humanize-key.d.ts.map +1 -1
  189. package/dist/.dts7/build/index.d.ts +20 -36
  190. package/dist/.dts7/build/index.d.ts.map +1 -1
  191. package/dist/.dts7/build/lifecycle-model.d.ts +87 -85
  192. package/dist/.dts7/build/lifecycle-model.d.ts.map +1 -1
  193. package/dist/.dts7/build/link.d.ts +38 -39
  194. package/dist/.dts7/build/link.d.ts.map +1 -1
  195. package/dist/.dts7/build/literal-eval.d.ts +2 -2
  196. package/dist/.dts7/build/literal-eval.d.ts.map +1 -1
  197. package/dist/.dts7/build/live-expirations.d.ts +14 -13
  198. package/dist/.dts7/build/live-expirations.d.ts.map +1 -1
  199. package/dist/.dts7/build/manifest.d.ts +6 -6
  200. package/dist/.dts7/build/map-utils.d.ts +4 -4
  201. package/dist/.dts7/build/merge-documentation.d.ts +9 -8
  202. package/dist/.dts7/build/merge-documentation.d.ts.map +1 -1
  203. package/dist/.dts7/build/ownership-model.d.ts +14 -15
  204. package/dist/.dts7/build/ownership-model.d.ts.map +1 -1
  205. package/dist/.dts7/build/parse.d.ts +20 -21
  206. package/dist/.dts7/build/parse.d.ts.map +1 -1
  207. package/dist/.dts7/build/reference-projections.d.ts +36 -38
  208. package/dist/.dts7/build/reference-projections.d.ts.map +1 -1
  209. package/dist/.dts7/build/resolution/resolve-import.d.ts +18 -14
  210. package/dist/.dts7/build/resolution/resolve-import.d.ts.map +1 -1
  211. package/dist/.dts7/build/resolution/resolve-package-schema.d.ts +26 -26
  212. package/dist/.dts7/build/resolution/resolve-package-schema.d.ts.map +1 -1
  213. package/dist/.dts7/build/resolution/resolve-within-root.d.ts +9 -9
  214. package/dist/.dts7/build/sarif.d.ts +5 -5
  215. package/dist/.dts7/build/sarif.d.ts.map +1 -1
  216. package/dist/.dts7/build/scan-dependencies.d.ts +17 -16
  217. package/dist/.dts7/build/scan-dependencies.d.ts.map +1 -1
  218. package/dist/.dts7/build/sort-by-identity.d.ts +1 -1
  219. package/dist/.dts7/build/source-position.d.ts +13 -13
  220. package/dist/.dts7/build/tool-version.d.ts +1 -1
  221. package/dist/.dts7/build/usage-report.d.ts +19 -19
  222. package/dist/.dts7/build/usage-report.d.ts.map +1 -1
  223. package/dist/.dts7/eslint-plugin/index.d.ts +16 -5
  224. package/dist/.dts7/eslint-plugin/index.d.ts.map +1 -1
  225. package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts +4 -4
  226. package/dist/.dts7/evidence/define-projection.d.ts +15 -16
  227. package/dist/.dts7/evidence/define-projection.d.ts.map +1 -1
  228. package/dist/.dts7/evidence/index.d.ts +11 -15
  229. package/dist/.dts7/evidence/index.d.ts.map +1 -1
  230. package/dist/.dts7/helpers/index.d.ts +15 -18
  231. package/dist/.dts7/helpers/index.d.ts.map +1 -1
  232. package/dist/.dts7/helpers/validators.d.ts +2 -2
  233. package/dist/.dts7/helpers/validators.d.ts.map +1 -1
  234. package/dist/.dts7/node/index.d.ts +19 -0
  235. package/dist/.dts7/node/index.d.ts.map +1 -1
  236. package/dist/.dts7/runtime/create.d.ts +3 -3
  237. package/dist/.dts7/runtime/document.d.ts +90 -99
  238. package/dist/.dts7/runtime/document.d.ts.map +1 -1
  239. package/dist/.dts7/runtime/errors.d.ts +5 -5
  240. package/dist/.dts7/runtime/reset.d.ts +1 -1
  241. package/dist/.dts7/runtime/types.d.ts +23 -24
  242. package/dist/.dts7/runtime/types.d.ts.map +1 -1
  243. package/dist/.dts7/runtime/validate.d.ts +1 -1
  244. package/dist/{build-DNAYWD2B.js → build-UEENZEUX.js} +37 -39
  245. package/dist/build-UEENZEUX.js.map +1 -0
  246. package/dist/build.cjs +36 -38
  247. package/dist/build.cjs.map +1 -1
  248. package/dist/build.js +36 -38
  249. package/dist/build.js.map +1 -1
  250. package/dist/{chunk-HAGMVMN5.js → chunk-TBL3O7IG.js} +2 -2
  251. package/dist/cli/index.js +29 -28
  252. package/dist/cli/index.js.map +1 -1
  253. package/dist/eslint-plugin/index.cjs.map +1 -1
  254. package/dist/eslint-plugin/index.js.map +1 -1
  255. package/dist/evidence.cjs +1 -1
  256. package/dist/evidence.cjs.map +1 -1
  257. package/dist/evidence.js +1 -1
  258. package/dist/evidence.js.map +1 -1
  259. package/dist/helpers.cjs +4 -4
  260. package/dist/helpers.cjs.map +1 -1
  261. package/dist/helpers.js +4 -4
  262. package/dist/helpers.js.map +1 -1
  263. package/dist/index.cjs.map +1 -1
  264. package/dist/index.js.map +1 -1
  265. package/examples/README.md +1 -1
  266. package/package.json +18 -10
  267. package/schemas/contract-model.schema.json +7 -7
  268. package/schemas/env-cap-report.schema.json +88 -88
  269. package/skills/env-cap/SKILL.md +12 -13
  270. package/skills/env-cap/references/api.md +1 -1
  271. package/specs/architecture.md +145 -120
  272. package/specs/generated-artifacts.md +78 -70
  273. package/specs/migrations/README.md +6 -6
  274. package/specs/migrations/from-centralized-schema.md +1 -1
  275. package/specs/migrations/from-t3-env.md +9 -9
  276. package/PROMPT.md +0 -89
  277. package/dist/build-DNAYWD2B.js.map +0 -1
  278. /package/dist/{chunk-HAGMVMN5.js.map → chunk-TBL3O7IG.js.map} +0 -0
package/README.md CHANGED
@@ -10,46 +10,65 @@
10
10
  [![Node](https://img.shields.io/node/v/%40maverickcer%2Fenv-cap)](https://www.npmjs.com/package/@maverickcer/env-cap)
11
11
  [![License](https://img.shields.io/npm/l/%40maverickcer%2Fenv-cap)](LICENSE)
12
12
 
13
- **Know who owns each environment variable, why it exists, and when it expires.**
13
+ **Each feature declares the environment variables it needs and their format. Your app validates them all in one place at startup, fails fast on a bad value, and reports how they should be rotated before they expire.**
14
14
 
15
- `env-cap` adds ownership, lifecycle and usage evidence to the loader, validator and secret manager you already use. It does not load `.env` files or store secrets.
15
+ `env-cap` is a TypeScript library. A feature is a folder or an installable package in your code; the docs also call it a capability. It declares its variables in a **contract**: how to parse and check each value, who owns it and, for a secret, when it expires.
16
16
 
17
- [Why](#why-it-exists) · [See it run](#see-it-run) · [Install](#install-and-verify) · [Fit](#fit-and-capabilities) · [Limits](#limits-and-when-not-to-use-it) · [Security](#security-and-supply-chain) · [Maturity](#maturity-versioning-and-support) · [Docs](#documentation)
17
+ A build step lists every contract in the **manifest**, a generated file your app passes to `validateEnv()` at startup. A bad value throws an error that names the variable, never its value.
18
+
19
+ **Rotation** replaces a secret before its expiry date, following the steps its contract gives. It applies to each variable whose `documentEnv()` entry declares both, for example `STRIPE_KEY: { expiresAt: "2026-09-01", refreshInstructions: "Rotate in the Stripe dashboard, then redeploy." }`. The build step writes environment docs that print those steps beside each date. They flag a variable that has expired or expires within 30 days, the default window. It also writes the **ownership report**: each contract's owner and the variables nothing reads.
20
+
21
+ It works alongside `dotenv`, Zod and your secret manager. It does not load `.env` files, store secrets or replace your validator.
22
+
23
+ **Try it:** run `npm install @maverickcer/env-cap`, then `npx env-cap init`. It writes a starter contract and a script that writes the manifest, the environment docs (`docs/ENVIRONMENT.md`) and the ownership report. A CI test runs both steps in an empty project ([Install and verify](#install-and-verify)). Once `validateEnv()` runs at startup, an `http://` value for the starter's `EXAMPLE_API_URL` stops the app with:
24
+
25
+ ```text
26
+ Environment validation failed.
27
+
28
+ 1 configuration error found:
29
+
30
+ EXAMPLE_API_URL
31
+ ---------------
32
+ Validation failed:
33
+ Expected an https URL.
34
+ ```
18
35
 
19
36
  ## Why it exists
20
37
 
21
38
  **The problem:** a variable can be well-formed and still be a problem. A validator checks its shape and a secret manager stores it. Neither says who owns it, what depends on it, when it must rotate, or whether anything still reads it.
22
39
 
23
- **What changes:** each part of your code declares the variables it owns. A build step reports owners, expiry dates and declared variables that nothing reads. At startup, the application fails with the variable's name, never its value.
40
+ **What changes:** the answers live in the code next to each variable. An expiring secret shows up in the environment docs with the steps to rotate it, and a variable nothing reads shows up in the ownership report.
24
41
 
25
42
  **Who it is for:** application developers who have shipped an undefined variable to production, and platform engineers who own configuration across teams.
26
43
 
27
44
  ## How it differs
28
45
 
29
- | Tool | What it solves | What remains unanswered |
30
- | ---------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------- |
31
- | `dotenv` | Loads values from a `.env` file | Who owns the value, why it exists, whether it is still used, when it expires |
32
- | Zod / envalid / t3-env | Validates value shape and types | Whether the variable is still needed, who owns it, or what capability depends on it |
33
- | Secret manager | Stores and manages secrets | Which capability in the codebase actually consumes the secret |
34
- | `env-cap` | Defines ownership, lifecycle, and consumption contracts | Does not replace loading, secret storage, or application-specific validation |
46
+ | Tool | What it solves | What remains unanswered |
47
+ | ---------------------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
48
+ | `dotenv` | Loads values from a `.env` file | Who owns the value, why it exists, whether it is still used, when it expires |
49
+ | Zod / envalid / t3-env | Validates value shape and types | Whether the variable is still needed, who owns it, or what code depends on it |
50
+ | Secret manager | Stores and manages secrets | Which code actually reads the secret |
51
+ | `env-cap` | Validates each feature's variables at startup; reports expiry dates, rotation steps, owners and readers | Does not replace loading, secret storage, or application-specific validation |
35
52
 
36
53
  Keep your existing validator: any function that returns `true` or a message plugs into a contract. [Migration guides](specs/migrations/README.md) cover `dotenv`, Zod, envalid and t3-env, including when to stay put.
37
54
 
38
55
  ## What it does
39
56
 
40
- Each entry point has one reader. The [Guide](GUIDE.md) tells each reader's story in full.
57
+ Application developers write contracts with `@maverickcer/env-cap` and `./helpers`. Platform engineers who own CI use `./build`, the `env-cap` CLI and the GitHub Action. These write the manifest, the environment docs, the ownership report and the **evidence file**, a JSON record of owners, expiry dates and readers. `--check` fails when any of them is stale. Reviewers build their own views of the evidence file with `./evidence`. The [Guide](GUIDE.md) tells each reader's story in full. The table below is generated from `package.json#exports` and `docs/surface.json`; the `GeneratedRegions` check fails if it is stale.
41
58
 
42
- | Entry point | Written for | What it gives you |
43
- | --------------------------------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------- |
44
- | `@maverickcer/env-cap` | Application developers | One startup check that names every failing variable, and contracts that redact themselves |
45
- | `@maverickcer/env-cap/helpers` | The same developers | Small processors and validators, tree-shaken when unused |
46
- | `@maverickcer/env-cap/build`, CLI, Action | Platform engineers who own CI | A manifest, docs and an evidence file from static analysis; `--check` fails on drift |
47
- | `@maverickcer/env-cap/evidence` | Reviewers who need an inventory | Findings, lifecycle data and SARIF that support a review |
48
- | `@maverickcer/env-cap/node`, `/eslint-plugin` | Build-script authors and lint owners | The `node:fs` adapter `./build` needs, and two lint rules |
59
+ <!-- ipc:begin entry-points -->
49
60
 
50
- ```text
51
- declare → generate → validate → consume
52
- ```
61
+ | Export | Source | Environment | Tier | Purpose |
62
+ | ------------------------------------ | -------------------- | ------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
63
+ | `@maverickcer/env-cap` | `src/runtime/` | No Node module or Node global | Stable | `createEnv`, `documentEnv`, `validateEnv`, `resetEnvCache`, `isEnvContract` and the error types |
64
+ | `@maverickcer/env-cap/build` | `src/build/` | Node only, in development and CI | Stable | Discovery, AST analysis and artifact generation. The four `generate*()` orchestrators and the lower-level primitives are Stable (ADR 0045, `VERSIONING.md`). |
65
+ | `@maverickcer/env-cap/helpers` | `src/helpers/` | No Node module; `processors.base64()` returns a Node `Buffer` | Stable | `processors` and `validators` |
66
+ | `@maverickcer/env-cap/node` | `src/node/` | Node only, in development and CI | Stable | `nodeBuildFileSystem`, the `BuildFileSystem` adapter a build script hands to `./build` |
67
+ | `@maverickcer/env-cap/evidence` | `src/evidence/` | No Node module or Node global | Stable | `defineEvidenceProjection`, pure transforms over the Evidence Model (Stable, see `VERSIONING.md`) |
68
+ | `@maverickcer/env-cap/eslint-plugin` | `src/eslint-plugin/` | Node only, inside the project's ESLint | Stable | The `no-raw-process-env` and `no-node-fs` lint rules |
69
+ | `@maverickcer/env-cap/schema` | `schemas/` | Static JSON | Stable | The JSON Schema for `env-cap --json` output (`env-cap-report.schema.json`) and the model schemas under `./schema/*` |
70
+
71
+ <!-- ipc:end entry-points -->
53
72
 
54
73
  ### See it run
55
74
 
@@ -105,16 +124,14 @@ $ npx tsx scripts/generate-docs/run.ts
105
124
  - STRIPE_KEY in app
106
125
  ```
107
126
 
108
- This is output from [`examples/application`](https://github.com/MaverickCER/env-cap/tree/main/examples/application) (`npm run docs:reports`). `N` stands for the days since 2026-09-01, counted on the day you run it.
109
-
110
- The report states facts a validator cannot see. `STRIPE_KEY` is declared to expire on 2026-09-01, and that date has passed. `DATABASE_URL` and `STRIPE_KEY` are declared in the `app` contract, but the analysis found no code that reads them.
127
+ This is output from [`examples/application`](https://github.com/MaverickCER/env-cap/tree/main/examples/application) (`npm run docs:reports`). `N` stands for the days since 2026-09-01, counted on the day you run it. The report states facts a validator cannot see. `STRIPE_KEY` is declared to expire on 2026-09-01, and that date has passed. `DATABASE_URL` and `STRIPE_KEY` are declared in the `app` contract, but the analysis found no code that reads them.
111
128
 
112
129
  ### Evidence it works
113
130
 
114
- - **Real output:** CI's `examples` job re-runs the block above and compares its expiry and unconsumed lists with this README (`npm run verify:readme-example`). That job does not yet block a merge.
131
+ - **Real output:** CI's `examples` job re-runs the block above and compares its expiry and unconsumed lists with this README (`npm run verify:readme-example`). `required` waits for `examples`, so a failure blocks a merge.
115
132
  - **Coverage floors:** 90% branches, 100% functions, 95% lines and statements, enforced by the `contract` job (`vitest.config.ts`). A pull request can lower a floor; reviewers treat that as a reviewed change.
116
133
  - **Mutation testing:** the `contract` job fails on any surviving, timed-out or uncovered Stryker mutant in `src/`. Managed copies under `src/_ipc/`, `scripts/`, and mutants silenced by a disable comment are not counted.
117
- - **Runtimes:** the runtime, helpers and evidence entries run on Node 22 and 24 in blocking jobs. They also run under Bun, Deno and a Web-globals VM; the Bun and Deno job is not yet merge-blocking.
134
+ - **Runtimes:** the runtime, helpers and evidence entries run on Node 22 and 24 in blocking jobs. They also run under Bun, Deno and a Web-globals VM. `required` waits for the Bun and Deno job (`cross-runtime`).
118
135
  - **Size budgets:** 3 KB gzip for the runtime, 4 KB for helpers and 3 KB for evidence, enforced by the `Size` check ([ADR 0008](specs/decisions/0008-gzip-size-budget.md)). The budget measures the entry file, not your bundle.
119
136
 
120
137
  ## Install and verify
@@ -127,7 +144,7 @@ npx env-cap init # writes env.schema.ts and scripts/generate-en
127
144
  node scripts/generate-env.mjs
128
145
  ```
129
146
 
130
- `init` writes two files and skips any file that already exists. Without a valid `package.json` it exits `1` and writes nothing. `test/cli/init.test.ts` pins these rules and the templates. **Verify it works:** the script exits `0` and prints `Discovered 1 contract(s).` CI pins the script's text but does not run it. Report an issue if that line differs.
147
+ `init` writes two files and skips any file that already exists. Without a valid `package.json` it exits `1` and writes nothing. `test/cli/init.test.ts` pins these rules and the templates. **Verify it works:** the script prints `Discovered 1 contract(s).` and exits `0`. `test/cli/quick-start.test.ts` runs `init` and the script against the built package and checks that line and each generated file. Report an issue if that line differs.
131
148
 
132
149
  Then validate once at startup and read values through the contract. `init` writes `env.schema.ts` into `src/` when that folder exists, otherwise into the project root; adjust the import path to match:
133
150
 
@@ -140,22 +157,22 @@ await validateEnv({ manifest, values: process.env })
140
157
  exampleEnv.EXAMPLE_API_URL
141
158
  ```
142
159
 
143
- **Using an AI agent?** Give it [the skill](https://raw.githubusercontent.com/MaverickCER/env-cap/main/skills/env-cap/SKILL.md), a short manual generated from this package's exports.
144
-
145
160
  ## Fit and capabilities
146
161
 
147
162
  **Use cases:** find expired or unowned secrets before they page someone. Generate variable documentation from the code instead of a wiki. Let each team own the variables its feature needs. Give CI bots facts such as "`STRIPE_KEY` is declared but unconsumed".
148
163
 
149
- **Core capabilities:**
164
+ **What you get:**
150
165
 
151
- - Capability-scoped contracts with validators, owners, sensitivity and expiry dates ([contracts](GUIDE.md#capability-owned-contracts)).
166
+ - Per-feature contracts with validators, owners, sensitivity and expiry dates ([contracts](GUIDE.md#capability-owned-contracts)).
152
167
  - A manifest, environment docs, `.env.example` and an ownership report, from static analysis that never imports your schema files.
153
168
  - A persisted evidence file, a CLI, a [GitHub Action](GUIDE.md#github-action), scheduled rotation reports and an [ESLint plugin](GUIDE.md#eslint-plugin).
154
169
  - One central schema or one contract per feature or package; the manifest stays project-wide either way.
155
170
 
156
171
  **How it works:** the runtime and the build tooling are separate entry points. The runtime has no filesystem access, which lint and a tarball scan enforce. The build pass runs only in development and CI ([Architecture](GUIDE.md#runtime-and-build-time-are-intentionally-separate)).
157
172
 
158
- **Runtimes:** Node.js 22 and 24 are tested. Bun, Deno and a browser-style bundle run in CI for the runtime, helpers and evidence entries; edge runtimes are not tested ([support matrix](GUIDE.md#runtime-support-matrix)). **Package managers:** npm is supported. pnpm, Yarn 1 and Yarn Berry are tested only for installing the tarball and importing every entry ([details](GUIDE.md#package-managers)).
173
+ **Runtimes:** Node.js 22 and 24 are tested. Bun, Deno and a browser-style bundle run in CI for the runtime, helpers and evidence entries. Edge runtimes are not tested ([support matrix](GUIDE.md#runtime-support-matrix)).
174
+
175
+ **Package managers:** npm is supported. pnpm, Yarn 1 and Yarn Berry are tested only for installing the tarball and importing every entry ([details](GUIDE.md#package-managers)).
159
176
 
160
177
  ## Limits and when not to use it
161
178
 
@@ -163,11 +180,11 @@ exampleEnv.EXAMPLE_API_URL
163
180
  - **Trade-offs:** it adds a build step and a declaration per variable. Its reports are only as accurate as those declarations, and it cannot see variables read outside the analyzed code.
164
181
  - **Install weight:** the one dependency is a TypeScript 6 compiler bundled in the tarball. Only the build entry loads it, and a CI step fails if a runtime entry can reach it ([Adoption guide](ADOPTION.md#bundle-size-and-performance)).
165
182
  - **Dynamic schemas:** a schema built by a function, or a spread at the top of a schema object, produces a parse warning. A spread nested inside a variable's definition or its `documentEnv()` entry is skipped without one. Nothing is guessed.
166
- - **Automation:** bots can read the same manifest and evidence. A structured finding does not make a fix correct; see the [AI integration prompt](PROMPT.md).
183
+ - **Automation:** bots can read the same manifest and evidence. A structured finding does not make a fix correct, so review a bot's change as you would a person's.
167
184
 
168
185
  ## Security and supply chain
169
186
 
170
- - **Runtime:** it has no filesystem access and reads only the `values` you pass; lint and the tarball scan enforce the first, the tarball scan and a browser-bundle test the second. Both scans are textual. Contracts redact themselves when logged or serialized, but spreading a contract reads every value ([runtime model](SECURITY.md#runtime-security-model)).
187
+ - **Runtime:** it has no filesystem access and reads only the `values` you pass. Lint and the tarball scan enforce the first; the tarball scan and a browser-bundle test the second. Both scans are textual. Contracts redact themselves when logged or serialized, but spreading a contract reads every value ([runtime model](SECURITY.md#runtime-security-model)).
171
188
  - **Errors:** validation errors carry variable and contract names and your own messages, never values (tested). A validator message that embeds the value is passed through.
172
189
  - **Build:** schema files are parsed as syntax trees and never imported or run (tested). It does not sandbox the rest of your build ([build-time model](SECURITY.md#build-time-security-model)).
173
190
  - **Dependencies:** what installing the package adds is generated from `package.json` into the [Adoption guide](ADOPTION.md#security--threat-model). MIT licensed.
@@ -189,6 +206,7 @@ Pre-1.0; the npm badge shows the current version. Before 1.0, a minor release ma
189
206
  - **[Adoption guide](ADOPTION.md):** what adopting costs, what it needs, and what it refuses to do.
190
207
  - **[Security](SECURITY.md):** the reviewer's model of what is enforced, where, and what is not.
191
208
  - **[API reference](https://maverickcer.github.io/env-cap/api/):** every exported symbol, generated from source.
209
+ - **[Agent skill](https://raw.githubusercontent.com/MaverickCER/env-cap/main/skills/env-cap/SKILL.md):** a short manual for an AI agent, generated from `docs/skill.json` and the exports; [AGENTS.md](AGENTS.md) adds the rules for this repository.
192
210
  - **[Architecture](specs/architecture.md)** and **[ADRs](https://github.com/MaverickCER/env-cap/tree/main/specs/decisions):** why it is designed this way.
193
211
  - **[Examples](https://github.com/MaverickCER/env-cap/tree/main/examples):** runnable application, team-service, enterprise-platform and Next.js examples.
194
212
  - **Toolkit:** `data-cap` governs application data; `repo-contract` and `internal-package-contract` verify both ([toolkit overview](https://github.com/MaverickCER/internal-package-contract/blob/main/TOOLKIT.md)).
package/RELEASING.md CHANGED
@@ -11,34 +11,42 @@ For what semver actually covers, see [`VERSIONING.md`](VERSIONING.md).
11
11
  Releases are driven by [Changesets](https://github.com/changesets/changesets) and npm's
12
12
  [OIDC trusted publishing](https://docs.npmjs.com/trusted-publishers), through
13
13
  [`.github/workflows/release.yml`](https://github.com/MaverickCER/env-cap/blob/main/.github/workflows/release.yml),
14
- which calls a shared, pinned workflow. **No `NPM_TOKEN` secret exists in this repository** and none is
15
- needed: npm verifies the workflow's OIDC identity against a one-time trusted-publisher registration on
16
- npmjs.com (see [First-time setup](#first-time-setup)). A person merges the release pull request. The one other path is recovery: a version on `main` that is not on
17
- npm is built and published without a pull request (see "Recovering from a failed release").
14
+ which calls a shared, pinned workflow. A person merges the release pull request.
15
+
16
+ **No `NPM_TOKEN` secret exists in this repository**, and none is needed. The workflow's OIDC identity is
17
+ verified by npm against a one-time trusted-publisher registration on npmjs.com (see
18
+ [First-time setup](#first-time-setup)).
19
+
20
+ The one other path is recovery. A version on `main` that is not on npm is built and published without a pull
21
+ request (see "Recovering from a failed release").
18
22
 
19
23
  The loop:
20
24
 
21
25
  1. A pull request that changes user-facing behavior carries a changeset in `.changeset/` (Markdown,
22
26
  `patch`/`minor`/`major` plus a consumer-facing description). When it does not, one is generated on `main`
23
- from the commit messages (`feat`, `fix`, `perf`, `revert` or a breaking marker; a `Changeset: <bump>`
24
- trailer overrides). Below 1.0.0 a generated bump never exceeds minor, so 1.0.0 is reached only by a
27
+ from the commit messages: `feat`, `fix`, `perf`, `revert` or a breaking marker. A `Changeset: <bump>`
28
+ trailer overrides. Below 1.0.0 a generated bump never exceeds minor, so 1.0.0 is reached only by a
25
29
  deliberate `major` changeset.
26
30
  2. On each push to `main`, the workflow opens or updates a pull request titled **"chore: version packages"**
27
- from the branch **`changeset-release/main`** and dispatches CI on it. That pull request consumes the
28
- changeset files, bumps `package.json`'s `version` and rewrites `CHANGELOG.md`. Review it and merge it
29
- yourself; it is never merged automatically.
30
- 3. Merging it runs the workflow again. A **build** job, which holds no publishing credentials, runs
31
- `npm run verify` when the package defines it, requires that a CI run on a commit with exactly this tree
32
- finished its `contract` job with success, checks that no scaffold prompt is unanswered, packs the
33
- tarball, installs that tarball into an empty project and imports every entry point it declares. Only if
34
- all of that passes does the **publish** job run, and only from the default branch. It publishes exactly
35
- the tarball the build job made, over OIDC with a provenance attestation.
36
- 4. After publishing, the workflow tags the release `v<major>.<minor>.<patch>` on the merged commit,
37
- force-updates the floating major tag (`v0` while the package is 0.x, `v1` from 1.0.0), and asks npm what
38
- it now serves: the version must be there and must carry the provenance attestation, or the run goes red.
39
- The floating tag tracks the composite Action's interface (`action.yml` inputs and outputs), so
40
- `uses: maverickcer/env-cap@v0` keeps pointing at the latest compatible build until `action.yml` itself
41
- has a breaking change.
31
+ from the branch **`changeset-release/main`**. It dispatches CI on that pull request. The pull request
32
+ consumes the changeset files, bumps `package.json`'s `version` and rewrites `CHANGELOG.md`. Review it and
33
+ merge it yourself; it is never merged automatically.
34
+ 3. Merging it runs the workflow again. A **build** job, which holds no publishing credentials:
35
+ - runs `npm run verify` when the package defines it;
36
+ - requires that a CI run on a commit with exactly this tree finished its `contract` job with success, and
37
+ its `required` job too where that run has one;
38
+ - checks that no scaffold prompt is unanswered;
39
+ - packs the tarball, installs that tarball into an empty project and imports every entry point it declares.
40
+
41
+ Only if all of that passes does the **publish** job run, and only from the default branch. It publishes
42
+ exactly the tarball the build job made, over OIDC with a provenance attestation.
43
+
44
+ 4. After publishing, the workflow tags the release `v<major>.<minor>.<patch>` on the merged commit. It
45
+ force-updates the floating major tag (`v0` while the package is 0.x, `v1` from 1.0.0). Then it asks npm
46
+ what it now serves. The version must be there and must carry the provenance attestation, or the run goes
47
+ red. The floating tag tracks the composite Action's interface (`action.yml` inputs and outputs).
48
+ `uses: maverickcer/env-cap@v0` therefore keeps pointing at the latest compatible build until
49
+ `action.yml` itself has a breaking change.
42
50
 
43
51
  `CHANGELOG.md` is generated; never hand-edit it. Fix a wrong entry by correcting the offending changeset
44
52
  before the version pull request is merged, or with a follow-up changeset after.
@@ -53,26 +61,23 @@ access, so it can't be done from a PR.
53
61
  GitHub Actions:
54
62
  - Organization or user: `maverickcer`
55
63
  - Repository: `env-cap`
56
- - Workflow filename: `release.yml` (exactly: the filename alone, not a
57
- path; a mismatch here is the most common cause of the OIDC flow failing
58
- with a misleading `E404`)
64
+ - Workflow filename: `release.yml`. Enter exactly the filename alone, not a path. A mismatch here is the
65
+ most common cause of the OIDC flow failing with a misleading `E404`.
59
66
  - Environment: leave blank unless `release.yml` is later scoped to a
60
67
  GitHub Environment
61
68
  2. That is the whole trust relationship: `release.yml`'s `id-token: write`
62
69
  permission plus this registration. There is no token to copy anywhere.
63
70
 
64
- Until the package exists on npm, its settings page doesn't either. For the
65
- **first ever publish**, register the trusted publisher immediately after the
66
- first `npm publish` (a one-time manual `npm publish --access public` from a
67
- maintainer machine, from a clean `npm run verify` tree), then let every
68
- subsequent release go through `release.yml`. Alternatively, publish an empty
69
- `0.0.0` placeholder manually first, register the trusted publisher, then let
70
- the first real version pull request publish `0.1.0` over OIDC.
71
+ Until the package exists on npm, its settings page doesn't either. For the **first ever publish**, make a
72
+ one-time manual `npm publish --access public` from a maintainer machine, from a clean `npm run verify` tree.
73
+ Register the trusted publisher immediately after that first `npm publish`. Then let every subsequent release
74
+ go through `release.yml`. Alternatively, publish an empty `0.0.0` placeholder manually first, register the
75
+ trusted publisher, then let the first real version pull request publish `0.1.0` over OIDC.
71
76
 
72
77
  ## Recovering from a failed release
73
78
 
74
- Identify which state you're in first — the recovery differs and the wrong
75
- one can double-publish or lose a version.
79
+ Identify which state you're in first. The recovery differs, and the wrong one can double-publish or lose a
80
+ version.
76
81
 
77
82
  ### A. The version pull request is open, nothing published yet
78
83
 
@@ -84,29 +89,38 @@ Nothing is on npm; nothing to undo.
84
89
  ### B. The version pull request is merged, but the release failed
85
90
 
86
91
  `main` now has the version bump and changelog commit, but npm does not have the version. This is the common
87
- failure (OIDC misconfiguration, a failing `npm run verify`, no passing `contract` run on the tree, a failing
88
- packed-consumer check in the build job, a registry blip).
92
+ failure. Its causes include:
93
+
94
+ - OIDC misconfiguration;
95
+ - a failing `npm run verify`;
96
+ - no CI run on the tree that passed `contract` and, where the run has it, `required`;
97
+ - a failing packed-consumer check in the build job;
98
+ - a registry blip.
99
+
100
+ To recover:
89
101
 
90
102
  1. Confirm npm really doesn't have it: `npm view @maverickcer/env-cap versions --json`, and check the bumped version is
91
103
  absent.
92
104
  2. Find the cause (see [Common failures](#common-failure-causes)).
93
105
  3. If it was transient or a configuration problem outside the repository (a registry blip, the
94
- trusted-publisher registration), fix that and re-run the failed `release.yml` run from the Actions tab
106
+ trusted-publisher registration), fix that. Then re-run the failed `release.yml` run from the Actions tab
95
107
  ("Re-run failed jobs"). A re-run uses the same commit.
96
108
  4. If the cause is in the code, a re-run cannot help: it would build the same commit again. Fix it in a normal
97
- pull request to `main`. What happens next depends on the commit type. A `fix`, `feat`, `perf` or `revert`
98
- commit gets a changeset generated for it, so the workflow opens a new version pull request instead of
99
- publishing the stuck version; merging that publishes the next version, and the stuck version number is
100
- skipped. A commit type that releases nothing (`chore`, `ci`, `docs`) leaves no changeset, so the
101
- workflow sees that the current `package.json` version isn't on npm and builds and publishes that version.
102
- 5. Publishing by hand is the last resort, and it publishes without the provenance attestation that the
103
- workflow adds. If you must, publish that exact version from a clean tree
104
- (`git checkout main && npm ci && npm run verify && npm publish --access public`), then confirm the next push
109
+ pull request to `main`. What happens next depends on the commit type.
110
+ - A `fix`, `feat`, `perf` or `revert` commit gets a changeset generated for it. The workflow then opens a
111
+ new version pull request instead of publishing the stuck version. Merging that publishes the next
112
+ version, and the stuck version number is skipped.
113
+ - A commit type that releases nothing (`chore`, `ci`, `docs`) leaves no changeset. The workflow then sees
114
+ that the current `package.json` version isn't on npm, and builds and publishes that version.
115
+ 5. Publishing by hand is the last resort. It skips the build job's proof that CI passed `contract` (and
116
+ `required`) on this tree, and it publishes without the provenance attestation that the workflow adds.
117
+ Check the CI run on that commit yourself first. If you must, publish that exact version from a clean tree
118
+ (`git checkout main && npm ci && npm run verify && npm publish --access public`). Then confirm the next push
105
119
  to `main` produces no spurious version pull request.
106
120
 
107
121
  ### C. Published to npm, but a later workflow step failed
108
122
 
109
- e.g. the publish succeeded but the floating major tag (`v0` or `v1`) roll failed. The release itself
123
+ For example, the publish succeeded but the floating major tag (`v0` or `v1`) roll failed. The release itself
110
124
  is done and correct. Fix the trailing step by hand:
111
125
 
112
126
  ```bash
@@ -115,48 +129,48 @@ git tag -f v0 && git push origin v0 --force # while the package is 0.x
115
129
  git tag -f v1 && git push origin v1 --force # from 1.0.0
116
130
  ```
117
131
 
118
- Do **not** re-run the whole workflow — `changeset publish` is idempotent and
119
- will no-op on the already-published version, but re-running risks masking
120
- whatever the real trailing failure was.
132
+ Fix it by hand rather than re-running the workflow. A re-run publishes nothing and runs none of the later
133
+ steps: the build job finds the version already on npm and stops there.
121
134
 
122
135
  ### D. Wrong version published
123
136
 
124
- npm publishes are effectively permanent (`npm unpublish` is allowed only
125
- within 72 hours and only if nothing depends on it, and the version number
126
- can never be reused). Don't try to unpublish a normal mistake. Instead:
137
+ npm publishes are effectively permanent. `npm unpublish` is allowed only within 72 hours and only if nothing
138
+ depends on it, and the version number can never be reused. Don't try to unpublish a normal mistake. Instead:
127
139
 
128
140
  - Wrong contents, right version number: publish a patch (`x.y.z+1`) with a
129
- changeset that fixes it, and `npm deprecate @maverickcer/env-cap@x.y.z
130
- "Broken publish — use x.y.z+1"`.
141
+ changeset that fixes it, and `npm deprecate @maverickcer/env-cap@x.y.z "Broken publish; use x.y.z+1"`.
131
142
  - Accidental major/minor bump: it stays. Continue from the new baseline; a
132
143
  version number is cheap, a rewritten history is not.
133
144
 
134
145
  ### E. First release, package not yet on npm
135
146
 
136
- See [First-time setup](#first-time-setup) — the trusted-publisher
137
- registration cannot exist before the package does, so the first publish is
138
- the one manual step. Every release after that is automated.
147
+ See [First-time setup](#first-time-setup). The trusted-publisher registration cannot exist before the
148
+ package does, so the first publish is the one manual step. Every release after that is automated.
139
149
 
140
150
  ## Common failure causes
141
151
 
142
152
  - **`E404` on publish with OIDC**: the trusted-publisher registration's
143
153
  workflow filename doesn't exactly match `release.yml`, or the
144
154
  org/user/repo fields are wrong.
145
- - **The build job's verify, contract-run or packed-consumer step fails**: the version pull request merged
146
- with a red `main`, no CI run finished `contract` on that tree, or the tarball does not contain what
147
- `exports` promises. Fix `main` first, then recover per case B.
155
+ - **The build job's verify, contract-run or packed-consumer step fails**: one of these happened.
156
+ - The version pull request merged with a red `main`.
157
+ - No CI run on that tree passed `contract` and, where the run has it, `required`.
158
+ - The tarball does not contain what `exports` promises.
159
+
160
+ Fix `main` first, then recover per case B.
161
+
148
162
  - **The final "Verify what npm now serves" step fails**: npm did not return the version or its provenance
149
163
  attestation. Nothing is unpublished by the failure; look at the registry before doing anything else.
150
- - **A version pull request appears when you didn't expect one**: there's a stray changeset file in `.changeset/` on `main`. If it's
151
- spurious, delete it in a normal PR.
164
+ - **A version pull request appears when you didn't expect one**: there's a stray changeset file in
165
+ `.changeset/` on `main`. If it's spurious, delete it in a normal PR.
152
166
  - **Two version pull requests**: an older one wasn't closed when `main` moved. Close the stale one; the
153
167
  workflow only maintains the newest.
154
168
 
155
169
  ## Related
156
170
 
157
- - [`VERSIONING.md`](VERSIONING.md) — what each bump type means, and which
171
+ - [`VERSIONING.md`](VERSIONING.md): what each bump type means, and which
158
172
  surface semver actually covers.
159
- - [`CONTRIBUTING.md`](CONTRIBUTING.md) — the contributor-side workflow
173
+ - [`CONTRIBUTING.md`](CONTRIBUTING.md): the contributor-side workflow
160
174
  (branch, changeset, PR).
161
- - [`SECURITY.md`](SECURITY.md#supported-versions) — which versions get
175
+ - [`SECURITY.md`](SECURITY.md#supported-versions): which versions get
162
176
  security fixes.
package/SECURITY.md CHANGED
@@ -90,21 +90,21 @@ These stay with you:
90
90
 
91
91
  What a reviewer of the build and publish pipeline can rely on:
92
92
 
93
- | Control | Mechanism | Limit |
94
- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
95
- | `main` requires a pull request, resolved review threads, and the `contract` and `lint` checks | Ruleset; `BranchProtection` check | Admins can bypass; no approving review is required |
96
- | Releases publish over npm OIDC trusted publishing with a provenance attestation | `.github/workflows/release.yml` and the shared release workflow it calls; the repository holds no `NPM_TOKEN` | A manual last-resort publish ([RELEASING.md](RELEASING.md)) carries no attestation |
97
- | The release checks that npm serves the version with its attestation | The release workflow's final verification step | It reports a failure; it cannot unpublish |
98
- | A release publishes only a tree whose `contract` job passed, after `npm run verify` and an install-and-import of that tarball | The shared release workflow | It looks at `contract`, not `required`. No env-cap release has run on this workflow version yet |
99
- | A person merges every release pull request | The Changesets flow; release pull requests are never merged automatically | An admin can merge a `major` changeset; the workflow only posts a notice |
100
- | Version tags `v<x.y.z>` cannot be moved or deleted | A tag ruleset on `refs/tags/v*.*.*` | Admins can bypass rulesets. The floating `v0` tag moves on each release by design |
101
- | Production dependency licences, `npm audit` and Socket alerts are reviewed | The `Licenses`, `SecurityDeps` and `SecuritySocket` checks in `contract`; each accepted alert needs a record | Socket alerts on the bundled compiler (network, shell, environment, filesystem) are recorded, not removed |
102
- | No secrets are committed | The `SecuritySecrets` check | Pattern-based |
103
- | A pull request with an open code-scanning alert on its ref fails | The `CodeScanning` check | Alerts that exist only on `main`, such as Scorecard's, are not visible to a pull request |
104
- | Shipped JavaScript is unminified, and every URL in `dist/` has a reviewed record | The `NoMinify` and `DistNoUrls` checks | None found |
105
- | Coverage stays above fixed floors | `vitest.config.ts` thresholds, enforced in `contract` | A pull request can lower a floor; reviewers treat that as a reviewed change |
106
-
107
- The runtime, helpers and evidence entries also run under Bun and Deno (`test/cross-runtime/`). That job does not yet block a merge. The build entry and the CLI are Node-only.
93
+ | Control | Mechanism | Limit |
94
+ | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
95
+ | `main` requires a pull request, resolved review threads, and the `contract`, `lint` and `required` checks | Ruleset; the `BranchProtection` check fails if it stops requiring `contract`, `required` or resolved threads | Admins can bypass; no approving review is required. `BranchProtection` does not check `lint` |
96
+ | Releases publish over npm OIDC trusted publishing with a provenance attestation | `.github/workflows/release.yml` and the shared release workflow it calls; the repository holds no `NPM_TOKEN` | A manual last-resort publish ([RELEASING.md](RELEASING.md)) carries no attestation |
97
+ | The release checks that npm serves the version with its attestation | The release workflow's final verification step | It reports a failure; it cannot unpublish |
98
+ | A release publishes only a tree whose `contract` and `required` jobs passed, after `npm run verify` and an install-and-import of that tarball | The shared release workflow | A run without a `required` job passes on `contract` alone; env-cap's CI always has one |
99
+ | A person merges every release pull request | The Changesets flow; release pull requests are never merged automatically | An admin can merge a `major` changeset; the workflow only posts a notice |
100
+ | Version tags `v<x.y.z>` cannot be moved or deleted | A tag ruleset on `refs/tags/v*.*.*` | Admins can bypass rulesets. The floating `v0` tag moves on each release by design |
101
+ | Production dependency licences, `npm audit` and Socket alerts are reviewed | The `Licenses`, `SecurityDeps` and `SecuritySocket` checks in `contract`; each accepted alert needs a record | Socket alerts on the bundled compiler (network, shell, environment, filesystem) are recorded, not removed |
102
+ | No secrets are committed | The `SecuritySecrets` check | Pattern-based |
103
+ | A pull request with an open code-scanning alert on its ref fails | The `CodeScanning` check | Alerts that exist only on `main`, such as Scorecard's, are not visible to a pull request |
104
+ | Shipped JavaScript is unminified, and every URL in `dist/` has a reviewed record | The `NoMinify` and `DistNoUrls` checks | None found |
105
+ | Coverage stays above fixed floors | `vitest.config.ts` thresholds, enforced in `contract` | A pull request can lower a floor; reviewers treat that as a reviewed change |
106
+
107
+ The runtime, helpers and evidence entries also run under Bun and Deno (`test/cross-runtime/`). `required` waits for that job (`cross-runtime`), so a failure blocks a merge. The build entry and the CLI are Node-only.
108
108
 
109
109
  [RELEASING.md](RELEASING.md#first-time-setup) describes the one-time trusted-publisher setup.
110
110
 
package/VERSIONING.md CHANGED
@@ -30,20 +30,21 @@ Generated from `package.json#exports` and `docs/surface.json` by `internal-packa
30
30
 
31
31
  ## What the Stable tier covers
32
32
 
33
- | Surface | Checked by | Limit |
34
- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
35
- | Runtime APIs: `createEnv`, `validateEnv`, `documentEnv`, `resetEnvCache`, `isEnvContract`, the error classes | `ApiContract` (runtime baseline) | Signatures, not behaviour; tests cover behaviour |
36
- | The four `generate*()` functions, their options, and the lower-level `./build` primitives such as `discoverSchemaFiles`, `parseSchemaFile`, `generateEvidenceModel` and `getEvidenceModel` | `ApiContract` (build baseline) | The dependency-ownership engine's internals are Private ([ADR 0010](specs/decisions/0010-dependency-ownership-engine-scope-boundary.md)) |
37
- | `@maverickcer/env-cap/helpers`, `/evidence`, `/node` and `/eslint-plugin` exports, including rule names, options and the default allow list | `ApiContract` (one baseline per entry) | None found |
38
- | CLI flags in `env-cap --help`, and the exit codes | `SurfaceContract` | None found |
39
- | The `--json` report and the published JSON Schema (`@maverickcer/env-cap/schema`) | `SurfaceContract` diffs the schema; the `Schema` check fails if it is not regenerated from `src/cli/json.ts` | A changed or removed field is meant to bump `schemaVersion`. No check ties a shape change to that bump yet |
40
- | The persisted evidence file, a serialization of `EvidenceModel` | `ApiContract` (evidence baseline) for the type | The committed evidence of two examples validates against the schema; a freshly written file is not checked |
41
- | The generated manifest's shape | Tests in `test/build/manifest.test.ts` | No baseline diff |
42
- | The `envCap.schema` field in a package's `package.json`, and the `packages` and `tsconfig` options | Tests in `test/build/resolution/` | No baseline diff for the field |
43
- | The files and templates `env-cap init` writes | `test/cli/init.test.ts` pins the exact templates | None found |
44
- | The GitHub Action's input names and defaults | `SurfaceContract` | Input descriptions and the summary comment's sections are not baselined |
45
- | The supported toolchain: Node.js `>=22` and `moduleResolution` `node16`, `nodenext` or `bundler` | `EngineMatrix` (Node 22 and 24) and `TypeResolution` | Node 26 runs as an informational job |
46
- | TypeScript 5, 6 and 7 for type-checking every entry point except `./eslint-plugin`, under `strict` and full library checking | `scripts/typescript-compat.mjs` in CI | CI installs the newest 5.x, 6.x and 7.x only, and that job does not yet block a merge |
33
+ | Surface | Checked by | Limit |
34
+ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
35
+ | Runtime APIs: `createEnv`, `validateEnv`, `documentEnv`, `resetEnvCache`, `isEnvContract`, the error classes | `ApiContract` (runtime baseline) | Signatures, not behaviour; tests cover behaviour |
36
+ | The four `generate*()` functions, their options, and the lower-level `./build` primitives such as `discoverSchemaFiles`, `parseSchemaFile`, `generateEvidenceModel` and `getEvidenceModel` | `ApiContract` (build baseline) | The dependency-ownership engine's internals are Private ([ADR 0010](specs/decisions/0010-dependency-ownership-engine-scope-boundary.md)) |
37
+ | `@maverickcer/env-cap/helpers`, `/evidence`, `/node` and `/eslint-plugin` exports, including rule names, options and the default allow list | `ApiContract` (one baseline per entry) | None found |
38
+ | CLI flags in `env-cap --help` and `env-cap init --help`, the exit codes of those two, and the exit codes `env-cap --help` lists | `SurfaceContract` | The baseline records the listed codes; `test/cli/main.test.ts` and `test/cli/direct-run.test.ts` check that the CLI returns them. `init`'s other exit codes are pinned by `test/cli/init.test.ts` only |
39
+ | The `--json` report and the published JSON Schema (`@maverickcer/env-cap/schema`) | `SurfaceContract` diffs the schema; the `Schema` check fails if it is not regenerated from `src/cli/json.ts` | `test/build/schema-version-bump.test.ts` fails when a field is removed, retyped or made optional at an unchanged `schemaVersion`. A change of meaning with the same shape is not detected |
40
+ | The persisted evidence file, a serialization of `EvidenceModel` | `ApiContract` (evidence baseline) for the type | The committed evidence of two examples validates against the schema; a freshly written file is not checked |
41
+ | The generated manifest's shape | Tests in `test/build/manifest.test.ts` | No baseline diff |
42
+ | The section headings of the generated Markdown (`ENVIRONMENT.md`, the ownership and usage reports), the comment headers of `.env.example`, and the Action summary's sections | `SurfaceContract` (renderer files listed under `internal-package-contract.surfaceRenderers` in `package.json`) | The wording inside a section, and a heading built from a variable or feature name, are not baselined |
43
+ | The `envCap.schema` field in a package's `package.json`, and the `packages` and `tsconfig` options | Tests in `test/build/resolution/` | No baseline diff for the field |
44
+ | The files and templates `env-cap init` writes | `test/cli/init.test.ts` pins the exact templates | None found |
45
+ | The GitHub Action's input names and defaults | `SurfaceContract` | Input descriptions are not baselined; the summary's section headings are, through the row above |
46
+ | The supported toolchain: Node.js `>=22` and `moduleResolution` `node16`, `nodenext` or `bundler` | `EngineMatrix` (Node 22 and 24) and `TypeResolution` | Node 26 runs as an informational job |
47
+ | TypeScript 5, 6 and 7 for type-checking every entry point except `./eslint-plugin`, under `strict` and full library checking | `scripts/typescript-compat.mjs` in CI | CI installs the newest 5.x, 6.x and 7.x only, in `typescript-5` and `typescript-compat`, which `required` waits for |
47
48
 
48
49
  The Action is used through a major tag: `uses: maverickcer/env-cap@v0` while the package is `0.x`, `@v1` from 1.0.0. That tag moves only within a major version.
49
50
 
@@ -72,7 +73,7 @@ Never covered by semver:
72
73
 
73
74
  How a `0.x` release level is chosen:
74
75
 
75
- 1. For changesets it generates from commit messages, the release tooling lowers each level by one below 1.0: a breaking commit releases a minor, a `feat` commit a patch. A hand-written changeset is released at the level it names.
76
+ 1. For changesets it generates from commit messages, the release tooling lowers each level by one below 1.0. A breaking commit releases a minor, and a `feat` commit a patch. A hand-written changeset is released at the level it names.
76
77
  2. The `ApiContract` check requires only a minor for a breaking API diff.
77
78
  3. Commit-generated bumps stop below 1.0.0. Crossing it takes a hand-written `major` changeset, and the workflow only posts a notice when its release pull request is opened. A person merges every release pull request.
78
79