feat(mcp): codemap://files/{path} + codemap://symbols/{name} resources (#67)

§ 1.8 from research note. Two new MCP / HTTP resources reusing
existing substrate (no schema bump):

codemap://files/{path}
- Per-file roll-up: {path, language, line_count, symbols, imports,
  exports, coverage}.
- imports.specifiers parsed inline (callers don't need JSON.parse).
- coverage is {measured_symbols, avg_coverage_pct, per_symbol} when
  ingested, else null.
- URI-encode the path; query is fail-closed (returns undefined when
  path not in index — distinguishes "unknown URI" from "valid URI,
  empty roll-up").

codemap://symbols/{name}
- Returns {matches, disambiguation?} envelope (reuses
  findSymbolsByName + buildShowResult from show-engine — same shape
  as `show <name>` per PR #39).
- Optional ?in=<path-prefix> query parameter mirrors `show --in`
  (directory prefix or exact file). Uses the WHATWG URL parser.
- Empty name → undefined; multi-match → disambiguation block.

Caching policy:
- Catalog-style resources (recipes, schema, skill) lazy-cache (existing
  pattern).
- Data-shaped resources (files, symbols) read LIVE every call — no
  caching. Index can change between requests under --watch; caching
  would silently serve stale data.

Both available over MCP read_resource AND HTTP GET /resources/
{encoded-uri} via the existing dispatcher (no new transport plumbing
needed; readResource() switch extended).

Tests:
- 9 new tests in resource-handlers.test.ts cover both endpoints +
  listResources advertising. Pattern mirrors mcp-server.test.ts (use
  initCodemap + resolveCodemapConfig + tmpdir fixture).
- bun run check passes (format, lint, typecheck, all 23 golden
  queries).

Rule 10 lockstep: both templates/agents/ and .agents/ codemap rule +
skill updated:
- Rule body — Resources bullet extended with new URIs + caching policy.
- Skill body — per-URI bullet for each new resource with shape spec.

Patch changeset: pre-v1; additive resources; no schema bump; no
breaking change to existing resource consumers.

Files: 7 changed (1 src impl, 1 src test, 4 lockstep, 1 changeset).

Author: SutuSebastian

.agents/rules/codemap.md

@@ -65,7 +65,7 @@ Validation: SQL is rejected at load time if it starts with DML/DDL (DELETE/DROP/
 - **Tools:** `query` / `query_batch` / `query_recipe` / `audit` / `save_baseline` / `list_baselines` / `drop_baseline` / `context` / `validate` / `show` / `snippet` / `impact`. Snake_case keys (Codemap convention matching MCP spec examples + reference servers — spec is convention-agnostic; CLI stays kebab).
 - **`query_batch` (MCP-only):** N statements in one round-trip. Items are `string | {sql, summary?, changed_since?, group_by?}` — string form inherits batch-wide flag defaults, object form overrides on a per-key basis. Per-statement errors are isolated.
 - **`save_baseline` (polymorphic):** one tool, `{name, sql? | recipe?}` with runtime exclusivity check (mirrors the CLI's single `--save-baseline=<name>` verb).
-- **Resources:** `codemap://recipes` (catalog), `codemap://recipes/{id}` (one recipe), `codemap://schema` (live DDL from `sqlite_schema`), `codemap://skill` (bundled SKILL.md text). Lazy-cached on first `read_resource`.
+- **Resources:** `codemap://recipes` (catalog), `codemap://recipes/{id}` (one recipe), `codemap://schema` (live DDL from `sqlite_schema`), `codemap://skill` (bundled SKILL.md text), `codemap://files/{path}` (per-file roll-up: symbols, imports, exports, coverage), `codemap://symbols/{name}` (symbol lookup with `{matches, disambiguation?}` envelope; `?in=<path-prefix>` filter mirrors `show --in`). Catalog resources lazy-cache on first `read_resource`; `files/` and `symbols/` read live every call (no caching) since the index can change between requests under `--watch`.
 - **Output shape uniformity:** every tool returns the JSON envelope its CLI counterpart's `--json` would print — no re-mapping. Schema additions to the CLI envelope propagate to MCP automatically.
 
 For developing the MCP server itself: `src/cli/cmd-mcp.ts` (CLI shell) + `src/application/mcp-server.ts` (engine). See [`docs/architecture.md` § MCP wiring](../../docs/architecture.md#cli-usage).

.agents/skills/codemap/SKILL.md

@@ -81,6 +81,8 @@ Each emitted delta carries its own `base` metadata so mixed-baseline audits are
 - **`codemap://recipes/{id}`** — single recipe `{id, description, body?, sql, actions?, source, shadows?}`. Replaces `--print-sql <id>`.
 - **`codemap://schema`** — DDL of every table in `.codemap/index.db` (queried live from `sqlite_schema`).
 - **`codemap://skill`** — full text of bundled `templates/agents/skills/codemap/SKILL.md`. Agents that don't preload the skill at session start can fetch it here.
+- **`codemap://files/{path}`** — per-file roll-up. Returns `{path, language, line_count, symbols, imports, exports, coverage}` where `imports.specifiers` is parsed JSON and `coverage` is `{measured_symbols, avg_coverage_pct, per_symbol}` or `null` when the file has no measured coverage. URI-encode the path. Reads live (no caching).
+- **`codemap://symbols/{name}`** — symbol lookup by exact name. Returns `{matches, disambiguation?}` envelope (same shape as `show <name>` per PR #39). Optional `?in=<path-prefix>` query parameter mirrors `show --in <path>` (directory prefix or exact file). Reads live.
 
 **Implementation:** `src/cli/cmd-mcp.ts` (CLI shell — argv + lifecycle) + `src/application/mcp-server.ts` (transport — SDK glue). Tool bodies live in `src/application/tool-handlers.ts` (pure transport-agnostic — same handlers `codemap serve` dispatches over HTTP); resource fetchers in `src/application/resource-handlers.ts`. Mirrors the `cmd-audit.ts ↔ audit-engine.ts` seam. `--changed-since` git lookups are memoised per `(root, ref)` pair across batch items so a `query_batch` of N items sharing the same ref does one git invocation, not N.
 

.changeset/mcp-resources-files-symbols.md

@@ -0,0 +1,18 @@
+---
+"@stainless-code/codemap": patch
+---
+
+feat(mcp): add `codemap://files/{path}` + `codemap://symbols/{name}` resources (research note § 1.8)
+
+Two new MCP / HTTP resources for direct agent reads — saves the recipe-compose round-trip when the agent just wants "everything about this file" or "where is this symbol?".
+
+- **`codemap://files/{path}`** — per-file roll-up. Returns `{path, language, line_count, symbols, imports, exports, coverage}`. `imports.specifiers` parsed inline (callers don't have to JSON.parse). `coverage` is `{measured_symbols, avg_coverage_pct, per_symbol}` when coverage was ingested, else `null`. URI-encode the path.
+- **`codemap://symbols/{name}`** — symbol lookup by exact name. Returns `{matches, disambiguation?}` envelope (same shape as the `show` verb per PR #39). Optional `?in=<path-prefix>` query parameter mirrors `show --in <path>` (directory prefix or exact file).
+
+Both reuse existing infrastructure (no schema bump): `codemap://files/` queries the existing tables; `codemap://symbols/` reuses `findSymbolsByName` + `buildShowResult` from `application/show-engine.ts`.
+
+**Caching policy:** catalog-style resources (`recipes`, `schema`, `skill`) lazy-cache as before. Data-shaped resources (`files/`, `symbols/`) read live every call — no caching, since the index can change between requests under `--watch`.
+
+Both available over MCP `read_resource` and HTTP `GET /resources/{encoded-uri}` via the existing dispatcher (no new transport plumbing).
+
+Agent rule + skill lockstep updated per `docs/README.md` Rule 10 — both `templates/agents/` and `.agents/` codemap rule + skill mention the new resource templates + caching policy.

src/application/resource-handlers.test.ts

@@ -0,0 +1,131 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { resolveCodemapConfig } from "../config";
+import { closeDb, createTables, openDb } from "../db";
+import { initCodemap } from "../runtime";
+import {
+  _resetResourceCachesForTests,
+  listResources,
+  readResource,
+} from "./resource-handlers";
+
+let benchDir: string;
+
+beforeEach(() => {
+  benchDir = mkdtempSync(join(tmpdir(), "codemap-resource-test-"));
+  mkdirSync(join(benchDir, "src"), { recursive: true });
+  initCodemap(resolveCodemapConfig(benchDir, undefined));
+  _resetResourceCachesForTests();
+
+  const db = openDb();
+  try {
+    createTables(db);
+    db.run(
+      `INSERT INTO files (path, content_hash, size, line_count, language, last_modified, indexed_at)
+       VALUES
+         ('src/foo.ts', 'h1', 100, 30, 'ts', 1, 1),
+         ('src/bar.ts', 'h2', 80, 20, 'ts', 1, 1),
+         ('src/legacy/foo.ts', 'h3', 50, 15, 'ts', 1, 1)`,
+    );
+    db.run(
+      `INSERT INTO symbols (file_path, name, kind, line_start, line_end, signature, is_exported, is_default_export)
+       VALUES
+         ('src/foo.ts', 'foo', 'function', 5, 15, 'function foo(): void', 1, 0),
+         ('src/foo.ts', 'helper', 'function', 20, 25, 'function helper(): string', 0, 0),
+         ('src/legacy/foo.ts', 'foo', 'function', 1, 50, 'function foo(arg: string): number', 0, 0)`,
+    );
+    db.run(
+      `INSERT INTO imports (file_path, source, resolved_path, specifiers, is_type_only, line_number)
+       VALUES ('src/foo.ts', './bar', 'src/bar.ts', '["bar"]', 0, 1)`,
+    );
+    db.run(
+      `INSERT INTO exports (file_path, name, kind, is_default)
+       VALUES ('src/foo.ts', 'foo', 'value', 0)`,
+    );
+  } finally {
+    closeDb(db);
+  }
+});
+
+afterEach(() => {
+  rmSync(benchDir, { recursive: true, force: true });
+  _resetResourceCachesForTests();
+});
+
+describe("readResource — codemap://files/{path}", () => {
+  it("returns per-file roll-up with symbols / imports / exports", () => {
+    const r = readResource("codemap://files/src/foo.ts");
+    expect(r).toBeDefined();
+    expect(r?.mimeType).toBe("application/json");
+    const payload = JSON.parse(r!.text);
+    expect(payload.path).toBe("src/foo.ts");
+    expect(payload.language).toBe("ts");
+    expect(payload.symbols).toHaveLength(2);
+    expect(payload.imports).toHaveLength(1);
+    expect(payload.imports[0].specifiers).toEqual(["bar"]);
+    expect(payload.exports).toHaveLength(1);
+    expect(payload.coverage).toBeNull();
+  });
+
+  it("returns undefined when path not in the index", () => {
+    expect(readResource("codemap://files/no-such-file.ts")).toBeUndefined();
+  });
+
+  it("URI-decodes the path", () => {
+    const r = readResource("codemap://files/src%2Flegacy%2Ffoo.ts");
+    expect(r).toBeDefined();
+    expect(JSON.parse(r!.text).path).toBe("src/legacy/foo.ts");
+  });
+});
+
+describe("readResource — codemap://symbols/{name}", () => {
+  it("returns single match envelope when the name is unique", () => {
+    const r = readResource("codemap://symbols/helper");
+    expect(r).toBeDefined();
+    const payload = JSON.parse(r!.text);
+    expect(payload.matches).toHaveLength(1);
+    expect(payload.matches[0].name).toBe("helper");
+    expect(payload.disambiguation).toBeUndefined();
+  });
+
+  it("returns disambiguation envelope on multi-match", () => {
+    const r = readResource("codemap://symbols/foo");
+    expect(r).toBeDefined();
+    const payload = JSON.parse(r!.text);
+    expect(payload.matches).toHaveLength(2);
+    expect(payload.disambiguation).toBeDefined();
+    expect(payload.disambiguation.n).toBe(2);
+    expect(payload.disambiguation.files).toContain("src/foo.ts");
+    expect(payload.disambiguation.files).toContain("src/legacy/foo.ts");
+  });
+
+  it("filters by ?in=<path-prefix>", () => {
+    const r = readResource("codemap://symbols/foo?in=src/legacy");
+    expect(r).toBeDefined();
+    const payload = JSON.parse(r!.text);
+    expect(payload.matches).toHaveLength(1);
+    expect(payload.matches[0].file_path).toBe("src/legacy/foo.ts");
+  });
+
+  it("returns empty matches for unknown name", () => {
+    const r = readResource("codemap://symbols/no-such-symbol");
+    expect(r).toBeDefined();
+    expect(JSON.parse(r!.text).matches).toEqual([]);
+  });
+
+  it("returns undefined when name is empty", () => {
+    expect(readResource("codemap://symbols/")).toBeUndefined();
+  });
+});
+
+describe("listResources", () => {
+  it("advertises the new files / symbols templates", () => {
+    const list = listResources();
+    const uris = list.map((r) => r.uri);
+    expect(uris).toContain("codemap://files/{path}");
+    expect(uris).toContain("codemap://symbols/{name}");
+  });
+});