@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/README.md
CHANGED
|
@@ -6,25 +6,23 @@
|
|
|
6
6
|
[](https://maverickcer.github.io/env-cap/mutation.json)
|
|
7
7
|
[](https://scorecard.dev/viewer/?uri=github.com/MaverickCER/env-cap)
|
|
8
8
|
[](https://maverickcer.github.io/env-cap/size.json)
|
|
9
|
-
|
|
9
|
+

|
|
10
10
|
[](https://www.npmjs.com/package/@maverickcer/env-cap)
|
|
11
11
|
[](LICENSE)
|
|
12
12
|
|
|
13
|
-
**
|
|
13
|
+
**Know who owns each environment variable, why it exists, and when it expires.**
|
|
14
14
|
|
|
15
|
-
`env-cap`
|
|
15
|
+
`env-cap` adds ownership, lifecycle and usage evidence to the loader, validator and secret manager you already use. It does not load `.env` files or store secrets.
|
|
16
16
|
|
|
17
17
|
[Why](#why-it-exists) · [See it run](#see-it-run) · [Install](#install-and-verify) · [Fit](#fit-and-capabilities) · [Limits](#limits-and-when-not-to-use-it) · [Security](#security-and-supply-chain) · [Maturity](#maturity-versioning-and-support) · [Docs](#documentation)
|
|
18
18
|
|
|
19
19
|
## Why it exists
|
|
20
20
|
|
|
21
|
-
**
|
|
21
|
+
**The problem:** a variable can be well-formed and still be a problem. A validator checks its shape and a secret manager stores it. Neither says who owns it, what depends on it, when it must rotate, or whether anything still reads it.
|
|
22
22
|
|
|
23
|
-
**
|
|
23
|
+
**What changes:** each part of your code declares the variables it owns. A build step reports owners, expiry dates and declared variables that nothing reads. At startup, the application fails with the variable's name, never its value.
|
|
24
24
|
|
|
25
|
-
**Who it is for:**
|
|
26
|
-
|
|
27
|
-
**Why it matters:** an undetected expiry or an unowned secret is a security and availability risk that no validator can see, because the value itself is well-formed.
|
|
25
|
+
**Who it is for:** application developers who have shipped an undefined variable to production, and platform engineers who own configuration across teams.
|
|
28
26
|
|
|
29
27
|
## How it differs
|
|
30
28
|
|
|
@@ -35,11 +33,19 @@
|
|
|
35
33
|
| Secret manager | Stores and manages secrets | Which capability in the codebase actually consumes the secret |
|
|
36
34
|
| `env-cap` | Defines ownership, lifecycle, and consumption contracts | Does not replace loading, secret storage, or application-specific validation |
|
|
37
35
|
|
|
38
|
-
|
|
36
|
+
Keep your existing validator: any function that returns `true` or a message plugs into a contract. [Migration guides](specs/migrations/README.md) cover `dotenv`, Zod, envalid and t3-env, including when to stay put.
|
|
39
37
|
|
|
40
38
|
## What it does
|
|
41
39
|
|
|
42
|
-
|
|
40
|
+
Each entry point has one reader. The [Guide](GUIDE.md) tells each reader's story in full.
|
|
41
|
+
|
|
42
|
+
| Entry point | Written for | What it gives you |
|
|
43
|
+
| --------------------------------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------- |
|
|
44
|
+
| `@maverickcer/env-cap` | Application developers | One startup check that names every failing variable, and contracts that redact themselves |
|
|
45
|
+
| `@maverickcer/env-cap/helpers` | The same developers | Small processors and validators, tree-shaken when unused |
|
|
46
|
+
| `@maverickcer/env-cap/build`, CLI, Action | Platform engineers who own CI | A manifest, docs and an evidence file from static analysis; `--check` fails on drift |
|
|
47
|
+
| `@maverickcer/env-cap/evidence` | Reviewers who need an inventory | Findings, lifecycle data and SARIF that support a review |
|
|
48
|
+
| `@maverickcer/env-cap/node`, `/eslint-plugin` | Build-script authors and lint owners | The `node:fs` adapter `./build` needs, and two lint rules |
|
|
43
49
|
|
|
44
50
|
```text
|
|
45
51
|
declare → generate → validate → consume
|
|
@@ -47,44 +53,40 @@ declare → generate → validate → consume
|
|
|
47
53
|
|
|
48
54
|
### See it run
|
|
49
55
|
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
A capability declares the environment it owns alongside the validation already needed at runtime:
|
|
56
|
+
A contract declares the variables it owns next to their validation. This excerpt is from [`examples/application/src/env.ts`](https://github.com/MaverickCER/env-cap/blob/main/examples/application/src/env.ts), the file CI runs:
|
|
53
57
|
|
|
54
58
|
```ts
|
|
55
|
-
//
|
|
59
|
+
// examples/application/src/env.ts (excerpt: other variables and fields omitted)
|
|
60
|
+
import { createEnv, documentEnv, type RawEnv } from "@maverickcer/env-cap"
|
|
61
|
+
import { processors } from "@maverickcer/env-cap/helpers"
|
|
56
62
|
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
const paymentsSchema = {
|
|
63
|
+
const schema = {
|
|
64
|
+
DATABASE_URL: { processor: processors.toURL() },
|
|
60
65
|
STRIPE_KEY: {
|
|
61
|
-
|
|
66
|
+
processor: (value: unknown): string => String(value ?? ""),
|
|
67
|
+
validator: (value: string, rawEnv: RawEnv) => {
|
|
68
|
+
if (rawEnv["PAYMENT_PROVIDER"] !== "stripe") return true
|
|
69
|
+
return value.length > 0 || "Stripe key is required when PAYMENT_PROVIDER=stripe."
|
|
70
|
+
},
|
|
62
71
|
},
|
|
63
72
|
}
|
|
64
73
|
|
|
65
|
-
export const
|
|
74
|
+
export const env = createEnv(schema, { name: "app", source: import.meta.url })
|
|
66
75
|
|
|
67
|
-
documentEnv(
|
|
68
|
-
owner: "
|
|
76
|
+
documentEnv(schema, {
|
|
77
|
+
owner: "platform-team",
|
|
69
78
|
variables: {
|
|
79
|
+
DATABASE_URL: { description: "Postgres connection string.", required: true },
|
|
70
80
|
STRIPE_KEY: {
|
|
71
|
-
description: "Stripe secret key used to
|
|
72
|
-
|
|
73
|
-
expiresAt: "
|
|
74
|
-
sensitivity: "secret",
|
|
81
|
+
description: "Stripe secret key used to authenticate server-side API calls.",
|
|
82
|
+
required: true,
|
|
83
|
+
expiresAt: "2026-09-01",
|
|
75
84
|
},
|
|
76
85
|
},
|
|
77
86
|
})
|
|
78
87
|
```
|
|
79
88
|
|
|
80
|
-
|
|
81
|
-
(`./generated/env.manifest`) and the evidence artifact, with one command (`npx env-cap init` scaffolds
|
|
82
|
-
the same thing as a script, `scripts/generate-env.mjs`). The manifest and the
|
|
83
|
-
persisted evidence artifact -- the two outputs a real project actually reads
|
|
84
|
-
at runtime/in CI (see [ADR 0046](specs/decisions/0046-cli-restricted-to-runtime-and-evidence-output.md))
|
|
85
|
-
-- come from the CLI itself; the human-facing docs/ownership report come
|
|
86
|
-
from a small script calling `@maverickcer/env-cap/build` directly (see
|
|
87
|
-
`examples/application/scripts/generate-docs`):
|
|
89
|
+
The CLI writes the manifest your code imports and the evidence file ([ADR 0046](specs/decisions/0046-cli-restricted-to-runtime-and-evidence-output.md)). A short script calls `@maverickcer/env-cap/build` for the human-facing docs and ownership report:
|
|
88
90
|
|
|
89
91
|
```text
|
|
90
92
|
$ npx env-cap --include src/env.ts --location src/generated/env.manifest.ts --evidence docs/env.evidence.json
|
|
@@ -103,95 +105,98 @@ $ npx tsx scripts/generate-docs/run.ts
|
|
|
103
105
|
- STRIPE_KEY in app
|
|
104
106
|
```
|
|
105
107
|
|
|
106
|
-
This is
|
|
108
|
+
This is output from [`examples/application`](https://github.com/MaverickCER/env-cap/tree/main/examples/application) (`npm run docs:reports`). `N` stands for the days since 2026-09-01, counted on the day you run it.
|
|
107
109
|
|
|
108
|
-
The
|
|
110
|
+
The report states facts a validator cannot see. `STRIPE_KEY` is declared to expire on 2026-09-01, and that date has passed. `DATABASE_URL` and `STRIPE_KEY` are declared in the `app` contract, but the analysis found no code that reads them.
|
|
109
111
|
|
|
110
112
|
### Evidence it works
|
|
111
113
|
|
|
112
|
-
- **Real
|
|
113
|
-
- **
|
|
114
|
-
- **
|
|
115
|
-
- **
|
|
116
|
-
- **
|
|
114
|
+
- **Real output:** CI's `examples` job re-runs the block above and compares its expiry and unconsumed lists with this README (`npm run verify:readme-example`). That job does not yet block a merge.
|
|
115
|
+
- **Coverage floors:** 90% branches, 100% functions, 95% lines and statements, enforced by the `contract` job (`vitest.config.ts`). A pull request can lower a floor; reviewers treat that as a reviewed change.
|
|
116
|
+
- **Mutation testing:** the `contract` job fails on any surviving, timed-out or uncovered Stryker mutant in `src/`. Managed copies under `src/_ipc/`, `scripts/`, and mutants silenced by a disable comment are not counted.
|
|
117
|
+
- **Runtimes:** the runtime, helpers and evidence entries run on Node 22 and 24 in blocking jobs. They also run under Bun, Deno and a Web-globals VM; the Bun and Deno job is not yet merge-blocking.
|
|
118
|
+
- **Size budgets:** 3 KB gzip for the runtime, 4 KB for helpers and 3 KB for evidence, enforced by the `Size` check ([ADR 0008](specs/decisions/0008-gzip-size-budget.md)). The budget measures the entry file, not your bundle.
|
|
117
119
|
|
|
118
120
|
## Install and verify
|
|
119
121
|
|
|
120
|
-
**Prerequisites:** Node.js `>=22`. TypeScript 5
|
|
122
|
+
**Prerequisites:** Node.js `>=22`. Your own TypeScript is optional. The generator uses it when it is version 5 or 6, and otherwise the bundled TypeScript 6 compiler. CI tests the newest 5.x only; the 5.0 floor is untested. The runtime works in plain JavaScript ([requirements](GUIDE.md#requirements)).
|
|
121
123
|
|
|
122
124
|
```sh
|
|
123
125
|
npm install @maverickcer/env-cap
|
|
124
|
-
npx env-cap init #
|
|
125
|
-
npm install --save-dev typescript # the generator parses your schema with it
|
|
126
|
+
npx env-cap init # writes env.schema.ts and scripts/generate-env.mjs
|
|
126
127
|
node scripts/generate-env.mjs
|
|
127
128
|
```
|
|
128
129
|
|
|
129
|
-
|
|
130
|
+
`init` writes two files and skips any file that already exists. Without a valid `package.json` it exits `1` and writes nothing. `test/cli/init.test.ts` pins these rules and the templates. **Verify it works:** the script exits `0` and prints `Discovered 1 contract(s).` CI pins the script's text but does not run it. Report an issue if that line differs.
|
|
130
131
|
|
|
131
|
-
|
|
132
|
+
Then validate once at startup and read values through the contract. `init` writes `env.schema.ts` into `src/` when that folder exists, otherwise into the project root; adjust the import path to match:
|
|
132
133
|
|
|
133
134
|
```ts
|
|
134
135
|
import { validateEnv } from "@maverickcer/env-cap"
|
|
135
136
|
import { manifest } from "./generated/env.manifest"
|
|
136
|
-
import {
|
|
137
|
+
import { exampleEnv } from "./env.schema"
|
|
137
138
|
|
|
138
139
|
await validateEnv({ manifest, values: process.env })
|
|
139
|
-
|
|
140
|
+
exampleEnv.EXAMPLE_API_URL
|
|
140
141
|
```
|
|
141
142
|
|
|
142
|
-
|
|
143
|
+
**Using an AI agent?** Give it [the skill](https://raw.githubusercontent.com/MaverickCER/env-cap/main/skills/env-cap/SKILL.md), a short manual generated from this package's exports.
|
|
143
144
|
|
|
144
145
|
## Fit and capabilities
|
|
145
146
|
|
|
146
|
-
**Use cases:** find expired or unowned secrets before they page someone
|
|
147
|
+
**Use cases:** find expired or unowned secrets before they page someone. Generate variable documentation from the code instead of a wiki. Let each team own the variables its feature needs. Give CI bots facts such as "`STRIPE_KEY` is declared but unconsumed".
|
|
147
148
|
|
|
148
149
|
**Core capabilities:**
|
|
149
150
|
|
|
150
|
-
- Capability-scoped contracts with validators,
|
|
151
|
-
- A
|
|
152
|
-
- A persisted evidence
|
|
153
|
-
-
|
|
151
|
+
- Capability-scoped contracts with validators, owners, sensitivity and expiry dates ([contracts](GUIDE.md#capability-owned-contracts)).
|
|
152
|
+
- A manifest, environment docs, `.env.example` and an ownership report, from static analysis that never imports your schema files.
|
|
153
|
+
- A persisted evidence file, a CLI, a [GitHub Action](GUIDE.md#github-action), scheduled rotation reports and an [ESLint plugin](GUIDE.md#eslint-plugin).
|
|
154
|
+
- One central schema or one contract per feature or package; the manifest stays project-wide either way.
|
|
154
155
|
|
|
155
|
-
**How it works:** the runtime and the build tooling are separate
|
|
156
|
+
**How it works:** the runtime and the build tooling are separate entry points. The runtime has no filesystem access, which lint and a tarball scan enforce. The build pass runs only in development and CI ([Architecture](GUIDE.md#runtime-and-build-time-are-intentionally-separate)).
|
|
156
157
|
|
|
157
|
-
**
|
|
158
|
+
**Runtimes:** Node.js 22 and 24 are tested. Bun, Deno and a browser-style bundle run in CI for the runtime, helpers and evidence entries; edge runtimes are not tested ([support matrix](GUIDE.md#runtime-support-matrix)). **Package managers:** npm is supported. pnpm, Yarn 1 and Yarn Berry are tested only for installing the tarball and importing every entry ([details](GUIDE.md#package-managers)).
|
|
158
159
|
|
|
159
160
|
## Limits and when not to use it
|
|
160
161
|
|
|
161
|
-
- **Skip it when**
|
|
162
|
-
- **Trade-offs:** it adds a build step and a declaration per variable
|
|
163
|
-
- **Install weight:** the
|
|
164
|
-
- **
|
|
162
|
+
- **Skip it when** one team owns every variable, there are few of them, and ownership is obvious. A validator or `dotenv` may be all you need.
|
|
163
|
+
- **Trade-offs:** it adds a build step and a declaration per variable. Its reports are only as accurate as those declarations, and it cannot see variables read outside the analyzed code.
|
|
164
|
+
- **Install weight:** the one dependency is a TypeScript 6 compiler bundled in the tarball. Only the build entry loads it, and a CI step fails if a runtime entry can reach it ([Adoption guide](ADOPTION.md#bundle-size-and-performance)).
|
|
165
|
+
- **Dynamic schemas:** a schema built by a function, or a spread at the top of a schema object, produces a parse warning. A spread nested inside a variable's definition or its `documentEnv()` entry is skipped without one. Nothing is guessed.
|
|
166
|
+
- **Automation:** bots can read the same manifest and evidence. A structured finding does not make a fix correct; see the [AI integration prompt](PROMPT.md).
|
|
165
167
|
|
|
166
168
|
## Security and supply chain
|
|
167
169
|
|
|
168
|
-
- **
|
|
169
|
-
- **
|
|
170
|
-
- **
|
|
171
|
-
- **
|
|
170
|
+
- **Runtime:** it has no filesystem access and reads only the `values` you pass; lint and the tarball scan enforce the first, the tarball scan and a browser-bundle test the second. Both scans are textual. Contracts redact themselves when logged or serialized, but spreading a contract reads every value ([runtime model](SECURITY.md#runtime-security-model)).
|
|
171
|
+
- **Errors:** validation errors carry variable and contract names and your own messages, never values (tested). A validator message that embeds the value is passed through.
|
|
172
|
+
- **Build:** schema files are parsed as syntax trees and never imported or run (tested). It does not sandbox the rest of your build ([build-time model](SECURITY.md#build-time-security-model)).
|
|
173
|
+
- **Dependencies:** what installing the package adds is generated from `package.json` into the [Adoption guide](ADOPTION.md#security--threat-model). MIT licensed.
|
|
174
|
+
- **Release integrity:** releases publish from CI over npm OIDC with a provenance attestation, and the repository stores no npm token. A manual last-resort publish carries no attestation ([supply chain](SECURITY.md#supply-chain-posture)).
|
|
175
|
+
- **Report a vulnerability** privately: [SECURITY.md](SECURITY.md#reporting-a-vulnerability).
|
|
172
176
|
|
|
173
177
|
## Maturity, versioning and support
|
|
174
178
|
|
|
175
|
-
Pre-1.0
|
|
179
|
+
Pre-1.0; the npm badge shows the current version. Before 1.0, a minor release may break the Stable tier, so pin a version ([VERSIONING.md](VERSIONING.md)). Security fixes target the latest `0.x` only, with no backport branch before 1.0.
|
|
176
180
|
|
|
177
|
-
- **Upgrade
|
|
178
|
-
- **
|
|
181
|
+
- **Upgrade:** read the [CHANGELOG](CHANGELOG.md) on every minor; [migration guides](specs/migrations/README.md) cover adoption from other tools.
|
|
182
|
+
- **Releases:** [GitHub releases](https://github.com/MaverickCER/env-cap/releases); a person merges every release pull request ([RELEASING.md](RELEASING.md)).
|
|
179
183
|
- **Bugs and requests:** [open an issue](https://github.com/MaverickCER/env-cap/issues); see [SUPPORT.md](SUPPORT.md).
|
|
180
|
-
- **Troubleshooting:** the [Guide's troubleshooting
|
|
184
|
+
- **Troubleshooting:** the [Guide's troubleshooting table](GUIDE.md#troubleshooting).
|
|
181
185
|
|
|
182
186
|
## Documentation
|
|
183
187
|
|
|
184
|
-
- **[Guide](GUIDE.md)
|
|
185
|
-
- **[Adoption guide](ADOPTION.md)
|
|
186
|
-
- **[
|
|
187
|
-
- **[
|
|
188
|
-
- **[
|
|
189
|
-
- **
|
|
188
|
+
- **[Guide](GUIDE.md):** one story per entry point and reader, the CLI options, the GitHub Action and the ESLint plugin.
|
|
189
|
+
- **[Adoption guide](ADOPTION.md):** what adopting costs, what it needs, and what it refuses to do.
|
|
190
|
+
- **[Security](SECURITY.md):** the reviewer's model of what is enforced, where, and what is not.
|
|
191
|
+
- **[API reference](https://maverickcer.github.io/env-cap/api/):** every exported symbol, generated from source.
|
|
192
|
+
- **[Architecture](specs/architecture.md)** and **[ADRs](https://github.com/MaverickCER/env-cap/tree/main/specs/decisions):** why it is designed this way.
|
|
193
|
+
- **[Examples](https://github.com/MaverickCER/env-cap/tree/main/examples):** runnable application, team-service, enterprise-platform and Next.js examples.
|
|
194
|
+
- **Toolkit:** `data-cap` governs application data; `repo-contract` and `internal-package-contract` verify both ([toolkit overview](https://github.com/MaverickCER/internal-package-contract/blob/main/TOOLKIT.md)).
|
|
190
195
|
|
|
191
196
|
## Next steps
|
|
192
197
|
|
|
193
|
-
- **Evaluate:** read the [Adoption guide](ADOPTION.md), then try env-cap
|
|
194
|
-
- **Integrate:** follow the [Guide](GUIDE.md#core-workflow) and
|
|
195
|
-
- **Verify:**
|
|
198
|
+
- **Evaluate:** read the [Adoption guide](ADOPTION.md), then try env-cap on one real schema.
|
|
199
|
+
- **Integrate:** follow the [Guide](GUIDE.md#core-workflow) and run an [example](https://github.com/MaverickCER/env-cap/tree/main/examples).
|
|
200
|
+
- **Verify:** check the [security model](SECURITY.md#runtime-security-model) against the tests it names.
|
|
196
201
|
|
|
197
|
-
Contributing: [CONTRIBUTING.md](CONTRIBUTING.md) covers setup
|
|
202
|
+
Contributing: [CONTRIBUTING.md](CONTRIBUTING.md) covers setup and changesets; [CODE_REVIEW.md](CODE_REVIEW.md) covers review. License: MIT, see [LICENSE](LICENSE).
|
package/RELEASING.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
# Releasing @maverickcer/env-cap
|
|
4
4
|
|
|
5
|
-
Maintainer-facing. Contributors
|
|
5
|
+
Maintainer-facing. Contributors run none of this: a normal change is a pull request, and its
|
|
6
6
|
changeset is generated if it has none (see [`CONTRIBUTING.md`](CONTRIBUTING.md#making-a-change)).
|
|
7
7
|
For what semver actually covers, see [`VERSIONING.md`](VERSIONING.md).
|
|
8
8
|
|
|
@@ -13,8 +13,8 @@ Releases are driven by [Changesets](https://github.com/changesets/changesets) an
|
|
|
13
13
|
[`.github/workflows/release.yml`](https://github.com/MaverickCER/env-cap/blob/main/.github/workflows/release.yml),
|
|
14
14
|
which calls a shared, pinned workflow. **No `NPM_TOKEN` secret exists in this repository** and none is
|
|
15
15
|
needed: npm verifies the workflow's OIDC identity against a one-time trusted-publisher registration on
|
|
16
|
-
npmjs.com (see [First-time setup](#first-time-setup)). A person merges the release pull request
|
|
17
|
-
|
|
16
|
+
npmjs.com (see [First-time setup](#first-time-setup)). A person merges the release pull request. The one other path is recovery: a version on `main` that is not on
|
|
17
|
+
npm is built and published without a pull request (see "Recovering from a failed release").
|
|
18
18
|
|
|
19
19
|
The loop:
|
|
20
20
|
|
|
@@ -28,10 +28,11 @@ The loop:
|
|
|
28
28
|
changeset files, bumps `package.json`'s `version` and rewrites `CHANGELOG.md`. Review it and merge it
|
|
29
29
|
yourself; it is never merged automatically.
|
|
30
30
|
3. Merging it runs the workflow again. A **build** job, which holds no publishing credentials, runs
|
|
31
|
-
`npm run verify` when the package defines it,
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
31
|
+
`npm run verify` when the package defines it, requires that a CI run on a commit with exactly this tree
|
|
32
|
+
finished its `contract` job with success, checks that no scaffold prompt is unanswered, packs the
|
|
33
|
+
tarball, installs that tarball into an empty project and imports every entry point it declares. Only if
|
|
34
|
+
all of that passes does the **publish** job run, and only from the default branch. It publishes exactly
|
|
35
|
+
the tarball the build job made, over OIDC with a provenance attestation.
|
|
35
36
|
4. After publishing, the workflow tags the release `v<major>.<minor>.<patch>` on the merged commit,
|
|
36
37
|
force-updates the floating major tag (`v0` while the package is 0.x, `v1` from 1.0.0), and asks npm what
|
|
37
38
|
it now serves: the version must be there and must carry the provenance attestation, or the run goes red.
|
|
@@ -52,12 +53,12 @@ access, so it can't be done from a PR.
|
|
|
52
53
|
GitHub Actions:
|
|
53
54
|
- Organization or user: `maverickcer`
|
|
54
55
|
- Repository: `env-cap`
|
|
55
|
-
- Workflow filename: `release.yml` (exactly
|
|
56
|
+
- Workflow filename: `release.yml` (exactly: the filename alone, not a
|
|
56
57
|
path; a mismatch here is the most common cause of the OIDC flow failing
|
|
57
58
|
with a misleading `E404`)
|
|
58
59
|
- Environment: leave blank unless `release.yml` is later scoped to a
|
|
59
60
|
GitHub Environment
|
|
60
|
-
2. That
|
|
61
|
+
2. That is the whole trust relationship: `release.yml`'s `id-token: write`
|
|
61
62
|
permission plus this registration. There is no token to copy anywhere.
|
|
62
63
|
|
|
63
64
|
Until the package exists on npm, its settings page doesn't either. For the
|
|
@@ -83,8 +84,8 @@ Nothing is on npm; nothing to undo.
|
|
|
83
84
|
### B. The version pull request is merged, but the release failed
|
|
84
85
|
|
|
85
86
|
`main` now has the version bump and changelog commit, but npm does not have the version. This is the common
|
|
86
|
-
failure (OIDC misconfiguration, a failing `npm run verify
|
|
87
|
-
registry blip).
|
|
87
|
+
failure (OIDC misconfiguration, a failing `npm run verify`, no passing `contract` run on the tree, a failing
|
|
88
|
+
packed-consumer check in the build job, a registry blip).
|
|
88
89
|
|
|
89
90
|
1. Confirm npm really doesn't have it: `npm view @maverickcer/env-cap versions --json`, and check the bumped version is
|
|
90
91
|
absent.
|
|
@@ -96,7 +97,7 @@ registry blip).
|
|
|
96
97
|
pull request to `main`. What happens next depends on the commit type. A `fix`, `feat`, `perf` or `revert`
|
|
97
98
|
commit gets a changeset generated for it, so the workflow opens a new version pull request instead of
|
|
98
99
|
publishing the stuck version; merging that publishes the next version, and the stuck version number is
|
|
99
|
-
|
|
100
|
+
skipped. A commit type that releases nothing (`chore`, `ci`, `docs`) leaves no changeset, so the
|
|
100
101
|
workflow sees that the current `package.json` version isn't on npm and builds and publishes that version.
|
|
101
102
|
5. Publishing by hand is the last resort, and it publishes without the provenance attestation that the
|
|
102
103
|
workflow adds. If you must, publish that exact version from a clean tree
|
|
@@ -106,7 +107,7 @@ registry blip).
|
|
|
106
107
|
### C. Published to npm, but a later workflow step failed
|
|
107
108
|
|
|
108
109
|
e.g. the publish succeeded but the floating major tag (`v0` or `v1`) roll failed. The release itself
|
|
109
|
-
is done and correct.
|
|
110
|
+
is done and correct. Fix the trailing step by hand:
|
|
110
111
|
|
|
111
112
|
```bash
|
|
112
113
|
git checkout main && git pull
|
|
@@ -141,8 +142,9 @@ the one manual step. Every release after that is automated.
|
|
|
141
142
|
- **`E404` on publish with OIDC**: the trusted-publisher registration's
|
|
142
143
|
workflow filename doesn't exactly match `release.yml`, or the
|
|
143
144
|
org/user/repo fields are wrong.
|
|
144
|
-
- **The build job's verify or packed-consumer step fails**: the version pull request merged
|
|
145
|
-
`main`,
|
|
145
|
+
- **The build job's verify, contract-run or packed-consumer step fails**: the version pull request merged
|
|
146
|
+
with a red `main`, no CI run finished `contract` on that tree, or the tarball does not contain what
|
|
147
|
+
`exports` promises. Fix `main` first, then recover per case B.
|
|
146
148
|
- **The final "Verify what npm now serves" step fails**: npm did not return the version or its provenance
|
|
147
149
|
attestation. Nothing is unpublished by the failure; look at the registry before doing anything else.
|
|
148
150
|
- **A version pull request appears when you didn't expect one**: there's a stray changeset file in `.changeset/` on `main`. If it's
|