@maverickcer/env-cap 0.7.4 → 0.7.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/ADOPTION.md +106 -124
- package/AGENTS.md +94 -128
- package/CHANGELOG.md +42 -0
- package/CODE_REVIEW.md +69 -173
- package/CONTRIBUTING.md +57 -74
- package/GUIDE.md +405 -866
- package/README.md +112 -89
- package/RELEASING.md +81 -65
- package/SECURITY.md +76 -227
- package/SUPPORT.md +21 -45
- package/VERSIONING.md +69 -105
- package/benchmarks/READING-BENCHMARKS.md +103 -81
- package/benchmarks/README.md +12 -9
- package/benchmarks/WRITING-BENCHMARKS.md +90 -80
- package/benchmarks/performance-buildtime/BENCHMARKS.md +20 -20
- package/benchmarks/performance-runtime/BENCHMARKS.md +107 -107
- package/dist/.dts/_ipc/build-fs.d.ts +12 -17
- package/dist/.dts/_ipc/build-fs.d.ts.map +1 -1
- package/dist/.dts/_ipc/compiler-api.d.ts +6 -6
- package/dist/.dts/_ipc/display-path.d.ts +1 -1
- package/dist/.dts/_ipc/display-path.d.ts.map +1 -1
- package/dist/.dts/_ipc/generated-banner.d.ts +8 -8
- package/dist/.dts/_ipc/glob.d.ts +9 -8
- package/dist/.dts/_ipc/glob.d.ts.map +1 -1
- package/dist/.dts/_ipc/no-node-fs.d.ts +2 -2
- package/dist/.dts/_ipc/no-node-fs.d.ts.map +1 -1
- package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts +16 -16
- package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts.map +1 -1
- package/dist/.dts/_ipc/typescript.d.ts +4 -4
- package/dist/.dts/build/assemble-project.d.ts +14 -15
- package/dist/.dts/build/assemble-project.d.ts.map +1 -1
- package/dist/.dts/build/change-model.d.ts +14 -14
- package/dist/.dts/build/change-model.d.ts.map +1 -1
- package/dist/.dts/build/check-artifacts.d.ts +4 -4
- package/dist/.dts/build/check-artifacts.d.ts.map +1 -1
- package/dist/.dts/build/citation-verification.d.ts +13 -14
- package/dist/.dts/build/citation-verification.d.ts.map +1 -1
- package/dist/.dts/build/compatibility.d.ts +24 -24
- package/dist/.dts/build/compatibility.d.ts.map +1 -1
- package/dist/.dts/build/contract-model.d.ts +10 -10
- package/dist/.dts/build/contract-model.d.ts.map +1 -1
- package/dist/.dts/build/deep-equal.d.ts +2 -2
- package/dist/.dts/build/deep-freeze.d.ts +2 -2
- package/dist/.dts/build/dependency-graph.d.ts +48 -55
- package/dist/.dts/build/dependency-graph.d.ts.map +1 -1
- package/dist/.dts/build/dependency-model.d.ts +18 -18
- package/dist/.dts/build/dependency-model.d.ts.map +1 -1
- package/dist/.dts/build/discover.d.ts +11 -11
- package/dist/.dts/build/discover.d.ts.map +1 -1
- package/dist/.dts/build/docs.d.ts +34 -38
- package/dist/.dts/build/docs.d.ts.map +1 -1
- package/dist/.dts/build/env-example.d.ts +13 -13
- package/dist/.dts/build/env-example.d.ts.map +1 -1
- package/dist/.dts/build/errors.d.ts +8 -8
- package/dist/.dts/build/evidence-cache.d.ts +23 -23
- package/dist/.dts/build/evidence-cache.d.ts.map +1 -1
- package/dist/.dts/build/evidence-model.d.ts +3 -3
- package/dist/.dts/build/evidence-reference.d.ts +15 -15
- package/dist/.dts/build/evidence-reference.d.ts.map +1 -1
- package/dist/.dts/build/evidence-snapshot.d.ts +47 -53
- package/dist/.dts/build/evidence-snapshot.d.ts.map +1 -1
- package/dist/.dts/build/exclusive-group.d.ts +4 -4
- package/dist/.dts/build/exclusive-group.d.ts.map +1 -1
- package/dist/.dts/build/finding-model.d.ts +12 -12
- package/dist/.dts/build/finding-model.d.ts.map +1 -1
- package/dist/.dts/build/generate-documentation.d.ts +19 -19
- package/dist/.dts/build/generate-documentation.d.ts.map +1 -1
- package/dist/.dts/build/generate-env-artifacts.d.ts +43 -43
- package/dist/.dts/build/generate-env-artifacts.d.ts.map +1 -1
- package/dist/.dts/build/generate-evidence.d.ts +19 -19
- package/dist/.dts/build/generate-evidence.d.ts.map +1 -1
- package/dist/.dts/build/generate-manifest.d.ts +11 -12
- package/dist/.dts/build/generate-manifest.d.ts.map +1 -1
- package/dist/.dts/build/generate-usage.d.ts +23 -24
- package/dist/.dts/build/generate-usage.d.ts.map +1 -1
- package/dist/.dts/build/generated-banner.d.ts +5 -5
- package/dist/.dts/build/governance-fields.d.ts +7 -7
- package/dist/.dts/build/humanize-key.d.ts +1 -1
- package/dist/.dts/build/humanize-key.d.ts.map +1 -1
- package/dist/.dts/build/index.d.ts +20 -36
- package/dist/.dts/build/index.d.ts.map +1 -1
- package/dist/.dts/build/lifecycle-model.d.ts +90 -83
- package/dist/.dts/build/lifecycle-model.d.ts.map +1 -1
- package/dist/.dts/build/link.d.ts +38 -39
- package/dist/.dts/build/link.d.ts.map +1 -1
- package/dist/.dts/build/literal-eval.d.ts +2 -2
- package/dist/.dts/build/literal-eval.d.ts.map +1 -1
- package/dist/.dts/build/live-expirations.d.ts +14 -13
- package/dist/.dts/build/live-expirations.d.ts.map +1 -1
- package/dist/.dts/build/manifest.d.ts +6 -6
- package/dist/.dts/build/map-utils.d.ts +4 -4
- package/dist/.dts/build/merge-documentation.d.ts +9 -8
- package/dist/.dts/build/merge-documentation.d.ts.map +1 -1
- package/dist/.dts/build/ownership-model.d.ts +14 -15
- package/dist/.dts/build/ownership-model.d.ts.map +1 -1
- package/dist/.dts/build/parse.d.ts +20 -21
- package/dist/.dts/build/parse.d.ts.map +1 -1
- package/dist/.dts/build/reference-projections.d.ts +36 -38
- package/dist/.dts/build/reference-projections.d.ts.map +1 -1
- package/dist/.dts/build/resolution/resolve-import.d.ts +18 -14
- package/dist/.dts/build/resolution/resolve-import.d.ts.map +1 -1
- package/dist/.dts/build/resolution/resolve-package-schema.d.ts +26 -26
- package/dist/.dts/build/resolution/resolve-package-schema.d.ts.map +1 -1
- package/dist/.dts/build/resolution/resolve-within-root.d.ts +9 -9
- package/dist/.dts/build/sarif.d.ts +5 -5
- package/dist/.dts/build/sarif.d.ts.map +1 -1
- package/dist/.dts/build/scan-dependencies.d.ts +17 -16
- package/dist/.dts/build/scan-dependencies.d.ts.map +1 -1
- package/dist/.dts/build/sort-by-identity.d.ts +1 -1
- package/dist/.dts/build/source-position.d.ts +13 -13
- package/dist/.dts/build/tool-version.d.ts +1 -1
- package/dist/.dts/build/usage-report.d.ts +19 -19
- package/dist/.dts/build/usage-report.d.ts.map +1 -1
- package/dist/.dts/eslint-plugin/index.d.ts +16 -5
- package/dist/.dts/eslint-plugin/index.d.ts.map +1 -1
- package/dist/.dts/eslint-plugin/no-raw-process-env.d.ts +4 -4
- package/dist/.dts/evidence/define-projection.d.ts +15 -16
- package/dist/.dts/evidence/define-projection.d.ts.map +1 -1
- package/dist/.dts/evidence/index.d.ts +11 -15
- package/dist/.dts/evidence/index.d.ts.map +1 -1
- package/dist/.dts/helpers/index.d.ts +15 -18
- package/dist/.dts/helpers/index.d.ts.map +1 -1
- package/dist/.dts/helpers/validators.d.ts +2 -2
- package/dist/.dts/helpers/validators.d.ts.map +1 -1
- package/dist/.dts/node/index.d.ts +19 -0
- package/dist/.dts/node/index.d.ts.map +1 -1
- package/dist/.dts/runtime/create.d.ts +6 -3
- package/dist/.dts/runtime/create.d.ts.map +1 -1
- package/dist/.dts/runtime/document.d.ts +91 -97
- package/dist/.dts/runtime/document.d.ts.map +1 -1
- package/dist/.dts/runtime/errors.d.ts +5 -5
- package/dist/.dts/runtime/index.d.ts +11 -10
- package/dist/.dts/runtime/index.d.ts.map +1 -1
- package/dist/.dts/runtime/reset.d.ts +1 -1
- package/dist/.dts/runtime/types.d.ts +39 -24
- package/dist/.dts/runtime/types.d.ts.map +1 -1
- package/dist/.dts/runtime/validate.d.ts +15 -2
- package/dist/.dts/runtime/validate.d.ts.map +1 -1
- package/dist/.dts7/_ipc/build-fs.d.ts +48 -0
- package/dist/.dts7/_ipc/build-fs.d.ts.map +1 -0
- package/dist/.dts7/_ipc/compiler-api.d.ts +17 -0
- package/dist/.dts7/_ipc/compiler-api.d.ts.map +1 -0
- package/dist/.dts7/_ipc/display-path.d.ts +27 -0
- package/dist/.dts7/_ipc/display-path.d.ts.map +1 -0
- package/dist/.dts7/_ipc/generated-banner.d.ts +58 -0
- package/dist/.dts7/_ipc/generated-banner.d.ts.map +1 -0
- package/dist/.dts7/_ipc/glob.d.ts +23 -0
- package/dist/.dts7/_ipc/glob.d.ts.map +1 -0
- package/dist/.dts7/_ipc/no-node-fs.d.ts +21 -0
- package/dist/.dts7/_ipc/no-node-fs.d.ts.map +1 -0
- package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts +134 -0
- package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts.map +1 -0
- package/dist/.dts7/_ipc/typescript.d.ts +20 -0
- package/dist/.dts7/_ipc/typescript.d.ts.map +1 -0
- package/dist/.dts7/build/assemble-project.d.ts +46 -0
- package/dist/.dts7/build/assemble-project.d.ts.map +1 -0
- package/dist/.dts7/build/change-model.d.ts +63 -0
- package/dist/.dts7/build/change-model.d.ts.map +1 -0
- package/dist/.dts7/build/check-artifacts.d.ts +48 -0
- package/dist/.dts7/build/check-artifacts.d.ts.map +1 -0
- package/dist/.dts7/build/citation-verification.d.ts +61 -0
- package/dist/.dts7/build/citation-verification.d.ts.map +1 -0
- package/dist/.dts7/build/compatibility.d.ts +83 -0
- package/dist/.dts7/build/compatibility.d.ts.map +1 -0
- package/dist/.dts7/build/compiler-api.d.ts +12 -0
- package/dist/.dts7/build/compiler-api.d.ts.map +1 -0
- package/dist/.dts7/build/contract-model.d.ts +93 -0
- package/dist/.dts7/build/contract-model.d.ts.map +1 -0
- package/dist/.dts7/build/deep-equal.d.ts +9 -0
- package/dist/.dts7/build/deep-equal.d.ts.map +1 -0
- package/dist/.dts7/build/deep-freeze.d.ts +20 -0
- package/dist/.dts7/build/deep-freeze.d.ts.map +1 -0
- package/dist/.dts7/build/dependency-graph.d.ts +163 -0
- package/dist/.dts7/build/dependency-graph.d.ts.map +1 -0
- package/dist/.dts7/build/dependency-model.d.ts +81 -0
- package/dist/.dts7/build/dependency-model.d.ts.map +1 -0
- package/dist/.dts7/build/discover.d.ts +41 -0
- package/dist/.dts7/build/discover.d.ts.map +1 -0
- package/dist/.dts7/build/display-path.d.ts +6 -0
- package/dist/.dts7/build/display-path.d.ts.map +1 -0
- package/dist/.dts7/build/docs.d.ts +172 -0
- package/dist/.dts7/build/docs.d.ts.map +1 -0
- package/dist/.dts7/build/env-example.d.ts +85 -0
- package/dist/.dts7/build/env-example.d.ts.map +1 -0
- package/dist/.dts7/build/errors.d.ts +78 -0
- package/dist/.dts7/build/errors.d.ts.map +1 -0
- package/dist/.dts7/build/evidence-cache.d.ts +74 -0
- package/dist/.dts7/build/evidence-cache.d.ts.map +1 -0
- package/dist/.dts7/build/evidence-model.d.ts +50 -0
- package/dist/.dts7/build/evidence-model.d.ts.map +1 -0
- package/dist/.dts7/build/evidence-reference.d.ts +67 -0
- package/dist/.dts7/build/evidence-reference.d.ts.map +1 -0
- package/dist/.dts7/build/evidence-snapshot.d.ts +142 -0
- package/dist/.dts7/build/evidence-snapshot.d.ts.map +1 -0
- package/dist/.dts7/build/exclusive-group.d.ts +19 -0
- package/dist/.dts7/build/exclusive-group.d.ts.map +1 -0
- package/dist/.dts7/build/finding-model.d.ts +80 -0
- package/dist/.dts7/build/finding-model.d.ts.map +1 -0
- package/dist/.dts7/build/generate-documentation.d.ts +176 -0
- package/dist/.dts7/build/generate-documentation.d.ts.map +1 -0
- package/dist/.dts7/build/generate-env-artifacts.d.ts +191 -0
- package/dist/.dts7/build/generate-env-artifacts.d.ts.map +1 -0
- package/dist/.dts7/build/generate-evidence.d.ts +77 -0
- package/dist/.dts7/build/generate-evidence.d.ts.map +1 -0
- package/dist/.dts7/build/generate-manifest.d.ts +100 -0
- package/dist/.dts7/build/generate-manifest.d.ts.map +1 -0
- package/dist/.dts7/build/generate-usage.d.ts +94 -0
- package/dist/.dts7/build/generate-usage.d.ts.map +1 -0
- package/dist/.dts7/build/generated-banner.d.ts +43 -0
- package/dist/.dts7/build/generated-banner.d.ts.map +1 -0
- package/dist/.dts7/build/glob.d.ts +6 -0
- package/dist/.dts7/build/glob.d.ts.map +1 -0
- package/dist/.dts7/build/governance-fields.d.ts +34 -0
- package/dist/.dts7/build/governance-fields.d.ts.map +1 -0
- package/dist/.dts7/build/humanize-key.d.ts +14 -0
- package/dist/.dts7/build/humanize-key.d.ts.map +1 -0
- package/dist/.dts7/build/index.d.ts +89 -0
- package/dist/.dts7/build/index.d.ts.map +1 -0
- package/dist/.dts7/build/lifecycle-model.d.ts +181 -0
- package/dist/.dts7/build/lifecycle-model.d.ts.map +1 -0
- package/dist/.dts7/build/link.d.ts +222 -0
- package/dist/.dts7/build/link.d.ts.map +1 -0
- package/dist/.dts7/build/literal-eval.d.ts +24 -0
- package/dist/.dts7/build/literal-eval.d.ts.map +1 -0
- package/dist/.dts7/build/live-expirations.d.ts +48 -0
- package/dist/.dts7/build/live-expirations.d.ts.map +1 -0
- package/dist/.dts7/build/manifest.d.ts +31 -0
- package/dist/.dts7/build/manifest.d.ts.map +1 -0
- package/dist/.dts7/build/map-utils.d.ts +8 -0
- package/dist/.dts7/build/map-utils.d.ts.map +1 -0
- package/dist/.dts7/build/merge-documentation.d.ts +36 -0
- package/dist/.dts7/build/merge-documentation.d.ts.map +1 -0
- package/dist/.dts7/build/ownership-model.d.ts +58 -0
- package/dist/.dts7/build/ownership-model.d.ts.map +1 -0
- package/dist/.dts7/build/parse.d.ts +206 -0
- package/dist/.dts7/build/parse.d.ts.map +1 -0
- package/dist/.dts7/build/reference-projections.d.ts +168 -0
- package/dist/.dts7/build/reference-projections.d.ts.map +1 -0
- package/dist/.dts7/build/resolution/resolve-import.d.ts +62 -0
- package/dist/.dts7/build/resolution/resolve-import.d.ts.map +1 -0
- package/dist/.dts7/build/resolution/resolve-package-schema.d.ts +83 -0
- package/dist/.dts7/build/resolution/resolve-package-schema.d.ts.map +1 -0
- package/dist/.dts7/build/resolution/resolve-tsconfig-paths.d.ts +18 -0
- package/dist/.dts7/build/resolution/resolve-tsconfig-paths.d.ts.map +1 -0
- package/dist/.dts7/build/resolution/resolve-within-root.d.ts +35 -0
- package/dist/.dts7/build/resolution/resolve-within-root.d.ts.map +1 -0
- package/dist/.dts7/build/sarif.d.ts +66 -0
- package/dist/.dts7/build/sarif.d.ts.map +1 -0
- package/dist/.dts7/build/scan-dependencies.d.ts +71 -0
- package/dist/.dts7/build/scan-dependencies.d.ts.map +1 -0
- package/dist/.dts7/build/sort-by-identity.d.ts +14 -0
- package/dist/.dts7/build/sort-by-identity.d.ts.map +1 -0
- package/dist/.dts7/build/source-position.d.ts +69 -0
- package/dist/.dts7/build/source-position.d.ts.map +1 -0
- package/dist/.dts7/build/tool-version.d.ts +8 -0
- package/dist/.dts7/build/tool-version.d.ts.map +1 -0
- package/dist/.dts7/build/types.d.ts +7 -0
- package/dist/.dts7/build/types.d.ts.map +1 -0
- package/dist/.dts7/build/typescript.d.ts +6 -0
- package/dist/.dts7/build/typescript.d.ts.map +1 -0
- package/dist/.dts7/build/usage-report.d.ts +124 -0
- package/dist/.dts7/build/usage-report.d.ts.map +1 -0
- package/dist/.dts7/cli/filesystem.d.ts +7 -0
- package/dist/.dts7/cli/filesystem.d.ts.map +1 -0
- package/dist/.dts7/eslint-plugin/glob.d.ts +7 -0
- package/dist/.dts7/eslint-plugin/glob.d.ts.map +1 -0
- package/dist/.dts7/eslint-plugin/index.d.ts +38 -0
- package/dist/.dts7/eslint-plugin/index.d.ts.map +1 -0
- package/dist/.dts7/eslint-plugin/no-node-fs.d.ts +15 -0
- package/dist/.dts7/eslint-plugin/no-node-fs.d.ts.map +1 -0
- package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts +23 -0
- package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts.map +1 -0
- package/dist/.dts7/evidence/define-projection.d.ts +51 -0
- package/dist/.dts7/evidence/define-projection.d.ts.map +1 -0
- package/dist/.dts7/evidence/index.d.ts +19 -0
- package/dist/.dts7/evidence/index.d.ts.map +1 -0
- package/dist/.dts7/helpers/index.d.ts +132 -0
- package/dist/.dts7/helpers/index.d.ts.map +1 -0
- package/dist/.dts7/helpers/processors.d.ts +32 -0
- package/dist/.dts7/helpers/processors.d.ts.map +1 -0
- package/dist/.dts7/helpers/validators.d.ts +68 -0
- package/dist/.dts7/helpers/validators.d.ts.map +1 -0
- package/dist/.dts7/node/index.d.ts +21 -0
- package/dist/.dts7/node/index.d.ts.map +1 -0
- package/dist/.dts7/runtime/cache.d.ts +17 -0
- package/dist/.dts7/runtime/cache.d.ts.map +1 -0
- package/dist/.dts7/runtime/create.d.ts +23 -0
- package/dist/.dts7/runtime/create.d.ts.map +1 -0
- package/dist/.dts7/runtime/document.d.ts +214 -0
- package/dist/.dts7/runtime/document.d.ts.map +1 -0
- package/dist/.dts7/runtime/errors.d.ts +55 -0
- package/dist/.dts7/runtime/errors.d.ts.map +1 -0
- package/dist/.dts7/runtime/index.d.ts +25 -0
- package/dist/.dts7/runtime/index.d.ts.map +1 -0
- package/dist/.dts7/runtime/registry.d.ts +12 -0
- package/dist/.dts7/runtime/registry.d.ts.map +1 -0
- package/dist/.dts7/runtime/reset.d.ts +8 -0
- package/dist/.dts7/runtime/reset.d.ts.map +1 -0
- package/dist/.dts7/runtime/types.d.ts +190 -0
- package/dist/.dts7/runtime/types.d.ts.map +1 -0
- package/dist/.dts7/runtime/validate.d.ts +27 -0
- package/dist/.dts7/runtime/validate.d.ts.map +1 -0
- package/dist/{build-6XFHJFQK.js → build-UEENZEUX.js} +43 -42
- package/dist/build-UEENZEUX.js.map +1 -0
- package/dist/build.cjs +42 -41
- package/dist/build.cjs.map +1 -1
- package/dist/build.js +42 -41
- package/dist/build.js.map +1 -1
- package/dist/build.ts7.d.cts +1 -0
- package/dist/build.ts7.d.ts +1 -0
- package/dist/{chunk-RL5KFVUT.js → chunk-TBL3O7IG.js} +2 -2
- package/dist/cli/index.js +29 -28
- package/dist/cli/index.js.map +1 -1
- package/dist/eslint-plugin/index.cjs.map +1 -1
- package/dist/eslint-plugin/index.js.map +1 -1
- package/dist/eslint-plugin/index.ts7.d.cts +1 -0
- package/dist/eslint-plugin/index.ts7.d.ts +1 -0
- package/dist/evidence.cjs +1 -1
- package/dist/evidence.cjs.map +1 -1
- package/dist/evidence.js +1 -1
- package/dist/evidence.js.map +1 -1
- package/dist/evidence.ts7.d.cts +1 -0
- package/dist/evidence.ts7.d.ts +1 -0
- package/dist/helpers.cjs +4 -4
- package/dist/helpers.cjs.map +1 -1
- package/dist/helpers.js +4 -4
- package/dist/helpers.js.map +1 -1
- package/dist/helpers.ts7.d.cts +1 -0
- package/dist/helpers.ts7.d.ts +1 -0
- package/dist/index.cjs.map +1 -1
- package/dist/index.js.map +1 -1
- package/dist/index.ts7.d.cts +1 -0
- package/dist/index.ts7.d.ts +1 -0
- package/dist/node.ts7.d.cts +1 -0
- package/dist/node.ts7.d.ts +1 -0
- package/examples/README.md +46 -80
- package/package.json +43 -12
- package/schemas/contract-model.schema.json +7 -7
- package/schemas/env-cap-report.schema.json +88 -88
- package/skills/env-cap/SKILL.md +12 -13
- package/skills/env-cap/references/api.md +1 -1
- package/specs/architecture.md +147 -122
- package/specs/decisions/0001-runtime-documentation-separation.md +1 -1
- package/specs/decisions/0014-cross-package-schema-discovery.md +4 -1
- package/specs/decisions/0023-tsconfig-path-alias-resolution.md +4 -1
- package/specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md +13 -8
- package/specs/generated-artifacts.md +91 -71
- package/specs/migrations/README.md +6 -6
- package/specs/migrations/from-centralized-schema.md +1 -1
- package/specs/migrations/from-t3-env.md +9 -9
- package/PROMPT.md +0 -89
- package/dist/build-6XFHJFQK.js.map +0 -1
- /package/dist/{chunk-RL5KFVUT.js.map → chunk-TBL3O7IG.js.map} +0 -0
package/README.md
CHANGED
|
@@ -10,81 +10,102 @@
|
|
|
10
10
|
[](https://www.npmjs.com/package/@maverickcer/env-cap)
|
|
11
11
|
[](LICENSE)
|
|
12
12
|
|
|
13
|
-
**
|
|
13
|
+
**Each feature declares the environment variables it needs and their format. Your app validates them all in one place at startup, fails fast on a bad value, and reports how they should be rotated before they expire.**
|
|
14
14
|
|
|
15
|
-
`env-cap`
|
|
15
|
+
`env-cap` is a TypeScript library. A feature is a folder or an installable package in your code; the docs also call it a capability. It declares its variables in a **contract**: how to parse and check each value, who owns it and, for a secret, when it expires.
|
|
16
16
|
|
|
17
|
-
|
|
17
|
+
A build step lists every contract in the **manifest**, a generated file your app passes to `validateEnv()` at startup. A bad value throws an error that names the variable, never its value.
|
|
18
18
|
|
|
19
|
-
|
|
19
|
+
**Rotation** replaces a secret before its expiry date, following the steps its contract gives. It applies to each variable whose `documentEnv()` entry declares both, for example `STRIPE_KEY: { expiresAt: "2026-09-01", refreshInstructions: "Rotate in the Stripe dashboard, then redeploy." }`. The build step writes environment docs that print those steps beside each date. They flag a variable that has expired or expires within 30 days, the default window. It also writes the **ownership report**: each contract's owner and the variables nothing reads.
|
|
20
|
+
|
|
21
|
+
It works alongside `dotenv`, Zod and your secret manager. It does not load `.env` files, store secrets or replace your validator.
|
|
22
|
+
|
|
23
|
+
**Try it:** run `npm install @maverickcer/env-cap`, then `npx env-cap init`. It writes a starter contract and a script that writes the manifest, the environment docs (`docs/ENVIRONMENT.md`) and the ownership report. A CI test runs both steps in an empty project ([Install and verify](#install-and-verify)). Once `validateEnv()` runs at startup, an `http://` value for the starter's `EXAMPLE_API_URL` stops the app with:
|
|
24
|
+
|
|
25
|
+
```text
|
|
26
|
+
Environment validation failed.
|
|
20
27
|
|
|
21
|
-
|
|
28
|
+
1 configuration error found:
|
|
22
29
|
|
|
23
|
-
|
|
30
|
+
EXAMPLE_API_URL
|
|
31
|
+
---------------
|
|
32
|
+
Validation failed:
|
|
33
|
+
Expected an https URL.
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
## Why it exists
|
|
24
37
|
|
|
25
|
-
**
|
|
38
|
+
**The problem:** a variable can be well-formed and still be a problem. A validator checks its shape and a secret manager stores it. Neither says who owns it, what depends on it, when it must rotate, or whether anything still reads it.
|
|
26
39
|
|
|
27
|
-
**
|
|
40
|
+
**What changes:** the answers live in the code next to each variable. An expiring secret shows up in the environment docs with the steps to rotate it, and a variable nothing reads shows up in the ownership report.
|
|
41
|
+
|
|
42
|
+
**Who it is for:** application developers who have shipped an undefined variable to production, and platform engineers who own configuration across teams.
|
|
28
43
|
|
|
29
44
|
## How it differs
|
|
30
45
|
|
|
31
|
-
| Tool | What it solves
|
|
32
|
-
| ---------------------- |
|
|
33
|
-
| `dotenv` | Loads values from a `.env` file
|
|
34
|
-
| Zod / envalid / t3-env | Validates value shape and types
|
|
35
|
-
| Secret manager | Stores and manages secrets
|
|
36
|
-
| `env-cap` |
|
|
46
|
+
| Tool | What it solves | What remains unanswered |
|
|
47
|
+
| ---------------------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
|
|
48
|
+
| `dotenv` | Loads values from a `.env` file | Who owns the value, why it exists, whether it is still used, when it expires |
|
|
49
|
+
| Zod / envalid / t3-env | Validates value shape and types | Whether the variable is still needed, who owns it, or what code depends on it |
|
|
50
|
+
| Secret manager | Stores and manages secrets | Which code actually reads the secret |
|
|
51
|
+
| `env-cap` | Validates each feature's variables at startup; reports expiry dates, rotation steps, owners and readers | Does not replace loading, secret storage, or application-specific validation |
|
|
37
52
|
|
|
38
|
-
|
|
53
|
+
Keep your existing validator: any function that returns `true` or a message plugs into a contract. [Migration guides](specs/migrations/README.md) cover `dotenv`, Zod, envalid and t3-env, including when to stay put.
|
|
39
54
|
|
|
40
55
|
## What it does
|
|
41
56
|
|
|
42
|
-
|
|
57
|
+
Application developers write contracts with `@maverickcer/env-cap` and `./helpers`. Platform engineers who own CI use `./build`, the `env-cap` CLI and the GitHub Action. These write the manifest, the environment docs, the ownership report and the **evidence file**, a JSON record of owners, expiry dates and readers. `--check` fails when any of them is stale. Reviewers build their own views of the evidence file with `./evidence`. The [Guide](GUIDE.md) tells each reader's story in full. The table below is generated from `package.json#exports` and `docs/surface.json`; the `GeneratedRegions` check fails if it is stale.
|
|
43
58
|
|
|
44
|
-
|
|
45
|
-
declare → generate → validate → consume
|
|
46
|
-
```
|
|
59
|
+
<!-- ipc:begin entry-points -->
|
|
47
60
|
|
|
48
|
-
|
|
61
|
+
| Export | Source | Environment | Tier | Purpose |
|
|
62
|
+
| ------------------------------------ | -------------------- | ------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
63
|
+
| `@maverickcer/env-cap` | `src/runtime/` | No Node module or Node global | Stable | `createEnv`, `documentEnv`, `validateEnv`, `resetEnvCache`, `isEnvContract` and the error types |
|
|
64
|
+
| `@maverickcer/env-cap/build` | `src/build/` | Node only, in development and CI | Stable | Discovery, AST analysis and artifact generation. The four `generate*()` orchestrators and the lower-level primitives are Stable (ADR 0045, `VERSIONING.md`). |
|
|
65
|
+
| `@maverickcer/env-cap/helpers` | `src/helpers/` | No Node module; `processors.base64()` returns a Node `Buffer` | Stable | `processors` and `validators` |
|
|
66
|
+
| `@maverickcer/env-cap/node` | `src/node/` | Node only, in development and CI | Stable | `nodeBuildFileSystem`, the `BuildFileSystem` adapter a build script hands to `./build` |
|
|
67
|
+
| `@maverickcer/env-cap/evidence` | `src/evidence/` | No Node module or Node global | Stable | `defineEvidenceProjection`, pure transforms over the Evidence Model (Stable, see `VERSIONING.md`) |
|
|
68
|
+
| `@maverickcer/env-cap/eslint-plugin` | `src/eslint-plugin/` | Node only, inside the project's ESLint | Stable | The `no-raw-process-env` and `no-node-fs` lint rules |
|
|
69
|
+
| `@maverickcer/env-cap/schema` | `schemas/` | Static JSON | Stable | The JSON Schema for `env-cap --json` output (`env-cap-report.schema.json`) and the model schemas under `./schema/*` |
|
|
49
70
|
|
|
50
|
-
|
|
71
|
+
<!-- ipc:end entry-points -->
|
|
51
72
|
|
|
52
|
-
|
|
73
|
+
### See it run
|
|
53
74
|
|
|
54
|
-
|
|
55
|
-
// features/payments/env.schema.ts
|
|
75
|
+
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:
|
|
56
76
|
|
|
57
|
-
|
|
77
|
+
```ts
|
|
78
|
+
// examples/application/src/env.ts (excerpt: other variables and fields omitted)
|
|
79
|
+
import { createEnv, documentEnv, type RawEnv } from "@maverickcer/env-cap"
|
|
80
|
+
import { processors } from "@maverickcer/env-cap/helpers"
|
|
58
81
|
|
|
59
|
-
const
|
|
82
|
+
const schema = {
|
|
83
|
+
DATABASE_URL: { processor: processors.toURL() },
|
|
60
84
|
STRIPE_KEY: {
|
|
61
|
-
|
|
85
|
+
processor: (value: unknown): string => String(value ?? ""),
|
|
86
|
+
validator: (value: string, rawEnv: RawEnv) => {
|
|
87
|
+
if (rawEnv["PAYMENT_PROVIDER"] !== "stripe") return true
|
|
88
|
+
return value.length > 0 || "Stripe key is required when PAYMENT_PROVIDER=stripe."
|
|
89
|
+
},
|
|
62
90
|
},
|
|
63
91
|
}
|
|
64
92
|
|
|
65
|
-
export const
|
|
93
|
+
export const env = createEnv(schema, { name: "app", source: import.meta.url })
|
|
66
94
|
|
|
67
|
-
documentEnv(
|
|
68
|
-
owner: "
|
|
95
|
+
documentEnv(schema, {
|
|
96
|
+
owner: "platform-team",
|
|
69
97
|
variables: {
|
|
98
|
+
DATABASE_URL: { description: "Postgres connection string.", required: true },
|
|
70
99
|
STRIPE_KEY: {
|
|
71
|
-
description: "Stripe secret key used to
|
|
72
|
-
|
|
73
|
-
expiresAt: "
|
|
74
|
-
sensitivity: "secret",
|
|
100
|
+
description: "Stripe secret key used to authenticate server-side API calls.",
|
|
101
|
+
required: true,
|
|
102
|
+
expiresAt: "2026-09-01",
|
|
75
103
|
},
|
|
76
104
|
},
|
|
77
105
|
})
|
|
78
106
|
```
|
|
79
107
|
|
|
80
|
-
|
|
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`):
|
|
108
|
+
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
109
|
|
|
89
110
|
```text
|
|
90
111
|
$ npx env-cap --include src/env.ts --location src/generated/env.manifest.ts --evidence docs/env.evidence.json
|
|
@@ -103,95 +124,97 @@ $ npx tsx scripts/generate-docs/run.ts
|
|
|
103
124
|
- STRIPE_KEY in app
|
|
104
125
|
```
|
|
105
126
|
|
|
106
|
-
This is
|
|
107
|
-
|
|
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.
|
|
127
|
+
This is output from [`examples/application`](https://github.com/MaverickCER/env-cap/tree/main/examples/application) (`npm run docs:reports`). `N` stands for the days since 2026-09-01, counted on the day you run it. The report states facts a validator cannot see. `STRIPE_KEY` is declared to expire on 2026-09-01, and that date has passed. `DATABASE_URL` and `STRIPE_KEY` are declared in the `app` contract, but the analysis found no code that reads them.
|
|
109
128
|
|
|
110
129
|
### Evidence it works
|
|
111
130
|
|
|
112
|
-
- **Real
|
|
113
|
-
- **
|
|
114
|
-
- **
|
|
115
|
-
- **
|
|
116
|
-
- **
|
|
131
|
+
- **Real output:** CI's `examples` job re-runs the block above and compares its expiry and unconsumed lists with this README (`npm run verify:readme-example`). `required` waits for `examples`, so a failure blocks a merge.
|
|
132
|
+
- **Coverage floors:** 90% branches, 100% functions, 95% lines and statements, enforced by the `contract` job (`vitest.config.ts`). A pull request can lower a floor; reviewers treat that as a reviewed change.
|
|
133
|
+
- **Mutation testing:** the `contract` job fails on any surviving, timed-out or uncovered Stryker mutant in `src/`. Managed copies under `src/_ipc/`, `scripts/`, and mutants silenced by a disable comment are not counted.
|
|
134
|
+
- **Runtimes:** the runtime, helpers and evidence entries run on Node 22 and 24 in blocking jobs. They also run under Bun, Deno and a Web-globals VM. `required` waits for the Bun and Deno job (`cross-runtime`).
|
|
135
|
+
- **Size budgets:** 3 KB gzip for the runtime, 4 KB for helpers and 3 KB for evidence, enforced by the `Size` check ([ADR 0008](specs/decisions/0008-gzip-size-budget.md)). The budget measures the entry file, not your bundle.
|
|
117
136
|
|
|
118
137
|
## Install and verify
|
|
119
138
|
|
|
120
|
-
**Prerequisites:** Node.js `>=22`. TypeScript 5
|
|
139
|
+
**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
140
|
|
|
122
141
|
```sh
|
|
123
142
|
npm install @maverickcer/env-cap
|
|
124
|
-
npx env-cap init #
|
|
125
|
-
npm install --save-dev typescript # the generator parses your schema with it
|
|
143
|
+
npx env-cap init # writes env.schema.ts and scripts/generate-env.mjs
|
|
126
144
|
node scripts/generate-env.mjs
|
|
127
145
|
```
|
|
128
146
|
|
|
129
|
-
|
|
147
|
+
`init` writes two files and skips any file that already exists. Without a valid `package.json` it exits `1` and writes nothing. `test/cli/init.test.ts` pins these rules and the templates. **Verify it works:** the script prints `Discovered 1 contract(s).` and exits `0`. `test/cli/quick-start.test.ts` runs `init` and the script against the built package and checks that line and each generated file. Report an issue if that line differs.
|
|
130
148
|
|
|
131
|
-
|
|
149
|
+
Then validate once at startup and read values through the contract. `init` writes `env.schema.ts` into `src/` when that folder exists, otherwise into the project root; adjust the import path to match:
|
|
132
150
|
|
|
133
151
|
```ts
|
|
134
152
|
import { validateEnv } from "@maverickcer/env-cap"
|
|
135
153
|
import { manifest } from "./generated/env.manifest"
|
|
136
|
-
import {
|
|
154
|
+
import { exampleEnv } from "./env.schema"
|
|
137
155
|
|
|
138
156
|
await validateEnv({ manifest, values: process.env })
|
|
139
|
-
|
|
157
|
+
exampleEnv.EXAMPLE_API_URL
|
|
140
158
|
```
|
|
141
159
|
|
|
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
|
-
|
|
144
160
|
## Fit and capabilities
|
|
145
161
|
|
|
146
|
-
**Use cases:** find expired or unowned secrets before they page someone
|
|
162
|
+
**Use cases:** find expired or unowned secrets before they page someone. Generate variable documentation from the code instead of a wiki. Let each team own the variables its feature needs. Give CI bots facts such as "`STRIPE_KEY` is declared but unconsumed".
|
|
163
|
+
|
|
164
|
+
**What you get:**
|
|
147
165
|
|
|
148
|
-
|
|
166
|
+
- Per-feature contracts with validators, owners, sensitivity and expiry dates ([contracts](GUIDE.md#capability-owned-contracts)).
|
|
167
|
+
- A manifest, environment docs, `.env.example` and an ownership report, from static analysis that never imports your schema files.
|
|
168
|
+
- A persisted evidence file, a CLI, a [GitHub Action](GUIDE.md#github-action), scheduled rotation reports and an [ESLint plugin](GUIDE.md#eslint-plugin).
|
|
169
|
+
- One central schema or one contract per feature or package; the manifest stays project-wide either way.
|
|
149
170
|
|
|
150
|
-
|
|
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.
|
|
171
|
+
**How it works:** the runtime and the build tooling are separate entry points. The runtime has no filesystem access, which lint and a tarball scan enforce. The build pass runs only in development and CI ([Architecture](GUIDE.md#runtime-and-build-time-are-intentionally-separate)).
|
|
154
172
|
|
|
155
|
-
**
|
|
173
|
+
**Runtimes:** Node.js 22 and 24 are tested. Bun, Deno and a browser-style bundle run in CI for the runtime, helpers and evidence entries. Edge runtimes are not tested ([support matrix](GUIDE.md#runtime-support-matrix)).
|
|
156
174
|
|
|
157
|
-
**
|
|
175
|
+
**Package managers:** npm is supported. pnpm, Yarn 1 and Yarn Berry are tested only for installing the tarball and importing every entry ([details](GUIDE.md#package-managers)).
|
|
158
176
|
|
|
159
177
|
## Limits and when not to use it
|
|
160
178
|
|
|
161
|
-
- **Skip it when**
|
|
162
|
-
- **Trade-offs:** it adds a build step and a declaration per variable
|
|
163
|
-
- **Install weight:** the
|
|
164
|
-
- **
|
|
179
|
+
- **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.
|
|
180
|
+
- **Trade-offs:** it adds a build step and a declaration per variable. Its reports are only as accurate as those declarations, and it cannot see variables read outside the analyzed code.
|
|
181
|
+
- **Install weight:** the one dependency is a TypeScript 6 compiler bundled in the tarball. Only the build entry loads it, and a CI step fails if a runtime entry can reach it ([Adoption guide](ADOPTION.md#bundle-size-and-performance)).
|
|
182
|
+
- **Dynamic schemas:** a schema built by a function, or a spread at the top of a schema object, produces a parse warning. A spread nested inside a variable's definition or its `documentEnv()` entry is skipped without one. Nothing is guessed.
|
|
183
|
+
- **Automation:** bots can read the same manifest and evidence. A structured finding does not make a fix correct, so review a bot's change as you would a person's.
|
|
165
184
|
|
|
166
185
|
## Security and supply chain
|
|
167
186
|
|
|
168
|
-
- **
|
|
169
|
-
- **
|
|
170
|
-
- **
|
|
171
|
-
- **
|
|
187
|
+
- **Runtime:** it has no filesystem access and reads only the `values` you pass. Lint and the tarball scan enforce the first; the tarball scan and a browser-bundle test the second. Both scans are textual. Contracts redact themselves when logged or serialized, but spreading a contract reads every value ([runtime model](SECURITY.md#runtime-security-model)).
|
|
188
|
+
- **Errors:** validation errors carry variable and contract names and your own messages, never values (tested). A validator message that embeds the value is passed through.
|
|
189
|
+
- **Build:** schema files are parsed as syntax trees and never imported or run (tested). It does not sandbox the rest of your build ([build-time model](SECURITY.md#build-time-security-model)).
|
|
190
|
+
- **Dependencies:** what installing the package adds is generated from `package.json` into the [Adoption guide](ADOPTION.md#security--threat-model). MIT licensed.
|
|
191
|
+
- **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)).
|
|
192
|
+
- **Report a vulnerability** privately: [SECURITY.md](SECURITY.md#reporting-a-vulnerability).
|
|
172
193
|
|
|
173
194
|
## Maturity, versioning and support
|
|
174
195
|
|
|
175
|
-
Pre-1.0
|
|
196
|
+
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
197
|
|
|
177
|
-
- **Upgrade
|
|
178
|
-
- **
|
|
198
|
+
- **Upgrade:** read the [CHANGELOG](CHANGELOG.md) on every minor; [migration guides](specs/migrations/README.md) cover adoption from other tools.
|
|
199
|
+
- **Releases:** [GitHub releases](https://github.com/MaverickCER/env-cap/releases); a person merges every release pull request ([RELEASING.md](RELEASING.md)).
|
|
179
200
|
- **Bugs and requests:** [open an issue](https://github.com/MaverickCER/env-cap/issues); see [SUPPORT.md](SUPPORT.md).
|
|
180
|
-
- **Troubleshooting:** the [Guide's troubleshooting
|
|
201
|
+
- **Troubleshooting:** the [Guide's troubleshooting table](GUIDE.md#troubleshooting).
|
|
181
202
|
|
|
182
203
|
## Documentation
|
|
183
204
|
|
|
184
|
-
- **[Guide](GUIDE.md)
|
|
185
|
-
- **[Adoption guide](ADOPTION.md)
|
|
186
|
-
- **[
|
|
187
|
-
- **[
|
|
188
|
-
- **[
|
|
189
|
-
- **
|
|
205
|
+
- **[Guide](GUIDE.md):** one story per entry point and reader, the CLI options, the GitHub Action and the ESLint plugin.
|
|
206
|
+
- **[Adoption guide](ADOPTION.md):** what adopting costs, what it needs, and what it refuses to do.
|
|
207
|
+
- **[Security](SECURITY.md):** the reviewer's model of what is enforced, where, and what is not.
|
|
208
|
+
- **[API reference](https://maverickcer.github.io/env-cap/api/):** every exported symbol, generated from source.
|
|
209
|
+
- **[Agent skill](https://raw.githubusercontent.com/MaverickCER/env-cap/main/skills/env-cap/SKILL.md):** a short manual for an AI agent, generated from `docs/skill.json` and the exports; [AGENTS.md](AGENTS.md) adds the rules for this repository.
|
|
210
|
+
- **[Architecture](specs/architecture.md)** and **[ADRs](https://github.com/MaverickCER/env-cap/tree/main/specs/decisions):** why it is designed this way.
|
|
211
|
+
- **[Examples](https://github.com/MaverickCER/env-cap/tree/main/examples):** runnable application, team-service, enterprise-platform and Next.js examples.
|
|
212
|
+
- **Toolkit:** `data-cap` governs application data; `repo-contract` and `internal-package-contract` verify both ([toolkit overview](https://github.com/MaverickCER/internal-package-contract/blob/main/TOOLKIT.md)).
|
|
190
213
|
|
|
191
214
|
## Next steps
|
|
192
215
|
|
|
193
|
-
- **Evaluate:** read the [Adoption guide](ADOPTION.md), then try env-cap
|
|
194
|
-
- **Integrate:** follow the [Guide](GUIDE.md#core-workflow) and
|
|
195
|
-
- **Verify:**
|
|
216
|
+
- **Evaluate:** read the [Adoption guide](ADOPTION.md), then try env-cap on one real schema.
|
|
217
|
+
- **Integrate:** follow the [Guide](GUIDE.md#core-workflow) and run an [example](https://github.com/MaverickCER/env-cap/tree/main/examples).
|
|
218
|
+
- **Verify:** check the [security model](SECURITY.md#runtime-security-model) against the tests it names.
|
|
196
219
|
|
|
197
|
-
Contributing: [CONTRIBUTING.md](CONTRIBUTING.md) covers setup
|
|
220
|
+
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
|
|
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
|
|
|
@@ -11,33 +11,42 @@ For what semver actually covers, see [`VERSIONING.md`](VERSIONING.md).
|
|
|
11
11
|
Releases are driven by [Changesets](https://github.com/changesets/changesets) and npm's
|
|
12
12
|
[OIDC trusted publishing](https://docs.npmjs.com/trusted-publishers), through
|
|
13
13
|
[`.github/workflows/release.yml`](https://github.com/MaverickCER/env-cap/blob/main/.github/workflows/release.yml),
|
|
14
|
-
which calls a shared, pinned workflow.
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
14
|
+
which calls a shared, pinned workflow. A person merges the release pull request.
|
|
15
|
+
|
|
16
|
+
**No `NPM_TOKEN` secret exists in this repository**, and none is needed. The workflow's OIDC identity is
|
|
17
|
+
verified by npm against a one-time trusted-publisher registration on npmjs.com (see
|
|
18
|
+
[First-time setup](#first-time-setup)).
|
|
19
|
+
|
|
20
|
+
The one other path is recovery. A version on `main` that is not on npm is built and published without a pull
|
|
21
|
+
request (see "Recovering from a failed release").
|
|
18
22
|
|
|
19
23
|
The loop:
|
|
20
24
|
|
|
21
25
|
1. A pull request that changes user-facing behavior carries a changeset in `.changeset/` (Markdown,
|
|
22
26
|
`patch`/`minor`/`major` plus a consumer-facing description). When it does not, one is generated on `main`
|
|
23
|
-
from the commit messages
|
|
24
|
-
trailer overrides
|
|
27
|
+
from the commit messages: `feat`, `fix`, `perf`, `revert` or a breaking marker. A `Changeset: <bump>`
|
|
28
|
+
trailer overrides. Below 1.0.0 a generated bump never exceeds minor, so 1.0.0 is reached only by a
|
|
25
29
|
deliberate `major` changeset.
|
|
26
30
|
2. On each push to `main`, the workflow opens or updates a pull request titled **"chore: version packages"**
|
|
27
|
-
from the branch **`changeset-release/main
|
|
28
|
-
changeset files, bumps `package.json`'s `version` and rewrites `CHANGELOG.md`. Review it and
|
|
29
|
-
yourself; it is never merged automatically.
|
|
30
|
-
3. Merging it runs the workflow again. A **build** job, which holds no publishing credentials
|
|
31
|
-
`npm run verify` when the package defines it
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
31
|
+
from the branch **`changeset-release/main`**. It dispatches CI on that pull request. The pull request
|
|
32
|
+
consumes the changeset files, bumps `package.json`'s `version` and rewrites `CHANGELOG.md`. Review it and
|
|
33
|
+
merge it yourself; it is never merged automatically.
|
|
34
|
+
3. Merging it runs the workflow again. A **build** job, which holds no publishing credentials:
|
|
35
|
+
- runs `npm run verify` when the package defines it;
|
|
36
|
+
- requires that a CI run on a commit with exactly this tree finished its `contract` job with success, and
|
|
37
|
+
its `required` job too where that run has one;
|
|
38
|
+
- checks that no scaffold prompt is unanswered;
|
|
39
|
+
- packs the tarball, installs that tarball into an empty project and imports every entry point it declares.
|
|
40
|
+
|
|
41
|
+
Only if all of that passes does the **publish** job run, and only from the default branch. It publishes
|
|
42
|
+
exactly the tarball the build job made, over OIDC with a provenance attestation.
|
|
43
|
+
|
|
44
|
+
4. After publishing, the workflow tags the release `v<major>.<minor>.<patch>` on the merged commit. It
|
|
45
|
+
force-updates the floating major tag (`v0` while the package is 0.x, `v1` from 1.0.0). Then it asks npm
|
|
46
|
+
what it now serves. The version must be there and must carry the provenance attestation, or the run goes
|
|
47
|
+
red. The floating tag tracks the composite Action's interface (`action.yml` inputs and outputs).
|
|
48
|
+
`uses: maverickcer/env-cap@v0` therefore keeps pointing at the latest compatible build until
|
|
49
|
+
`action.yml` itself has a breaking change.
|
|
41
50
|
|
|
42
51
|
`CHANGELOG.md` is generated; never hand-edit it. Fix a wrong entry by correcting the offending changeset
|
|
43
52
|
before the version pull request is merged, or with a follow-up changeset after.
|
|
@@ -52,26 +61,23 @@ access, so it can't be done from a PR.
|
|
|
52
61
|
GitHub Actions:
|
|
53
62
|
- Organization or user: `maverickcer`
|
|
54
63
|
- Repository: `env-cap`
|
|
55
|
-
- Workflow filename: `release.yml
|
|
56
|
-
|
|
57
|
-
with a misleading `E404`)
|
|
64
|
+
- Workflow filename: `release.yml`. Enter exactly the filename alone, not a path. A mismatch here is the
|
|
65
|
+
most common cause of the OIDC flow failing with a misleading `E404`.
|
|
58
66
|
- Environment: leave blank unless `release.yml` is later scoped to a
|
|
59
67
|
GitHub Environment
|
|
60
|
-
2. That
|
|
68
|
+
2. That is the whole trust relationship: `release.yml`'s `id-token: write`
|
|
61
69
|
permission plus this registration. There is no token to copy anywhere.
|
|
62
70
|
|
|
63
|
-
Until the package exists on npm, its settings page doesn't either. For the
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
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.
|
|
71
|
+
Until the package exists on npm, its settings page doesn't either. For the **first ever publish**, make a
|
|
72
|
+
one-time manual `npm publish --access public` from a maintainer machine, from a clean `npm run verify` tree.
|
|
73
|
+
Register the trusted publisher immediately after that first `npm publish`. Then let every subsequent release
|
|
74
|
+
go through `release.yml`. Alternatively, publish an empty `0.0.0` placeholder manually first, register the
|
|
75
|
+
trusted publisher, then let the first real version pull request publish `0.1.0` over OIDC.
|
|
70
76
|
|
|
71
77
|
## Recovering from a failed release
|
|
72
78
|
|
|
73
|
-
Identify which state you're in first
|
|
74
|
-
|
|
79
|
+
Identify which state you're in first. The recovery differs, and the wrong one can double-publish or lose a
|
|
80
|
+
version.
|
|
75
81
|
|
|
76
82
|
### A. The version pull request is open, nothing published yet
|
|
77
83
|
|
|
@@ -83,30 +89,39 @@ Nothing is on npm; nothing to undo.
|
|
|
83
89
|
### B. The version pull request is merged, but the release failed
|
|
84
90
|
|
|
85
91
|
`main` now has the version bump and changelog commit, but npm does not have the version. This is the common
|
|
86
|
-
failure
|
|
87
|
-
|
|
92
|
+
failure. Its causes include:
|
|
93
|
+
|
|
94
|
+
- OIDC misconfiguration;
|
|
95
|
+
- a failing `npm run verify`;
|
|
96
|
+
- no CI run on the tree that passed `contract` and, where the run has it, `required`;
|
|
97
|
+
- a failing packed-consumer check in the build job;
|
|
98
|
+
- a registry blip.
|
|
99
|
+
|
|
100
|
+
To recover:
|
|
88
101
|
|
|
89
102
|
1. Confirm npm really doesn't have it: `npm view @maverickcer/env-cap versions --json`, and check the bumped version is
|
|
90
103
|
absent.
|
|
91
104
|
2. Find the cause (see [Common failures](#common-failure-causes)).
|
|
92
105
|
3. If it was transient or a configuration problem outside the repository (a registry blip, the
|
|
93
|
-
trusted-publisher registration), fix that
|
|
106
|
+
trusted-publisher registration), fix that. Then re-run the failed `release.yml` run from the Actions tab
|
|
94
107
|
("Re-run failed jobs"). A re-run uses the same commit.
|
|
95
108
|
4. If the cause is in the code, a re-run cannot help: it would build the same commit again. Fix it in a normal
|
|
96
|
-
pull request to `main`. What happens next depends on the commit type.
|
|
97
|
-
commit gets a changeset generated for it
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
109
|
+
pull request to `main`. What happens next depends on the commit type.
|
|
110
|
+
- A `fix`, `feat`, `perf` or `revert` commit gets a changeset generated for it. The workflow then opens a
|
|
111
|
+
new version pull request instead of publishing the stuck version. Merging that publishes the next
|
|
112
|
+
version, and the stuck version number is skipped.
|
|
113
|
+
- A commit type that releases nothing (`chore`, `ci`, `docs`) leaves no changeset. The workflow then sees
|
|
114
|
+
that the current `package.json` version isn't on npm, and builds and publishes that version.
|
|
115
|
+
5. Publishing by hand is the last resort. It skips the build job's proof that CI passed `contract` (and
|
|
116
|
+
`required`) on this tree, and it publishes without the provenance attestation that the workflow adds.
|
|
117
|
+
Check the CI run on that commit yourself first. If you must, publish that exact version from a clean tree
|
|
118
|
+
(`git checkout main && npm ci && npm run verify && npm publish --access public`). Then confirm the next push
|
|
104
119
|
to `main` produces no spurious version pull request.
|
|
105
120
|
|
|
106
121
|
### C. Published to npm, but a later workflow step failed
|
|
107
122
|
|
|
108
|
-
|
|
109
|
-
is done and correct.
|
|
123
|
+
For example, the publish succeeded but the floating major tag (`v0` or `v1`) roll failed. The release itself
|
|
124
|
+
is done and correct. Fix the trailing step by hand:
|
|
110
125
|
|
|
111
126
|
```bash
|
|
112
127
|
git checkout main && git pull
|
|
@@ -114,47 +129,48 @@ git tag -f v0 && git push origin v0 --force # while the package is 0.x
|
|
|
114
129
|
git tag -f v1 && git push origin v1 --force # from 1.0.0
|
|
115
130
|
```
|
|
116
131
|
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
whatever the real trailing failure was.
|
|
132
|
+
Fix it by hand rather than re-running the workflow. A re-run publishes nothing and runs none of the later
|
|
133
|
+
steps: the build job finds the version already on npm and stops there.
|
|
120
134
|
|
|
121
135
|
### D. Wrong version published
|
|
122
136
|
|
|
123
|
-
npm publishes are effectively permanent
|
|
124
|
-
|
|
125
|
-
can never be reused). Don't try to unpublish a normal mistake. Instead:
|
|
137
|
+
npm publishes are effectively permanent. `npm unpublish` is allowed only within 72 hours and only if nothing
|
|
138
|
+
depends on it, and the version number can never be reused. Don't try to unpublish a normal mistake. Instead:
|
|
126
139
|
|
|
127
140
|
- 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"`.
|
|
141
|
+
changeset that fixes it, and `npm deprecate @maverickcer/env-cap@x.y.z "Broken publish; use x.y.z+1"`.
|
|
130
142
|
- Accidental major/minor bump: it stays. Continue from the new baseline; a
|
|
131
143
|
version number is cheap, a rewritten history is not.
|
|
132
144
|
|
|
133
145
|
### E. First release, package not yet on npm
|
|
134
146
|
|
|
135
|
-
See [First-time setup](#first-time-setup)
|
|
136
|
-
|
|
137
|
-
the one manual step. Every release after that is automated.
|
|
147
|
+
See [First-time setup](#first-time-setup). The trusted-publisher registration cannot exist before the
|
|
148
|
+
package does, so the first publish is the one manual step. Every release after that is automated.
|
|
138
149
|
|
|
139
150
|
## Common failure causes
|
|
140
151
|
|
|
141
152
|
- **`E404` on publish with OIDC**: the trusted-publisher registration's
|
|
142
153
|
workflow filename doesn't exactly match `release.yml`, or the
|
|
143
154
|
org/user/repo fields are wrong.
|
|
144
|
-
- **The build job's verify or packed-consumer step fails**:
|
|
145
|
-
|
|
155
|
+
- **The build job's verify, contract-run or packed-consumer step fails**: one of these happened.
|
|
156
|
+
- The version pull request merged with a red `main`.
|
|
157
|
+
- No CI run on that tree passed `contract` and, where the run has it, `required`.
|
|
158
|
+
- The tarball does not contain what `exports` promises.
|
|
159
|
+
|
|
160
|
+
Fix `main` first, then recover per case B.
|
|
161
|
+
|
|
146
162
|
- **The final "Verify what npm now serves" step fails**: npm did not return the version or its provenance
|
|
147
163
|
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
|
|
149
|
-
spurious, delete it in a normal PR.
|
|
164
|
+
- **A version pull request appears when you didn't expect one**: there's a stray changeset file in
|
|
165
|
+
`.changeset/` on `main`. If it's spurious, delete it in a normal PR.
|
|
150
166
|
- **Two version pull requests**: an older one wasn't closed when `main` moved. Close the stale one; the
|
|
151
167
|
workflow only maintains the newest.
|
|
152
168
|
|
|
153
169
|
## Related
|
|
154
170
|
|
|
155
|
-
- [`VERSIONING.md`](VERSIONING.md)
|
|
171
|
+
- [`VERSIONING.md`](VERSIONING.md): what each bump type means, and which
|
|
156
172
|
surface semver actually covers.
|
|
157
|
-
- [`CONTRIBUTING.md`](CONTRIBUTING.md)
|
|
173
|
+
- [`CONTRIBUTING.md`](CONTRIBUTING.md): the contributor-side workflow
|
|
158
174
|
(branch, changeset, PR).
|
|
159
|
-
- [`SECURITY.md`](SECURITY.md#supported-versions)
|
|
175
|
+
- [`SECURITY.md`](SECURITY.md#supported-versions): which versions get
|
|
160
176
|
security fixes.
|