feat(recipes): loader scaffold + merge logic (Tracer 1 of 6)

Pure transport-agnostic loader in src/application/recipes-loader.ts (mirrors the cmd-* ↔ *-engine seam from PR #33). Scope per plan §8 Tracer 1:

- LoadedRecipe interface (canonical shape; bundled + project share it)
- RecipeAction interface lifted from cli/query-recipes.ts (will become the canonical home; query-recipes becomes a shim in Tracer 2)
- readRecipesFromDir(dir, source) — reads <id>.sql, pairs with optional <id>.md (description = first non-empty line, body = full text). Returns [] for missing/non-directory paths (project-recipes case where .codemap/recipes/ is absent — not an error). Throws on empty SQL with recipe-aware message
- mergeRecipes(bundled, project) — project wins on id collision; sets shadows: true on overriding entries (Q-E settled). Output sorted by id (deterministic catalog order)
- loadAllRecipes({bundledDir, projectDir}) — Tracer 1 wires bundled only; projectDir argument accepted but stubbed (returns []). Tracer 3 plugs project loader

15 unit tests cover: missing dir, non-.sql ignore, sql-only loading, sibling-md pairing, heading-strip in description, deterministic id order, empty-sql rejection, comments-then-sql happy path, non-directory passthrough, all 4 merge cases (project-only / bundled-only / shadow / no-overlap), Tracer 1 stub behavior.

Layer note: query-recipes.ts (cli/) still owns QUERY_RECIPES + getQueryRecipeSql / getQueryRecipeActions / listQueryRecipeCatalog / listQueryRecipeIds. Tracer 2 migrates them to call into this loader.

Author: SutuSebastian

src/application/recipes-loader.test.ts

@@ -0,0 +1,194 @@
+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 {
+  loadAllRecipes,
+  mergeRecipes,
+  readRecipesFromDir,
+} from "./recipes-loader";
+import type { LoadedRecipe } from "./recipes-loader";
+
+let workDir: string;
+
+beforeEach(() => {
+  workDir = mkdtempSync(join(tmpdir(), "recipes-loader-"));
+});
+
+afterEach(() => {
+  rmSync(workDir, { recursive: true, force: true });
+});
+
+function makeRecipeDir(name: string): string {
+  const dir = join(workDir, name);
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+describe("readRecipesFromDir", () => {
+  it("returns [] when directory doesn't exist (project-recipes case)", () => {
+    expect(readRecipesFromDir(join(workDir, "missing"), "project")).toEqual([]);
+  });
+
+  it("ignores non-.sql files", () => {
+    const dir = makeRecipeDir("ignore-noise");
+    writeFileSync(join(dir, "fan-out.sql"), "SELECT 1\n");
+    writeFileSync(join(dir, "README.md"), "# unrelated\n");
+    writeFileSync(join(dir, ".DS_Store"), "");
+    const r = readRecipesFromDir(dir, "bundled");
+    expect(r.map((x) => x.id)).toEqual(["fan-out"]);
+  });
+
+  it("loads SQL only — no sibling .md → description/body/actions undefined", () => {
+    const dir = makeRecipeDir("sql-only");
+    writeFileSync(join(dir, "fan-out.sql"), "SELECT 1\n");
+    const r = readRecipesFromDir(dir, "bundled");
+    expect(r).toHaveLength(1);
+    const recipe = r[0]!;
+    expect(recipe).toMatchObject({
+      id: "fan-out",
+      sql: "SELECT 1\n",
+      description: undefined,
+      body: undefined,
+      actions: undefined,
+      source: "bundled",
+      shadows: false,
+    });
+  });
+
+  it("pairs sibling .md — description = first non-empty line, body = full text", () => {
+    const dir = makeRecipeDir("with-md");
+    writeFileSync(join(dir, "fan-out.sql"), "SELECT 1\n");
+    writeFileSync(
+      join(dir, "fan-out.md"),
+      "# Fan-out\n\nWhen to use: …\n\nFollow-up SQL: …\n",
+    );
+    const r = readRecipesFromDir(dir, "bundled");
+    expect(r[0]!.description).toBe("Fan-out");
+    expect(r[0]!.body).toContain("When to use");
+  });
+
+  it("description strips leading `# ` heading marker", () => {
+    const dir = makeRecipeDir("md-headers");
+    writeFileSync(join(dir, "x.sql"), "SELECT 1\n");
+    writeFileSync(join(dir, "x.md"), "## Heading two\n\ncontent\n");
+    expect(readRecipesFromDir(dir, "bundled")[0]!.description).toBe(
+      "Heading two",
+    );
+  });
+
+  it("returns recipes sorted by id (deterministic order)", () => {
+    const dir = makeRecipeDir("ordering");
+    writeFileSync(join(dir, "zebra.sql"), "SELECT 1\n");
+    writeFileSync(join(dir, "alpha.sql"), "SELECT 2\n");
+    writeFileSync(join(dir, "monkey.sql"), "SELECT 3\n");
+    const r = readRecipesFromDir(dir, "project");
+    expect(r.map((x) => x.id)).toEqual(["alpha", "monkey", "zebra"]);
+  });
+
+  it("throws on empty SQL (just whitespace + comments)", () => {
+    const dir = makeRecipeDir("empty");
+    writeFileSync(
+      join(dir, "blank.sql"),
+      "-- this is just a comment\n   \n-- and another\n",
+    );
+    expect(() => readRecipesFromDir(dir, "project")).toThrow(/empty/);
+  });
+
+  it("counts SQL with content as non-empty even with leading comments", () => {
+    const dir = makeRecipeDir("comments-then-sql");
+    writeFileSync(
+      join(dir, "x.sql"),
+      "-- doc comment line\nSELECT path FROM files\n",
+    );
+    expect(readRecipesFromDir(dir, "bundled")).toHaveLength(1);
+  });
+
+  it("returns [] for a non-directory path (not an error)", () => {
+    const filePath = join(workDir, "actually-a-file.txt");
+    writeFileSync(filePath, "");
+    expect(readRecipesFromDir(filePath, "bundled")).toEqual([]);
+  });
+});
+
+describe("mergeRecipes", () => {
+  function recipe(id: string, source: LoadedRecipe["source"]): LoadedRecipe {
+    return {
+      id,
+      sql: `SELECT '${id}'`,
+      description: undefined,
+      body: undefined,
+      actions: undefined,
+      source,
+      shadows: false,
+    };
+  }
+
+  it("project-only — no shadows, no merging", () => {
+    const r = mergeRecipes(
+      [],
+      [recipe("a", "project"), recipe("b", "project")],
+    );
+    expect(r.map((x) => `${x.id}:${x.source}:${x.shadows}`)).toEqual([
+      "a:project:false",
+      "b:project:false",
+    ]);
+  });
+
+  it("bundled-only — passes through, sorted by id", () => {
+    const r = mergeRecipes(
+      [recipe("zebra", "bundled"), recipe("alpha", "bundled")],
+      [],
+    );
+    expect(r.map((x) => x.id)).toEqual(["alpha", "zebra"]);
+  });
+
+  it("project shadows bundled — project wins, shadows: true", () => {
+    const r = mergeRecipes(
+      [recipe("fan-out", "bundled"), recipe("fan-in", "bundled")],
+      [recipe("fan-out", "project")],
+    );
+    const fanOut = r.find((x) => x.id === "fan-out")!;
+    expect(fanOut.source).toBe("project");
+    expect(fanOut.shadows).toBe(true);
+    // bundled fan-out is filtered out — only one entry per id.
+    expect(r.filter((x) => x.id === "fan-out")).toHaveLength(1);
+    // unrelated bundled recipe still present.
+    const fanIn = r.find((x) => x.id === "fan-in")!;
+    expect(fanIn.source).toBe("bundled");
+    expect(fanIn.shadows).toBe(false);
+  });
+
+  it("project recipe with no bundled match — shadows: false", () => {
+    const r = mergeRecipes(
+      [recipe("fan-out", "bundled")],
+      [recipe("internal-flaky-tests", "project")],
+    );
+    const internal = r.find((x) => x.id === "internal-flaky-tests")!;
+    expect(internal.shadows).toBe(false);
+  });
+});
+
+describe("loadAllRecipes (Tracer 1 — bundled-only path)", () => {
+  it("loads bundled, ignores projectDir stub", () => {
+    const dir = makeRecipeDir("bundled-stub");
+    writeFileSync(join(dir, "fan-out.sql"), "SELECT 1\n");
+    const r = loadAllRecipes({ bundledDir: dir, projectDir: undefined });
+    expect(r).toHaveLength(1);
+    expect(r[0]!.source).toBe("bundled");
+  });
+
+  it("ignores a projectDir argument in Tracer 1 (project loader stubbed)", () => {
+    const bundledDir = makeRecipeDir("bundled");
+    const projectDir = makeRecipeDir("project");
+    writeFileSync(join(bundledDir, "x.sql"), "SELECT 1\n");
+    writeFileSync(
+      join(projectDir, "y.sql"),
+      "SELECT 2\n",
+      // Will load in Tracer 3; for now project recipes are silently dropped.
+    );
+    const r = loadAllRecipes({ bundledDir, projectDir });
+    expect(r.map((x) => x.id)).toEqual(["x"]);
+  });
+});

src/application/recipes-loader.ts

@@ -0,0 +1,168 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * One agent-facing follow-up suggested for every row of a recipe's result.
+ * Recipe authors hand-write this alongside the SQL (predictable: every row gets
+ * the same template). Ad-hoc SQL never carries actions — recipe-only feature.
+ *
+ * `auto_fixable` defaults to `false` when omitted. `description` is human prose
+ * for the agent to surface; `type` is a stable kebab-case verb the agent can
+ * key off (`delete-file`, `split-barrel`, `flag-caller`, …).
+ */
+export interface RecipeAction {
+  type: string;
+  auto_fixable?: boolean;
+  description?: string;
+}
+
+/**
+ * One loaded recipe — the canonical shape the loader returns. Bundled and
+ * project recipes share this shape; `source` discriminates them. `shadows`
+ * is true when a project recipe overrides a bundled recipe of the same id
+ * (see plan §9 Q-E — agents read this at session start to know when a
+ * recipe behaves differently from the documented bundled version).
+ */
+export interface LoadedRecipe {
+  id: string;
+  sql: string;
+  description: string | undefined;
+  body: string | undefined;
+  actions: RecipeAction[] | undefined;
+  source: "bundled" | "project";
+  shadows: boolean;
+}
+
+export interface LoadRecipesOpts {
+  /**
+   * Absolute path to the directory containing bundled recipe `.sql` files.
+   * Resolved by the caller via `resolveBundledRecipesDir()` (npm package
+   * layout — `templates/recipes/` next to `templates/agents/`).
+   */
+  bundledDir: string;
+  /**
+   * Absolute path to the project's `.codemap/recipes/` directory, or
+   * `undefined` if it doesn't exist. Tracer 3 wires this; Tracer 1
+   * accepts but doesn't read it.
+   */
+  projectDir: string | undefined;
+}
+
+/**
+ * Eager loader — reads every `<id>.sql` from `bundledDir` (and `projectDir`
+ * once Tracer 3 lands), pairs each with optional `<id>.md`, applies
+ * load-time validation (non-empty SQL after stripping comments;
+ * lexical DML/DDL deny-list — Tracer 5), and returns the merged list.
+ *
+ * Project recipes win on id collision (`shadows: true` flag; see plan
+ * §9 Q-E). Per plan §9 Q-B (eager startup load), this is called once
+ * at module init in `cli/query-recipes.ts`'s shim layer; the result
+ * is module-cached for the process lifetime.
+ */
+export function loadAllRecipes(opts: LoadRecipesOpts): LoadedRecipe[] {
+  const bundled = readRecipesFromDir(opts.bundledDir, "bundled");
+
+  // Tracer 1: project loader is a stub. Tracer 3 implements it + the
+  // shadow-flag merge logic (project wins; sets shadows: true when
+  // an id matches a bundled recipe).
+  const project: LoadedRecipe[] = [];
+
+  return mergeRecipes(bundled, project);
+}
+
+/**
+ * Project recipes win on id collision; matching bundled entries are filtered
+ * out and the project entry's `shadows` flag is flipped to `true`. Order:
+ * project first (in id order), then bundled (in id order) — the catalog
+ * surface stays deterministic per directory listing.
+ */
+export function mergeRecipes(
+  bundled: LoadedRecipe[],
+  project: LoadedRecipe[],
+): LoadedRecipe[] {
+  const projectIds = new Set(project.map((r) => r.id));
+  const flaggedProject = project.map((r) => ({
+    ...r,
+    shadows: projectIds.has(r.id) && bundled.some((b) => b.id === r.id),
+  }));
+  const filteredBundled = bundled.filter((r) => !projectIds.has(r.id));
+  return [...flaggedProject, ...filteredBundled].sort((a, b) =>
+    a.id.localeCompare(b.id),
+  );
+}
+
+/**
+ * Read every `<id>.sql` from `dir`, pair with optional `<id>.md`. Returns
+ * `[]` if the directory doesn't exist (project-recipes case in Tracer 3 —
+ * absence of `.codemap/recipes/` is not an error). Throws if the directory
+ * exists but a `<id>.sql` fails the load-time validation (Tracer 5 will
+ * extend this with the DML/DDL lexical check).
+ */
+export function readRecipesFromDir(
+  dir: string,
+  source: "bundled" | "project",
+): LoadedRecipe[] {
+  if (!existsSync(dir)) return [];
+  const stat = statSync(dir);
+  if (!stat.isDirectory()) return [];
+
+  const entries = readdirSync(dir);
+  const recipes: LoadedRecipe[] = [];
+
+  for (const entry of entries) {
+    if (!entry.endsWith(".sql")) continue;
+    const id = entry.slice(0, -".sql".length);
+    if (id.length === 0) continue;
+    const sqlPath = join(dir, entry);
+    const sql = readFileSync(sqlPath, "utf8");
+    if (isEffectivelyEmpty(sql)) {
+      throw new Error(
+        `Recipe "${id}" at ${sqlPath} is empty (no SQL after stripping -- comments and whitespace).`,
+      );
+    }
+
+    const mdPath = join(dir, `${id}.md`);
+    const md = existsSync(mdPath) ? readFileSync(mdPath, "utf8") : undefined;
+    const description = md !== undefined ? firstNonEmptyLine(md) : undefined;
+
+    recipes.push({
+      id,
+      sql,
+      description,
+      body: md,
+      // Tracer 5 will populate this from YAML frontmatter on `md`.
+      actions: undefined,
+      source,
+      shadows: false,
+    });
+  }
+
+  return recipes.sort((a, b) => a.id.localeCompare(b.id));
+}
+
+/**
+ * Strip `--` line comments and trailing whitespace; return true if nothing
+ * meaningful remains. Same shape the load-time DML/DDL check (Tracer 5)
+ * will extend.
+ */
+function isEffectivelyEmpty(sql: string): boolean {
+  const stripped = sql
+    .split("\n")
+    .map((line) => {
+      const commentIdx = line.indexOf("--");
+      return commentIdx === -1 ? line : line.slice(0, commentIdx);
+    })
+    .join("\n")
+    .trim();
+  return stripped.length === 0;
+}
+
+function firstNonEmptyLine(text: string): string | undefined {
+  for (const raw of text.split("\n")) {
+    const trimmed = raw.trim();
+    if (trimmed.length === 0) continue;
+    // Strip leading Markdown header markers so "# Fan-out" → "Fan-out".
+    return trimmed.replace(/^#+\s+/, "");
+  }
+  return undefined;
+}