edsger 0.59.0 → 0.60.0

package/dist/commands/recipes/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * CLI command: edsger recipes <productId> --scan-id <id>
+ *
+ * Clones the product's repo, asks Claude to identify implementation recipes
+ * the product uses, and persists them via the recipes / product_recipes
+ * tables. The desktop UI creates a pending recipe_scans row first then
+ * invokes the CLI with --scan-id; the CLI flips status running →
+ * success/failed and writes recipes via the MCP toolkit.
+ */
+export interface RecipesCliOptions {
+    scanId: string;
+    guidance?: string;
+    verbose?: boolean;
+}
+export declare function runRecipes(productId: string, options: RecipesCliOptions): Promise<void>;

package/dist/commands/recipes/index.js

@@ -0,0 +1,34 @@
+/**
+ * CLI command: edsger recipes <productId> --scan-id <id>
+ *
+ * Clones the product's repo, asks Claude to identify implementation recipes
+ * the product uses, and persists them via the recipes / product_recipes
+ * tables. The desktop UI creates a pending recipe_scans row first then
+ * invokes the CLI with --scan-id; the CLI flips status running →
+ * success/failed and writes recipes via the MCP toolkit.
+ */
+import { runRecipesPhase } from '../../phases/recipes/index.js';
+import { logError, logInfo, logSuccess } from '../../utils/logger.js';
+export async function runRecipes(productId, options) {
+    const { scanId, guidance, verbose } = options;
+    if (!productId) {
+        throw new Error('Product ID is required for recipes');
+    }
+    if (!scanId) {
+        throw new Error('--scan-id is required (the pending recipe_scans row id)');
+    }
+    logInfo(`Starting recipes scan for product ${productId}`);
+    const result = await runRecipesPhase({
+        productId,
+        scanId,
+        guidance,
+        verbose,
+    });
+    if (result.status === 'success') {
+        logSuccess(result.message);
+    }
+    else {
+        logError(result.message);
+        process.exit(1);
+    }
+}

package/dist/index.js

@@ -24,8 +24,8 @@ import { runIntelligence } from './commands/intelligence/index.js';
 import { runIssueAnalysisCommand } from './commands/issue-analysis/index.js';
 import { runPRResolve } from './commands/pr-resolve/index.js';
 import { runPRReview } from './commands/pr-review/index.js';
-import { runProductTechniques } from './commands/product-techniques/index.js';
 import { runProductTestCases } from './commands/product-test-cases/index.js';
+import { runRecipes } from './commands/recipes/index.js';
 import { runQualityBenchmarkCli } from './commands/quality-benchmark/index.js';
 import { runRefactor } from './commands/refactor/refactor.js';
 import { runReleaseSyncCommand } from './commands/release-sync/index.js';
@@ -695,18 +695,18 @@ program
     }
 });
 // ============================================================
-// Subcommand: edsger product-techniques <productId>
+// Subcommand: edsger recipes <productId>
 // ============================================================
 program
