feat(mcp): add ingest_coverage and query baseline parity

Close the last two agent-relevant transport gaps: MCP/HTTP can load coverage artifacts and diff queries against saved baselines in one call, matching CLI ingest-coverage and query --baseline.

Author: SutuSebastian

docs/plans/ingest-coverage-mcp.md

@@ -0,0 +1,37 @@
+# Ingest coverage — MCP/HTTP parity — plan
+
+> **Status:** open · **Priority:** P1 (transport parity) · **Effort:** S (~1 day)
+>
+> **Motivator:** Coverage-aware recipes (`worst-covered-exports`, `files-by-coverage`, `untested-and-dead`) need `coverage` table rows. CLI has `codemap ingest-coverage`; MCP-only agents cannot load artifacts without shelling out.
+>
+> **Roadmap:** transport parity (agent-relevant core)
+
+---
+
+## Pre-locked decisions
+
+| #   | Decision                                                                                               | Source                     |
+| --- | ------------------------------------------------------------------------------------------------------ | -------------------------- |
+| I.1 | **Thin transport twin** — same `IngestResult` envelope as CLI `--json`; no new semantics.              | Transport-agnostic engines |
+| I.2 | **Lift orchestration** to `application/ingest-coverage-run.ts`; CLI `cmd-ingest-coverage.ts` calls it. | `architecture.md` layering |
+| I.3 | **Tool name** `ingest_coverage` (snake_case MCP); HTTP `POST /tool/ingest_coverage`.                   | MCP convention             |
+| I.4 | **Args:** `path` (required), `runtime` (optional, V8 dir), mirrors CLI flags.                          | CLI parity                 |
+| I.5 | **No human text mode** on MCP — JSON only (infra output format excluded).                              | Agent transport            |
+
+---
+
+## Implementation steps
+
+1. Extract `runIngestCoverage` + path resolvers from `cmd-ingest-coverage.ts` → `ingest-coverage-run.ts`
+2. `handleIngestCoverage` in `tool-handlers.ts`
+3. Register MCP tool + HTTP dispatch + `MCP_TOOL_NAMES` allowlist
+4. Tests: `ingest-coverage-run.test.ts` (minimal), `tool-handlers.test.ts` smoke
+5. Update `cmd-mcp.ts` help, `mcp-instructions.md`, `architecture.md` apply/coverage wiring
+
+---
+
+## Acceptance
+
+- [x] MCP `ingest_coverage` ingests Istanbul fixture → `coverage` rows queryable
+- [x] CLI `ingest-coverage` unchanged behavior (refactor only)
+- [x] HTTP `POST /tool/ingest_coverage` returns same JSON as CLI `--json`

docs/plans/query-baseline-mcp-parity.md

@@ -0,0 +1,38 @@
+# Query baseline compare — MCP/HTTP parity — plan
+
+> **Status:** open · **Priority:** P1 (transport parity) · **Effort:** S (~1 day)
+>
+> **Motivator:** CLI `codemap query --baseline=<name>` diffs current rows vs `query_baselines` in one call. MCP has `save_baseline` / `list_baselines` / `drop_baseline` but not inline compare on `query` / `query_recipe`.
+>
+> **Roadmap:** transport parity (agent-relevant core)
+
+---
+
+## Pre-locked decisions
+
+| #   | Decision                                                                                                                       | Source                           |
+| --- | ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------- |
+| B.1 | **Extend existing tools** — add optional `baseline: string` to `query` and `query_recipe`; no new tool.                        | Moat A — recipes stay the API    |
+| B.2 | **Same envelope** as CLI `--json --baseline`: `{baseline, current_row_count, added, removed}`; `summary: true` → count fields. | `cmd-query.ts` `runBaselineDiff` |
+| B.3 | **Recipe `actions` on `added` rows only** — same as CLI.                                                                       | Apply discover loop              |
+| B.4 | **Reject combos** — `baseline` + `format` (sarif/annotations/mermaid/diff/diff-json) or `group_by`; mirrors CLI parser.        | Output-shape contract            |
+| B.5 | **Engine** — `application/query-baseline.ts` (`compareQueryBaseline`); shared by MCP handlers (CLI refactor optional later).   | Layering                         |
+
+---
+
+## Implementation steps
+
+1. Add `compareQueryBaseline` in `application/query-baseline.ts` (uses `diffRows`, `getQueryBaseline`, `filterRowsByChangedFiles`)
+2. Wire `baseline?: string` into `queryArgsSchema` / `queryRecipeArgsSchema`
+3. Early branch in `handleQuery` / `handleQueryRecipe` before `executeQuery` / formatted paths
+4. Tests: `query-baseline.test.ts` + `tool-handlers.test.ts` baseline diff case
+5. Update MCP tool descriptions + `templates/agent-content/mcp-instructions.md`
+
+---
+
+## Acceptance
+
+- [x] `query_recipe` + `baseline` + `summary` returns `{added: N, removed: N}` counts
+- [x] `query_recipe` + `baseline` returns full diff with `actions` on `added` when recipe declares them
+- [x] Missing baseline name → `{error}` envelope
+- [x] `baseline` + `format: sarif` → error (incompatible)

