micro-contracts 0.18.14 → 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 +7 -2
- package/dist/guardrails/allowlist.d.ts.map +1 -1
- package/dist/guardrails/allowlist.js +146 -19
- package/dist/guardrails/allowlist.js.map +1 -1
- package/dist/guardrails/config.d.ts.map +1 -1
- package/dist/guardrails/config.js +26 -11
- 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 +315 -312
- package/dist/micro-contracts.bundle.mjs.map +3 -3
- package/docs/cli-reference.md +1 -1
- package/docs/development-guardrails.md +54 -7
- package/package.json +2 -1
package/docs/cli-reference.md
CHANGED
|
@@ -146,16 +146,20 @@ Prevents unauthorized edits to protected/generated areas.
|
|
|
146
146
|
|-------|------|-------------|---------------|--------|
|
|
147
147
|
| Allowlist | built-in | Block **direct** edits to `packages/**`, `*.generated.*`; require approval for `.github/**` | `micro-contracts check --only allowlist` | `allowlist` |
|
|
148
148
|
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
149
|
+
On a pull request the check inspects what that pull request adds to its base branch,
|
|
150
|
+
which the runner names in `GITHUB_BASE_REF`. A CI checkout has nothing uncommitted, so
|
|
151
|
+
asking it what changed locally reads no file at all. In a working copy the check
|
|
152
|
+
inspects everything not yet committed — staged, unstaged and untracked alike.
|
|
153
|
+
`--changed-files` supplies the list instead. The check fails rather than reporting no
|
|
154
|
+
changes when it cannot ask git at all, and when the base branch is absent from the
|
|
155
|
+
checkout — clone with `fetch-depth: 0`.
|
|
152
156
|
|
|
153
157
|
Files are categorized into three groups:
|
|
154
158
|
|
|
155
159
|
| Category | Examples | Who can edit |
|
|
156
160
|
|----------|----------|--------------|
|
|
157
161
|
| `allowed` | `spec/**/*.yaml`, `server/src/**/services/**` | Anyone (AI or human) |
|
|
158
|
-
| `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) |
|
|
159
163
|
| `generated` | `packages/**`, `*.generated.*` | Only via `generate` command |
|
|
160
164
|
|
|
161
165
|
Patterns are evaluated in order and the last match wins, so a negation (`!pattern`)
|
|
@@ -165,6 +169,35 @@ Protected files include:
|
|
|
165
169
|
- CI/workflow definitions (`.github/**`) — guardrail bypass prevention
|
|
166
170
|
- Spectral lint rules (`spec/spectral.yaml`) — security rule tampering
|
|
167
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.
|
|
168
201
|
|
|
169
202
|
### Gate 2: OpenAPI Spec Validation
|
|
170
203
|
|
|
@@ -289,8 +322,12 @@ allowed:
|
|
|
289
322
|
- "!server/src/_shared/overlays/**"
|
|
290
323
|
|
|
291
324
|
# Configuration
|
|
325
|
+
# The example is three npm projects (this one, server/, frontend/) and CI installs all
|
|
326
|
+
# three. A dependency change moves a manifest and its lock together, so allowing one
|
|
327
|
+
# without the other describes a change nobody can make.
|
|
292
328
|
- micro-contracts.config.yaml
|
|
293
|
-
- package.json
|
|
329
|
+
- "**/package.json"
|
|
330
|
+
- "**/package-lock.json"
|
|
294
331
|
- tsconfig.json
|
|
295
332
|
|
|
296
333
|
# Documentation
|
|
@@ -462,10 +499,15 @@ npx --yes -p micro-contracts@${MICRO_CONTRACTS_VERSION} micro-contracts check
|
|
|
462
499
|
|
|
463
500
|
### Protecting `.github/**`
|
|
464
501
|
|
|
465
|
-
- Feature branches MUST NOT modify `.github/**`
|
|
466
|
-
- 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
|
|
467
505
|
- **Rationale**: CI definition is part of the guardrail
|
|
468
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
|
+
|
|
469
511
|
### Required Status Checks
|
|
470
512
|
|
|
471
513
|
`main` branch protection must require these **2 job names**:
|
|
@@ -486,6 +528,9 @@ npx --yes -p micro-contracts@${MICRO_CONTRACTS_VERSION} micro-contracts check
|
|
|
486
528
|
| `micro-contracts.guardrails.yaml` | security/platform | Guardrail config |
|
|
487
529
|
| `.github/**` | infra/maintainer | CI definitions |
|
|
488
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
|
+
|
|
489
534
|
---
|
|
490
535
|
|
|
491
536
|
## Developer Workflow
|
|
@@ -510,6 +555,8 @@ npx --yes -p micro-contracts@${MICRO_CONTRACTS_VERSION} micro-contracts check
|
|
|
510
555
|
|----------|------|--------|
|
|
511
556
|
| Edit `spec/**/*.yaml` → regenerate → commit | — | ✅ Allowed |
|
|
512
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 |
|
|
513
560
|
| Edit `packages/**/*.ts` directly | 1 | ❌ Blocked |
|
|
514
561
|
| Edit `*.generated.ts` directly | 1 | ❌ Blocked |
|
|
515
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/",
|