pr-checkmate 3.3.0 → 4.0.1

package/LICENSE

@@ -1,4 +1,5 @@
 PROPRIETARY SOFTWARE LICENSE
+SPDX-License-Identifier: LicenseRef-PR-Checkmate-Proprietary
 All Rights Reserved
 
 Copyright (c) 2025-2026 Artur Polishchuk. All Rights Reserved.
@@ -62,9 +63,13 @@ This grant does not include, and RESTRICTIONS 1 and 3 through 7 above
 continue to apply in full to, any right to: copy or redistribute the
 Distributed Package outside of standard package-manager installation; modify,
 decompile, or reverse engineer it; or access, copy, or create derivative
-works from any source code not included in the published npm tarball. This
-grant may be revoked by the Owner for future versions at any time; it does
-not affect versions already installed.
+works from any source code not included in the published npm tarball.
+
+The grant above is perpetual and irrevocable for every version of the
+Distributed Package published under these terms, including after the Owner
+stops publishing. The Owner may release future versions under different
+terms, including paid terms; such terms apply only to those future versions
+and never to a version already published.
 
 ================================================================================
 PUBLIC MIRROR EXCEPTION

package/README.md

@@ -15,9 +15,10 @@
 > A security-first PR gate for CI: secret scanning, dependency vulnerability checks, and
 > a CycloneDX SBOM plus an independent
 > [VirusTotal scan](https://github.com/Mybono/pr_checkmate_public/releases/latest) of the
-> exact published tarball on every release — plus 53 code-quality checks across 11
+> exact published tarball on every release — plus 54 code-quality checks across 11
 > languages, bundled. One npm package, one `pr-checkmate.json`, no per-language toolchain
-> setup for the bundled ones.
+> setup for the bundled ones. Also an [MCP server](#ai-agents-mcp): your AI coding agent runs the
+> same gate while it writes code.
 
 Language is auto-detected. Checks run in parallel phases, results post as one PR comment
 that updates in place, and formatter fixes are committed back to the branch.
@@ -64,6 +65,59 @@ Commit both and it runs on the next pull request. Both are regenerated on every
 line, which three lines are load-bearing, adopting it on a codebase that is not clean
 yet, and the setup step each runner-dependency language needs.
 
+## AI agents (MCP)
+
+PR CheckMate is also an [MCP](https://modelcontextprotocol.io) server, so Claude Code, Cursor or any
+other MCP client can run the gate **while it writes code**, not after the pull request is open. The
+agent reads the repository's rules first, checks its own changes as it goes — uncommitted files
+included, nothing has to be staged — and runs the full gate once before it says it is done.
+
+```bash
+npm install -g pr-checkmate
+claude mcp add --scope user pr-checkmate -- pr-checkmate mcp   # once, for every project
+npx pr-checkmate agent-setup                                   # per repository, below
+```
+
+Then check it: `claude mcp list` shows `pr-checkmate ✔ Connected`; sessions that were already open
+need a restart. `claude` comes from the Claude Code CLI (an editor extension keeps its own copy off
+your `PATH`). To stop Claude Code asking before every call, allow `mcp__pr-checkmate` in
+`permissions.allow`
+([details](https://github.com/Mybono/pr_checkmate_public/blob/main/documentation/ai-agents.md#after-installing)).
+
+| Tool | The agent calls it |
+|---|---|
+| `get_rules` | before writing — what blocks a PR, what only warns, your custom rules and banned imports |
+| `check_changes` | while working — fast checks on what it has changed so far |
+| `scan_secrets` | before committing config, environment or credential files |
+| `apply_fixes` | instead of fixing style by hand — formats and autofixes only the files it changed |
+| `check_dependency` | before adding a package — does it exist, advisories (malware included), look-alike names |
+| `verify` | once, when it believes the work is done — every check, the slow ones included |
+| `suggest_config` / `write_config` | set pr-checkmate up for *this* repository: propose, then write once you agree |
+
+`agent-setup` registers the server in `.mcp.json`, adds a short instructions block to `AGENTS.md` /
+`CLAUDE.md` telling the agent *when* to call each tool, and — in Claude Code — installs a hook that
+checks staged changes on `git commit` and blocks the commit with the findings. It only adds, and is
+safe to re-run. While a project has no `pr-checkmate` entry in `.mcp.json`, the summary printed by
+`npx pr-checkmate all` ends with an `AI AGENT:` line pointing at the command (not shown in CI), and
+`init` adds it to the `commands` block of an existing `pr-checkmate.json`.
+
+**Limits.** An agent can ignore a tool, so nothing here guarantees that `npx pr-checkmate all` finds
+nothing: the CI gate stays the authority. Two tools write files, `apply_fixes` and `write_config`;
+the rest only read. The protocol is implemented in this package, with no MCP SDK or HTTP framework
+behind it.
+
+**Turn it off or narrow it.** The `mcp` block of `pr-checkmate.json` controls what the agent sees,
+from its next request and without a restart:
+
+```json
+"mcp": { "enabled": true, "disabledTools": ["check_dependency"], "readOnly": false }
+```
+
+`enabled: false` leaves the server connected with nothing to offer, `disabledTools` hides tools by
+name, and `readOnly: true` hides the two that write files.
+
+[AI agents guide →](https://github.com/Mybono/pr_checkmate_public/blob/main/documentation/ai-agents.md)
+
 ## Language Support
 
 Bundled languages need nothing on the runner. Runner-dependency languages need their
@@ -88,7 +142,7 @@ every language.
 
 ## Checks
 
-54 checks, run in parallel within each phase:
+55 checks, run in parallel within each phase:
 
 | Group | Count | What it covers |
 |---|---|---|
@@ -143,5 +197,6 @@ affect it.
 ## License
 
 LicenseRef Proprietary © 2025-2026 Artur Polishchuk. Free to install and run via the
-published npm package (see [LICENSE](LICENSE) for the exact grant); the source is not
+published npm package, and that right is irrevocable for every published version (see
+[LICENSE](LICENSE) for the exact grant); the source is not
 open-source and is not licensed for copying, modification, or redistribution.

package/cspell.json

@@ -1377,6 +1377,7 @@
     "samd",
     "samplerate",
     "sandboxing",
+    "sarif",
     "satoshis",
     "savgol",
     "sbom",

package/dist/cjs/agent/hook.d.ts

@@ -0,0 +1,38 @@
+import { type ReviewScope } from '../mcp/review.js';
+export declare const HOOK_COMMAND = "pr-checkmate hook";
+/**
+ * Which commits in a shell line need a check, and what each will record.
+ *
+ * `git commit -a` / `-am` stages tracked modifications as it commits, so the index
+ * at hook time does not yet hold what will be recorded; those are checked as a
+ * working-tree snapshot instead, which errs towards reviewing a little more.
+ *
+ * @returns the scope to review, or `undefined` when the line commits nothing.
+ */
+export declare function commitScopeFor(command: string): ReviewScope | undefined;
+interface HookVerdict {
+    /** 2 blocks the tool call, 0 lets it through. */
+    exitCode: 0 | 2;
+    /** Shown to the model when blocked. */
+    stderr?: string;
+}
+/**
+ * What runs after a file edit. Only checks that are a pattern match over the added
+ * lines: they finish in well under a second, and a hook that waits on a type
+ * checker after every keystroke-sized edit would make the agent unusable.
+ *
+ * Deliberately not here: Diff Smells and Leftover Debug. Mid-edit, a `console.log`
+ * or a TODO is how work is done, and a nag for each one teaches the agent to
+ * ignore the hook. They are reported when it asks for `check_changes`, at the point
+ * where they would actually be a mistake. Secrets wait for the commit gate for the
+ * same reason of cost: the scanner starts a process.
+ */
+export declare const EDIT_CHECKS: readonly string[];
+/**
+ * Decide what to do with the call a harness is about to make.
+ *
+ * @param stdin Raw hook payload, as the harness wrote it.
+ * @param fallbackCwd Used when the payload carries no directory.
+ */
+export declare function evaluateHook(stdin: string, fallbackCwd: string): Promise<HookVerdict>;
+export {};

package/dist/cjs/agent/hook.js

@@ -0,0 +1,175 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EDIT_CHECKS = exports.HOOK_COMMAND = void 0;
+exports.commitScopeFor = commitScopeFor;
+exports.evaluateHook = evaluateHook;
+/**
+ * The commit gate for AI coding agents — a Claude Code `PreToolUse` hook.
+ *
+ * An MCP tool is a request: the agent calls `check_changes` if it remembers to.
+ * A hook is a fact: the harness runs it whether the agent remembers or not. So the
+ * server makes conforming code easy and this makes committing nonconforming code
+ * hard — when the agent runs `git commit`, the staged changes are checked first
+ * and a failure comes back as the reason the commit did not happen.
+ *
+ * Exit code 2 is the harness's "block this call and show stderr to the model".
+ * Every other outcome exits 0, **including our own failures**: a gate that cannot
+ * run must not become a reason the agent cannot work.
+ */
+const node_path_1 = __importDefault(require("node:path"));
+const review_js_1 = require("../mcp/review.js");
+const tools_js_1 = require("../mcp/tools.js");
+exports.HOOK_COMMAND = 'pr-checkmate hook';
+/** Separators that begin a new command inside one shell line. */
+const SEGMENT_SPLIT = /&&|\|\||[;|\n]/;
+/** Global git options that take a value as the next token. */
+const OPTIONS_WITH_VALUE = new Set(['-C', '-c', '--git-dir', '--work-tree']);
+/**
+ * The git subcommand a shell segment runs, skipping global options
+ * (`git -C repo -c user.name=x commit` → `commit`).
+ */
+function gitSubcommand(tokens) {
+    if (tokens[0] !== 'git')
+        return undefined;
+    let i = 1;
+    while (i < tokens.length && tokens[i].startsWith('-')) {
+        i += OPTIONS_WITH_VALUE.has(tokens[i]) ? 2 : 1;
+    }
+    return i < tokens.length ? { sub: tokens[i], rest: tokens.slice(i + 1) } : undefined;
+}
+/**
+ * Which commits in a shell line need a check, and what each will record.
+ *
+ * `git commit -a` / `-am` stages tracked modifications as it commits, so the index
+ * at hook time does not yet hold what will be recorded; those are checked as a
+ * working-tree snapshot instead, which errs towards reviewing a little more.
+ *
+ * @returns the scope to review, or `undefined` when the line commits nothing.
+ */
+function commitScopeFor(command) {
+    let scope;
+    for (const segment of command.split(SEGMENT_SPLIT)) {
+        const git = gitSubcommand(segment.trim().split(/\s+/));
+        if (git?.sub !== 'commit')
+            continue;
+        const stagesAll = git.rest.some(t => t === '--all' || /^-[A-Za-z]*a[A-Za-z]*$/.test(t));
+        if (stagesAll)
+            return 'worktree';
+        scope = 'staged';
+    }
+    return scope;
+}
+/**
+ * What runs after a file edit. Only checks that are a pattern match over the added
+ * lines: they finish in well under a second, and a hook that waits on a type
+ * checker after every keystroke-sized edit would make the agent unusable.
+ *
+ * Deliberately not here: Diff Smells and Leftover Debug. Mid-edit, a `console.log`
+ * or a TODO is how work is done, and a nag for each one teaches the agent to
+ * ignore the hook. They are reported when it asks for `check_changes`, at the point
+ * where they would actually be a mistake. Secrets wait for the commit gate for the
+ * same reason of cost: the scanner starts a process.
+ */
+exports.EDIT_CHECKS = [
+    'Merge Conflict',
+    'Diff Security',
+    'Banned Imports',
+    'Custom Rules',
+    'Migration Safety',
+    'Dockerfile Security',
+    'Workflow Security',
+];
+/** Tools that write a file and say which one. */
+const EDIT_TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit']);
+/** More than this and a slow disk or a huge repository has made the hook a cost, not a help. */
+const EDIT_BUDGET_MS = 10000;
+/** Paths nobody wrote by hand: reviewing them only produces noise. */
+const GENERATED = /(^|\/)(node_modules|dist|build|\.git|vendor)\//;
+/**
+ * Review one file the agent just wrote and tell it about problems in *that file*.
+ *
+ * Runs after the edit, so it cannot block anything: exit 2 here only hands the
+ * message to the model. The review sees the whole working tree (the checks are
+ * diff-based) but only findings that point into the edited file are returned, so a
+ * problem the agent has not touched and cannot be blamed for stays out of its way.
+ */
+async function evaluateEdit(payload, fallbackCwd) {
+    const target = payload.tool_input?.file_path;
+    if (typeof target !== 'string' || !target)
+        return { exitCode: 0 };
+    const abs = node_path_1.default.resolve(payload.cwd ?? fallbackCwd, target);
+    const root = await (0, review_js_1.resolveRepoRoot)(node_path_1.default.dirname(abs));
+    if (!root)
+        return { exitCode: 0 };
+    const rel = node_path_1.default.relative(root, abs).split(node_path_1.default.sep).join('/');
+    if (rel.startsWith('..') || GENERATED.test(rel))
+        return { exitCode: 0 };
+    const timedOut = Symbol('timeout');
+    let timer;
+    const outcome = await Promise.race([
+        (0, review_js_1.review)({ cwd: root, scope: 'worktree', only: [...exports.EDIT_CHECKS] }),
+        new Promise(resolve => {
+            timer = setTimeout(() => resolve(timedOut), EDIT_BUDGET_MS);
+        }),
+    ]);
+    clearTimeout(timer);
+    if (outcome === timedOut)
+        return { exitCode: 0 };
+    const lines = [];
+    for (const result of outcome.report.results) {
+        for (const f of result.findings ?? []) {
+            if (f.file !== rel)
+                continue;
+            lines.push(`  ${f.file}${f.line ? `:${f.line}` : ''}  [${result.name}] ${f.rule}${f.snippet ? ` — ${f.snippet}` : ''}`);
+        }
+    }
+    if (lines.length === 0)
+        return { exitCode: 0 };
+    return {
+        exitCode: 2,
+        stderr: `pr-checkmate found problems in ${rel} — fix them in this file:\n${lines.join('\n')}`,
+    };
+}
+/**
+ * Decide what to do with the call a harness is about to make.
+ *
+ * @param stdin Raw hook payload, as the harness wrote it.
+ * @param fallbackCwd Used when the payload carries no directory.
+ */
+async function evaluateHook(stdin, fallbackCwd) {
+    try {
+        const payload = JSON.parse(stdin);
+        if (payload.hook_event_name === 'PostToolUse') {
+            return payload.tool_name && EDIT_TOOLS.has(payload.tool_name)
+                ? await evaluateEdit(payload, fallbackCwd)
+                : { exitCode: 0 };
+        }
+        const command = payload.tool_input?.command;
+        if ((payload.tool_name && payload.tool_name !== 'Bash') || typeof command !== 'string') {
+            return { exitCode: 0 };
+        }
+        const scope = commitScopeFor(command);
+        if (!scope)
+            return { exitCode: 0 };
+        const root = await (0, review_js_1.resolveRepoRoot)(node_path_1.default.resolve(payload.cwd ?? fallbackCwd));
+        if (!root)
+            return { exitCode: 0 };
+        const outcome = await (0, review_js_1.review)({ cwd: root, scope });
+        if (outcome.report.ok)
+            return { exitCode: 0 };
+        const { text } = (0, tools_js_1.formatReport)(outcome.report, { ...outcome, advice: '' });
+        return {
+            exitCode: 2,
+            stderr: `Commit blocked by pr-checkmate — the pull request gate would fail on these changes.\n${text}\nFix the findings, stage the fixes, and commit again.`,
+        };
+    }
+    catch (err) {
+        return {
+            exitCode: 0,
+            stderr: `pr-checkmate hook skipped, could not complete: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+}

package/dist/cjs/agent/registration.d.ts

@@ -0,0 +1,10 @@
+export declare const MCP_SERVER_NAME = "pr-checkmate";
+/**
+ * Whether the project's `.mcp.json` already registers the server. A missing or
+ * broken file counts as no.
+ *
+ * Kept apart from `setup.ts` on purpose: the run summary asks this question, and
+ * importing `setup.ts` from there closes a loop through the hook and the MCP
+ * review back into the run that is printing.
+ */
+export declare function isMcpRegistered(cwd: string): boolean;

package/dist/cjs/agent/registration.js

@@ -0,0 +1,28 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MCP_SERVER_NAME = void 0;
+exports.isMcpRegistered = isMcpRegistered;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+exports.MCP_SERVER_NAME = 'pr-checkmate';
+/**
+ * Whether the project's `.mcp.json` already registers the server. A missing or
+ * broken file counts as no.
+ *
+ * Kept apart from `setup.ts` on purpose: the run summary asks this question, and
+ * importing `setup.ts` from there closes a loop through the hook and the MCP
+ * review back into the run that is printing.
+ */
+function isMcpRegistered(cwd) {
+    try {
+        const parsed = JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(cwd, '.mcp.json'), 'utf-8'));
+        const servers = parsed?.mcpServers;
+        return typeof servers === 'object' && servers !== null && exports.MCP_SERVER_NAME in servers;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/cjs/agent/setup.d.ts

@@ -0,0 +1,21 @@
+/** Whether `name` resolves to an executable on PATH — the question the client will ask when it starts the server. */
+export declare function isOnPath(name: string, env?: NodeJS.ProcessEnv): boolean;
+export declare const BLOCK_START = "<!-- pr-checkmate:agent-rules:start -->";
+export declare const BLOCK_END = "<!-- pr-checkmate:agent-rules:end -->";
+type SetupStatus = 'created' | 'updated' | 'unchanged' | 'skipped';
+interface SetupAction {
+    file: string;
+    status: SetupStatus;
+    detail: string;
+}
+interface SetupOptions {
+    /** Install the commit-gate hook. Default true. */
+    hook?: boolean;
+    /** Whether the CLI is on PATH. Detected when omitted; injectable for tests. */
+    cliOnPath?: boolean;
+}
+/** Configure a repository for agents. Throws, naming the file, if a JSON file cannot be read safely. */
+export declare function setupAgent(cwd: string, opts?: SetupOptions): SetupAction[];
+/** Print what changed and the one step the repository cannot do for the user. */
+export declare function reportSetup(actions: SetupAction[]): void;
+export {};

package/dist/cjs/agent/setup.js

@@ -0,0 +1,229 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BLOCK_END = exports.BLOCK_START = void 0;
+exports.isOnPath = isOnPath;
+exports.setupAgent = setupAgent;
+exports.reportSetup = reportSetup;
+// cspell:ignore PATHEXT
+/**
+ * `pr-checkmate agent-setup` — wire a repository so AI agents use the gate by default.
+ *
+ * Three pieces, each covering a failure of the one before:
+ *
+ * 1. `.mcp.json` registers the server, so the tools exist;
+ * 2. an instructions block in `AGENTS.md` / `CLAUDE.md` tells the agent *when* to
+ *    call them — tools an agent was never told to use mostly go unused;
+ * 3. a Claude Code hook checks staged changes on `git commit`, so the gate holds
+ *    even when the agent forgets steps 1 and 2.
+ *
+ * Idempotent, and it only ever adds: an existing entry is left as the user wrote
+ * it, a block we own is refreshed in place, and a settings file we cannot parse is
+ * reported instead of overwritten.
+ */
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const index_js_1 = require("../utils/index.js");
+const package_version_js_1 = require("../utils/package-version.js");
+const hook_js_1 = require("./hook.js");
+const registration_js_1 = require("./registration.js");
+const CLI = 'pr-checkmate';
+/** Whether `name` resolves to an executable on PATH — the question the client will ask when it starts the server. */
+function isOnPath(name, env = process.env) {
+    const exts = process.platform === 'win32' ? (env.PATHEXT ?? '.EXE;.CMD').split(';') : [''];
+    return (env.PATH ?? '')
+        .split(node_path_1.default.delimiter)
+        .filter(Boolean)
+        .some(dir => exts.some(ext => {
+        try {
+            node_fs_1.default.accessSync(node_path_1.default.join(dir, name + ext), node_fs_1.default.constants.X_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }));
+}
+/**
+ * How a client should start the server. A bare `pr-checkmate` is only right when the
+ * CLI is installed globally; otherwise the entry would be written, look fine, and
+ * fail silently the first time a client tried to use it. `npx` always resolves.
+ */
+function mcpEntry(onPath) {
+    // Pinned to the version writing the entry: an unpinned `npx -y` runs whatever is
+    // published next on every contributor's machine, which is exactly what the Agent
+    // Instructions check flags in other people's `.mcp.json`.
+    return onPath
+        ? { command: CLI, args: ['mcp'] }
+        : { command: 'npx', args: ['-y', `${CLI}@${(0, package_version_js_1.packageVersion)()}`, 'mcp'] };
+}
+exports.BLOCK_START = '<!-- pr-checkmate:agent-rules:start -->';
+exports.BLOCK_END = '<!-- pr-checkmate:agent-rules:end -->';
+/** What the agent is told. Kept short: it is read on every session. */
+const AGENT_RULES_BLOCK = `${exports.BLOCK_START}
+## Code quality gate (pr-checkmate)
+
+Pull requests in this repository are checked by pr-checkmate. Write code that passes the first time:
+
+1. Before writing code, call \`get_rules\` on the \`pr-checkmate\` MCP server to see what the gate enforces.
+2. While working, and before every commit, call \`check_changes\`. Fix every ❌ finding and call it again until it passes.
+3. Before adding any package, call \`check_dependency\` — it catches names that do not exist, versions with known advisories and look-alike names. Before committing configuration, environment or credential files, call \`scan_secrets\`.
+4. When you believe the work is done, call \`verify\` once (it also runs the slow checks) and fix what it reports before telling the user you are finished.
+5. Fix findings in the code. Do not silence them with \`eslint-disable\`, \`--no-verify\`, or by editing \`pr-checkmate.json\` unless the user asks you to.
+
+If the MCP server is unavailable, run \`pr-checkmate precommit\` before committing.
+${exports.BLOCK_END}
+`;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Read a JSON object, `{}` when the file is absent, and an error that names the file when it is not JSON. */
+function readJsonObject(file) {
+    if (!node_fs_1.default.existsSync(file))
+        return { data: {}, existed: false };
+    try {
+        const parsed = JSON.parse(node_fs_1.default.readFileSync(file, 'utf-8'));
+        if (isRecord(parsed))
+            return { data: parsed, existed: true };
+    }
+    catch {
+        // fall through to the shared message
+    }
+    throw new Error(`${file} is not a valid JSON object — fix it by hand, then run agent-setup again`);
+}
+function writeJson(file, data) {
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(file), { recursive: true });
+    node_fs_1.default.writeFileSync(file, `${JSON.stringify(data, null, 2)}\n`);
+}
+/** Register the MCP server in the project's `.mcp.json`. */
+function setupMcpConfig(cwd, onPath) {
+    const file = node_path_1.default.join(cwd, '.mcp.json');
+    const { data, existed } = readJsonObject(file);
+    const servers = isRecord(data.mcpServers) ? data.mcpServers : {};
+    const entry = mcpEntry(onPath);
+    if (registration_js_1.MCP_SERVER_NAME in servers) {
+        return {
+            file: '.mcp.json',
+            status: 'unchanged',
+            detail: `"${registration_js_1.MCP_SERVER_NAME}" already registered`,
+        };
+    }
+    writeJson(file, { ...data, mcpServers: { ...servers, [registration_js_1.MCP_SERVER_NAME]: entry } });
+    return {
+        file: '.mcp.json',
+        status: existed ? 'updated' : 'created',
+        detail: `registered "${registration_js_1.MCP_SERVER_NAME}" (runs: ${entry.command} ${entry.args.join(' ')})`,
+    };
+}
+/** Insert or refresh our block in one instructions file. */
+function upsertBlock(file, name) {
+    const existing = node_fs_1.default.existsSync(file) ? node_fs_1.default.readFileSync(file, 'utf-8') : undefined;
+    if (existing === undefined) {
+        node_fs_1.default.writeFileSync(file, `${AGENT_RULES_BLOCK}`);
+        return { file: name, status: 'created', detail: 'wrote the agent instructions' };
+    }
+    const start = existing.indexOf(exports.BLOCK_START);
+    const end = existing.indexOf(exports.BLOCK_END);
+    let next;
+    if (start !== -1 && end > start) {
+        next =
+            existing.slice(0, start) +
+                AGENT_RULES_BLOCK.trimEnd() +
+                existing.slice(end + exports.BLOCK_END.length);
+    }
+    else {
+        next = `${existing.trimEnd()}\n\n${AGENT_RULES_BLOCK}`;
+    }
+    if (next === existing)
+        return { file: name, status: 'unchanged', detail: 'instructions already current' };
+    node_fs_1.default.writeFileSync(file, next);
+    return { file: name, status: 'updated', detail: 'added the agent instructions' };
+}
+/**
+ * Put the instructions where agents read them. `AGENTS.md` is the shared
+ * convention; `CLAUDE.md` is what Claude Code reads. Both are updated when both
+ * exist, and `AGENTS.md` is created when neither does.
+ */
+function setupInstructions(cwd) {
+    const targets = ['AGENTS.md', 'CLAUDE.md'].filter(name => node_fs_1.default.existsSync(node_path_1.default.join(cwd, name)));
+    if (targets.length === 0)
+        targets.push('AGENTS.md');
+    return targets.map(name => upsertBlock(node_path_1.default.join(cwd, name), name));
+}
+/** The two hook entries: the commit gate before `git commit`, the file check after an edit. */
+const HOOK_ENTRIES = [
+    { event: 'PreToolUse', matcher: 'Bash' },
+    { event: 'PostToolUse', matcher: 'Edit|Write|MultiEdit' },
+];
+/** Whether `entries` already holds our hook command. */
+function hasOurHook(entries) {
+    return entries.some(entry => isRecord(entry) &&
+        Array.isArray(entry.hooks) &&
+        entry.hooks.some(h => isRecord(h) && h.command === hook_js_1.HOOK_COMMAND));
+}
+/**
+ * Add the commit gate and the per-edit check to `.claude/settings.json`, each only
+ * if it is not there yet. Both run the same command; which one fires is decided by
+ * the event the harness reports.
+ */
+function setupHook(cwd) {
+    const rel = node_path_1.default.join('.claude', 'settings.json');
+    const file = node_path_1.default.join(cwd, rel);
+    const { data, existed } = readJsonObject(file);
+    const hooks = isRecord(data.hooks) ? { ...data.hooks } : {};
+    let added = 0;
+    for (const { event, matcher } of HOOK_ENTRIES) {
+        const current = Array.isArray(hooks[event]) ? hooks[event] : [];
+        if (hasOurHook(current))
+            continue;
+        hooks[event] = [...current, { matcher, hooks: [{ type: 'command', command: hook_js_1.HOOK_COMMAND }] }];
+        added++;
+    }
+    if (added === 0)
+        return { file: rel, status: 'unchanged', detail: 'hooks already installed' };
+    writeJson(file, { ...data, hooks });
+    return {
+        file: rel,
+        status: existed ? 'updated' : 'created',
+        detail: 'git commit runs the gate on staged changes; each file edit is checked for security problems',
+    };
+}
+/** Configure a repository for agents. Throws, naming the file, if a JSON file cannot be read safely. */
+function setupAgent(cwd, opts = {}) {
+    const onPath = opts.cliOnPath ?? isOnPath(CLI);
+    const settings = node_path_1.default.join('.claude', 'settings.json');
+    const actions = [setupMcpConfig(cwd, onPath), ...setupInstructions(cwd)];
+    if (opts.hook === false) {
+        actions.push({
+            file: settings,
+            status: 'skipped',
+            detail: 'commit gate not requested (--no-hook)',
+        });
+    }
+    else if (!onPath) {
+        // The hook runs on every Bash call the agent makes. Through `npx` that is a
+        // package resolution per call — a cost paid all session for a gate that only
+        // matters at commit time — so it waits for an install the hook can rely on.
+        actions.push({
+            file: settings,
+            status: 'skipped',
+            detail: `commit gate needs "${CLI}" on PATH — run "npm install -g ${CLI}", then agent-setup again`,
+        });
+    }
+    else {
+        actions.push(setupHook(cwd));
+    }
+    return actions;
+}
+/** Print what changed and the one step the repository cannot do for the user. */
+function reportSetup(actions) {
+    for (const a of actions)
+        index_js_1.logger.info(`[agent-setup]: ${a.status.padEnd(9)} ${a.file} — ${a.detail}`);
+    index_js_1.logger.info('');
+    index_js_1.logger.info('[agent-setup]: Installing the CLI globally is recommended (faster start, enables the commit gate):');
+    index_js_1.logger.info('[agent-setup]:   npm install -g pr-checkmate');
+    index_js_1.logger.info('[agent-setup]: To make it available in every project for Claude Code, run once:');
+    index_js_1.logger.info('[agent-setup]:   claude mcp add --scope user pr-checkmate -- pr-checkmate mcp');
+}