coderifts 1.9.0 → 3.0.0

package/README.md

@@ -64,6 +64,140 @@ Interactive configuration generator. Creates a `.coderifts.yml` file with indust
 
 Save your CodeRifts API key for cloud features. Get a free key at [app.coderifts.com/api/signup](https://app.coderifts.com/api/signup).
 
+### `coderifts publish-gate`
+
+Gate **npm publish** on the same contract-preflight family as the pre-push hook:
+`before` = last published / merge-base baseline, `after` = working tree. Exit **0**
+only when `execution_action` permits publish; **BLOCK**, resolver errors, empty
+before, and preflight unreachability all exit **1** (fail-closed). Empty `before`
+is **never** treated as a silent NEW_ARTIFACT pass.
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--spec <path>` | Contract artifact path | `git config coderifts.specPath` or `api/openapi.yaml` |
+| `--json` | Machine-readable result | `false` |
+
+**Recommended package.json wiring:**
+
+```json
+{
+  "scripts": {
+    "prepublishOnly": "coderifts publish-gate"
+  }
+}
+```
+
+**Before resolution order (fail-closed):**
+1. Git tag of `package.json` version (`vX.Y.Z`, then `X.Y.Z`)
+2. `git merge-base HEAD origin/main` (fallbacks: `origin/master`, `main`, `master`)
+3. Exit 1 with a clear error — never invent an empty baseline
+
+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
+resolved baseline (remote tip, or for new branches a merge-base with the
+default branch). Empty-before allow is not used. The hook prefers closed-set
+`execution_action` from the diff API (legacy `omega_decision` only when action
+is absent). Configure with `git config coderifts.apiKey` and optional
+`git config coderifts.specPath`.
+
+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

@@ -42,6 +42,46 @@ program
     await runDeployGate(options);
   });
 
+// ── publish-gate — npm prepublishOnly (same decision family as pre-push, fail-closed before) ──
+// Exit status is set only at this command boundary (library never process.exit).
+// program.parse() does not await async actions; process.exit here makes the gate's
+// fail-closed status authoritative for npm prepublishOnly / child_process callers.
+program
+  .command('publish-gate')
+  .description('Gate npm publish on contract-artifact preflight (before=git baseline, after=working tree)')
+  .option('--spec <path>', 'Contract artifact path (default: git config coderifts.specPath or api/openapi.yaml)')
+  .option('--json', 'Machine-readable JSON result')
+  .action(async (options) => {
+    const { runPublishGate } = require('../src/commands/publish-gate');
+    const result = await runPublishGate(options);
+    const code = result && typeof result.exitCode === 'number' ? result.exitCode : 1;
+    process.exitCode = code;
+    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]')
@@ -60,6 +100,75 @@ 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 });
+  });
+
 // ── hook command group ──
 const hookCmd = program
   .command('hook')
@@ -107,4 +216,13 @@ corpusCmd
     corpusVerify(options);
   });
 
-program.parse();
+// parseAsync: required so async command actions (publish-gate, diff, deploy-gate, …)
+// complete before the process ends. program.parse() discards the action promise and
+// can leave process.exitCode at the default 0 even after a fail-closed gate printed errors.
+program.parseAsync(process.argv).catch((err) => {
+  console.error(err);
+  process.exitCode = typeof process.exitCode === 'number' && process.exitCode !== 0
+    ? process.exitCode
+    : 1;
+  process.exit(process.exitCode);
+});