@delegance/claude-autopilot 2.5.0 → 5.0.0-alpha.2

package/src/core/detect/llm-key.ts

@@ -0,0 +1,89 @@
+/**
+ * Shared LLM API key detection. Used by setup, doctor/preflight, scan, and run so
+ * every surface agrees on which env vars count as "have a key."
+ *
+ * Before this unified helper, doctor only checked ANTHROPIC_API_KEY + OPENAI_API_KEY
+ * while setup/scan/run checked all 5 providers — producing contradictory messages
+ * ("LLM API key: detected" from setup, "No LLM API key" from doctor moments later).
+ */
+
+import * as fs from 'node:fs';
+
+/** All env var names guardrail recognizes as LLM API keys, ordered by preference. */
+export const LLM_KEY_NAMES = [
+  'ANTHROPIC_API_KEY',
+  'OPENAI_API_KEY',
+  'GEMINI_API_KEY',
+  'GOOGLE_API_KEY',
+  'GROQ_API_KEY',
+] as const;
+
+export type LLMKeyName = typeof LLM_KEY_NAMES[number];
+
+export interface KeyDetectionOptions {
+  /** Additional key→value map to check alongside process.env (e.g. parsed .env.local). */
+  extraEnv?: Record<string, string | undefined>;
+}
+
+export interface KeyDetectionResult {
+  /** True if any recognized LLM key is set to a non-empty value. */
+  hasKey: boolean;
+  /** Preferred key that was detected, or null. Follows LLM_KEY_NAMES order. */
+  preferred: LLMKeyName | null;
+  /** All keys that were detected, in LLM_KEY_NAMES order. */
+  detected: LLMKeyName[];
+}
+
+function readEnvFileSync(filePath: string): Record<string, string> {
+  const vars: Record<string, string> = {};
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    for (const line of content.split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith('#')) continue;
+      const eq = trimmed.indexOf('=');
+      if (eq < 0) continue;
+      vars[trimmed.slice(0, eq).trim()] = trimmed.slice(eq + 1).trim().replace(/^['"]|['"]$/g, '');
+    }
+  } catch {
+    /* ignore */
+  }
+  return vars;
+}
+
+/** Load an env file into a plain object without mutating process.env. */
+export function loadEnvFile(filePath: string): Record<string, string> {
+  return readEnvFileSync(filePath);
+}
+
+/** Detect whether any recognized LLM API key is set. */
+export function detectLLMKey(options: KeyDetectionOptions = {}): KeyDetectionResult {
+  const extra = options.extraEnv ?? {};
+  const detected: LLMKeyName[] = [];
+  for (const name of LLM_KEY_NAMES) {
+    // Treat empty string as "not set" so an env file value can supply the key when
+    // the shell has `FOO=` exported. `??` would shadow the env file here because it
+    // only falls through on null/undefined — matching the old `!! || !!` semantics.
+    const fromProcess = process.env[name];
+    const value = (fromProcess && fromProcess.length > 0) ? fromProcess : extra[name];
+    if (value && value.length > 0) detected.push(name);
+  }
+  return {
+    hasKey: detected.length > 0,
+    preferred: detected[0] ?? null,
+    detected,
+  };
+}
+
+/**
+ * Human-readable list of providers and signup URLs, used by every "no key" message.
+ * Must cover every entry in LLM_KEY_NAMES so users see the same set of options across
+ * preflight, setup, scan, and run.
+ */
+export const LLM_KEY_HINTS: Array<{ name: LLMKeyName; url: string; note?: string }> = [
+  { name: 'ANTHROPIC_API_KEY', url: 'https://console.anthropic.com/' },
+  { name: 'OPENAI_API_KEY',    url: 'https://platform.openai.com/api-keys' },
+  { name: 'GEMINI_API_KEY',    url: 'https://aistudio.google.com/app/apikey' },
+  { name: 'GOOGLE_API_KEY',    url: 'https://aistudio.google.com/app/apikey', note: 'legacy alias for GEMINI_API_KEY' },
+  { name: 'GROQ_API_KEY',      url: 'https://console.groq.com/keys', note: 'fast free tier' },
+];

package/src/core/detect/workspaces.ts

