pr-checkmate 3.3.0 → 4.0.1

package/dist/cjs/utils/execa.js

@@ -1,6 +1,46 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isolateInheritedStdio = isolateInheritedStdio;
 exports.execa = execa;
+/**
+ * Whether children that would inherit our standard streams are kept off them.
+ *
+ * A few checks run a tool with `stdio: 'inherit'` so its output reaches the
+ * terminal. That is right for the CLI and fatal for the MCP server, whose stdout
+ * *is* the protocol: gitleaks printing its banner there is a line that is not
+ * JSON, and the client drops the connection. Swapping `process.stdout.write`
+ * cannot help, because an inherited descriptor never passes through it — so the
+ * redirection has to happen where the child is spawned.
+ */
+let childOutput = null;
+/**
+ * Keep children that would inherit our streams off them, and stop them sharing
+ * stdin. `stderr` (the MCP server) keeps their output as the server's log;
+ * `discard` (the commit hook) drops it, because a hook's stderr is read by the
+ * model and tool banners are not what it needs to hear. No other command is affected.
+ */
+function isolateInheritedStdio(output = 'stderr') {
+    childOutput = output === 'stderr' ? 2 : 'ignore';
+}
+/** Redirect inherited stdout/stderr per {@link isolateInheritedStdio}; stdin is never ours to give away. */
+function isolated(options) {
+    if (childOutput === null || !options)
+        return options;
+    const { stdio } = options;
+    if (stdio === 'inherit')
+        return { ...options, stdio: ['ignore', childOutput, childOutput] };
+    if (Array.isArray(stdio)) {
+        const next = stdio.map((entry, fd) => {
+            if (fd === 0 && entry === 'inherit')
+                return 'ignore';
+            if ((fd === 1 || fd === 2) && entry === 'inherit')
+                return childOutput;
+            return entry;
+        });
+        return { ...options, stdio: next };
+    }
+    return options;
+}
 /**
  * Run a command via execa, loading the module lazily on first call.
  *
@@ -9,5 +49,5 @@ exports.execa = execa;
  */
 async function execa(file, args, options) {
     const { execa: run } = await import('execa');
-    return (await run(file, args, options));
+    return (await run(file, args, isolated(options)));
 }

package/dist/cjs/utils/result-collector.d.ts

@@ -1,8 +1,24 @@
 export type CheckStatus = 'pass' | 'warn' | 'fail' | 'skip';
+/**
+ * One thing a check found, with where it is. Optional on every result: only the
+ * checks that can say where report it, and a result without any is not an error —
+ * it just has a summary and no location.
+ */
+export interface Finding {
+    file: string;
+    /** 1-based line in the file as it will be committed. */
+    line?: number;
+    /** Which rule or pattern matched, as the check names it. */
+    rule: string;
+    /** The offending text, shortened. Never a secret: scanners that find those leave it out. */
+    snippet?: string;
+    severity: 'error' | 'warn';
+}
 export interface CheckResult {
     name: string;
     status: CheckStatus;
     details?: string;
+    findings?: Finding[];
 }
 /**
  *
@@ -12,7 +28,7 @@ export declare class ResultCollector {
     /**
      *
      */
-    register(name: string, status: CheckStatus, details?: string): void;
+    register(name: string, status: CheckStatus, details?: string, findings?: Finding[]): void;
     /**
      *
      */

package/dist/cjs/utils/result-collector.js