-    .command('product-techniques <productId>')
-    .description("Generate a catalogue of the techniques a product's repo uses (languages, frameworks, patterns, state idioms, build & deploy, notable bits). Writes the result to the pending product_techniques row identified by --techniques-id.")
-    .requiredOption('--techniques-id <id>', 'Pending product_techniques row id to populate')
+    .command('recipes <productId>')
+    .description("Scan a product's repo for the implementation recipes it uses (which services/tools are chained together to deliver each capability) and persist them via the recipes / product_recipes tables. Writes against the pending recipe_scans row identified by --scan-id.")
+    .requiredOption('--scan-id <id>', 'Pending recipe_scans row id to drive (created by the desktop UI before invocation)')
     .option('-g, --guidance <text>', 'Human direction for the AI (focus areas, exclusions)')
     .option('-v, --verbose', 'Verbose output')
     .action(async (productId, opts) => {
     try {
-        await runProductTechniques(productId, {
-            techniquesId: opts.techniquesId,
+        await runRecipes(productId, {
+            scanId: opts.scanId,
             guidance: opts.guidance,
             verbose: opts.verbose,
         });

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

@@ -0,0 +1,56 @@
+/**
+ * Recipes phase: clone the product's repo, ask Claude to identify each
+ * non-trivial capability the product implements, and persist HOW it's built
+ * via the recipes / product_recipes tables.
+ *
+ * Production-grade behaviours layered on top of the basic agent loop:
+ *
+ *   - Heartbeat: `last_heartbeat_at` on the recipe_scans row is refreshed
+ *     on every assistant message so the reader can detect stalled / crashed
+ *     runs (see desktop-app/.../services/db/recipe-scans.ts for the lazy
+ *     reaper).
+ *   - Cancellation-safe writes: markRunning / markSuccess / markFailed only
+ *     touch rows whose status is in {pending, running}. If the user clicked
+ *     Stop and the row is now 'cancelled', the final write no-ops.
+ *   - Per-call MCP writes: agent commits each create / update / link /
+ *     unlink as it goes. There is no "submit at the end" buffer — partial
+ *     progress survives even if the agent later errors out.
+ */
+import type { SupabaseClient } from '@supabase/supabase-js';
+import type { RecipeSummary } from './types.js';
+export interface RecipesPhaseOptions {
+    productId: string;
+    scanId: string;
+    guidance?: string;
+    verbose?: boolean;
+}
+export interface RecipesPhaseResult {
+    status: 'success' | 'error' | 'cancelled';
+    message: string;
+    counts?: {
+        created: number;
+        updated: number;
+        linked: number;
+        unlinked: number;
+    };
+}
+export declare function runRecipesPhase(options: RecipesPhaseOptions): Promise<RecipesPhaseResult>;
+export declare function getProductTeamId(supabase: SupabaseClient, productId: string): Promise<string | null>;
+export declare function getScanCreator(supabase: SupabaseClient, scanId: string): Promise<{
+    created_by: string;
+} | null>;
+export declare function listTeamRecipes(supabase: SupabaseClient, teamId: string): Promise<RecipeSummary[]>;
+export declare function listProductRecipeLinks(supabase: SupabaseClient, productId: string): Promise<{
+    recipe_id: string;
+    name: string;
+}[]>;
+/**
+ * Claim the row by flipping `pending` → `running`. Returns true on success
+ * (we won the claim) and false when the row has already moved on (e.g. user
+ * cancelled before the CLI started). Bounded by the status filter so we
+ * can't accidentally resurrect a 'cancelled' row.
+ */
+export declare function markRunning(supabase: SupabaseClient, scanId: string): Promise<boolean>;
+export declare function heartbeat(supabase: SupabaseClient, scanId: string): Promise<void>;
+export declare function markFailed(supabase: SupabaseClient, scanId: string, errorMessage: string): Promise<boolean>;
+export declare function markSuccess(supabase: SupabaseClient, scanId: string): Promise<boolean>;

package/dist/phases/recipes/index.js

@@ -0,0 +1,301 @@
+/**
+ * Recipes phase: clone the product's repo, ask Claude to identify each
+ * non-trivial capability the product implements, and persist HOW it's built
+ * via the recipes / product_recipes tables.
+ *
+ * Production-grade behaviours layered on top of the basic agent loop:
+ *
+ *   - Heartbeat: `last_heartbeat_at` on the recipe_scans row is refreshed
+ *     on every assistant message so the reader can detect stalled / crashed
+ *     runs (see desktop-app/.../services/db/recipe-scans.ts for the lazy
+ *     reaper).
+ *   - Cancellation-safe writes: markRunning / markSuccess / markFailed only
+ *     touch rows whose status is in {pending, running}. If the user clicked
+ *     Stop and the row is now 'cancelled', the final write no-ops.
+ *   - Per-call MCP writes: agent commits each create / update / link /
+ *     unlink as it goes. There is no "submit at the end" buffer — partial
+ *     progress survives even if the agent later errors out.
+ */
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import { getGitHubConfigByProduct } from '../../api/github.js';
+import { DEFAULT_MODEL } from '../../constants.js';
+import { getSupabase } from '../../supabase/client.js';
+import { logError, logInfo, logSuccess, logWarning, } from '../../utils/logger.js';
+import { cleanupIssueRepo, cloneIssueRepo, ensureWorkspaceDir, } from '../../workspace/workspace-manager.js';
+import { fetchProductBasics } from '../find-shared/mcp.js';
+import { createPromptGenerator, extractTextFromContent, } from '../pr-shared/agent-utils.js';
+import { createRecipesMcpServer, createRecipesMutationCounts, } from './mcp-server.js';
+import { createRecipesSystemPrompt, createRecipesUserPrompt, } from './prompts.js';
+const WORKSPACE_KEY = 'recipes';
+const MAX_TURNS = 200;
+// Heartbeat cadence: at most one DB write per HEARTBEAT_MIN_INTERVAL_MS.
+// Triggered on every assistant message so a stalled agent (no messages
+// flowing) lets the row go stale and the reader can mark it failed.
+const HEARTBEAT_MIN_INTERVAL_MS = 15_000;
+export async function runRecipesPhase(options) {
+    const { productId, scanId, guidance, verbose } = options;
+    logInfo(`Starting recipes scan for product ${productId}`);
+    const supabase = getSupabase();
+    const claimed = await markRunning(supabase, scanId);
+    if (!claimed) {
+        return {
+            status: 'cancelled',
+            message: 'Recipe scan row is no longer in a runnable state (likely cancelled before the CLI started)',
+        };
+    }
+    const teamId = await getProductTeamId(supabase, productId);
+    if (!teamId) {
+        const msg = 'Product is not associated with a team; recipes are team-scoped and require one.';
+        await markFailed(supabase, scanId, msg);
+        return { status: 'error', message: msg };
+    }
+    const githubConfig = await getGitHubConfigByProduct(productId, verbose);
+    if (!githubConfig.configured ||
+        !githubConfig.token ||
+        !githubConfig.owner ||
+        !githubConfig.repo) {
+        const msg = githubConfig.message ||
+            'GitHub repository not configured for this product. Connect a repo first.';
+        await markFailed(supabase, scanId, msg);
+        return { status: 'error', message: msg };
+    }
+    let repoPath;
+    let succeeded = false;
+    try {
+        const workspaceRoot = ensureWorkspaceDir();
+        const repoKey = `${WORKSPACE_KEY}-${productId}`;
+        ({ repoPath } = cloneIssueRepo(workspaceRoot, repoKey, githubConfig.owner, githubConfig.repo, githubConfig.token));
+        const [product, scanMeta, teamRecipes, existingLinks] = await Promise.all([
+            fetchProductBasics(productId),
+            getScanCreator(supabase, scanId),
+            listTeamRecipes(supabase, teamId),
+            listProductRecipeLinks(supabase, productId),
+        ]);
+        if (!scanMeta) {
+            const msg = 'recipe_scans row vanished mid-run; aborting';
+            await markFailed(supabase, scanId, msg);
+            return { status: 'error', message: msg };
+        }
+        const systemPrompt = createRecipesSystemPrompt();
+        const userPrompt = createRecipesUserPrompt({
+            productName: product.name,
+            productDescription: product.description,
+            guidance,
+            teamRecipes,
+            existingLinks: existingLinks.map((l) => ({
+                recipeId: l.recipe_id,
+                name: l.name,
+            })),
+        });
+        const counts = createRecipesMutationCounts();
+        const existingLinkIds = new Set(existingLinks.map((l) => l.recipe_id));
+        const mcpServer = createRecipesMcpServer({
+            supabase,
+            teamId,
+            productId,
+            createdBy: scanMeta.created_by,
+        }, counts, teamRecipes, existingLinkIds);
+        logInfo('Running Claude agent to identify recipes...');
+        let lastHeartbeatAt = 0;
+        for await (const message of query({
+            prompt: createPromptGenerator(userPrompt),
+            options: {
+                systemPrompt: {
+                    type: 'preset',
+                    preset: 'claude_code',
+                    append: systemPrompt,
+                },
+                model: DEFAULT_MODEL,
+                maxTurns: MAX_TURNS,
+                permissionMode: 'bypassPermissions',
+                cwd: repoPath,
+                mcpServers: {
+                    recipes: mcpServer,
+                },
+            },
+        })) {
+            if (message.type === 'assistant') {
+                extractTextFromContent(message.message?.content ?? [], verbose);
+                const now = Date.now();
+                if (now - lastHeartbeatAt >= HEARTBEAT_MIN_INTERVAL_MS) {
+                    lastHeartbeatAt = now;
+                    await heartbeat(supabase, scanId);
+                }
+                continue;
+            }
+            if (message.type !== 'result') {
+                continue;
+            }
+            if (message.subtype !== 'success') {
+                const msg = `Recipes scan failed: agent ${message.subtype}`;
+                const written = await markFailed(supabase, scanId, msg);
+                return {
+                    status: written ? 'error' : 'cancelled',
+                    message: written
+                        ? msg
+                        : 'Scan was cancelled while the agent was running',
+                    counts,
+                };
+            }
+            const written = await markSuccess(supabase, scanId);
+            if (!written) {
+                return {
+                    status: 'cancelled',
+                    message: 'Scan was cancelled before the result could be written',
+                    counts,
+                };
+            }
+            succeeded = true;
+            const summary = `created ${counts.created}, updated ${counts.updated}, linked ${counts.linked}, unlinked ${counts.unlinked}`;
+            logSuccess(`Recipes scan complete — ${summary}`);
+            return {
+                status: 'success',
+                message: `Recipes scan complete (${summary})`,
+                counts,
+            };
+        }
+        const msg = 'Recipes scan ended without a result message';
+        await markFailed(supabase, scanId, msg);
+        return { status: 'error', message: msg, counts };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logError(`Recipes scan failed: ${errorMessage}`);
+        await markFailed(supabase, scanId, errorMessage);
+        return { status: 'error', message: errorMessage };
+    }
+    finally {
+        if (succeeded) {
+            cleanupIssueRepo(repoPath);
+        }
+    }
+}
+// ============================================================================
+// DB helpers — exported for unit tests
+// ============================================================================
+export async function getProductTeamId(supabase, productId) {
+    const { data, error } = await supabase
+        .from('products')
+        .select('team_id')
+        .eq('id', productId)
+        .maybeSingle();
+    if (error || !data) {
+        return null;
+    }
+    return data.team_id ?? null;
+}
+export async function getScanCreator(supabase, scanId) {
+    const { data, error } = await supabase
+        .from('recipe_scans')
+        .select('created_by')
+        .eq('id', scanId)
+        .maybeSingle();
+    if (error || !data) {
+        return null;
+    }
+    return data;
+}
+export async function listTeamRecipes(supabase, teamId) {
+    const { data, error } = await supabase
+        .from('recipes')
+        .select('id, name, summary, services')
+        .eq('team_id', teamId)
+        .order('updated_at', { ascending: false });
+    if (error || !data) {
+        return [];
+    }
+    return data.map((r) => ({
+        id: r.id,
+        name: r.name,
+        summary: r.summary,
+        services: Array.isArray(r.services) ? r.services : [],
+    }));
+}
+export async function listProductRecipeLinks(supabase, productId) {
+    const { data, error } = await supabase
+        .from('product_recipes')
+        .select('recipe_id, recipes(name)')
+        .eq('product_id', productId);
+    if (error || !data) {
+        return [];
+    }
+    const rows = data;
+    const out = [];
+    for (const r of rows) {
+        const recipe = Array.isArray(r.recipes) ? r.recipes[0] : r.recipes;
+        if (recipe) {
+            out.push({ recipe_id: r.recipe_id, name: recipe.name });
+        }
+    }
+    return out;
+}
+/**
+ * Claim the row by flipping `pending` → `running`. Returns true on success
+ * (we won the claim) and false when the row has already moved on (e.g. user
+ * cancelled before the CLI started). Bounded by the status filter so we
+ * can't accidentally resurrect a 'cancelled' row.
+ */
+export async function markRunning(supabase, scanId) {
+    const { data, error } = await supabase
+        .from('recipe_scans')
+        .update({
+        status: 'running',
+        error: null,
+        last_heartbeat_at: new Date().toISOString(),
+    })
+        .eq('id', scanId)
+        .in('status', ['pending', 'running'])
+        .select('id')
+        .maybeSingle();
+    if (error) {
+        logWarning(`Could not mark scan as running: ${error.message}`);
+        return false;
+    }
+    return data !== null;
+}
+export async function heartbeat(supabase, scanId) {
+    const { error } = await supabase
+        .from('recipe_scans')
+        .update({ last_heartbeat_at: new Date().toISOString() })
+        .eq('id', scanId)
+        .eq('status', 'running');
+    if (error) {
+        logWarning(`Heartbeat failed: ${error.message}`);
+    }
+}
+export async function markFailed(supabase, scanId, errorMessage) {
+    const { data, error } = await supabase
+        .from('recipe_scans')
+        .update({
+        status: 'failed',
+        error: errorMessage,
+        completed_at: new Date().toISOString(),
+    })
+        .eq('id', scanId)
+        .in('status', ['pending', 'running'])
+        .select('id')
+        .maybeSingle();
+    if (error) {
+        logWarning(`Could not mark scan as failed: ${error.message}`);
+        return false;
+    }
+    return data !== null;
+}
+export async function markSuccess(supabase, scanId) {
+    const { data, error } = await supabase
+        .from('recipe_scans')
+        .update({
+        status: 'success',
+        error: null,
+        completed_at: new Date().toISOString(),
+    })
+        .eq('id', scanId)
+        .in('status', ['pending', 'running'])
+        .select('id')
+        .maybeSingle();
+    if (error) {
+        logWarning(`Could not mark scan as success: ${error.message}`);
+        return false;
+    }
+    return data !== null;
+}

package/dist/phases/recipes/mcp-server.d.ts

@@ -0,0 +1,63 @@
+/**
+ * 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 type { SupabaseClient } from '@supabase/supabase-js';
+import { z } from 'zod';
+import { type RecipeSummary } from './types.js';
+export interface RecipesToolContext {
+    supabase: SupabaseClient;
+    teamId: string;
+    productId: string;
+    createdBy: string;
+}
+/**
+ * Records how many of each kind of mutation the agent made — exported so the
+ * orchestrator can print a summary line at the end of the scan.
+ */
+export interface RecipesMutationCounts {
+    created: number;
+    updated: number;
+    linked: number;
+    unlinked: number;
+}
+export declare function createRecipesMutationCounts(): RecipesMutationCounts;
+export declare function createGetRecipeDetailTool(ctx: RecipesToolContext, teamRecipeIds: Set<string>): import("@anthropic-ai/claude-agent-sdk").SdkMcpToolDefinition<{
+    recipe_id: z.ZodString;
+}>;
+export declare function createCreateRecipeTool(ctx: RecipesToolContext, counts: RecipesMutationCounts, teamRecipeIds: Set<string>): import("@anthropic-ai/claude-agent-sdk").SdkMcpToolDefinition<{
+    name: z.ZodString;
+    summary: z.ZodString;
+    content: z.ZodString;
+    services: z.ZodArray<z.ZodString>;
+    evidence: z.ZodString;
+}>;
+export declare function createUpdateRecipeTool(ctx: RecipesToolContext, counts: RecipesMutationCounts, teamRecipeIds: Set<string>): import("@anthropic-ai/claude-agent-sdk").SdkMcpToolDefinition<{
+    recipe_id: z.ZodString;
+    summary: z.ZodOptional<z.ZodString>;
+    content: z.ZodOptional<z.ZodString>;
+    services: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    evidence: z.ZodString;
+}>;
+export declare function createLinkRecipeTool(ctx: RecipesToolContext, counts: RecipesMutationCounts, teamRecipeIds: Set<string>): import("@anthropic-ai/claude-agent-sdk").SdkMcpToolDefinition<{
+    recipe_id: z.ZodString;
+    evidence: z.ZodString;
+}>;
+export declare function createUnlinkRecipeTool(ctx: RecipesToolContext, counts: RecipesMutationCounts, existingLinkIds: Set<string>): import("@anthropic-ai/claude-agent-sdk").SdkMcpToolDefinition<{
+    recipe_id: z.ZodString;
+}>;
+export declare function createRecipesMcpServer(ctx: RecipesToolContext, counts: RecipesMutationCounts, teamRecipes: RecipeSummary[], existingLinkIds: Set<string>): import("@anthropic-ai/claude-agent-sdk").McpSdkServerConfigWithInstance;

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/package.json

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

package/vitest.config.ts

@@ -16,7 +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/product-techniques/__tests__/**/*.test.ts',
+      'src/phases/recipes/__tests__/**/*.test.ts',
       'src/types/__tests__/**/*.test.ts',
       'src/commands/find-smells/__tests__/**/*.test.ts',
     ],