@maverickcer/env-cap 0.5.3 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (359) hide show
  1. package/ADOPTION.md +144 -0
  2. package/AGENTS.md +146 -0
  3. package/CHANGELOG.md +438 -0
  4. package/CODE_OF_CONDUCT.md +124 -0
  5. package/CODE_REVIEW.md +200 -0
  6. package/CONTRIBUTING.md +131 -0
  7. package/GUIDE.md +1214 -0
  8. package/PROMPT.md +89 -0
  9. package/README.md +97 -199
  10. package/RELEASING.md +160 -0
  11. package/SECURITY.md +270 -0
  12. package/SUPPORT.md +76 -0
  13. package/VERSIONING.md +118 -0
  14. package/benchmarks/READING-BENCHMARKS.md +197 -0
  15. package/benchmarks/README.md +126 -0
  16. package/benchmarks/WRITING-BENCHMARKS.md +252 -0
  17. package/benchmarks/performance-buildtime/BENCHMARKS.md +889 -0
  18. package/benchmarks/performance-runtime/BENCHMARKS.md +1988 -0
  19. package/dist/.dts/_ipc/build-fs.d.ts +53 -0
  20. package/dist/.dts/_ipc/build-fs.d.ts.map +1 -0
  21. package/dist/.dts/_ipc/compiler-api.d.ts +17 -0
  22. package/dist/.dts/_ipc/compiler-api.d.ts.map +1 -0
  23. package/dist/.dts/_ipc/display-path.d.ts +27 -0
  24. package/dist/.dts/_ipc/display-path.d.ts.map +1 -0
  25. package/dist/.dts/_ipc/generated-banner.d.ts +58 -0
  26. package/dist/.dts/_ipc/generated-banner.d.ts.map +1 -0
  27. package/dist/.dts/_ipc/glob.d.ts +22 -0
  28. package/dist/.dts/_ipc/glob.d.ts.map +1 -0
  29. package/dist/.dts/_ipc/no-node-fs.d.ts +34 -0
  30. package/dist/.dts/_ipc/no-node-fs.d.ts.map +1 -0
  31. package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts +134 -0
  32. package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts.map +1 -0
  33. package/dist/.dts/_ipc/typescript.d.ts +20 -0
  34. package/dist/.dts/_ipc/typescript.d.ts.map +1 -0
  35. package/dist/.dts/build/assemble-project.d.ts +1 -1
  36. package/dist/.dts/build/assemble-project.d.ts.map +1 -1
  37. package/dist/.dts/build/change-model.d.ts.map +1 -1
  38. package/dist/.dts/build/check-artifacts.d.ts.map +1 -1
  39. package/dist/.dts/build/citation-verification.d.ts.map +1 -1
  40. package/dist/.dts/build/compatibility.d.ts.map +1 -1
  41. package/dist/.dts/build/compiler-api.d.ts +12 -0
  42. package/dist/.dts/build/compiler-api.d.ts.map +1 -0
  43. package/dist/.dts/build/dependency-graph.d.ts +3 -1
  44. package/dist/.dts/build/dependency-graph.d.ts.map +1 -1
  45. package/dist/.dts/build/dependency-model.d.ts.map +1 -1
  46. package/dist/.dts/build/discover.d.ts.map +1 -1
  47. package/dist/.dts/build/display-path.d.ts +3 -21
  48. package/dist/.dts/build/display-path.d.ts.map +1 -1
  49. package/dist/.dts/build/docs.d.ts +1 -1
  50. package/dist/.dts/build/docs.d.ts.map +1 -1
  51. package/dist/.dts/build/env-example.d.ts.map +1 -1
  52. package/dist/.dts/build/evidence-cache.d.ts +1 -1
  53. package/dist/.dts/build/evidence-cache.d.ts.map +1 -1
  54. package/dist/.dts/build/evidence-model.d.ts +2 -2
  55. package/dist/.dts/build/evidence-snapshot.d.ts +25 -0
  56. package/dist/.dts/build/evidence-snapshot.d.ts.map +1 -1
  57. package/dist/.dts/build/finding-model.d.ts +1 -1
  58. package/dist/.dts/build/finding-model.d.ts.map +1 -1
  59. package/dist/.dts/build/generate-documentation.d.ts.map +1 -1
  60. package/dist/.dts/build/generate-env-artifacts.d.ts +23 -8
  61. package/dist/.dts/build/generate-env-artifacts.d.ts.map +1 -1
  62. package/dist/.dts/build/generate-evidence.d.ts.map +1 -1
  63. package/dist/.dts/build/generate-manifest.d.ts +1 -1
  64. package/dist/.dts/build/generate-manifest.d.ts.map +1 -1
  65. package/dist/.dts/build/generate-usage.d.ts +3 -3
  66. package/dist/.dts/build/generate-usage.d.ts.map +1 -1
  67. package/dist/.dts/build/generated-banner.d.ts +29 -38
  68. package/dist/.dts/build/generated-banner.d.ts.map +1 -1
  69. package/dist/.dts/build/glob.d.ts +3 -15
  70. package/dist/.dts/build/glob.d.ts.map +1 -1
  71. package/dist/.dts/build/index.d.ts +2 -2
  72. package/dist/.dts/build/lifecycle-model.d.ts.map +1 -1
  73. package/dist/.dts/build/link.d.ts.map +1 -1
  74. package/dist/.dts/build/literal-eval.d.ts +4 -3
  75. package/dist/.dts/build/literal-eval.d.ts.map +1 -1
  76. package/dist/.dts/build/live-expirations.d.ts.map +1 -1
  77. package/dist/.dts/build/manifest.d.ts.map +1 -1
  78. package/dist/.dts/build/merge-documentation.d.ts +35 -0
  79. package/dist/.dts/build/merge-documentation.d.ts.map +1 -0
  80. package/dist/.dts/build/parse.d.ts +12 -12
  81. package/dist/.dts/build/parse.d.ts.map +1 -1
  82. package/dist/.dts/build/reference-projections.d.ts +17 -3
  83. package/dist/.dts/build/reference-projections.d.ts.map +1 -1
  84. package/dist/.dts/build/resolution/resolve-import.d.ts +5 -0
  85. package/dist/.dts/build/resolution/resolve-import.d.ts.map +1 -1
  86. package/dist/.dts/build/resolution/resolve-package-schema.d.ts +1 -1
  87. package/dist/.dts/build/resolution/resolve-package-schema.d.ts.map +1 -1
  88. package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts +11 -94
  89. package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts.map +1 -1
  90. package/dist/.dts/build/sarif.d.ts.map +1 -1
  91. package/dist/.dts/build/scan-dependencies.d.ts +23 -0
  92. package/dist/.dts/build/scan-dependencies.d.ts.map +1 -1
  93. package/dist/.dts/build/types.d.ts +4 -53
  94. package/dist/.dts/build/types.d.ts.map +1 -1
  95. package/dist/.dts/build/typescript.d.ts +6 -0
  96. package/dist/.dts/build/typescript.d.ts.map +1 -0
  97. package/dist/.dts/build/usage-report.d.ts.map +1 -1
  98. package/dist/.dts/cli/filesystem.d.ts +4 -0
  99. package/dist/.dts/cli/filesystem.d.ts.map +1 -1
  100. package/dist/.dts/eslint-plugin/glob.d.ts +4 -15
  101. package/dist/.dts/eslint-plugin/glob.d.ts.map +1 -1
  102. package/dist/.dts/eslint-plugin/index.d.ts +3 -3
  103. package/dist/.dts/eslint-plugin/no-node-fs.d.ts +8 -18
  104. package/dist/.dts/eslint-plugin/no-node-fs.d.ts.map +1 -1
  105. package/dist/.dts/eslint-plugin/no-raw-process-env.d.ts.map +1 -1
  106. package/dist/.dts/evidence/index.d.ts +2 -2
  107. package/dist/.dts/helpers/index.d.ts +2 -2
  108. package/dist/.dts/helpers/processors.d.ts.map +1 -1
  109. package/dist/.dts/helpers/validators.d.ts.map +1 -1
  110. package/dist/.dts/runtime/cache.d.ts +0 -3
  111. package/dist/.dts/runtime/cache.d.ts.map +1 -1
  112. package/dist/.dts/runtime/create.d.ts.map +1 -1
  113. package/dist/.dts/runtime/document.d.ts.map +1 -1
  114. package/dist/.dts/runtime/index.d.ts +2 -2
  115. package/dist/.dts/runtime/registry.d.ts.map +1 -1
  116. package/dist/.dts/runtime/validate.d.ts.map +1 -1
  117. package/dist/{build-U326PI5A.js → build-WKDIAWF7.js} +685 -645
  118. package/dist/build-WKDIAWF7.js.map +1 -0
  119. package/dist/build.cjs +698 -651
  120. package/dist/build.cjs.map +1 -1
  121. package/dist/build.js +695 -649
  122. package/dist/build.js.map +1 -1
  123. package/dist/{chunk-BSTLSR2R.js → chunk-KEGYUHBU.js} +2 -2
  124. package/dist/chunk-KEGYUHBU.js.map +1 -0
  125. package/dist/cli/index.js +64 -63
  126. package/dist/cli/index.js.map +1 -1
  127. package/dist/eslint-plugin/index.cjs +95 -626
  128. package/dist/eslint-plugin/index.cjs.map +1 -1
  129. package/dist/eslint-plugin/index.js +94 -625
  130. package/dist/eslint-plugin/index.js.map +1 -1
  131. package/dist/evidence.cjs.map +1 -1
  132. package/dist/evidence.js.map +1 -1
  133. package/dist/helpers.cjs +4 -9
  134. package/dist/helpers.cjs.map +1 -1
  135. package/dist/helpers.js +4 -9
  136. package/dist/helpers.js.map +1 -1
  137. package/dist/index.cjs +11 -25
  138. package/dist/index.cjs.map +1 -1
  139. package/dist/index.js +11 -25
  140. package/dist/index.js.map +1 -1
  141. package/dist/node.cjs +10 -8
  142. package/dist/node.cjs.map +1 -1
  143. package/dist/node.js +10 -8
  144. package/dist/node.js.map +1 -1
  145. package/examples/README.md +95 -0
  146. package/node_modules/@typescript/old/LICENSE.txt +55 -0
  147. package/node_modules/@typescript/old/README.md +50 -0
  148. package/node_modules/@typescript/old/SECURITY.md +39 -0
  149. package/node_modules/@typescript/old/ThirdPartyNoticeText.txt +193 -0
  150. package/node_modules/@typescript/old/bin/tsc +2 -0
  151. package/node_modules/@typescript/old/bin/tsserver +2 -0
  152. package/node_modules/@typescript/old/lib/_tsc.js +134465 -0
  153. package/node_modules/@typescript/old/lib/_tsserver.js +659 -0
  154. package/node_modules/@typescript/old/lib/_typingsInstaller.js +222 -0
  155. package/node_modules/@typescript/old/lib/cs/diagnosticMessages.generated.json +2129 -0
  156. package/node_modules/@typescript/old/lib/de/diagnosticMessages.generated.json +2125 -0
  157. package/node_modules/@typescript/old/lib/es/diagnosticMessages.generated.json +2129 -0
  158. package/node_modules/@typescript/old/lib/fr/diagnosticMessages.generated.json +2129 -0
  159. package/node_modules/@typescript/old/lib/it/diagnosticMessages.generated.json +2125 -0
  160. package/node_modules/@typescript/old/lib/ja/diagnosticMessages.generated.json +2129 -0
  161. package/node_modules/@typescript/old/lib/ko/diagnosticMessages.generated.json +2129 -0
  162. package/node_modules/@typescript/old/lib/lib.d.ts +20 -0
  163. package/node_modules/@typescript/old/lib/lib.decorators.d.ts +382 -0
  164. package/node_modules/@typescript/old/lib/lib.decorators.legacy.d.ts +20 -0
  165. package/node_modules/@typescript/old/lib/lib.dom.asynciterable.d.ts +18 -0
  166. package/node_modules/@typescript/old/lib/lib.dom.d.ts +45125 -0
  167. package/node_modules/@typescript/old/lib/lib.dom.iterable.d.ts +18 -0
  168. package/node_modules/@typescript/old/lib/lib.es2015.collection.d.ts +150 -0
  169. package/node_modules/@typescript/old/lib/lib.es2015.core.d.ts +595 -0
  170. package/node_modules/@typescript/old/lib/lib.es2015.d.ts +26 -0
  171. package/node_modules/@typescript/old/lib/lib.es2015.generator.d.ts +75 -0
  172. package/node_modules/@typescript/old/lib/lib.es2015.iterable.d.ts +603 -0
  173. package/node_modules/@typescript/old/lib/lib.es2015.promise.d.ts +79 -0
  174. package/node_modules/@typescript/old/lib/lib.es2015.proxy.d.ts +126 -0
  175. package/node_modules/@typescript/old/lib/lib.es2015.reflect.d.ts +142 -0
  176. package/node_modules/@typescript/old/lib/lib.es2015.symbol.d.ts +44 -0
  177. package/node_modules/@typescript/old/lib/lib.es2015.symbol.wellknown.d.ts +324 -0
  178. package/node_modules/@typescript/old/lib/lib.es2016.array.include.d.ts +114 -0
  179. package/node_modules/@typescript/old/lib/lib.es2016.d.ts +19 -0
  180. package/node_modules/@typescript/old/lib/lib.es2016.full.d.ts +21 -0
  181. package/node_modules/@typescript/old/lib/lib.es2016.intl.d.ts +29 -0
  182. package/node_modules/@typescript/old/lib/lib.es2017.arraybuffer.d.ts +19 -0
  183. package/node_modules/@typescript/old/lib/lib.es2017.d.ts +24 -0
  184. package/node_modules/@typescript/old/lib/lib.es2017.date.d.ts +29 -0
  185. package/node_modules/@typescript/old/lib/lib.es2017.full.d.ts +21 -0
  186. package/node_modules/@typescript/old/lib/lib.es2017.intl.d.ts +42 -0
  187. package/node_modules/@typescript/old/lib/lib.es2017.object.d.ts +47 -0
  188. package/node_modules/@typescript/old/lib/lib.es2017.sharedmemory.d.ts +133 -0
  189. package/node_modules/@typescript/old/lib/lib.es2017.string.d.ts +43 -0
  190. package/node_modules/@typescript/old/lib/lib.es2017.typedarrays.d.ts +51 -0
  191. package/node_modules/@typescript/old/lib/lib.es2018.asyncgenerator.d.ts +75 -0
  192. package/node_modules/@typescript/old/lib/lib.es2018.asynciterable.d.ts +51 -0
  193. package/node_modules/@typescript/old/lib/lib.es2018.d.ts +22 -0
  194. package/node_modules/@typescript/old/lib/lib.es2018.full.d.ts +22 -0
  195. package/node_modules/@typescript/old/lib/lib.es2018.intl.d.ts +81 -0
  196. package/node_modules/@typescript/old/lib/lib.es2018.promise.d.ts +28 -0
  197. package/node_modules/@typescript/old/lib/lib.es2018.regexp.d.ts +35 -0
  198. package/node_modules/@typescript/old/lib/lib.es2019.array.d.ts +77 -0
  199. package/node_modules/@typescript/old/lib/lib.es2019.d.ts +22 -0
  200. package/node_modules/@typescript/old/lib/lib.es2019.full.d.ts +22 -0
  201. package/node_modules/@typescript/old/lib/lib.es2019.intl.d.ts +21 -0
  202. package/node_modules/@typescript/old/lib/lib.es2019.object.d.ts +31 -0
  203. package/node_modules/@typescript/old/lib/lib.es2019.string.d.ts +35 -0
  204. package/node_modules/@typescript/old/lib/lib.es2019.symbol.d.ts +22 -0
  205. package/node_modules/@typescript/old/lib/lib.es2020.bigint.d.ts +763 -0
  206. package/node_modules/@typescript/old/lib/lib.es2020.d.ts +25 -0
  207. package/node_modules/@typescript/old/lib/lib.es2020.date.d.ts +40 -0
  208. package/node_modules/@typescript/old/lib/lib.es2020.full.d.ts +22 -0
  209. package/node_modules/@typescript/old/lib/lib.es2020.intl.d.ts +472 -0
  210. package/node_modules/@typescript/old/lib/lib.es2020.number.d.ts +26 -0
  211. package/node_modules/@typescript/old/lib/lib.es2020.promise.d.ts +45 -0
  212. package/node_modules/@typescript/old/lib/lib.es2020.sharedmemory.d.ts +97 -0
  213. package/node_modules/@typescript/old/lib/lib.es2020.string.d.ts +42 -0
  214. package/node_modules/@typescript/old/lib/lib.es2020.symbol.wellknown.d.ts +39 -0
  215. package/node_modules/@typescript/old/lib/lib.es2021.d.ts +21 -0
  216. package/node_modules/@typescript/old/lib/lib.es2021.full.d.ts +22 -0
  217. package/node_modules/@typescript/old/lib/lib.es2021.intl.d.ts +164 -0
  218. package/node_modules/@typescript/old/lib/lib.es2021.promise.d.ts +46 -0
  219. package/node_modules/@typescript/old/lib/lib.es2021.string.d.ts +31 -0
  220. package/node_modules/@typescript/old/lib/lib.es2021.weakref.d.ts +76 -0
  221. package/node_modules/@typescript/old/lib/lib.es2022.array.d.ts +119 -0
  222. package/node_modules/@typescript/old/lib/lib.es2022.d.ts +23 -0
  223. package/node_modules/@typescript/old/lib/lib.es2022.error.d.ts +73 -0
  224. package/node_modules/@typescript/old/lib/lib.es2022.full.d.ts +22 -0
  225. package/node_modules/@typescript/old/lib/lib.es2022.intl.d.ts +143 -0
  226. package/node_modules/@typescript/old/lib/lib.es2022.object.d.ts +24 -0
  227. package/node_modules/@typescript/old/lib/lib.es2022.regexp.d.ts +37 -0
  228. package/node_modules/@typescript/old/lib/lib.es2022.string.d.ts +23 -0
  229. package/node_modules/@typescript/old/lib/lib.es2023.array.d.ts +922 -0
  230. package/node_modules/@typescript/old/lib/lib.es2023.collection.d.ts +19 -0
  231. package/node_modules/@typescript/old/lib/lib.es2023.d.ts +20 -0
  232. package/node_modules/@typescript/old/lib/lib.es2023.full.d.ts +22 -0
  233. package/node_modules/@typescript/old/lib/lib.es2023.intl.d.ts +62 -0
  234. package/node_modules/@typescript/old/lib/lib.es2024.arraybuffer.d.ts +63 -0
  235. package/node_modules/@typescript/old/lib/lib.es2024.collection.d.ts +27 -0
  236. package/node_modules/@typescript/old/lib/lib.es2024.d.ts +24 -0
  237. package/node_modules/@typescript/old/lib/lib.es2024.full.d.ts +22 -0
  238. package/node_modules/@typescript/old/lib/lib.es2024.object.d.ts +27 -0
  239. package/node_modules/@typescript/old/lib/lib.es2024.promise.d.ts +33 -0
  240. package/node_modules/@typescript/old/lib/lib.es2024.regexp.d.ts +23 -0
  241. package/node_modules/@typescript/old/lib/lib.es2024.sharedmemory.d.ts +66 -0
  242. package/node_modules/@typescript/old/lib/lib.es2024.string.d.ts +27 -0
  243. package/node_modules/@typescript/old/lib/lib.es2025.collection.d.ts +94 -0
  244. package/node_modules/@typescript/old/lib/lib.es2025.d.ts +23 -0
  245. package/node_modules/@typescript/old/lib/lib.es2025.float16.d.ts +443 -0
  246. package/node_modules/@typescript/old/lib/lib.es2025.full.d.ts +22 -0
  247. package/node_modules/@typescript/old/lib/lib.es2025.intl.d.ts +200 -0
  248. package/node_modules/@typescript/old/lib/lib.es2025.iterator.d.ts +146 -0
  249. package/node_modules/@typescript/old/lib/lib.es2025.promise.d.ts +32 -0
  250. package/node_modules/@typescript/old/lib/lib.es2025.regexp.d.ts +30 -0
  251. package/node_modules/@typescript/old/lib/lib.es5.d.ts +4599 -0
  252. package/node_modules/@typescript/old/lib/lib.es6.d.ts +21 -0
  253. package/node_modules/@typescript/old/lib/lib.esnext.array.d.ts +33 -0
  254. package/node_modules/@typescript/old/lib/lib.esnext.collection.d.ts +47 -0
  255. package/node_modules/@typescript/old/lib/lib.esnext.d.ts +27 -0
  256. package/node_modules/@typescript/old/lib/lib.esnext.date.d.ts +21 -0
  257. package/node_modules/@typescript/old/lib/lib.esnext.decorators.d.ts +26 -0
  258. package/node_modules/@typescript/old/lib/lib.esnext.disposable.d.ts +191 -0
  259. package/node_modules/@typescript/old/lib/lib.esnext.error.d.ts +22 -0
  260. package/node_modules/@typescript/old/lib/lib.esnext.full.d.ts +22 -0
  261. package/node_modules/@typescript/old/lib/lib.esnext.intl.d.ts +107 -0
  262. package/node_modules/@typescript/old/lib/lib.esnext.sharedmemory.d.ts +23 -0
  263. package/node_modules/@typescript/old/lib/lib.esnext.temporal.d.ts +485 -0
  264. package/node_modules/@typescript/old/lib/lib.esnext.typedarrays.d.ts +90 -0
  265. package/node_modules/@typescript/old/lib/lib.scripthost.d.ts +320 -0
  266. package/node_modules/@typescript/old/lib/lib.webworker.asynciterable.d.ts +18 -0
  267. package/node_modules/@typescript/old/lib/lib.webworker.d.ts +15606 -0
  268. package/node_modules/@typescript/old/lib/lib.webworker.importscripts.d.ts +21 -0
  269. package/node_modules/@typescript/old/lib/lib.webworker.iterable.d.ts +18 -0
  270. package/node_modules/@typescript/old/lib/pl/diagnosticMessages.generated.json +2129 -0
  271. package/node_modules/@typescript/old/lib/pt-br/diagnosticMessages.generated.json +2129 -0
  272. package/node_modules/@typescript/old/lib/ru/diagnosticMessages.generated.json +2125 -0
  273. package/node_modules/@typescript/old/lib/tr/diagnosticMessages.generated.json +2129 -0
  274. package/node_modules/@typescript/old/lib/tsc.js +8 -0
  275. package/node_modules/@typescript/old/lib/tsserver.js +8 -0
  276. package/node_modules/@typescript/old/lib/tsserverlibrary.d.ts +17 -0
  277. package/node_modules/@typescript/old/lib/tsserverlibrary.js +21 -0
  278. package/node_modules/@typescript/old/lib/typesMap.json +497 -0
  279. package/node_modules/@typescript/old/lib/typescript.d.ts +11448 -0
  280. package/node_modules/@typescript/old/lib/typescript.js +201039 -0
  281. package/node_modules/@typescript/old/lib/typingsInstaller.js +8 -0
  282. package/node_modules/@typescript/old/lib/watchGuard.js +53 -0
  283. package/node_modules/@typescript/old/lib/zh-cn/diagnosticMessages.generated.json +2129 -0
  284. package/node_modules/@typescript/old/lib/zh-tw/diagnosticMessages.generated.json +2125 -0
  285. package/node_modules/@typescript/old/package.json +118 -0
  286. package/node_modules/@typescript/typescript6/LICENSE.txt +55 -0
  287. package/node_modules/@typescript/typescript6/README.md +9 -0
  288. package/node_modules/@typescript/typescript6/bin/tsc6 +2 -0
  289. package/node_modules/@typescript/typescript6/lib/tsc.js +1 -0
  290. package/node_modules/@typescript/typescript6/lib/tsserverlibrary.d.ts +2 -0
  291. package/node_modules/@typescript/typescript6/lib/tsserverlibrary.js +1 -0
  292. package/node_modules/@typescript/typescript6/lib/typescript.d.ts +2 -0
  293. package/node_modules/@typescript/typescript6/lib/typescript.js +1 -0
  294. package/node_modules/@typescript/typescript6/package.json +39 -0
  295. package/package.json +74 -22
  296. package/schemas/env-cap-report.schema.json +1 -1
  297. package/skills/env-cap/SKILL.md +91 -0
  298. package/skills/env-cap/references/api.md +220 -0
  299. package/specs/architecture.md +634 -0
  300. package/specs/decisions/0001-runtime-documentation-separation.md +197 -0
  301. package/specs/decisions/0002-static-analysis-never-execution.md +233 -0
  302. package/specs/decisions/0003-no-global-env-object.md +172 -0
  303. package/specs/decisions/0004-no-client-server-package-split.md +116 -0
  304. package/specs/decisions/0005-warn-not-throw-by-default.md +93 -0
  305. package/specs/decisions/0006-self-redacting-contracts.md +124 -0
  306. package/specs/decisions/0007-processor-not-transformer.md +109 -0
  307. package/specs/decisions/0008-gzip-size-budget.md +173 -0
  308. package/specs/decisions/0009-exclusive-groups-are-always-errors.md +139 -0
  309. package/specs/decisions/0010-dependency-ownership-engine-scope-boundary.md +100 -0
  310. package/specs/decisions/0011-shared-discovery-compute-atomic-write-non-atomic.md +104 -0
  311. package/specs/decisions/0012-live-expiration-overrides-not-ast-functions.md +145 -0
  312. package/specs/decisions/0013-json-output-is-a-versioned-mirror.md +136 -0
  313. package/specs/decisions/0014-cross-package-schema-discovery.md +206 -0
  314. package/specs/decisions/0015-security-backport-window.md +60 -0
  315. package/specs/decisions/0016-check-mode-compute-before-compare-never-partial-write.md +113 -0
  316. package/specs/decisions/0017-eslint-plugin-entry-point.md +113 -0
  317. package/specs/decisions/0018-rotation-alert-issue-on-non-pr-runs.md +104 -0
  318. package/specs/decisions/0019-published-json-schema-generated-from-types.md +100 -0
  319. package/specs/decisions/0020-declaration-maps-via-separate-tsc-pass.md +101 -0
  320. package/specs/decisions/0021-manifest-change-report-persisted-snapshot.md +177 -0
  321. package/specs/decisions/0022-validation-contexts.md +267 -0
  322. package/specs/decisions/0023-tsconfig-path-alias-resolution.md +182 -0
  323. package/specs/decisions/0024-fact-model-architecture.md +144 -0
  324. package/specs/decisions/0025-contract-model-json-projection.md +105 -0
  325. package/specs/decisions/0026-finding-model-unifies-four-families.md +109 -0
  326. package/specs/decisions/0027-dependency-model-fact-shape-not-engine-access.md +98 -0
  327. package/specs/decisions/0028-ownership-model-shared-effective-owner.md +85 -0
  328. package/specs/decisions/0029-lifecycle-model-deprecation-rename-fields.md +98 -0
  329. package/specs/decisions/0030-change-model-wraps-manifest-change-report.md +97 -0
  330. package/specs/decisions/0031-evidence-entry-point.md +85 -0
  331. package/specs/decisions/0032-evidence-projection-provenance-mechanism.md +120 -0
  332. package/specs/decisions/0033-reference-projections-live-in-examples.md +81 -0
  333. package/specs/decisions/0034-three-tier-examples-restructuring.md +85 -0
  334. package/specs/decisions/0035-documentenv-metadata-generalization-and-compliance-fields.md +85 -0
  335. package/specs/decisions/0036-exact-source-position-evidence.md +122 -0
  336. package/specs/decisions/0037-developer-declared-dynamic-access-citations.md +114 -0
  337. package/specs/decisions/0038-always-computed-evidence-model-backs-generate-check-docs.md +244 -0
  338. package/specs/decisions/0039-scanner-local-dataflow-boundary.md +160 -0
  339. package/specs/decisions/0040-library-surfaces-do-not-acquire-node-fs.md +156 -0
  340. package/specs/decisions/0041-dual-package-hazard-checked-documented.md +75 -0
  341. package/specs/decisions/0042-init-cli-subcommand-scaffolds-only.md +95 -0
  342. package/specs/decisions/0043-env-cap-resolver-relocated-and-duplicated.md +71 -0
  343. package/specs/decisions/0044-strict-escalates-every-warning-family.md +88 -0
  344. package/specs/decisions/0045-promote-experimental-surfaces-to-stable.md +103 -0
  345. package/specs/decisions/0046-cli-restricted-to-runtime-and-evidence-output.md +177 -0
  346. package/specs/decisions/0047-supported-toolchain-node-22-and-typescript-5-6.md +30 -0
  347. package/specs/decisions/0048-eslint-plugin-does-not-vendor-typescript-eslint.md +25 -0
  348. package/specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md +87 -0
  349. package/specs/decisions/0050-a-variable-declared-twice-is-documented-once.md +55 -0
  350. package/specs/generated-artifacts.md +104 -0
  351. package/specs/migrations/README.md +30 -0
  352. package/specs/migrations/from-centralized-schema.md +503 -0
  353. package/specs/migrations/from-dotenv.md +352 -0
  354. package/specs/migrations/from-envalid.md +482 -0
  355. package/specs/migrations/from-process-env.md +398 -0
  356. package/specs/migrations/from-t3-env.md +416 -0
  357. package/specs/migrations/from-zod.md +303 -0
  358. package/dist/build-U326PI5A.js.map +0 -1
  359. package/dist/chunk-BSTLSR2R.js.map +0 -1