@@ -11,9 +11,14 @@ class ResultCollector {
     /**
      *
      */
-    register(name, status, details) {
+    register(name, status, details, findings) {
         const idx = this.results.findIndex(r => r.name === name);
-        const entry = { name, status, ...(details && { details }) };
+        const entry = {
+            name,
+            status,
+            ...(details && { details }),
+            ...(findings && findings.length > 0 && { findings }),
+        };
         if (idx >= 0) {
             this.results[idx] = entry;
         }

package/dist/esm/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/esm/agent/hook.js

@@ -0,0 +1,167 @@
+/**
+ * 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.
+ */
+import path from 'node:path';
+import { resolveRepoRoot, review } from '../mcp/review.js';
+import { formatReport } from '../mcp/tools.js';
+export const 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.
+ */
+export 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.
+ */
+export const 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 = path.resolve(payload.cwd ?? fallbackCwd, target);
+    const root = await resolveRepoRoot(path.dirname(abs));
+    if (!root)
+        return { exitCode: 0 };
+    const rel = path.relative(root, abs).split(path.sep).join('/');
+    if (rel.startsWith('..') || GENERATED.test(rel))
+        return { exitCode: 0 };
+    const timedOut = Symbol('timeout');
+    let timer;
+    const outcome = await Promise.race([
+        review({ cwd: root, scope: 'worktree', only: [...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.
+ */
+export 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 resolveRepoRoot(path.resolve(payload.cwd ?? fallbackCwd));
+        if (!root)
+            return { exitCode: 0 };
+        const outcome = await review({ cwd: root, scope });
+        if (outcome.report.ok)
+            return { exitCode: 0 };
+        const { text } = 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/esm/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/esm/agent/registration.js

@@ -0,0 +1,21 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export 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 function isMcpRegistered(cwd) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(cwd, '.mcp.json'), 'utf-8'));
+        const servers = parsed?.mcpServers;
+        return typeof servers === 'object' && servers !== null && MCP_SERVER_NAME in servers;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/esm/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/esm/agent/setup.js

@@ -0,0 +1,220 @@
+// 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.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { logger } from '../utils/index.js';
+import { packageVersion } from '../utils/package-version.js';
+import { HOOK_COMMAND } from './hook.js';
+import { MCP_SERVER_NAME } from './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. */
+export function isOnPath(name, env = process.env) {
+    const exts = process.platform === 'win32' ? (env.PATHEXT ?? '.EXE;.CMD').split(';') : [''];
+    return (env.PATH ?? '')
+        .split(path.delimiter)
+        .filter(Boolean)
+        .some(dir => exts.some(ext => {
+        try {
+            fs.accessSync(path.join(dir, name + ext), fs.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}@${packageVersion()}`, 'mcp'] };
+}
+export const BLOCK_START = '<!-- pr-checkmate:agent-rules:start -->';
+export const BLOCK_END = '<!-- pr-checkmate:agent-rules:end -->';
+/** What the agent is told. Kept short: it is read on every session. */
+const AGENT_RULES_BLOCK = `${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.
+${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 (!fs.existsSync(file))
+        return { data: {}, existed: false };
+    try {
+        const parsed = JSON.parse(fs.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) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${JSON.stringify(data, null, 2)}\n`);
+}
+/** Register the MCP server in the project's `.mcp.json`. */
+function setupMcpConfig(cwd, onPath) {
+    const file = path.join(cwd, '.mcp.json');
+    const { data, existed } = readJsonObject(file);
+    const servers = isRecord(data.mcpServers) ? data.mcpServers : {};
+    const entry = mcpEntry(onPath);
+    if (MCP_SERVER_NAME in servers) {
+        return {
+            file: '.mcp.json',
+            status: 'unchanged',
+            detail: `"${MCP_SERVER_NAME}" already registered`,
+        };
+    }
+    writeJson(file, { ...data, mcpServers: { ...servers, [MCP_SERVER_NAME]: entry } });
+    return {
+        file: '.mcp.json',
+        status: existed ? 'updated' : 'created',
+        detail: `registered "${MCP_SERVER_NAME}" (runs: ${entry.command} ${entry.args.join(' ')})`,
+    };
+}
+/** Insert or refresh our block in one instructions file. */
+function upsertBlock(file, name) {
+    const existing = fs.existsSync(file) ? fs.readFileSync(file, 'utf-8') : undefined;
+    if (existing === undefined) {
+        fs.writeFileSync(file, `${AGENT_RULES_BLOCK}`);
+        return { file: name, status: 'created', detail: 'wrote the agent instructions' };
+    }
+    const start = existing.indexOf(BLOCK_START);
+    const end = existing.indexOf(BLOCK_END);
+    let next;
+    if (start !== -1 && end > start) {
+        next =
+            existing.slice(0, start) +
+                AGENT_RULES_BLOCK.trimEnd() +
+                existing.slice(end + BLOCK_END.length);
+    }
+    else {
+        next = `${existing.trimEnd()}\n\n${AGENT_RULES_BLOCK}`;
+    }
+    if (next === existing)
+        return { file: name, status: 'unchanged', detail: 'instructions already current' };
+    fs.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 => fs.existsSync(path.join(cwd, name)));
+    if (targets.length === 0)
+        targets.push('AGENTS.md');
+    return targets.map(name => upsertBlock(path.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_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 = path.join('.claude', 'settings.json');
+    const file = path.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_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. */
+export function setupAgent(cwd, opts = {}) {
+    const onPath = opts.cliOnPath ?? isOnPath(CLI);
+    const settings = path.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. */
+export function reportSetup(actions) {
+    for (const a of actions)
+        logger.info(`[agent-setup]: ${a.status.padEnd(9)} ${a.file} — ${a.detail}`);
+    logger.info('');
+    logger.info('[agent-setup]: Installing the CLI globally is recommended (faster start, enables the commit gate):');
+    logger.info('[agent-setup]:   npm install -g pr-checkmate');
+    logger.info('[agent-setup]: To make it available in every project for Claude Code, run once:');
+    logger.info('[agent-setup]:   claude mcp add --scope user pr-checkmate -- pr-checkmate mcp');
+}