@maverickcer/env-cap 0.6.0 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/ADOPTION.md +144 -0
- package/AGENTS.md +146 -0
- package/CHANGELOG.md +438 -0
- package/CODE_OF_CONDUCT.md +124 -0
- package/CODE_REVIEW.md +200 -0
- package/CONTRIBUTING.md +131 -0
- package/GUIDE.md +1214 -0
- package/PROMPT.md +89 -0
- package/README.md +92 -200
- package/RELEASING.md +160 -0
- package/SECURITY.md +270 -0
- package/SUPPORT.md +76 -0
- package/VERSIONING.md +118 -0
- package/benchmarks/READING-BENCHMARKS.md +197 -0
- package/benchmarks/README.md +126 -0
- package/benchmarks/WRITING-BENCHMARKS.md +252 -0
- package/benchmarks/performance-buildtime/BENCHMARKS.md +889 -0
- package/benchmarks/performance-runtime/BENCHMARKS.md +1988 -0
- package/dist/.dts/_ipc/build-fs.d.ts +53 -0
- package/dist/.dts/_ipc/build-fs.d.ts.map +1 -0
- package/dist/.dts/_ipc/compiler-api.d.ts +17 -0
- package/dist/.dts/_ipc/compiler-api.d.ts.map +1 -0
- package/dist/.dts/_ipc/display-path.d.ts +27 -0
- package/dist/.dts/_ipc/display-path.d.ts.map +1 -0
- package/dist/.dts/_ipc/generated-banner.d.ts +58 -0
- package/dist/.dts/_ipc/generated-banner.d.ts.map +1 -0
- package/dist/.dts/_ipc/glob.d.ts +22 -0
- package/dist/.dts/_ipc/glob.d.ts.map +1 -0
- package/dist/.dts/_ipc/no-node-fs.d.ts +34 -0
- package/dist/.dts/_ipc/no-node-fs.d.ts.map +1 -0
- package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts +134 -0
- package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts.map +1 -0
- package/dist/.dts/_ipc/typescript.d.ts +20 -0
- package/dist/.dts/_ipc/typescript.d.ts.map +1 -0
- package/dist/.dts/build/compatibility.d.ts.map +1 -1
- package/dist/.dts/build/compiler-api.d.ts +3 -6
- package/dist/.dts/build/compiler-api.d.ts.map +1 -1
- package/dist/.dts/build/display-path.d.ts +3 -21
- package/dist/.dts/build/display-path.d.ts.map +1 -1
- package/dist/.dts/build/generated-banner.d.ts +21 -42
- package/dist/.dts/build/generated-banner.d.ts.map +1 -1
- package/dist/.dts/build/glob.d.ts +3 -15
- package/dist/.dts/build/glob.d.ts.map +1 -1
- package/dist/.dts/build/link.d.ts.map +1 -1
- package/dist/.dts/build/merge-documentation.d.ts +35 -0
- package/dist/.dts/build/merge-documentation.d.ts.map +1 -0
- package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts +11 -112
- package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts.map +1 -1
- package/dist/.dts/build/types.d.ts +4 -53
- package/dist/.dts/build/types.d.ts.map +1 -1
- package/dist/.dts/build/typescript.d.ts +3 -17
- package/dist/.dts/build/typescript.d.ts.map +1 -1
- package/dist/.dts/eslint-plugin/glob.d.ts +4 -15
- package/dist/.dts/eslint-plugin/glob.d.ts.map +1 -1
- package/dist/.dts/eslint-plugin/index.d.ts +1 -1
- package/dist/.dts/eslint-plugin/no-node-fs.d.ts +8 -18
- package/dist/.dts/eslint-plugin/no-node-fs.d.ts.map +1 -1
- package/dist/.dts/eslint-plugin/no-raw-process-env.d.ts.map +1 -1
- package/dist/{build-H4KFV44Z.js → build-WKDIAWF7.js} +198 -60
- package/dist/build-WKDIAWF7.js.map +1 -0
- package/dist/build.cjs +194 -56
- package/dist/build.cjs.map +1 -1
- package/dist/build.js +194 -56
- package/dist/build.js.map +1 -1
- package/dist/{chunk-7GVPOHDU.js → chunk-KEGYUHBU.js} +2 -2
- package/dist/cli/index.js +36 -29
- package/dist/cli/index.js.map +1 -1
- package/dist/eslint-plugin/index.cjs +84 -54
- package/dist/eslint-plugin/index.cjs.map +1 -1
- package/dist/eslint-plugin/index.js +83 -53
- package/dist/eslint-plugin/index.js.map +1 -1
- package/examples/README.md +95 -0
- package/package.json +48 -14
- package/skills/env-cap/SKILL.md +91 -0
- package/skills/env-cap/references/api.md +220 -0
- package/specs/architecture.md +634 -0
- package/specs/decisions/0001-runtime-documentation-separation.md +197 -0
- package/specs/decisions/0002-static-analysis-never-execution.md +233 -0
- package/specs/decisions/0003-no-global-env-object.md +172 -0
- package/specs/decisions/0004-no-client-server-package-split.md +116 -0
- package/specs/decisions/0005-warn-not-throw-by-default.md +93 -0
- package/specs/decisions/0006-self-redacting-contracts.md +124 -0
- package/specs/decisions/0007-processor-not-transformer.md +109 -0
- package/specs/decisions/0008-gzip-size-budget.md +173 -0
- package/specs/decisions/0009-exclusive-groups-are-always-errors.md +139 -0
- package/specs/decisions/0010-dependency-ownership-engine-scope-boundary.md +100 -0
- package/specs/decisions/0011-shared-discovery-compute-atomic-write-non-atomic.md +104 -0
- package/specs/decisions/0012-live-expiration-overrides-not-ast-functions.md +145 -0
- package/specs/decisions/0013-json-output-is-a-versioned-mirror.md +136 -0
- package/specs/decisions/0014-cross-package-schema-discovery.md +206 -0
- package/specs/decisions/0015-security-backport-window.md +60 -0
- package/specs/decisions/0016-check-mode-compute-before-compare-never-partial-write.md +113 -0
- package/specs/decisions/0017-eslint-plugin-entry-point.md +113 -0
- package/specs/decisions/0018-rotation-alert-issue-on-non-pr-runs.md +104 -0
- package/specs/decisions/0019-published-json-schema-generated-from-types.md +100 -0
- package/specs/decisions/0020-declaration-maps-via-separate-tsc-pass.md +101 -0
- package/specs/decisions/0021-manifest-change-report-persisted-snapshot.md +177 -0
- package/specs/decisions/0022-validation-contexts.md +267 -0
- package/specs/decisions/0023-tsconfig-path-alias-resolution.md +182 -0
- package/specs/decisions/0024-fact-model-architecture.md +144 -0
- package/specs/decisions/0025-contract-model-json-projection.md +105 -0
- package/specs/decisions/0026-finding-model-unifies-four-families.md +109 -0
- package/specs/decisions/0027-dependency-model-fact-shape-not-engine-access.md +98 -0
- package/specs/decisions/0028-ownership-model-shared-effective-owner.md +85 -0
- package/specs/decisions/0029-lifecycle-model-deprecation-rename-fields.md +98 -0
- package/specs/decisions/0030-change-model-wraps-manifest-change-report.md +97 -0
- package/specs/decisions/0031-evidence-entry-point.md +85 -0
- package/specs/decisions/0032-evidence-projection-provenance-mechanism.md +120 -0
- package/specs/decisions/0033-reference-projections-live-in-examples.md +81 -0
- package/specs/decisions/0034-three-tier-examples-restructuring.md +85 -0
- package/specs/decisions/0035-documentenv-metadata-generalization-and-compliance-fields.md +85 -0
- package/specs/decisions/0036-exact-source-position-evidence.md +122 -0
- package/specs/decisions/0037-developer-declared-dynamic-access-citations.md +114 -0
- package/specs/decisions/0038-always-computed-evidence-model-backs-generate-check-docs.md +244 -0
- package/specs/decisions/0039-scanner-local-dataflow-boundary.md +160 -0
- package/specs/decisions/0040-library-surfaces-do-not-acquire-node-fs.md +156 -0
- package/specs/decisions/0041-dual-package-hazard-checked-documented.md +75 -0
- package/specs/decisions/0042-init-cli-subcommand-scaffolds-only.md +95 -0
- package/specs/decisions/0043-env-cap-resolver-relocated-and-duplicated.md +71 -0
- package/specs/decisions/0044-strict-escalates-every-warning-family.md +88 -0
- package/specs/decisions/0045-promote-experimental-surfaces-to-stable.md +103 -0
- package/specs/decisions/0046-cli-restricted-to-runtime-and-evidence-output.md +177 -0
- package/specs/decisions/0047-supported-toolchain-node-22-and-typescript-5-6.md +30 -0
- package/specs/decisions/0048-eslint-plugin-does-not-vendor-typescript-eslint.md +25 -0
- package/specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md +87 -0
- package/specs/decisions/0050-a-variable-declared-twice-is-documented-once.md +55 -0
- package/specs/generated-artifacts.md +104 -0
- package/specs/migrations/README.md +30 -0
- package/specs/migrations/from-centralized-schema.md +503 -0
- package/specs/migrations/from-dotenv.md +352 -0
- package/specs/migrations/from-envalid.md +482 -0
- package/specs/migrations/from-process-env.md +398 -0
- package/specs/migrations/from-t3-env.md +416 -0
- package/specs/migrations/from-zod.md +303 -0
- package/dist/build-H4KFV44Z.js.map +0 -1
- /package/dist/{chunk-7GVPOHDU.js.map → chunk-KEGYUHBU.js.map} +0 -0
package/ADOPTION.md
ADDED
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
# Adoption guide for technical decision-makers
|
|
2
|
+
|
|
3
|
+
This document exists for one purpose: to let a Principal/Staff engineer,
|
|
4
|
+
architect, or security reviewer evaluate `env-cap` for adoption at
|
|
5
|
+
organizational scale without having to reconstruct the picture from
|
|
6
|
+
`SECURITY.md`, `specs/architecture.md`, the ADRs in `specs/decisions/`, and six migration
|
|
7
|
+
guides scattered across the repository tree. Everything here links back to
|
|
8
|
+
the primary source it summarizes — nothing here is a new claim.
|
|
9
|
+
|
|
10
|
+
## What problem this solves
|
|
11
|
+
|
|
12
|
+
Most environment-variable tooling (`dotenv`, `zod`, `envalid`, `t3-env`)
|
|
13
|
+
solves _validation_: is this value the right shape? None of them solve
|
|
14
|
+
_ownership_: which team owns `STRIPE_WEBHOOK_SECRET`, what breaks if it
|
|
15
|
+
disappears, and is it actually still read anywhere? As an application grows
|
|
16
|
+
past a handful of features, environment configuration tends to converge on
|
|
17
|
+
one growing, centrally-owned schema file that nobody wants to touch because
|
|
18
|
+
nobody's sure what depends on what. `env-cap` lets each capability declare
|
|
19
|
+
and validate the variables _it_ consumes, and adds a static-analysis layer
|
|
20
|
+
that answers the ownership/blast-radius questions a validation-only library
|
|
21
|
+
never asks. See [`specs/migrations/README.md`](specs/migrations/README.md)
|
|
22
|
+
and its six per-tool guides for an honest, specific comparison — including
|
|
23
|
+
when _not_ to switch.
|
|
24
|
+
|
|
25
|
+
## Security & threat model
|
|
26
|
+
|
|
27
|
+
Full detail: [`SECURITY.md`](SECURITY.md). The summary a security reviewer
|
|
28
|
+
needs:
|
|
29
|
+
|
|
30
|
+
- **The runtime has no dependencies.** The runtime entry points (`.` and `./helpers`) import
|
|
31
|
+
nothing, so nothing is added to your application's production bundle. `package.json` has one
|
|
32
|
+
`dependencies` entry: a bundled TypeScript 6 compiler (about 5 MB to download, about 24 MB unpacked in your
|
|
33
|
+
`node_modules`), used only by the build entry so that TypeScript 7 projects can run the scanner
|
|
34
|
+
([ADR 0049](specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md)).
|
|
35
|
+
`internal-package-contract tool compiler-isolation` fails the build if any runtime entry can reach it.
|
|
36
|
+
- **The runtime never persists, retrieves, rotates, or logs secrets**, and
|
|
37
|
+
never inserts raw or processed values into a thrown error — only variable
|
|
38
|
+
names, contract names, and the _developer's own_ validator/processor
|
|
39
|
+
message strings ever reach an `EnvValidationError`.
|
|
40
|
+
- **Contracts self-redact.** `console.log`, `JSON.stringify`, and template-
|
|
41
|
+
literal interpolation of a contract object all produce a redacted
|
|
42
|
+
`EnvContract("name")` marker, never resolved values ([ADR
|
|
43
|
+
0006](specs/decisions/0006-self-redacting-contracts.md)).
|
|
44
|
+
- **The build tool never executes discovered code.** Schema files are parsed
|
|
45
|
+
as TypeScript ASTs (`ts.createSourceFile`), never `import()`ed, `require()`d,
|
|
46
|
+
or `eval()`d — a build tool meant to run in CI against a team's own source
|
|
47
|
+
tree does not become a second execution path for that source
|
|
48
|
+
([ADR 0002](specs/decisions/0002-static-analysis-never-execution.md)).
|
|
49
|
+
This guarantee is enforced by a regression test proving a schema file with
|
|
50
|
+
a throwing top-level statement never actually runs during discovery.
|
|
51
|
+
- **Cross-package discovery (ADR 0014) does not weaken the
|
|
52
|
+
above.** It is opt-in (an explicit `packages` allowlist, never an implicit
|
|
53
|
+
scan of installed dependencies), never walks `node_modules` via `readdir`,
|
|
54
|
+
and validates a resolved file's path, extension, symlink target, and size
|
|
55
|
+
before ever parsing it — see
|
|
56
|
+
[ADR 0014](specs/decisions/0014-cross-package-schema-discovery.md) and the
|
|
57
|
+
updated `SECURITY.md` section for the exact bounds.
|
|
58
|
+
- **TypeScript path-alias resolution (ADR 0023) never crosses
|
|
59
|
+
into `node_modules`.** Unlike cross-package discovery, this mechanism is on
|
|
60
|
+
by default (a project's own `tsconfig.json` never crosses a
|
|
61
|
+
trust/versioning boundary the way an installed package does), but the
|
|
62
|
+
boundary between the two stays strict: any resolution landing inside
|
|
63
|
+
`node_modules` is discarded, so bare package specifiers remain exclusively
|
|
64
|
+
governed by the explicit `packages` allowlist above — see
|
|
65
|
+
[ADR 0023](specs/decisions/0023-tsconfig-path-alias-resolution.md).
|
|
66
|
+
- **Supply-chain posture:** dependency-free at runtime; CI enforces
|
|
67
|
+
typecheck, lint, tests with coverage thresholds, cross-runtime conformance
|
|
68
|
+
(Node/Bun/Deno), and a hard gzip size budget on every change; releases
|
|
69
|
+
publish via npm's OIDC trusted publishing (no long-lived `NPM_TOKEN`) with
|
|
70
|
+
provenance attestation, so a consumer can verify a published artifact was
|
|
71
|
+
built by this repository's own CI, not a maintainer's laptop.
|
|
72
|
+
|
|
73
|
+
## Versioning, stability, and long-term support
|
|
74
|
+
|
|
75
|
+
Full detail: [`VERSIONING.md`](VERSIONING.md). The three-tier model —
|
|
76
|
+
**Stable** (semver-covered public runtime/build APIs, CLI flags, the `--json`
|
|
77
|
+
schema, the generated manifest format, and every surface listed in
|
|
78
|
+
[ADR 0045](specs/decisions/0045-promote-experimental-surfaces-to-stable.md)),
|
|
79
|
+
**Experimental** (explicitly labeled new surfaces that may still change
|
|
80
|
+
shape before being promoted -- nothing currently ships under this tier), and
|
|
81
|
+
**Private** (internal implementation, never covered) — is what the eventual
|
|
82
|
+
1.0 stability promise will cover.
|
|
83
|
+
|
|
84
|
+
**The honest gap or long-term support question, answered directly:**
|
|
85
|
+
`env-cap` has not reached a 1.0 release, and today, per `SECURITY.md`,
|
|
86
|
+
security fixes target the latest published `0.x` version only — there is
|
|
87
|
+
no backport branch yet. **Starting at `1.0`**, `SECURITY.md` commits to
|
|
88
|
+
backporting security fixes to the latest minor release of the previous
|
|
89
|
+
major version for a minimum of six months after a new major ships (a
|
|
90
|
+
window that can be extended, never shortened, once stated). An
|
|
91
|
+
organization with a hard LTS/backport requirement today should treat the
|
|
92
|
+
_current_ state as a real limitation — the `1.0` commitment is a forward
|
|
93
|
+
policy, not something already exercised in production. It is offset by the
|
|
94
|
+
same two structural factors as before: zero runtime dependencies, and a
|
|
95
|
+
fully automated, OIDC-attested release pipeline plus documented governance
|
|
96
|
+
that lower the bar for a successor maintainer or fork.
|
|
97
|
+
|
|
98
|
+
## Bundle size and performance
|
|
99
|
+
|
|
100
|
+
The runtime entry point carries a **hard 3 KB gzip budget** and the helpers a **hard 4 KB** one,
|
|
101
|
+
enforced at `prepublishOnly` — not an aspirational CI check a maintainer can
|
|
102
|
+
ignore, a publish-blocking one ([ADR
|
|
103
|
+
0008](specs/decisions/0008-gzip-size-budget.md)). `sideEffects: false` is set
|
|
104
|
+
and verified by a dedicated test that bundles the real `dist/helpers.js`
|
|
105
|
+
output with esbuild and asserts unused exports are actually tree-shaken, not
|
|
106
|
+
just assumed to be.
|
|
107
|
+
|
|
108
|
+
## Architectural guarantees worth knowing before you adopt
|
|
109
|
+
|
|
110
|
+
Each of these is a locked-in product decision, not an implementation detail
|
|
111
|
+
that might silently change:
|
|
112
|
+
|
|
113
|
+
| Guarantee | Why it matters for adoption | ADR |
|
|
114
|
+
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
115
|
+
| No global `env` object — only per-capability contracts | Prevents the "one giant schema file nobody owns" failure mode this package exists to solve | [0003](specs/decisions/0003-no-global-env-object.md) |
|
|
116
|
+
| One runtime, no `/client`/`/server` split | Works identically in Node, browser, edge, and serverless — no framework-specific build variant to maintain | [0004](specs/decisions/0004-no-client-server-package-split.md) |
|
|
117
|
+
| Warn, not throw, by default | Adopting incrementally in a large codebase doesn't require fixing every finding on day one. `--strict-docs`/`--strict-ownership` opt into a stricter CI gate one family at a time, or `--strict` escalates all three provable-error families (compatibility, documentation, ownership) at once once a team is ready (ADR 0044). Nothing throws until a team opts in | [0005](specs/decisions/0005-warn-not-throw-by-default.md), [0038](specs/decisions/0038-always-computed-evidence-model-backs-generate-check-docs.md), [0044](specs/decisions/0044-strict-escalates-every-warning-family.md) |
|
|
118
|
+
| Exclusive-group violations are always hard errors | A safety guarantee (e.g. "never activate two database backends at once") that can't be silently downgraded to a warning by a lenient CI setting | [0009](specs/decisions/0009-exclusive-groups-are-always-errors.md) |
|
|
119
|
+
| `--json` output is a versioned, additive-only wire contract | Safe to build dashboards/CI integrations against; a `schemaVersion` bump is the only breaking-change signal to watch for | [0013](specs/decisions/0013-json-output-is-a-versioned-mirror.md) |
|
|
120
|
+
|
|
121
|
+
Full list: [`specs/architecture.md`](specs/architecture.md)'s decision table.
|
|
122
|
+
|
|
123
|
+
## Migration cost from what you likely have today
|
|
124
|
+
|
|
125
|
+
| Coming from | Migration guide | One-line take |
|
|
126
|
+
| -------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
|
|
127
|
+
| Raw `process.env` | [from-process-env.md](specs/migrations/from-process-env.md) | Lowest-friction starting point; adds validation and ownership where there was none |
|
|
128
|
+
| `dotenv` | [from-dotenv.md](specs/migrations/from-dotenv.md) | `dotenv` still loads `.env` files; `env-cap` validates and documents what's in them |
|
|
129
|
+
| `zod`-based validation | [from-zod.md](specs/migrations/from-zod.md) | Keep Zod for request/response validation; only adopt `env-cap` if ownership/discovery, not validation, is the actual pain point |
|
|
130
|
+
| `envalid` | [from-envalid.md](specs/migrations/from-envalid.md) | Similar validation ergonomics; the real delta is per-capability ownership vs. one central schema |
|
|
131
|
+
| `t3-env` | [from-t3-env.md](specs/migrations/from-t3-env.md) | Both are type-safe; `t3-env` centralizes, `env-cap` deliberately doesn't |
|
|
132
|
+
| A hand-rolled centralized schema | [from-centralized-schema.md](specs/migrations/from-centralized-schema.md) | The most direct fit for what this package changes about your architecture |
|
|
133
|
+
|
|
134
|
+
Every guide above includes an explicit "when to keep what you have"
|
|
135
|
+
section — these are not one-directional sales pitches; several actively
|
|
136
|
+
recommend staying put for small or single-team applications.
|
|
137
|
+
|
|
138
|
+
## Questions this document doesn't answer
|
|
139
|
+
|
|
140
|
+
If you need something not covered here — a specific compliance framework
|
|
141
|
+
mapping, a formal SLA, or an LTS commitment beyond what `SECURITY.md`
|
|
142
|
+
states — that is a real gap today, not an oversight in this document. Open
|
|
143
|
+
an issue or reach the maintainer through the channels in `SECURITY.md`
|
|
144
|
+
rather than assuming an answer either way.
|
package/AGENTS.md
ADDED
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
# AGENTS.md
|
|
2
|
+
|
|
3
|
+
Guidance for AI coding agents (Codex, Cursor, Copilot, Continue, and others reading this
|
|
4
|
+
convention) working in `env-cap`'s own source, or in an application that consumes
|
|
5
|
+
`env-cap`. Agents whose tooling loads skill files get the fuller, more detailed version of
|
|
6
|
+
this same guidance from [`skills/env-cap/SKILL.md`](skills/env-cap/SKILL.md) — read that file
|
|
7
|
+
instead if your tooling supports it; this file is a self-contained distillation for
|
|
8
|
+
agents that don't.
|
|
9
|
+
|
|
10
|
+
## What this package is
|
|
11
|
+
|
|
12
|
+
`env-cap` gives each capability (a feature folder or an installable package) its own
|
|
13
|
+
environment contract — declared once as a static schema, validated at runtime, documented
|
|
14
|
+
and aggregated at build time. There is no global `env` object.
|
|
15
|
+
|
|
16
|
+
## Non-negotiable invariants
|
|
17
|
+
|
|
18
|
+
1. **Static analysis only — schemas are never executed.** The build package
|
|
19
|
+
(`@maverickcer/env-cap/build`) parses `env.schema.ts` files as TypeScript AST; it never
|
|
20
|
+
`import()`s, `require()`s, or `eval()`s them. Only literal expressions resolve — a
|
|
21
|
+
spread, a factory call, or a re-export resolves as "unknown" and surfaces as a warning,
|
|
22
|
+
never a guess. Keep every schema object passed to `createEnv()`/`documentEnv()` a
|
|
23
|
+
static literal.
|
|
24
|
+
2. **Capability ownership — never a global env object.** Each `createEnv()` call is
|
|
25
|
+
scoped to, and exported by, the module that owns it (`paymentsEnv`, `databaseEnv`).
|
|
26
|
+
Access always goes through the owning contract — `paymentsEnv.STRIPE_KEY`, never
|
|
27
|
+
`env.payments.STRIPE_KEY`. Never introduce a merged/global wrapper object.
|
|
28
|
+
3. **Runtime config and documentation are separate calls on the same schema object.**
|
|
29
|
+
`createEnv(schema, options)` reads only `default`/`processor`/`validator`/`context` —
|
|
30
|
+
that is the runtime's entire vocabulary. `documentEnv(schema, docs)` is a second, inert
|
|
31
|
+
call over the same object; it returns `void` and exists only as a build-time AST marker.
|
|
32
|
+
Never put `description`/`owner`/`expiresAt` fields inside `createEnv()`; never expect
|
|
33
|
+
`documentEnv()` to affect runtime behavior.
|
|
34
|
+
4. **Public API surface only.** `package.json#exports` exposes exactly `.`, `./build`,
|
|
35
|
+
`./helpers`, `./evidence`, `./node`, `./eslint-plugin`, `./schema`, `./schema/*` (one JSON Schema
|
|
36
|
+
per canonical fact model, e.g. `./schema/contract-model`), and `./package.json`. Import
|
|
37
|
+
only from these — never `dist/*.cjs` internals, `src/**/*.ts` paths, or an unexported
|
|
38
|
+
build internal (e.g. the dependency-graph engine).
|
|
39
|
+
5. **Runtime and build are strictly separated.** `src/build` uses `node:fs`/`node:path`/
|
|
40
|
+
`typescript` and must never be imported from runtime/browser code. `src/runtime` has
|
|
41
|
+
zero filesystem access and zero dependencies, and is held to a 3KB gzip budget
|
|
42
|
+
(`npm run size`).
|
|
43
|
+
6. **Contracts self-redact; errors never carry values.** `console.log(paymentsEnv)`
|
|
44
|
+
prints only `EnvContract("payments") { N variable(s) }`. Validation errors are built
|
|
45
|
+
from variable name, contract name/source, failure kind, and the developer's own error
|
|
46
|
+
message — never raw or processed values. Never write a processor/validator error
|
|
47
|
+
message that embeds the raw value.
|
|
48
|
+
7. **Validation contexts are participation filters, not security or detection.** A schema
|
|
49
|
+
entry may set `context: "server"` (or any application-defined string); `validateEnv({
|
|
50
|
+
activeContexts })` skips any variable whose `context` isn't in that list — no default/
|
|
51
|
+
processor/validator runs for it, and reading it throws `EnvNotReadyError`. env-cap never
|
|
52
|
+
detects or infers `activeContexts` (no `window`/`NODE_ENV` sniffing inside the package —
|
|
53
|
+
the application always computes and passes it explicitly), `context` never restricts who
|
|
54
|
+
can read a resolved value, and it is **not** a bundling boundary: a `context: "server"`
|
|
55
|
+
variable in the same manifest as `context: "client"` variables still ships its
|
|
56
|
+
definition to a client bundle that imports that manifest. Use separate discovery/
|
|
57
|
+
manifests per contract when a variable must never reach client-bound code at all (see
|
|
58
|
+
`specs/decisions/0004-no-client-server-package-split.md` and
|
|
59
|
+
`specs/decisions/0022-validation-contexts.md`).
|
|
60
|
+
|
|
61
|
+
## Avoid
|
|
62
|
+
|
|
63
|
+
- Deep/internal imports (`dist/*.cjs`, `src/build/dependency-graph.ts`, anything not
|
|
64
|
+
re-exported by the public entry points).
|
|
65
|
+
- Importing `@maverickcer/env-cap/build` into runtime or browser code — it is Node-only,
|
|
66
|
+
dev/CI-only.
|
|
67
|
+
- Calling any `generate*()` function at application startup or on a request path —
|
|
68
|
+
build-time only, wired into an npm script or CI step.
|
|
69
|
+
- Dynamically constructed schemas (`createEnv(buildSchema())`, `createEnv({ ...shared })`,
|
|
70
|
+
re-exporting a contract from another module) — static AST discovery cannot resolve
|
|
71
|
+
these.
|
|
72
|
+
- Documentation fields inside `createEnv()`'s schema — those belong in `documentEnv()`
|
|
73
|
+
only.
|
|
74
|
+
- The field name `transformer` — renamed to `processor`, no alias exists.
|
|
75
|
+
- Reading a contract before `validateEnv()` has run — throws `EnvNotReadyError`.
|
|
76
|
+
- Spreading or `Object.entries()`-ing a whole contract "just to inspect it" —
|
|
77
|
+
`console.log(paymentsEnv)` is safe by design, but `{...paymentsEnv}` triggers every
|
|
78
|
+
getter and produces a plain object with every real value.
|
|
79
|
+
- Manually constructing a contract collection when a generated manifest is available —
|
|
80
|
+
regenerate it instead: run the project's `generate:env` script if one exists, or call
|
|
81
|
+
`generateEnvManifest({ location: "src/generated/env.manifest.ts" })` from
|
|
82
|
+
`@maverickcer/env-cap/build`, or run `npx env-cap --location
|
|
83
|
+
src/generated/env.manifest.ts` from the CLI. Never hand-assemble the collection it
|
|
84
|
+
produces.
|
|
85
|
+
- Validation managers, service locators, providers, registries, or other initialization
|
|
86
|
+
frameworks around `validateEnv()` — call it directly from the application's existing
|
|
87
|
+
startup path.
|
|
88
|
+
|
|
89
|
+
## Migrating an existing app onto env-cap
|
|
90
|
+
|
|
91
|
+
- Generated manifests are meant to be consumed by `validateEnv()` at runtime, and
|
|
92
|
+
generated artifacts (manifest, docs, `.env.example`, ownership report) are meant to be
|
|
93
|
+
consumed by tooling — prefer them over anything manually maintained, and treat them as
|
|
94
|
+
the source of truth.
|
|
95
|
+
- To generate a manifest: check for an existing `generate:env` (or similarly named) npm
|
|
96
|
+
script first and run that. If none exists, either call
|
|
97
|
+
`generateEnvManifest({ location: "src/generated/env.manifest.ts" })` (import from
|
|
98
|
+
`@maverickcer/env-cap/build`) from a build script, or run the CLI directly —
|
|
99
|
+
`npx env-cap --location src/generated/env.manifest.ts` (add `--evidence`, `--strict`,
|
|
100
|
+
etc. as needed; see the Public API map and `skills/env-cap/SKILL.md` for the full option
|
|
101
|
+
set). `--docs`/`--ownership`/`--env-example` are not CLI flags — the documentation
|
|
102
|
+
catalog, `.env.example`, and dependency-ownership report have no runtime consumer, so
|
|
103
|
+
generating them is a `generateEnvArtifacts()`/`generateDocumentation()`/
|
|
104
|
+
`generateUsageReport()` call from a build script instead (see ADR 0046). Commit the
|
|
105
|
+
generated file only if the project already commits generated artifacts; otherwise wire
|
|
106
|
+
the command into CI.
|
|
107
|
+
- Prefer migrations that are small, reviewable PRs covering one capability at a time,
|
|
108
|
+
preserve existing validation and runtime behavior, and avoid new infrastructure unless
|
|
109
|
+
it's actually required. See [`specs/migrations/`](specs/migrations/) for guide-by-guide
|
|
110
|
+
detail.
|
|
111
|
+
|
|
112
|
+
## Public API map
|
|
113
|
+
|
|
114
|
+
<!-- ipc:begin entry-points -->
|
|
115
|
+
|
|
116
|
+
| Export | Source | Environment | Tier | Purpose |
|
|
117
|
+
| ------------------------------------ | -------------------- | --------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
118
|
+
| `@maverickcer/env-cap` | `src/runtime/` | isomorphic, zero deps | Stable | `createEnv`, `documentEnv`, `validateEnv`, `resetEnvCache`, error types, `isEnvContract` |
|
|
119
|
+
| `@maverickcer/env-cap/build` | `src/build/` | Node-only, dev/CI | Stable | discovery, AST analysis, artifact generation (see `VERSIONING.md` — the four `generate*()` orchestrators and the lower-level primitives are all Stable, ADR 0045) |
|
|
120
|
+
| `@maverickcer/env-cap/helpers` | `src/helpers/` | isomorphic, optional | Stable | `processors` / `validators` |
|
|
121
|
+
| `@maverickcer/env-cap/node` | `src/node/` | Node-only, dev/CI | Stable | `nodeBuildFileSystem` — the ready-made `BuildFileSystem` adapter a build script hands to `./build` |
|
|
122
|
+
| `@maverickcer/env-cap/evidence` | `src/evidence/` | isomorphic, optional | Stable | `defineEvidenceProjection` — pure transforms over the Evidence Model (Stable, see `VERSIONING.md`) |
|
|
123
|
+
| `@maverickcer/env-cap/eslint-plugin` | `src/eslint-plugin/` | Node-only, optional | Stable | `no-raw-process-env` and `no-node-fs` lint rules |
|
|
124
|
+
| `@maverickcer/env-cap/schema` | `schemas/` | static JSON | Stable | The published JSON Schema for `env-cap --json` output (`env-cap-report.schema.json`), plus the model schemas under `./schema/*` |
|
|
125
|
+
|
|
126
|
+
<!-- ipc:end entry-points -->
|
|
127
|
+
|
|
128
|
+
## Before finishing a change
|
|
129
|
+
|
|
130
|
+
- Run `npm run typecheck` and `npm test`.
|
|
131
|
+
- If `src/runtime` or `src/helpers` changed, run `npm run size`.
|
|
132
|
+
- If public exports changed, confirm it's intentional and justified — otherwise revert
|
|
133
|
+
the export.
|
|
134
|
+
- If an `env.schema.ts` changed, add/update the matching `documentEnv()` entry and
|
|
135
|
+
regenerate dependent generated artifacts via the project's `generate:env` script. Never
|
|
136
|
+
hand-edit a file marked `AUTO-GENERATED FILE. DO NOT EDIT.`
|
|
137
|
+
- Confirm no secret/raw environment value appears in a thrown error message, a log, or a
|
|
138
|
+
committed example file.
|
|
139
|
+
|
|
140
|
+
## Full reference
|
|
141
|
+
|
|
142
|
+
For architecture rationale, the complete decision history, migration guides, and
|
|
143
|
+
maintainer-only notes on modifying `env-cap`'s own source, see
|
|
144
|
+
[`specs/architecture.md`](specs/architecture.md), [`specs/decisions/`](specs/decisions/),
|
|
145
|
+
[`specs/migrations/`](specs/migrations/), and
|
|
146
|
+
[`skills/env-cap/SKILL.md`](skills/env-cap/SKILL.md).
|