edsger 0.58.0 → 0.60.0

package/dist/phases/recipes/mcp-server.js

@@ -0,0 +1,204 @@
+/**
+ * In-process MCP server exposing the recipes toolkit. Five tools:
+ *
+ *   - get_recipe_detail  read-only: fetch full content of a team recipe
+ *   - create_recipe      INSERT recipe + INSERT product_recipe link
+ *   - update_recipe      UPDATE recipe (latest-wins overwrite) + UPSERT link
+ *   - link_recipe        UPSERT product_recipe link only (no content change)
+ *   - unlink_recipe      DELETE product_recipe link for a previously-linked
+ *                        recipe the agent confirmed is no longer present
+ *
+ * All writes are scoped to:
+ *   - the active recipe_scan's product_id (the link target)
+ *   - the team that owns that product (recipes are team-scoped)
+ *
+ * The handlers persist directly via the Supabase client passed in by the
+ * orchestrator — there is no captured-extraction buffer to flush at the
+ * end. Each tool call is its own committed effect.
+ */
+import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { RECIPE_CONTENT_MAX, RECIPE_EVIDENCE_MAX, RECIPE_NAME_MAX, RECIPE_SERVICE_NAME_MAX, RECIPE_SERVICES_MAX, RECIPE_SUMMARY_MAX, } from './types.js';
+export function createRecipesMutationCounts() {
+    return { created: 0, updated: 0, linked: 0, unlinked: 0 };
+}
+const servicesSchema = z
+    .array(z.string().min(1).max(RECIPE_SERVICE_NAME_MAX))
+    .max(RECIPE_SERVICES_MAX)
+    .describe('Sorted list of canonical service/tool/library names this recipe chains together (e.g. ["ElevenLabs","ffmpeg","Whisper"]). Sort alphabetically.');
+function normalizeServices(services) {
+    const cleaned = services.map((s) => s.trim()).filter((s) => s.length > 0);
+    return Array.from(new Set(cleaned)).sort((a, b) => a.toLowerCase().localeCompare(b.toLowerCase()));
+}
+function textError(message) {
+    return {
+        content: [{ type: 'text', text: message }],
+        isError: true,
+    };
+}
+function textOk(message) {
+    return {
+        content: [{ type: 'text', text: message }],
+    };
+}
+export function createGetRecipeDetailTool(ctx, teamRecipeIds) {
+    return tool('get_recipe_detail', 'Fetch the full markdown content of an existing team recipe by id. Call this when the prompt summary is not enough to decide between link / update / create.', {
+        recipe_id: z.string().uuid().describe('id from the team recipe list'),
+    }, async (args) => {
+        if (!teamRecipeIds.has(args.recipe_id)) {
+            return textError(`recipe_id ${args.recipe_id} is not in this team's recipe list.`);
+        }
+        const { data, error } = await ctx.supabase
+            .from('recipes')
+            .select('id, name, summary, content, services')
+            .eq('id', args.recipe_id)
+            .eq('team_id', ctx.teamId)
+            .maybeSingle();
+        if (error) {
+            return textError(`Failed to read recipe: ${error.message}`);
+        }
+        if (!data) {
+            return textError(`Recipe ${args.recipe_id} not found.`);
+        }
+        return textOk(JSON.stringify(data));
+    });
+}
+export function createCreateRecipeTool(ctx, counts, teamRecipeIds) {
+    return tool('create_recipe', 'Register a brand-new recipe in the team library AND link it to this product. Use only when no existing recipe matches the capability. Pass a fully-formed recipe — name, one-paragraph summary, markdown content, sorted services list, and product-specific evidence.', {
+        name: z.string().min(1).max(RECIPE_NAME_MAX),
+        summary: z.string().min(1).max(RECIPE_SUMMARY_MAX),
+        content: z.string().min(1).max(RECIPE_CONTENT_MAX),
+        services: servicesSchema,
+        evidence: z
+            .string()
+            .min(1)
+            .max(RECIPE_EVIDENCE_MAX)
+            .describe('Plain-text paragraph saying where in THIS product the recipe shows up (file paths, entry points).'),
+    }, async (args) => {
+        const services = normalizeServices(args.services);
+        const insertRecipe = await ctx.supabase
+            .from('recipes')
+            .insert({
+            team_id: ctx.teamId,
+            name: args.name.trim(),
+            summary: args.summary.trim(),
+            content: args.content,
+            services,
+            created_by: ctx.createdBy,
+        })
+            .select('id')
+            .single();
+        if (insertRecipe.error || !insertRecipe.data) {
+            return textError(`Failed to create recipe: ${insertRecipe.error?.message ?? 'unknown error'}`);
+        }
+        const recipeId = insertRecipe.data.id;
+        const linkErr = await ctx.supabase.from('product_recipes').insert({
+            product_id: ctx.productId,
+            recipe_id: recipeId,
+            evidence: args.evidence.trim(),
+        });
+        if (linkErr.error) {
+            return textError(`Recipe created (${recipeId}) but linking to product failed: ${linkErr.error.message}`);
+        }
+        teamRecipeIds.add(recipeId);
+        counts.created += 1;
+        return textOk(`Created recipe ${recipeId} and linked to this product.`);
+    });
+}
+export function createUpdateRecipeTool(ctx, counts, teamRecipeIds) {
+    return tool('update_recipe', 'Overwrite an existing recipe (latest-wins) with better information you discovered in this repo AND link this product to it. Use when the existing entry is broadly correct but lacks detail / has outdated services / has a vague summary. Omit fields you do not want to change.', {
+        recipe_id: z.string().uuid(),
+        summary: z.string().min(1).max(RECIPE_SUMMARY_MAX).optional(),
+        content: z.string().min(1).max(RECIPE_CONTENT_MAX).optional(),
+        services: servicesSchema.optional(),
+        evidence: z.string().min(1).max(RECIPE_EVIDENCE_MAX),
+    }, async (args) => {
+        if (!teamRecipeIds.has(args.recipe_id)) {
+            return textError(`recipe_id ${args.recipe_id} is not in this team's recipe list. Use create_recipe for new entries.`);
+        }
+        const patch = {};
+        if (args.summary !== undefined) {
+            patch.summary = args.summary.trim();
+        }
+        if (args.content !== undefined) {
+            patch.content = args.content;
+        }
+        if (args.services !== undefined) {
+            patch.services = normalizeServices(args.services);
+        }
+        if (Object.keys(patch).length > 0) {
+            const updateErr = await ctx.supabase
+                .from('recipes')
+                .update(patch)
+                .eq('id', args.recipe_id)
+                .eq('team_id', ctx.teamId);
+            if (updateErr.error) {
+                return textError(`Failed to update recipe: ${updateErr.error.message}`);
+            }
+        }
+        const linkErr = await ctx.supabase.from('product_recipes').upsert({
+            product_id: ctx.productId,
+            recipe_id: args.recipe_id,
+            evidence: args.evidence.trim(),
+        }, { onConflict: 'product_id,recipe_id' });
+        if (linkErr.error) {
+            return textError(`Recipe updated but linking to product failed: ${linkErr.error.message}`);
+        }
+        counts.updated += 1;
+        return textOk(`Updated recipe ${args.recipe_id} and linked to this product.`);
+    });
+}
+export function createLinkRecipeTool(ctx, counts, teamRecipeIds) {
+    return tool('link_recipe', 'Link this product to an existing recipe that already describes the capability accurately. Does NOT modify the recipe content. Use this whenever possible — the whole point of the team library is cross-product reuse.', {
+        recipe_id: z.string().uuid(),
+        evidence: z.string().min(1).max(RECIPE_EVIDENCE_MAX),
+    }, async (args) => {
+        if (!teamRecipeIds.has(args.recipe_id)) {
+            return textError(`recipe_id ${args.recipe_id} is not in this team's recipe list. Use create_recipe for new entries.`);
+        }
+        const linkErr = await ctx.supabase.from('product_recipes').upsert({
+            product_id: ctx.productId,
+            recipe_id: args.recipe_id,
+            evidence: args.evidence.trim(),
+        }, { onConflict: 'product_id,recipe_id' });
+        if (linkErr.error) {
+            return textError(`Failed to link recipe: ${linkErr.error.message}`);
+        }
+        counts.linked += 1;
+        return textOk(`Linked recipe ${args.recipe_id} to this product.`);
+    });
+}
+export function createUnlinkRecipeTool(ctx, counts, existingLinkIds) {
+    return tool('unlink_recipe', 'Drop a previously-linked recipe that you have confirmed is NO LONGER present in this repo. Only call this for ids in the "Currently linked to this product" list. Does not delete the recipe itself.', {
+        recipe_id: z.string().uuid(),
+    }, async (args) => {
+        if (!existingLinkIds.has(args.recipe_id)) {
+            return textError(`recipe_id ${args.recipe_id} is not in the "Currently linked to this product" list — nothing to unlink.`);
+        }
+        const { error } = await ctx.supabase
+            .from('product_recipes')
+            .delete()
+            .eq('product_id', ctx.productId)
+            .eq('recipe_id', args.recipe_id);
+        if (error) {
+            return textError(`Failed to unlink recipe: ${error.message}`);
+        }
+        existingLinkIds.delete(args.recipe_id);
+        counts.unlinked += 1;
+        return textOk(`Unlinked recipe ${args.recipe_id} from this product.`);
+    });
+}
+export function createRecipesMcpServer(ctx, counts, teamRecipes, existingLinkIds) {
+    const teamRecipeIds = new Set(teamRecipes.map((r) => r.id));
+    return createSdkMcpServer({
+        name: 'recipes',
+        version: '1.0.0',
+        tools: [
+            createGetRecipeDetailTool(ctx, teamRecipeIds),
+            createCreateRecipeTool(ctx, counts, teamRecipeIds),
+            createUpdateRecipeTool(ctx, counts, teamRecipeIds),
+            createLinkRecipeTool(ctx, counts, teamRecipeIds),
+            createUnlinkRecipeTool(ctx, counts, existingLinkIds),
+        ],
+    });
+}