package/PROMPT.md ADDED
@@ -0,0 +1,89 @@
1
+ ## AI-Assisted Integration
2
+
3
+ env-cap is designed to integrate with existing application architectures rather than replace them blindly.
4
+
5
+ If you use an AI coding assistant, provide it with the following prompt before asking it to modify your project. This helps the assistant understand both your application's architecture and env-cap's design principles before making changes.
6
+
7
+ Replace `<YOUR_PROJECT_CONTEXT>` with any additional context about your application before submitting the prompt.
8
+
9
+ ```text
10
+ You are integrating env-cap into an existing production codebase.
11
+
12
+ Package source:
13
+ https://github.com/maverickcer/env-cap
14
+
15
+ Before making any changes, first study the env-cap repository above, including:
16
+
17
+ - README.md
18
+ - Architecture documentation
19
+ - ADRs (architectural decision records)
20
+ - Examples
21
+ - Migration guides
22
+ - Package exports and API design
23
+
24
+ Understand the package's intended architecture and constraints before proposing an implementation.
25
+
26
+ Your role is to act as a senior/staff-level engineer performing an infrastructure integration review.
27
+
28
+ Application context:
29
+ <YOUR_PROJECT_CONTEXT>
30
+
31
+ First, analyze this repository and understand:
32
+
33
+ 1. Application architecture:
34
+ - Framework and runtime(s)
35
+ - Build system and bundler behavior
36
+ - Monorepo/package boundaries (if applicable)
37
+ - Server/client boundaries
38
+ - Deployment environments
39
+ - CI/CD environment configuration
40
+ - Existing environment loading and validation flow
41
+
42
+ 2. Current configuration system:
43
+ - Where environment variables are defined
44
+ - Where they are consumed
45
+ - Existing validation logic
46
+ - Existing documentation or generated configuration artifacts
47
+ - Security-sensitive variables
48
+ - Client-exposed variables
49
+
50
+ 3. Integration approach:
51
+ - Determine where env-cap contracts should live
52
+ - Identify existing environment boundaries
53
+ - Determine whether validation contexts are appropriate
54
+ - Determine whether separate manifests/contracts are needed
55
+ - Identify migration risks
56
+
57
+ Follow env-cap's architectural principles:
58
+
59
+ - Runtime validation and build-time analysis are separate concerns.
60
+ - Generated artifacts are derived outputs, not manually maintained files.
61
+ - Server-only secrets must remain outside client bundles.
62
+ - Validation contexts control validation participation only; they are not a security boundary.
63
+ - Application code determines active validation contexts explicitly.
64
+ - Do not add framework-specific behavior to env-cap usage.
65
+ - Avoid unnecessary wrappers or abstractions unless they solve a real application need.
66
+
67
+ Before changing code, provide:
68
+
69
+ 1. Current environment configuration architecture summary.
70
+ 2. Recommended env-cap integration strategy.
71
+ 3. Proposed migration steps.
72
+ 4. Files that should change.
73
+ 5. Risks and mitigations.
74
+ 6. Questions requiring developer decisions.
75
+
76
+ Do not implement changes until the plan has been reviewed and approved.
77
+
78
+ After approval:
79
+
80
+ - Implement changes incrementally.
81
+ - Preserve existing behavior where possible.
82
+ - Add or update tests.
83
+ - Verify generated documentation/artifacts.
84
+ - Verify type safety.
85
+ - Verify build output.
86
+ - Verify CI/CD compatibility.
87
+
88
+ For the best results, provide your AI assistant access to both your repository and the env-cap repository. The assistant should understand your application's architecture before recommending how env-cap fits into it.
89
+ ```
package/README.md CHANGED
@@ -2,20 +2,50 @@
2
2
 
