feat(recipes): catalog payload carries source / body / shadows (Tracer 4 of 6)

Extends QueryRecipeCatalogEntry with three new additive fields:

- body — full Markdown body of sibling <id>.md (description = first non-empty line; body = long-form 'when to use' / 'follow-up SQL' content)
- source — 'bundled' | 'project' (provenance discriminator)
- shadows — true ONLY on project entries that override a bundled recipe of the same id (per Q-E settled — agents check this at session start to know when a recipe behaves differently from the documented bundled version)

All additive: existing callers that destructure {id, description, sql, actions?} keep working unchanged.

New helper: getQueryRecipeCatalogEntry(id) — same shape as listQueryRecipeCatalog entries, for one id (undefined for unknown). Used by codemap://recipes/{id} MCP resource so the per-id payload includes the same provenance fields the full catalog has.

MCP server changes:
- codemap://recipes/{id} payload now includes body / source / shadows (replaced the inline {id, description, sql, actions?} construction with JSON.stringify(getQueryRecipeCatalogEntry(id)))
- codemap://recipes list-callback uses listQueryRecipeCatalog() (drops dependency on the legacy QUERY_RECIPES Proxy access)
- Resource description updated to 'Single recipe by id: {id, description, body?, sql, actions?, source, shadows?}'
- Removed unused listQueryRecipeIds + QUERY_RECIPES imports

5 new shim tests: bundled.source, bundled.body presence, project.source, project.shadows=true on override, getQueryRecipeCatalogEntry parity + unknown-id-undefined.

Tracer 5 next: YAML frontmatter parser for project-recipe actions + load-time DML/DDL lexical check.

Author: SutuSebastian

src/application/mcp-server.ts

@@ -20,10 +20,9 @@ import { buildContextEnvelope } from "../cli/cmd-context";
 import { computeValidateRows } from "../cli/cmd-validate";
 import {
   getQueryRecipeActions,
+  getQueryRecipeCatalogEntry,
   getQueryRecipeSql,
   listQueryRecipeCatalog,
-  listQueryRecipeIds,
-  QUERY_RECIPES,
 } from "../cli/query-recipes";
 import { loadUserConfig, resolveCodemapConfig } from "../config";
 import {
@@ -605,23 +604,26 @@ function registerResources(server: McpServer): void {
     },
   );
 