package/dist/phases/recipes/prompts.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Prompts for the recipes phase.
+ *
+ * Agent's job: explore the cloned product repo and identify each non-trivial
+ * CAPABILITY the product implements ("AI video generation", "PDF export",
+ * "real-time presence", "Stripe subscription billing", etc.) and document
+ * HOW the capability is built — which services / tools / libraries are
+ * chained together. NOT a tech-stack inventory.
+ *
+ * The agent is fed the team's existing recipes (compact form: id + name +
+ * summary + services) and must, for each capability it identifies, pick one
+ * of:
+ *   - link_recipe   — existing recipe describes this capability correctly,
+ *                     just record this product uses it
+ *   - update_recipe — existing recipe is close but the agent has better /
+ *                     more accurate info from this repo; overwrite
+ *   - create_recipe — no existing recipe matches; new entry
+ *   - unlink_recipe — this product was previously linked to a recipe that
+ *                     is no longer present in the repo
+ *
+ * Submission is via MCP tool calls only — no fenced JSON.
+ */
+import type { RecipeSummary } from './types.js';
+export interface RecipesPromptContext {
+    productName: string;
+    productDescription?: string;
+    guidance?: string;
+    teamRecipes: RecipeSummary[];
+    existingLinks: {
+        recipeId: string;
+        name: string;
+    }[];
+}
+export declare function createRecipesSystemPrompt(): string;
+export declare function createRecipesUserPrompt(ctx: RecipesPromptContext): string;

