@maverickcer/env-cap 0.7.3 → 0.7.5

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 (238) hide show
  1. package/ADOPTION.md +106 -124
  2. package/AGENTS.md +14 -13
  3. package/CHANGELOG.md +23 -0
  4. package/CODE_REVIEW.md +69 -173
  5. package/CONTRIBUTING.md +57 -74
  6. package/GUIDE.md +393 -872
  7. package/README.md +82 -77
  8. package/RELEASING.md +17 -15
  9. package/SECURITY.md +76 -227
  10. package/SUPPORT.md +21 -45
  11. package/VERSIONING.md +68 -105
  12. package/benchmarks/READING-BENCHMARKS.md +13 -7
  13. package/benchmarks/WRITING-BENCHMARKS.md +1 -1
  14. package/dist/.dts/_ipc/build-fs.d.ts +9 -14
  15. package/dist/.dts/_ipc/build-fs.d.ts.map +1 -1
  16. package/dist/.dts/_ipc/compiler-api.d.ts +6 -6
  17. package/dist/.dts/_ipc/display-path.d.ts.map +1 -1
  18. package/dist/.dts/_ipc/generated-banner.d.ts +8 -8
  19. package/dist/.dts/_ipc/glob.d.ts +6 -6
  20. package/dist/.dts/_ipc/no-node-fs.d.ts +0 -14
  21. package/dist/.dts/_ipc/no-node-fs.d.ts.map +1 -1
  22. package/dist/.dts/build/lifecycle-model.d.ts +8 -3
  23. package/dist/.dts/build/lifecycle-model.d.ts.map +1 -1
  24. package/dist/.dts/build/sarif.d.ts.map +1 -1
  25. package/dist/.dts/helpers/index.d.ts +1 -1
  26. package/dist/.dts/runtime/create.d.ts +3 -0
  27. package/dist/.dts/runtime/create.d.ts.map +1 -1
  28. package/dist/.dts/runtime/document.d.ts +7 -4
  29. package/dist/.dts/runtime/document.d.ts.map +1 -1
  30. package/dist/.dts/runtime/index.d.ts +11 -10
  31. package/dist/.dts/runtime/index.d.ts.map +1 -1
  32. package/dist/.dts/runtime/types.d.ts +16 -0
  33. package/dist/.dts/runtime/types.d.ts.map +1 -1
  34. package/dist/.dts/runtime/validate.d.ts +14 -1
  35. package/dist/.dts/runtime/validate.d.ts.map +1 -1
  36. package/dist/.dts7/_ipc/build-fs.d.ts +48 -0
  37. package/dist/.dts7/_ipc/build-fs.d.ts.map +1 -0
  38. package/dist/.dts7/_ipc/compiler-api.d.ts +17 -0
  39. package/dist/.dts7/_ipc/compiler-api.d.ts.map +1 -0
  40. package/dist/.dts7/_ipc/display-path.d.ts +27 -0
  41. package/dist/.dts7/_ipc/display-path.d.ts.map +1 -0
  42. package/dist/.dts7/_ipc/generated-banner.d.ts +58 -0
  43. package/dist/.dts7/_ipc/generated-banner.d.ts.map +1 -0
  44. package/dist/.dts7/_ipc/glob.d.ts +22 -0
  45. package/dist/.dts7/_ipc/glob.d.ts.map +1 -0
  46. package/dist/.dts7/_ipc/no-node-fs.d.ts +21 -0
  47. package/dist/.dts7/_ipc/no-node-fs.d.ts.map +1 -0
  48. package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts +134 -0
  49. package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts.map +1 -0
  50. package/dist/.dts7/_ipc/typescript.d.ts +20 -0
  51. package/dist/.dts7/_ipc/typescript.d.ts.map +1 -0
  52. package/dist/.dts7/build/assemble-project.d.ts +47 -0
  53. package/dist/.dts7/build/assemble-project.d.ts.map +1 -0
  54. package/dist/.dts7/build/change-model.d.ts +63 -0
  55. package/dist/.dts7/build/change-model.d.ts.map +1 -0
  56. package/dist/.dts7/build/check-artifacts.d.ts +48 -0
  57. package/dist/.dts7/build/check-artifacts.d.ts.map +1 -0
  58. package/dist/.dts7/build/citation-verification.d.ts +62 -0
  59. package/dist/.dts7/build/citation-verification.d.ts.map +1 -0
  60. package/dist/.dts7/build/compatibility.d.ts +83 -0
  61. package/dist/.dts7/build/compatibility.d.ts.map +1 -0
  62. package/dist/.dts7/build/compiler-api.d.ts +12 -0
  63. package/dist/.dts7/build/compiler-api.d.ts.map +1 -0
  64. package/dist/.dts7/build/contract-model.d.ts +93 -0
  65. package/dist/.dts7/build/contract-model.d.ts.map +1 -0
  66. package/dist/.dts7/build/deep-equal.d.ts +9 -0
  67. package/dist/.dts7/build/deep-equal.d.ts.map +1 -0
  68. package/dist/.dts7/build/deep-freeze.d.ts +20 -0
  69. package/dist/.dts7/build/deep-freeze.d.ts.map +1 -0
  70. package/dist/.dts7/build/dependency-graph.d.ts +170 -0
  71. package/dist/.dts7/build/dependency-graph.d.ts.map +1 -0
  72. package/dist/.dts7/build/dependency-model.d.ts +81 -0
  73. package/dist/.dts7/build/dependency-model.d.ts.map +1 -0
  74. package/dist/.dts7/build/discover.d.ts +41 -0
  75. package/dist/.dts7/build/discover.d.ts.map +1 -0
  76. package/dist/.dts7/build/display-path.d.ts +6 -0
  77. package/dist/.dts7/build/display-path.d.ts.map +1 -0
  78. package/dist/.dts7/build/docs.d.ts +176 -0
  79. package/dist/.dts7/build/docs.d.ts.map +1 -0
  80. package/dist/.dts7/build/env-example.d.ts +85 -0
  81. package/dist/.dts7/build/env-example.d.ts.map +1 -0
  82. package/dist/.dts7/build/errors.d.ts +78 -0
  83. package/dist/.dts7/build/errors.d.ts.map +1 -0
  84. package/dist/.dts7/build/evidence-cache.d.ts +74 -0
  85. package/dist/.dts7/build/evidence-cache.d.ts.map +1 -0
  86. package/dist/.dts7/build/evidence-model.d.ts +50 -0
  87. package/dist/.dts7/build/evidence-model.d.ts.map +1 -0
  88. package/dist/.dts7/build/evidence-reference.d.ts +67 -0
  89. package/dist/.dts7/build/evidence-reference.d.ts.map +1 -0
  90. package/dist/.dts7/build/evidence-snapshot.d.ts +148 -0
  91. package/dist/.dts7/build/evidence-snapshot.d.ts.map +1 -0
  92. package/dist/.dts7/build/exclusive-group.d.ts +19 -0
  93. package/dist/.dts7/build/exclusive-group.d.ts.map +1 -0
  94. package/dist/.dts7/build/finding-model.d.ts +80 -0
  95. package/dist/.dts7/build/finding-model.d.ts.map +1 -0
  96. package/dist/.dts7/build/generate-documentation.d.ts +176 -0
  97. package/dist/.dts7/build/generate-documentation.d.ts.map +1 -0
  98. package/dist/.dts7/build/generate-env-artifacts.d.ts +191 -0
  99. package/dist/.dts7/build/generate-env-artifacts.d.ts.map +1 -0
  100. package/dist/.dts7/build/generate-evidence.d.ts +77 -0
  101. package/dist/.dts7/build/generate-evidence.d.ts.map +1 -0
  102. package/dist/.dts7/build/generate-manifest.d.ts +101 -0
  103. package/dist/.dts7/build/generate-manifest.d.ts.map +1 -0
  104. package/dist/.dts7/build/generate-usage.d.ts +95 -0
  105. package/dist/.dts7/build/generate-usage.d.ts.map +1 -0
  106. package/dist/.dts7/build/generated-banner.d.ts +43 -0
  107. package/dist/.dts7/build/generated-banner.d.ts.map +1 -0
  108. package/dist/.dts7/build/glob.d.ts +6 -0
  109. package/dist/.dts7/build/glob.d.ts.map +1 -0
  110. package/dist/.dts7/build/governance-fields.d.ts +34 -0
  111. package/dist/.dts7/build/governance-fields.d.ts.map +1 -0
  112. package/dist/.dts7/build/humanize-key.d.ts +14 -0
  113. package/dist/.dts7/build/humanize-key.d.ts.map +1 -0
  114. package/dist/.dts7/build/index.d.ts +105 -0
  115. package/dist/.dts7/build/index.d.ts.map +1 -0
  116. package/dist/.dts7/build/lifecycle-model.d.ts +179 -0
  117. package/dist/.dts7/build/lifecycle-model.d.ts.map +1 -0
  118. package/dist/.dts7/build/link.d.ts +223 -0
  119. package/dist/.dts7/build/link.d.ts.map +1 -0
  120. package/dist/.dts7/build/literal-eval.d.ts +24 -0
  121. package/dist/.dts7/build/literal-eval.d.ts.map +1 -0
  122. package/dist/.dts7/build/live-expirations.d.ts +47 -0
  123. package/dist/.dts7/build/live-expirations.d.ts.map +1 -0
  124. package/dist/.dts7/build/manifest.d.ts +31 -0
  125. package/dist/.dts7/build/manifest.d.ts.map +1 -0
  126. package/dist/.dts7/build/map-utils.d.ts +8 -0
  127. package/dist/.dts7/build/map-utils.d.ts.map +1 -0
  128. package/dist/.dts7/build/merge-documentation.d.ts +35 -0
  129. package/dist/.dts7/build/merge-documentation.d.ts.map +1 -0
  130. package/dist/.dts7/build/ownership-model.d.ts +59 -0
  131. package/dist/.dts7/build/ownership-model.d.ts.map +1 -0
  132. package/dist/.dts7/build/parse.d.ts +207 -0
  133. package/dist/.dts7/build/parse.d.ts.map +1 -0
  134. package/dist/.dts7/build/reference-projections.d.ts +170 -0
  135. package/dist/.dts7/build/reference-projections.d.ts.map +1 -0
  136. package/dist/.dts7/build/resolution/resolve-import.d.ts +58 -0
  137. package/dist/.dts7/build/resolution/resolve-import.d.ts.map +1 -0
  138. package/dist/.dts7/build/resolution/resolve-package-schema.d.ts +83 -0
  139. package/dist/.dts7/build/resolution/resolve-package-schema.d.ts.map +1 -0
  140. package/dist/.dts7/build/resolution/resolve-tsconfig-paths.d.ts +18 -0
  141. package/dist/.dts7/build/resolution/resolve-tsconfig-paths.d.ts.map +1 -0
  142. package/dist/.dts7/build/resolution/resolve-within-root.d.ts +35 -0
  143. package/dist/.dts7/build/resolution/resolve-within-root.d.ts.map +1 -0
  144. package/dist/.dts7/build/sarif.d.ts +66 -0
  145. package/dist/.dts7/build/sarif.d.ts.map +1 -0
  146. package/dist/.dts7/build/scan-dependencies.d.ts +70 -0
  147. package/dist/.dts7/build/scan-dependencies.d.ts.map +1 -0
  148. package/dist/.dts7/build/sort-by-identity.d.ts +14 -0
  149. package/dist/.dts7/build/sort-by-identity.d.ts.map +1 -0
  150. package/dist/.dts7/build/source-position.d.ts +69 -0
  151. package/dist/.dts7/build/source-position.d.ts.map +1 -0
  152. package/dist/.dts7/build/tool-version.d.ts +8 -0
  153. package/dist/.dts7/build/tool-version.d.ts.map +1 -0
  154. package/dist/.dts7/build/types.d.ts +7 -0
  155. package/dist/.dts7/build/types.d.ts.map +1 -0
  156. package/dist/.dts7/build/typescript.d.ts +6 -0
  157. package/dist/.dts7/build/typescript.d.ts.map +1 -0
  158. package/dist/.dts7/build/usage-report.d.ts +124 -0
  159. package/dist/.dts7/build/usage-report.d.ts.map +1 -0
  160. package/dist/.dts7/cli/filesystem.d.ts +7 -0
  161. package/dist/.dts7/cli/filesystem.d.ts.map +1 -0
  162. package/dist/.dts7/eslint-plugin/glob.d.ts +7 -0
  163. package/dist/.dts7/eslint-plugin/glob.d.ts.map +1 -0
  164. package/dist/.dts7/eslint-plugin/index.d.ts +27 -0
  165. package/dist/.dts7/eslint-plugin/index.d.ts.map +1 -0
  166. package/dist/.dts7/eslint-plugin/no-node-fs.d.ts +15 -0
  167. package/dist/.dts7/eslint-plugin/no-node-fs.d.ts.map +1 -0
  168. package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts +23 -0
  169. package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts.map +1 -0
  170. package/dist/.dts7/evidence/define-projection.d.ts +52 -0
  171. package/dist/.dts7/evidence/define-projection.d.ts.map +1 -0
  172. package/dist/.dts7/evidence/index.d.ts +23 -0
  173. package/dist/.dts7/evidence/index.d.ts.map +1 -0
  174. package/dist/.dts7/helpers/index.d.ts +135 -0
  175. package/dist/.dts7/helpers/index.d.ts.map +1 -0
  176. package/dist/.dts7/helpers/processors.d.ts +32 -0
  177. package/dist/.dts7/helpers/processors.d.ts.map +1 -0
  178. package/dist/.dts7/helpers/validators.d.ts +68 -0
  179. package/dist/.dts7/helpers/validators.d.ts.map +1 -0
  180. package/dist/.dts7/node/index.d.ts +2 -0
  181. package/dist/.dts7/node/index.d.ts.map +1 -0
  182. package/dist/.dts7/runtime/cache.d.ts +17 -0
  183. package/dist/.dts7/runtime/cache.d.ts.map +1 -0
  184. package/dist/.dts7/runtime/create.d.ts +23 -0
  185. package/dist/.dts7/runtime/create.d.ts.map +1 -0
  186. package/dist/.dts7/runtime/document.d.ts +223 -0
  187. package/dist/.dts7/runtime/document.d.ts.map +1 -0
  188. package/dist/.dts7/runtime/errors.d.ts +55 -0
  189. package/dist/.dts7/runtime/errors.d.ts.map +1 -0
  190. package/dist/.dts7/runtime/index.d.ts +25 -0
  191. package/dist/.dts7/runtime/index.d.ts.map +1 -0
  192. package/dist/.dts7/runtime/registry.d.ts +12 -0
  193. package/dist/.dts7/runtime/registry.d.ts.map +1 -0
  194. package/dist/.dts7/runtime/reset.d.ts +8 -0
  195. package/dist/.dts7/runtime/reset.d.ts.map +1 -0
  196. package/dist/.dts7/runtime/types.d.ts +191 -0
  197. package/dist/.dts7/runtime/types.d.ts.map +1 -0
  198. package/dist/.dts7/runtime/validate.d.ts +27 -0
  199. package/dist/.dts7/runtime/validate.d.ts.map +1 -0
  200. package/dist/{build-LFHPVDQL.js → build-DNAYWD2B.js} +8 -5
  201. package/dist/build-DNAYWD2B.js.map +1 -0
  202. package/dist/build.cjs +7 -4
  203. package/dist/build.cjs.map +1 -1
  204. package/dist/build.js +7 -4
  205. package/dist/build.js.map +1 -1
  206. package/dist/build.ts7.d.cts +1 -0
  207. package/dist/build.ts7.d.ts +1 -0
  208. package/dist/{chunk-ZW3BLAPD.js → chunk-HAGMVMN5.js} +2 -2
  209. package/dist/cli/index.js +3 -3
  210. package/dist/eslint-plugin/index.cjs +8 -5
  211. package/dist/eslint-plugin/index.cjs.map +1 -1
  212. package/dist/eslint-plugin/index.js +8 -5
  213. package/dist/eslint-plugin/index.js.map +1 -1
  214. package/dist/eslint-plugin/index.ts7.d.cts +1 -0
  215. package/dist/eslint-plugin/index.ts7.d.ts +1 -0
  216. package/dist/evidence.ts7.d.cts +1 -0
  217. package/dist/evidence.ts7.d.ts +1 -0
  218. package/dist/helpers.ts7.d.cts +1 -0
  219. package/dist/helpers.ts7.d.ts +1 -0
  220. package/dist/index.cjs.map +1 -1
  221. package/dist/index.js.map +1 -1
  222. package/dist/index.ts7.d.cts +1 -0
  223. package/dist/index.ts7.d.ts +1 -0
  224. package/dist/node.ts7.d.cts +1 -0
  225. package/dist/node.ts7.d.ts +1 -0
  226. package/examples/README.md +46 -80
  227. package/package.json +37 -6
  228. package/schemas/env-cap-report.schema.json +1 -1
  229. package/skills/env-cap/SKILL.md +1 -1
  230. package/skills/env-cap/references/api.md +1 -1
  231. package/specs/architecture.md +2 -2
  232. package/specs/decisions/0001-runtime-documentation-separation.md +1 -1
  233. package/specs/decisions/0014-cross-package-schema-discovery.md +4 -1
  234. package/specs/decisions/0023-tsconfig-path-alias-resolution.md +4 -1
  235. package/specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md +13 -8
  236. package/specs/generated-artifacts.md +14 -2
  237. package/dist/build-LFHPVDQL.js.map +0 -1
  238. /package/dist/{chunk-ZW3BLAPD.js.map → chunk-HAGMVMN5.js.map} +0 -0
