coderifts 2.0.0 → 3.1.0

package/README.md

@@ -94,6 +94,37 @@ is **never** treated as a silent NEW_ARTIFACT pass.
 
 On success the command prints a **receipt reference** when the preflight path issues one.
 
+### `coderifts registry-gate [dir]`
+
+Local **registry admission gate** for a directory of OpenAPI/Swagger specs
+(audit **3.4/9**). Runs the pure registry-validation core offline — **no cloud
+calls** — so a registry CI step does not depend on CodeRifts uptime to admit
+specs.
+
+Discovers `*.yaml` / `*.yml` / `*.json` under `[dir]` (default: `.`), skips
+`node_modules` and dotdirs, skips non-spec files (no `openapi`/`swagger` field),
+and fails closed on unreadable files (`GATE_ERROR`) or zero specs
+(`REGISTRY_EMPTY`).
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `[dir]` | Registry root to scan | `.` |
+| `--glob <pattern>` | Filter paths with `@coderifts/agent-guard` `matchGlob` (relative to dir) | all candidates |
+| `--errors-only` | Fail only on **ERROR** severity (warnings printed, exit 0) | off |
+| `--warn-only` | Advisory: print findings, always exit **0** | off |
+
+**Severity (important):** core `endpoint_collision` is a **WARNING** and leaves
+`valid: true`. This gate fails on **ERROR + WARNING** by default — it does **not**
+branch on `valid` alone. Info findings are printed and do not fail.
+
+**GitHub Actions (minimal):**
+
+```yaml
+- uses: actions/checkout@v4
+- name: Registry admission
+  run: npx coderifts registry-gate specs/
+```
+
 ### Git hook (`coderifts hook install`)
 
 Installs a **pre-push** hook that diffs the configured OpenAPI path against a
@@ -106,6 +137,67 @@ is absent). Configure with `git config coderifts.apiKey` and optional
 After upgrading the `coderifts` CLI, re-run `coderifts hook install` so the
 installed hook matches the package (already-installed hooks are not
 auto-updated).
+
+### Agent host files (`coderifts agent-setup`)
+
+Writes the six CodeRifts agent-host rule files into the current repo (or `--out <dir>`):
+
+| File | Host |
+|------|------|
+| `AGENTS.md` | multi-agent / open convention |
+| `CLAUDE.md` | Claude Code |
+| `.cursor/rules/coderifts.mdc` | Cursor |
+| `.github/copilot-instructions.md` | GitHub Copilot |
+| `coderifts-langgraph-policy.js` | LangGraph |
+| `openai-agent-instructions.md` | OpenAI Agents SDK |
+
+```bash
+coderifts agent-setup              # write (skip existing files)
+coderifts agent-setup --force      # overwrite
+coderifts agent-setup --check      # drift vs embedded content
+coderifts agent-setup --out ./docs # custom root
+```
+
+Content is vendored from the app generator (`scripts/generate-agent-host-files.js`);
+re-sync with `node scripts/sync-cli-agent-host-embed.js` when the rule source changes.
+
+Policy template for agent/MCP APIs: `coderifts init ai-agent` (aliases: `agent`, `mcp`).
+
+### Required check wizard (`coderifts setup-required-check`)
+
+Guided setup so **CodeRifts / contract-gate** is a **required status check** on
+your default branch (audit **3.4/1** + **3.5**; registry admission is **3.4/9**
+via `coderifts registry-gate`). The wizard:
+
+1. Resolves `owner/repo` from `git remote origin` (or `--repo`)
+2. Observes classic branch protection via **`gh api`** (your login — never a
+   CodeRifts API key)
+3. Detects **repository rulesets** that already require the check (honest
+   report; classic GET `/protection` does not include rulesets)
+4. **Default dry-run:** prints the exact `gh api --method PUT … --input -`
+   read-modify-write command that adds the check **without clobbering**
+   existing protection settings
+5. **`--apply`:** runs that PUT with your credentials, then **re-reads** and
+   only reports success if the check is required
+
+**Why the App never writes protection:** mutating branch protection needs
+`administration:write` — a trust jump we refuse. Your credentials do the write.
+
+**Merge queues:** when this check is required, the GitHub App also handles the
+`merge_group` webhook (`checks_requested`) and posts **CodeRifts / contract-gate**
+on the merge group head (same gate as PR heads), so the queue does not stall.
+
+```bash
+# Observe + print command (safe default)
+coderifts setup-required-check
+
+# Apply + re-verify
+coderifts setup-required-check --apply
+
+# One-liner for CI docs
+coderifts setup-required-check --branch main
+```
+
 ## CI/CD Integration
 
 ### GitHub Actions

package/bin/coderifts.js

@@ -59,6 +59,29 @@ program
     process.exit(code);
   });
 
+// ── registry-gate — local OpenAPI registry admission (pure core, no cloud) ──
+// Fail-closed discovery + severity selection (WARNING findings fail by default;
+// never gate on core `valid` alone — endpoint_collision is warning).
+// process.exit only at this boundary (library returns exitCode).
+program
+  .command('registry-gate [dir]')
+  .description('Admit a directory of OpenAPI specs via local registry validation (CI gate, no cloud)')
+  .option('--glob <pattern>', 'Filter discovered paths with agent-guard matchGlob (relative to dir)')
+  .option('--errors-only', 'Fail only on ERROR severity (warnings are printed, exit 0)')
+  .option('--warn-only', 'Advisory: print all findings, always exit 0')
+  .action((dir, options) => {
+    const { runRegistryGate } = require('../src/commands/registry-gate');
+    const result = runRegistryGate({
+      dir: dir || '.',
+      glob: options.glob,
+      errorsOnly: !!options.errorsOnly,
+      warnOnly: !!options.warnOnly,
+    });
+    const code = result && typeof result.exitCode === 'number' ? result.exitCode : 1;
+    process.exitCode = code;
+    process.exit(code);
+  });
+
 // ── init command ──
 program
   .command('init [template]')