package/dist/phases/recipes/prompts.js

@@ -0,0 +1,105 @@
+/**
+ * Prompts for the recipes phase.
+ *
+ * Agent's job: explore the cloned product repo and identify each non-trivial
+ * CAPABILITY the product implements ("AI video generation", "PDF export",
+ * "real-time presence", "Stripe subscription billing", etc.) and document
+ * HOW the capability is built — which services / tools / libraries are
+ * chained together. NOT a tech-stack inventory.
+ *
+ * The agent is fed the team's existing recipes (compact form: id + name +
+ * summary + services) and must, for each capability it identifies, pick one
+ * of:
+ *   - link_recipe   — existing recipe describes this capability correctly,
+ *                     just record this product uses it
+ *   - update_recipe — existing recipe is close but the agent has better /
+ *                     more accurate info from this repo; overwrite
+ *   - create_recipe — no existing recipe matches; new entry
+ *   - unlink_recipe — this product was previously linked to a recipe that
+ *                     is no longer present in the repo
+ *
+ * Submission is via MCP tool calls only — no fenced JSON.
+ */
+export function createRecipesSystemPrompt() {
+    return `You are a senior staff engineer cataloguing the IMPLEMENTATION RECIPES a product uses.
+
+The current working directory is a fresh clone of the product's repository. Use Glob/Grep/Read (and Bash for git/log when helpful) to explore it before writing.
+
+## What is a "recipe"?
+
+A recipe describes ONE non-trivial capability the product delivers, and HOW it is built: which services, libraries, tools, and techniques are chained together to make it work end-to-end.
+
+Good recipe names: "AI video generation", "PDF export with custom fonts", "Real-time collaborative editing", "Stripe subscription billing with proration", "GitHub OAuth device flow".
+Bad recipe names: "React frontend", "TypeScript", "Tailwind", "Authentication" (too vague).
+
+A recipe is the WHAT + HOW pair. The WHAT is the user-facing capability. The HOW is the specific stack of services chained to deliver it. Two products can implement the same capability with the same stack — that is one recipe, linked from both products. Two products that implement "OCR" but one uses Tesseract and the other uses PaddleOCR are TWO different recipes (same capability name, different services).
+
+## Output protocol
+
+The MCP server exposes these tools — use them, do NOT paste content as fenced code:
+
+1. \`get_recipe_detail({ recipe_id })\` — fetch the full content of an existing recipe when you need to decide whether to link, update, or create. The prompt only gives you names + summaries + services to keep your context small.
+
+2. \`create_recipe({ name, summary, content, services, evidence })\` — register a brand-new recipe in the team library AND link this product to it.
+
+3. \`update_recipe({ recipe_id, summary?, content?, services?, evidence })\` — overwrite an existing recipe with better information you discovered in this repo AND link this product to it. Use when the existing recipe is broadly correct but lacks detail / has outdated services / has a vague summary.
+
+4. \`link_recipe({ recipe_id, evidence })\` — just link this product to an existing recipe that already describes the capability accurately. The recipe's content is not touched.
+
+5. \`unlink_recipe({ recipe_id })\` — drop a previously-linked recipe that the agent has confirmed is NO LONGER present in this repo (capability was removed, or the previous scan was wrong). Only unlink things in the "Currently linked to this product" list.
+
+Call exactly one of create / update / link for each capability you identify. Call unlink at the end for any previously-linked recipe you could not corroborate. When you are done with every capability and every unlink, end your turn — no summary message, no JSON dump.
+
+## Rules
+
+- \`services\` is a SORTED list of canonical service / tool / library names ("ElevenLabs", "ffmpeg", "Whisper", "Stripe", "Resend"). Sort alphabetically so equivalent recipes compare cleanly. Don't include language/framework names ("React", "Node") unless they're the actual differentiator.
+- \`content\` is markdown. Aim for 200–800 words per recipe. Structure: a short intro sentence, then numbered steps describing the flow, then a "Files" subsection with relative paths (e.g. \`src/services/video/encoder.ts\`).
+- \`evidence\` is one paragraph of plain text saying where in THIS product's repo the recipe shows up: file paths, key entry points. Used to help reviewers verify the link.
+- Don't invent capabilities. If the repo is small or only does one thing, emit one recipe — don't pad.
+- Prefer LINK over UPDATE over CREATE in that order. Reuse the team library aggressively; the whole point is cross-product visibility into the same recipe.
+- When the same capability is implemented with a clearly different stack, that's a NEW recipe even if the name collides. Disambiguate the name (\"PDF export (Puppeteer)\" vs \"PDF export (pdf-lib)\") so the team can tell them apart.`;
+}
+export function createRecipesUserPrompt(ctx) {
+    const lines = [];
+    lines.push(`# Product: ${ctx.productName}`);
+    if (ctx.productDescription) {
+        lines.push('');
+        lines.push('## Description');
+        lines.push(ctx.productDescription);
+    }
+    if (ctx.guidance && ctx.guidance.trim()) {
+        lines.push('');
+        lines.push('## Reviewer guidance (focus or exclusions)');
+        lines.push(ctx.guidance.trim());
+    }
+    lines.push('');
+    lines.push('## Existing recipes in this team');
+    if (ctx.teamRecipes.length === 0) {
+        lines.push('(none — every recipe you identify will be a `create_recipe`.)');
+    }
+    else {
+        lines.push('Prefer `link_recipe` / `update_recipe` over `create_recipe` when one of these matches the capability you found. Call `get_recipe_detail` if you need to see the full content before deciding.');
+        lines.push('');
+        for (const r of ctx.teamRecipes) {
+            const svc = r.services.length > 0 ? ` services=[${r.services.join(', ')}]` : '';
+            const sum = r.summary ? ` — ${r.summary}` : '';
+            lines.push(`- id=${r.id} "${r.name}"${svc}${sum}`);
+        }
+    }
+    lines.push('');
+    lines.push('## Currently linked to this product');
+    if (ctx.existingLinks.length === 0) {
+        lines.push('(none)');
+    }
+    else {
+        lines.push('If you confirm any of these is no longer present in the repo, call `unlink_recipe` with its id.');
+        lines.push('');
+        for (const l of ctx.existingLinks) {
+            lines.push(`- id=${l.recipeId} "${l.name}"`);
+        }
+    }
+    lines.push('');
+    lines.push('## Task');
+    lines.push('Explore the cloned repository, identify every non-trivial capability the product delivers, and for each call exactly one of `create_recipe` / `update_recipe` / `link_recipe`. Then call `unlink_recipe` for any previously-linked recipe you could not corroborate. End your turn when done.');
+    return lines.join('\n');
+}

