@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/ADOPTION.md
CHANGED
|
@@ -1,144 +1,126 @@
|
|
|
1
|
-
# Adoption guide
|
|
1
|
+
# Adoption guide
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
architect, or security reviewer evaluate `env-cap` for adoption at
|
|
5
|
-
organizational scale without having to reconstruct the picture from
|
|
6
|
-
`SECURITY.md`, `specs/architecture.md`, the ADRs in `specs/decisions/`, and six migration
|
|
7
|
-
guides scattered across the repository tree. Everything here links back to
|
|
8
|
-
the primary source it summarizes — nothing here is a new claim.
|
|
3
|
+
Adopting `env-cap` costs a build step and a declaration per variable; it needs Node 22 and npm. The sections below list each cost, need and refusal, with the check behind it.
|
|
9
4
|
|
|
10
5
|
## What problem this solves
|
|
11
6
|
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
7
|
+
Validation libraries answer one question: is this value well-formed? They do not say which team owns `STRIPE_WEBHOOK_SECRET`, what breaks if it disappears, or whether anything still reads it. `env-cap` lets each feature or package declare the variables it reads in a contract. A build-time analysis then reports owners, expiry dates and declared variables that nothing reads.
|
|
8
|
+
|
|
9
|
+
[`specs/migrations/README.md`](specs/migrations/README.md) compares it with each tool you may have, and says when not to switch.
|
|
10
|
+
|
|
11
|
+
## What it costs
|
|
12
|
+
|
|
13
|
+
| Cost | Detail |
|
|
14
|
+
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
|
|
15
|
+
| A build step | The CLI or a script runs in development and CI to write the manifest your startup code imports |
|
|
16
|
+
| A declaration per variable | `createEnv()` for validation and `documentEnv()` for owners and dates. Reports are only as accurate as these declarations |
|
|
17
|
+
| Committed generated files | The manifest and the evidence file are committed, so changes show up as reviewable diffs |
|
|
18
|
+
| Install weight | A TypeScript 6 compiler, bundled in the tarball and used only by the build entry ([details](#bundle-size-and-performance)) |
|
|
19
|
+
| Runtime weight | The runtime entry stays under 3 KB gzip, helpers under 4 KB and evidence under 3 KB, enforced by the `Size` check |
|
|
20
|
+
| Pre-1.0 churn | A minor release may break the Stable tier before 1.0 ([versioning](#versioning-stability-and-long-term-support)) |
|
|
21
|
+
|
|
22
|
+
## What it needs
|
|
23
|
+
|
|
24
|
+
- Node.js `>=22`. CI tests 22 and 24 in blocking jobs.
|
|
25
|
+
- npm. pnpm, Yarn 1 and Yarn Berry are tested only for installing the tarball and importing every entry. `required` waits for that job (`package-managers`), so a failure blocks a merge.
|
|
26
|
+
- TypeScript `moduleResolution` set to `node16`, `nodenext` or `bundler` if you type-check against the subpath exports.
|
|
27
|
+
- Your own TypeScript is optional. The build entry uses it when it is version 5 or 6, and the bundled TypeScript 6 otherwise.
|
|
28
|
+
- Schemas written as static object literals. 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.
|
|
29
|
+
|
|
30
|
+
## What it refuses to do
|
|
31
|
+
|
|
32
|
+
| It will not | Enforced by | Limit |
|
|
33
|
+
| ------------------------------------------------------------ | --------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
|
|
34
|
+
| Load `.env` files or store, fetch or rotate secrets | No such code exists; keep `dotenv` and your secret manager | Not a check |
|
|
35
|
+
| Run your schema files during analysis | `test/build/parse.test.ts`: a throwing top-level statement never runs | Lint does not ban `import()` or `vm` in `src/build`; review covers that |
|
|
36
|
+
| Touch the filesystem from the runtime | Lint, and the `AmbientCapabilities` scan of the packed tarball | The scan is textual and skips bundled dependencies |
|
|
37
|
+
| Read `process.env` in the runtime | The `AmbientCapabilities` scan and the browser-bundle test | Textual; an indirect reference would evade both |
|
|
38
|
+
| Put a value in an error message | `test/runtime/validate.test.ts` | Your own validator or processor message is passed through |
|
|
39
|
+
| Guess a value it cannot resolve statically | `test/build/parse.test.ts`, `test/build/literal-eval.test.ts` | None found |
|
|
40
|
+
| Walk `node_modules` during discovery | `test/build/discover.test.ts` | Packages you list in `packages` are read, one file each |
|
|
41
|
+
| Fail a run on documentation or ownership findings by default | `test/cli/main.test.ts`, `test/build/generate-env-artifacts.test.ts` | Exclusive-group violations and conflicting explicit processor types always fail |
|
|
24
42
|
|
|
25
43
|
## Security & threat model
|
|
26
44
|
|
|
27
|
-
Full detail
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
- **The
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
- **TypeScript path-alias resolution (ADR 0023) never crosses
|
|
59
|
-
into `node_modules`.** Unlike cross-package discovery, this mechanism is on
|
|
60
|
-
by default (a project's own `tsconfig.json` never crosses a
|
|
61
|
-
trust/versioning boundary the way an installed package does), but the
|
|
62
|
-
boundary between the two stays strict: any resolution landing inside
|
|
63
|
-
`node_modules` is discarded, so bare package specifiers remain exclusively
|
|
64
|
-
governed by the explicit `packages` allowlist above — see
|
|
65
|
-
[ADR 0023](specs/decisions/0023-tsconfig-path-alias-resolution.md).
|
|
66
|
-
- **Supply-chain posture:** dependency-free at runtime; CI enforces
|
|
67
|
-
typecheck, lint, tests with coverage thresholds, cross-runtime conformance
|
|
68
|
-
(Node/Bun/Deno), and a hard gzip size budget on every change; releases
|
|
69
|
-
publish via npm's OIDC trusted publishing (no long-lived `NPM_TOKEN`) with
|
|
70
|
-
provenance attestation, so a consumer can verify a published artifact was
|
|
71
|
-
built by this repository's own CI, not a maintainer's laptop.
|
|
45
|
+
Full detail is in [`SECURITY.md`](SECURITY.md). The summary a reviewer needs:
|
|
46
|
+
|
|
47
|
+
- **The runtime imports no Node module.** The browser-bundle test rejects a `node:` import, a Node built-in `require`, `process.` or `Buffer.` in the bundle. It does not fail on a third-party import, which would be bundled silently.
|
|
48
|
+
- **The compiler stays out of the runtime.** `internal-package-contract tool compiler-isolation` fails the build if any runtime entry can reach the bundled compiler ([ADR 0049](specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md)). It reads the static import graph of `dist/` only.
|
|
49
|
+
- **Contracts redact themselves** under `console.log`, `String()`, `JSON.stringify` and template interpolation (`test/runtime/create.test.ts`, [ADR 0006](specs/decisions/0006-self-redacting-contracts.md)). Spreading a contract reads every value.
|
|
50
|
+
- **Cross-package discovery is opt-in.** It reads only packages you name, one `package.json` and one declared file each. It rejects symlink escapes and oversized files ([ADR 0014](specs/decisions/0014-cross-package-schema-discovery.md)).
|
|
51
|
+
- **Path-alias resolution never lands in `node_modules`.** It is on by default, and any result inside `node_modules` is discarded ([ADR 0023](specs/decisions/0023-tsconfig-path-alias-resolution.md)).
|
|
52
|
+
- **No outbound network in env-cap's own code.** The `ipc/no-network` lint rule covers `src/`. It does not cover the bundled TypeScript compiler, which Socket flags for network access.
|
|
53
|
+
|
|
54
|
+
What installing the package adds, generated from `package.json` and `docs/surface.json`:
|
|
55
|
+
|
|
56
|
+
<!-- ipc:begin dependencies -->
|
|
57
|
+
|
|
58
|
+
Installing `@maverickcer/env-cap` installs 1 package directly, and whatever it depends on. It names 3 optional peers, which you install yourself when you use the part that needs them.
|
|
59
|
+
|
|
60
|
+
| Package | Kind | Range | Why |
|
|
61
|
+
| -------------------------- | ------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
62
|
+
| `@typescript/typescript6` | dependency | `^6.0.2` | The TypeScript 6 compiler the build entry parses schemas with when the project's own TypeScript is 7 or missing (ADR 0049). Bundled inside the tarball. No runtime entry can reach it (`compiler-isolation`). |
|
|
63
|
+
| `@typescript-eslint/utils` | optional peer | `^8.0.0` | Only for `@maverickcer/env-cap/eslint-plugin`; projects linting TypeScript already have it through `typescript-eslint`. |
|
|
64
|
+
| `eslint` | optional peer | `^8.57.0 \|\| ^9.0.0 \|\| ^10.0.0` | Only for `@maverickcer/env-cap/eslint-plugin`, which runs inside the project's own ESLint. CI runs the rules on ESLint 10 only. |
|
|
65
|
+
| `typescript` | optional peer | `^5.0.0 \|\| ^6.0.0 \|\| ^7.0.0` | The project's own compiler, used by the build entry instead of `@typescript/typescript6` when it is version 5 or 6. CI tests the newest 5.x, 6.x and 7.x, not the 5.0 floor. |
|
|
66
|
+
|
|
67
|
+
<!-- ipc:end dependencies -->
|
|
68
|
+
|
|
69
|
+
**Supply chain.** A merge to `main` requires a pull request, resolved review threads, and the `contract`, `lint` and `required` checks. The ruleset enforces that. The `BranchProtection` check fails if the ruleset stops requiring `contract` or `required`, or stops requiring resolved threads; it does not check `lint`. Admins can bypass, and no approving review is required. These gates run in the `contract` job:
|
|
70
|
+
|
|
71
|
+
- Typecheck, lint, tests with coverage floors, zero surviving mutants, and size budgets.
|
|
72
|
+
- Production dependency licences, `npm audit` and Socket alerts, each with a reviewed record when accepted.
|
|
73
|
+
- An install-and-import of the packed tarball, for every entry except `./eslint-plugin`.
|
|
74
|
+
|
|
75
|
+
Releases publish from CI over npm OIDC with a provenance attestation, so you can check that a version was built by this repository's workflow. The Bun and Deno runs, the examples and the package-manager smoke test run in CI. The required `required` check fails when any of them fails.
|
|
72
76
|
|
|
73
77
|
## Versioning, stability, and long-term support
|
|
74
78
|
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
shape before being promoted -- nothing currently ships under this tier), and
|
|
81
|
-
**Private** (internal implementation, never covered) — is what the eventual
|
|
82
|
-
1.0 stability promise will cover.
|
|
83
|
-
|
|
84
|
-
**The honest gap or long-term support question, answered directly:**
|
|
85
|
-
`env-cap` has not reached a 1.0 release, and today, per `SECURITY.md`,
|
|
86
|
-
security fixes target the latest published `0.x` version only — there is
|
|
87
|
-
no backport branch yet. **Starting at `1.0`**, `SECURITY.md` commits to
|
|
88
|
-
backporting security fixes to the latest minor release of the previous
|
|
89
|
-
major version for a minimum of six months after a new major ships (a
|
|
90
|
-
window that can be extended, never shortened, once stated). An
|
|
91
|
-
organization with a hard LTS/backport requirement today should treat the
|
|
92
|
-
_current_ state as a real limitation — the `1.0` commitment is a forward
|
|
93
|
-
policy, not something already exercised in production. It is offset by the
|
|
94
|
-
same two structural factors as before: zero runtime dependencies, and a
|
|
95
|
-
fully automated, OIDC-attested release pipeline plus documented governance
|
|
96
|
-
that lower the bar for a successor maintainer or fork.
|
|
79
|
+
[`VERSIONING.md`](VERSIONING.md) lists every entry point and its tier. Every entry point is Stable today, and nothing ships as Experimental ([ADR 0045](specs/decisions/0045-promote-experimental-surfaces-to-stable.md)). The `ApiContract` and `SurfaceContract` checks diff the public surface against committed baselines and require a changeset at the matching level. Before 1.0, a breaking change needs only a minor release.
|
|
80
|
+
|
|
81
|
+
**Long-term support, stated plainly.** env-cap has not reached 1.0. Security fixes target the latest `0.x` only, and there is no backport branch. From 1.0, [`SECURITY.md`](SECURITY.md#supported-versions) commits to backporting security fixes to the previous major's latest minor for at least six months. That is a policy for a future release line; it has not been exercised. An organization with a backport requirement today should treat this as a real limitation.
|
|
82
|
+
|
|
83
|
+
Releases are automated after a person merges the release pull request ([RELEASING.md](RELEASING.md)). Commit-generated bumps stop below 1.0.0. Crossing it takes a hand-written `major` changeset, and the workflow only posts a notice when its release pull request is opened.
|
|
97
84
|
|
|
98
85
|
## Bundle size and performance
|
|
99
86
|
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
output with esbuild and asserts unused exports are actually tree-shaken, not
|
|
106
|
-
just assumed to be.
|
|
87
|
+
| Entry point | Gzip budget | Enforced by |
|
|
88
|
+
| ------------- | ----------- | ------------------------------------------------------------------------ |
|
|
89
|
+
| `.` (runtime) | 3 KB | The `Size` check in `contract`, and the release build's `npm run verify` |
|
|
90
|
+
| `./helpers` | 4 KB | The same |
|
|
91
|
+
| `./evidence` | 3 KB | The same |
|
|
107
92
|
|
|
108
|
-
|
|
93
|
+
Each budget measures the entry's own file, not your bundle. The release publishes with `--ignore-scripts`, so the budget blocks through those two steps, not `prepublishOnly` ([ADR 0008](specs/decisions/0008-gzip-size-budget.md)).
|
|
109
94
|
|
|
110
|
-
|
|
111
|
-
that might silently change:
|
|
95
|
+
`sideEffects: false` is set, and a test bundles the real `dist/helpers.js` with esbuild to check that unused helpers are dropped (`test/helpers/tree-shaking.test.ts`). Other bundlers are not tested.
|
|
112
96
|
|
|
113
|
-
|
|
114
|
-
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
115
|
-
| No global `env` object — only per-capability contracts | Prevents the "one giant schema file nobody owns" failure mode this package exists to solve | [0003](specs/decisions/0003-no-global-env-object.md) |
|
|
116
|
-
| One runtime, no `/client`/`/server` split | Works identically in Node, browser, edge, and serverless — no framework-specific build variant to maintain | [0004](specs/decisions/0004-no-client-server-package-split.md) |
|
|
117
|
-
| Warn, not throw, by default | Adopting incrementally in a large codebase doesn't require fixing every finding on day one. `--strict-docs`/`--strict-ownership` opt into a stricter CI gate one family at a time, or `--strict` escalates all three provable-error families (compatibility, documentation, ownership) at once once a team is ready (ADR 0044). Nothing throws until a team opts in | [0005](specs/decisions/0005-warn-not-throw-by-default.md), [0038](specs/decisions/0038-always-computed-evidence-model-backs-generate-check-docs.md), [0044](specs/decisions/0044-strict-escalates-every-warning-family.md) |
|
|
118
|
-
| Exclusive-group violations are always hard errors | A safety guarantee (e.g. "never activate two database backends at once") that can't be silently downgraded to a warning by a lenient CI setting | [0009](specs/decisions/0009-exclusive-groups-are-always-errors.md) |
|
|
119
|
-
| `--json` output is a versioned, additive-only wire contract | Safe to build dashboards/CI integrations against; a `schemaVersion` bump is the only breaking-change signal to watch for | [0013](specs/decisions/0013-json-output-is-a-versioned-mirror.md) |
|
|
97
|
+
The install includes the bundled TypeScript 6 compiler. No check measures its size, so run `npm pack --dry-run` on the version you evaluate. Only the build entry loads it, in development and CI.
|
|
120
98
|
|
|
121
|
-
|
|
99
|
+
## Architectural decisions worth knowing before you adopt
|
|
100
|
+
|
|
101
|
+
| Decision | What it means for you | ADR |
|
|
102
|
+
| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
|
|
103
|
+
| No global `env` object | Each feature reads only the contract it owns | [0003](specs/decisions/0003-no-global-env-object.md) |
|
|
104
|
+
| One runtime, no `/client` or `/server` split | The same runtime entry serves server and browser code. Browser use is tested in a Web-globals VM, not a real browser | [0004](specs/decisions/0004-no-client-server-package-split.md) |
|
|
105
|
+
| Warn, not throw, by default | No documentation or ownership finding fails a run until a team passes a `--strict*` flag | [0005](specs/decisions/0005-warn-not-throw-by-default.md), [0044](specs/decisions/0044-strict-escalates-every-warning-family.md) |
|
|
106
|
+
| Exclusive-group violations are always errors | Two active contracts in one exclusive group fail the build, whatever the flags | [0009](specs/decisions/0009-exclusive-groups-are-always-errors.md) |
|
|
107
|
+
| `--json` output is versioned and additive | New fields can appear in any release. A removed, retyped or newly optional field must bump `schemaVersion`; `test/build/schema-version-bump.test.ts` fails otherwise | [0013](specs/decisions/0013-json-output-is-a-versioned-mirror.md) |
|
|
108
|
+
|
|
109
|
+
The full list is in [`specs/architecture.md`](specs/architecture.md).
|
|
122
110
|
|
|
123
111
|
## Migration cost from what you likely have today
|
|
124
112
|
|
|
125
|
-
| Coming from | Migration guide | One-line take
|
|
126
|
-
| -------------------------------- | ------------------------------------------------------------------------- |
|
|
127
|
-
| Raw `process.env` | [from-process-env.md](specs/migrations/from-process-env.md) |
|
|
128
|
-
| `dotenv` | [from-dotenv.md](specs/migrations/from-dotenv.md) | `dotenv` still loads `.env` files; `env-cap` validates and documents what
|
|
129
|
-
| `zod`-based validation | [from-zod.md](specs/migrations/from-zod.md) | Keep Zod
|
|
130
|
-
| `envalid` | [from-envalid.md](specs/migrations/from-envalid.md) | Similar validation
|
|
131
|
-
| `t3-env` | [from-t3-env.md](specs/migrations/from-t3-env.md) | Both are type-safe; `t3-env` centralizes
|
|
132
|
-
| A hand-rolled centralized schema | [from-centralized-schema.md](specs/migrations/from-centralized-schema.md) | The
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
If you need something not covered here — a specific compliance framework
|
|
141
|
-
mapping, a formal SLA, or an LTS commitment beyond what `SECURITY.md`
|
|
142
|
-
states — that is a real gap today, not an oversight in this document. Open
|
|
143
|
-
an issue or reach the maintainer through the channels in `SECURITY.md`
|
|
144
|
-
rather than assuming an answer either way.
|
|
113
|
+
| Coming from | Migration guide | One-line take |
|
|
114
|
+
| -------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
|
|
115
|
+
| Raw `process.env` | [from-process-env.md](specs/migrations/from-process-env.md) | The lowest-friction start; adds validation and ownership where there was none |
|
|
116
|
+
| `dotenv` | [from-dotenv.md](specs/migrations/from-dotenv.md) | `dotenv` still loads `.env` files; `env-cap` validates and documents what is in them |
|
|
117
|
+
| `zod`-based validation | [from-zod.md](specs/migrations/from-zod.md) | Keep Zod; adopt `env-cap` only if ownership, not validation, is the pain |
|
|
118
|
+
| `envalid` | [from-envalid.md](specs/migrations/from-envalid.md) | Similar validation; the difference is per-feature ownership |
|
|
119
|
+
| `t3-env` | [from-t3-env.md](specs/migrations/from-t3-env.md) | Both are type-safe; `t3-env` centralizes and `env-cap` does not |
|
|
120
|
+
| A hand-rolled centralized schema | [from-centralized-schema.md](specs/migrations/from-centralized-schema.md) | The closest fit for what this package changes |
|
|
121
|
+
|
|
122
|
+
Each guide has a section on when to keep what you have.
|
|
123
|
+
|
|
124
|
+
## Questions this document does not answer
|
|
125
|
+
|
|
126
|
+
There is no formal SLA, and no support commitment beyond [`SUPPORT.md`](SUPPORT.md) and [`SECURITY.md`](SECURITY.md). The generated documents support a review; they do not establish that any standard is met. Open an issue if you need something this document does not cover.
|
package/AGENTS.md
CHANGED
|
@@ -1,146 +1,112 @@
|
|
|
1
1
|
# AGENTS.md
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
`env-cap
|
|
6
|
-
|
|
7
|
-
instead if your tooling supports it; this file is a self-contained distillation for
|
|
8
|
-
agents that don't.
|
|
3
|
+
Rules for coding agents working with `env-cap`, both in an application that uses it and in this
|
|
4
|
+
repository's own source. If your tooling loads skill files, load
|
|
5
|
+
[`skills/env-cap/SKILL.md`](skills/env-cap/SKILL.md) instead: it is the fuller version of the
|
|
6
|
+
application rules, generated from the package.
|
|
9
7
|
|
|
10
8
|
## What this package is
|
|
11
9
|
|
|
12
|
-
`env-cap
|
|
13
|
-
|
|
14
|
-
and
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
3.
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
-
|
|
73
|
-
|
|
74
|
-
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
`console.log(paymentsEnv)` is safe by design, but `{...paymentsEnv}` triggers every
|
|
78
|
-
getter and produces a plain object with every real value.
|
|
79
|
-
- Manually constructing a contract collection when a generated manifest is available —
|
|
80
|
-
regenerate it instead: run the project's `generate:env` script if one exists, or call
|
|
81
|
-
`generateEnvManifest({ location: "src/generated/env.manifest.ts" })` from
|
|
82
|
-
`@maverickcer/env-cap/build`, or run `npx env-cap --location
|
|
83
|
-
src/generated/env.manifest.ts` from the CLI. Never hand-assemble the collection it
|
|
84
|
-
produces.
|
|
85
|
-
- Validation managers, service locators, providers, registries, or other initialization
|
|
86
|
-
frameworks around `validateEnv()` — call it directly from the application's existing
|
|
87
|
-
startup path.
|
|
88
|
-
|
|
89
|
-
## Migrating an existing app onto env-cap
|
|
90
|
-
|
|
91
|
-
- Generated manifests are meant to be consumed by `validateEnv()` at runtime, and
|
|
92
|
-
generated artifacts (manifest, docs, `.env.example`, ownership report) are meant to be
|
|
93
|
-
consumed by tooling — prefer them over anything manually maintained, and treat them as
|
|
94
|
-
the source of truth.
|
|
95
|
-
- To generate a manifest: check for an existing `generate:env` (or similarly named) npm
|
|
96
|
-
script first and run that. If none exists, either call
|
|
97
|
-
`generateEnvManifest({ location: "src/generated/env.manifest.ts" })` (import from
|
|
98
|
-
`@maverickcer/env-cap/build`) from a build script, or run the CLI directly —
|
|
99
|
-
`npx env-cap --location src/generated/env.manifest.ts` (add `--evidence`, `--strict`,
|
|
100
|
-
etc. as needed; see the Public API map and `skills/env-cap/SKILL.md` for the full option
|
|
101
|
-
set). `--docs`/`--ownership`/`--env-example` are not CLI flags — the documentation
|
|
102
|
-
catalog, `.env.example`, and dependency-ownership report have no runtime consumer, so
|
|
103
|
-
generating them is a `generateEnvArtifacts()`/`generateDocumentation()`/
|
|
104
|
-
`generateUsageReport()` call from a build script instead (see ADR 0046). Commit the
|
|
105
|
-
generated file only if the project already commits generated artifacts; otherwise wire
|
|
106
|
-
the command into CI.
|
|
107
|
-
- Prefer migrations that are small, reviewable PRs covering one capability at a time,
|
|
108
|
-
preserve existing validation and runtime behavior, and avoid new infrastructure unless
|
|
109
|
-
it's actually required. See [`specs/migrations/`](specs/migrations/) for guide-by-guide
|
|
110
|
-
detail.
|
|
10
|
+
In `env-cap`, each feature (a folder or an installable package; the docs also call it a
|
|
11
|
+
capability) declares its environment variables in a **contract**: a static schema object passed to
|
|
12
|
+
`createEnv()` and `documentEnv()`. The application validates every contract once at startup. A build
|
|
13
|
+
step reads the contracts as source and writes the manifest, docs, `.env.example` and ownership
|
|
14
|
+
report. Values are always read through the contract that owns them.
|
|
15
|
+
|
|
16
|
+
## Contract rules
|
|
17
|
+
|
|
18
|
+
1. **Schemas are static literals, read as source.** The build entry (`@maverickcer/env-cap/build`)
|
|
19
|
+
parses `env.schema.ts` files as TypeScript syntax trees and never runs them. Only literal
|
|
20
|
+
expressions resolve. A spread, a factory call or a re-export resolves as "unknown" and surfaces
|
|
21
|
+
as a warning. So declare each schema as a literal object in the module that owns it, and pass
|
|
22
|
+
that one binding to `createEnv()` and `documentEnv()`.
|
|
23
|
+
2. **Each contract belongs to the module that declares it.** That module exports it (`paymentsEnv`,
|
|
24
|
+
`databaseEnv`), and code reads `paymentsEnv.STRIPE_KEY` from it. Keep contracts separate; a
|
|
25
|
+
merged or global env object defeats ownership.
|
|
26
|
+
3. **`createEnv()` holds runtime fields; `documentEnv()` holds documentation.** `createEnv(schema,
|
|
27
|
+
options)` reads only `default`, `processor`, `validator` and `context`. `documentEnv(schema, docs)`
|
|
28
|
+
is an inert second call over the same object: it returns `void` and exists only as a build-time
|
|
29
|
+
marker. So `description`, `owner` and `expiresAt` go in `documentEnv()`. The field is `processor`;
|
|
30
|
+
the old name `transformer` has no alias.
|
|
31
|
+
4. **Import from the public entry points only.** They are listed in the
|
|
32
|
+
[Public API map](#public-api-map) below. Internal paths (`dist/*.cjs`, `src/**/*.ts`, the
|
|
33
|
+
dependency-graph engine in `src/build/dependency-graph.ts`) are not public.
|
|
34
|
+
5. **Runtime and build stay apart.** `src/runtime` imports no Node module, has no filesystem access
|
|
35
|
+
and is held to a 3 KB gzip budget (`npm run size`). `src/build` uses `node:path` and
|
|
36
|
+
`typescript`, and takes a `BuildFileSystem` from its caller. Only `src/cli` imports `node:fs`
|
|
37
|
+
(ADR 0040). Runtime and browser code import neither `./build` nor `./node`.
|
|
38
|
+
6. **Errors and logs carry names, not values.** `console.log(paymentsEnv)` prints only
|
|
39
|
+
`EnvContract("payments") { N variable(s) }`. Validation errors are built from the variable name,
|
|
40
|
+
the contract name and source, the failure kind and your own message. Write processor and
|
|
41
|
+
validator messages that describe the expected shape without quoting the value. To inspect a
|
|
42
|
+
contract, log it; spreading it or calling `Object.entries()` on it reads every real value.
|
|
43
|
+
7. **`context` filters which variables take part in validation.** A schema entry may set
|
|
44
|
+
`context: "server"` or any application-defined string. `validateEnv({ activeContexts })` skips a
|
|
45
|
+
variable whose `context` is not listed: no default, processor or validator runs, and reading it
|
|
46
|
+
throws `EnvNotReadyError`. The application computes `activeContexts` and passes it explicitly;
|
|
47
|
+
the package never infers it. `context` is neither an access control nor a bundling boundary: a
|
|
48
|
+
client bundle that imports a manifest ships every definition in it. To keep a variable out of
|
|
49
|
+
client code, give it its own discovery run and manifest
|
|
50
|
+
([ADR 0004](specs/decisions/0004-no-client-server-package-split.md),
|
|
51
|
+
[ADR 0022](specs/decisions/0022-validation-contexts.md)).
|
|
52
|
+
|
|
53
|
+
## In an application
|
|
54
|
+
|
|
55
|
+
- Call `validateEnv()` once, directly from the application's existing startup path, before any
|
|
56
|
+
contract is read. Reading earlier throws `EnvNotReadyError`. Wrappers such as validation managers,
|
|
57
|
+
service locators or registries add nothing.
|
|
58
|
+
- Run the `generate*()` functions from an npm script or CI step; they are build-time only.
|
|
59
|
+
- Treat generated files as the source of truth. To change one, change its contract and regenerate
|
|
60
|
+
it, in this order of preference:
|
|
61
|
+
1. the project's `generate:env` script (or a similarly named one), if it exists;
|
|
62
|
+
2. `generateEnvManifest({ location: "src/generated/env.manifest.ts" })` from
|
|
63
|
+
`@maverickcer/env-cap/build`, called in a build script;
|
|
64
|
+
3. `npx env-cap --location src/generated/env.manifest.ts`, adding `--evidence` or `--strict` as
|
|
65
|
+
needed (`npx env-cap --help` lists every flag).
|
|
66
|
+
- The CLI writes only the manifest and the evidence file. The docs catalog, `.env.example` and the
|
|
67
|
+
ownership report come from `generateEnvArtifacts()`, `generateDocumentation()` or
|
|
68
|
+
`generateUsageReport()` in a build script (ADR 0046). There are no `--docs`, `--ownership` or
|
|
69
|
+
`--env-example` flags.
|
|
70
|
+
- Commit generated files only if the project already commits generated files; otherwise wire the
|
|
71
|
+
command into CI.
|
|
72
|
+
- Migrate one feature per pull request, keep its validation and runtime behavior unchanged, and
|
|
73
|
+
add infrastructure only when the migration needs it. [`specs/migrations/`](specs/migrations/) has
|
|
74
|
+
a guide per starting point (`dotenv`, a central schema, Zod, envalid, t3-env).
|
|
111
75
|
|
|
112
76
|
## Public API map
|
|
113
77
|
|
|
114
78
|
<!-- ipc:begin entry-points -->
|
|
115
79
|
|
|
116
|
-
| Export | Source | Environment
|
|
117
|
-
| ------------------------------------ | -------------------- |
|
|
118
|
-
| `@maverickcer/env-cap` | `src/runtime/` |
|
|
119
|
-
| `@maverickcer/env-cap/build` | `src/build/` | Node
|
|
120
|
-
| `@maverickcer/env-cap/helpers` | `src/helpers/` |
|
|
121
|
-
| `@maverickcer/env-cap/node` | `src/node/` | Node
|
|
122
|
-
| `@maverickcer/env-cap/evidence` | `src/evidence/` |
|
|
123
|
-
| `@maverickcer/env-cap/eslint-plugin` | `src/eslint-plugin/` | Node
|
|
124
|
-
| `@maverickcer/env-cap/schema` | `schemas/` |
|
|
80
|
+
| Export | Source | Environment | Tier | Purpose |
|
|
81
|
+
| ------------------------------------ | -------------------- | ------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
82
|
+
| `@maverickcer/env-cap` | `src/runtime/` | No Node module or Node global | Stable | `createEnv`, `documentEnv`, `validateEnv`, `resetEnvCache`, `isEnvContract` and the error types |
|
|
83
|
+
| `@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`). |
|
|
84
|
+
| `@maverickcer/env-cap/helpers` | `src/helpers/` | No Node module; `processors.base64()` returns a Node `Buffer` | Stable | `processors` and `validators` |
|
|
85
|
+
| `@maverickcer/env-cap/node` | `src/node/` | Node only, in development and CI | Stable | `nodeBuildFileSystem`, the `BuildFileSystem` adapter a build script hands to `./build` |
|
|
86
|
+
| `@maverickcer/env-cap/evidence` | `src/evidence/` | No Node module or Node global | Stable | `defineEvidenceProjection`, pure transforms over the Evidence Model (Stable, see `VERSIONING.md`) |
|
|
87
|
+
| `@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 |
|
|
88
|
+
| `@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/*` |
|
|
125
89
|
|
|
126
90
|
<!-- ipc:end entry-points -->
|
|
127
91
|
|
|
128
92
|
## Before finishing a change
|
|
129
93
|
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
94
|
+
Each step is done when its command exits 0 or its condition holds.
|
|
95
|
+
|
|
96
|
+
1. `npm run typecheck` and `npm test` pass.
|
|
97
|
+
2. If `src/runtime`, `src/helpers` or `src/evidence` changed, `npm run size` passes.
|
|
98
|
+
3. If a public export changed, the change is intended; otherwise the export is restored.
|
|
99
|
+
4. If an `env.schema.ts` changed, its `documentEnv()` entry matches, and the generated files are
|
|
100
|
+
regenerated by the project's `generate:env` script.
|
|
101
|
+
5. Every generated file was regenerated, not edited. A generated file starts with a comment that
|
|
102
|
+
says `GENERATED FILE -- do not edit by hand`, or, for `.env.example`, with the line
|
|
103
|
+
`# AUTO-GENERATED EXAMPLE FILE.`.
|
|
104
|
+
6. No secret or raw environment value appears in a thrown error message, a log or a committed
|
|
105
|
+
example file.
|
|
139
106
|
|
|
140
107
|
## Full reference
|
|
141
108
|
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
[
|
|
146
|
-
[`skills/env-cap/SKILL.md`](skills/env-cap/SKILL.md).
|
|
109
|
+
- Why the architecture is shaped this way: [`specs/architecture.md`](specs/architecture.md).
|
|
110
|
+
- Why a specific rule exists: [`specs/decisions/`](specs/decisions/).
|
|
111
|
+
- Moving an existing application onto env-cap: [`specs/migrations/`](specs/migrations/).
|
|
112
|
+
- Every option of the generators and the CLI: [GUIDE.md](GUIDE.md).
|