@@ -77,6 +100,107 @@ program
     await login();
   });
 
+// ── setup-required-check — guided wizard for branch protection (audit 3.4/1 + 3.5) ──
+// Observes classic protection + rulesets via `gh` (user credentials). Default dry-run;
+// --apply does read-modify-write + re-verify. App never writes protection.
+program
+  .command('setup-required-check')
+  .description('Guide setup of required status check "CodeRifts / contract-gate" (uses gh, your credentials)')
+  .option('--branch <name>', 'Branch to protect (default: repo default branch)')
+  .option('--repo <owner/repo>', 'Override owner/repo (default: git remote origin)')
+  .option('--apply', 'Apply the protection change (default: print the exact gh command only)')
+  .option('--json', 'Machine-readable JSON result')
+  .action(async (options) => {
+    const { runSetupRequiredCheck } = require('../src/commands/setup-required-check');
+    const result = await runSetupRequiredCheck(options);
+    if (result && typeof result.exitCode === 'number') {
+      process.exitCode = result.exitCode;
+    }
+  });
+
+// ── status — read-only cross-layer enforcement report (ID851) ──
+// GET /api/v1/enforcement-status — no GitHub writes. Distinct from `coderifts hook status`.
+program
+  .command('status [repo]')
+  .description('Show cross-layer enforcement status (Runtime / Merge / Deploy) for a repo — read-only')
+  .option('--repo <owner/repo>', 'Repository (owner/repo); also accepted as a positional argument')
+  .option('--json', 'Machine-readable JSON (raw API body)')
+  .action(async (repoPositional, options) => {
+    const { runStatus } = require('../src/commands/status');
+    const result = await runStatus({
+      ...options,
+      repo: options.repo || repoPositional || null,
+    });
+    if (result && typeof result.exitCode === 'number') {
+      process.exitCode = result.exitCode;
+    }
+  });
+
+// ── enforce — orchestrate existing setup commands (ID851 step 2) ──
+// Dry-run by default; --apply threads into setup-required-check / hook.install.
+// No new GitHub writes with the CodeRifts API key (user's gh for merge; local fs for hook).
+program
+  .command('enforce [repo]')
+  .description('Close enforcement gaps by chaining setup-required-check / hook / deploy guidance (dry-run default; use --apply to mutate)')
+  .option('--repo <owner/repo>', 'Repository (owner/repo); also accepted as a positional argument')
+  .option('--apply', 'Actually run underlying setup commands (default: dry-run only)')
+  .option('--json', 'Machine-readable JSON result')
+  .action(async (repoPositional, options) => {
+    const { runEnforce } = require('../src/commands/enforce');
+    const result = await runEnforce({
+      ...options,
+      repo: options.repo || repoPositional || null,
+      apply: !!options.apply,
+    });
+    if (result && typeof result.exitCode === 'number') {
+      process.exitCode = result.exitCode;
+    }
+  });
+
+// ── agent-setup — emit six agent-host rule files (vendored from app generator) ──
+program
+  .command('agent-setup')
+  .description('Write AGENTS.md / CLAUDE.md / Cursor / Copilot / LangGraph / OpenAI agent rule files')
+  .option('--out <dir>', 'Target directory (default: current working directory)')
+  .option('--check', 'Exit 0 if on-disk files match embedded content; exit 1 on drift')
+  .option('--force', 'Overwrite existing files (default: skip collisions)')
+  .action((options) => {
+    const { runAgentSetup } = require('../src/commands/agent-setup');
+    runAgentSetup(options, { exit: true });
+  });
+
+// ── copilot-setup — emit GitHub Copilot MCP configs (VS Code + cloud agent + custom agent) ──
+// Single-source from CANONICAL_TOOL_NAMES; root keys: servers (VS Code) vs mcpServers (cloud).
+program
+  .command('copilot-setup')
+  .description('Write GitHub Copilot MCP configs (.vscode/mcp.json + cloud-agent paste JSON + docs)')
+  .option('--out <dir>', 'Target directory (default: current working directory)')
+  .option('--check', 'Exit 0 if on-disk files match embedded content; exit 1 on drift')
+  .option('--force', 'Overwrite existing files (default: skip collisions)')
+  .action((options) => {
+    const { runCopilotSetup } = require('../src/commands/copilot-setup');
+    runCopilotSetup(options, { exit: true });
+  });
+
+// ── lock — agent contract lockfile v1 (observed usage; ID847) ──
+// GET /api/v1/lock?repo= → write coderifts.lock. Observed-only; empty agents when none recorded.
+program
+  .command('lock [repo]')
+  .description('Fetch the observed agent-contract lockfile (coderifts.lock v1) for a repo')
+  .option('--repo <owner/repo>', 'Repository (owner/repo); also accepted as a positional argument')
+  .option('--out <path>', 'Output path (default: coderifts.lock in cwd)')
+  .option('--json', 'Print the lock document JSON to stdout (still writes --out)')
+  .action(async (repoPositional, options) => {
+    const { runLock } = require('../src/commands/lock');
+    const result = await runLock({
+      ...options,
+      repo: options.repo || repoPositional || null,
+    });
+    if (result && typeof result.exitCode === 'number') {
+      process.exitCode = result.exitCode;
+    }
+  });
+
 // ── hook command group ──
 const hookCmd = program
   .command('hook')