package/dist/phases/recipes/types.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Shapes the recipes MCP tools accept and return. The Zod schemas live in
+ * mcp-server.ts; these plain TS types are what the rest of the phase
+ * (orchestrator, persistence helpers, tests) consumes so they don't have
+ * to inflate Zod into their dependency graph.
+ */
+export interface RecipeSummary {
+    id: string;
+    name: string;
+    summary: string | null;
+    services: string[];
+}
+export interface RecipeDetail extends RecipeSummary {
+    content: string | null;
+}
+export interface CreateRecipeArgs {
+    name: string;
+    summary: string;
+    content: string;
+    services: string[];
+    evidence: string;
+}
+export interface UpdateRecipeArgs {
+    recipeId: string;
+    summary?: string;
+    content?: string;
+    services?: string[];
+    evidence: string;
+}
+export interface LinkRecipeArgs {
+    recipeId: string;
+    evidence: string;
+}
+export interface UnlinkRecipeArgs {
+    recipeId: string;
+}
+export declare const RECIPE_SUMMARY_MAX = 500;
+export declare const RECIPE_CONTENT_MAX = 50000;
+export declare const RECIPE_NAME_MAX = 200;
+export declare const RECIPE_SERVICES_MAX = 20;
+export declare const RECIPE_SERVICE_NAME_MAX = 80;
+export declare const RECIPE_EVIDENCE_MAX = 4000;