-  // codemap://recipes/{id} — one recipe (template form)
+  // codemap://recipes/{id} — one recipe (template form). Per Tracer 4 the
+  // payload includes `body` / `source` / `shadows` from the catalog entry —
+  // session-start agents check `shadows` to know when a project recipe
+  // overrides the documented bundled version.
   const oneRecipeCache = new Map<string, string>();
   server.registerResource(
     "recipe",
     new ResourceTemplate("codemap://recipes/{id}", {
       list: () => ({
-        resources: listQueryRecipeIds().map((id) => ({
-          uri: `codemap://recipes/${id}`,
-          name: id,
-          description: QUERY_RECIPES[id]!.description,
+        resources: listQueryRecipeCatalog().map((entry) => ({
+          uri: `codemap://recipes/${entry.id}`,
+          name: entry.id,
+          description: entry.description,
           mimeType: "application/json",
         })),
       }),
     }),
     {
       description:
-        "Single recipe by id: {id, description, sql, actions?}. Replaces `codemap query --print-sql <id>` for agents.",
+        "Single recipe by id: {id, description, body?, sql, actions?, source, shadows?}. Replaces `codemap query --print-sql <id>` for agents; carries provenance fields so agents see when a project-local recipe overrides a bundled one.",
       mimeType: "application/json",
     },
     (uri, variables) => {
@@ -635,20 +637,15 @@ function registerResources(server: McpServer): void {
           ],
         };
       }
-      const meta = QUERY_RECIPES[id];
-      if (meta === undefined) {
+      const entry = getQueryRecipeCatalogEntry(id);
+      if (entry === undefined) {
         // Resources can't return structured errors the way tools do; throw so
         // the SDK surfaces a JSON-RPC error to the host.
         throw new Error(
           `codemap: unknown recipe "${id}". Read codemap://recipes for the catalog.`,
         );
       }
-      const payload = JSON.stringify({
-        id,
-        description: meta.description,
-        sql: meta.sql,
-        ...(meta.actions !== undefined ? { actions: meta.actions } : {}),
-      });
+      const payload = JSON.stringify(entry);
       oneRecipeCache.set(id, payload);
       return {
         contents: [

src/cli/query-recipes.test.ts

@@ -8,6 +8,7 @@ import { initCodemap } from "../runtime";
 import {
   _resetRecipesCacheForTests,
   getQueryRecipeActions,
+  getQueryRecipeCatalogEntry,
   getQueryRecipeSql,
   listQueryRecipeCatalog,
   listQueryRecipeIds,
@@ -97,3 +98,54 @@ describe("query-recipes shim — project recipes via runtime root", () => {
     expect(ids).toContain("fan-out");
   });
 });
+
+describe("query-recipes shim — catalog source / shadows / body fields (Tracer 4)", () => {
+  it("bundled entries carry source: 'bundled' and no shadows flag", () => {
+    const fanOut = listQueryRecipeCatalog().find((c) => c.id === "fan-out");
+    expect(fanOut?.source).toBe("bundled");
+    expect(fanOut?.shadows).toBeUndefined();
+  });
+
+  it("bundled entries carry body when sibling .md exists", () => {
+    const fanOut = listQueryRecipeCatalog().find((c) => c.id === "fan-out");
+    expect(fanOut?.body).toBeDefined();
+    expect(fanOut?.body).toContain("Top 10 files by dependency fan-out");
+  });
+
+  it("project entries carry source: 'project' (no bundled clash → no shadows)", () => {
+    const recipesDir = join(projectRoot, ".codemap", "recipes");
+    mkdirSync(recipesDir, { recursive: true });
+    writeFileSync(join(recipesDir, "internal-fizz.sql"), "SELECT 1\n");
+    _resetRecipesCacheForTests();
+
+    const fizz = listQueryRecipeCatalog().find((c) => c.id === "internal-fizz");
+    expect(fizz?.source).toBe("project");
+    expect(fizz?.shadows).toBeUndefined();
+  });
+
+  it("project recipe shadowing bundled carries shadows: true", () => {
+    const recipesDir = join(projectRoot, ".codemap", "recipes");
+    mkdirSync(recipesDir, { recursive: true });
+    writeFileSync(
+      join(recipesDir, "fan-out.sql"),
+      "SELECT 'project override' AS marker\n",
+    );
+    _resetRecipesCacheForTests();
+
+    const fanOut = listQueryRecipeCatalog().find((c) => c.id === "fan-out");
+    expect(fanOut?.source).toBe("project");
+    expect(fanOut?.shadows).toBe(true);
+  });
+});
+
+describe("getQueryRecipeCatalogEntry (single-id lookup)", () => {
+  it("returns the same entry shape as listQueryRecipeCatalog for known id", () => {
+    const fromList = listQueryRecipeCatalog().find((c) => c.id === "fan-out");
+    const fromGet = getQueryRecipeCatalogEntry("fan-out");
+    expect(fromGet).toEqual(fromList);
+  });
+
+  it("returns undefined for unknown id", () => {
+    expect(getQueryRecipeCatalogEntry("no-such-recipe")).toBeUndefined();
+  });
+});

src/cli/query-recipes.ts

@@ -10,18 +10,27 @@ export type { RecipeAction } from "../application/recipes-loader";
 import type { RecipeAction } from "../application/recipes-loader";
 
 /**
- * One bundled recipe: id, human description, SQL, and optional per-row actions
- * (canonical source for CLI, `--recipes-json`, and the JSON output enrichment).
+ * Catalog entry surfaced to `--recipes-json`, the `codemap://recipes` MCP
+ * resource, and the per-id `codemap://recipes/{id}` lookup. Backwards-compat
+ * shape with three extensions added in Tracer 4:
  *
- * NOTE: Kept for backwards-compat with callers that destructure the legacy
- * shape. `LoadedRecipe` (from `application/recipes-loader`) is the new
- * canonical type — has `body`, `source`, `shadows` in addition.
+ * - **`body`** — full Markdown body of the sibling `<id>.md` (when present);
+ *   description is the first non-empty line of that body.
+ * - **`source`** — `"bundled"` (ships with the npm package) or `"project"`
+ *   (loaded from `<projectRoot>/.codemap/recipes/`).
+ * - **`shadows`** — `true` when a project recipe overrides a bundled recipe
+ *   of the same id (per plan §9 Q-E — agents read this at session start to
+ *   know when a recipe behaves differently from the documented bundled
+ *   version). Absent / `false` for non-shadowing entries.
  */
 export interface QueryRecipeCatalogEntry {
   id: string;
   description: string;
+  body?: string;
   sql: string;
   actions?: RecipeAction[];
+  source: "bundled" | "project";
+  shadows?: boolean;
 }
 
 /**
@@ -206,22 +215,38 @@ export function listQueryRecipeIds(): string[] {
 }
 
 /**
- * Full catalog for **`codemap query --recipes-json`**.
- *
- * Tracer 2 returns the legacy shape (id / description / sql / actions?).
- * Tracer 4 will extend the catalog payload to include `body`, `source`,
- * and `shadows` from the {@link LoadedRecipe} shape.
+ * Full catalog for **`codemap query --recipes-json`** and the
+ * `codemap://recipes` MCP resource. Per Tracer 4, includes `body`,
+ * `source`, and `shadows` fields on each entry.
  */
 export function listQueryRecipeCatalog(): QueryRecipeCatalogEntry[] {
-  return getRegistry().map((r) => {
-    const entry: QueryRecipeCatalogEntry = {
-      id: r.id,
-      description: r.description ?? r.id,
-      sql: r.sql,
-    };
-    if (r.actions !== undefined) entry.actions = r.actions;
-    return entry;
-  });
+  return getRegistry().map((r) => buildCatalogEntry(r));
+}
+
+/**
+ * Single-entry lookup for the `codemap://recipes/{id}` MCP resource and any
+ * future `--recipe-json <id>` CLI shape. Returns `undefined` for unknown
+ * ids; otherwise the same {@link QueryRecipeCatalogEntry} shape as the
+ * full-catalog listing.
+ */
+export function getQueryRecipeCatalogEntry(
+  id: string,
+): QueryRecipeCatalogEntry | undefined {
+  const recipe = getRegistry().find((r) => r.id === id);
+  return recipe === undefined ? undefined : buildCatalogEntry(recipe);
+}
+
+function buildCatalogEntry(r: LoadedRecipe): QueryRecipeCatalogEntry {
+  const entry: QueryRecipeCatalogEntry = {
+    id: r.id,
+    description: r.description ?? r.id,
+    sql: r.sql,
+    source: r.source,
+  };
+  if (r.body !== undefined) entry.body = r.body;
+  if (r.actions !== undefined) entry.actions = r.actions;
+  if (r.shadows) entry.shadows = true;
+  return entry;
 }
 
 /**