@maverickcer/env-cap 0.6.0 → 0.7.1
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 +449 -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 +35 -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/index.d.ts +3 -3
- 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-F3RQS7VE.js} +218 -63
- package/dist/build-F3RQS7VE.js.map +1 -0
- package/dist/build.cjs +257 -102
- package/dist/build.cjs.map +1 -1
- package/dist/build.js +256 -101
- package/dist/build.js.map +1 -1
- package/dist/{chunk-7GVPOHDU.js → chunk-QKIQ3LZP.js} +2 -2
- package/dist/cli/index.js +36 -29
- package/dist/cli/index.js.map +1 -1
- package/dist/eslint-plugin/index.cjs +95 -54
- package/dist/eslint-plugin/index.cjs.map +1 -1
- package/dist/eslint-plugin/index.js +94 -53
- package/dist/eslint-plugin/index.js.map +1 -1
- package/examples/README.md +95 -0
- package/package.json +53 -19
- 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-QKIQ3LZP.js.map} +0 -0
package/PROMPT.md
ADDED
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
## AI-Assisted Integration
|
|
2
|
+
|
|
3
|
+
env-cap is designed to integrate with existing application architectures rather than replace them blindly.
|
|
4
|
+
|
|
5
|
+
If you use an AI coding assistant, provide it with the following prompt before asking it to modify your project. This helps the assistant understand both your application's architecture and env-cap's design principles before making changes.
|
|
6
|
+
|
|
7
|
+
Replace `<YOUR_PROJECT_CONTEXT>` with any additional context about your application before submitting the prompt.
|
|
8
|
+
|
|
9
|
+
```text
|
|
10
|
+
You are integrating env-cap into an existing production codebase.
|
|
11
|
+
|
|
12
|
+
Package source:
|
|
13
|
+
https://github.com/maverickcer/env-cap
|
|
14
|
+
|
|
15
|
+
Before making any changes, first study the env-cap repository above, including:
|
|
16
|
+
|
|
17
|
+
- README.md
|
|
18
|
+
- Architecture documentation
|
|
19
|
+
- ADRs (architectural decision records)
|
|
20
|
+
- Examples
|
|
21
|
+
- Migration guides
|
|
22
|
+
- Package exports and API design
|
|
23
|
+
|
|
24
|
+
Understand the package's intended architecture and constraints before proposing an implementation.
|
|
25
|
+
|
|
26
|
+
Your role is to act as a senior/staff-level engineer performing an infrastructure integration review.
|
|
27
|
+
|
|
28
|
+
Application context:
|
|
29
|
+
<YOUR_PROJECT_CONTEXT>
|
|
30
|
+
|
|
31
|
+
First, analyze this repository and understand:
|
|
32
|
+
|
|
33
|
+
1. Application architecture:
|
|
34
|
+
- Framework and runtime(s)
|
|
35
|
+
- Build system and bundler behavior
|
|
36
|
+
- Monorepo/package boundaries (if applicable)
|
|
37
|
+
- Server/client boundaries
|
|
38
|
+
- Deployment environments
|
|
39
|
+
- CI/CD environment configuration
|
|
40
|
+
- Existing environment loading and validation flow
|
|
41
|
+
|
|
42
|
+
2. Current configuration system:
|
|
43
|
+
- Where environment variables are defined
|
|
44
|
+
- Where they are consumed
|
|
45
|
+
- Existing validation logic
|
|
46
|
+
- Existing documentation or generated configuration artifacts
|
|
47
|
+
- Security-sensitive variables
|
|
48
|
+
- Client-exposed variables
|
|
49
|
+
|
|
50
|
+
3. Integration approach:
|
|
51
|
+
- Determine where env-cap contracts should live
|
|
52
|
+
- Identify existing environment boundaries
|
|
53
|
+
- Determine whether validation contexts are appropriate
|
|
54
|
+
- Determine whether separate manifests/contracts are needed
|
|
55
|
+
- Identify migration risks
|
|
56
|
+
|
|
57
|
+
Follow env-cap's architectural principles:
|
|
58
|
+
|
|
59
|
+
- Runtime validation and build-time analysis are separate concerns.
|
|
60
|
+
- Generated artifacts are derived outputs, not manually maintained files.
|
|
61
|
+
- Server-only secrets must remain outside client bundles.
|
|
62
|
+
- Validation contexts control validation participation only; they are not a security boundary.
|
|
63
|
+
- Application code determines active validation contexts explicitly.
|
|
64
|
+
- Do not add framework-specific behavior to env-cap usage.
|
|
65
|
+
- Avoid unnecessary wrappers or abstractions unless they solve a real application need.
|
|
66
|
+
|
|
67
|
+
Before changing code, provide:
|
|
68
|
+
|
|
69
|
+
1. Current environment configuration architecture summary.
|
|
70
|
+
2. Recommended env-cap integration strategy.
|
|
71
|
+
3. Proposed migration steps.
|
|
72
|
+
4. Files that should change.
|
|
73
|
+
5. Risks and mitigations.
|
|
74
|
+
6. Questions requiring developer decisions.
|
|
75
|
+
|
|
76
|
+
Do not implement changes until the plan has been reviewed and approved.
|
|
77
|
+
|
|
78
|
+
After approval:
|
|
79
|
+
|
|
80
|
+
- Implement changes incrementally.
|
|
81
|
+
- Preserve existing behavior where possible.
|
|
82
|
+
- Add or update tests.
|
|
83
|
+
- Verify generated documentation/artifacts.
|
|
84
|
+
- Verify type safety.
|
|
85
|
+
- Verify build output.
|
|
86
|
+
- Verify CI/CD compatibility.
|
|
87
|
+
|
|
88
|
+
For the best results, provide your AI assistant access to both your repository and the env-cap repository. The assistant should understand your application's architecture before recommending how env-cap fits into it.
|
|
89
|
+
```
|
package/README.md
CHANGED
|
@@ -2,20 +2,50 @@
|
|
|
2
2
|
|
|
3
3
|
[](https://github.com/maverickcer/env-cap/actions/workflows/ci.yml)
|
|
4
4
|
[](https://www.npmjs.com/package/@maverickcer/env-cap)
|
|
5
|
+
[](https://maverickcer.github.io/env-cap/coverage.json)
|
|
6
|
+
[](https://maverickcer.github.io/env-cap/mutation.json)
|
|
7
|
+
[](https://scorecard.dev/viewer/?uri=github.com/MaverickCER/env-cap)
|
|
8
|
+
[](https://maverickcer.github.io/env-cap/size.json)
|
|
5
9
|
[](https://socket.dev/npm/package/@maverickcer/env-cap)
|
|
6
|
-
[](#quick-start)
|
|
10
|
+
[](https://www.npmjs.com/package/@maverickcer/env-cap)
|
|
11
|
+
[](LICENSE)
|
|
9
12
|
|
|
10
13
|
**Define who owns your environment variables, why they exist, and where they are used.**
|
|
11
14
|
|
|
12
|
-
`env-cap` turns environment configuration into capability-owned contracts you can version, review, validate, document, and query.
|
|
15
|
+
`env-cap` turns environment configuration into capability-owned contracts you can version, review, validate, document, and query. It keeps `dotenv`, Zod, envalid, t3-env, your secret manager, and plain `process.env` exactly where they are, and adds the layer they do not provide: ownership, lifecycle, and project-wide evidence about whether declared configuration is actually consumed.
|
|
13
16
|
|
|
14
|
-
|
|
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)
|
|
15
18
|
|
|
16
|
-
|
|
19
|
+
## Why it exists
|
|
20
|
+
|
|
21
|
+
**Benefit:** every environment variable has an owner, a reason to exist, and a lifecycle you can query, so a rotation deadline or an orphaned secret is found by a report instead of an outage.
|
|
22
|
+
|
|
23
|
+
**Problem:** a configuration value can be perfectly valid and still be a problem. A secret manager stores a credential securely and a validator confirms its shape, but neither says why the variable exists, which capability depends on it, who owns it, when it should be rotated or retired, or whether anything still consumes it. That knowledge drifts into wikis, Slack threads, and memory, until the application accepts a variable that nobody owns, nobody uses, or nobody remembers to retire.
|
|
24
|
+
|
|
25
|
+
**Who it is for:** platform and staff engineers responsible for configuration across teams or packages, and teams whose environment has outgrown a single `.env` convention.
|
|
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.
|
|
28
|
+
|
|
29
|
+
## How it differs
|
|
30
|
+
|
|
31
|
+
| Tool | What it solves | What remains unanswered |
|
|
32
|
+
| ---------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------- |
|
|
33
|
+
| `dotenv` | Loads values from a `.env` file | Who owns the value, why it exists, whether it is still used, when it expires |
|
|
34
|
+
| Zod / envalid / t3-env | Validates value shape and types | Whether the variable is still needed, who owns it, or what capability depends on it |
|
|
35
|
+
| Secret manager | Stores and manages secrets | Which capability in the codebase actually consumes the secret |
|
|
36
|
+
| `env-cap` | Defines ownership, lifecycle, and consumption contracts | Does not replace loading, secret storage, or application-specific validation |
|
|
37
|
+
|
|
38
|
+
`env-cap` is additive: use it with your existing validator or processor, or with its lightweight helpers when a validation library is unnecessary. [Migration guides](specs/migrations/README.md) cover `dotenv`, Zod, envalid, and t3-env, including cases where switching is not worth it.
|
|
17
39
|
|
|
18
|
-
##
|
|
40
|
+
## What it does
|
|
41
|
+
|
|
42
|
+
A capability declares the environment it owns next to the validation it already needs. A build-time pass reads those declarations and your source, and writes a project-wide manifest, documentation, an ownership report, and an evidence artifact. At runtime the application validates its environment against that manifest and reads typed, capability-scoped values.
|
|
43
|
+
|
|
44
|
+
```text
|
|
45
|
+
declare → generate → validate → consume
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
### See it run
|
|
19
49
|
|
|
20
50
|
**Every environment variable has an owner, a reason to exist, and a lifecycle you can query.**
|
|
21
51
|
|
|
@@ -73,233 +103,95 @@ $ npx tsx scripts/generate-docs/run.ts
|
|
|
73
103
|
- STRIPE_KEY in app
|
|
74
104
|
```
|
|
75
105
|
|
|
76
|
-
This is real output from [`examples/application`](examples/application)'s own `npm run docs` and `npm run docs:reports` scripts, not a mockup. The age (`Nd`) is counted from the day you run it, so it is shown as `N` here instead of a number that would rot.
|
|
77
|
-
|
|
78
|
-
The important part is what the analysis can establish:
|
|
79
|
-
|
|
80
|
-
- `STRIPE_KEY` has an ownership and expiration record.
|
|
81
|
-
- Its declared expiration has passed.
|
|
82
|
-
- `DATABASE_URL` and `STRIPE_KEY` are declared as owned but are not consumed by the analyzed application.
|
|
83
|
-
|
|
84
|
-
Those are facts about the application's configuration and dependencies, not merely the result of a value validator.
|
|
85
|
-
|
|
86
|
-
## Why it exists
|
|
87
|
-
|
|
88
|
-
A configuration value can be perfectly valid and still be a problem.
|
|
89
|
-
|
|
90
|
-
A secret manager can store a credential securely. A validator can confirm that it has the expected shape. Neither answers:
|
|
91
|
-
|
|
92
|
-
- Why does this variable exist?
|
|
93
|
-
- Which capability actually depends on it?
|
|
94
|
-
- Who owns it?
|
|
95
|
-
- When should it be reviewed, rotated, or retired?
|
|
96
|
-
- Is anything still consuming it?
|
|
106
|
+
This is real output from [`examples/application`](https://github.com/MaverickCER/env-cap/tree/main/examples/application)'s own `npm run docs` and `npm run docs:reports` scripts, not a mockup. The age (`Nd`) is counted from the day you run it, so it is shown as `N` here instead of a number that would rot.
|
|
97
107
|
|
|
98
|
-
|
|
108
|
+
The important part is what the analysis can establish: `STRIPE_KEY` has an ownership and expiration record, its declared expiration has passed, and `DATABASE_URL` and `STRIPE_KEY` are declared as owned but are not consumed by the analyzed application. Those are facts about the application's configuration and dependencies, not merely the result of a value validator.
|
|
99
109
|
|
|
100
|
-
|
|
110
|
+
### Evidence it works
|
|
101
111
|
|
|
102
|
-
**the
|
|
112
|
+
- **Real fixtures:** the output above comes from a runnable example that is also a regression test, and two more stages (a [team service](https://github.com/MaverickCER/env-cap/tree/main/examples/team-service) and an [enterprise platform](https://github.com/MaverickCER/env-cap/tree/main/examples/enterprise-platform)) show the model at scale.
|
|
113
|
+
- **Enforced in CI:** coverage is a ratchet that may only move up, mutation score is a gate ([CODE_REVIEW.md](CODE_REVIEW.md)), and the README's own demo is re-run and compared on every change.
|
|
114
|
+
- **Runtime-tested:** the runtime and helpers are verified against real Node, Bun, and Deno in CI, not assumed isomorphic.
|
|
115
|
+
- **Hard size budget:** the runtime entry point stays under 3 KB gzip and the helpers under 4 KB, enforced before publish ([ADR 0008](specs/decisions/0008-gzip-size-budget.md)).
|
|
116
|
+
- **Verifiable release:** published with npm OIDC provenance and no long-lived token ([SECURITY.md](SECURITY.md#supply-chain-posture)).
|
|
103
117
|
|
|
104
|
-
|
|
118
|
+
## Install and verify
|
|
105
119
|
|
|
106
|
-
|
|
120
|
+
**Prerequisites:** Node.js `>=22`. TypeScript 5, 6, or 7 is needed only for the build-time generator (the runtime works in plain JavaScript); the [runtime and TypeScript requirements](GUIDE.md#runtime-support-matrix) are in the Guide.
|
|
107
121
|
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
> **Validators answer whether a value is valid.
|
|
111
|
-
> env-cap answers why the value exists, who owns it, and whether the application still uses it.**
|
|
112
|
-
|
|
113
|
-
## Quick Start
|
|
114
|
-
|
|
115
|
-
**Start with one capability.**
|
|
116
|
-
|
|
117
|
-
```bash
|
|
122
|
+
```sh
|
|
118
123
|
npm install @maverickcer/env-cap
|
|
119
|
-
npx env-cap init
|
|
124
|
+
npx env-cap init # scaffolds env.schema.ts and scripts/generate-env.mjs
|
|
125
|
+
npm install --save-dev typescript # the generator parses your schema with it
|
|
126
|
+
node scripts/generate-env.mjs
|
|
120
127
|
```
|
|
121
128
|
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
If you prefer to create the contract yourself, the minimum setup is:
|
|
125
|
-
|
|
126
|
-
```ts
|
|
127
|
-
// features/payments/env.schema.ts
|
|
128
|
-
|
|
129
|
-
import { createEnv } from "@maverickcer/env-cap"
|
|
130
|
-
|
|
131
|
-
export const paymentsEnv = createEnv(
|
|
132
|
-
{
|
|
133
|
-
STRIPE_KEY: {
|
|
134
|
-
validator: (value: string) =>
|
|
135
|
-
value.startsWith("sk_") || 'Expected a key starting with "sk_".',
|
|
136
|
-
},
|
|
137
|
-
},
|
|
138
|
-
{ name: "payments" },
|
|
139
|
-
)
|
|
140
|
-
```
|
|
129
|
+
**Using an AI agent?** Give it [the skill](https://raw.githubusercontent.com/MaverickCER/env-cap/main/skills/env-cap/SKILL.md): a short manual written from this package's own exports, with the rules a type signature cannot say.
|
|
141
130
|
|
|
142
|
-
|
|
131
|
+
`init` never overwrites existing files and never edits `package.json`. **Verify it works:** the generator prints `Discovered 1 contract(s).` and writes the manifest, `docs/ENVIRONMENT.md`, and an ownership report. Then validate once at startup and read values through the contract:
|
|
143
132
|
|
|
144
133
|
```ts
|
|
145
|
-
// app.ts
|
|
146
|
-
|
|
147
134
|
import { validateEnv } from "@maverickcer/env-cap"
|
|
148
|
-
|
|
149
135
|
import { manifest } from "./generated/env.manifest"
|
|
150
136
|
import { paymentsEnv } from "./features/payments/env.schema"
|
|
151
137
|
|
|
152
|
-
await validateEnv({
|
|
153
|
-
manifest,
|
|
154
|
-
values: process.env,
|
|
155
|
-
})
|
|
156
|
-
|
|
138
|
+
await validateEnv({ manifest, values: process.env })
|
|
157
139
|
paymentsEnv.STRIPE_KEY
|
|
158
140
|
```
|
|
159
141
|
|
|
160
|
-
The
|
|
161
|
-
|
|
162
|
-
```text
|
|
163
|
-
declare → generate → validate → consume
|
|
164
|
-
```
|
|
165
|
-
|
|
166
|
-
`generateEnvManifest()` produces the project-wide manifest. Runtime validation uses that manifest against the environment values supplied by the application.
|
|
167
|
-
|
|
168
|
-
See the [Guide's Core workflow](GUIDE.md#core-workflow) for the complete generate/validate cycle.
|
|
169
|
-
|
|
170
|
-
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, bundled inside the package and used only by the build entry; it adds about 26 MB 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). See the [runtime support matrix](GUIDE.md#runtime-support-matrix) for Node, browser bundles, edge runtimes, Bun, and Deno.
|
|
171
|
-
|
|
172
|
-
## What declared metadata can express
|
|
173
|
-
|
|
174
|
-
**Ownership and lifecycle data isn't documentation bolted onto validation — it's what the build-time analysis actually queries:**
|
|
175
|
-
|
|
176
|
-
```ts
|
|
177
|
-
documentEnv(paymentsSchema, {
|
|
178
|
-
owner: "payments-team",
|
|
179
|
-
variables: {
|
|
180
|
-
STRIPE_KEY: {
|
|
181
|
-
description: "Stripe secret key used to create charges and process refunds.",
|
|
182
|
-
owner: "payments-team",
|
|
183
|
-
expiresAt: "2027-01-01",
|
|
184
|
-
sensitivity: "secret",
|
|
185
|
-
},
|
|
186
|
-
},
|
|
187
|
-
})
|
|
188
|
-
```
|
|
189
|
-
|
|
190
|
-
That `expiresAt` is what powers the "expiring soon or already expired" line in [See it run](#see-it-run) above — not a separate expiration-tracking system, the same declaration the validator already needs. The same build pass cross-references every declared variable against actual usage in your source, which is what produces the "unconsumed owned variable(s)" warning: a variable can be perfectly valid and still be a problem nobody's watching. The [Guide](GUIDE.md#capability-owned-contracts) has the full model — capability-scoped ownership, rotation cadence, storage provider, access policy.
|
|
191
|
-
|
|
192
|
-
## Why not just use existing tools?
|
|
193
|
-
|
|
194
|
-
`env-cap` is deliberately additive.
|
|
195
|
-
|
|
196
|
-
| Tool | What it solves | What remains unanswered |
|
|
197
|
-
| ---------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------- |
|
|
198
|
-
| `dotenv` | Loads values from a `.env` file | Who owns the value, why it exists, whether it is still used, when it expires |
|
|
199
|
-
| Zod / envalid / t3-env | Validates value shape and types | Whether the variable is still needed, who owns it, or what capability depends on it |
|
|
200
|
-
| Secret manager | Stores and manages secrets | Which capability in the codebase actually consumes the secret |
|
|
201
|
-
| `env-cap` | Defines ownership, lifecycle, and consumption contracts | Does not replace loading, secret storage, or application-specific validation |
|
|
202
|
-
|
|
203
|
-
**You keep your existing tools.**
|
|
204
|
-
|
|
205
|
-
Use `env-cap` with your existing validator or processor, or use its lightweight helpers when a dedicated validation library is unnecessary. What env-cap adds is the layer around the value: ownership, lifecycle, and project-wide evidence about whether declared configuration is actually consumed.
|
|
206
|
-
|
|
207
|
-
You do not have to migrate away from an existing configuration library to adopt env-cap. The [migration guides](specs/migrations/) document the adoption path for `dotenv`, Zod, envalid, and t3-env, including cases where switching is unnecessary.
|
|
208
|
-
|
|
209
|
-
## From one schema to a whole organization
|
|
210
|
-
|
|
211
|
-
```text
|
|
212
|
-
one schema, one team
|
|
213
|
-
| ownership boundaries start to matter
|
|
214
|
-
capability-owned schemas, one per feature
|
|
215
|
-
| share it
|
|
216
|
-
reusable package contracts
|
|
217
|
-
| scale it
|
|
218
|
-
organization-wide configuration ownership
|
|
219
|
-
```
|
|
220
|
-
|
|
221
|
-
A capability contract records what a variable is for, who owns it, how sensitive it is, when it expires, and whether the codebase still consumes it. Start with a single centralized schema and move toward capability- or package-owned contracts only as ownership boundaries start to matter — `generateEnvManifest()` produces one project-wide manifest regardless of how many contracts contribute to it, so validation, documentation, and ownership reporting never depend on how the schema is organized.
|
|
222
|
-
|
|
223
|
-
The [`examples/`](examples/) directory has three runnable stages of that model — [`examples/application`](examples/application), [`examples/team-service`](examples/team-service), and [`examples/enterprise-platform`](examples/enterprise-platform) — and the [Guide](GUIDE.md#capability-owned-contracts) covers the full walkthrough.
|
|
224
|
-
|
|
225
|
-
## You probably don't need it when
|
|
226
|
-
|
|
227
|
-
A validation library or `dotenv` may be enough when:
|
|
228
|
-
|
|
229
|
-
- the application is small;
|
|
230
|
-
- one team owns every configuration decision;
|
|
231
|
-
- there are only a few environment variables;
|
|
232
|
-
- variables rarely change;
|
|
233
|
-
- ownership and lifecycle are already obvious;
|
|
234
|
-
- you do not need project-wide evidence about configuration usage.
|
|
235
|
-
|
|
236
|
-
`env-cap` becomes more useful when configuration starts crossing capability, team, package, or organizational boundaries.
|
|
237
|
-
|
|
238
|
-
## Works with automated contributors
|
|
239
|
-
|
|
240
|
-
AI coding agents, CI bots, and release automation can consume the same manifests and evidence artifacts as human contributors.
|
|
241
|
-
|
|
242
|
-
A structured finding such as:
|
|
243
|
-
|
|
244
|
-
```text
|
|
245
|
-
payments owns STRIPE_KEY
|
|
246
|
-
STRIPE_KEY is declared but unconsumed
|
|
247
|
-
```
|
|
248
|
-
|
|
249
|
-
gives automation a concrete fact to investigate.
|
|
250
|
-
|
|
251
|
-
That is more useful than a generic failure such as:
|
|
252
|
-
|
|
253
|
-
```text
|
|
254
|
-
configuration check failed
|
|
255
|
-
```
|
|
256
|
-
|
|
257
|
-
The repository can therefore use the same configuration contract to guide both human and automated changes.
|
|
258
|
-
|
|
259
|
-
See the [AI Integration Prompt](./PROMPT.md) for a repository-aware review workflow.
|
|
260
|
-
|
|
261
|
-
## Status
|
|
262
|
-
|
|
263
|
-
`env-cap` is currently in `0.x`.
|
|
264
|
-
|
|
265
|
-
Per [VERSIONING.md](VERSIONING.md), a minor release may include a breaking change to a Stable-tier API before 1.0. Pin according to your upgrade policy.
|
|
266
|
-
|
|
267
|
-
The architecture is considered stable; APIs may continue to evolve based on production usage.
|
|
268
|
-
|
|
269
|
-
## Learn more
|
|
142
|
+
The smallest contract is one `createEnv` call with a validator per variable ([Core workflow](GUIDE.md#core-workflow) has the complete generate and validate cycle).
|
|
270
143
|
|
|
271
|
-
|
|
144
|
+
## Fit and capabilities
|
|
272
145
|
|
|
273
|
-
|
|
146
|
+
**Use cases:** find expired or unowned secrets before they page someone; document every variable from the code instead of a wiki; let each team own the variables its feature needs; give CI bots and coding agents concrete facts (`payments owns STRIPE_KEY`, `STRIPE_KEY is declared but unconsumed`) instead of "configuration check failed".
|
|
274
147
|
|
|
275
|
-
|
|
148
|
+
**Core capabilities:**
|
|
276
149
|
|
|
277
|
-
-
|
|
150
|
+
- Capability-scoped contracts with validators, ownership, sensitivity, and expiry ([model](GUIDE.md#capability-owned-contracts)).
|
|
151
|
+
- A project-wide manifest, environment docs, `.env.example`, and an ownership and unconsumed-variable report, generated by static analysis that never executes your schema files.
|
|
152
|
+
- A persisted evidence artifact for change tracking, a CLI, a [GitHub Action](GUIDE.md#github-action), scheduled rotation alerts, and an [ESLint plugin](GUIDE.md#eslint-plugin).
|
|
153
|
+
- Adoption from one centralized schema to per-feature and per-package contracts; the manifest stays project-wide however the schema is organized.
|
|
278
154
|
|
|
279
|
-
|
|
155
|
+
**How it works:** the runtime and the build tooling are separate on purpose. Runtime validation needs no dependencies and no filesystem; the build pass analyzes your source and runs only in development and CI ([Architecture](specs/architecture.md)).
|
|
280
156
|
|
|
281
|
-
-
|
|
157
|
+
**Integration:** it works beside the validator and secret manager you already use, so nothing is replaced. **Runtimes:** Node.js 22+, browser bundles, edge runtimes, Bun, and Deno for the runtime; the build entry is Node-only ([support matrix](GUIDE.md#runtime-support-matrix)). **Configuration and extension:** plug any `Validator<T>` or `Processor<T>` function into a contract, share contracts from a reusable package, and resolve TypeScript path aliases ([Guide](GUIDE.md)).
|
|
282
158
|
|
|
283
|
-
|
|
159
|
+
## Limits and when not to use it
|
|
284
160
|
|
|
285
|
-
|
|
161
|
+
- **Skip it when** the application is small, one team owns every configuration decision, there are only a few stable variables, ownership is already obvious, or you do not need project-wide evidence about usage. A validation library or `dotenv` may be all you need.
|
|
162
|
+
- **Trade-offs:** it adds a build step and a declaration per variable, and its reports are only as accurate as those declarations. It cannot see variables read from outside the code it analyzes.
|
|
163
|
+
- **Install weight:** the build entry bundles a TypeScript 6 compiler (about 24 MB unpacked) used only in development and CI; the runtime never reaches it, which CI verifies ([Adoption guide](ADOPTION.md#bundle-size-and-performance)).
|
|
164
|
+
- **Automation:** agents and bots can consume the same manifests and evidence, but a structured finding does not guarantee a correct fix; the automation owns its retry and validation loop. See the [AI integration prompt](PROMPT.md).
|
|
286
165
|
|
|
287
|
-
|
|
166
|
+
## Security and supply chain
|
|
288
167
|
|
|
289
|
-
|
|
168
|
+
- **Guarantees:** the runtime never persists, retrieves, rotates, or logs secrets, and contracts redact themselves when logged or serialized ([runtime security model](SECURITY.md#runtime-security-model)).
|
|
169
|
+
- **Trust boundaries:** the build tool parses schema files as ASTs and never imports or executes them, but it does not sandbox the rest of your build, and a validator you write can still log ([build-time model](SECURITY.md#build-time-security-model), [your responsibilities](SECURITY.md#application-responsibilities)).
|
|
170
|
+
- **Dependencies and licence:** zero runtime dependencies in the runtime and helpers entry points; the build entry bundles one compiler. MIT licensed.
|
|
171
|
+
- **Release integrity:** npm OIDC trusted publishing with provenance ([supply-chain posture](SECURITY.md#supply-chain-posture)). Report a vulnerability through [SECURITY.md](SECURITY.md#reporting-a-vulnerability).
|
|
290
172
|
|
|
291
|
-
##
|
|
173
|
+
## Maturity, versioning and support
|
|
292
174
|
|
|
293
|
-
|
|
175
|
+
Pre-1.0 (see the npm badge for the current version). Per [VERSIONING.md](VERSIONING.md), a minor release may include a breaking change to the Stable tier before 1.0, so pin accordingly. Security fixes target the latest published `0.x` only; there is no backport branch until 1.0 ([Adoption guide](ADOPTION.md#versioning-stability-and-long-term-support)).
|
|
294
176
|
|
|
295
|
-
|
|
177
|
+
- **Upgrade and migrate:** read the [CHANGELOG](CHANGELOG.md) on every minor; [migration guides](specs/migrations/README.md) cover adoption from other tools.
|
|
178
|
+
- **Release history:** [CHANGELOG](CHANGELOG.md) and [GitHub releases](https://github.com/MaverickCER/env-cap/releases); the process is in [RELEASING.md](RELEASING.md).
|
|
179
|
+
- **Bugs and requests:** [open an issue](https://github.com/MaverickCER/env-cap/issues); see [SUPPORT.md](SUPPORT.md).
|
|
180
|
+
- **Troubleshooting:** the [Guide's troubleshooting section](GUIDE.md#troubleshooting).
|
|
296
181
|
|
|
297
|
-
|
|
182
|
+
## Documentation
|
|
298
183
|
|
|
299
|
-
[
|
|
184
|
+
- **[Guide](GUIDE.md)**: the complete generate and validate workflow, validation contexts, reusable packages, path aliases, CLI, GitHub Action, ESLint plugin, and performance.
|
|
185
|
+
- **[Adoption guide](ADOPTION.md)**: the decision-maker summary of security, bundle size, and versioning.
|
|
186
|
+
- **[API reference](https://maverickcer.github.io/env-cap/api/)**: every exported symbol, generated from source.
|
|
187
|
+
- **[Architecture](specs/architecture.md)** and **[ADRs](https://github.com/MaverickCER/env-cap/tree/main/specs/decisions)**: why it is designed this way.
|
|
188
|
+
- **[Examples](https://github.com/MaverickCER/env-cap/tree/main/examples)**: runnable application, team-service, and enterprise-platform examples.
|
|
189
|
+
- **Part of the MaverickCER toolkit:** `@maverickcer/env-cap` governs configuration and `data-cap` governs application data; `repo-contract` and `internal-package-contract` are how they are verified ([toolkit overview](https://github.com/MaverickCER/internal-package-contract/blob/main/TOOLKIT.md)).
|
|
300
190
|
|
|
301
|
-
|
|
191
|
+
## Next steps
|
|
302
192
|
|
|
303
|
-
|
|
193
|
+
- **Evaluate:** read the [Adoption guide](ADOPTION.md), then try env-cap against one real schema.
|
|
194
|
+
- **Integrate:** follow the [Guide](GUIDE.md#core-workflow) and the [examples](https://github.com/MaverickCER/env-cap/tree/main/examples).
|
|
195
|
+
- **Verify:** inspect the [security model](SECURITY.md#runtime-security-model) and the [architecture](specs/architecture.md).
|
|
304
196
|
|
|
305
|
-
MIT
|
|
197
|
+
Contributing: [CONTRIBUTING.md](CONTRIBUTING.md) covers setup, the change workflow, ADRs and changesets; [CODE_REVIEW.md](CODE_REVIEW.md) covers review. License: MIT, see [LICENSE](LICENSE).
|
package/RELEASING.md
ADDED
|
@@ -0,0 +1,160 @@
|
|
|
1
|
+
<!-- Managed by internal-package-contract. Do not edit this file: change template/package/RELEASING.md in the standard and run `internal-package-contract sync`. -->
|
|
2
|
+
|
|
3
|
+
# Releasing @maverickcer/env-cap
|
|
4
|
+
|
|
5
|
+
Maintainer-facing. Contributors don't run any of this: a normal change is just a pull request, and its
|
|
6
|
+
changeset is generated if it has none (see [`CONTRIBUTING.md`](CONTRIBUTING.md#making-a-change)).
|
|
7
|
+
For what semver actually covers, see [`VERSIONING.md`](VERSIONING.md).
|
|
8
|
+
|
|
9
|
+
## How releases work
|
|
10
|
+
|
|
11
|
+
Releases are driven by [Changesets](https://github.com/changesets/changesets) and npm's
|
|
12
|
+
[OIDC trusted publishing](https://docs.npmjs.com/trusted-publishers), through
|
|
13
|
+
[`.github/workflows/release.yml`](https://github.com/MaverickCER/env-cap/blob/main/.github/workflows/release.yml),
|
|
14
|
+
which calls a shared, pinned workflow. **No `NPM_TOKEN` secret exists in this repository** and none is
|
|
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; nothing
|
|
17
|
+
publishes without that.
|
|
18
|
+
|
|
19
|
+
The loop:
|
|
20
|
+
|
|
21
|
+
1. A pull request that changes user-facing behavior carries a changeset in `.changeset/` (Markdown,
|
|
22
|
+
`patch`/`minor`/`major` plus a consumer-facing description). When it does not, one is generated on `main`
|
|
23
|
+
from the commit messages (`feat`, `fix`, `perf`, `revert` or a breaking marker; a `Changeset: <bump>`
|
|
24
|
+
trailer overrides). Below 1.0.0 a generated bump never exceeds minor, so 1.0.0 is reached only by a
|
|
25
|
+
deliberate `major` changeset.
|
|
26
|
+
2. On each push to `main`, the workflow opens or updates a pull request titled **"chore: version packages"**
|
|
27
|
+
from the branch **`changeset-release/main`** and dispatches CI on it. That pull request consumes the
|
|
28
|
+
changeset files, bumps `package.json`'s `version` and rewrites `CHANGELOG.md`. Review it and merge it
|
|
29
|
+
yourself; it is never merged automatically.
|
|
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, packs the tarball, installs that tarball into an empty
|
|
32
|
+
project and imports every entry point it declares. Only if all of that passes does the **publish** job
|
|
33
|
+
run, and only from the default branch. It publishes exactly the tarball the build job made, over OIDC with
|
|
34
|
+
a provenance attestation.
|
|
35
|
+
4. After publishing, the workflow tags the release `v<major>.<minor>.<patch>` on the merged commit,
|
|
36
|
+
force-updates the floating major tag (`v0` while the package is 0.x, `v1` from 1.0.0), and asks npm what
|
|
37
|
+
it now serves: the version must be there and must carry the provenance attestation, or the run goes red.
|
|
38
|
+
The floating tag tracks the composite Action's interface (`action.yml` inputs and outputs), so
|
|
39
|
+
`uses: maverickcer/env-cap@v0` keeps pointing at the latest compatible build until `action.yml` itself
|
|
40
|
+
has a breaking change.
|
|
41
|
+
|
|
42
|
+
`CHANGELOG.md` is generated; never hand-edit it. Fix a wrong entry by correcting the offending changeset
|
|
43
|
+
before the version pull request is merged, or with a follow-up changeset after.
|
|
44
|
+
|
|
45
|
+
## First-time setup
|
|
46
|
+
|
|
47
|
+
One-time, before the very first automated release. Requires npm account
|
|
48
|
+
access, so it can't be done from a PR.
|
|
49
|
+
|
|
50
|
+
1. On [npmjs.com](https://www.npmjs.com), open `@maverickcer/env-cap`'s
|
|
51
|
+
package settings → **Publishing access** → add a **trusted publisher** for
|
|
52
|
+
GitHub Actions:
|
|
53
|
+
- Organization or user: `maverickcer`
|
|
54
|
+
- Repository: `env-cap`
|
|
55
|
+
- Workflow filename: `release.yml` (exactly — just the filename, not a
|
|
56
|
+
path; a mismatch here is the most common cause of the OIDC flow failing
|
|
57
|
+
with a misleading `E404`)
|
|
58
|
+
- Environment: leave blank unless `release.yml` is later scoped to a
|
|
59
|
+
GitHub Environment
|
|
60
|
+
2. That's the whole trust relationship — `release.yml`'s `id-token: write`
|
|
61
|
+
permission plus this registration. There is no token to copy anywhere.
|
|
62
|
+
|
|
63
|
+
Until the package exists on npm, its settings page doesn't either. For the
|
|
64
|
+
**first ever publish**, register the trusted publisher immediately after the
|
|
65
|
+
first `npm publish` (a one-time manual `npm publish --access public` from a
|
|
66
|
+
maintainer machine, from a clean `npm run verify` tree), then let every
|
|
67
|
+
subsequent release go through `release.yml`. Alternatively, publish an empty
|
|
68
|
+
`0.0.0` placeholder manually first, register the trusted publisher, then let
|
|
69
|
+
the first real version pull request publish `0.1.0` over OIDC.
|
|
70
|
+
|
|
71
|
+
## Recovering from a failed release
|
|
72
|
+
|
|
73
|
+
Identify which state you're in first — the recovery differs and the wrong
|
|
74
|
+
one can double-publish or lose a version.
|
|
75
|
+
|
|
76
|
+
### A. The version pull request is open, nothing published yet
|
|
77
|
+
|
|
78
|
+
Safe state. The bump only exists on the `changeset-release/main` branch.
|
|
79
|
+
Fix forward: push more changesets to `main` (the PR auto-updates), or edit
|
|
80
|
+
the PR branch directly if the generated `CHANGELOG.md`/version is wrong.
|
|
81
|
+
Nothing is on npm; nothing to undo.
|
|
82
|
+
|
|
83
|
+
### B. The version pull request is merged, but the release failed
|
|
84
|
+
|
|
85
|
+
`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` or packed-consumer check in the build job, a
|
|
87
|
+
registry blip).
|
|
88
|
+
|
|
89
|
+
1. Confirm npm really doesn't have it: `npm view @maverickcer/env-cap versions --json`, and check the bumped version is
|
|
90
|
+
absent.
|
|
91
|
+
2. Find the cause (see [Common failures](#common-failure-causes)).
|
|
92
|
+
3. If it was transient or a configuration problem outside the repository (a registry blip, the
|
|
93
|
+
trusted-publisher registration), fix that and re-run the failed `release.yml` run from the Actions tab
|
|
94
|
+
("Re-run failed jobs"). A re-run uses the same commit.
|
|
95
|
+
4. If the cause is in the code, a re-run cannot help: it would build the same commit again. Fix it in a normal
|
|
96
|
+
pull request to `main`. What happens next depends on the commit type. A `fix`, `feat`, `perf` or `revert`
|
|
97
|
+
commit gets a changeset generated for it, so the workflow opens a new version pull request instead of
|
|
98
|
+
publishing the stuck version; merging that publishes the next version, and the stuck version number is
|
|
99
|
+
simply skipped. A commit type that releases nothing (`chore`, `ci`, `docs`) leaves no changeset, so the
|
|
100
|
+
workflow sees that the current `package.json` version isn't on npm and builds and publishes that version.
|
|
101
|
+
5. Publishing by hand is the last resort, and it publishes without the provenance attestation that the
|
|
102
|
+
workflow adds. If you must, publish that exact version from a clean tree
|
|
103
|
+
(`git checkout main && npm ci && npm run verify && npm publish --access public`), then confirm the next push
|
|
104
|
+
to `main` produces no spurious version pull request.
|
|
105
|
+
|
|
106
|
+
### C. Published to npm, but a later workflow step failed
|
|
107
|
+
|
|
108
|
+
e.g. the publish succeeded but the floating major tag (`v0` or `v1`) roll failed. The release itself
|
|
109
|
+
is done and correct. Just fix the trailing step manually:
|
|
110
|
+
|
|
111
|
+
```bash
|
|
112
|
+
git checkout main && git pull
|
|
113
|
+
git tag -f v0 && git push origin v0 --force # while the package is 0.x
|
|
114
|
+
git tag -f v1 && git push origin v1 --force # from 1.0.0
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Do **not** re-run the whole workflow — `changeset publish` is idempotent and
|
|
118
|
+
will no-op on the already-published version, but re-running risks masking
|
|
119
|
+
whatever the real trailing failure was.
|
|
120
|
+
|
|
121
|
+
### D. Wrong version published
|
|
122
|
+
|
|
123
|
+
npm publishes are effectively permanent (`npm unpublish` is allowed only
|
|
124
|
+
within 72 hours and only if nothing depends on it, and the version number
|
|
125
|
+
can never be reused). Don't try to unpublish a normal mistake. Instead:
|
|
126
|
+
|
|
127
|
+
- Wrong contents, right version number: publish a patch (`x.y.z+1`) with a
|
|
128
|
+
changeset that fixes it, and `npm deprecate @maverickcer/env-cap@x.y.z
|
|
129
|
+
"Broken publish — use x.y.z+1"`.
|
|
130
|
+
- Accidental major/minor bump: it stays. Continue from the new baseline; a
|
|
131
|
+
version number is cheap, a rewritten history is not.
|
|
132
|
+
|
|
133
|
+
### E. First release, package not yet on npm
|
|
134
|
+
|
|
135
|
+
See [First-time setup](#first-time-setup) — the trusted-publisher
|
|
136
|
+
registration cannot exist before the package does, so the first publish is
|
|
137
|
+
the one manual step. Every release after that is automated.
|
|
138
|
+
|
|
139
|
+
## Common failure causes
|
|
140
|
+
|
|
141
|
+
- **`E404` on publish with OIDC**: the trusted-publisher registration's
|
|
142
|
+
workflow filename doesn't exactly match `release.yml`, or the
|
|
143
|
+
org/user/repo fields are wrong.
|
|
144
|
+
- **The build job's verify or packed-consumer step fails**: the version pull request merged with a red
|
|
145
|
+
`main`, or the tarball does not contain what `exports` promises. Fix `main` first, then recover per case B.
|
|
146
|
+
- **The final "Verify what npm now serves" step fails**: npm did not return the version or its provenance
|
|
147
|
+
attestation. Nothing is unpublished by the failure; look at the registry before doing anything else.
|
|
148
|
+
- **A version pull request appears when you didn't expect one**: there's a stray changeset file in `.changeset/` on `main`. If it's
|
|
149
|
+
spurious, delete it in a normal PR.
|
|
150
|
+
- **Two version pull requests**: an older one wasn't closed when `main` moved. Close the stale one; the
|
|
151
|
+
workflow only maintains the newest.
|
|
152
|
+
|
|
153
|
+
## Related
|
|
154
|
+
|
|
155
|
+
- [`VERSIONING.md`](VERSIONING.md) — what each bump type means, and which
|
|
156
|
+
surface semver actually covers.
|
|
157
|
+
- [`CONTRIBUTING.md`](CONTRIBUTING.md) — the contributor-side workflow
|
|
158
|
+
(branch, changeset, PR).
|
|
159
|
+
- [`SECURITY.md`](SECURITY.md#supported-versions) — which versions get
|
|
160
|
+
security fixes.
|