package/dist/phases/recipes/types.js

@@ -0,0 +1,16 @@
+/**
+ * Shapes the recipes MCP tools accept and return. The Zod schemas live in
+ * mcp-server.ts; these plain TS types are what the rest of the phase
+ * (orchestrator, persistence helpers, tests) consumes so they don't have
+ * to inflate Zod into their dependency graph.
+ */
+// Defensive caps mirroring the DB CHECK constraints from
+// 20260521000000_create_recipes.sql. Keeping the limits here lets the MCP
+// tool reject oversized output with an actionable error message instead of
+// getting a Postgres constraint violation.
+export const RECIPE_SUMMARY_MAX = 500;
+export const RECIPE_CONTENT_MAX = 50_000;
+export const RECIPE_NAME_MAX = 200;
+export const RECIPE_SERVICES_MAX = 20;
+export const RECIPE_SERVICE_NAME_MAX = 80;
+export const RECIPE_EVIDENCE_MAX = 4000;

package/dist/phases/screen-flow/mcp-server.d.ts

@@ -42,10 +42,10 @@ export declare function createSubmitScreenFlowTool(state: ScreenFlowCaptureState
         file: z.ZodOptional<z.ZodString>;
         kind: z.ZodEnum<{
             page: "page";
+            state: "state";
             modal: "modal";
             drawer: "drawer";
             tab: "tab";
-            state: "state";
         }>;
         layout: z.ZodEnum<{
             split: "split";

package/dist/services/branches.js

@@ -30,7 +30,7 @@ export async function getBranches(options) {
             // Fall through to MCP
         }
     }
-    if (branches == null) {
+    if (!branches) {
         const result = (await callMcpEndpoint('branches/list', {
             issue_id: issueId,
         }));
@@ -79,7 +79,7 @@ export async function createBranches(options, branches) {
             // Fall through to MCP
         }
     }
-    if (createdBranches == null) {
+    if (!createdBranches) {
         const result = (await callMcpEndpoint('branches/create', {
             issue_id: issueId,
             branches,
@@ -119,7 +119,7 @@ export async function updateBranch(branchId, updates, verbose) {
             // Fall through to MCP
         }
     }
-    if (updated == null) {
+    if (!updated) {
         const result = (await callMcpEndpoint('branches/update', {
             branch_id: branchId,
             ...updates,

package/dist/services/phase-hooks/hook-executor.js

@@ -7,7 +7,7 @@ import { DEFAULT_MODEL } from '../../constants.js';
 import { logDebug } from '../../utils/logger.js';
 import { loadSkillFile } from './plugin-loader.js';
 const defaultDeps = {
-    loadSkillFile: loadSkillFile,
+    loadSkillFile,
     queryFn: query,
 };
 // ---- Prompt building (pure) ----

package/dist/services/phase-ratings.js

@@ -116,7 +116,7 @@ export async function getPhaseRatings(issueId, phase, verbose) {
                 // Fall through to MCP
             }
         }
-        if (ratings == null) {
+        if (!ratings) {
             const result = await callMcpEndpoint('phase_ratings/list', {
                 issue_id: issueId,
                 phase,

package/dist/services/product-logs.js

@@ -46,7 +46,7 @@ export async function getPendingLogsByUser(productId, verbose) {
             // Fall through to MCP
         }
     }
-    if (groups == null) {
+    if (!groups) {
         const result = (await callMcpEndpoint('product_logs/pending_by_user', {
             product_id: productId,
         }));

package/dist/services/pull-requests.js

@@ -30,7 +30,7 @@ export async function getPullRequests(options) {
             // Fall through to MCP
         }
     }
-    if (pullRequests == null) {
+    if (!pullRequests) {
         const result = (await callMcpEndpoint('pull_requests/list', {
             issue_id: issueId,
         }));
@@ -66,7 +66,7 @@ export async function createPullRequests(options, pullRequests) {
             // Fall through to MCP
         }
     }
-    if (created == null) {
+    if (!created) {
         const result = (await callMcpEndpoint('pull_requests/create', {
             issue_id: issueId,
             pull_requests: pullRequests,
@@ -106,7 +106,7 @@ export async function updatePullRequest(prId, updates, verbose) {
             // Fall through to MCP
         }
     }
-    if (updated == null) {
+    if (!updated) {
         const result = (await callMcpEndpoint('pull_requests/update', {
             pull_request_id: prId,
             ...updates,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "edsger",
-  "version": "0.58.0",
+  "version": "0.60.0",
   "type": "module",
   "bin": {
     "edsger": "dist/index.js"

package/vitest.config.ts

@@ -16,6 +16,7 @@ export default defineConfig({
       'src/phases/sync-sentry-issues/__tests__/**/*.test.ts',
       'src/phases/sync-shared/__tests__/**/*.test.ts',
       'src/phases/screen-flow/__tests__/**/*.test.ts',
+      'src/phases/recipes/__tests__/**/*.test.ts',
       'src/types/__tests__/**/*.test.ts',
       'src/commands/find-smells/__tests__/**/*.test.ts',
     ],