@maverickcer/env-cap 0.7.3 → 0.7.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/ADOPTION.md +106 -124
- package/AGENTS.md +14 -13
- package/CHANGELOG.md +23 -0
- package/CODE_REVIEW.md +69 -173
- package/CONTRIBUTING.md +57 -74
- package/GUIDE.md +393 -872
- package/README.md +82 -77
- package/RELEASING.md +17 -15
- package/SECURITY.md +76 -227
- package/SUPPORT.md +21 -45
- package/VERSIONING.md +68 -105
- package/benchmarks/READING-BENCHMARKS.md +13 -7
- package/benchmarks/WRITING-BENCHMARKS.md +1 -1
- package/dist/.dts/_ipc/build-fs.d.ts +9 -14
- 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.map +1 -1
- package/dist/.dts/_ipc/generated-banner.d.ts +8 -8
- package/dist/.dts/_ipc/glob.d.ts +6 -6
- package/dist/.dts/_ipc/no-node-fs.d.ts +0 -14
- package/dist/.dts/_ipc/no-node-fs.d.ts.map +1 -1
- package/dist/.dts/build/lifecycle-model.d.ts +8 -3
- package/dist/.dts/build/lifecycle-model.d.ts.map +1 -1
- package/dist/.dts/build/sarif.d.ts.map +1 -1
- package/dist/.dts/helpers/index.d.ts +1 -1
- package/dist/.dts/runtime/create.d.ts +3 -0
- package/dist/.dts/runtime/create.d.ts.map +1 -1
- package/dist/.dts/runtime/document.d.ts +7 -4
- package/dist/.dts/runtime/document.d.ts.map +1 -1
- package/dist/.dts/runtime/index.d.ts +11 -10
- package/dist/.dts/runtime/index.d.ts.map +1 -1
- package/dist/.dts/runtime/types.d.ts +16 -0
- package/dist/.dts/runtime/types.d.ts.map +1 -1
- package/dist/.dts/runtime/validate.d.ts +14 -1
- 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 +22 -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 +47 -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 +62 -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 +170 -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 +176 -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 +148 -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 +101 -0
- package/dist/.dts7/build/generate-manifest.d.ts.map +1 -0
- package/dist/.dts7/build/generate-usage.d.ts +95 -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 +105 -0
- package/dist/.dts7/build/index.d.ts.map +1 -0
- package/dist/.dts7/build/lifecycle-model.d.ts +179 -0
- package/dist/.dts7/build/lifecycle-model.d.ts.map +1 -0
- package/dist/.dts7/build/link.d.ts +223 -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 +47 -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 +35 -0
- package/dist/.dts7/build/merge-documentation.d.ts.map +1 -0
- package/dist/.dts7/build/ownership-model.d.ts +59 -0
- package/dist/.dts7/build/ownership-model.d.ts.map +1 -0
- package/dist/.dts7/build/parse.d.ts +207 -0
- package/dist/.dts7/build/parse.d.ts.map +1 -0
- package/dist/.dts7/build/reference-projections.d.ts +170 -0
- package/dist/.dts7/build/reference-projections.d.ts.map +1 -0
- package/dist/.dts7/build/resolution/resolve-import.d.ts +58 -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 +70 -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 +27 -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 +52 -0
- package/dist/.dts7/evidence/define-projection.d.ts.map +1 -0
- package/dist/.dts7/evidence/index.d.ts +23 -0
- package/dist/.dts7/evidence/index.d.ts.map +1 -0
- package/dist/.dts7/helpers/index.d.ts +135 -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 +2 -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 +223 -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 +191 -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-LFHPVDQL.js → build-DNAYWD2B.js} +8 -5
- package/dist/build-DNAYWD2B.js.map +1 -0
- package/dist/build.cjs +7 -4
- package/dist/build.cjs.map +1 -1
- package/dist/build.js +7 -4
- 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-ZW3BLAPD.js → chunk-HAGMVMN5.js} +2 -2
- package/dist/cli/index.js +3 -3
- package/dist/eslint-plugin/index.cjs +8 -5
- package/dist/eslint-plugin/index.cjs.map +1 -1
- package/dist/eslint-plugin/index.js +8 -5
- 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.ts7.d.cts +1 -0
- package/dist/evidence.ts7.d.ts +1 -0
- 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 +37 -6
- package/schemas/env-cap-report.schema.json +1 -1
- package/skills/env-cap/SKILL.md +1 -1
- package/skills/env-cap/references/api.md +1 -1
- package/specs/architecture.md +2 -2
- 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 +14 -2
- package/dist/build-LFHPVDQL.js.map +0 -1
- /package/dist/{chunk-ZW3BLAPD.js.map → chunk-HAGMVMN5.js.map} +0 -0
package/GUIDE.md
CHANGED
|
@@ -1,73 +1,27 @@
|
|
|
1
1
|
# env-cap Guide
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
For the pitch, quick start, and adoption reasoning, see [README.md](README.md). For why the package is built the way it is, see [specs/architecture.md](specs/architecture.md) and the [ADRs](specs/decisions/).
|
|
6
|
-
|
|
7
|
-
- [Documented example](#documented-example)
|
|
8
|
-
- [Capability-owned contracts](#capability-owned-contracts)
|
|
9
|
-
- [Helpers](#helpers)
|
|
10
|
-
- [Core workflow](#core-workflow)
|
|
11
|
-
- [Runtime support matrix](#runtime-support-matrix)
|
|
12
|
-
- [Validation contexts](#validation-contexts)
|
|
13
|
-
- [Reusable packages](#reusable-packages)
|
|
14
|
-
- [TypeScript path aliases (paths/baseUrl)](#typescript-path-aliases-pathsbaseurl)
|
|
15
|
-
- [Architecture](#architecture)
|
|
16
|
-
- [Migration](#migration)
|
|
17
|
-
- [Security model](#security-model)
|
|
18
|
-
- [Troubleshooting](#troubleshooting)
|
|
19
|
-
- [CLI](#cli)
|
|
20
|
-
- [GitHub Action](#github-action)
|
|
21
|
-
- [ESLint plugin](#eslint-plugin)
|
|
22
|
-
- [Performance characteristics](#performance-characteristics)
|
|
23
|
-
|
|
24
|
-
## Documented example
|
|
25
|
-
|
|
26
|
-
Most applications start with a centralized environment configuration model:
|
|
3
|
+
Find your entry point in the table below; its section starts with the problem it solves and states each limit next to its promise. Snippets name the CI-run file they come from, or say they are illustrative.
|
|
27
4
|
|
|
28
|
-
|
|
29
|
-
// src/env.ts
|
|
30
|
-
|
|
31
|
-
import { createEnv } from "@maverickcer/env-cap"
|
|
32
|
-
|
|
33
|
-
const schema = {
|
|
34
|
-
DATABASE_URL: {
|
|
35
|
-
validator(value: string) {
|
|
36
|
-
return value.startsWith("postgres://") || "Expected a PostgreSQL connection string."
|
|
37
|
-
},
|
|
38
|
-
},
|
|
39
|
-
|
|
40
|
-
STRIPE_KEY: {
|
|
41
|
-
validator(value: string) {
|
|
42
|
-
return value.startsWith("sk_") || 'Expected a Stripe secret key starting with "sk_".'
|
|
43
|
-
},
|
|
44
|
-
},
|
|
5
|
+
For the overview and quick start, read [README.md](README.md). For the reasons behind the design, read [specs/architecture.md](specs/architecture.md) and the [ADRs](specs/decisions/).
|
|
45
6
|
|
|
46
|
-
|
|
47
|
-
validator(value: string) {
|
|
48
|
-
return value.startsWith("SG.") || "Expected a SendGrid API key."
|
|
49
|
-
},
|
|
50
|
-
},
|
|
51
|
-
}
|
|
52
|
-
|
|
53
|
-
export const env = createEnv(schema)
|
|
54
|
-
```
|
|
7
|
+
## Find your part
|
|
55
8
|
|
|
56
|
-
|
|
9
|
+
| You are | Entry point | Start at |
|
|
10
|
+
| -------------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------- |
|
|
11
|
+
| An application developer bitten by an undefined variable | `@maverickcer/env-cap` | [The runtime](#application-developers-the-runtime) |
|
|
12
|
+
| The same developer writing processors and validators | `@maverickcer/env-cap/helpers` | [Helpers](#application-developers-helpers) |
|
|
13
|
+
| A platform engineer who owns the CI pipeline | `@maverickcer/env-cap/build`, the CLI, the GitHub Action | [Generating artifacts](#platform-engineers-generating-artifacts) |
|
|
14
|
+
| A reviewer who needs an inventory of secrets and owners | `@maverickcer/env-cap/evidence` | [Evidence](#reviewers-evidence) |
|
|
15
|
+
| A build-script author on Node | `@maverickcer/env-cap/node` | [The Node adapter](#build-script-authors-the-node-adapter) |
|
|
16
|
+
| A lint owner | `@maverickcer/env-cap/eslint-plugin` | [ESLint plugin](#eslint-plugin) |
|
|
57
17
|
|
|
58
|
-
|
|
18
|
+
## Application developers: the runtime
|
|
59
19
|
|
|
60
|
-
|
|
61
|
-
- Can this variable be removed when a feature is removed?
|
|
62
|
-
- Who owns its rotation?
|
|
63
|
-
- Which service depends on this secret?
|
|
64
|
-
- Is this configuration still required?
|
|
20
|
+
**What it solves:** your application fails at startup with every bad variable's name, never its value, instead of crashing later in a request.
|
|
65
21
|
|
|
66
|
-
|
|
22
|
+
### Capability-owned contracts
|
|
67
23
|
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
Each capability defines its own environment requirements while the application can still generate a complete project-wide view.
|
|
24
|
+
Each feature declares the variables it owns, next to the validation it needs. This contract is illustrative. The contract CI runs is [`examples/application/src/env.ts`](https://github.com/MaverickCER/env-cap/blob/main/examples/application/src/env.ts).
|
|
71
25
|
|
|
72
26
|
```ts
|
|
73
27
|
// features/payments/env.schema.ts
|
|
@@ -82,138 +36,41 @@ const paymentsSchema = {
|
|
|
82
36
|
},
|
|
83
37
|
}
|
|
84
38
|
|
|
85
|
-
export const paymentsEnv = createEnv(paymentsSchema, {
|
|
86
|
-
name: "payments",
|
|
87
|
-
})
|
|
39
|
+
export const paymentsEnv = createEnv(paymentsSchema, { name: "payments" })
|
|
88
40
|
|
|
89
41
|
documentEnv(paymentsSchema, {
|
|
90
42
|
category: "Payments",
|
|
91
43
|
owner: "payments-team",
|
|
92
|
-
metadata: {
|
|
93
|
-
service: "Payment Processing API",
|
|
94
|
-
criticality: "Production-critical",
|
|
95
|
-
},
|
|
96
44
|
variables: {
|
|
97
45
|
STRIPE_KEY: {
|
|
98
|
-
description:
|
|
99
|
-
"Stripe secret API key used by the payment service to create charges and process refunds.",
|
|
46
|
+
description: "Stripe secret key used to create charges and process refunds.",
|
|
100
47
|
owner: "payments-team",
|
|
101
48
|
expiresAt: "2027-01-01",
|
|
102
|
-
refreshInstructions: "Rotate in AWS Secrets Manager, then redeploy.
|
|
49
|
+
refreshInstructions: "Rotate in AWS Secrets Manager, then redeploy.",
|
|
103
50
|
sensitivity: "secret",
|
|
104
|
-
metadata: {
|
|
105
|
-
storageProvider: "AWS Secrets Manager",
|
|
106
|
-
accessPolicy: "Restricted to payment service runtime credentials.",
|
|
107
|
-
validationReason:
|
|
108
|
-
"Ensures the payment service cannot start with missing or malformed Stripe credentials.",
|
|
109
|
-
},
|
|
110
51
|
},
|
|
111
52
|
},
|
|
112
53
|
})
|
|
113
54
|
```
|
|
114
55
|
|
|
115
|
-
|
|
56
|
+
`createEnv()` takes what validation needs: `default`, `processor`, `validator` and `context`. `documentEnv()` takes what people need: owners, descriptions and expiry dates. `documentEnv()` has no runtime effect (`test/runtime/document.test.ts`), but its literals ship in any bundle that imports the file.
|
|
116
57
|
|
|
117
|
-
|
|
118
|
-
await validateEnv({
|
|
119
|
-
manifest,
|
|
120
|
-
values: process.env,
|
|
121
|
-
})
|
|
122
|
-
```
|
|
123
|
-
|
|
124
|
-
But ownership follows usage:
|
|
58
|
+
There is no global `env` object. Code reads a value through the contract that owns it:
|
|
125
59
|
|
|
126
60
|
```ts
|
|
127
61
|
paymentsEnv.STRIPE_KEY
|
|
128
62
|
```
|
|
129
63
|
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
```ts
|
|
133
|
-
env.payments.STRIPE_KEY
|
|
134
|
-
```
|
|
135
|
-
|
|
136
|
-
Instead, each capability exposes only the configuration it owns.
|
|
137
|
-
|
|
138
|
-
At application startup, `validateEnv()` provides fail-fast verification across the complete application when paired with a generated manifest:
|
|
139
|
-
|
|
140
|
-
```ts
|
|
141
|
-
import { validateEnv } from "@maverickcer/env-cap"
|
|
142
|
-
import { manifest } from "./generated/env.manifest"
|
|
143
|
-
|
|
144
|
-
await validateEnv({
|
|
145
|
-
manifest,
|
|
146
|
-
values: process.env,
|
|
147
|
-
})
|
|
148
|
-
```
|
|
149
|
-
|
|
150
|
-
The generated manifest provides a complete project-wide view without requiring runtime centralization. `validateEnv()` discovers every registered capability contract, validates required environment dependencies before the application serves traffic, and aggregates failures into a single validation error.
|
|
151
|
-
|
|
152
|
-
This allows teams to maintain local ownership while preserving operational visibility:
|
|
153
|
-
|
|
154
|
-
- Missing variables are detected before the application serves traffic.
|
|
155
|
-
- Invalid values across multiple capabilities are reported together instead of failing one at a time.
|
|
156
|
-
- Each capability retains ownership of its validation rules.
|
|
157
|
-
- Operations teams maintain visibility into application-wide configuration requirements.
|
|
158
|
-
|
|
159
|
-
Runtime access remains capability-scoped, while validation remains application-wide.
|
|
160
|
-
|
|
161
|
-
## Helpers
|
|
162
|
-
|
|
163
|
-
`@maverickcer/env-cap/helpers` provides optional convenience functions for common processor and validator patterns.
|
|
164
|
-
|
|
165
|
-
Helpers are intentionally not the core `env-cap` workflow. They are provided for smaller applications, prototypes, and straightforward configuration requirements where a lightweight convenience API is useful.
|
|
166
|
-
|
|
167
|
-
Already using Zod, envalid, or another validation library? Keep it and integrate it directly with env-cap contracts — helpers exist for when a lighter API is enough, not as a reason to switch.
|
|
168
|
-
|
|
169
|
-
```ts
|
|
170
|
-
import { createEnv } from "@maverickcer/env-cap"
|
|
171
|
-
import { processors, validators } from "@maverickcer/env-cap/helpers"
|
|
172
|
-
|
|
173
|
-
export const databaseEnv = createEnv(
|
|
174
|
-
{
|
|
175
|
-
DATABASE_URL: {
|
|
176
|
-
processor: processors.toURL(),
|
|
177
|
-
validator: validators.required(),
|
|
178
|
-
},
|
|
179
|
-
|
|
180
|
-
PORT: {
|
|
181
|
-
default: 5432,
|
|
182
|
-
processor: processors.toNumber(),
|
|
183
|
-
validator: validators.range(1, 65535),
|
|
184
|
-
},
|
|
185
|
-
},
|
|
186
|
-
{
|
|
187
|
-
name: "database",
|
|
188
|
-
},
|
|
189
|
-
)
|
|
190
|
-
```
|
|
191
|
-
|
|
192
|
-
Available helpers include common processors and validators with composition utilities. They can be
|
|
193
|
-
found at [src/helpers/index.ts](https://github.com/MaverickCER/env-cap/blob/main/src/helpers/index.ts)
|
|
194
|
-
|
|
195
|
-
When possible, prefer validation rules that communicate domain intent directly alongside the capability contract. These may be custom `Processor<T>` and `Validator<T>` functions or existing validators from your application's validation stack.
|
|
196
|
-
|
|
197
|
-
```ts
|
|
198
|
-
validator(value: string) {
|
|
199
|
-
return value.startsWith("sk_") ||
|
|
200
|
-
'Expected a Stripe secret key starting with "sk_".';
|
|
201
|
-
}
|
|
202
|
-
```
|
|
203
|
-
|
|
204
|
-
A named validation rule explains why the dependency exists and gives future maintainers context that a generic helper cannot always provide.
|
|
205
|
-
|
|
206
|
-
The helper package is optional and has no impact on the core runtime when unused. When all runtime features are included, the runtime entry point remains within its 3 KB gzip budget and `./helpers` within its 4 KB one. `createEnv()` and `validateEnv()` remain the core APIs and provide the foundation for capability-owned configuration, while helpers provide convenient building blocks for common processor and validator patterns.
|
|
207
|
-
|
|
208
|
-
## Core workflow
|
|
64
|
+
Validation stays application-wide. One `validateEnv()` call checks every contract in the generated manifest and reports every failure in one `EnvValidationError` (`test/runtime/validate.test.ts`).
|
|
209
65
|
|
|
210
|
-
###
|
|
66
|
+
### Core workflow
|
|
211
67
|
|
|
212
|
-
|
|
68
|
+
#### 1. Define your environment contract
|
|
213
69
|
|
|
214
|
-
|
|
70
|
+
Start with one central contract if that is what you have. This snippet is illustrative; [`examples/application/src/env.ts`](https://github.com/MaverickCER/env-cap/blob/main/examples/application/src/env.ts) is the central contract CI runs.
|
|
215
71
|
|
|
216
72
|
```ts
|
|
73
|
+
// src/env.ts
|
|
217
74
|
import { createEnv } from "@maverickcer/env-cap"
|
|
218
75
|
|
|
219
76
|
export const env = createEnv(
|
|
@@ -223,253 +80,81 @@ export const env = createEnv(
|
|
|
223
80
|
return value.startsWith("postgres://") || "Expected a PostgreSQL connection string."
|
|
224
81
|
},
|
|
225
82
|
},
|
|
226
|
-
PORT: {
|
|
227
|
-
default: 3000,
|
|
228
|
-
processor(value: string) {
|
|
229
|
-
return Number(value)
|
|
230
|
-
},
|
|
231
|
-
},
|
|
232
|
-
},
|
|
233
|
-
{
|
|
234
|
-
name: "application",
|
|
83
|
+
PORT: { default: 3000, processor: (value: string) => Number(value) },
|
|
235
84
|
},
|
|
85
|
+
{ name: "application" },
|
|
236
86
|
)
|
|
237
87
|
```
|
|
238
88
|
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
```text
|
|
242
|
-
src/
|
|
243
|
-
├── features/
|
|
244
|
-
│ ├── payments/
|
|
245
|
-
│ │ └── env.schema.ts
|
|
246
|
-
│ ├── database/
|
|
247
|
-
│ │ └── env.schema.ts
|
|
248
|
-
│ └── notifications/
|
|
249
|
-
│ └── env.schema.ts
|
|
250
|
-
```
|
|
251
|
-
|
|
252
|
-
A capability can also be a reusable package:
|
|
89
|
+
Move contracts next to the features that consume them when ownership starts to matter. The runtime model does not change:
|
|
253
90
|
|
|
254
91
|
```text
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
92
|
+
src/features/payments/env.schema.ts
|
|
93
|
+
src/features/database/env.schema.ts
|
|
94
|
+
packages/paypal-addon/src/env.schema.ts
|
|
258
95
|
```
|
|
259
96
|
|
|
260
|
-
|
|
97
|
+
[`examples/application`](https://github.com/MaverickCER/env-cap/tree/main/examples/application) keeps one contract; [`examples/team-service`](https://github.com/MaverickCER/env-cap/tree/main/examples/team-service) splits it per feature.
|
|
261
98
|
|
|
262
|
-
|
|
99
|
+
#### 2. Generate the project view
|
|
263
100
|
|
|
264
|
-
|
|
101
|
+
A build step, run in development or CI, writes the manifest your startup code imports. The platform engineer's section covers the options; the short form is the CLI:
|
|
265
102
|
|
|
266
|
-
```
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
await generateEnvManifest({
|
|
270
|
-
location: "src/generated/env.manifest.ts",
|
|
271
|
-
})
|
|
103
|
+
```sh
|
|
104
|
+
npx env-cap --location src/generated/env.manifest.ts --evidence docs/env.evidence.json
|
|
272
105
|
```
|
|
273
106
|
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
- environment manifests
|
|
277
|
-
- documentation
|
|
278
|
-
- `.env.example` files
|
|
279
|
-
- configuration reports
|
|
280
|
-
|
|
281
|
-
Every one of these draws a hard line between **declared** facts (author
|
|
282
|
-
metadata — `owner`, `sensitivity`, `expiresAt`, `retention` — presence is
|
|
283
|
-
checked, correctness never is) and **proven** facts (AST-derived —
|
|
284
|
-
`UNCONSUMED_OWNED_VARIABLE`, the dependency graph). See
|
|
285
|
-
[`specs/generated-artifacts.md`](specs/generated-artifacts.md) for the full
|
|
286
|
-
list of what's generated today, the seven canonical fact models each one
|
|
287
|
-
projects from, and what's deliberately deferred.
|
|
288
|
-
|
|
289
|
-
Schemas are analyzed statically.
|
|
290
|
-
|
|
291
|
-
They are never imported or executed during discovery.
|
|
292
|
-
|
|
293
|
-
This provides project-wide visibility without requiring runtime configuration to become centralized.
|
|
294
|
-
|
|
295
|
-
#### Change tracking via the persisted evidence artifact
|
|
296
|
-
|
|
297
|
-
`generateEnvManifest()` no longer tracks its own change history — that moved to a separate, optional
|
|
298
|
-
artifact: the full `EvidenceModel`, env-cap's canonical fact model covering the contract graph,
|
|
299
|
-
dependency/ownership findings, lifecycle data, and a change report diffed against whatever was
|
|
300
|
-
previously persisted. `generateEnvArtifacts()` always computes it; passing `evidence` also writes it
|
|
301
|
-
to disk:
|
|
302
|
-
|
|
303
|
-
```ts
|
|
304
|
-
const result = await generateEnvArtifacts({
|
|
305
|
-
manifest: { location: "src/generated/env.manifest.ts" },
|
|
306
|
-
evidence: { location: "docs/env.evidence.json" },
|
|
307
|
-
})
|
|
308
|
-
|
|
309
|
-
console.log(result.evidence.change.manifest.addedVariables) // newly documented this run
|
|
310
|
-
console.log(result.evidence.change.manifest.updatedVariables) // field-level before/after for anything that changed
|
|
311
|
-
console.log(result.evidence.change.manifest.removedVariables) // no longer discovered at all
|
|
312
|
-
```
|
|
107
|
+
Schema files are parsed, never imported or run (`test/build/parse.test.ts`). 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.
|
|
313
108
|
|
|
314
|
-
|
|
315
|
-
project with no `.ts` manifest at all can still generate a pure evidence report. Writing it also
|
|
316
|
-
writes a paired `docs/env.evidence.json.fingerprint` sidecar, a cheap content hash a later read
|
|
317
|
-
(`getEvidenceModel()`, for a report/projection script that doesn't want to pay for a full recompute
|
|
318
|
-
on every invocation) uses to skip regenerating when nothing relevant has changed.
|
|
319
|
-
|
|
320
|
-
**Commit both files, the same as you already commit `env.manifest.ts` itself.** "Since last
|
|
321
|
-
execution" means since the last commit on your branch — that's what makes the diff meaningful in CI and
|
|
322
|
-
reviewable in a pull request, not just a local curiosity. See
|
|
323
|
-
[ADR 0038](specs/decisions/0038-always-computed-evidence-model-backs-generate-check-docs.md) for the
|
|
324
|
-
full reasoning (superseding [ADR 0021](specs/decisions/0021-manifest-change-report-persisted-snapshot.md)'s
|
|
325
|
-
original manifest-adjacent design).
|
|
326
|
-
|
|
327
|
-
- **A diff is expected** any time a `documentEnv()` call's `description`/`owner`/`expiresAt`/
|
|
328
|
-
`refreshInstructions`/`required`/`extra` changes, or a contract's `active`/`category`/`exclusiveGroup`
|
|
329
|
-
changes — anything that isn't schema shape itself.
|
|
330
|
-
- **Regeneration is automatic.** Every `generate:env`/CI run that passes `--evidence` already
|
|
331
|
-
rewrites both files; there's no separate "update the snapshot" step to remember.
|
|
332
|
-
- **A diff signals real drift worth a second look** when it shows up somewhere nobody meant to touch —
|
|
333
|
-
an `updatedVariables` entry for a variable nobody intended to edit, or an `addedContracts`/
|
|
334
|
-
`removedContracts` entry from a change that was supposed to be unrelated.
|
|
335
|
-
|
|
336
|
-
The CLI's normal (non-`--check`) output prints the same summary as an "Evidence changes since the
|
|
337
|
-
last persisted snapshot" section whenever `--evidence <path>` is passed; run with `--json --evidence
|
|
338
|
-
<path>` for the same data in machine-readable form.
|
|
339
|
-
|
|
340
|
-
Separately, when two _active_ contracts document the same variable key with different metadata (e.g. two
|
|
341
|
-
features that happen to reuse a name, each with its own `description`/`owner`), that's reported as a
|
|
342
|
-
`duplicate-variable-documentation` warning in `result.warnings` — always a warning, never a hard error
|
|
343
|
-
(static analysis can't prove two descriptions are "wrong," only different), gated by the same
|
|
344
|
-
`onIncompatibility` option as every other compatibility warning.
|
|
345
|
-
|
|
346
|
-
### 3. Validate once during startup
|
|
109
|
+
#### 3. Validate once during startup
|
|
347
110
|
|
|
348
111
|
```ts
|
|
349
112
|
import { validateEnv } from "@maverickcer/env-cap"
|
|
350
113
|
import { manifest } from "./generated/env.manifest"
|
|
351
114
|
|
|
352
|
-
await validateEnv({
|
|
353
|
-
manifest,
|
|
354
|
-
values: process.env,
|
|
355
|
-
})
|
|
356
|
-
```
|
|
357
|
-
|
|
358
|
-
At startup, `validateEnv()` verifies the complete application environment boundary.
|
|
359
|
-
|
|
360
|
-
After validation:
|
|
361
|
-
|
|
362
|
-
```ts
|
|
363
|
-
env.DATABASE_URL
|
|
364
|
-
```
|
|
365
|
-
|
|
366
|
-
or:
|
|
367
|
-
|
|
368
|
-
```ts
|
|
369
|
-
paymentsEnv.STRIPE_KEY
|
|
115
|
+
await validateEnv({ manifest, values: process.env })
|
|
370
116
|
```
|
|
371
117
|
|
|
372
|
-
|
|
118
|
+
What happens, and where each rule is tested:
|
|
373
119
|
|
|
374
|
-
|
|
120
|
+
| Situation | Result | Test |
|
|
121
|
+
| ---------------------------------------------- | --------------------------------------------------------------------- | ------------------------------- |
|
|
122
|
+
| A contract is read before `validateEnv()` ends | Throws `EnvNotReadyError` | `test/runtime/create.test.ts` |
|
|
123
|
+
| Several variables fail | One `EnvValidationError` lists every failure | `test/runtime/validate.test.ts` |
|
|
124
|
+
| A failure message | Carries variable and contract names and your message, never the value | `test/runtime/validate.test.ts` |
|
|
125
|
+
| `validateEnv()` is called again | Returns or rethrows the first outcome without re-running validators | `test/runtime/validate.test.ts` |
|
|
126
|
+
| A test needs a fresh run | `resetEnvCache()` clears the cached outcome | `test/runtime/reset.test.ts` |
|
|
375
127
|
|
|
376
|
-
|
|
377
|
-
paymentsEnv.STRIPE_KEY
|
|
378
|
-
```
|
|
379
|
-
|
|
380
|
-
throws:
|
|
381
|
-
|
|
382
|
-
```ts
|
|
383
|
-
EnvNotReadyError
|
|
384
|
-
```
|
|
128
|
+
The record of validated values is frozen. The freeze is shallow: an object, array or `URL` that a processor returns stays mutable.
|
|
385
129
|
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
```ts
|
|
389
|
-
EnvValidationError
|
|
390
|
-
```
|
|
391
|
-
|
|
392
|
-
so applications receive the complete startup failure state instead of discovering missing or invalid variables one at a time.
|
|
393
|
-
|
|
394
|
-
Runtime access can remain centralized for simpler applications or become capability-scoped as ownership boundaries grow. Validation remains application-wide.
|
|
395
|
-
|
|
396
|
-
`validateEnv()` is idempotent for the life of the process: the first call's outcome (success or `EnvValidationError`) is cached and returned by every later call, without re-running any processor or validator — by design, since a real application validates once at startup and every later read should see that same, stable outcome. A test suite or a script that intentionally validates different `values` in the same process (as opposed to a real app's single startup call) needs `resetEnvCache()` between runs:
|
|
130
|
+
A test suite that validates several scenarios in one process resets between them:
|
|
397
131
|
|
|
398
132
|
```ts
|
|
399
133
|
import { resetEnvCache, validateEnv } from "@maverickcer/env-cap"
|
|
400
134
|
|
|
401
135
|
await validateEnv({ manifest, values: scenarioA })
|
|
402
136
|
resetEnvCache()
|
|
403
|
-
await validateEnv({ manifest, values: scenarioB })
|
|
137
|
+
await validateEnv({ manifest, values: scenarioB })
|
|
404
138
|
```
|
|
405
139
|
|
|
406
|
-
Without
|
|
407
|
-
|
|
408
|
-
## Runtime support matrix
|
|
409
|
-
|
|
410
|
-
| Environment | `.` (runtime) | `./helpers` | `./build` (CLI/tooling) |
|
|
411
|
-
| -------------------------------------------------------------- | ----------------------------- | ----------- | ------------------------------------------------------------- |
|
|
412
|
-
| Node.js 22+ (CJS or ESM) | ✅ | ✅ | ✅ |
|
|
413
|
-
| Browser bundle (Webpack/Vite/esbuild/etc.) | ✅ | ✅ ¹ | ❌ not applicable — build-only, never bundle this into an app |
|
|
414
|
-
| Edge/serverless (Cloudflare Workers, Vercel Edge, Deno Deploy) | ✅ | ✅ ¹ | ❌ not applicable |
|
|
415
|
-
| Bun | ✅ (conformance-tested in CI) | ✅ | ✅ |
|
|
416
|
-
| Deno | ✅ (conformance-tested in CI) | ✅ | ✅ |
|
|
417
|
-
|
|
418
|
-
¹ Except `processors.base64()`, which returns a Node `Buffer`: use it only where `Buffer` exists, or decode with your own processor elsewhere.
|
|
419
|
-
|
|
420
|
-
The runtime (`.` and `./helpers`) has zero dependencies, never touches the filesystem, and never imports a Node module (the one Node global it uses is the `Buffer` that `processors.base64()` returns) — see [`specs/architecture.md`](specs/architecture.md). `./build` is Node-only developer tooling (uses `node:path` and the TypeScript compiler API — never `node:fs`, see [ADR 0040](specs/decisions/0040-library-surfaces-do-not-acquire-node-fs.md)) meant for CI/npm-script use, never for shipping to a browser. Both ESM and CommonJS builds are published for every entry point (`package.json#exports`).
|
|
421
|
-
|
|
422
|
-
### Requirements
|
|
423
|
-
|
|
424
|
-
Node.js `>=22`. TypeScript 5, 6 or 7 is only required for build-time manifest generation: a bundled TypeScript 6 parses the schemas when yours is 7, is bundled inside the package and used only by the build entry, and adds about 24 MB unpacked to the install. The runtime works in plain JavaScript. TypeScript consumers need `moduleResolution` set to `node16`, `nodenext` or `bundler` to resolve the subpath exports (`./build`, `./helpers`, ...); the legacy `node10` resolver is not supported. `@maverickcer/env-cap/eslint-plugin` also needs `@typescript-eslint/utils` installed (an optional peer).
|
|
425
|
-
|
|
426
|
-
## Validation contexts
|
|
140
|
+
Without `resetEnvCache()`, the second call returns the first call's result.
|
|
427
141
|
|
|
428
|
-
|
|
429
|
-
contexts active for a given run, and skips every variable that doesn't match:
|
|
142
|
+
### Validation contexts
|
|
430
143
|
|
|
431
|
-
|
|
432
|
-
DATABASE_URL: {
|
|
433
|
-
context: "server",
|
|
434
|
-
validator: validators.required(),
|
|
435
|
-
}
|
|
436
|
-
```
|
|
437
|
-
|
|
438
|
-
```ts
|
|
439
|
-
await validateEnv({
|
|
440
|
-
manifest,
|
|
441
|
-
values: process.env,
|
|
442
|
-
activeContexts: ["server"],
|
|
443
|
-
})
|
|
444
|
-
```
|
|
445
|
-
|
|
446
|
-
**Matching rule:** a variable with no `context` participates in every run. A variable with a `context`
|
|
447
|
-
participates only when `activeContexts` contains that exact string — no prefix matching, wildcards, or
|
|
448
|
-
hierarchy. A skipped variable never runs its `default`/`processor`/`validator`, and reading it throws
|
|
449
|
-
`EnvNotReadyError`, exactly as if `validateEnv()` had never run for it.
|
|
450
|
-
|
|
451
|
-
`context` is entirely application-defined — env-cap never interprets, detects, or infers it. `"server"` and
|
|
452
|
-
`"client"` are just one example; a validation context can represent anything a validation run needs to
|
|
453
|
-
distinguish:
|
|
144
|
+
A variable can belong to one validation context, a plain string your application chooses. These snippets are illustrative; the CI-run fixture is [`validation-contexts`](https://github.com/MaverickCER/env-cap/tree/main/test/integration/positive/team/validation-contexts).
|
|
454
145
|
|
|
455
146
|
```ts
|
|
456
147
|
DATABASE_URL: { context: "server", validator: validators.required() }
|
|
457
148
|
STRIPE_LIVE_KEY: { context: "production", validator: validators.required() }
|
|
458
149
|
QUEUE_CONCURRENCY: { context: "worker", default: 4 }
|
|
459
|
-
DEBUG_TRACE_ENDPOINT: { context: "development" }
|
|
460
150
|
```
|
|
461
151
|
|
|
462
|
-
|
|
463
|
-
variable declaring either. This works the same regardless of framework: `env-cap` never inspects `window` or
|
|
464
|
-
`NODE_ENV` itself, the application computes `activeContexts` once, explicitly, before calling `validateEnv()`:
|
|
152
|
+
Pass the contexts that apply to this process:
|
|
465
153
|
|
|
466
154
|
```ts
|
|
467
|
-
// Works the same in a Next.js, TanStack Start, or plain Node app -- env-cap
|
|
468
|
-
// never inspects window/NODE_ENV itself; the application does, once, before
|
|
469
|
-
// calling validateEnv().
|
|
470
155
|
await validateEnv({
|
|
471
|
-
values: typeof window === "undefined" ? process.env : window.__ENV__,
|
|
472
156
|
manifest,
|
|
157
|
+
values: process.env,
|
|
473
158
|
activeContexts: [
|
|
474
159
|
typeof window === "undefined" ? "server" : "client",
|
|
475
160
|
process.env.NODE_ENV === "production" ? "production" : "development",
|
|
@@ -477,412 +162,261 @@ await validateEnv({
|
|
|
477
162
|
})
|
|
478
163
|
```
|
|
479
164
|
|
|
480
|
-
|
|
481
|
-
named to match `activeContexts` itself so it can be passed straight through:
|
|
165
|
+
A variable takes part in a run by these rules:
|
|
482
166
|
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
```
|
|
488
|
-
|
|
489
|
-
```ts
|
|
490
|
-
import { activeContexts, manifest } from "./generated/env.manifest"
|
|
491
|
-
|
|
492
|
-
await validateEnv({ manifest, values: process.env, activeContexts })
|
|
493
|
-
```
|
|
167
|
+
1. A variable with no `context` takes part in every run.
|
|
168
|
+
2. A variable with a `context` takes part only when `activeContexts` contains that exact string.
|
|
169
|
+
3. A skipped variable runs no default, processor or validator, and reading it throws `EnvNotReadyError`.
|
|
170
|
+
4. env-cap never inspects `window` or `NODE_ENV`; your code computes `activeContexts`.
|
|
494
171
|
|
|
495
|
-
|
|
496
|
-
unmodified into every process defeats the point of scoping contexts per deployment target in the first place;
|
|
497
|
-
narrow it (or import it under another name and filter it) the same way `src/server.ts`/`src/client.ts` in
|
|
498
|
-
[`test/integration/positive/team/validation-contexts`](https://github.com/MaverickCER/env-cap/tree/main/test/integration/positive/team/validation-contexts)
|
|
499
|
-
each hand-write their own narrowed `activeContexts: ["server"]` / `["client"]` instead of using this
|
|
500
|
-
export directly.
|
|
172
|
+
When any variable declares a context, the generated manifest also exports `activeContexts`, listing every context it found. Treat it as a starting point and narrow it per process, as [`validation-contexts`](https://github.com/MaverickCER/env-cap/tree/main/test/integration/positive/team/validation-contexts) does.
|
|
501
173
|
|
|
502
|
-
|
|
503
|
-
> `validateEnv()` processes a variable — nothing else. Putting a `context: "server"` variable in the same
|
|
504
|
-
> schema as `context: "client"` variables, feeding one manifest that a client bundle imports, does **not**
|
|
505
|
-
> keep the server-context variable's definition (including any literal `default`) out of that bundle —
|
|
506
|
-
> `activeContexts` filtering happens after the schema is already wherever it's going to be. If a variable must
|
|
507
|
-
> never reach a browser bundle at all, keep using separate discovery/generated manifests per contract (see
|
|
508
|
-
> ["Runtime and build-time are intentionally separate"](#architecture)
|
|
509
|
-
> and [ADR 0004](specs/decisions/0004-no-client-server-package-split.md)) — validation contexts are a
|
|
510
|
-
> complement to that boundary, not a replacement for it. Likewise, a string like `context: "admin"` does not
|
|
511
|
-
> restrict _who_ can read a value; it only decides whether a given run validates it. See
|
|
512
|
-
> [ADR 0022](specs/decisions/0022-validation-contexts.md) for the full set of invariants this feature commits to.
|
|
174
|
+
**Contexts are not a security or bundling boundary.** They decide whether a run validates a variable, nothing else. A `context: "server"` variable in a schema that a client bundle imports still ships its definition and any literal `default`. Keep server-only variables in a separate schema and manifest ([ADR 0004](specs/decisions/0004-no-client-server-package-split.md), [ADR 0022](specs/decisions/0022-validation-contexts.md)).
|
|
513
175
|
|
|
514
|
-
|
|
176
|
+
### Security model
|
|
515
177
|
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
This works for both centralized application schemas and capability-owned contracts. A reusable package can expose the environment requirements it owns, allowing consuming applications to validate and generate visibility artifacts without manually copying configuration definitions.
|
|
519
|
-
|
|
520
|
-
See [`test/integration/positive/enterprise/paypal-addon`](https://github.com/MaverickCER/env-cap/tree/main/test/integration/positive/enterprise/paypal-addon)/[`test/integration/positive/enterprise/paypal-consumer`](https://github.com/MaverickCER/env-cap/tree/main/test/integration/positive/enterprise/paypal-consumer) for a complete, runnable example (see [`examples/`](examples/) for the three flagship, human-facing examples, and [`test/integration/`](https://github.com/MaverickCER/env-cap/tree/main/test/integration) for every other runnable scenario).
|
|
521
|
-
|
|
522
|
-
Discovery still never walks `node_modules` during its general file-discovery pass (`generateEnvManifest()`'s `include`/`exclude` globs), and that guarantee is unconditional.
|
|
523
|
-
|
|
524
|
-
Making a package-shipped contract discoverable is an opt-in mechanism (see [`VERSIONING.md`](VERSIONING.md) and [ADR 0014](specs/decisions/0014-cross-package-schema-discovery.md)):
|
|
525
|
-
|
|
526
|
-
```ts
|
|
527
|
-
// consuming app's build script
|
|
528
|
-
await generateEnvArtifacts({
|
|
529
|
-
packages: ["@acme/payments-sdk"], // explicit allowlist -- never implicit
|
|
530
|
-
manifest: { location: "src/env.manifest.ts" },
|
|
531
|
-
})
|
|
532
|
-
```
|
|
178
|
+
What the runtime refuses to do, and what enforces each refusal:
|
|
533
179
|
|
|
534
|
-
The
|
|
180
|
+
| The runtime does not | Enforced by | Limit |
|
|
181
|
+
| ------------------------------ | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
|
|
182
|
+
| Touch the filesystem | A lint ban on `node:fs` in `src/` outside the CLI, and the `AmbientCapabilities` tarball scan | The scan is textual |
|
|
183
|
+
| Read `process.env` | The `AmbientCapabilities` scan and the browser-bundle test | `globalThis["process"]` would evade both |
|
|
184
|
+
| Open a network connection | The `ipc/no-network` lint rule on env-cap's own `src/` | Source lint only; the bundled TypeScript compiler is not covered |
|
|
185
|
+
| Show values when logged | `test/runtime/create.test.ts`: `console.log`, `String()`, `JSON.stringify`, templates | Spreading a contract or calling `Object.entries()` reads every value |
|
|
186
|
+
| Put values in errors | `test/runtime/validate.test.ts` | Your own validator or processor message is passed through verbatim |
|
|
187
|
+
| Fetch, store or rotate secrets | No such code exists; `documentEnv()` fields are documentation only | Not a check; read the source |
|
|
535
188
|
|
|
536
|
-
|
|
189
|
+
Logged, a contract prints a marker instead of its values:
|
|
537
190
|
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
```ts
|
|
541
|
-
import { paypalEnv } from "@acme/paypal-addon"
|
|
542
|
-
```
|
|
543
|
-
|
|
544
|
-
resolves to the same contract discovered during build-time analysis.
|
|
545
|
-
|
|
546
|
-
Resolution never calls `readdir` on `node_modules` — it reads exactly one `package.json` per allow-listed package to find the declared field, then exactly one declared file, validated (path, extension, symlink target, size) before it is parsed.
|
|
547
|
-
|
|
548
|
-
See `SECURITY.md`'s "Avoids unnecessary traversal of dependency directories" section for the exact bounds.
|
|
549
|
-
|
|
550
|
-
### Documenting a variable a package already explains
|
|
551
|
-
|
|
552
|
-
A variable can be declared in the package's contract and again in the application that consumes it. The application
|
|
553
|
-
does not repeat the explanation: it names the variable with only what is its own, and every field it leaves unset is
|
|
554
|
-
filled from the package's declaration.
|
|
555
|
-
|
|
556
|
-
```ts
|
|
557
|
-
const credentials = { PAYPAL_CLIENT_SECRET: { default: "", validator: () => true } }
|
|
558
|
-
export const credentialsEnv = createEnv(credentials, { name: "credentials" })
|
|
559
|
-
|
|
560
|
-
documentEnv(credentials, {
|
|
561
|
-
variables: { PAYPAL_CLIENT_SECRET: { expiresAt: "2027-01-01", owner: "payments" } },
|
|
562
|
-
})
|
|
563
|
-
```
|
|
564
|
-
|
|
565
|
-
Both declarations then report the package's `description`, `sensitivity` and `refreshInstructions` together with the
|
|
566
|
-
application's `expiresAt` and `owner`. A field the application sets itself is never replaced, and a field both set to
|
|
567
|
-
different values is reported as `DUPLICATE_VARIABLE_DOCUMENTATION`. Two of the application's own contracts never fill
|
|
568
|
-
each other (a service that can run on either of two databases documents each one's variable for itself); a field
|
|
569
|
-
both set differently is still reported. See
|
|
570
|
-
[ADR 0050](specs/decisions/0050-a-variable-declared-twice-is-documented-once.md).
|
|
571
|
-
|
|
572
|
-
## TypeScript path aliases (paths/baseUrl)
|
|
573
|
-
|
|
574
|
-
If your project organizes its own source with a `tsconfig.json` path alias (`"@/lib/env"`, `"~/schema/env"`, ...), `env-cap` resolves it automatically — no configuration required:
|
|
575
|
-
|
|
576
|
-
```ts
|
|
577
|
-
// tsconfig.json
|
|
578
|
-
{ "compilerOptions": { "paths": { "@/*": ["./src/*"] } } }
|
|
579
|
-
```
|
|
580
|
-
|
|
581
|
-
```ts
|
|
582
|
-
// src/consumer.ts
|
|
583
|
-
import { paymentsEnv } from "@/features/payments/env.schema.js"
|
|
584
|
-
paymentsEnv.STRIPE_KEY
|
|
585
|
-
```
|
|
586
|
-
|
|
587
|
-
Without this, a contract only ever imported through an alias would be misreported as `abandoned` in the Dependency & Ownership Report, or its `documentEnv()` call left unlinked — the same class of false positive [ADR 0010](specs/decisions/0010-dependency-ownership-engine-scope-boundary.md)'s ownership engine exists to avoid.
|
|
588
|
-
|
|
589
|
-
See [`test/integration/positive/enterprise/tsconfig-aliases`](https://github.com/MaverickCER/env-cap/tree/main/test/integration/positive/enterprise/tsconfig-aliases) for a complete, runnable example, and [`test/integration/positive/enterprise/tsconfig-aliases-consumer`](https://github.com/MaverickCER/env-cap/tree/main/test/integration/positive/enterprise/tsconfig-aliases-consumer) for the same producer/consumer pairing [Reusable packages](#reusable-packages) uses — proving this composes correctly with cross-package discovery (ADR 0014) in one real install (see [`examples/`](examples/) for the three flagship, human-facing examples, and [`test/integration/`](https://github.com/MaverickCER/env-cap/tree/main/test/integration) for every other runnable scenario).
|
|
590
|
-
|
|
591
|
-
Unlike [Reusable packages](#reusable-packages) above, this is on by default (see [`VERSIONING.md`](VERSIONING.md) and [ADR 0023](specs/decisions/0023-tsconfig-path-alias-resolution.md)): a project's own `tsconfig.json` never crosses a trust/versioning boundary the way an installed package does, so there's no safety reason to require opt-in. `env-cap` auto-detects `tsconfig.json` at `root`, exactly (no upward directory search, unlike bare `tsc`). Pass `tsconfig: "<path>"` to point at a different file (useful in monorepos where the relevant config isn't at `root`), or `tsconfig: false` to disable alias resolution entirely:
|
|
592
|
-
|
|
593
|
-
```ts
|
|
594
|
-
await generateEnvArtifacts({
|
|
595
|
-
tsconfig: "tsconfig.build.json", // or `false` to disable
|
|
596
|
-
manifest: { location: "src/env.manifest.ts" },
|
|
597
|
-
})
|
|
598
|
-
```
|
|
599
|
-
|
|
600
|
-
The actual `paths`/`baseUrl` matching is delegated entirely to the TypeScript compiler (`ts.resolveModuleName()`, the same function `tsc`/`tsserver` themselves use), never resolves into `node_modules` (that boundary stays exclusively [ADR 0014](specs/decisions/0014-cross-package-schema-discovery.md)'s), and only ever resolves to a real `.ts`/`.tsx` file.
|
|
601
|
-
|
|
602
|
-
## Architecture
|
|
603
|
-
|
|
604
|
-
### Runtime and build-time are intentionally separate
|
|
605
|
-
|
|
606
|
-
`env-cap` separates application execution from project-wide analysis.
|
|
607
|
-
|
|
608
|
-
```text
|
|
609
|
-
Environment contract
|
|
610
|
-
|
|
|
611
|
-
|
|
|
612
|
-
+----+----+
|
|
613
|
-
| |
|
|
614
|
-
Runtime Build-time
|
|
615
|
-
| |
|
|
616
|
-
createEnv AST analysis
|
|
617
|
-
| |
|
|
618
|
-
validateEnv generate artifacts
|
|
619
|
-
|
|
|
620
|
-
Typed access
|
|
191
|
+
```txt
|
|
192
|
+
EnvContract("payments") { 1 variable(s) }
|
|
621
193
|
```
|
|
622
194
|
|
|
623
|
-
|
|
195
|
+
The full model, including what stays your responsibility, is in [SECURITY.md](SECURITY.md).
|
|
624
196
|
|
|
625
|
-
|
|
626
|
-
- exposes typed values
|
|
627
|
-
- contains no filesystem access
|
|
628
|
-
- does not discover files dynamically
|
|
197
|
+
### Troubleshooting
|
|
629
198
|
|
|
630
|
-
|
|
199
|
+
env-cap defines these error classes. A contract from the other module format throws a `TypeError` ([dual-package hazard](SECURITY.md#dual-package-hazard)), and a processor called outside `validateEnv()` throws a plain `Error`.
|
|
631
200
|
|
|
632
|
-
|
|
633
|
-
|
|
634
|
-
|
|
201
|
+
| Error | Thrown by | Common cause | Fix |
|
|
202
|
+
| --------------------------------- | ------------------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
|
|
203
|
+
| `EnvNotReadyError` | Reading `someEnv.KEY` | The contract was read before `validateEnv()` finished, or its context was not active | Await `validateEnv()` at startup, before application code reads values |
|
|
204
|
+
| `EnvValidationError` | `validateEnv()` | A processor or validator rejected one or more variables | Read `error.failures`: one entry per variable, with names and your message |
|
|
205
|
+
| `EnvManifestGenerationError` | `generateEnvManifest()` | Conflicting explicit processor types for one variable, or `location` outside `root` | Read `error.issues`; fix the definitions or the output path |
|
|
206
|
+
| `EnvDocumentationGenerationError` | `generateDocumentation()` | `location` or `envExample.location` outside `root` | Correct the output path |
|
|
207
|
+
| `EnvUsageAnalysisError` | `generateUsageReport()` | `report.location` outside `root` | Correct the output path |
|
|
208
|
+
| `EnvProjectGenerationError` | `generateEnvArtifacts()` | Any of the above, collected across the requested passes, or an exclusive-group violation | Fix the underlying error; every failure is listed in one result |
|
|
635
209
|
|
|
636
|
-
|
|
210
|
+
Documentation and ownership findings never throw. They are reported as findings in the evidence file, and fail a run only under a `--strict*` flag.
|
|
637
211
|
|
|
638
|
-
A
|
|
212
|
+
**A schema's variable is missing from the manifest.** Discovery reads an inline object literal or a resolvable `const`. A spread or a factory produces a parse warning; read `result.parseWarnings` or the CLI output ([ADR 0002](specs/decisions/0002-static-analysis-never-execution.md)).
|
|
639
213
|
|
|
640
|
-
|
|
641
|
-
|
|
642
|
-
## Migration
|
|
214
|
+
**A contract imported through a path alias shows as abandoned.** Check that `tsconfig.json` sits at `root` and declares `paths` or `baseUrl`. Otherwise, point `tsconfig` at the right file. Discovery does not search upward ([path aliases](#typescript-path-aliases-pathsbaseurl)).
|
|
643
215
|
|
|
644
|
-
|
|
216
|
+
**A listed package's contract is not discovered.** Look for a `(package) <name>` entry in `result.parseWarnings`. The package must declare `envCap.schema` pointing at a `.ts` or `.tsx` file inside itself ([reusable packages](#reusable-packages)).
|
|
645
217
|
|
|
646
|
-
|
|
218
|
+
**A second `validateEnv()` call returned the first result.** That is the cache ([step 3](#3-validate-once-during-startup)). Call `resetEnvCache()` between scenarios.
|
|
647
219
|
|
|
648
|
-
|
|
220
|
+
**Discovery fails with a "sanity limit" error.** `discoverSchemaFiles` refuses to return more files than `MAX_DISCOVERED_SCHEMA_FILES`. The usual cause is a `root` or `include` far broader than intended, such as an unset `root` falling back to a large working directory. Narrow `root`, `include` or `exclude`.
|
|
649
221
|
|
|
650
|
-
|
|
222
|
+
## Application developers: helpers
|
|
651
223
|
|
|
652
|
-
|
|
224
|
+
**What it solves:** small, composable processors and validators for when a validation library is more than a variable needs. This snippet is illustrative; [`examples/application/src/env.ts`](https://github.com/MaverickCER/env-cap/blob/main/examples/application/src/env.ts) uses `processors` and `validators` in CI.
|
|
653
225
|
|
|
654
226
|
```ts
|
|
655
227
|
import { createEnv } from "@maverickcer/env-cap"
|
|
228
|
+
import { processors, validators } from "@maverickcer/env-cap/helpers"
|
|
656
229
|
|
|
657
|
-
export const
|
|
658
|
-
|
|
659
|
-
validator
|
|
660
|
-
|
|
230
|
+
export const databaseEnv = createEnv(
|
|
231
|
+
{
|
|
232
|
+
DATABASE_URL: { processor: processors.toURL(), validator: validators.required() },
|
|
233
|
+
PORT: {
|
|
234
|
+
default: 5432,
|
|
235
|
+
processor: processors.toNumber(),
|
|
236
|
+
validator: validators.range(1, 65535),
|
|
661
237
|
},
|
|
662
238
|
},
|
|
663
|
-
}
|
|
239
|
+
{ name: "database" },
|
|
240
|
+
)
|
|
664
241
|
```
|
|
665
242
|
|
|
666
|
-
|
|
667
|
-
|
|
668
|
-
|
|
243
|
+
- **The `Buffer` caveat:** `processors.base64()` returns a Node `Buffer`. Use it only where `Buffer` exists, or decode with your own processor. Every other helper uses Web globals only (`test/runtime/browser-bundle.test.ts`).
|
|
244
|
+
- **Cost:** `./helpers` stays under 4 KB gzip, enforced by the `Size` check. Unused helpers are dropped by esbuild (`test/helpers/tree-shaking.test.ts`); other bundlers are not tested.
|
|
245
|
+
- **Messages:** a processor that receives `undefined` or `null` names the type, not the value (`test/helpers/processors.test.ts`).
|
|
246
|
+
- **Optional:** keep Zod, envalid or your own functions if you have them. Any function returning `true` or a message works as a validator.
|
|
669
247
|
|
|
670
|
-
|
|
248
|
+
The full list is in the [API reference](https://maverickcer.github.io/env-cap/api/) and [src/helpers/index.ts](https://github.com/MaverickCER/env-cap/blob/main/src/helpers/index.ts).
|
|
671
249
|
|
|
672
|
-
|
|
673
|
-
process.env.STRIPE_KEY
|
|
674
|
-
```
|
|
675
|
-
|
|
676
|
-
with validated contract access:
|
|
250
|
+
## Platform engineers: generating artifacts
|
|
677
251
|
|
|
678
|
-
|
|
679
|
-
env.STRIPE_KEY
|
|
680
|
-
```
|
|
252
|
+
**What it solves:** generated manifests, documentation that cannot go stale, and drift that fails a pull request instead of reaching production.
|
|
681
253
|
|
|
682
|
-
|
|
254
|
+
The build entry discovers every `env.schema.ts`, parses it, and writes the artifacts you ask for. It needs a filesystem from its caller; on Node, pass `nodeBuildFileSystem`. This is the script `env-cap init` scaffolds, pinned by `test/cli/init.test.ts`:
|
|
683
255
|
|
|
684
256
|
```ts
|
|
685
|
-
|
|
686
|
-
|
|
687
|
-
|
|
688
|
-
|
|
689
|
-
|
|
690
|
-
Keep your existing validation logic.
|
|
691
|
-
|
|
692
|
-
`env-cap` organizes configuration ownership, lifecycle visibility, and application-wide validation boundaries; it does not replace specialized validation libraries.
|
|
257
|
+
import { generateEnvArtifacts } from "@maverickcer/env-cap/build"
|
|
258
|
+
import { nodeBuildFileSystem } from "@maverickcer/env-cap/node"
|
|
259
|
+
import path from "node:path"
|
|
260
|
+
import { fileURLToPath } from "node:url"
|
|
693
261
|
|
|
694
|
-
|
|
262
|
+
const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..")
|
|
695
263
|
|
|
696
|
-
|
|
697
|
-
|
|
698
|
-
|
|
699
|
-
}
|
|
264
|
+
const result = await generateEnvArtifacts({
|
|
265
|
+
fs: nodeBuildFileSystem,
|
|
266
|
+
root,
|
|
267
|
+
manifest: { location: "src/generated/env.manifest.ts" },
|
|
268
|
+
docs: {
|
|
269
|
+
location: "docs/ENVIRONMENT.md",
|
|
270
|
+
envExample: { location: ".env.example", onExisting: "keep-sibling" },
|
|
271
|
+
},
|
|
272
|
+
usage: { report: { location: "docs/ENV-OWNERSHIP.md" } },
|
|
273
|
+
})
|
|
700
274
|
```
|
|
701
275
|
|
|
702
|
-
|
|
703
|
-
|
|
704
|
-
See [`specs/migrations/`](specs/migrations/) for the full, tool-specific guides this section summarizes.
|
|
705
|
-
|
|
706
|
-
## Security model
|
|
276
|
+
What the build step promises, and where it stops:
|
|
707
277
|
|
|
708
|
-
|
|
278
|
+
| Promise | Test | Limit |
|
|
279
|
+
| --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
|
|
280
|
+
| Schema files are parsed, never imported or run | `test/build/parse.test.ts` (a throwing top-level statement never runs) | Lint does not ban `import()` or `vm` in `src/build`; reviewers check that |
|
|
281
|
+
| Only literal values are resolved; anything dynamic is reported as unresolved | `test/build/parse.test.ts`, `test/build/literal-eval.test.ts` | None found |
|
|
282
|
+
| An output path that is absolute outside `root`, or climbs out with `..`, fails before writing | `test/build/manifest-generate.test.ts`, `documentation-generate.test.ts` | The check is lexical; a symlinked directory inside `root` can lead outside |
|
|
283
|
+
| An existing `.env.example` is never overwritten by default | `test/build/env-example.test.ts` | `onExisting: "overwrite"` opts out |
|
|
284
|
+
| Discovery never enters `node_modules` or `.git` | `test/build/discover.test.ts` | None found |
|
|
709
285
|
|
|
710
|
-
|
|
286
|
+
Every artifact separates **declared** facts from **proven** ones. Declared facts come from `documentEnv()`: owner, sensitivity, expiry. env-cap checks they are present, never that they are true. Proven facts come from the syntax tree: which variables are consumed, and the dependency graph. [`specs/generated-artifacts.md`](specs/generated-artifacts.md) lists each artifact and the models it reads.
|
|
711
287
|
|
|
712
|
-
|
|
713
|
-
- does not fetch secrets
|
|
714
|
-
- does not transmit telemetry
|
|
715
|
-
- does not execute lifecycle commands
|
|
716
|
-
- does not log secret values
|
|
717
|
-
- does not include documentation metadata in runtime contracts
|
|
288
|
+
### Change tracking via the evidence file
|
|
718
289
|
|
|
719
|
-
|
|
290
|
+
Pass `evidence` to also write the full Evidence Model, with a change report against the previous file:
|
|
720
291
|
|
|
721
292
|
```ts
|
|
722
|
-
|
|
723
|
-
|
|
724
|
-
|
|
725
|
-
|
|
726
|
-
|
|
727
|
-
|
|
728
|
-
EnvContract("payments") { 1 variable(s) }
|
|
729
|
-
```
|
|
730
|
-
|
|
731
|
-
not:
|
|
293
|
+
const result = await generateEnvArtifacts({
|
|
294
|
+
fs: nodeBuildFileSystem,
|
|
295
|
+
root,
|
|
296
|
+
manifest: { location: "src/generated/env.manifest.ts" },
|
|
297
|
+
evidence: { location: "docs/env.evidence.json" },
|
|
298
|
+
})
|
|
732
299
|
|
|
733
|
-
|
|
734
|
-
|
|
735
|
-
|
|
736
|
-
}
|
|
300
|
+
result.evidence.change.manifest.addedVariables
|
|
301
|
+
result.evidence.change.manifest.updatedVariables
|
|
302
|
+
result.evidence.change.manifest.removedVariables
|
|
737
303
|
```
|
|
738
304
|
|
|
739
|
-
|
|
305
|
+
Writing it also writes `docs/env.evidence.json.fingerprint`, a content hash `getEvidenceModel()` uses to skip a rebuild when nothing changed.
|
|
740
306
|
|
|
741
|
-
|
|
742
|
-
paymentsEnv.STRIPE_KEY
|
|
743
|
-
```
|
|
307
|
+
Commit both files, as you commit the manifest. The diff then means "since the last commit on this branch", which a reviewer can read ([ADR 0038](specs/decisions/0038-always-computed-evidence-model-backs-generate-check-docs.md)).
|
|
744
308
|
|
|
745
|
-
|
|
309
|
+
1. A diff is expected when a `documentEnv()` field or a contract's `active`, `category` or `exclusiveGroup` changes.
|
|
310
|
+
2. Every run with `--evidence` rewrites both files; there is no separate update step.
|
|
311
|
+
3. A diff worth a second look is one nobody meant to make, such as an `updatedVariables` entry in an unrelated change.
|
|
746
312
|
|
|
747
|
-
|
|
313
|
+
Two active contracts that document the same variable differently produce a `DUPLICATE_VARIABLE_DOCUMENTATION` warning, which only `--strict` turns into an error.
|
|
748
314
|
|
|
749
|
-
|
|
315
|
+
### Reusable packages
|
|
750
316
|
|
|
751
|
-
|
|
317
|
+
A package can ship its own contract, and a consuming application can discover it. Discovery is opt-in, by exact package name:
|
|
752
318
|
|
|
753
|
-
|
|
754
|
-
|
|
755
|
-
|
|
756
|
-
|
|
757
|
-
|
|
758
|
-
|
|
759
|
-
|
|
760
|
-
| `EnvProjectGenerationError` | `generateEnvArtifacts()` | Any of the above errors aggregated across requested generation steps (manifest/docs/usage), or a provable manifest-pass compatibility/exclusive-group issue | Apply the fix for the underlying error. `generateEnvArtifacts()` combines failures into one result instead of failing independently per generation step |
|
|
761
|
-
|
|
762
|
-
**Documentation completeness and dependency ownership never throw.** An undocumented contract/variable
|
|
763
|
-
or an unconsumed owned dependency is a heuristic signal, not a provable defect the way a manifest
|
|
764
|
-
compatibility conflict is — both have real, common false-positive causes (a webhook handler in another
|
|
765
|
-
repo, a shell script reading the variable, a package outside the `packages` allowlist). They're
|
|
766
|
-
reported as `Finding`s (`documentation`/`ownership` families) on the persisted evidence artifact
|
|
767
|
-
instead; gate CI on them yourself by reading `--evidence`'s `finding` field if you want that
|
|
768
|
-
enforced. See [ADR 0038](specs/decisions/0038-always-computed-evidence-model-backs-generate-check-docs.md).
|
|
319
|
+
```ts
|
|
320
|
+
await generateEnvArtifacts({
|
|
321
|
+
fs: nodeBuildFileSystem,
|
|
322
|
+
packages: ["@acme/payments-sdk"],
|
|
323
|
+
manifest: { location: "src/env.manifest.ts" },
|
|
324
|
+
})
|
|
325
|
+
```
|
|
769
326
|
|
|
770
|
-
|
|
327
|
+
The publishing package does two things:
|
|
771
328
|
|
|
772
|
-
|
|
329
|
+
1. Declare `"envCap": { "schema": "./src/env.schema.ts" }` in its `package.json`, and ship that `.ts` file in `files`.
|
|
330
|
+
2. Re-export the `createEnv()` contract under the same name from its main entry.
|
|
773
331
|
|
|
774
|
-
|
|
332
|
+
Resolution reads one `package.json` and one declared file per listed package, and never calls `readdir`. It rejects a symlink escaping the package and a file over the size cap (`test/build/resolution/resolve-package-schema.test.ts`). The runnable pair is [`paypal-addon`](https://github.com/MaverickCER/env-cap/tree/main/test/integration/positive/enterprise/paypal-addon) and [`paypal-consumer`](https://github.com/MaverickCER/env-cap/tree/main/test/integration/positive/enterprise/paypal-consumer); their CI job does not yet block a merge.
|
|
775
333
|
|
|
776
|
-
|
|
334
|
+
An application can document a package's variable again with only its own fields, such as `expiresAt` and `owner`. Fields it leaves unset come from the package's declaration. A field both set differently is reported as `DUPLICATE_VARIABLE_DOCUMENTATION` ([ADR 0050](specs/decisions/0050-a-variable-declared-twice-is-documented-once.md)).
|
|
777
335
|
|
|
778
|
-
|
|
336
|
+
### TypeScript path aliases (paths/baseUrl)
|
|
779
337
|
|
|
780
|
-
|
|
338
|
+
A contract imported through an alias such as `@/features/payments/env.schema.js` is resolved with no configuration. Without it, that contract would be reported as abandoned.
|
|
781
339
|
|
|
782
|
-
|
|
340
|
+
- `tsconfig.json` is read from `root` exactly; there is no upward search.
|
|
341
|
+
- Pass `tsconfig: "tsconfig.build.json"` to use another file, or `tsconfig: false` to turn resolution off.
|
|
342
|
+
- Matching uses TypeScript's own `ts.resolveModuleName()`. A result inside `node_modules` is discarded, so only `packages` can reach installed code ([ADR 0023](specs/decisions/0023-tsconfig-path-alias-resolution.md)).
|
|
783
343
|
|
|
784
|
-
|
|
344
|
+
### Requirements
|
|
785
345
|
|
|
786
|
-
|
|
346
|
+
| Need | Detail |
|
|
347
|
+
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
|
|
348
|
+
| Node.js | `>=22`. CI tests 22 and 24; 26 runs as an informational job |
|
|
349
|
+
| TypeScript (optional) | The build entry uses yours when it is 5 or 6, and otherwise the bundled TypeScript 6 (`test/build/typescript-bundled.test.ts`) |
|
|
350
|
+
| TypeScript versions in CI | The newest 5.x, 6.x and 7.x, in a job that does not yet block a merge; the `^5.0.0` floor is not tested |
|
|
351
|
+
| `moduleResolution` | `node16`, `nodenext` or `bundler`, checked by the `TypeResolution` check; `node10` cannot resolve subpath exports |
|
|
352
|
+
| `./eslint-plugin` | Also needs `eslint` and `@typescript-eslint/utils`; versions in [ADOPTION's dependency table](ADOPTION.md#security--threat-model) |
|
|
787
353
|
|
|
788
|
-
The
|
|
354
|
+
The bundled TypeScript 6 compiler is the package's one dependency. Only the build entry loads it, and `compiler-isolation` fails the build if a runtime entry can reach it ([ADR 0049](specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md)). It is the price of scanning TypeScript 7 projects, whose compiler has no classic API.
|
|
789
355
|
|
|
790
|
-
|
|
356
|
+
### Package managers
|
|
791
357
|
|
|
792
|
-
|
|
358
|
+
npm is the supported package manager, and every CI job installs with it. The `package-managers` job checks pnpm, Yarn 1 and Yarn Berry with the `node-modules` linker. It checks one thing: the tarball installs and every entry imports as ESM and CommonJS. That job does not yet block a merge. Yarn Plug'n'Play and non-hoisted pnpm are unsupported.
|
|
793
359
|
|
|
794
360
|
## CLI
|
|
795
361
|
|
|
796
|
-
|
|
362
|
+
**What it solves:** the same artifacts and drift check in any CI system, from one command.
|
|
797
363
|
|
|
798
|
-
```
|
|
799
|
-
npx env-cap
|
|
800
|
-
--location src/generated/env.manifest.ts \
|
|
801
|
-
--evidence docs/env.evidence.json \
|
|
802
|
-
--strict
|
|
364
|
+
```sh
|
|
365
|
+
npx env-cap --location src/generated/env.manifest.ts --evidence docs/env.evidence.json --strict
|
|
803
366
|
```
|
|
804
367
|
|
|
805
|
-
The CLI
|
|
806
|
-
|
|
807
|
-
The CLI's own surface is deliberately narrow -- see [ADR 0046](specs/decisions/0046-cli-restricted-to-runtime-and-evidence-output.md):
|
|
808
|
-
only outputs with a real runtime consumer (the manifest) or that are inherent
|
|
809
|
-
to the tool's own evidence/reporting contract (`--evidence`/`--json`/`--check`)
|
|
810
|
-
get a flag. The rich Markdown docs catalog, the dependency & ownership
|
|
811
|
-
report, and a reconciled `.env.example` have no such consumer -- nothing
|
|
812
|
-
imports them the way application code imports the generated manifest -- so
|
|
813
|
-
generating them is a few lines of application code instead, calling
|
|
814
|
-
`@maverickcer/env-cap/build`'s exported `generateDocumentation()`/`generateUsageReport()`
|
|
815
|
-
directly:
|
|
368
|
+
The CLI writes only the manifest and the evidence file ([ADR 0046](specs/decisions/0046-cli-restricted-to-runtime-and-evidence-output.md)). The documentation catalog, the ownership report and `.env.example` come from your own script calling `@maverickcer/env-cap/build`. This one is from [`examples/application/scripts/generate-docs/run.ts`](https://github.com/MaverickCER/env-cap/blob/main/examples/application/scripts/generate-docs/run.ts):
|
|
816
369
|
|
|
817
370
|
```ts
|
|
818
371
|
import { generateDocumentation, generateUsageReport } from "@maverickcer/env-cap/build"
|
|
819
372
|
import { nodeBuildFileSystem } from "@maverickcer/env-cap/node"
|
|
820
373
|
|
|
821
|
-
await generateDocumentation({
|
|
374
|
+
const docs = await generateDocumentation({
|
|
822
375
|
fs: nodeBuildFileSystem,
|
|
376
|
+
root,
|
|
377
|
+
include,
|
|
823
378
|
location: "docs/ENVIRONMENT.md",
|
|
824
|
-
// Never overwrites a file that already exists at `envExample.location` by
|
|
825
|
-
// default -- it writes a timestamped sibling instead, for you to
|
|
826
|
-
// diff/merge by hand. Pass `onExisting: "overwrite"` to replace it
|
|
827
|
-
// directly, or `"skip"` to write nothing at all when one is already
|
|
828
|
-
// present -- see `EnvExampleOnExisting`.
|
|
829
379
|
envExample: { location: ".env.example", onExisting: "overwrite" },
|
|
830
380
|
})
|
|
831
381
|
|
|
832
|
-
await generateUsageReport({
|
|
382
|
+
const usage = await generateUsageReport({
|
|
833
383
|
fs: nodeBuildFileSystem,
|
|
834
|
-
|
|
384
|
+
root,
|
|
385
|
+
include,
|
|
386
|
+
report: { location: "docs/OWNERSHIP.md" },
|
|
835
387
|
})
|
|
836
388
|
```
|
|
837
389
|
|
|
838
|
-
`checkEnvArtifacts()` is the
|
|
839
|
-
takes the same `docs`/`usage` options -- see any of this repo's own
|
|
840
|
-
`examples/*/scripts/generate-docs/` directories for a complete, wired-up
|
|
841
|
-
`run.ts`/`check.ts` pair to copy from.
|
|
842
|
-
|
|
843
|
-
Common uses include:
|
|
844
|
-
|
|
845
|
-
- generating environment manifests
|
|
846
|
-
- generating the persisted evidence artifact for reporting/CI
|
|
847
|
-
- enforcing configuration ownership rules
|
|
848
|
-
- detecting undocumented or stale configuration changes
|
|
849
|
-
- producing machine-readable reports for automation
|
|
390
|
+
`checkEnvArtifacts()` is the drift check `--check` uses, with the same `docs` and `usage` options. Each example's `scripts/generate-docs/check.ts` shows it wired up.
|
|
850
391
|
|
|
851
392
|
### Options
|
|
852
393
|
|
|
853
|
-
At least one of `--location` or `--evidence` is required.
|
|
854
|
-
|
|
855
|
-
| Flag | Meaning
|
|
856
|
-
| -------------------- |
|
|
857
|
-
| `--root <path>` | Directory that globs resolve from (default: the current directory).
|
|
858
|
-
| `--location <path>` | Output path for the generated manifest.
|
|
859
|
-
| `--include <glob>` | Schema-discovery glob. Repeatable. Default: `**/env.schema.ts`.
|
|
860
|
-
| `--exclude <glob>` | Glob to exclude from discovery. Repeatable.
|
|
861
|
-
| `--package <name>` | Installed package to also discover a schema from, through its `envCap.schema`
|
|
862
|
-
| `--tsconfig <path>` | `tsconfig.json` (relative to root) whose `paths` and `baseUrl` resolve aliased imports
|
|
863
|
-
| `--no-tsconfig` | Turn path-alias resolution off
|
|
864
|
-
| `--evidence <path>` | Also write the
|
|
865
|
-
| `--strict` | Escalate every warning
|
|
866
|
-
| `--strict-docs` | Escalate only documentation warnings
|
|
867
|
-
| `--strict-ownership` | Escalate only ownership warnings
|
|
868
|
-
| `--json` |
|
|
869
|
-
| `--check` |
|
|
870
|
-
| `--help`, `-h` | Show the help text.
|
|
394
|
+
At least one of `--location` or `--evidence` is required. `npx env-cap --help` prints the same list, and `test/docs-cli-flags.test.ts` fails if a flag has no row here.
|
|
395
|
+
|
|
396
|
+
| Flag | Meaning |
|
|
397
|
+
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
398
|
+
| `--root <path>` | Directory that globs resolve from (default: the current directory). |
|
|
399
|
+
| `--location <path>` | Output path for the generated manifest. |
|
|
400
|
+
| `--include <glob>` | Schema-discovery glob. Repeatable. Default: `**/env.schema.ts`. |
|
|
401
|
+
| `--exclude <glob>` | Glob to exclude from discovery. Repeatable. |
|
|
402
|
+
| `--package <name>` | Installed package to also discover a schema from, through its `envCap.schema` field. Repeatable. |
|
|
403
|
+
| `--tsconfig <path>` | `tsconfig.json` (relative to root) whose `paths` and `baseUrl` resolve aliased imports. Default: `tsconfig.json` at the root. |
|
|
404
|
+
| `--no-tsconfig` | Turn path-alias resolution off. |
|
|
405
|
+
| `--evidence <path>` | Also write the evidence file and its `.fingerprint` sidecar, for example `docs/env.evidence.json`. |
|
|
406
|
+
| `--strict` | Escalate every warning to an error: compatibility, documentation and ownership. Nothing is written when one fires. |
|
|
407
|
+
| `--strict-docs` | Escalate only documentation warnings: undocumented or stale entries, expiring or expired entries, and unresolvable `documentEnv()` links. |
|
|
408
|
+
| `--strict-ownership` | Escalate only ownership warnings: abandoned contracts, unresolved consumers, unconsumed owned variables, indeterminate ownership, stale or missing `dynamicAccess` citations. |
|
|
409
|
+
| `--json` | Print a machine-readable report instead of text. |
|
|
410
|
+
| `--check` | Write nothing; exit `1` if any generated artifact is stale or missing. |
|
|
411
|
+
| `--help`, `-h` | Show the help text. |
|
|
412
|
+
|
|
413
|
+
The CLI exits `0` on success. It exits `1` on any error, a warning escalated by `--strict*`, or a bad argument.
|
|
414
|
+
|
|
415
|
+
Info findings never escalate. Without a `--strict*` flag, documentation and ownership findings never fail a run. Exclusive-group violations and conflicting explicit processor types always fail (`test/cli/main.test.ts`, `test/build/exclusive-group.test.ts`).
|
|
871
416
|
|
|
872
417
|
### `--json`
|
|
873
418
|
|
|
874
|
-
|
|
875
|
-
|
|
876
|
-
The output contains the same generated artifact information returned by `generateEnvArtifacts()` wrapped in a stable JSON envelope:
|
|
877
|
-
|
|
878
|
-
```bash
|
|
879
|
-
npx env-cap \
|
|
880
|
-
--location src/generated/env.manifest.ts \
|
|
881
|
-
--evidence docs/env.evidence.json \
|
|
882
|
-
--json
|
|
883
|
-
```
|
|
884
|
-
|
|
885
|
-
Example:
|
|
419
|
+
`--json` prints a versioned report instead of text. It changes the format only; the exit code is the same. An abbreviated example:
|
|
886
420
|
|
|
887
421
|
```jsonc
|
|
888
422
|
{
|
|
@@ -890,77 +424,55 @@ Example:
|
|
|
890
424
|
"kind": "env-cap-report",
|
|
891
425
|
"toolVersion": "<installed env-cap version>",
|
|
892
426
|
"ok": true,
|
|
893
|
-
"manifest": {
|
|
894
|
-
|
|
895
|
-
"contracts": [/* discovered contracts */],
|
|
896
|
-
},
|
|
897
|
-
// "evidence" appears when --evidence is passed. "docs"/"usage" no longer
|
|
898
|
-
// appear from the CLI at all (ADR 0046) -- call `generateDocumentation()`/
|
|
899
|
-
// `generateUsageReport()` directly for that shape.
|
|
427
|
+
"manifest": { "outputPath": "...", "contracts": [] },
|
|
428
|
+
// "evidence" appears when --evidence is passed.
|
|
900
429
|
}
|
|
901
430
|
```
|
|
902
431
|
|
|
903
|
-
|
|
904
|
-
`usage` -- is defined by the [published JSON Schema](#published-json-schema) below
|
|
905
|
-
rather than repeated here.
|
|
906
|
-
|
|
907
|
-
`--json` changes output formatting only. Exit-code behavior remains unchanged.
|
|
908
|
-
|
|
909
|
-
New fields may be added without a `schemaVersion` change. Consumers should ignore properties they do not recognize.
|
|
910
|
-
|
|
911
|
-
See [ADR 0013](specs/decisions/0013-json-output-is-a-versioned-mirror.md).
|
|
432
|
+
New fields may appear without a `schemaVersion` change, so ignore properties you do not recognize ([ADR 0013](specs/decisions/0013-json-output-is-a-versioned-mirror.md)).
|
|
912
433
|
|
|
913
434
|
#### Published JSON Schema
|
|
914
435
|
|
|
915
|
-
|
|
916
|
-
[`schemas/env-cap-report.schema.json`](schemas/env-cap-report.schema.json), also
|
|
917
|
-
resolvable as `@maverickcer/env-cap/schema` -- for external, non-TypeScript tooling
|
|
918
|
-
(a Go service, a Python dashboard, a generic CI linter) to validate or codegen
|
|
919
|
-
against without hand-transcribing the shape above.
|
|
436
|
+
The report's schema is [`schemas/env-cap-report.schema.json`](schemas/env-cap-report.schema.json), importable as `@maverickcer/env-cap/schema`. It is generated from `src/cli/json.ts`, and the `Schema` check fails if the committed file differs ([ADR 0019](specs/decisions/0019-published-json-schema-generated-from-types.md)).
|
|
920
437
|
|
|
921
|
-
|
|
922
|
-
|
|
923
|
-
|
|
924
|
-
schema change; a changed or removed field is.
|
|
925
|
-
|
|
926
|
-
See [ADR 0019](specs/decisions/0019-published-json-schema-generated-from-types.md).
|
|
438
|
+
- Real success, failure and `--check` payloads validate against it (`test/build/json-schema.test.ts`).
|
|
439
|
+
- The committed evidence files of two examples validate against its `EvidenceModel` definition, in the same test file.
|
|
440
|
+
- A changed or removed field is meant to bump `schemaVersion`. No check enforces that yet; the `SurfaceContract` check enforces the changeset level.
|
|
927
441
|
|
|
928
442
|
### `--check`
|
|
929
443
|
|
|
930
|
-
|
|
931
|
-
|
|
932
|
-
This is useful as a CI drift check when a schema changes but generated artifacts were not updated:
|
|
444
|
+
`--check` recomputes every requested artifact in memory and compares it with the committed file. It never writes ([ADR 0016](specs/decisions/0016-check-mode-compute-before-compare-never-partial-write.md)).
|
|
933
445
|
|
|
934
|
-
```
|
|
935
|
-
npx env-cap
|
|
936
|
-
--location src/generated/env.manifest.ts \
|
|
937
|
-
--evidence docs/env.evidence.json \
|
|
938
|
-
--check
|
|
446
|
+
```sh
|
|
447
|
+
npx env-cap --location src/generated/env.manifest.ts --evidence docs/env.evidence.json --check
|
|
939
448
|
```
|
|
940
449
|
|
|
941
|
-
|
|
450
|
+
| Exit code | Meaning | Line of output |
|
|
451
|
+
| --------- | ------------------------------- | ----------------------------------------- |
|
|
452
|
+
| `0` | Every artifact matches | `All generated artifacts are up to date.` |
|
|
453
|
+
| `1` | An artifact is stale or missing | `<n> artifact(s) are stale or missing.` |
|
|
942
454
|
|
|
943
|
-
|
|
944
|
-
- `1` when artifacts are missing or stale
|
|
455
|
+
With `--json`, the report carries a `checkResult` field: `ok` is the verdict and `stale` names each stale artifact (`test/build/check-artifacts.test.ts`).
|
|
945
456
|
|
|
946
|
-
|
|
457
|
+
### Using the CLI outside GitHub Actions
|
|
947
458
|
|
|
948
|
-
|
|
459
|
+
GitLab, Jenkins or Buildkite get the same gate from the CLI alone.
|
|
949
460
|
|
|
950
|
-
|
|
461
|
+
1. Install the package as a devDependency and run:
|
|
951
462
|
|
|
952
|
-
|
|
463
|
+
```sh
|
|
464
|
+
npx env-cap --location src/generated/env.manifest.ts --evidence docs/env.evidence.json --check --json > env-cap.json
|
|
465
|
+
```
|
|
953
466
|
|
|
954
|
-
|
|
467
|
+
2. Fail the job on the exit code: `0` when every artifact is current, `1` when one is stale or missing or the run failed.
|
|
468
|
+
3. Read `checkResult` in `env-cap.json` for the verdict. For per-finding severity, file and line, read `finding.findings` in the evidence file.
|
|
469
|
+
4. For a SARIF upload, pass the persisted Finding Model to `buildSarifLog` from `@maverickcer/env-cap/build` ([evidence](#reviewers-evidence)).
|
|
955
470
|
|
|
956
|
-
|
|
471
|
+
The CLI reads no `GITHUB_` variable today. No check enforces that, so read it as a description of the current code.
|
|
957
472
|
|
|
958
|
-
|
|
959
|
-
- inline pull request annotations
|
|
960
|
-
- sticky summary comments
|
|
961
|
-
- scheduled rotation monitoring
|
|
473
|
+
## GitHub Action
|
|
962
474
|
|
|
963
|
-
|
|
475
|
+
**What it solves:** drift and findings show up on the pull request, as annotations and one summary comment.
|
|
964
476
|
|
|
965
477
|
```yaml
|
|
966
478
|
# .github/workflows/env-cap.yml
|
|
@@ -976,67 +488,48 @@ permissions:
|
|
|
976
488
|
jobs:
|
|
977
489
|
report:
|
|
978
490
|
runs-on: ubuntu-latest
|
|
979
|
-
|
|
980
491
|
steps:
|
|
981
492
|
- uses: actions/checkout@v4
|
|
982
|
-
|
|
493
|
+
- run: npm ci # the Action runs the env-cap your project installs
|
|
983
494
|
- uses: maverickcer/env-cap@v0
|
|
984
495
|
with:
|
|
985
496
|
args: "--location src/generated/env.manifest.ts --evidence docs/env.evidence.json"
|
|
986
497
|
```
|
|
987
498
|
|
|
988
|
-
|
|
989
|
-
`latest`: with no local install it needs `with: version: "<x.y.z>"` and otherwise fails with an
|
|
990
|
-
explanation. Inputs reach the CLI through environment variables, not shell text, so a PR-controlled
|
|
991
|
-
value forwarded into `args` cannot become a command.
|
|
992
|
-
|
|
993
|
-
What this action reports (data-cap's sibling action reports the same sections minus the rotation
|
|
994
|
-
alert): inline `::warning`/`::error` annotations, one sticky pull-request comment per `report-key`,
|
|
995
|
-
and -- env-cap only, on runs with no pull request -- a GitHub issue for expiring or expired
|
|
996
|
-
variables (`rotation-alert`, needs `issues: write`), closed again once nothing is expiring.
|
|
997
|
-
|
|
998
|
-
`args` only reaches the CLI, so it can only drive `--location`/`--evidence`/
|
|
999
|
-
`--strict`-family flags (ADR 0046) -- the persisted evidence artifact this
|
|
1000
|
-
produces is what the Action's own PR annotations/summary comment/rotation
|
|
1001
|
-
alerts read from (Finding Model, ADR 0038), regardless of whether your repo
|
|
1002
|
-
also generates `docs/ENVIRONMENT.md`/`docs/ENV-OWNERSHIP.md` as a separate step (the scaffolded default is `ENV-OWNERSHIP.md` so it never collides with a sibling package's ownership report).
|
|
1003
|
-
|
|
1004
|
-
| Input | Default | Purpose |
|
|
1005
|
-
| ------------------- | --------------------- | ----------------------------------------------------------------------------------------------------- |
|
|
1006
|
-
| `args` | _(required)_ | Arguments passed to `env-cap --json`, such as `--location`, `--evidence`, and strict validation flags |
|
|
1007
|
-
| `working-directory` | `.` | Directory where `env-cap` executes |
|
|
1008
|
-
| `version` | _(latest)_ | Version to execute through `npx` when `env-cap` is not installed locally |
|
|
1009
|
-
| `comment` | `true` | Creates or updates a sticky pull request summary comment |
|
|
1010
|
-
| `annotations` | `true` | Emits GitHub workflow annotations for detected issues |
|
|
1011
|
-
| `rotation-alert` | `true` | Enables scheduled expiration reporting outside pull requests |
|
|
1012
|
-
| `report-key` | _(working-directory)_ | Identifies this report when multiple workflows run against the same pull request |
|
|
1013
|
-
| `github-token` | `${{ github.token }}` | Token used for the `gh` CLI calls that post/update PR comments and rotation-alert issues |
|
|
1014
|
-
|
|
1015
|
-
The Action does not create its own policy layer. Pass/fail behavior always follows the CLI exit code and whatever `--strict`/`--strict-docs`/`--strict-ownership` combination this invocation's own `args` input passes (ADR 0044 — see [Troubleshooting](#troubleshooting)). A finding family with no matching `--strict*` flag never fails the run on its own; read it from `--evidence`'s output and gate on it in your own workflow step if you want that enforced.
|
|
499
|
+
How the Action behaves, and what tests it:
|
|
1016
500
|
|
|
1017
|
-
|
|
501
|
+
1. It runs the env-cap your project installs. It looks for `node_modules/.bin/env-cap` inside `working-directory`; in a hoisted monorepo, set `version` or run from the root. With none found, it needs a `version` input and exits `2` without one (`test/scripts/github-action-run-cli.test.ts`).
|
|
502
|
+
2. A `version` must be a plain version or a dist-tag. `latest` is a dist-tag and is accepted, so pin a version instead.
|
|
503
|
+
3. Inputs reach the CLI as environment variables, never as shell text. `args` is split into words, so a forwarded value can add CLI flags.
|
|
504
|
+
4. Its pass or fail is the CLI's exit code. It adds no policy of its own; a finding family fails only under its `--strict*` flag in `args`.
|
|
505
|
+
5. Annotations and the summary comment are computed from the CLI report and the evidence file. Pass `--evidence` to get documentation, ownership and expiry reporting.
|
|
1018
506
|
|
|
1019
|
-
|
|
507
|
+
The report functions are unit-tested with a real CLI payload (`test/scripts/github-action-report.test.ts`). The `gh` calls that post comments and issues are not run in CI.
|
|
1020
508
|
|
|
1021
|
-
|
|
509
|
+
| Input | Default | Purpose |
|
|
510
|
+
| ------------------- | ----------------------- | ---------------------------------------------------------------------------------------- |
|
|
511
|
+
| `args` | _(required)_ | Arguments passed to `env-cap --json`, such as `--location`, `--evidence` and `--strict*` |
|
|
512
|
+
| `working-directory` | `.` | Directory where `env-cap` runs |
|
|
513
|
+
| `version` | _(none; required then)_ | Version to run through `npx` when env-cap is not installed; pin one rather than `latest` |
|
|
514
|
+
| `comment` | `true` | Create or update one sticky summary comment on the pull request |
|
|
515
|
+
| `annotations` | `true` | Emit inline workflow annotations |
|
|
516
|
+
| `rotation-alert` | `true` | On runs with no pull request, report expiring variables in an issue |
|
|
517
|
+
| `report-key` | _(working-directory)_ | Identifies this report when several jobs comment on one pull request |
|
|
518
|
+
| `github-token` | `${{ github.token }}` | Token for the `gh` calls that post comments and issues |
|
|
1022
519
|
|
|
1023
|
-
|
|
520
|
+
### Monorepos
|
|
1024
521
|
|
|
1025
|
-
|
|
522
|
+
Give each parallel invocation its own `report-key`, so jobs do not overwrite each other's comments. For one combined report, upload each job's `--json` output and merge them in a final step.
|
|
1026
523
|
|
|
1027
|
-
|
|
524
|
+
The Action looks for `node_modules/.bin/env-cap` inside `working-directory`; in a hoisted monorepo, set `version` or run from the root.
|
|
1028
525
|
|
|
1029
|
-
|
|
526
|
+
### Reusable packages and external contracts
|
|
1030
527
|
|
|
1031
|
-
|
|
528
|
+
Contracts discovered through `packages` appear in the same annotations and comment. Their files sit in `node_modules`, outside the diff, so their findings appear only in the summary comment.
|
|
1032
529
|
|
|
1033
530
|
### Scheduled rotation alerts
|
|
1034
531
|
|
|
1035
|
-
The same Action can run
|
|
1036
|
-
|
|
1037
|
-
This is useful for detecting variables that are approaching expiration or have exceeded their documented rotation window.
|
|
1038
|
-
|
|
1039
|
-
Example:
|
|
532
|
+
The same Action can run on a schedule and report expiring variables in an issue:
|
|
1040
533
|
|
|
1041
534
|
```yaml
|
|
1042
535
|
# .github/workflows/env-cap-rotation.yml
|
|
@@ -1054,161 +547,189 @@ permissions:
|
|
|
1054
547
|
jobs:
|
|
1055
548
|
check-rotation:
|
|
1056
549
|
runs-on: ubuntu-latest
|
|
1057
|
-
|
|
1058
550
|
steps:
|
|
1059
551
|
- uses: actions/checkout@v4
|
|
1060
|
-
|
|
552
|
+
- run: npm ci
|
|
1061
553
|
- uses: maverickcer/env-cap@v0
|
|
1062
554
|
with:
|
|
1063
555
|
args: "--location src/generated/env.manifest.ts --evidence docs/env.evidence.json"
|
|
1064
556
|
```
|
|
1065
557
|
|
|
1066
|
-
The
|
|
558
|
+
1. The list comes from the evidence file's Lifecycle Model, so `--evidence` is required.
|
|
559
|
+
2. The window is the library's default (`DEFAULT_EXPIRING_WITHIN_DAYS`); the CLI has no flag to change it.
|
|
560
|
+
3. With no pull request, the Action opens or updates an issue listing expiring or expired variables.
|
|
561
|
+
4. When nothing is expiring, it decides to close that issue. The decision is unit-tested; the `gh` call is not run in CI.
|
|
1067
562
|
|
|
1068
|
-
|
|
563
|
+
Set `rotation-alert: "false"` to turn issues off ([ADR 0018](specs/decisions/0018-rotation-alert-issue-on-non-pr-runs.md)).
|
|
1069
564
|
|
|
1070
|
-
|
|
565
|
+
## Reviewers: evidence
|
|
1071
566
|
|
|
1072
|
-
|
|
567
|
+
**What it solves:** an inventory of every variable, its owner and its expiry, with findings you can trace to a file and line. The outputs support a review, nothing more.
|
|
1073
568
|
|
|
1074
|
-
|
|
569
|
+
The evidence file is a serialized `EvidenceModel` with these members:
|
|
1075
570
|
|
|
1076
|
-
|
|
571
|
+
| Member | What it holds |
|
|
572
|
+
| --------------- | -------------------------------------------------------------------------------------------------------------- |
|
|
573
|
+
| `schemaVersion` | The evidence format's version |
|
|
574
|
+
| `provenance` | When it was generated, by which env-cap version, at which commit |
|
|
575
|
+
| `contract` | Every contract and variable, with declared documentation |
|
|
576
|
+
| `dependency` | Which code consumes which variable, computed from the syntax tree; dynamic access is reported as indeterminate |
|
|
577
|
+
| `ownership` | Owners, abandoned contracts and unconsumed owned variables |
|
|
578
|
+
| `lifecycle` | Expiry, rotation fields and the computed `rotationStatus` |
|
|
579
|
+
| `finding` | Every finding, with family, severity and position where one is known |
|
|
580
|
+
| `change` | What changed since the previous evidence file |
|
|
581
|
+
|
|
582
|
+
`rotationStatus` is a judgement over declared dates and periods. It never states that a rotation happened or that a control is met. Its values are `compliant`, `overdue`, `expired` and `undeclared`. `compliant` means only that the declared dates fall within the declared period; 1.0 renames it `withinPolicy`.
|
|
583
|
+
|
|
584
|
+
### Findings and SARIF
|
|
1077
585
|
|
|
1078
|
-
`@maverickcer/env-cap/
|
|
586
|
+
`buildSarifLog` from `@maverickcer/env-cap/build` turns the Finding Model into SARIF 2.1.0. Its output validates against the official OASIS schema, with and without positions (`test/build/sarif.test.ts`). It is a library export; the CLI does not write SARIF.
|
|
1079
587
|
|
|
1080
|
-
|
|
588
|
+
### Projections
|
|
1081
589
|
|
|
1082
|
-
|
|
1083
|
-
|
|
590
|
+
`defineEvidenceProjection()` from `@maverickcer/env-cap/evidence` turns the model into any shape you need. It also records which model paths each output field read (`test/evidence/define-projection.test.ts`). This one is trimmed from [`inventory.mjs`](https://github.com/MaverickCER/env-cap/blob/main/test/integration/positive/enterprise/evidence-projections/projections/inventory.mjs):
|
|
591
|
+
|
|
592
|
+
```ts
|
|
593
|
+
import { defineEvidenceProjection } from "@maverickcer/env-cap/evidence"
|
|
594
|
+
|
|
595
|
+
export const inventoryProjection = defineEvidenceProjection({
|
|
596
|
+
inventory: (evidence) =>
|
|
597
|
+
evidence.contract.contracts.map((contract) => ({
|
|
598
|
+
contractName: contract.contractName,
|
|
599
|
+
variables: contract.variables.map((variable) => variable.key),
|
|
600
|
+
})),
|
|
601
|
+
})
|
|
1084
602
|
```
|
|
1085
603
|
|
|
604
|
+
- `./evidence` imports no Node module and runs under Web globals only (`test/runtime/browser-bundle.test.ts`).
|
|
605
|
+
- It stays under 3 KB gzip, enforced by the `Size` check.
|
|
606
|
+
- `./evidence` and the `EvidenceModel` shape are Stable, and the `ApiContract` check diffs them. Before 1.0, a breaking change needs only a minor release.
|
|
607
|
+
|
|
608
|
+
[`examples/enterprise-platform`](https://github.com/MaverickCER/env-cap/tree/main/examples/enterprise-platform) builds a configuration-governance report this way.
|
|
609
|
+
|
|
610
|
+
## Build-script authors: the Node adapter
|
|
611
|
+
|
|
612
|
+
**What it solves:** `./build` never acquires a filesystem on its own, so your script hands it one.
|
|
613
|
+
|
|
614
|
+
```ts
|
|
615
|
+
import { generateEnvArtifacts } from "@maverickcer/env-cap/build"
|
|
616
|
+
import { nodeBuildFileSystem } from "@maverickcer/env-cap/node"
|
|
617
|
+
```
|
|
618
|
+
|
|
619
|
+
`./node` re-exports the CLI's `node:fs` adapter; only `src/cli` imports `node:fs`. `./node` does not read `process.env`. The `AmbientCapabilities` check enforces both. A non-Node runtime passes its own `BuildFileSystem` instead ([ADR 0040](specs/decisions/0040-library-surfaces-do-not-acquire-node-fs.md)).
|
|
620
|
+
|
|
621
|
+
## ESLint plugin
|
|
622
|
+
|
|
623
|
+
**What it solves:** direct `process.env` reads outside your contracts become lint errors, so ownership is enforced by tooling.
|
|
624
|
+
|
|
1086
625
|
```js
|
|
1087
626
|
// eslint.config.js
|
|
1088
|
-
|
|
1089
627
|
import envCapPlugin from "@maverickcer/env-cap/eslint-plugin"
|
|
1090
628
|
|
|
1091
629
|
export default [
|
|
1092
630
|
{
|
|
1093
631
|
files: ["**/*.ts"],
|
|
1094
|
-
plugins: {
|
|
1095
|
-
|
|
1096
|
-
},
|
|
1097
|
-
rules: {
|
|
1098
|
-
"env-cap/no-raw-process-env": "error",
|
|
1099
|
-
},
|
|
632
|
+
plugins: { "env-cap": envCapPlugin },
|
|
633
|
+
rules: { "env-cap/no-raw-process-env": "error" },
|
|
1100
634
|
},
|
|
1101
635
|
]
|
|
1102
636
|
```
|
|
1103
637
|
|
|
1104
|
-
|
|
638
|
+
The plugin needs `eslint` and `@typescript-eslint/utils`; [ADOPTION's dependency table](ADOPTION.md#security--threat-model) lists the ranges. Its tests run on ESLint 10 only; the declared ESLint 8.57 and 9 support is untested.
|
|
1105
639
|
|
|
1106
|
-
|
|
640
|
+
### `no-raw-process-env`
|
|
1107
641
|
|
|
1108
|
-
|
|
642
|
+
The rule reports `process.env` outside `env.schema.ts` and `env.schema.tsx` files (`test/eslint-plugin/no-raw-process-env.test.ts`). Nothing else is exempt unless you list it:
|
|
1109
643
|
|
|
1110
|
-
```
|
|
1111
|
-
|
|
644
|
+
```js
|
|
645
|
+
rules: {
|
|
646
|
+
"env-cap/no-raw-process-env": ["error", { allow: ["scripts/bootstrap-secrets.ts"] }],
|
|
647
|
+
}
|
|
1112
648
|
```
|
|
1113
649
|
|
|
1114
|
-
|
|
650
|
+
A one-off exception can use `// eslint-disable-next-line env-cap/no-raw-process-env` ([ADR 0017](specs/decisions/0017-eslint-plugin-entry-point.md)).
|
|
1115
651
|
|
|
1116
|
-
|
|
1117
|
-
paymentsEnv.STRIPE_KEY
|
|
1118
|
-
```
|
|
1119
|
-
|
|
1120
|
-
The rule does not prevent legitimate infrastructure or build-time code from accessing raw environment variables.
|
|
652
|
+
### `no-node-fs`
|
|
1121
653
|
|
|
1122
|
-
|
|
654
|
+
The rule reports `import`, `require` and `import()` of `fs`, `node:fs` and their `/promises` subpaths (`test/eslint-plugin/no-node-fs.test.ts`). Nothing is exempt unless you list it:
|
|
1123
655
|
|
|
1124
656
|
```js
|
|
1125
657
|
rules: {
|
|
1126
|
-
"env-cap/no-
|
|
1127
|
-
"error",
|
|
1128
|
-
{
|
|
1129
|
-
allow: ["scripts/bootstrap-secrets.ts"],
|
|
1130
|
-
},
|
|
1131
|
-
],
|
|
658
|
+
"env-cap/no-node-fs": ["error", { allow: ["src/cli/**", "scripts/**"] }],
|
|
1132
659
|
}
|
|
1133
660
|
```
|
|
1134
661
|
|
|
1135
|
-
|
|
662
|
+
It applies the rule env-cap follows itself: a library accepts a filesystem from its caller ([ADR 0040](specs/decisions/0040-library-surfaces-do-not-acquire-node-fs.md)).
|
|
1136
663
|
|
|
1137
|
-
|
|
1138
|
-
// eslint-disable-next-line env-cap/no-raw-process-env
|
|
1139
|
-
process.env.BOOTSTRAP_TOKEN
|
|
1140
|
-
```
|
|
664
|
+
## Architecture
|
|
1141
665
|
|
|
1142
|
-
|
|
666
|
+
### Runtime and build-time are intentionally separate
|
|
1143
667
|
|
|
1144
|
-
|
|
668
|
+
The runtime and the build tooling share one contract file and nothing else.
|
|
1145
669
|
|
|
1146
|
-
|
|
670
|
+
| Path | Entry points | What it does | Where it runs |
|
|
671
|
+
| ---------- | -------------------------------- | -------------------------------------------------------------------- | ---------------------------- |
|
|
672
|
+
| Runtime | `.`, `./helpers`, `./evidence` | Validates values, exposes typed access, projects evidence | Your application, at startup |
|
|
673
|
+
| Build-time | `./build`, CLI, `./node`, Action | Discovers contracts, analyzes source, writes manifests and documents | Development and CI only |
|
|
1147
674
|
|
|
1148
|
-
|
|
675
|
+
A run goes through four steps, in order:
|
|
1149
676
|
|
|
1150
|
-
|
|
1151
|
-
|
|
1152
|
-
|
|
1153
|
-
|
|
1154
|
-
|
|
1155
|
-
|
|
1156
|
-
|
|
1157
|
-
|
|
1158
|
-
},
|
|
1159
|
-
],
|
|
1160
|
-
}
|
|
1161
|
-
```
|
|
677
|
+
1. Each capability declares a contract with `createEnv()` and `documentEnv()`.
|
|
678
|
+
2. The build step parses every contract file and writes the manifest, documents and evidence.
|
|
679
|
+
3. The application imports the manifest and calls `validateEnv()` once at startup.
|
|
680
|
+
4. Code reads typed values through the contract that owns them.
|
|
681
|
+
|
|
682
|
+
A project can start with one central contract and split it later; the runtime model stays the same. [specs/architecture.md](specs/architecture.md) has the full treatment.
|
|
683
|
+
|
|
684
|
+
### Runtime support matrix
|
|
1162
685
|
|
|
1163
|
-
|
|
686
|
+
| Environment | `.` (runtime) | `./helpers` | `./evidence` | `./build`, CLI, `./node`, `./eslint-plugin` |
|
|
687
|
+
| ---------------------------------- | ---------------- | ------------------ | ---------------- | ------------------------------------------- |
|
|
688
|
+
| Node.js 22 and 24 (ESM and CJS) | Tested, blocking | Tested, blocking | Tested, blocking | Tested, blocking ⁴ |
|
|
689
|
+
| Web-globals bundle ¹ | Tested, blocking | Tested ², blocking | Tested, blocking | Not applicable |
|
|
690
|
+
| Bun and Deno | Executed in CI ³ | Executed in CI ³ | Executed in CI ³ | Not tested |
|
|
691
|
+
| Real browsers, edge and serverless | Not tested | Not tested | Not tested | Not applicable |
|
|
1164
692
|
|
|
1165
|
-
|
|
693
|
+
¹ Bundled with esbuild for the browser and run in a `node:vm` context with no `process`, `Buffer`, `require` or timers (`test/runtime/browser-bundle.test.ts`).
|
|
1166
694
|
|
|
1167
|
-
|
|
695
|
+
² Except `processors.base64()`, which returns a Node `Buffer`.
|
|
1168
696
|
|
|
1169
|
-
|
|
1170
|
-
runtime complexity into every environment variable access.
|
|
697
|
+
³ `bun-version: latest` and Deno `v2.x`, in a job that does not yet block a merge.
|
|
1171
698
|
|
|
1172
|
-
|
|
699
|
+
⁴ `./eslint-plugin`: unit tests block; its ESM and CJS import from the tarball runs only in the non-blocking `package-managers` job.
|
|
1173
700
|
|
|
1174
|
-
|
|
1175
|
-
|
|
1176
|
-
|
|
1177
|
-
- Repeated validation after the initial pass: O(1) through cached validation state.
|
|
701
|
+
ESM and CommonJS builds ship for every entry point, and the `PackedConsumer` check imports each one from the packed tarball except `./eslint-plugin`. A dual-package split fails fast with a `TypeError` instead of validating against the wrong schema ([SECURITY.md](SECURITY.md#dual-package-hazard)).
|
|
702
|
+
|
|
703
|
+
## Migration
|
|
1178
704
|
|
|
1179
|
-
|
|
1180
|
-
rather than repeatedly processing configuration during normal execution.
|
|
705
|
+
Adopt env-cap one contract at a time, and keep what you have:
|
|
1181
706
|
|
|
1182
|
-
|
|
1183
|
-
|
|
707
|
+
| Coming from | What changes |
|
|
708
|
+
| -------------------- | --------------------------------------------------------------------------------------------------------------------------- |
|
|
709
|
+
| `dotenv` | Keep loading with it; add a contract over the variables it loads |
|
|
710
|
+
| Raw `process.env` | Replace `process.env.STRIPE_KEY` with `env.STRIPE_KEY`, then move contracts next to their features |
|
|
711
|
+
| Zod, envalid, t3-env | Keep your schemas; call them from a validator: `validator: (value) => schema.safeParse(value).success \|\| "Invalid value"` |
|
|
1184
712
|
|
|
1185
|
-
|
|
1186
|
-
- Object construction: O(N)
|
|
1187
|
-
- Property lookup: O(1)
|
|
713
|
+
[`specs/migrations/`](specs/migrations/) has a guide per tool, each with a section on when to keep what you have.
|
|
1188
714
|
|
|
1189
|
-
|
|
1190
|
-
- Object construction: O(N)
|
|
1191
|
-
- Processing cost: O(N)
|
|
1192
|
-
- Validation cost: O(N)
|
|
715
|
+
## Performance
|
|
1193
716
|
|
|
1194
|
-
|
|
1195
|
-
validation, and access so repeated application usage remains constant-time.
|
|
717
|
+
Validation runs once, at startup. After it, reading a value is a property lookup on the frozen record of validated values.
|
|
1196
718
|
|
|
1197
|
-
|
|
1198
|
-
and regression tracking.
|
|
719
|
+
The [benchmark suite](./benchmarks/README.md) measures runtime and build-time cost as the number of variables grows. Pull requests from this repository are benchmarked, and a regression fails the `benchmark-pr` job. That job does not yet block a merge, and fork and bot pull requests are not measured. The growth class of `createEnv` is not yet determined on CI, so this guide states no complexity bound.
|
|
1199
720
|
|
|
1200
721
|
## Documentation index
|
|
1201
722
|
|
|
1202
|
-
| Doc
|
|
1203
|
-
|
|
|
1204
|
-
| This
|
|
1205
|
-
| [API reference](https://maverickcer.github.io/env-cap/api/)
|
|
1206
|
-
| [`specs/architecture.md`](specs/architecture.md)
|
|
1207
|
-
| [`specs/migrations/`](specs/migrations/)
|
|
1208
|
-
| [`ADOPTION.md`](ADOPTION.md)
|
|
1209
|
-
| [`SECURITY.md`](SECURITY.md)
|
|
1210
|
-
| [`VERSIONING.md`](VERSIONING.md)
|
|
1211
|
-
| [`CONTRIBUTING.md`](CONTRIBUTING.md)
|
|
1212
|
-
| [`CODE_REVIEW.md`](CODE_REVIEW.md)
|
|
1213
|
-
| [`RELEASING.md`](RELEASING.md)
|
|
1214
|
-
| [`SUPPORT.md`](SUPPORT.md)
|
|
723
|
+
| Doc | For |
|
|
724
|
+
| ------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
|
|
725
|
+
| This guide and the [docs site](https://maverickcer.github.io/env-cap/) | Using env-cap |
|
|
726
|
+
| [API reference](https://maverickcer.github.io/env-cap/api/) | Every exported symbol, generated from source |
|
|
727
|
+
| [`specs/architecture.md`](specs/architecture.md) and [`specs/decisions/`](specs/decisions/) | Why the package is shaped this way |
|
|
728
|
+
| [`specs/migrations/`](specs/migrations/) | Adopting env-cap beside dotenv, Zod, envalid or t3-env |
|
|
729
|
+
| [`ADOPTION.md`](ADOPTION.md) | What adopting costs, needs and refuses to do |
|
|
730
|
+
| [`SECURITY.md`](SECURITY.md) | What is enforced, where, and what is not |
|
|
731
|
+
| [`VERSIONING.md`](VERSIONING.md) | What semver covers; the tier of each entry point |
|
|
732
|
+
| [`CONTRIBUTING.md`](CONTRIBUTING.md) | Making a change |
|
|
733
|
+
| [`CODE_REVIEW.md`](CODE_REVIEW.md) | What a reviewer checks before merging |
|
|
734
|
+
| [`RELEASING.md`](RELEASING.md) | The release process |
|
|
735
|
+
| [`SUPPORT.md`](SUPPORT.md) | Where to ask questions and file bugs |
|