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.
@@ -2,7 +2,7 @@
2
2
 
3
3
  Contract-first OpenAPI toolchain for TypeScript Web/API systems. Generates contract packages, server routes, and frontend clients from OpenAPI specifications with enforceable guardrails.
4
4
 
5
- **Version:** 0.18.11
5
+ **Version:** 0.18.16
6
6
 
7
7
  ## Table of Contents
8
8
 
@@ -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/**` | Requires CODEOWNERS approval |
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" with CODEOWNERS approval
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.15",
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/",