pr-checkmate 3.2.3 → 4.0.0

package/dist/cjs/core/checks/security/agent-instructions.js

@@ -0,0 +1,149 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentInstructionsCheck = exports.AGENT_PATTERNS = void 0;
+// cspell:ignore windsurfrules
+const index_js_1 = require("../../../utils/index.js");
+const targets_js_1 = require("../../targets.js");
+const types_js_1 = require("../../types.js");
+const findings_js_1 = require("../findings.js");
+/**
+ * Files that tell an AI agent what to do, or what it may do.
+ *
+ * They are code in every sense that matters: an agent reads them and acts, with
+ * the developer's shell and the developer's credentials. A pull request that edits
+ * one changes what every contributor's agent will do on its next run, and the diff
+ * is prose — which review tends to skim. That makes this the cheapest place in a
+ * repository to plant an instruction, and the least reviewed.
+ */
+const INSTRUCTION_GLOBS = [
+    'AGENTS.md',
+    '**/AGENTS.md',
+    'CLAUDE.md',
+    '**/CLAUDE.md',
+    'GEMINI.md',
+    '.cursorrules',
+    '.windsurfrules',
+    '.cursor/rules/**',
+    '.github/copilot-instructions.md',
+    '.claude/commands/**',
+    '.claude/agents/**',
+    '.claude/skills/**',
+    '.claude/settings.json',
+    '.mcp.json',
+];
+/** Dot-directories the file walk drops by default and this check lives in. */
+const KEEP_DIRS = ['.claude', '.cursor', '.github'];
+/**
+ * Characters a person cannot see and a model reads anyway: zero-width characters,
+ * bidirectional overrides and the Unicode "tag" block. Each has been used to hide
+ * an instruction inside text that looks harmless on screen. A byte-order mark is
+ * left out on purpose — editors put one at the top of ordinary files.
+ */
+const INVISIBLE = '[\\u200B-\\u200F\\u202A-\\u202E\\u2060-\\u2064\\u2066-\\u2069]|[\\u{E0000}-\\u{E007F}]';
+exports.AGENT_PATTERNS = [
+    {
+        pattern: new RegExp(`^\\+(?!\\+).*(?:${INVISIBLE})`, 'u'),
+        label: 'invisible Unicode characters (can hide instructions from a human reviewer)',
+        severity: 'error',
+    },
+    {
+        pattern: 
+        // "Do not add X without telling the user" asks the agent to check in, so a
+        // `without` that follows a negation in the same sentence is not a match.
+        /^\+(?!\+)(?![^\n]*\b(?:do not|don't|never)\b[^.\n]*\bwithout\b).*\b(?:do not|don't|never|without)\b[^.\n]{0,30}\b(?:tell|telling|inform|informing|mention|show|reveal|notify)\b[^.\n]{0,20}\b(?:the )?(?:user|developer|human)\b/i,
+        label: 'tells the agent to hide something from the user',
+        severity: 'error',
+    },
+    {
+        pattern: /^\+(?!\+).*\b(?:send|post|upload|curl|wget|fetch|exfiltrate|email)\b[^\n]{0,80}(?:\.env\b|credentials?|secrets?|api[_ -]?keys?|\btokens?\b|\bssh\b|id_rsa)[^\n]{0,80}https?:\/\//i,
+        label: 'sends credentials or secrets to a URL',
+        severity: 'error',
+    },
+    {
+        pattern: /^\+(?!\+).*\b(?:ignore|disregard|forget|override)\b[^.\n]{0,40}\b(?:previous|prior|above|earlier|all|any)\b[^.\n]{0,30}\b(?:instructions?|rules|prompts?|guidelines)\b/i,
+        label: 'prompt-injection phrasing ("ignore previous instructions")',
+        severity: 'warn',
+    },
+    {
+        pattern: /^\+(?!\+).*\b(?:curl|wget)\b[^|\n]*\|\s*(?:sudo\s+)?(?:sh|bash|zsh)\b/i,
+        label: 'pipes a download straight into a shell (an agent will run what it is told to run)',
+        severity: 'warn',
+    },
+    {
+        pattern: /^\+(?!\+).*(?:--no-verify|--dangerously-skip-permissions|--no-gpg-sign)\b/,
+        label: 'instructs the agent to skip a safety check',
+        severity: 'warn',
+    },
+    {
+        pattern: /^\+(?!\+)\s*"defaultMode"\s*:\s*"bypassPermissions"/,
+        label: 'bypassPermissions as the project default (every contributor’s agent runs without asking)',
+        severity: 'error',
+    },
+    {
+        pattern: /^\+(?!\+)\s*"enableAllProjectMcpServers"\s*:\s*true/,
+        label: 'auto-approves every MCP server this repository declares',
+        severity: 'warn',
+    },
+    {
+        pattern: /^\+(?!\+)\s*"(?:Bash|Write|Edit)(?:\((?:\*|:\*)\))?"\s*,?\s*$/,
+        label: 'permission granted for every shell command or file write',
+        severity: 'warn',
+    },
+    {
+        pattern: /^\+(?!\+).*"url"\s*:\s*"http:\/\/(?!localhost|127\.0\.0\.1|\[::1\])/,
+        label: 'MCP server reached over plain HTTP',
+        severity: 'warn',
+    },
+    {
+        // `"args": ["-y", "pkg"]` with no @version: whatever is published next runs on
+        // the machine of everyone who opens the repository.
+        pattern: /^\+(?!\+).*"args"\s*:\s*\[\s*"-y"\s*,\s*"(?:@[^/"@]+\/)?[^"@]+"/,
+        label: 'MCP server fetched with npx and no pinned version (the next publish runs on every contributor’s machine)',
+        severity: 'warn',
+    },
+];
+exports.agentInstructionsCheck = {
+    name: 'Agent Instructions',
+    phase: 'informational',
+    // No `requiresDiff`: a hidden instruction is as live in a file that arrived last
+    // year as in one added today, so a whole-repository run reads them too.
+    applies(ctx) {
+        return ctx.config.agentInstructions?.enabled !== false;
+    },
+    async run(ctx) {
+        try {
+            const cfg = ctx.config.agentInstructions ?? {};
+            const found = (0, findings_js_1.emptyBuckets)();
+            const scanInto = (stdout) => {
+                // `comments: 'off'`: these are Markdown and JSON, where a leading `#` is a
+                // heading and `//` is part of a URL — stripping them as comments would
+                // blank exactly the lines worth reading.
+                (0, findings_js_1.mergeSeverityBuckets)(found, (0, findings_js_1.scanDiffPatterns)(stdout, exports.AGENT_PATTERNS, {
+                    comments: 'off',
+                    ignorePaths: cfg.ignorePaths,
+                }));
+            };
+            if (ctx.baseSha) {
+                scanInto(await (0, findings_js_1.diffAddedLines)(ctx, INSTRUCTION_GLOBS));
+            }
+            else if (ctx.config.run?.fullScanBehaviour !== 'skip') {
+                const files = await (0, targets_js_1.listTrackedFiles)(ctx, INSTRUCTION_GLOBS, ['.'], {
+                    keepDirs: KEEP_DIRS,
+                });
+                if (files === null)
+                    return (0, types_js_1.skip)('git unavailable');
+                await (0, findings_js_1.scanTrackedFiles)(ctx, files, scanInto);
+            }
+            return (0, findings_js_1.reportSeverityBuckets)(found.errors, found.warnings, {
+                prefix: 'Agent Instructions',
+                errorSummary: n => `${n} issue(s)`,
+                warningSummary: n => `${n} warning(s)`,
+                ...(0, findings_js_1.clientFindingOptions)(ctx, cfg),
+            });
+        }
+        catch (err) {
+            index_js_1.logger.warn(`[Agent Instructions]: ⚠️ Could not analyze agent files\n${err}`);
+            return (0, types_js_1.skip)('agent files unavailable');
+        }
+    },
+};

package/dist/cjs/core/checks/security/diff-security.d.ts

@@ -1,2 +1,9 @@
 import { Check } from '../../types.js';
+import { DiffPattern } from '../findings.js';
+/**
+ * npm supply-chain entry points, matched in `package.json`. Both are how a
+ * compromised package reaches a developer machine or CI runner, so they are
+ * worth a human look whenever one is added — neither is wrong by itself.
+ */
+export declare const PACKAGE_JSON_PATTERNS: DiffPattern[];
 export declare const diffSecurityCheck: Check;

package/dist/cjs/core/checks/security/diff-security.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.diffSecurityCheck = void 0;
+exports.diffSecurityCheck = exports.PACKAGE_JSON_PATTERNS = void 0;
 const index_js_1 = require("../../../config/index.js");
 const index_js_2 = require("../../../utils/index.js");
 const types_js_1 = require("../../types.js");
@@ -235,6 +235,25 @@ const KOTLIN_SECURITY_PATTERNS = [
     },
 ];
 const JS_GLOBS = ['*.ts', '*.tsx', '*.js', '*.jsx', '*.mjs', '*.cjs'];
