micro-contracts 0.18.15 → 0.18.16
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/cli-contract.yaml +1 -1
- package/dist/generated/contract.js +2 -2
- package/dist/guardrails/allowlist.d.ts +6 -1
- package/dist/guardrails/allowlist.d.ts.map +1 -1
- package/dist/guardrails/allowlist.js +101 -15
- package/dist/guardrails/allowlist.js.map +1 -1
- package/dist/guardrails/config.d.ts.map +1 -1
- package/dist/guardrails/config.js +17 -9
- package/dist/guardrails/config.js.map +1 -1
- package/dist/guardrails/runner.d.ts.map +1 -1
- package/dist/guardrails/runner.js +5 -1
- package/dist/guardrails/runner.js.map +1 -1
- package/dist/guardrails/types.d.ts +5 -0
- package/dist/guardrails/types.d.ts.map +1 -1
- package/dist/micro-contracts.bundle.mjs +311 -311
- package/dist/micro-contracts.bundle.mjs.map +3 -3
- package/docs/cli-reference.md +1 -1
- package/docs/development-guardrails.md +42 -3
- package/package.json +2 -1
package/docs/cli-reference.md
CHANGED
|
@@ -159,7 +159,7 @@ Files are categorized into three groups:
|
|
|
159
159
|
| Category | Examples | Who can edit |
|
|
160
160
|
|----------|----------|--------------|
|
|
161
161
|
| `allowed` | `spec/**/*.yaml`, `server/src/**/services/**` | Anyone (AI or human) |
|
|
162
|
-
| `protected` | `.github/**`, `spec/spectral.yaml`, `server/src/_shared/overlays/**` |
|
|
162
|
+
| `protected` | `.github/**`, `spec/spectral.yaml`, `server/src/_shared/overlays/**` | Anyone, once a maintainer approves the pull request (see below) |
|
|
163
163
|
| `generated` | `packages/**`, `*.generated.*` | Only via `generate` command |
|
|
164
164
|
|
|
165
165
|
Patterns are evaluated in order and the last match wins, so a negation (`!pattern`)
|
|
@@ -169,6 +169,35 @@ Protected files include:
|
|
|
169
169
|
- CI/workflow definitions (`.github/**`) — guardrail bypass prevention
|
|
170
170
|
- Spectral lint rules (`spec/spectral.yaml`) — security rule tampering
|
|
171
171
|
- Shared overlay implementations (`server/src/_shared/overlays/**`) — security logic
|
|
172
|
+
- The guardrails config itself, under every name it is loaded as
|
|
173
|
+
(`micro-contracts.guardrails.yaml`/`.yml`, and the legacy `guardrails.yaml`/`.yml`)
|
|
174
|
+
|
|
175
|
+
#### Approving a protected change
|
|
176
|
+
|
|
177
|
+
**The approval is the `guardrails-approved` label on the pull request.** With it, the
|
|
178
|
+
protected paths in that pull request pass the gate; the check reports the pass and names
|
|
179
|
+
each path it let through, so a run that waived something never reads like one that waived
|
|
180
|
+
nothing. Removing the label makes the gate red again.
|
|
181
|
+
|
|
182
|
+
An approval covers `protected` paths only. A file that no pattern describes still fails as
|
|
183
|
+
`not-in-allowlist`: the label says "yes, change that protected path", not "yes, change
|
|
184
|
+
anything".
|
|
185
|
+
|
|
186
|
+
The label is a human's act in the GitHub UI, and CI cannot perform it — adding a label
|
|
187
|
+
needs `pull-requests: write` and the workflow runs with `contents: read`. The check reads
|
|
188
|
+
the labels out of the event payload the run was triggered with, so the same run always
|
|
189
|
+
reaches the same verdict.
|
|
190
|
+
|
|
191
|
+
Two things follow for the workflow:
|
|
192
|
+
|
|
193
|
+
- `on.pull_request.types` must include `labeled` and `unlabeled`. The default types
|
|
194
|
+
(`opened`, `synchronize`, `reopened`) do not re-run anything when a label changes, so
|
|
195
|
+
the approval would arrive after the only run that could have read it.
|
|
196
|
+
- `permissions` must **not** grant `pull-requests: write`, or the workflow could label its
|
|
197
|
+
own pull request and the approval would be approving itself.
|
|
198
|
+
|
|
199
|
+
Outside a pull request there is nothing to read and the check stays strict: a working copy
|
|
200
|
+
has no local flag, variable or option that waives a protected path.
|
|
172
201
|
|
|
173
202
|
### Gate 2: OpenAPI Spec Validation
|
|
174
203
|
|
|
@@ -470,10 +499,15 @@ npx --yes -p micro-contracts@${MICRO_CONTRACTS_VERSION} micro-contracts check
|
|
|
470
499
|
|
|
471
500
|
### Protecting `.github/**`
|
|
472
501
|
|
|
473
|
-
- Feature branches MUST NOT modify `.github/**`
|
|
474
|
-
- Changes require dedicated "infra PR"
|
|
502
|
+
- Feature branches MUST NOT modify `.github/**` on their own
|
|
503
|
+
- Changes require a dedicated "infra PR" carrying the `guardrails-approved` label, applied
|
|
504
|
+
by one of the owners below
|
|
475
505
|
- **Rationale**: CI definition is part of the guardrail
|
|
476
506
|
|
|
507
|
+
Create the label once per repository (`gh label create guardrails-approved`), and restrict
|
|
508
|
+
who may apply it through repository roles: applying a label needs write access, which is
|
|
509
|
+
what makes it usable as an approval at all.
|
|
510
|
+
|
|
477
511
|
### Required Status Checks
|
|
478
512
|
|
|
479
513
|
`main` branch protection must require these **2 job names**:
|
|
@@ -494,6 +528,9 @@ npx --yes -p micro-contracts@${MICRO_CONTRACTS_VERSION} micro-contracts check
|
|
|
494
528
|
| `micro-contracts.guardrails.yaml` | security/platform | Guardrail config |
|
|
495
529
|
| `.github/**` | infra/maintainer | CI definitions |
|
|
496
530
|
|
|
531
|
+
These owners are who to ask for the `guardrails-approved` label. CODEOWNERS decides whose
|
|
532
|
+
review GitHub requires; the label is what Gate 1 reads.
|
|
533
|
+
|
|
497
534
|
---
|
|
498
535
|
|
|
499
536
|
## Developer Workflow
|
|
@@ -518,6 +555,8 @@ npx --yes -p micro-contracts@${MICRO_CONTRACTS_VERSION} micro-contracts check
|
|
|
518
555
|
|----------|------|--------|
|
|
519
556
|
| Edit `spec/**/*.yaml` → regenerate → commit | — | ✅ Allowed |
|
|
520
557
|
| Edit `server/src/**/services/**` | — | ✅ Allowed |
|
|
558
|
+
| Edit `.github/**` without the `guardrails-approved` label | 1 | ❌ Blocked |
|
|
559
|
+
| Edit `.github/**` with the `guardrails-approved` label | 1 | ✅ Allowed, and named in the check output |
|
|
521
560
|
| Edit `packages/**/*.ts` directly | 1 | ❌ Blocked |
|
|
522
561
|
| Edit `*.generated.ts` directly | 1 | ❌ Blocked |
|
|
523
562
|
| Edit spec but forget to regenerate | 3 | ❌ Fails drift |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "micro-contracts",
|
|
3
|
-
"version": "0.18.
|
|
3
|
+
"version": "0.18.16",
|
|
4
4
|
"description": "Contract-first OpenAPI toolchain that keeps TypeScript UI and microservices aligned via code generation",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -38,6 +38,7 @@
|
|
|
38
38
|
"generate": "tsx src/cli.ts generate",
|
|
39
39
|
"contract:validate": "npx cli-contracts validate",
|
|
40
40
|
"contract:generate": "npx cli-contracts generate",
|
|
41
|
+
"contract:check": "npx cli-contracts version-sync --check && npx cli-contracts generate && git diff --exit-code cli-contract.yaml src/generated docs/cli-reference.md",
|
|
41
42
|
"dsl:generate": "npx agent-runtime generate --config dsl/agent-runtime.config.yaml",
|
|
42
43
|
"docs:sync": "npx embedoc build",
|
|
43
44
|
"docs:check": "npx embedoc build && git diff --exit-code README.md docs/",
|