src/application/http-server.ts

@@ -41,6 +41,7 @@ import {
   handleAffected,
   handleContext,
   handleDropBaseline,
+  handleIngestCoverage,
   handleExplore,
   handleImpact,
   handleNode,
@@ -54,6 +55,7 @@ import {
   handleSnippet,
   handleValidate,
   impactArgsSchema,
+  ingestCoverageArgsSchema,
   nodeArgsSchema,
   traceArgsSchema,
   listBaselinesArgsSchema,
@@ -126,6 +128,7 @@ const TOOL_NAMES = [
   "save_baseline",
   "list_baselines",
   "drop_baseline",
+  "ingest_coverage",
 ] as const;
 
 /**
@@ -609,6 +612,12 @@ async function dispatchTool(
       result = handleDropBaseline(r.value);
       break;
     }
+    case "ingest_coverage": {
+      const r = validate(ingestCoverageArgsSchema, args, "ingest_coverage");
+      if (!r.ok) return writeJson(res, 400, { error: r.error }, opts.version);
+      result = await handleIngestCoverage(r.value, opts.root);
+      break;
+    }
     default: {
       // Reachable only if TOOL_NAMES gains an entry without a switch arm —
       // the route guard above catches user-typed unknown names.

src/application/ingest-coverage-run.test.ts

@@ -0,0 +1,122 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { resolveCodemapConfig } from "../config";
+import {
+  closeDb,
+  createIndexes,
+  createTables,
+  insertFile,
+  insertSymbols,
+} from "../db";
+import { initCodemap } from "../runtime";
+import { openCodemapDatabase } from "../sqlite-db";
+import {
+  resolveCoverageArtifact,
+  runIngestCoverageOnDb,
+} from "./ingest-coverage-run";
+
+let projectRoot: string;
+
+beforeEach(() => {
+  projectRoot = mkdtempSync(join(tmpdir(), "ingest-coverage-run-"));
+  initCodemap(resolveCodemapConfig(projectRoot, undefined));
+});
+
+afterEach(() => {
+  rmSync(projectRoot, { recursive: true, force: true });
+});
+
+describe("resolveCoverageArtifact", () => {
+  it("resolves istanbul file by extension", () => {
+    const file = join(projectRoot, "coverage-final.json");
+    writeFileSync(file, "{}");
+    expect(resolveCoverageArtifact(file, projectRoot)).toEqual({
+      format: "istanbul",
+      absPath: file,
+    });
+  });
+
+  it("errors when directory holds both istanbul and lcov", () => {
+    const dir = join(projectRoot, "coverage");
+    mkdirSync(dir);
+    writeFileSync(join(dir, "coverage-final.json"), "{}");
+    writeFileSync(join(dir, "lcov.info"), "TN:\n");
+    expect(() => resolveCoverageArtifact(dir, projectRoot)).toThrow(
+      /both coverage-final\.json and lcov\.info/,
+    );
+  });
+});
+
+describe("runIngestCoverageOnDb", () => {
+  it("ingests istanbul artifact into coverage table", async () => {
+    const db = openCodemapDatabase(":memory:");
+    try {
+      createTables(db);
+      createIndexes(db);
+      insertFile(db, {
+        path: "src/lib/cache.ts",
+        content_hash: "h1",
+        size: 1,
+        line_count: 100,
+        language: "typescript",
+        last_modified: 0,
+        indexed_at: 0,
+      });
+      insertSymbols(db, [
+        {
+          file_path: "src/lib/cache.ts",
+          name: "get",
+          kind: "function",
+          line_start: 9,
+          line_end: 15,
+          signature: "get(): void",
+          is_exported: 1,
+          is_default_export: 0,
+          members: null,
+          doc_comment: null,
+          value: null,
+          parent_name: null,
+          visibility: null,
+        },
+      ]);
+
+      const coverageDir = join(projectRoot, "coverage");
+      mkdirSync(coverageDir);
+      const artifact = join(coverageDir, "coverage-final.json");
+      writeFileSync(
+        artifact,
+        JSON.stringify({
+          [`${projectRoot}/src/lib/cache.ts`]: {
+            path: `${projectRoot}/src/lib/cache.ts`,
+            statementMap: {
+              "0": {
+                start: { line: 10, column: 0 },
+                end: { line: 10, column: 1 },
+              },
+            },
+            s: { "0": 1 },
+          },
+        }),
+      );
+
+      const outcome = await runIngestCoverageOnDb(db, {
+        projectRoot,
+        path: "coverage/coverage-final.json",
+      });
+      expect(outcome.ok).toBe(true);
+      if (!outcome.ok) return;
+      expect(outcome.result.format).toBe("istanbul");
+      expect(outcome.result.ingested.symbols).toBe(1);
+
+      const rows = db.query("SELECT name FROM coverage").all() as Array<{
+        name: string;
+      }>;
+      expect(rows.map((r) => r.name)).toEqual(["get"]);
+    } finally {
+      closeDb(db);
+    }
+  });
+});