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.
@@ -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
 
@@ -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
- The changed files it inspects are everything not yet committed — staged, unstaged
150
- and untracked alike — or the list given by `--changed-files` in CI. Without a
151
- usable git repository the check fails rather than reporting no changes.
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/**` | Requires CODEOWNERS approval |
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" 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
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.14",
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/",