pattern-mcp 0.9.1 → 0.10.0

package/README.md

@@ -31,7 +31,7 @@ design reference.
 ## Install
 
 ```bash
-npm install pattern-mcp
+npx pattern-mcp
 ```
 
 See [Quick Start](#quick-start) below to add your Anthropic API key and connect
@@ -224,11 +224,11 @@ threshold.
 ### 1. Install
 
 ```bash
-npm install pattern-mcp
+npx pattern-mcp
 ```
 
-This installs the `pattern-mcp` command via `npx` (or your project's
-local `node_modules/.bin`), used in the client configs below.
+`npx` runs the `pattern-mcp` command on demand without a separate install
+step, used in the client configs below.
 
 <details>
 <summary>Build from source instead</summary>
@@ -1576,6 +1576,51 @@ the source line, most recent record wins at read time" convention as
 layered onto `ledger.jsonl`'s own entries at read time -- the ledger line
 itself is never rewritten.
 
+## Enforcement boundary: hook + CI gate
+
+**The gap this closes:** SKILL.md instructs the calling agent to call
+`recommend_component` before scaffolding a new, non-trivial UI component,
+but nothing before this feature *enforced* that -- an agent could simply
+skip the call, and nothing server-side would know. This is opt-in and
+Claude-Code-specific for the hook half; a consuming repo that never wires
+either piece up gets Pattern exactly as it worked before, and any other
+MCP host (Cursor, Codex, etc.) is entirely unaffected either way.
+
+Two pieces, both templates under `templates/` -- pattern-mcp never
+installs either into your repo on its own:
+
+- **`templates/hooks/check-gate-hook.mjs`** + **`templates/claude-settings/settings.json`**
+  -- a Claude Code `PreToolUse` hook that runs on `Write`/`Edit` calls. For
+  a genuinely new `.tsx`/`.jsx` file that exports a non-trivial component,
+  it looks up a ledger entry (via `~/.pattern/ledger.jsonl`, same as
+  everywhere else in Pattern) whose `file_path` matches the file being
+  written. A match writes a receipt and allows the write; no match blocks
+  it with a reason fed back to the model as retryable guidance, not a hard
+  failure. **This is the one new exception where Pattern writes into your
+  repo** (`.pattern/receipts/<feature_id>.json`) -- everything else
+  described in this README is read-only.
+- **`templates/github-workflows/pattern-gate.yml`** -- a required PR
+  check that reads the same receipt files back out of the diff. It never
+  touches `~/.pattern/` (not reachable from a CI runner) and needs no
+  `GITHUB_TOKEN` -- it trusts the committed receipt as the artifact of
+  record, the same way it would trust a committed test fixture.
+
+The join between the two depends on `file_path` being passed to
+`recommend_component`/`record_component_decision` -- if it's omitted, the
+gate has nothing to match against and fails closed (blocks) rather than
+guessing. Pass `file_path` whenever you know it.
+
+An escape hatch exists for both a whole-hook kill switch
+(`PATTERN_NO_ENFORCEMENT_HOOK`, local only -- does not affect the CI
+check) and a per-file override (a `// pattern-mcp:override reason="..."`
+comment) -- the override still writes a receipt recording
+`manual_override: true` and the reason, so it stays visible rather than
+silent. See `src/component-gate.ts`, `src/gate-receipt.ts`, and
+`src/check-gate.ts` (the new `pattern-check-gate` CLI, this project's
+first entry point separate from the stdio MCP server) for the
+implementation, and BACKLOG.md's "Enforcement boundary: hook + CI gate"
+entry for the fuller design writeup.
+
 ## Per-project decision memory
 
 Pattern stores confirmed decisions locally in:

package/dist/check-gate.js

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+// pattern-check-gate -- the enforcement-boundary CLI (see
+// BACKLOG.md's "Enforcement boundary: hook + CI gate" entry).
+//
+// Two modes, one shared classifier (component-gate.ts) so the local hook
+// and the CI check can never silently drift on what counts as "gated":
+//
+//   write  -- run locally (by the PreToolUse hook template) where
+//             ~/.pattern/ledger.jsonl is reachable. Looks up a ledger
+//             entry whose file_path matches the file being written; on a
+//             match (or a manual override), writes a receipt into the
+//             CONSUMING repo at .pattern/receipts/<feature_id>.json and
+//             exits 0. No match, no override -> exits 1 and blocks.
+//
+//   verify -- run in CI, where ~/.pattern/ is never reachable. Trusts the
+//             committed receipt as the artifact of record instead of
+//             re-deriving anything from the ledger -- fails if a gated
+//             file in the diff has no matching receipt.
+//
+// No CLI-parsing or git-wrapper dependency, matching this project's
+// existing minimal-dependency posture (index.ts shells out to fixed git
+// subcommands rather than a library) -- argv is parsed by hand below.
+//
+// This is the project's first standalone CLI entry point separate from
+// the stdio MCP server (see package.json's new "pattern-check-gate" bin
+// entry) -- entirely opt-in. A consuming repo that never installs the
+// hook template or the workflow template never invokes this file, and
+// Pattern's core MCP tools are unaffected either way.
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, relative, resolve as resolvePath } from "node:path";
+import { isGatedComponentFile, parseManualOverride } from "./component-gate.js";
+import { deriveOverrideFeatureId, readAllGateReceipts, writeGateReceipt } from "./gate-receipt.js";
+function normalize(p) {
+    return p.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+// Converts a possibly-absolute file argument into a path relative to
+// root, without ever reading/writing outside root.
+function toRepoRelative(root, fileArg) {
+    const abs = isAbsolute(fileArg) ? fileArg : resolvePath(root, fileArg);
+    const rel = relative(root, abs);
+    if (rel.startsWith("..") || isAbsolute(rel))
+        return null;
+    return normalize(rel);
+}
+function parseArgs(argv) {
+    const mode = argv[0];
+    const flags = {};
+    const files = [];
+    for (let i = 1; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--files") {
+            // --files (verify mode) consumes every following non-flag token
+            i++;
+            while (i < argv.length && !argv[i].startsWith("--")) {
+                files.push(argv[i]);
+                i++;
+            }
+            i--;
+        }
+        else if (arg.startsWith("--")) {
+            const key = arg.slice(2);
+            const next = argv[i + 1];
+            if (next !== undefined && !next.startsWith("--")) {
+                flags[key] = next;
+                i++;
+            }
+            else {
+                flags[key] = true;
+            }
+        }
+    }
+    return { mode, flags, files };
+}
+function readStdin() {
+    return new Promise((resolveP, reject) => {
+        let data = "";
+        process.stdin.setEncoding("utf8");
+        process.stdin.on("data", (chunk) => (data += chunk));
+        process.stdin.on("end", () => resolveP(data));
+        process.stdin.on("error", reject);
+    });
+}
+function emit(result, ok) {
+    process.stdout.write(JSON.stringify(result) + "\n");
+    process.exit(ok ? 0 : 1);
+}
+async function runWrite(root, flags) {
+    const fileArg = flags.file;
+    const projectId = flags["project-id"];
+    if (typeof fileArg !== "string" || typeof projectId !== "string") {
+        emit({ ok: false, reason: "write mode requires --file <path> and --project-id <id>" }, false);
+    }
+    const relPath = toRepoRelative(root, fileArg);
+    if (relPath === null) {
+        emit({ ok: false, reason: `--file resolves outside project root: ${fileArg}` }, false);
+    }
+    const content = await readStdin();
+    const isNew = flags["is-new"] === true;
+    if (!isGatedComponentFile(relPath, content, isNew)) {
+        emit({ ok: true, gated: false }, true);
+    }
+    const override = parseManualOverride(content);
+    const checkedAt = new Date().toISOString();
+    // Dynamic import, after nothing has set PATTERN_NO_AUTOSTART yet in
+    // this process -- set it now, before index.js's module body runs, same
+    // convention scripts/*.mjs already use to import from this file
+    // without starting the stdio MCP server as a side effect.
+    process.env.PATTERN_NO_AUTOSTART = "1";
+    const { readLedgerEntries, computeSnapshotRef } = await import("./index.js");
+    const snapshotRef = computeSnapshotRef(root);
+    if (override.overridden) {
+        const receipt = {
+            schema_version: 1,
+            feature_id: deriveOverrideFeatureId(projectId, relPath),
+            file_path: relPath,
+            ledger_entry_id: null,
+            verdict: null,
+            chosen_candidate: null,
+            snapshot_ref: snapshotRef,
+            checked_at: checkedAt,
+            manual_override: true,
+            override_reason: override.reason,
+        };
+        writeGateReceipt(root, receipt);
+        emit({ ok: true, gated: true, manual_override: true, feature_id: receipt.feature_id }, true);
+    }
+    const entries = readLedgerEntries(projectId);
+    const match = entries.find((e) => e.file_path && normalize(e.file_path) === relPath);
+    if (!match) {
+        emit({
+            ok: false,
+            gated: true,
+            reason: `No recommend_component/record_component_decision entry found with file_path="${relPath}" ` +
+                `for project_id="${projectId}". Call recommend_component with file_path set to this exact ` +
+                `path before creating it, or add \`// pattern-mcp:override reason="..."\` to the file.`,
+        }, false);
+    }
+    const receipt = {
+        schema_version: 1,
+        feature_id: match.feature_id,
+        file_path: relPath,
+        ledger_entry_id: match.id,
+        verdict: match.verdict,
+        chosen_candidate: match.chosen_candidate,
+        snapshot_ref: snapshotRef,
+        checked_at: checkedAt,
+        manual_override: false,
+        override_reason: null,
+    };
+    writeGateReceipt(root, receipt);
+    emit({ ok: true, gated: true, feature_id: receipt.feature_id }, true);
+}
+async function runVerify(root, files) {
+    const receipts = readAllGateReceipts(root);
+    const ungated = [];
+    let checked = 0;
+    for (const fileArg of files) {
+        const relPath = toRepoRelative(root, fileArg);
+        if (relPath === null)
+            continue;
+        const abs = resolvePath(root, relPath);
+        if (!existsSync(abs))
+            continue;
+        const content = readFileSync(abs, "utf8");
+        // verify mode's caller (the workflow) is expected to pass only files
+        // already filtered to "added in this diff" -- see
+        // templates/github-workflows/pattern-gate.yml.
+        if (!isGatedComponentFile(relPath, content, true))
+            continue;
+        checked++;
+        const hasReceipt = receipts.some((r) => normalize(r.file_path) === relPath);
+        if (!hasReceipt)
+            ungated.push(relPath);
+    }
+    if (ungated.length > 0) {
+        emit({
+            ok: false,
+            ungated_files: ungated,
+            reason: "One or more new UI components have no matching .pattern/receipts/*.json entry.",
+        }, false);
+    }
+    emit({ ok: true, checked }, true);
+}
+async function main() {
+    const { mode, flags, files } = parseArgs(process.argv.slice(2));
+    const root = typeof flags["project-root"] === "string" ? flags["project-root"] : process.cwd();
+    if (mode === "write") {
+        await runWrite(root, flags);
+    }
+    else if (mode === "verify") {
+        await runVerify(root, files);
+    }
+    else {
+        process.stderr.write("Usage: pattern-check-gate write --file <path> [--is-new] --project-id <id> [--project-root <root>] (content on stdin)\n");
+        process.stderr.write("       pattern-check-gate verify --files <path...> [--project-root <root>]\n");
+        process.exit(2);
+    }
+}
+main().catch((err) => {
+    process.stderr.write(`pattern-check-gate crashed: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(2);
+});

package/dist/component-gate.js

@@ -0,0 +1,56 @@
+// Shared classifier for the enforcement-boundary feature (hook + CI gate).
+// Used identically by check-gate.ts's write mode (the local PreToolUse
+// hook) and verify mode (the CI check) -- lives in its own module,
+// deliberately with zero dependency on index.ts, so the two call sites can
+// never silently drift on what counts as "a non-trivial new UI component."
+// This is host-agnostic and opt-in: nothing here runs unless a consuming
+// repo explicitly wires up the hook template or the workflow template --
+// Pattern's core MCP tools (recommend_component, record_component_decision,
+// etc.) are unaffected either way, so Codex/Cursor/any other MCP host keeps
+// working exactly as before.
+const GATED_EXTENSIONS = new Set([".tsx", ".jsx"]);
+// Deliberately NOT a "non-trivial" threshold -- an earlier version used
+// 15 here specifically to auto-exempt "trivial" files, and a real,
+// 14-non-blank-line component (a labeled progress-bar widget) slipped
+// through ungated in end-to-end testing on 2026-09-11 as a direct result.
+// Any fixed line-count threshold used as an exemption has this problem by
+// construction: there's always a real component sitting just under
+// whatever number you pick, and tuning the number only moves the
+// boundary to a different real component, it doesn't close the class of
+// bug. This floor exists ONLY to exclude degenerate non-components (a
+// bare re-export line, an empty file) -- genuine trivial-but-real
+// components are meant to go through the manual override instead
+// (parseManualOverride below), which requires a reason and still leaves
+// a visible, logged receipt, rather than being silently auto-exempted.
+const MIN_NON_BLANK_LINES = 3;
+const COMPONENT_EXPORT_PATTERN = /^export\s+(default\s+)?(function|class)\s+[A-Z]|^export\s+(default\s+)?const\s+[A-Z]\w*\s*[:=]/m;
+// isNewFile is passed in, not derived here -- the local hook knows it via
+// existsSync before the write happens; CI verify mode knows it via the
+// workflow's own `git diff --diff-filter=A` filtering. Keeping that
+// detection out of this module keeps it a pure, easily-tested function.
+export function isGatedComponentFile(filePath, fileContent, isNewFile) {
+    if (!isNewFile)
+        return false;
+    const dot = filePath.lastIndexOf(".");
+    if (dot === -1)
+        return false;
+    if (!GATED_EXTENSIONS.has(filePath.slice(dot)))
+        return false;
+    if (!COMPONENT_EXPORT_PATTERN.test(fileContent))
+        return false;
+    const nonBlankLines = fileContent.split("\n").filter((l) => l.trim().length > 0).length;
+    return nonBlankLines >= MIN_NON_BLANK_LINES;
+}
+// Per-file escape hatch (Q3 from the enforcement-boundary design): a
+// magic comment with a required reason. The hook and CI both honor this
+// identically because both call this same function -- but it never
+// silently bypasses: check-gate.ts still writes a receipt recording
+// manual_override: true and the reason, so the exception stays visible in
+// the same committed artifact as a normal pass.
+const OVERRIDE_PATTERN = /\/\/\s*pattern-mcp:override\s+reason="([^"]+)"/;
+export function parseManualOverride(fileContent) {
+    const match = fileContent.match(OVERRIDE_PATTERN);
+    if (!match || !match[1].trim())
+        return { overridden: false, reason: null };
+    return { overridden: true, reason: match[1].trim() };
+}

package/dist/gate-receipt.js

@@ -0,0 +1,94 @@
+// Receipt schema + read/write for the enforcement-boundary feature.
+// Deliberately committed into the CONSUMING repo (e.g. `.pattern/receipts/`
+// at that repo's root) rather than `~/.pattern/` -- this is the one
+// artifact a CI runner can see without any access to the local, homedir-
+// scoped ledger (see SECURITY.md's "not sent anywhere by Pattern itself").
+// One JSON file per feature, git-diffable, not an append-only jsonl --
+// receipts are meant to be read directly out of a small PR diff, not
+// grown forever like the homedir ledger overlays.
+//
+// No dependency on index.ts by design: importing index.ts triggers its
+// module-level MCP-server autostart unless PATTERN_NO_AUTOSTART is set
+// before the import resolves, which a static import from this module
+// could not guarantee. check-gate.ts handles that ordering itself via a
+// dynamic import for the one piece of real reuse it needs
+// (readLedgerEntries/computeSnapshotRef) -- this module stays
+// self-contained.
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { createHash } from "node:crypto";
+const RECEIPTS_DIR = ".pattern/receipts";
+const ALLOWED_GATE_RECEIPT_KEYS = new Set([
+    "schema_version",
+    "feature_id",
+    "file_path",
+    "ledger_entry_id",
+    "verdict",
+    "chosen_candidate",
+    "snapshot_ref",
+    "checked_at",
+    "manual_override",
+    "override_reason",
+]);
+// Same throw-on-unknown-key discipline as index.ts's
+// assertDistilledCandidateShape -- a receipt reaching this function with
+// an extra key is a bug, not something to silently strip, since this
+// shape is the one thing CI trusts without re-deriving it.
+export function assertGateReceiptShape(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error("GateReceipt must be a plain object");
+    }
+    const record = value;
+    const extra = Object.keys(record).filter((k) => !ALLOWED_GATE_RECEIPT_KEYS.has(k));
+    if (extra.length > 0) {
+        throw new Error(`GateReceipt has disallowed key(s): ${extra.join(", ")}`);
+    }
+    if (record.schema_version !== 1) {
+        throw new Error("GateReceipt.schema_version must be 1");
+    }
+}
+// feature_id can be caller-supplied (recommend_component's optional
+// feature_id arg) -- never trust it as a bare filename. Sanitizing to a
+// safe character set makes path traversal structurally impossible here
+// without needing index.ts's resolveWithinRoot (see file header).
+function sanitizeFeatureIdForFilename(featureId) {
+    return featureId.replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+// Only used on the manual-override path, which has no ledger entry to
+// derive a feature_id from. Deliberately a separate, local derivation
+// rather than index.ts's deriveFeatureId (not exported, and this only
+// ever needs to be stable for one project_id+file_path pair -- it's never
+// joined against real ledger data).
+export function deriveOverrideFeatureId(projectId, filePath) {
+    return createHash("sha256").update(`override::${projectId}::${filePath}`).digest("hex").slice(0, 8);
+}
+export function writeGateReceipt(root, receipt) {
+    assertGateReceiptShape(receipt);
+    const abs = join(root, RECEIPTS_DIR, `${sanitizeFeatureIdForFilename(receipt.feature_id)}.json`);
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, JSON.stringify(receipt, null, 2) + "\n", "utf8");
+}
+// verify mode's only read path: it doesn't know a file's feature_id ahead
+// of time (that lives in the local ledger, invisible to CI), so it scans
+// every committed receipt and matches on file_path instead. A malformed
+// receipt is treated as absent, not fatal -- the caller reports the gated
+// file as unreceipted, same as if no file existed at all.
+export function readAllGateReceipts(root) {
+    const dirAbs = join(root, RECEIPTS_DIR);
+    if (!existsSync(dirAbs))
+        return [];
+    const receipts = [];
+    for (const name of readdirSync(dirAbs)) {
+        if (!name.endsWith(".json"))
+            continue;
+        try {
+            const parsed = JSON.parse(readFileSync(join(dirAbs, name), "utf8"));
+            assertGateReceiptShape(parsed);
+            receipts.push(parsed);
+        }
+        catch {
+            // skip malformed/unreadable receipt
+        }
+    }
+    return receipts;
+}

package/dist/index.js

@@ -189,6 +189,12 @@ const LEDGER_TTL_DAYS = Number(process.env.PATTERN_LEDGER_TTL_DAYS ?? 30);
 // failure-prone surface than "does this one file exist right now" or
 // "what commit is HEAD."
 //
+// resolveWithinRoot/computeSnapshotRef/readLedgerEntries are exported so
+// check-gate.ts (the enforcement-boundary CLI, see that file) can reuse
+// this exact scoping rather than growing a second, parallel fs/git-access
+// surface -- it imports these dynamically, after setting
+// PATTERN_NO_AUTOSTART, the same convention scripts/*.mjs already use.
+//
 // Defaults to process.cwd() -- for a locally-run stdio MCP server, that's
 // normally the consuming repo's root, since MCP hosts typically launch
 // the server with the project directory as its working directory. When
@@ -202,7 +208,7 @@ const PROJECT_ROOT = process.env.PATTERN_PROJECT_ROOT ?? process.cwd();
 // to "unknown" rather than silently stat-ing something outside the
 // project. Returns null (never throws) on anything that doesn't resolve
 // cleanly inside root.
-function resolveWithinRoot(root, relPath) {
+export function resolveWithinRoot(root, relPath) {
     if (!relPath || isAbsolute(relPath))
         return null;
     const resolved = resolve(root, relPath);
@@ -217,7 +223,7 @@ function resolveWithinRoot(root, relPath) {
 // rather than failing the judgment call that triggered this write (see
 // buildLedgerEntry). Read-only: `git rev-parse HEAD` never touches repo
 // state.
-function computeSnapshotRef(root) {
+export function computeSnapshotRef(root) {
     try {
         const sha = execFileSync("git", ["rev-parse", "HEAD"], {
             cwd: root,
@@ -2206,7 +2212,7 @@ function backfillLedgerSnapshotRefs(input) {
 // but line-oriented (JSONL) rather than whole-file JSON -- a single
 // corrupted line (e.g. a hand-edited file, or a write that got cut off)
 // is skipped rather than failing the whole read.
-function readLedgerEntries(projectId) {
+export function readLedgerEntries(projectId) {
     let raw;
     try {
         raw = readFileSync(LEDGER_PATH, "utf8");

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "pattern-mcp",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "MCP server that turns your design guidance into a checkable process -- evaluates UI components from external libraries (shadcn/ui, 21st.dev, ReUI) or your own registered design system against a requirements checklist, then tells the agent whether to reuse an existing component or build one from a concrete design reference.",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
-    "pattern-mcp": "dist/index.js"
+    "pattern-mcp": "dist/index.js",
+    "pattern-check-gate": "dist/check-gate.js"
   },
   "author": "Don Richard",
   "license": "MIT",
@@ -28,7 +29,8 @@
   ],
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "templates"
   ],
   "scripts": {
     "build": "tsc",

package/templates/claude-settings/settings.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "env PATTERN_PROJECT_ID=your-project-id node ./node_modules/pattern-mcp/templates/hooks/check-gate-hook.mjs",
+            "timeout": 60
+          }
+        ]
+      }
+    ]
+  }
+}

package/templates/github-workflows/pattern-gate.yml

@@ -0,0 +1,42 @@
+name: Pattern gate
+
+# Required-check template for the enforcement boundary (see BACKLOG.md's
+# "Enforcement boundary: hook + CI gate" entry). Copy this into your own
+# repo's .github/workflows/ and mark the "pattern-gate" job required in
+# branch protection. Opt-in -- pattern-mcp never installs this for you.
+#
+# Deliberately does NOT need a GITHUB_TOKEN or any secret: it only reads
+# the receipt files already committed in this PR's diff
+# (.pattern/receipts/*.json), which were written locally by the
+# PreToolUse hook (see ../hooks/check-gate-hook.mjs) when the gate
+# passed. It never touches ~/.pattern/ledger.jsonl, which isn't reachable
+# from a CI runner at all -- see gate-receipt.ts for why the receipt file
+# is the artifact of record here, not a posted PR comment.
+
+on:
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  pattern-gate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "20"
+      - name: Compute added files
+        id: diff
+        run: |
+          ADDED=$(git diff --name-only --diff-filter=A "origin/${{ github.base_ref }}...HEAD")
+          echo "files<<EOF" >> "$GITHUB_OUTPUT"
+          echo "$ADDED" >> "$GITHUB_OUTPUT"
+          echo "EOF" >> "$GITHUB_OUTPUT"
+      - name: Run pattern-check-gate verify
+        if: steps.diff.outputs.files != ''
+        run: npx --yes pattern-check-gate verify --files ${{ steps.diff.outputs.files }} --project-root "$PWD"

package/templates/hooks/check-gate-hook.mjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+// Claude-Code-specific PreToolUse adapter for pattern-check-gate. Copy this
+// file into your repo (or reference it from node_modules/pattern-mcp) and
+// wire it up via .claude/settings.json -- see
+// ../claude-settings/settings.json for the exact hook config. Not
+// installed automatically by pattern-mcp; this is opt-in (see
+// BACKLOG.md's "Enforcement boundary: hook + CI gate" entry for why).
+//
+// Reads the PreToolUse stdin JSON, shells out to `pattern-check-gate
+// write`, and translates the result into the hook's blocking contract:
+// a JSON object on stdout with permissionDecision "deny" blocks the tool
+// call and feeds the reason back to Claude as retryable guidance (not a
+// hard turn failure); exiting 0 with no output allows it.
+//
+// Requires a PATTERN_PROJECT_ID env var (or --project-id below) -- set it
+// in the hook's own "command" (e.g. via `env PATTERN_PROJECT_ID=my-app
+// node ...`) or export it in your shell profile for local dev.
+
+import { existsSync, readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+
+async function main() {
+  if (process.env.PATTERN_NO_ENFORCEMENT_HOOK) {
+    process.exit(0);
+  }
+
+  const input = JSON.parse(readFileSync(0, "utf8"));
+  const toolName = input.tool_name;
+  if (toolName !== "Write" && toolName !== "Edit") {
+    process.exit(0);
+  }
+
+  const filePath = input.tool_input?.file_path;
+  if (!filePath) process.exit(0);
+
+  // isNewFile is determined here, at hook time, before the write happens
+  // -- this is the one piece of Claude-Code-specific state check-gate.ts
+  // itself doesn't have access to. Edit calls always target an existing
+  // file, so isNewFile is always false for them, which is why they're
+  // effectively never gated by this hook (see component-gate.ts's
+  // comment on isNewFile) -- the initial Write that creates the file is
+  // the highest-signal moment.
+  const isNewFile = !existsSync(filePath);
+  const content = toolName === "Write" ? input.tool_input?.content ?? "" : "";
+
+  const projectId = process.env.PATTERN_PROJECT_ID;
+  if (!projectId) {
+    // Fail open with a clear stderr note rather than blocking every write
+    // in a repo that hasn't configured this yet -- misconfiguration
+    // shouldn't look identical to "no ledger entry found."
+    process.stderr.write("check-gate-hook: PATTERN_PROJECT_ID not set, skipping gate\n");
+    process.exit(0);
+  }
+
+  const args = ["write", "--file", filePath, "--project-id", projectId, "--project-root", input.cwd ?? process.cwd()];
+  if (isNewFile) args.push("--is-new");
+
+  const result = spawnSync("npx", ["pattern-check-gate", ...args], {
+    input: content,
+    encoding: "utf8",
+    timeout: 30000,
+  });
+
+  let parsed;
+  try {
+    parsed = JSON.parse((result.stdout || "").trim());
+  } catch {
+    // If pattern-check-gate itself crashed or produced no parseable
+    // output, fail open (allow) rather than blocking on a plumbing bug --
+    // stderr still carries the detail for debugging.
+    if (result.stderr) process.stderr.write(result.stderr);
+    process.exit(0);
+  }
+
+  if (parsed.ok === false) {
+    process.stdout.write(
+      JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: "PreToolUse",
+          permissionDecision: "deny",
+          permissionDecisionReason: parsed.reason ?? "pattern-check-gate blocked this file.",
+        },
+      }),
+    );
+  }
+  process.exit(0);
+}
+
+main();