+const PACKAGE_JSON_GLOBS = ['package.json', '*/package.json'];
+/**
+ * npm supply-chain entry points, matched in `package.json`. Both are how a
+ * compromised package reaches a developer machine or CI runner, so they are
+ * worth a human look whenever one is added — neither is wrong by itself.
+ */
+exports.PACKAGE_JSON_PATTERNS = [
+    {
+        pattern: /^\+(?!\+)\s*"(?:preinstall|install|postinstall)"\s*:/,
+        label: 'npm install lifecycle script (runs on every consumer install)',
+        severity: 'warn',
+    },
+    {
+        // `repository.url` is the one key that legitimately holds a `git+https:` value.
+        pattern: /^\+(?!\+)\s*"(?!url")[^"]+"\s*:\s*"(?:git\+[a-z]+:|git:\/\/|git@|github:|https?:\/\/[^"]+\.(?:tgz|tar\.gz)")/,
+        label: 'dependency from a git or tarball URL (bypasses registry integrity and audit)',
+        severity: 'warn',
+    },
+];
 /**
  * Compile the client's `extraPatterns` into the same shape as the built-ins, so
  * a project rule gets identical treatment: comment stripping, the code/raw view,
@@ -323,6 +342,7 @@ exports.diffSecurityCheck = {
             // Client `extraPatterns` run against every scanned language, since a
             // project rule is not tied to the built-in language split.
             const sets = [[JS_GLOBS, [...SECURITY_PATTERNS, ...extra]]];
+            sets.push([PACKAGE_JSON_GLOBS, exports.PACKAGE_JSON_PATTERNS]);
             if (ctx.languages.includes('python')) {
                 sets.push([['*.py'], [...PYTHON_SECURITY_PATTERNS, ...extra]]);
             }

package/dist/cjs/core/checks/security/security.d.ts

@@ -30,19 +30,6 @@ import { Check } from '../../types.js';
  *   the caller keeps its old wording rather than claiming a number it does not have.
  */
 export declare function countFindings(reportPath: string): number | null;