3
3
  [![CI](https://img.shields.io/github/actions/workflow/status/maverickcer/env-cap/ci.yml?branch=main&label=CI)](https://github.com/maverickcer/env-cap/actions/workflows/ci.yml)
4
4
  [![npm version](https://img.shields.io/npm/v/%40maverickcer%2Fenv-cap)](https://www.npmjs.com/package/@maverickcer/env-cap)
5
+ [![Coverage: the lowest of line, statement, function and branch coverage](https://img.shields.io/endpoint?url=https://maverickcer.github.io/env-cap/coverage-badge.json)](https://maverickcer.github.io/env-cap/coverage.json)
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
+ [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/MaverickCER/env-cap/badge)](https://scorecard.dev/viewer/?uri=github.com/MaverickCER/env-cap)
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)
5
9
  [![Socket Badge](https://badge.socket.dev/npm/package/@maverickcer/env-cap/latest)](https://socket.dev/npm/package/@maverickcer/env-cap)
6
- [![Coverage](https://img.shields.io/endpoint?url=https://maverickcer.github.io/env-cap/coverage-badge.json)](vitest.config.ts)
7
- [![Bundle size](https://img.shields.io/endpoint?url=https://maverickcer.github.io/env-cap/size-badge.json)](specs/decisions/0008-gzip-size-budget.md)
8
- [![TypeScript](https://img.shields.io/badge/TypeScript-ready-3178c6)](#quick-start)
10
+ [![Node](https://img.shields.io/node/v/%40maverickcer%2Fenv-cap)](https://www.npmjs.com/package/@maverickcer/env-cap)
11
+ [![License](https://img.shields.io/npm/l/%40maverickcer%2Fenv-cap)](LICENSE)
9
12
 
10
13
  **Define who owns your environment variables, why they exist, and where they are used.**
11
14
 
12
- `env-cap` turns environment configuration into capability-owned contracts you can version, review, validate, document, and query.
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.
13
16
 
14
- It does not replace your existing configuration tools. `dotenv`, Zod, envalid, t3-env, secret managers, and plain `process.env` can stay exactly where they are. `env-cap` adds the layer they do not provide: **ownership, lifecycle, and project-wide evidence about whether declared configuration is actually consumed.**
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)
15
18
 
16
- [See it run](#see-it-run) · [Quick Start](#quick-start) · [Why env-cap](#why-not-just-use-existing-tools)
19
+ ## Why it exists
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.
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.
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.
28
+
29
+ ## How it differs
30
+
31
+ | Tool | What it solves | What remains unanswered |
32
+ | ---------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------- |
33
+ | `dotenv` | Loads values from a `.env` file | Who owns the value, why it exists, whether it is still used, when it expires |
34
+ | Zod / envalid / t3-env | Validates value shape and types | Whether the variable is still needed, who owns it, or what capability depends on it |
35
+ | Secret manager | Stores and manages secrets | Which capability in the codebase actually consumes the secret |
36
+ | `env-cap` | Defines ownership, lifecycle, and consumption contracts | Does not replace loading, secret storage, or application-specific validation |
37
+
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.
17
39
 
18
- ## See it run
40
+ ## What it does
41
+
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.
43
+
44
+ ```text
45
+ declare → generate → validate → consume
46
+ ```
47
+
48
+ ### See it run
19
49
 
20
50
  **Every environment variable has an owner, a reason to exist, and a lifecycle you can query.**
21
51
 
@@ -47,11 +77,13 @@ documentEnv(paymentsSchema, {
47
77
  })
48
78
  ```
49
79
 
50
- Run the build-time analysis against a real project. The manifest and the
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
51
83
  persisted evidence artifact -- the two outputs a real project actually reads
52
84
  at runtime/in CI (see [ADR 0046](specs/decisions/0046-cli-restricted-to-runtime-and-evidence-output.md))
53
85
  -- come from the CLI itself; the human-facing docs/ownership report come
54
- from a small script calling `env-cap/build` directly (see
86
+ from a small script calling `@maverickcer/env-cap/build` directly (see
55
87
  `examples/application/scripts/generate-docs`):
56
88
 
57
89
  ```text
@@ -64,236 +96,102 @@ $ npx tsx scripts/generate-docs/run.ts
64
96
  [generate-docs] wrote docs/ENVIRONMENT.md (1 contract(s)), .env.example, and docs/OWNERSHIP.md (0 abandoned, 2 unconsumed owned variable(s)).
65
97
 
66
98
  1 variable(s)/contract(s) expiring soon or already expired:
67
- - STRIPE_KEY in env: 2026-09-01 (expired 27d ago)
99
+ - STRIPE_KEY in env: 2026-09-01 (expired Nd ago)
68
100
 
69
101
  2 unconsumed owned variable(s):
70
102
  - DATABASE_URL in app
71
103
  - STRIPE_KEY in app
72
104
  ```
73
105
 
74
- This is real output from [`examples/application`](examples/application)'s own `npm run docs` and `npm run docs:reports` scripts, not a mockup.
75
-
76
- The important part is what the analysis can establish:
77
-
78
- - `STRIPE_KEY` has an ownership and expiration record.
79
- - Its declared expiration has passed.
80
- - `DATABASE_URL` and `STRIPE_KEY` are declared as owned but are not consumed by the analyzed application.
81
-
82
- Those are facts about the application's configuration and dependencies, not merely the result of a value validator.
83
-
84
- ## Why it exists
85
-
86
- A configuration value can be perfectly valid and still be a problem.
87
-
88
- A secret manager can store a credential securely. A validator can confirm that it has the expected shape. Neither answers:
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.
89
107
 
90
- - Why does this variable exist?
91
- - Which capability actually depends on it?
92
- - Who owns it?
93
- - When should it be reviewed, rotated, or retired?
94
- - Is anything still consuming it?
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.
95
109
 
96
- As applications grow, those answers tend to move into documentation, team knowledge, Slack messages, tickets, and conventions.
110
+ ### Evidence it works
97
111
 
98
- That creates a different class of configuration failure:
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)).
99
117
 
100
- **the application can accept a variable that nobody owns, nobody uses, or nobody remembers to retire.**
118
+ ## Install and verify
101
119
 
102
- `env-cap` makes those decisions part of the code.
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.
103
121
 
104
- A capability declares the environment it owns. A build-time pass turns those declarations into a project-wide manifest, documentation, ownership information, and evidence about what the codebase actually consumes.
105
-
106
- The distinction is simple:
107
-
108
- > **Validators answer whether a value is valid.
109
- > env-cap answers why the value exists, who owns it, and whether the application still uses it.**
110
-
111
- ## Quick Start
112
-
113
- **Start with one capability.**
114
-
115
- ```bash
122
+ ```sh
116
123
  npm install @maverickcer/env-cap
117
- npx env-cap init
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
+ node scripts/generate-env.mjs
118
127
  ```
119
128
 
120
- `init` scaffolds the same setup shown below: an `env.schema.ts` contract and a `scripts/generate-env.mjs` generator. It never overwrites existing files and never modifies `package.json`. See [VERSIONING.md](VERSIONING.md).
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.
121
130
 
122
- If you prefer to create the contract yourself, the minimum setup is:
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:
123
132
 
124
133
  ```ts
125
- // features/payments/env.schema.ts
126
-
127
- import { createEnv } from "@maverickcer/env-cap"
128
-
129
- export const paymentsEnv = createEnv(
130
- {
131
- STRIPE_KEY: {
132
- validator: (value: string) =>
133
- value.startsWith("sk_") || 'Expected a key starting with "sk_".',
134
- },
135
- },
136
- { name: "payments" },
137
- )
138
- ```
139
-
140
- Then validate the generated project manifest before using the capability:
141
-
142
- ```ts
143
- // app.ts
144
-
145
134
  import { validateEnv } from "@maverickcer/env-cap"
146
-
147
135
  import { manifest } from "./generated/env.manifest"
148
136
  import { paymentsEnv } from "./features/payments/env.schema"
149
137
 
150
- await validateEnv({
151
- manifest,
152
- values: process.env,
153
- })
154
-
138
+ await validateEnv({ manifest, values: process.env })
155
139
  paymentsEnv.STRIPE_KEY
156
140
  ```
157
141
 
158
- The normal flow is:
159
-
160
- ```text
161
- declare → generate → validate → consume
162
- ```
163
-
164
- `generateEnvManifest()` produces the project-wide manifest. Runtime validation uses that manifest against the environment values supplied by the application.
165
-
166
- See the [Guide's Core workflow](GUIDE.md#core-workflow) for the complete generate/validate cycle.
167
-
168
- Node.js `>=20`. TypeScript 5+ is only required for build-time manifest generation; the runtime works in plain JavaScript. See the [runtime support matrix](GUIDE.md#runtime-support-matrix) for Node, browser bundles, edge runtimes, Bun, and Deno.
169
-
170
- ## What declared metadata can express
171
-
172
- **Ownership and lifecycle data isn't documentation bolted onto validation — it's what the build-time analysis actually queries:**
173
-
174
- ```ts
175
- documentEnv(paymentsSchema, {
176
- owner: "payments-team",
177
- variables: {
178
- STRIPE_KEY: {
179
- description: "Stripe secret key used to create charges and process refunds.",
180
- owner: "payments-team",
181
- expiresAt: "2027-01-01",
182
- sensitivity: "secret",
183
- },
184
- },
185
- })
186
- ```
187
-
188
- That `expiresAt` is what powers the "expiring soon or already expired" line in [See it run](#see-it-run) above — not a separate expiration-tracking system, the same declaration the validator already needs. The same build pass cross-references every declared variable against actual usage in your source, which is what produces the "unconsumed owned variable(s)" warning: a variable can be perfectly valid and still be a problem nobody's watching. The [Guide](GUIDE.md#capability-owned-contracts) has the full model — capability-scoped ownership, rotation cadence, storage provider, access policy.
189
-
190
- ## Why not just use existing tools?
191
-
192
- `env-cap` is deliberately additive.
193
-
194
- | Tool | What it solves | What remains unanswered |
195
- | ---------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------- |
196
- | `dotenv` | Loads values from a `.env` file | Who owns the value, why it exists, whether it is still used, when it expires |
197
- | Zod / envalid / t3-env | Validates value shape and types | Whether the variable is still needed, who owns it, or what capability depends on it |
198
- | Secret manager | Stores and manages secrets | Which capability in the codebase actually consumes the secret |
199
- | `env-cap` | Defines ownership, lifecycle, and consumption contracts | Does not replace loading, secret storage, or application-specific validation |
200
-
201
- **You keep your existing tools.**
202
-
203
- Use `env-cap` with your existing validator or processor, or use its lightweight helpers when a dedicated validation library is unnecessary. What env-cap adds is the layer around the value: ownership, lifecycle, and project-wide evidence about whether declared configuration is actually consumed.
204
-
205
- You do not have to migrate away from an existing configuration library to adopt env-cap. The [migration guides](specs/migrations/) document the adoption path for `dotenv`, Zod, envalid, and t3-env, including cases where switching is unnecessary.
206
-
207
- ## From one schema to a whole organization
208
-
209
- ```text
210
- one schema, one team
211
- | ownership boundaries start to matter
212
- capability-owned schemas, one per feature
213
- | share it
214
- reusable package contracts
215
- | scale it
216
- organization-wide configuration ownership
217
- ```
218
-
219
- A capability contract records what a variable is for, who owns it, how sensitive it is, when it expires, and whether the codebase still consumes it. Start with a single centralized schema and move toward capability- or package-owned contracts only as ownership boundaries start to matter — `generateEnvManifest()` produces one project-wide manifest regardless of how many contracts contribute to it, so validation, documentation, and ownership reporting never depend on how the schema is organized.
220
-
221
- The [`examples/`](examples/) directory has three runnable stages of that model — [`examples/application`](examples/application), [`examples/team-service`](examples/team-service), and [`examples/enterprise-platform`](examples/enterprise-platform) — and the [Guide](GUIDE.md#capability-owned-contracts) covers the full walkthrough.
222
-
223
- ## You probably don't need it when
224
-
225
- A validation library or `dotenv` may be enough when:
226
-
227
- - the application is small;
228
- - one team owns every configuration decision;
229
- - there are only a few environment variables;
230
- - variables rarely change;
231
- - ownership and lifecycle are already obvious;
232
- - you do not need project-wide evidence about configuration usage.
233
-
234
- `env-cap` becomes more useful when configuration starts crossing capability, team, package, or organizational boundaries.
235
-
236
- ## Works with automated contributors
237
-
238
- AI coding agents, CI bots, and release automation can consume the same manifests and evidence artifacts as human contributors.
239
-
240
- A structured finding such as:
241
-
242
- ```text
243
- payments owns STRIPE_KEY
244
- STRIPE_KEY is declared but unconsumed
245
- ```
246
-
247
- gives automation a concrete fact to investigate.
248
-
249
- That is more useful than a generic failure such as:
250
-
251
- ```text
252
- configuration check failed
253
- ```
254
-
255
- The repository can therefore use the same configuration contract to guide both human and automated changes.
256
-
257
- See the [AI Integration Prompt](./PROMPT.md) for a repository-aware review workflow.
258
-
259
- ## Status
260
-
261
- `env-cap` is currently in `0.x`.
262
-
263
- Per [VERSIONING.md](VERSIONING.md), a minor release may include a breaking change to a Stable-tier API before 1.0. Pin according to your upgrade policy.
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).
264
143
 
265
- The architecture is considered stable; APIs may continue to evolve based on production usage.
144
+ ## Fit and capabilities
266
145
 
267
- ## Learn more
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".
268
147
 
269
- - **[Guide](GUIDE.md)** — capability-owned contracts, the complete generate/validate workflow, validation contexts, reusable packages, path aliases, CLI, GitHub Action, ESLint plugin, and performance characteristics.
148
+ **Core capabilities:**
270
149
 
271
- - **[Security](SECURITY.md)** — threat model, secret-handling boundaries, and application responsibilities.
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.
272
154
 
273
- - **[Adoption guide](ADOPTION.md)** — decision-maker summary covering security posture, bundle size, and versioning/LTS considerations.
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)).
274
156
 
275
- - **[Migration guides](specs/migrations/)** — adoption alongside `dotenv`, Zod, envalid, or t3-env.
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)).
276
158
 
277
- - **[API reference](https://maverickcer.github.io/env-cap/api/)** — every exported symbol, generated from source.
159
+ ## Limits and when not to use it
278
160
 
279
- - **[Architecture](specs/architecture.md)** and **[ADRs](specs/decisions/)** — why env-cap is designed this way.
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).
280
165
 
281
- - **[Examples](examples/)** — runnable application, team-service, and enterprise-platform examples.
166
+ ## Security and supply chain
282
167
 
283
- ## If this is useful
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).
284
172
 
285
- If capability-owned configuration matches how you think about environment variables, try env-cap against one real schema.
173
+ ## Maturity, versioning and support
286
174
 
287
- If it does not fit your application's configuration model, [open an issue](https://github.com/MaverickCER/env-cap/issues) and explain why.
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)).
288
176
 
289
- ## Contributing
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).
179
+ - **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).
290
181
 
291
- Start with [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, the change workflow, ADRs, and changeset-based versioning.
182
+ ## Documentation
292
183
 
293
- [CODE_REVIEW.md](CODE_REVIEW.md) covers the reviewer-side process.
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)).
294
190
 
295
- Maintainers can see [RELEASING.md](RELEASING.md) for the release process.
191
+ ## Next steps
296
192
 
297
- ## License
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).
298
196
 
299
- MIT
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).
package/RELEASING.md ADDED
@@ -0,0 +1,160 @@
1
+ <!-- Managed by internal-package-contract. Do not edit this file: change template/package/RELEASING.md in the standard and run `internal-package-contract sync`. -->
2
+
3
+ # Releasing @maverickcer/env-cap
4
+
5
+ Maintainer-facing. Contributors don't run any of this: a normal change is just a pull request, and its
6
+ changeset is generated if it has none (see [`CONTRIBUTING.md`](CONTRIBUTING.md#making-a-change)).
7
+ For what semver actually covers, see [`VERSIONING.md`](VERSIONING.md).
8
+
9
+ ## How releases work
10
+
11
+ Releases are driven by [Changesets](https://github.com/changesets/changesets) and npm's
12
+ [OIDC trusted publishing](https://docs.npmjs.com/trusted-publishers), through
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; nothing
17
+ publishes without that.
18
+
19
+ The loop:
20
+
21
+ 1. A pull request that changes user-facing behavior carries a changeset in `.changeset/` (Markdown,
22
+ `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
25
+ deliberate `major` changeset.
26
+ 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, 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.
35
+ 4. After publishing, the workflow tags the release `v<major>.<minor>.<patch>` on the merged commit,
36
+ force-updates the floating major tag (`v0` while the package is 0.x, `v1` from 1.0.0), and asks npm what
37
+ it now serves: the version must be there and must carry the provenance attestation, or the run goes red.
38
+ The floating tag tracks the composite Action's interface (`action.yml` inputs and outputs), so
39
+ `uses: maverickcer/env-cap@v0` keeps pointing at the latest compatible build until `action.yml` itself
40
+ has a breaking change.
41
+
42
+ `CHANGELOG.md` is generated; never hand-edit it. Fix a wrong entry by correcting the offending changeset
43
+ before the version pull request is merged, or with a follow-up changeset after.
44
+
45
+ ## First-time setup
46
+
47
+ One-time, before the very first automated release. Requires npm account
48
+ access, so it can't be done from a PR.
49
+
50
+ 1. On [npmjs.com](https://www.npmjs.com), open `@maverickcer/env-cap`'s
51
+ package settings → **Publishing access** → add a **trusted publisher** for
52
+ GitHub Actions:
53
+ - Organization or user: `maverickcer`
54
+ - Repository: `env-cap`
55
+ - Workflow filename: `release.yml` (exactly — just the filename, not a
56
+ path; a mismatch here is the most common cause of the OIDC flow failing
57
+ with a misleading `E404`)
58
+ - Environment: leave blank unless `release.yml` is later scoped to a
59
+ GitHub Environment
60
+ 2. That's the whole trust relationship — `release.yml`'s `id-token: write`
61
+ permission plus this registration. There is no token to copy anywhere.
62
+
63
+ Until the package exists on npm, its settings page doesn't either. For the
64
+ **first ever publish**, register the trusted publisher immediately after the
65
+ first `npm publish` (a one-time manual `npm publish --access public` from a
66
+ maintainer machine, from a clean `npm run verify` tree), then let every
67
+ subsequent release go through `release.yml`. Alternatively, publish an empty
68
+ `0.0.0` placeholder manually first, register the trusted publisher, then let
69
+ the first real version pull request publish `0.1.0` over OIDC.
70
+
71
+ ## Recovering from a failed release
72
+
73
+ Identify which state you're in first — the recovery differs and the wrong
74
+ one can double-publish or lose a version.
75
+
76
+ ### A. The version pull request is open, nothing published yet
77
+
78
+ Safe state. The bump only exists on the `changeset-release/main` branch.
79
+ Fix forward: push more changesets to `main` (the PR auto-updates), or edit
80
+ the PR branch directly if the generated `CHANGELOG.md`/version is wrong.
81
+ Nothing is on npm; nothing to undo.
82
+
83
+ ### B. The version pull request is merged, but the release failed
84
+
85
+ `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).
88
+
89
+ 1. Confirm npm really doesn't have it: `npm view @maverickcer/env-cap versions --json`, and check the bumped version is
90
+ absent.
91
+ 2. Find the cause (see [Common failures](#common-failure-causes)).
92
+ 3. If it was transient or a configuration problem outside the repository (a registry blip, the
93
+ trusted-publisher registration), fix that and re-run the failed `release.yml` run from the Actions tab
94
+ ("Re-run failed jobs"). A re-run uses the same commit.
95
+ 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
96
+ pull request to `main`. What happens next depends on the commit type. A `fix`, `feat`, `perf` or `revert`
97
+ commit gets a changeset generated for it, so the workflow opens a new version pull request instead of
98
+ 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
+ workflow sees that the current `package.json` version isn't on npm and builds and publishes that version.
101
+ 5. Publishing by hand is the last resort, and it publishes without the provenance attestation that the
102
+ workflow adds. If you must, publish that exact version from a clean tree
103
+ (`git checkout main && npm ci && npm run verify && npm publish --access public`), then confirm the next push
104
+ to `main` produces no spurious version pull request.
105
+
106
+ ### C. Published to npm, but a later workflow step failed
107
+
108
+ 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
+
111
+ ```bash
112
+ git checkout main && git pull
113
+ git tag -f v0 && git push origin v0 --force # while the package is 0.x
114
+ git tag -f v1 && git push origin v1 --force # from 1.0.0
115
+ ```
116
+
117
+ Do **not** re-run the whole workflow — `changeset publish` is idempotent and
118
+ will no-op on the already-published version, but re-running risks masking
119
+ whatever the real trailing failure was.
120
+
121
+ ### D. Wrong version published
122
+
123
+ npm publishes are effectively permanent (`npm unpublish` is allowed only
124
+ within 72 hours and only if nothing depends on it, and the version number
125
+ can never be reused). Don't try to unpublish a normal mistake. Instead:
126
+
127
+ - Wrong contents, right version number: publish a patch (`x.y.z+1`) with a
128
+ changeset that fixes it, and `npm deprecate @maverickcer/env-cap@x.y.z
129
+ "Broken publish — use x.y.z+1"`.
130
+ - Accidental major/minor bump: it stays. Continue from the new baseline; a
131
+ version number is cheap, a rewritten history is not.
132
+
133
+ ### E. First release, package not yet on npm
134
+
135
+ See [First-time setup](#first-time-setup) — the trusted-publisher
136
+ registration cannot exist before the package does, so the first publish is
137
+ the one manual step. Every release after that is automated.
138
+
139
+ ## Common failure causes
140
+
141
+ - **`E404` on publish with OIDC**: the trusted-publisher registration's
142
+ workflow filename doesn't exactly match `release.yml`, or the
143
+ 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.
146
+ - **The final "Verify what npm now serves" step fails**: npm did not return the version or its provenance
147
+ attestation. Nothing is unpublished by the failure; look at the registry before doing anything else.
148
+ - **A version pull request appears when you didn't expect one**: there's a stray changeset file in `.changeset/` on `main`. If it's
149
+ spurious, delete it in a normal PR.
150
+ - **Two version pull requests**: an older one wasn't closed when `main` moved. Close the stale one; the
151
+ workflow only maintains the newest.
152
+
153
+ ## Related
154
+
155
+ - [`VERSIONING.md`](VERSIONING.md) — what each bump type means, and which
156
+ surface semver actually covers.
157
+ - [`CONTRIBUTING.md`](CONTRIBUTING.md) — the contributor-side workflow
158
+ (branch, changeset, PR).
159
+ - [`SECURITY.md`](SECURITY.md#supported-versions) — which versions get
160
+ security fixes.