@@ -0,0 +1,103 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+export interface Workspace {
+  name: string;
+  dir: string;          // absolute path
+  rel: string;          // relative to root
+  testCommand?: string;
+}
+
+function readJson(p: string): Record<string, unknown> | null {
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')) as Record<string, unknown>; } catch { return null; }
+}
+
+function globDirs(root: string, patterns: string[]): string[] {
+  const results: string[] = [];
+  for (const pattern of patterns) {
+    // Support "packages/*" and "apps/*" style globs (one level deep only)
+    const parts = pattern.split('/');
+    if (parts.length === 2 && parts[1] === '*') {
+      const base = path.join(root, parts[0]!);
+      if (!fs.existsSync(base)) continue;
+      for (const entry of fs.readdirSync(base, { withFileTypes: true })) {
+        if (entry.isDirectory()) results.push(path.join(base, entry.name));
+      }
+    } else {
+      const abs = path.join(root, pattern);
+      if (fs.existsSync(abs) && fs.statSync(abs).isDirectory()) results.push(abs);
+    }
+  }
+  return results;
+}
+
+function detectTestCommand(dir: string): string | undefined {
+  const pkg = readJson(path.join(dir, 'package.json'));
+  if (pkg?.scripts && typeof (pkg.scripts as Record<string, unknown>).test === 'string') {
+    return `npm test --prefix ${dir}`;
+  }
+  if (fs.existsSync(path.join(dir, 'go.mod'))) return `go test ./... -C ${dir}`;
+  if (fs.existsSync(path.join(dir, 'Cargo.toml'))) return `cargo test --manifest-path ${path.join(dir, 'Cargo.toml')}`;
+  return undefined;
+}
+
+/** Detect npm/yarn/pnpm workspaces, Turborepo, Nx, Go multi-module. */
+export function detectWorkspaces(cwd: string): Workspace[] | null {
+  const pkg = readJson(path.join(cwd, 'package.json')) as { workspaces?: string[] | { packages?: string[] }; name?: string } | null;
+
+  // npm/yarn workspaces
+  let wsDirs: string[] = [];
+  if (pkg?.workspaces) {
+    const patterns = Array.isArray(pkg.workspaces) ? pkg.workspaces : (pkg.workspaces.packages ?? []);
+    wsDirs = globDirs(cwd, patterns);
+  }
+
+  // Turborepo — pnpm-workspace.yaml or turbo.json
+  if (wsDirs.length === 0 && fs.existsSync(path.join(cwd, 'pnpm-workspace.yaml'))) {
+    try {
+      const raw = fs.readFileSync(path.join(cwd, 'pnpm-workspace.yaml'), 'utf8');
+      const matches = raw.match(/^\s*-\s*['"]?([^'"#\n]+)['"]?/gm) ?? [];
+      const patterns = matches.map(m => m.replace(/^\s*-\s*['"]?/, '').replace(/['"]?\s*$/, '').trim());
+      wsDirs = globDirs(cwd, patterns);
+    } catch { /* ignore */ }
+  }
+
+  // Turborepo fallback: packages/ and apps/ dirs
+  if (wsDirs.length === 0 && fs.existsSync(path.join(cwd, 'turbo.json'))) {
+    wsDirs = globDirs(cwd, ['packages/*', 'apps/*']);
+  }
+
+  // Nx: check nx.json + libs/ + apps/
+  if (wsDirs.length === 0 && fs.existsSync(path.join(cwd, 'nx.json'))) {
+    wsDirs = globDirs(cwd, ['libs/*', 'apps/*', 'packages/*']);
+  }
+
+  if (wsDirs.length === 0) return null;
+
+  return wsDirs
+    .filter(d => fs.existsSync(d))
+    .map(d => {
+      const rel = path.relative(cwd, d);
+      const pkgJson = readJson(path.join(d, 'package.json')) as { name?: string } | null;
+      return {
+        name: pkgJson?.name ?? rel,
+        dir: d,
+        rel,
+        testCommand: detectTestCommand(d),
+      };
+    });
+}
+
+/** Given a list of touched files, return which workspaces they belong to. */
+export function mapFilesToWorkspaces(files: string[], workspaces: Workspace[], cwd: string): Map<Workspace, string[]> {
+  const result = new Map<Workspace, string[]>();
+  for (const file of files) {
+    const abs = path.isAbsolute(file) ? file : path.resolve(cwd, file);
+    const ws = workspaces.find(w => abs.startsWith(w.dir + path.sep) || abs === w.dir);
+    if (ws) {
+      if (!result.has(ws)) result.set(ws, []);
+      result.get(ws)!.push(file);
+    }
+  }
+  return result;
+}

package/src/core/errors.ts

@@ -4,7 +4,7 @@ export type ErrorCode =
   | 'auth' | 'rate_limit' | 'transient_network' | 'invalid_config'
   | 'adapter_bug' | 'user_input' | 'budget_exceeded' | 'concurrency_lock' | 'superseded';
 
-export interface AutopilotErrorOptions {
+export interface GuardrailErrorOptions {
   code: ErrorCode;
   retryable?: boolean;
   provider?: string;
@@ -18,16 +18,16 @@ const DEFAULT_RETRYABLE: Record<ErrorCode, boolean> = {
   concurrency_lock: false, superseded: false,
 };
 
-export class AutopilotError extends Error {
+export class GuardrailError extends Error {
   code: ErrorCode;
   retryable: boolean;
   provider?: string;
   step?: string;
   details: Record<string, unknown>;
 
-  constructor(message: string, options: AutopilotErrorOptions) {
+  constructor(message: string, options: GuardrailErrorOptions) {
     super(message);
-    this.name = 'AutopilotError';
+    this.name = 'GuardrailError';
     this.code = options.code;
     this.retryable = options.retryable ?? DEFAULT_RETRYABLE[options.code];
     this.provider = options.provider;

package/src/core/fix/generator.ts

@@ -0,0 +1,149 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import type { Finding } from '../findings/types.ts';
+import type { ReviewEngine } from '../../adapters/review-engine/types.ts';
+
+export const CONTEXT_LINES = 20;
+
+// LLM error / refusal phrases that indicate a bad output
+const REFUSAL_PHRASES = [
+  'i cannot', "i can't", 'i am unable', 'as an ai', 'as a language model',
+  'i apologize', "i'm sorry", 'cannot safely', 'would require', 'error:',
+];
+
+export interface GenerateResult {
+  status: 'ok' | 'cannot_fix' | 'rejected' | 'error';
+  reason?: string;
+  originalLines?: string[];
+  replacementLines?: string[];
+  startLine?: number;
+  endLine?: number;
+}
+
+export function validateReplacement(original: string[], replacement: string[], _finding: Finding): string | null {
+  if (replacement.length === 0) return 'LLM returned empty output';
+
+  // Reject obvious LLM refusals
+  const joined = replacement.join(' ').toLowerCase();
+  for (const phrase of REFUSAL_PHRASES) {
+    if (joined.includes(phrase)) return `LLM refused: "${replacement[0]?.slice(0, 60)}"`;
+  }
+
+  // Reject if line count ballooned more than 3x (likely hallucination)
+  if (replacement.length > original.length * 3 + 10) {
+    return `Suspicious: replacement is ${replacement.length} lines vs original ${original.length}`;
+  }
+
+  // Reject if the replacement is identical (LLM made no change)
+  if (replacement.join('\n') === original.join('\n')) {
+    return 'LLM returned identical code — no change made';
+  }
+
+  return null;
+}
+
+export function buildUnifiedDiff(
+  original: string[],
+  replacement: string[],
+  filePath: string,
+  startLine: number,
+  opts: { color?: boolean } = {},
+): string {
+  // Colors default on for CLI ergonomics; MCP callers pass color:false so ANSI
+  // escapes don't leak into JSON responses that machine clients must parse.
+  const useColor = opts.color !== false;
+  const C = {
+    reset: '\x1b[0m', green: '\x1b[32m', red: '\x1b[31m',
+  };
+  const fmt = (c: keyof typeof C, t: string) => useColor ? `${C[c]}${t}${C.reset}` : t;
+  const lines: string[] = [`--- ${filePath}`, `+++ ${filePath} (proposed fix)`, `@@ -${startLine},${original.length} +${startLine},${replacement.length} @@`];
+  for (const l of original) lines.push(fmt('red', `- ${l}`));
+  for (const l of replacement) lines.push(fmt('green', `+ ${l}`));
+  return lines.join('\n');
+}
+
+export async function generateFix(finding: Finding, engine: ReviewEngine, cwd: string): Promise<GenerateResult> {
+  // MCP handlers can pass through findings loaded from disk — validate required
+  // fields rather than trusting the CLI pre-filter path.
+  if (!finding.file || typeof finding.file !== 'string') {
+    return { status: 'cannot_fix', reason: 'finding.file missing' };
+  }
+  if (typeof finding.line !== 'number' || !Number.isFinite(finding.line) || finding.line < 1) {
+    return { status: 'cannot_fix', reason: 'finding.line missing or invalid' };
+  }
+
+  const absPath = path.resolve(cwd, finding.file);
+  let fileLines: string[];
+  try {
+    fileLines = fs.readFileSync(absPath, 'utf8').split('\n');
+  } catch {
+    return { status: 'cannot_fix', reason: 'file not readable' };
+  }
+
+  const lineIdx = finding.line - 1;
+  if (lineIdx < 0 || lineIdx >= fileLines.length) {
+    return { status: 'cannot_fix', reason: 'line out of range' };
+  }
+
+  const startIdx = Math.max(0, lineIdx - CONTEXT_LINES);
+  const endIdx   = Math.min(fileLines.length - 1, lineIdx + CONTEXT_LINES);
+  const contextLines = fileLines.slice(startIdx, endIdx + 1);
+  const startLine = startIdx + 1;
+
+  const numbered = contextLines.map((l, i) => {
+    const n = startLine + i;
+    return `${n === finding.line ? '>>>' : '   '} ${String(n).padStart(4)}: ${l}`;
+  }).join('\n');
+
+  const prompt = [
+    `File: ${finding.file}`,
+    `Finding (line ${finding.line}): [${finding.severity.toUpperCase()}] ${finding.message}`,
+    finding.suggestion ? `Suggestion: ${finding.suggestion}` : '',
+    '',
+    'Relevant lines (>>> marks the finding):',
+    '```',
+    numbered,
+    '```',
+    '',
+    `Rewrite ONLY lines ${startLine}–${endIdx + 1} to fix this finding.`,
+    'Rules:',
+    '- Output ONLY the replacement lines with no explanation, no markdown fences, no line numbers',
+    '- Preserve indentation exactly',
+    '- Make the minimal change needed — do not refactor unrelated code',
+    '- If the fix cannot be done safely in this context, output exactly: CANNOT_FIX',
+  ].filter(Boolean).join('\n');
+
+  let rawOutput: string;
+  try {
+    const output = await engine.review({ content: prompt, kind: 'file-batch' });
+    rawOutput = output.rawOutput.trim();
+  } catch (err) {
+    return { status: 'error', reason: `LLM error: ${err instanceof Error ? err.message : String(err)}` };
+  }
+
+  if (rawOutput === 'CANNOT_FIX' || rawOutput.startsWith('CANNOT_FIX')) {
+    return { status: 'cannot_fix', reason: 'LLM: cannot fix safely in this context' };
+  }
+
+  // Strip markdown fences if the model added them despite instructions
+  const cleaned = rawOutput
+    .replace(/^```[a-zA-Z]*\n?/, '')
+    .replace(/\n?```$/, '')
+    .trimEnd();
+
+  const replacementLines = cleaned.split('\n');
+  const originalLines = contextLines;
+
+  const validationError = validateReplacement(originalLines, replacementLines, finding);
+  if (validationError) {
+    return { status: 'rejected', reason: validationError };
+  }
+
+  return {
+    status: 'ok',
+    originalLines,
+    replacementLines,
+    startLine,
+    endLine: endIdx + 1,
+  };
+}

package/src/core/ignore/index.ts

@@ -2,7 +2,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { minimatch } from 'minimatch';
 import type { Finding } from '../findings/types.ts';
-import type { AutopilotConfig } from '../config/types.ts';
+import type { GuardrailConfig } from '../config/types.ts';
 
 export interface IgnoreRule {
   ruleId: string | '*';  // finding id prefix or '*' for any
@@ -10,7 +10,7 @@ export interface IgnoreRule {
 }
 
 export function loadIgnoreRules(cwd: string): IgnoreRule[] {
-  const filePath = path.join(cwd, '.autopilot-ignore');
+  const filePath = path.join(cwd, '.guardrail-ignore');
   if (!fs.existsSync(filePath)) return [];
 
   const rules: IgnoreRule[] = [];
@@ -37,8 +37,8 @@ function matchesRule(finding: Finding, rule: IgnoreRule): boolean {
   return minimatch(finding.file.replace(/\\/g, '/'), rule.pathGlob, { matchBase: true });
 }
 
-/** Convert `ignore:` entries from autopilot.config.yaml into IgnoreRules. */
-export function parseConfigIgnore(entries: AutopilotConfig['ignore']): IgnoreRule[] {
+/** Convert `ignore:` entries from guardrail.config.yaml into IgnoreRules. */
+export function parseConfigIgnore(entries: GuardrailConfig['ignore']): IgnoreRule[] {
   if (!entries || entries.length === 0) return [];
   return entries.map(entry => {
     if (typeof entry === 'string') {

package/src/core/mcp/concurrency.ts

@@ -0,0 +1,16 @@
+const mutexes = new Map<string, Promise<void>>();
+
+export async function withWriteLock<T>(workspace: string, fn: () => Promise<T>): Promise<T> {
+  let unlock!: () => void;
+  const current = new Promise<void>(resolve => { unlock = resolve; });
+  const prev = mutexes.get(workspace) ?? Promise.resolve();
+  mutexes.set(workspace, current);
+
+  await prev;
+  try {
+    return await fn();
+  } finally {
+    unlock();
+    if (mutexes.get(workspace) === current) mutexes.delete(workspace);
+  }
+}

package/src/core/mcp/handlers/fix-finding.ts

@@ -0,0 +1,126 @@
+// src/core/mcp/handlers/fix-finding.ts
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { resolveWorkspace, assertInWorkspace } from '../workspace.ts';
+import { loadRun, checksumFile } from '../run-store.ts';
+import { withWriteLock } from '../concurrency.ts';
+import { generateFix, buildUnifiedDiff } from '../../fix/generator.ts';
+import type { ReviewEngine } from '../../../adapters/review-engine/types.ts';
+import type { GuardrailConfig } from '../../config/types.ts';
+
+export interface FixFindingResult {
+  schema_version: 1;
+  status: 'fixed' | 'reverted' | 'human_required' | 'skipped';
+  reason?: string;
+  patch?: string;
+  commitSha?: string;
+  appliedFiles: string[];
+}
+
+export async function handleFixFinding(
+  input: { run_id: string; finding_id: string; cwd?: string; dry_run?: boolean },
+  config: GuardrailConfig,
+  engine: ReviewEngine,
+): Promise<FixFindingResult> {
+  const workspace = resolveWorkspace(input.cwd);
+
+  const record = loadRun(workspace, input.run_id);
+  if (!record) {
+    throw Object.assign(
+      new Error(`run_not_found: no run with id "${input.run_id}"`),
+      { code: 'run_not_found' },
+    );
+  }
+
+  const finding = record.findings.find(f => f.id === input.finding_id);
+  if (!finding) {
+    throw Object.assign(
+      new Error(`finding_not_found: no finding with id "${input.finding_id}"`),
+      { code: 'finding_not_found' },
+    );
+  }
+
+  // Protected path check
+  if (finding.protectedPath) {
+    return { schema_version: 1, status: 'human_required', reason: 'protected_path', appliedFiles: [] };
+  }
+
+  // Validate finding.file against workspace boundary (run records could be tampered)
+  const absFile = assertInWorkspace(workspace, finding.file);
+
+  // Look up checksum under both the raw finding.file and its relative form,
+  // so the drift check works whether older runs stored absolute or relative keys.
+  const relKey = path.relative(workspace, absFile);
+  const savedChecksum = record.fileChecksums[finding.file] ?? record.fileChecksums[relKey] ?? '';
+
+  // Dry-run path: generate fix, return patch, no mutations
+  if (input.dry_run) {
+    const currentChecksum = checksumFile(absFile);
+    if (savedChecksum && currentChecksum !== savedChecksum) {
+      return { schema_version: 1, status: 'human_required', reason: 'file_changed', appliedFiles: [] };
+    }
+    const genResult = await generateFix(finding, engine, workspace);
+    if (genResult.status !== 'ok') {
+      return { schema_version: 1, status: 'human_required', reason: genResult.reason, appliedFiles: [] };
+    }
+    const patch = buildUnifiedDiff(
+      genResult.originalLines!,
+      genResult.replacementLines!,
+      finding.file,
+      genResult.startLine!,
+      { color: false }, // MCP clients parse patch text — no ANSI
+    );
+    return { schema_version: 1, status: 'skipped', reason: 'dry_run', patch, appliedFiles: [] };
+  }
+
+  // Apply path: checksum validation + fix generation run INSIDE the lock to
+  // prevent TOCTOU between two concurrent fix_finding calls on the same file.
+  return withWriteLock(workspace, async () => {
+    const currentChecksum = checksumFile(absFile);
+    if (savedChecksum && currentChecksum !== savedChecksum) {
+      return { schema_version: 1 as const, status: 'human_required' as const, reason: 'file_changed', appliedFiles: [] };
+    }
+
+    const genResult = await generateFix(finding, engine, workspace);
+    if (genResult.status !== 'ok') {
+      return { schema_version: 1 as const, status: 'human_required' as const, reason: genResult.reason, appliedFiles: [] };
+    }
+
+    const patch = buildUnifiedDiff(
+      genResult.originalLines!,
+      genResult.replacementLines!,
+      finding.file,
+      genResult.startLine!,
+      { color: false },
+    );
+
+    const originalContent = fs.readFileSync(absFile, 'utf8');
+    const allLines = originalContent.split('\n');
+    const newLines = [
+      ...allLines.slice(0, genResult.startLine! - 1),
+      ...genResult.replacementLines!,
+      ...allLines.slice(genResult.endLine!),
+    ];
+
+    const tmpFile = absFile + '.guardrail.tmp';
+    fs.writeFileSync(tmpFile, newLines.join('\n'), 'utf8');
+    fs.renameSync(tmpFile, absFile);
+
+    // Test verification
+    if (config.testCommand) {
+      const { spawnSync } = await import('node:child_process');
+      const testResult = spawnSync('/bin/sh', ['-c', config.testCommand], {
+        cwd: workspace,
+        shell: false,
+        timeout: 120_000,
+        encoding: 'utf8',
+      });
+      if (testResult.status !== 0) {
+        fs.writeFileSync(absFile, originalContent, 'utf8');
+        return { schema_version: 1 as const, status: 'reverted' as const, patch, appliedFiles: [] };
+      }
+    }
+
+    return { schema_version: 1 as const, status: 'fixed' as const, patch, appliedFiles: [finding.file] };
+  });
+}

package/src/core/mcp/handlers/get-capabilities.ts

@@ -0,0 +1,62 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as child_process from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { resolveWorkspace } from '../workspace.ts';
+import type { GuardrailConfig, StaticRuleReference } from '../../config/types.ts';
+
+export interface CapabilitiesResult {
+  schema_version: 1;
+  adapter: string;
+  enabledRules: string[];
+  writeable: boolean;
+  gitAvailable: boolean;
+  testCommandConfigured: boolean;
+  guardrailVersion: string;
+}
+
+function readVersion(): string {
+  try {
+    const pkgPath = path.join(path.dirname(fileURLToPath(import.meta.url)), '../../../../package.json');
+    return (JSON.parse(fs.readFileSync(pkgPath, 'utf8')) as { version: string }).version;
+  } catch {
+    return 'unknown';
+  }
+}
+
+function isGitAvailable(workspace: string): boolean {
+  try {
+    // Safe: no user input, static arguments only
+    child_process.execFileSync('git', ['rev-parse', '--git-dir'], {
+      cwd: workspace,
+      stdio: 'ignore',
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function extractRuleName(rule: StaticRuleReference): string {
+  return typeof rule === 'string' ? rule : rule.adapter;
+}
+
+export async function handleGetCapabilities(
+  input: { cwd?: string },
+  config: GuardrailConfig,
+  adapterName: string,
+): Promise<CapabilitiesResult> {
+  const workspace = resolveWorkspace(input.cwd);
+  const staticRules = config.staticRules ?? [];
+  const enabledRules = staticRules.map(extractRuleName);
+
+  return {
+    schema_version: 1,
+    adapter: adapterName,
+    enabledRules,
+    writeable: true,
+    gitAvailable: isGitAvailable(workspace),
+    testCommandConfigured: !!config.testCommand,
+    guardrailVersion: readVersion(),
+  };
+}

package/src/core/mcp/handlers/get-findings.ts

@@ -0,0 +1,36 @@
+import { resolveWorkspace } from '../workspace.ts';
+import { loadRun } from '../run-store.ts';
+import type { Finding, Severity } from '../../findings/types.ts';
+
+export interface GetFindingsResult {
+  schema_version: 1;
+  run_id: string;
+  findings: Finding[];
+  cachedAt: string;
+}
+
+// Severity order: index 0 = highest priority
+const SEVERITY_ORDER = ['critical', 'warning', 'note'] as const;
+
+export async function handleGetFindings(input: {
+  run_id: string;
+  severity?: Severity;
+  cwd?: string;
+}): Promise<GetFindingsResult> {
+  const workspace = resolveWorkspace(input.cwd);
+  const record = loadRun(workspace, input.run_id);
+  if (!record) {
+    throw Object.assign(
+      new Error(`run_not_found: no run with id "${input.run_id}"`),
+      { code: 'run_not_found' }
+    );
+  }
+
+  let findings = record.findings;
+  if (input.severity) {
+    const minIdx = SEVERITY_ORDER.indexOf(input.severity);
+    findings = findings.filter(f => SEVERITY_ORDER.indexOf(f.severity) <= minIdx);
+  }
+
+  return { schema_version: 1, run_id: input.run_id, findings, cachedAt: record.createdAt };
+}