-/**
- * How the outcome names what was found.
- *
- * Its own function so both halves are reachable without running the scanner. The
- * corpus for this check deliberately does not: the wrapper downloads a gitleaks
- * binary on first use, and a unit suite that reaches the network is the thing the
- * `installer` seam in `ensure.ts` exists to avoid. What broke here was the wording
- * — a row that read the same for one secret and for thirty-nine — and the wording
- * is testable on its own.
- *
- * `null` keeps the old sentence rather than inventing a number: a report we could
- * not read is not a reason to claim a count.
- */
 export declare function secretsSummary(found: number | null): string;
 /**
  * Whether the wrapper died instead of reporting, judged from its stderr.

package/dist/cjs/core/checks/security/security.js

@@ -13,6 +13,7 @@ const node_path_1 = __importDefault(require("node:path"));
 const index_js_1 = require("../../../config/index.js");
 const execa_js_1 = require("../../../utils/execa.js");
 const index_js_2 = require("../../../utils/index.js");
+const finding_store_js_1 = require("../../finding-store.js");
 const types_js_1 = require("../../types.js");
 /**
  * A HOME the scanner can actually write to.
@@ -66,6 +67,31 @@ function countFindings(reportPath) {
  * `null` keeps the old sentence rather than inventing a number: a report we could
  * not read is not a reason to claim a count.
  */