package/README.md CHANGED
@@ -6,25 +6,23 @@
6
6
  [![Mutation score: the share of applicable mutants the tests detect](https://img.shields.io/endpoint?url=https://maverickcer.github.io/env-cap/mutation-badge.json)](https://maverickcer.github.io/env-cap/mutation.json)
7
7
  [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/MaverickCER/env-cap/badge)](https://scorecard.dev/viewer/?uri=github.com/MaverickCER/env-cap)
8
8
  [![Bundle size: gzip size of the entry point against its budget](https://img.shields.io/endpoint?url=https://maverickcer.github.io/env-cap/size-badge.json)](https://maverickcer.github.io/env-cap/size.json)
9
- [![Socket Badge](https://badge.socket.dev/npm/package/@maverickcer/env-cap/latest)](https://socket.dev/npm/package/@maverickcer/env-cap)
9
+ ![Socket Badge](https://badge.socket.dev/npm/package/@maverickcer/env-cap/latest)
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
- **Define who owns your environment variables, why they exist, and where they are used.**
13
+ **Know who owns each environment variable, why it exists, and when it expires.**
14
14
 
15
- `env-cap` turns environment configuration into capability-owned contracts you can version, review, validate, document, and query. It keeps `dotenv`, Zod, envalid, t3-env, your secret manager, and plain `process.env` exactly where they are, and adds the layer they do not provide: ownership, lifecycle, and project-wide evidence about whether declared configuration is actually consumed.
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.
16
16
 
17
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)
18
18
 
19
19
  ## Why it exists
20
20
 
21
- **Benefit:** every environment variable has an owner, a reason to exist, and a lifecycle you can query, so a rotation deadline or an orphaned secret is found by a report instead of an outage.
21
+ **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
22
 
23
- **Problem:** a configuration value can be perfectly valid and still be a problem. A secret manager stores a credential securely and a validator confirms its shape, but neither says why the variable exists, which capability depends on it, who owns it, when it should be rotated or retired, or whether anything still consumes it. That knowledge drifts into wikis, Slack threads, and memory, until the application accepts a variable that nobody owns, nobody uses, or nobody remembers to retire.
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.
24
24
 
25
- **Who it is for:** platform and staff engineers responsible for configuration across teams or packages, and teams whose environment has outgrown a single `.env` convention.
26
-
27
- **Why it matters:** an undetected expiry or an unowned secret is a security and availability risk that no validator can see, because the value itself is well-formed.
25
+ **Who it is for:** application developers who have shipped an undefined variable to production, and platform engineers who own configuration across teams.
28
26
 
29
27
  ## How it differs
30
28
 
@@ -35,11 +33,19 @@
35
33
  | Secret manager | Stores and manages secrets | Which capability in the codebase actually consumes the secret |
36
34
  | `env-cap` | Defines ownership, lifecycle, and consumption contracts | Does not replace loading, secret storage, or application-specific validation |
37
35
 
38
- `env-cap` is additive: use it with your existing validator or processor, or with its lightweight helpers when a validation library is unnecessary. [Migration guides](specs/migrations/README.md) cover `dotenv`, Zod, envalid, and t3-env, including cases where switching is not worth it.
36
+ 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.
39
37
 
40
38
  ## What it does
41
39
 
42
- A capability declares the environment it owns next to the validation it already needs. A build-time pass reads those declarations and your source, and writes a project-wide manifest, documentation, an ownership report, and an evidence artifact. At runtime the application validates its environment against that manifest and reads typed, capability-scoped values.
40
+ Each entry point has one reader. The [Guide](GUIDE.md) tells each reader's story in full.
41
+
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 |
43
49
 
44
50
  ```text
45
51
  declare → generate → validate → consume
@@ -47,44 +53,40 @@ declare → generate → validate → consume
47
53
 
48
54
  ### See it run
49
55
 
50
- **Every environment variable has an owner, a reason to exist, and a lifecycle you can query.**
51
-
52
- A capability declares the environment it owns alongside the validation already needed at runtime:
56
+ A contract declares the variables it owns next to their validation. This excerpt is from [`examples/application/src/env.ts`](https://github.com/MaverickCER/env-cap/blob/main/examples/application/src/env.ts), the file CI runs:
53
57
 
54
58
  ```ts
55
- // features/payments/env.schema.ts
59
+ // examples/application/src/env.ts (excerpt: other variables and fields omitted)
60
+ import { createEnv, documentEnv, type RawEnv } from "@maverickcer/env-cap"
61
+ import { processors } from "@maverickcer/env-cap/helpers"
56
62
 
57
- import { createEnv, documentEnv } from "@maverickcer/env-cap"
58
-
59
- const paymentsSchema = {
63
+ const schema = {
64
+ DATABASE_URL: { processor: processors.toURL() },
60
65
  STRIPE_KEY: {
61
- validator: (value: string) => value.startsWith("sk_") || 'Expected a key starting with "sk_".',
66
+ processor: (value: unknown): string => String(value ?? ""),
67
+ validator: (value: string, rawEnv: RawEnv) => {
68
+ if (rawEnv["PAYMENT_PROVIDER"] !== "stripe") return true
69
+ return value.length > 0 || "Stripe key is required when PAYMENT_PROVIDER=stripe."
70
+ },
62
71
  },
63
72
  }
64
73
 
65
- export const paymentsEnv = createEnv(paymentsSchema, { name: "payments" })
74
+ export const env = createEnv(schema, { name: "app", source: import.meta.url })
66
75
 
67
- documentEnv(paymentsSchema, {
68
- owner: "payments-team",
76
+ documentEnv(schema, {
77
+ owner: "platform-team",
69
78
  variables: {
79
+ DATABASE_URL: { description: "Postgres connection string.", required: true },
70
80
  STRIPE_KEY: {
71
- description: "Stripe secret key used to create charges and process refunds.",
72
- owner: "payments-team",
73
- expiresAt: "2027-01-01",
74
- sensitivity: "secret",
81
+ description: "Stripe secret key used to authenticate server-side API calls.",
82
+ required: true,
83
+ expiresAt: "2026-09-01",
75
84
  },
76
85
  },
77
86
  })
78
87
  ```
79
88
 
80
- Generate, then validate: the build-time analysis writes the manifest your code imports
81
- (`./generated/env.manifest`) and the evidence artifact, with one command (`npx env-cap init` scaffolds
82
- the same thing as a script, `scripts/generate-env.mjs`). The manifest and the
83
- persisted evidence artifact -- the two outputs a real project actually reads
84
- at runtime/in CI (see [ADR 0046](specs/decisions/0046-cli-restricted-to-runtime-and-evidence-output.md))
85
- -- come from the CLI itself; the human-facing docs/ownership report come
86
- from a small script calling `@maverickcer/env-cap/build` directly (see
87
- `examples/application/scripts/generate-docs`):
89
+ The CLI writes the manifest your code imports and the evidence file ([ADR 0046](specs/decisions/0046-cli-restricted-to-runtime-and-evidence-output.md)). A short script calls `@maverickcer/env-cap/build` for the human-facing docs and ownership report:
88
90
 
89
91
  ```text
90
92
  $ npx env-cap --include src/env.ts --location src/generated/env.manifest.ts --evidence docs/env.evidence.json
@@ -103,95 +105,98 @@ $ npx tsx scripts/generate-docs/run.ts
103
105
  - STRIPE_KEY in app
104
106
  ```
105
107
 
106
- This is real output from [`examples/application`](https://github.com/MaverickCER/env-cap/tree/main/examples/application)'s own `npm run docs` and `npm run docs:reports` scripts, not a mockup. The age (`Nd`) is counted from the day you run it, so it is shown as `N` here instead of a number that would rot.
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.
107
109
 
108
- The important part is what the analysis can establish: `STRIPE_KEY` has an ownership and expiration record, its declared expiration has passed, and `DATABASE_URL` and `STRIPE_KEY` are declared as owned but are not consumed by the analyzed application. Those are facts about the application's configuration and dependencies, not merely the result of a value validator.
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.
109
111
 
110
112
  ### Evidence it works
111
113
 
112
- - **Real fixtures:** the output above comes from a runnable example that is also a regression test, and two more stages (a [team service](https://github.com/MaverickCER/env-cap/tree/main/examples/team-service) and an [enterprise platform](https://github.com/MaverickCER/env-cap/tree/main/examples/enterprise-platform)) show the model at scale.
113
- - **Enforced in CI:** coverage is a ratchet that may only move up, mutation score is a gate ([CODE_REVIEW.md](CODE_REVIEW.md)), and the README's own demo is re-run and compared on every change.
114
- - **Runtime-tested:** the runtime and helpers are verified against real Node, Bun, and Deno in CI, not assumed isomorphic.
115
- - **Hard size budget:** the runtime entry point stays under 3 KB gzip and the helpers under 4 KB, enforced before publish ([ADR 0008](specs/decisions/0008-gzip-size-budget.md)).
116
- - **Verifiable release:** published with npm OIDC provenance and no long-lived token ([SECURITY.md](SECURITY.md#supply-chain-posture)).
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.
115
+ - **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
+ - **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.
118
+ - **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.
117
119
 
118
120
  ## Install and verify
119
121
 
120
- **Prerequisites:** Node.js `>=22`. TypeScript 5, 6, or 7 is needed only for the build-time generator (the runtime works in plain JavaScript); the [runtime and TypeScript requirements](GUIDE.md#runtime-support-matrix) are in the Guide.
122
+ **Prerequisites:** Node.js `>=22`. Your own TypeScript is optional. The generator uses it when it is version 5 or 6, and otherwise the bundled TypeScript 6 compiler. CI tests the newest 5.x only; the 5.0 floor is untested. The runtime works in plain JavaScript ([requirements](GUIDE.md#requirements)).
121
123
 
122
124
  ```sh
123
125
  npm install @maverickcer/env-cap
124
- npx env-cap init # scaffolds env.schema.ts and scripts/generate-env.mjs
125
- npm install --save-dev typescript # the generator parses your schema with it
126
+ npx env-cap init # writes env.schema.ts and scripts/generate-env.mjs
126
127
  node scripts/generate-env.mjs
127
128
  ```
128
129
 
129
- **Using an AI agent?** Give it [the skill](https://raw.githubusercontent.com/MaverickCER/env-cap/main/skills/env-cap/SKILL.md): a short manual written from this package's own exports, with the rules a type signature cannot say.
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.
130
131
 
131
- `init` never overwrites existing files and never edits `package.json`. **Verify it works:** the generator prints `Discovered 1 contract(s).` and writes the manifest, `docs/ENVIRONMENT.md`, and an ownership report. Then validate once at startup and read values through the contract:
132
+ 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:
132
133
 
133
134
  ```ts
134
135
  import { validateEnv } from "@maverickcer/env-cap"
135
136
  import { manifest } from "./generated/env.manifest"
136
- import { paymentsEnv } from "./features/payments/env.schema"
137
+ import { exampleEnv } from "./env.schema"
137
138
 
138
139
  await validateEnv({ manifest, values: process.env })
139
- paymentsEnv.STRIPE_KEY
140
+ exampleEnv.EXAMPLE_API_URL
140
141
  ```
141
142
 
142
- The smallest contract is one `createEnv` call with a validator per variable ([Core workflow](GUIDE.md#core-workflow) has the complete generate and validate cycle).
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.
143
144
 
144
145
  ## Fit and capabilities
145
146
 
146
- **Use cases:** find expired or unowned secrets before they page someone; document every variable from the code instead of a wiki; let each team own the variables its feature needs; give CI bots and coding agents concrete facts (`payments owns STRIPE_KEY`, `STRIPE_KEY is declared but unconsumed`) instead of "configuration check failed".
147
+ **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".
147
148
 
148
149
  **Core capabilities:**
149
150
 
150
- - Capability-scoped contracts with validators, ownership, sensitivity, and expiry ([model](GUIDE.md#capability-owned-contracts)).
151
- - A project-wide manifest, environment docs, `.env.example`, and an ownership and unconsumed-variable report, generated by static analysis that never executes your schema files.
152
- - A persisted evidence artifact for change tracking, a CLI, a [GitHub Action](GUIDE.md#github-action), scheduled rotation alerts, and an [ESLint plugin](GUIDE.md#eslint-plugin).
153
- - Adoption from one centralized schema to per-feature and per-package contracts; the manifest stays project-wide however the schema is organized.
151
+ - Capability-scoped contracts with validators, owners, sensitivity and expiry dates ([contracts](GUIDE.md#capability-owned-contracts)).
152
+ - A manifest, environment docs, `.env.example` and an ownership report, from static analysis that never imports your schema files.
153
+ - 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
+ - One central schema or one contract per feature or package; the manifest stays project-wide either way.
154
155
 
155
- **How it works:** the runtime and the build tooling are separate on purpose. Runtime validation needs no dependencies and no filesystem; the build pass analyzes your source and runs only in development and CI ([Architecture](specs/architecture.md)).
156
+ **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)).
156
157
 
157
- **Integration:** it works beside the validator and secret manager you already use, so nothing is replaced. **Runtimes:** Node.js 22+, browser bundles, edge runtimes, Bun, and Deno for the runtime; the build entry is Node-only ([support matrix](GUIDE.md#runtime-support-matrix)). **Configuration and extension:** plug any `Validator<T>` or `Processor<T>` function into a contract, share contracts from a reusable package, and resolve TypeScript path aliases ([Guide](GUIDE.md)).
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)).
158
159
 
159
160
  ## Limits and when not to use it
160
161
 
161
- - **Skip it when** the application is small, one team owns every configuration decision, there are only a few stable variables, ownership is already obvious, or you do not need project-wide evidence about usage. A validation library or `dotenv` may be all you need.
162
- - **Trade-offs:** it adds a build step and a declaration per variable, and its reports are only as accurate as those declarations. It cannot see variables read from outside the code it analyzes.
163
- - **Install weight:** the build entry bundles a TypeScript 6 compiler (about 24 MB unpacked) used only in development and CI; the runtime never reaches it, which CI verifies ([Adoption guide](ADOPTION.md#bundle-size-and-performance)).
164
- - **Automation:** agents and bots can consume the same manifests and evidence, but a structured finding does not guarantee a correct fix; the automation owns its retry and validation loop. See the [AI integration prompt](PROMPT.md).
162
+ - **Skip it when** one team owns every variable, there are few of them, and ownership is obvious. A validator or `dotenv` may be all you need.
163
+ - **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
+ - **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
+ - **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).
165
167
 
166
168
  ## Security and supply chain
167
169
 
168
- - **Guarantees:** the runtime never persists, retrieves, rotates, or logs secrets, and contracts redact themselves when logged or serialized ([runtime security model](SECURITY.md#runtime-security-model)).
169
- - **Trust boundaries:** the build tool parses schema files as ASTs and never imports or executes them, but it does not sandbox the rest of your build, and a validator you write can still log ([build-time model](SECURITY.md#build-time-security-model), [your responsibilities](SECURITY.md#application-responsibilities)).
170
- - **Dependencies and licence:** zero runtime dependencies in the runtime and helpers entry points; the build entry bundles one compiler. MIT licensed.
171
- - **Release integrity:** npm OIDC trusted publishing with provenance ([supply-chain posture](SECURITY.md#supply-chain-posture)). Report a vulnerability through [SECURITY.md](SECURITY.md#reporting-a-vulnerability).
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)).
171
+ - **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
+ - **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
+ - **Dependencies:** what installing the package adds is generated from `package.json` into the [Adoption guide](ADOPTION.md#security--threat-model). MIT licensed.
174
+ - **Release integrity:** releases publish from CI over npm OIDC with a provenance attestation, and the repository stores no npm token. A manual last-resort publish carries no attestation ([supply chain](SECURITY.md#supply-chain-posture)).
175
+ - **Report a vulnerability** privately: [SECURITY.md](SECURITY.md#reporting-a-vulnerability).
172
176
 
173
177
  ## Maturity, versioning and support
174
178
 
175
- Pre-1.0 (see the npm badge for the current version). Per [VERSIONING.md](VERSIONING.md), a minor release may include a breaking change to the Stable tier before 1.0, so pin accordingly. Security fixes target the latest published `0.x` only; there is no backport branch until 1.0 ([Adoption guide](ADOPTION.md#versioning-stability-and-long-term-support)).
179
+ Pre-1.0; the npm badge shows the current version. Before 1.0, a minor release may break the Stable tier, so pin a version ([VERSIONING.md](VERSIONING.md)). Security fixes target the latest `0.x` only, with no backport branch before 1.0.
176
180
 
177
- - **Upgrade and migrate:** read the [CHANGELOG](CHANGELOG.md) on every minor; [migration guides](specs/migrations/README.md) cover adoption from other tools.
178
- - **Release history:** [CHANGELOG](CHANGELOG.md) and [GitHub releases](https://github.com/MaverickCER/env-cap/releases); the process is in [RELEASING.md](RELEASING.md).
181
+ - **Upgrade:** read the [CHANGELOG](CHANGELOG.md) on every minor; [migration guides](specs/migrations/README.md) cover adoption from other tools.
182
+ - **Releases:** [GitHub releases](https://github.com/MaverickCER/env-cap/releases); a person merges every release pull request ([RELEASING.md](RELEASING.md)).
179
183
  - **Bugs and requests:** [open an issue](https://github.com/MaverickCER/env-cap/issues); see [SUPPORT.md](SUPPORT.md).
180
- - **Troubleshooting:** the [Guide's troubleshooting section](GUIDE.md#troubleshooting).
184
+ - **Troubleshooting:** the [Guide's troubleshooting table](GUIDE.md#troubleshooting).
181
185
 
182
186
  ## Documentation
183
187
 
184
- - **[Guide](GUIDE.md)**: the complete generate and validate workflow, validation contexts, reusable packages, path aliases, CLI, GitHub Action, ESLint plugin, and performance.
185
- - **[Adoption guide](ADOPTION.md)**: the decision-maker summary of security, bundle size, and versioning.
186
- - **[API reference](https://maverickcer.github.io/env-cap/api/)**: every exported symbol, generated from source.
187
- - **[Architecture](specs/architecture.md)** and **[ADRs](https://github.com/MaverickCER/env-cap/tree/main/specs/decisions)**: why it is designed this way.
188
- - **[Examples](https://github.com/MaverickCER/env-cap/tree/main/examples)**: runnable application, team-service, and enterprise-platform examples.
189
- - **Part of the MaverickCER toolkit:** `@maverickcer/env-cap` governs configuration and `data-cap` governs application data; `repo-contract` and `internal-package-contract` are how they are verified ([toolkit overview](https://github.com/MaverickCER/internal-package-contract/blob/main/TOOLKIT.md)).
188
+ - **[Guide](GUIDE.md):** one story per entry point and reader, the CLI options, the GitHub Action and the ESLint plugin.
189
+ - **[Adoption guide](ADOPTION.md):** what adopting costs, what it needs, and what it refuses to do.
190
+ - **[Security](SECURITY.md):** the reviewer's model of what is enforced, where, and what is not.
191
+ - **[API reference](https://maverickcer.github.io/env-cap/api/):** every exported symbol, generated from source.
192
+ - **[Architecture](specs/architecture.md)** and **[ADRs](https://github.com/MaverickCER/env-cap/tree/main/specs/decisions):** why it is designed this way.
193
+ - **[Examples](https://github.com/MaverickCER/env-cap/tree/main/examples):** runnable application, team-service, enterprise-platform and Next.js examples.
194
+ - **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)).
190
195
 
191
196
  ## Next steps
192
197
 
193
- - **Evaluate:** read the [Adoption guide](ADOPTION.md), then try env-cap against one real schema.
194
- - **Integrate:** follow the [Guide](GUIDE.md#core-workflow) and the [examples](https://github.com/MaverickCER/env-cap/tree/main/examples).
195
- - **Verify:** inspect the [security model](SECURITY.md#runtime-security-model) and the [architecture](specs/architecture.md).
198
+ - **Evaluate:** read the [Adoption guide](ADOPTION.md), then try env-cap on one real schema.
199
+ - **Integrate:** follow the [Guide](GUIDE.md#core-workflow) and run an [example](https://github.com/MaverickCER/env-cap/tree/main/examples).
200
+ - **Verify:** check the [security model](SECURITY.md#runtime-security-model) against the tests it names.
196
201
 
197
- Contributing: [CONTRIBUTING.md](CONTRIBUTING.md) covers setup, the change workflow, ADRs and changesets; [CODE_REVIEW.md](CODE_REVIEW.md) covers review. License: MIT, see [LICENSE](LICENSE).
202
+ Contributing: [CONTRIBUTING.md](CONTRIBUTING.md) covers setup and changesets; [CODE_REVIEW.md](CODE_REVIEW.md) covers review. License: MIT, see [LICENSE](LICENSE).
package/RELEASING.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  # Releasing @maverickcer/env-cap
4
4
 
5
- Maintainer-facing. Contributors don't run any of this: a normal change is just a pull request, and its
5
+ Maintainer-facing. Contributors run none of this: a normal change is a pull request, and its
6
6
  changeset is generated if it has none (see [`CONTRIBUTING.md`](CONTRIBUTING.md#making-a-change)).
7
7
  For what semver actually covers, see [`VERSIONING.md`](VERSIONING.md).
8
8
 
@@ -13,8 +13,8 @@ Releases are driven by [Changesets](https://github.com/changesets/changesets) an
13
13
  [`.github/workflows/release.yml`](https://github.com/MaverickCER/env-cap/blob/main/.github/workflows/release.yml),
14
14
  which calls a shared, pinned workflow. **No `NPM_TOKEN` secret exists in this repository** and none is
15
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; nothing
17
- publishes without that.
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").
18
18
 
19
19
  The loop:
20
20
 
@@ -28,10 +28,11 @@ The loop:
28
28
  changeset files, bumps `package.json`'s `version` and rewrites `CHANGELOG.md`. Review it and merge it
29
29
  yourself; it is never merged automatically.
30
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, packs the tarball, installs that tarball into an empty
32
- project and imports every entry point it declares. Only if all of that passes does the **publish** job
33
- run, and only from the default branch. It publishes exactly the tarball the build job made, over OIDC with
34
- a provenance attestation.
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.
35
36
  4. After publishing, the workflow tags the release `v<major>.<minor>.<patch>` on the merged commit,
36
37
  force-updates the floating major tag (`v0` while the package is 0.x, `v1` from 1.0.0), and asks npm what
37
38
  it now serves: the version must be there and must carry the provenance attestation, or the run goes red.
@@ -52,12 +53,12 @@ access, so it can't be done from a PR.
52
53
  GitHub Actions:
53
54
  - Organization or user: `maverickcer`
54
55
  - Repository: `env-cap`
55
- - Workflow filename: `release.yml` (exactly — just the filename, not a
56
+ - Workflow filename: `release.yml` (exactly: the filename alone, not a
56
57
  path; a mismatch here is the most common cause of the OIDC flow failing
57
58
  with a misleading `E404`)
58
59
  - Environment: leave blank unless `release.yml` is later scoped to a
59
60
  GitHub Environment
60
- 2. That's the whole trust relationship — `release.yml`'s `id-token: write`
61
+ 2. That is the whole trust relationship: `release.yml`'s `id-token: write`
61
62
  permission plus this registration. There is no token to copy anywhere.
62
63
 
63
64
  Until the package exists on npm, its settings page doesn't either. For the
@@ -83,8 +84,8 @@ Nothing is on npm; nothing to undo.
83
84
  ### B. The version pull request is merged, but the release failed
84
85
 
85
86
  `main` now has the version bump and changelog commit, but npm does not have the version. This is the common
86
- failure (OIDC misconfiguration, a failing `npm run verify` or packed-consumer check in the build job, a
87
- registry blip).
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).
88
89
 
89
90
  1. Confirm npm really doesn't have it: `npm view @maverickcer/env-cap versions --json`, and check the bumped version is
90
91
  absent.
@@ -96,7 +97,7 @@ registry blip).
96
97
  pull request to `main`. What happens next depends on the commit type. A `fix`, `feat`, `perf` or `revert`
97
98
  commit gets a changeset generated for it, so the workflow opens a new version pull request instead of
98
99
  publishing the stuck version; merging that publishes the next version, and the stuck version number is
99
- simply skipped. A commit type that releases nothing (`chore`, `ci`, `docs`) leaves no changeset, so the
100
+ skipped. A commit type that releases nothing (`chore`, `ci`, `docs`) leaves no changeset, so the
100
101
  workflow sees that the current `package.json` version isn't on npm and builds and publishes that version.
101
102
  5. Publishing by hand is the last resort, and it publishes without the provenance attestation that the
102
103
  workflow adds. If you must, publish that exact version from a clean tree
@@ -106,7 +107,7 @@ registry blip).
106
107
  ### C. Published to npm, but a later workflow step failed
107
108
 
108
109
  e.g. the publish succeeded but the floating major tag (`v0` or `v1`) roll failed. The release itself
109
- is done and correct. Just fix the trailing step manually:
110
+ is done and correct. Fix the trailing step by hand:
110
111
 
111
112
  ```bash
112
113
  git checkout main && git pull
@@ -141,8 +142,9 @@ the one manual step. Every release after that is automated.
141
142
  - **`E404` on publish with OIDC**: the trusted-publisher registration's
142
143
  workflow filename doesn't exactly match `release.yml`, or the
143
144
  org/user/repo fields are wrong.
144
- - **The build job's verify or packed-consumer step fails**: the version pull request merged with a red
145
- `main`, or the tarball does not contain what `exports` promises. Fix `main` first, then recover per case B.
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.
146
148
  - **The final "Verify what npm now serves" step fails**: npm did not return the version or its provenance
147
149
  attestation. Nothing is unpublished by the failure; look at the registry before doing anything else.
148
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