+/**
+ * Tell the report where each leak is. The secret itself is never copied: the
+ * finding carries a file, a line and the rule that matched, which is all anyone
+ * needs to go and remove it — and all that is safe to hand to an agent's context.
+ */
+function recordLeaks(reportPath, cwd) {
+    try {
+        const report = JSON.parse(node_fs_1.default.readFileSync(reportPath, 'utf-8'));
+        if (!Array.isArray(report))
+            return;
+        for (const leak of report) {
+            if (typeof leak?.File !== 'string')
+                continue;
+            (0, finding_store_js_1.addFinding)({
+                file: node_path_1.default.isAbsolute(leak.File) ? node_path_1.default.relative(cwd, leak.File) : leak.File,
+                line: typeof leak.StartLine === 'number' ? leak.StartLine : undefined,
+                rule: typeof leak.RuleID === 'string' ? leak.RuleID : 'secret',
+                severity: 'error',
+            });
+        }
+    }
+    catch {
+        // An unreadable report already shows up as an uncounted summary; no locations to add.
+    }
+}
 function secretsSummary(found) {
     return found === null ? 'potential secrets detected' : `${found} potential secret(s)`;
 }
@@ -186,6 +212,7 @@ exports.securityCheck = {
         if (stderr.trim())
             index_js_2.logger.warn(stderr.trimEnd());
         const found = countFindings(reportPath);
+        recordLeaks(reportPath, ctx.cwd);
         node_fs_1.default.rmSync(reportDir, { recursive: true, force: true });
         if (result.exitCode === 0)
             return (0, types_js_1.pass)();

package/dist/cjs/core/checks/security/workflow-security.js

@@ -55,6 +55,39 @@ exports.WORKFLOW_PATTERNS = [
         label: 'pull_request_target trigger (runs with repo secrets on untrusted PRs)',
         severity: 'warn',
     },
+    {
+        // The second half of the "pwn request": `pull_request_target` alone is harmless,
+        // checking out the PR's own code under it hands the attacker a privileged
+        // runner. One line cannot see the trigger, so this stays a warning.
+        pattern: /^\+(?!\+)\s*(?:ref|repository):\s*['"]?\$\{\{\s*github\.event\.pull_request\.head\.(?:sha|ref|repo\.full_name)\s*\}\}/,
+        label: 'checkout of the PR head (code execution with secrets under pull_request_target)',
+        severity: 'warn',
+    },
+    {
+        pattern: /^\+(?!\+)\s*permissions:\s*write-all\b/,
+        label: 'permissions: write-all (grant the token only the scopes the job needs)',
+        severity: 'error',
+    },
+    {
+        pattern: /^\+(?!\+)\s*secrets:\s*inherit\b/,
+        label: 'secrets: inherit (hands every repository secret to the called workflow)',
+        severity: 'warn',
+    },
+    {
+        pattern: /^\+(?!\+)\s*ACTIONS_ALLOW_UNSECURE_COMMANDS:\s*['"]?true\b/i,
+        label: 'ACTIONS_ALLOW_UNSECURE_COMMANDS (re-enables the deprecated set-env / add-path injection vector)',
+        severity: 'error',
+    },
+    {
+        pattern: /^\+(?!\+).*\b(?:curl|wget)\b[^|]*\|\s*(?:sudo\s+)?(?:sh|bash)\b/i,
+        label: 'piping a download straight to a shell (curl/wget … | sh)',
+        severity: 'warn',
+    },
+    {
+        pattern: /^\+(?!\+)\s*runs-on:\s*\[?\s*['"]?self-hosted\b/,
+        label: 'self-hosted runner (a PR from a fork can run code on your own infrastructure)',
+        severity: 'warn',
+    },
 ];
 exports.workflowSecurityCheck = {
     name: 'Workflow Security',

package/dist/cjs/core/commands.d.ts

@@ -22,6 +22,12 @@ export declare const COMMAND_TO_CHECK: Record<string, string>;
  * and not a reading of our source.
  */
 export declare const TOOLING_COMMANDS: readonly string[];
+/**
+ * Commands that serve AI agents rather than review a diff. They share the CLI's
+ * entry point and nothing else: no scope flags apply, and `mcp` in particular owns
+ * stdout for the protocol, so none of them may be confused with a check name.
+ */
+export declare const AGENT_COMMANDS: readonly string[];
 export declare const STANDALONE_COMMANDS: readonly string[];
 /** Flags accepted anywhere on the command line, with what each one means. */
 export declare const FLAGS: Record<string, string>;

package/dist/cjs/core/commands.js

@@ -12,7 +12,7 @@
  * reports success having verified nothing at all.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FLAGS = exports.STANDALONE_COMMANDS = exports.TOOLING_COMMANDS = exports.COMMAND_TO_CHECK = void 0;
+exports.FLAGS = exports.STANDALONE_COMMANDS = exports.AGENT_COMMANDS = exports.TOOLING_COMMANDS = exports.COMMAND_TO_CHECK = void 0;
 /** Maps short CLI command names to their registry check names. */
 exports.COMMAND_TO_CHECK = {
     // Every check that can fail a run is reachable on its own, so "why does this
@@ -44,6 +44,7 @@ exports.COMMAND_TO_CHECK = {
     'license-header': 'License Header',
     'config-validation': 'Config Validation',
     'dockerfile-security': 'Dockerfile Security',
+    'agent-instructions': 'Agent Instructions',
     'case-collision': 'Case Collision',
     'vuln-scan': 'Vuln Scan',
     'leftover-debug': 'Leftover Debug',
@@ -79,14 +80,23 @@ exports.COMMAND_TO_CHECK = {
  * and not a reading of our source.
  */
 exports.TOOLING_COMMANDS = ['install', 'doctor', 'cache-prune'];
+/**
+ * Commands that serve AI agents rather than review a diff. They share the CLI's
+ * entry point and nothing else: no scope flags apply, and `mcp` in particular owns
+ * stdout for the protocol, so none of them may be confused with a check name.
+ */
+exports.AGENT_COMMANDS = ['mcp', 'hook', 'agent-setup'];
 exports.STANDALONE_COMMANDS = [
     'init',
     'all',
     'precommit',
     ...exports.TOOLING_COMMANDS,
+    ...exports.AGENT_COMMANDS,
 ];
 /** Flags accepted anywhere on the command line, with what each one means. */
 exports.FLAGS = {
     '--full': 'review every tracked file instead of the diff (the default outside CI)',
     '--all': 'with "install": fetch every profile, not only the ones this repository needs',
+    '--sarif': 'write findings as SARIF 2.1.0 to pr-checkmate.sarif (check-running commands only)',
+    '--no-hook': 'with "agent-setup": skip the git-commit gate for Claude Code',
 };

package/dist/cjs/core/finding-store.d.ts

@@ -0,0 +1,16 @@
+import type { Finding } from '../utils/result-collector.js';
+/** Run `work` collecting every finding filed inside it. */
+export declare function collectFindings<T>(work: () => Promise<T>): Promise<{
+    result: T;
+    findings: Finding[];
+}>;
+/** A scanner saw `sample` under `label` at `file:line`. Claimed later by {@link fileFindings}. */
+export declare function noteLocation(label: string, sample: string, file: string, line: number): void;
+/**
+ * Turn the findings that survived filtering into located ones. Each sample claims
+ * the oldest location noted for it, so the same line appearing twice resolves to
+ * two places rather than one place twice.
+ */
+export declare function fileFindings(bucket: Record<string, string[]>, severity: Finding['severity']): void;
+/** File a finding directly, for scanners that already know exactly where it is. */
+export declare function addFinding(finding: Finding): void;

package/dist/cjs/core/finding-store.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectFindings = collectFindings;
+exports.noteLocation = noteLocation;
+exports.fileFindings = fileFindings;
+exports.addFinding = addFinding;
+/**
+ * Where a finding was, carried from the scanner that saw it to the report that
+ * names it.
+ *
+ * Scanners reduce what they find to strings in a bucket — `"debugger statement" →
+ * ["debugger;"]` — because the report only ever needed a count and a sample. An
+ * agent needs more: which file, which line. Rewriting forty checks to carry that
+ * would have been forty chances to disagree with each other, so the location is
+ * noted once, where the diff is walked, and attached once, where the buckets are
+ * filed.
+ *
+ * It is attached at filing time, not scan time, on purpose. `ignore` and
+ * `severityOverrides` run in between, and a finding the client has silenced must
+ * not reach an agent that would then dutifully "fix" it.
+ *
+ * The store is an `AsyncLocalStorage` scope per check. Checks of one phase run in
+ * parallel, so a module-level list would mix their findings; a scope cannot. Code
+ * running outside `collectFindings` (the library API, unit tests) finds no store
+ * and every call here does nothing.
+ */
+const node_async_hooks_1 = require("node:async_hooks");
+/** More than this and the list is noise to a reader and a cost to an agent. */
+const MAX_FINDINGS_PER_CHECK = 200;
+const scope = new node_async_hooks_1.AsyncLocalStorage();
+const keyOf = (label, sample) => `${label}\u0000${sample}`;
+/** Run `work` collecting every finding filed inside it. */
+async function collectFindings(work) {
+    const store = { found: [], pending: new Map() };
+    const result = await scope.run(store, work);
+    return { result, findings: store.found };
+}
+/** A scanner saw `sample` under `label` at `file:line`. Claimed later by {@link fileFindings}. */
+function noteLocation(label, sample, file, line) {
+    const store = scope.getStore();
+    if (!store)
+        return;
+    const key = keyOf(label, sample);
+    const queue = store.pending.get(key) ?? [];
+    queue.push({ file, line });
+    store.pending.set(key, queue);
+}
+/**
+ * Turn the findings that survived filtering into located ones. Each sample claims
+ * the oldest location noted for it, so the same line appearing twice resolves to
+ * two places rather than one place twice.
+ */
+function fileFindings(bucket, severity) {
+    const store = scope.getStore();
+    if (!store)
+        return;
+    for (const [label, samples] of Object.entries(bucket)) {
+        for (const sample of samples) {
+            if (store.found.length >= MAX_FINDINGS_PER_CHECK)
+                return;
+            const where = store.pending.get(keyOf(label, sample))?.shift();
+            if (!where)
+                continue;
+            store.found.push({ ...where, rule: label, snippet: sample, severity });
+        }
+    }
+}
+/** File a finding directly, for scanners that already know exactly where it is. */
+function addFinding(finding) {
+    const store = scope.getStore();
+    if (store && store.found.length < MAX_FINDINGS_PER_CHECK)
+        store.found.push(finding);
+}

package/dist/cjs/core/install/doctor.js

@@ -16,6 +16,7 @@ const package_version_js_1 = require("../../utils/package-version.js");
 Object.defineProperty(exports, "packageVersion", { enumerable: true, get: function () { return package_version_js_1.packageVersion; } });
 const cache_js_1 = require("./cache.js");
 const ensure_js_1 = require("./ensure.js");
+const grype_db_js_1 = require("./grype-db.js");
 const prepare_js_1 = require("./prepare.js");
 const profiles_js_1 = require("./profiles.js");
 /**
@@ -142,6 +143,17 @@ async function runDoctor(cwd = process.cwd()) {
         lines.push(`  ${missing.length} profile(s) not installed yet. They are fetched on the next`);
         lines.push('  run, or now with: npx pr-checkmate install');
     }
+    if (config.grypeScan?.enabled !== false) {
+        const db = await (0, grype_db_js_1.grypeDbState)(cwd);
+        lines.push('');
+        lines.push('  Grype database (shared by all projects on this machine)');
+        if (db.state === 'missing-tool')
+            lines.push('    — grype is not installed (brew install grype)');
+        else if (db.state === 'ready')
+            lines.push(`    ✅ up to date${db.built ? ` (built ${db.built})` : ''}`);
+        else
+            lines.push(`    ⬇️  stale${db.built ? ` (built ${db.built})` : ''} — refresh: npx pr-checkmate install`);
+    }
     const stale = (0, cache_js_1.stalePaths)((0, package_version_js_1.packageVersion)(), config.install?.cacheDir);
     if (stale.length > 0) {
         lines.push('');

package/dist/cjs/core/install/grype-db.d.ts

@@ -0,0 +1,25 @@
+type GrypeDbState = {
+    state: 'missing-tool';
+} | {
+    state: 'ready';
+    built?: string;
+} | {
+    state: 'stale';
+    built?: string;
+};
+/**
+ * Is grype's vulnerability database usable right now? grype refuses one older than
+ * 5 days (exit code 1 from `db status`). The database lives in grype's own cache,
+ * shared by every project on the machine, so one refresh serves them all.
+ */
+export declare function grypeDbState(cwd: string): Promise<GrypeDbState>;
+/**
+ * Download a fresh database when the current one is missing or stale.
+ *
+ * `timeoutMs` bounds the download: a check inside a run passes one so it can never
+ * look like a hung commit, `install` passes none because a person asked for exactly
+ * this and the download is the whole job. Returns why it is still unusable, or
+ * `null` when it is ready.
+ */
+export declare function ensureGrypeDb(cwd: string, timeoutMs?: number): Promise<string | null>;
+export {};

package/dist/cjs/core/install/grype-db.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.grypeDbState = grypeDbState;
+exports.ensureGrypeDb = ensureGrypeDb;
+const execa_js_1 = require("../../utils/execa.js");
+const logger_js_1 = require("../../utils/logger.js");
+/** `Built:` line of `grype db status`, so `doctor` can say how old the data is. */
+const builtOf = (stdout) => typeof stdout === 'string' ? /^Built:\s*(.+)$/m.exec(stdout)?.[1]?.trim() : undefined;
+/**
+ * Is grype's vulnerability database usable right now? grype refuses one older than
+ * 5 days (exit code 1 from `db status`). The database lives in grype's own cache,
+ * shared by every project on the machine, so one refresh serves them all.
+ */
+async function grypeDbState(cwd) {
+    const status = await (0, execa_js_1.execa)('grype', ['db', 'status'], { cwd, reject: false, timeout: 30000 });
+    if (status.code === 'ENOENT')
+        return { state: 'missing-tool' };
+    const built = builtOf(status.stdout);
+    return status.exitCode === 0 ? { state: 'ready', built } : { state: 'stale', built };
+}
+/**
+ * Download a fresh database when the current one is missing or stale.
+ *
+ * `timeoutMs` bounds the download: a check inside a run passes one so it can never
+ * look like a hung commit, `install` passes none because a person asked for exactly
+ * this and the download is the whole job. Returns why it is still unusable, or
+ * `null` when it is ready.
+ */
+async function ensureGrypeDb(cwd, timeoutMs) {
+    const current = await grypeDbState(cwd);
+    if (current.state === 'missing-tool')
+        return 'ENOENT';
+    if (current.state === 'ready')
+        return null;
+    logger_js_1.logger.info('[Grype Scan]: vulnerability database missing or stale — updating it');
+    const update = await (0, execa_js_1.execa)('grype', ['db', 'update'], {
+        cwd,
+        reject: false,
+        ...(timeoutMs ? { timeout: timeoutMs } : {}),
+    });
+    if (update.timedOut) {
+        return `database update exceeded ${timeoutMs}ms — run "grype db update" once, then retry`;
+    }
+    return update.exitCode === 0 ? null : 'database update failed (offline?) — run "grype db update"';
+}

package/dist/cjs/core/install/profiles.d.ts

@@ -3,7 +3,7 @@ import type { Language, LanguageUsage } from '../../utils/detect-language.js';
 /**
  * A named bundle of tooling, and the checks that stop working without it.
  *
- * The package ships ~233 MB of tooling, and no repository needs all of it: a
+ * The tooling totals ~233 MB, and no repository needs all of it: a
  * Python service pays for the whole JavaScript toolchain, a repository with
  * Spellcheck switched off still pays for cspell. Profiles are how that stops —
  * they name which slice of the tooling a given repository actually needs.

package/dist/cjs/core/install/profiles.js

@@ -25,9 +25,9 @@ exports.PROFILES = [
             'typescript',
             'eslint',
             'eslint-config-prettier',
-            'eslint-plugin-import-x',
             'eslint-plugin-jsdoc',
             'eslint-plugin-prettier',
+            'eslint-plugin-simple-import-sort',
             'eslint-plugin-sonarjs',
             '@typescript-eslint/eslint-plugin',
             '@typescript-eslint/parser',

package/dist/cjs/core/install/reuse.js

@@ -12,15 +12,18 @@ const resolve_bin_js_1 = require("../../utils/resolve-bin.js");
 /**
  * The major version we declare for a tool, from our own manifest.
  *
- * Read from `dependencies` rather than from the installed tree: what matters is
+ * Read from the manifest rather than from the installed tree: what matters is
  * the version our configuration was written against, and a hoisted install can
  * resolve to something else entirely.
  */
 function ownMajor(pkgName) {
     try {
         const manifest = node_path_1.default.join((0, resolve_bin_js_1.ownPackageRoot)(), 'package.json');
-        const deps = JSON.parse(node_fs_1.default.readFileSync(manifest, 'utf-8')).dependencies;
-        const range = deps?.[pkgName];
+        const parsed = JSON.parse(node_fs_1.default.readFileSync(manifest, 'utf-8'));
+        // Profile tooling is declared in `devDependencies` — it is fetched on demand
+        // rather than installed with us — but it is still the version our config was
+        // written against, and the manifest keeps both.
+        const range = parsed.dependencies?.[pkgName] ?? parsed.devDependencies?.[pkgName];
         if (!range)
             return null;
         // `^10.6.0`, `>=3.0.0`, `~5.1` — the leading number is the major in every

package/dist/cjs/core/registry.js

@@ -41,6 +41,7 @@ const package_size_js_1 = require("./checks/quality/package-size.js");
 const spellcheck_js_1 = require("./checks/quality/spellcheck.js");
 const symlinks_js_1 = require("./checks/quality/symlinks.js");
 const yaml_lint_js_1 = require("./checks/quality/yaml-lint.js");
+const agent_instructions_js_1 = require("./checks/security/agent-instructions.js");
 const diff_security_js_1 = require("./checks/security/diff-security.js");
 const dockerfile_security_js_1 = require("./checks/security/dockerfile-security.js");
 const migration_safety_js_1 = require("./checks/security/migration-safety.js");
@@ -66,6 +67,7 @@ exports.REGISTRY = [
     diff_security_js_1.diffSecurityCheck,
     workflow_security_js_1.workflowSecurityCheck,
     dockerfile_security_js_1.dockerfileSecurityCheck,
+    agent_instructions_js_1.agentInstructionsCheck,
     case_collision_js_1.caseCollisionCheck,
     vuln_scan_js_1.vulnScanCheck,
     grype_scan_js_1.grypeScanCheck,

package/dist/cjs/core/reporters.js

@@ -6,6 +6,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildMarkdownReport = buildMarkdownReport;
 exports.report = report;
 const node_fs_1 = __importDefault(require("node:fs"));
+const registration_js_1 = require("../agent/registration.js");
+const constants_js_1 = require("../config/constants.js");
+const settings_js_1 = require("../mcp/settings.js");
 const http_js_1 = require("../utils/http.js");
 const index_js_1 = require("../utils/index.js");
 const package_version_js_1 = require("../utils/package-version.js");
@@ -107,6 +110,12 @@ function printStdout(report, cfg) {
     if (cfg.include?.docsLink !== false) {
         // The docs cover every check and config key.
         index_js_1.logger.print(' DOCUMENTATION: https://pr-checkmate-docs.pages.dev/');
+        // Said once per project, and never in CI, where nobody is there to act on it.
+        if (!process.env.CI &&
+            (0, settings_js_1.readMcpSettings)(process.cwd()).enabled &&
+            !(0, registration_js_1.isMcpRegistered)(process.cwd())) {
+            index_js_1.logger.print(` AI AGENT: ${constants_js_1.AGENT_SETUP_COMMAND} — your agent then writes code that passes.`);
+        }
     }
 }
 /** Network settings shared by every platform call. */