edsger 0.59.0 → 0.61.0

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/index.d.ts

@@ -1,8 +1,8 @@
 /**
  * screen-flow phase: clone the product's repo, ask Claude to map every
  * user-facing screen and the transitions between them into a structured
- * ScreenFlowExtraction, then persist the result to screen_flows /
- * screen_flow_nodes / screen_flow_edges via the Supabase SDK.
+ * ScreenFlowExtraction, then persist the result to flows / flow_nodes /
+ * flow_edges (rows tagged `type = 'screen'`) via the Supabase SDK.
  *
  * Companion to find-architecture / find-bugs / find-features. Same workspace
  * pattern, but writes to its own tables rather than filing issues.

package/dist/phases/screen-flow/index.js

@@ -1,8 +1,8 @@
 /**
  * screen-flow phase: clone the product's repo, ask Claude to map every
  * user-facing screen and the transitions between them into a structured
- * ScreenFlowExtraction, then persist the result to screen_flows /
- * screen_flow_nodes / screen_flow_edges via the Supabase SDK.
+ * ScreenFlowExtraction, then persist the result to flows / flow_nodes /
+ * flow_edges (rows tagged `type = 'screen'`) via the Supabase SDK.
  *
  * Companion to find-architecture / find-bugs / find-features. Same workspace
  * pattern, but writes to its own tables rather than filing issues.
@@ -186,7 +186,7 @@ function tryFallbackParse(resultMessage, assistantText) {
 // ============================================================================
 async function markFlowRunning(supabase, flowId) {
     const { error } = await supabase
-        .from('screen_flows')
+        .from('flows')
         .update({ status: 'running', error: null })
         .eq('id', flowId);
     if (error) {
@@ -195,7 +195,7 @@ async function markFlowRunning(supabase, flowId) {
 }
 async function markFlowFailed(supabase, flowId, errorMessage) {
     await supabase
-        .from('screen_flows')
+        .from('flows')
         .update({
         status: 'failed',
         error: errorMessage,
@@ -204,9 +204,23 @@ async function markFlowFailed(supabase, flowId, errorMessage) {
         .eq('id', flowId);
 }
 async function persistTheme(supabase, flowId, theme) {
+    // Theme is screen-flow-specific; stash it inside the generic options JSONB.
+    const { data, error: readError } = await supabase
+        .from('flows')
+        .select('options')
+        .eq('id', flowId)
+        .single();
+    if (readError) {
+        logWarning(`Could not read flow options: ${readError.message}`);
+        return;
+    }
+    const nextOptions = {
+        ...(data?.options ?? {}),
+        theme,
+    };
     const { error } = await supabase
-        .from('screen_flows')
-        .update({ theme })
+        .from('flows')
+        .update({ options: nextOptions })
         .eq('id', flowId);
     if (error) {
         logWarning(`Could not persist extracted theme: ${error.message}`);
@@ -214,7 +228,7 @@ async function persistTheme(supabase, flowId, theme) {
 }
 async function markFlowSuccess(supabase, flowId, summary) {
     await supabase
-        .from('screen_flows')
+        .from('flows')
         .update({
         status: 'success',
         summary,
@@ -225,14 +239,14 @@ async function markFlowSuccess(supabase, flowId, summary) {
 }
 async function persistFlow(supabase, flowId, extraction) {
     // Re-runs replace prior content for the same flow row.
-    await supabase.from('screen_flow_edges').delete().eq('flow_id', flowId);
-    await supabase.from('screen_flow_nodes').delete().eq('flow_id', flowId);
+    await supabase.from('flow_edges').delete().eq('flow_id', flowId);
+    await supabase.from('flow_nodes').delete().eq('flow_id', flowId);
     if (extraction.nodes.length === 0) {
         return { nodesCreated: 0, edgesCreated: 0 };
     }
     const nodeRows = extraction.nodes.map((n, i) => buildNodeRow(flowId, n, i));
     const { data: insertedNodes, error: nodesError } = await supabase
-        .from('screen_flow_nodes')
+        .from('flow_nodes')
         .insert(nodeRows)
         .select('id, slug');
     if (nodesError) {
@@ -244,7 +258,7 @@ async function persistFlow(supabase, flowId, extraction) {
         .filter((e) => e !== null);
     if (edgeRows.length > 0) {
         const { error: edgesError } = await supabase
-            .from('screen_flow_edges')
+            .from('flow_edges')
             .insert(edgeRows);
         if (edgesError) {
             throw new Error(`Failed to insert edges: ${edgesError.message}`);
@@ -260,8 +274,6 @@ function buildNodeRow(flowId, node, index) {
         flow_id: flowId,
         slug: node.slug,
         name: node.name,
-        route: node.route ?? null,
-        file: node.file ?? null,
         kind: node.kind,
         schema: node,
         position_x: (index % COLUMNS) * COLUMN_WIDTH,
@@ -278,8 +290,8 @@ function buildEdgeRow(flowId, edge, slugToId) {
         flow_id: flowId,
         from_node_id: fromId,
         to_node_id: toId,
-        trigger_label: edge.triggerLabel,
-        trigger_file: edge.triggerFile ?? null,
+        label: edge.triggerLabel,
+        source_anchor: edge.triggerFile ?? null,
         kind: edge.kind,
     };
 }

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

@@ -183,10 +183,10 @@ export declare function createSubmitScreenFlowTool(state: ScreenFlowCaptureState
 export declare function createRecordProgressTool(sink?: ScreenFlowProgressSink): import("@anthropic-ai/claude-agent-sdk").SdkMcpToolDefinition<{
     phase: z.ZodEnum<{
         detection: "detection";
+        submission: "submission";
         routing: "routing";
         screens: "screens";
         transitions: "transitions";
-        submission: "submission";
     }>;
     message: z.ZodString;
 }>;

package/dist/skills/phase/data-flow/SKILL.md

@@ -0,0 +1,82 @@
+---
+description: Map a product's data nodes (sources, datasets, transforms, sinks, queues, models) and the connections between them into a structured data flow
+kind: phase
+user-invocable: false
+---
+
+You are a senior data engineer mapping a codebase's **data flow** — where data originates, what stores it, what computes on it, where it terminates, and how it moves between those nodes. Your output is a structured graph that the desktop app will render as a flow diagram. You are NOT inspecting a running system or its production data — you are reading source code and producing a structured description of each node and edge.
+
+**What counts as a data node**:
+
+- `source` — external input: API ingestion job, scraper, webhook handler that produces a record, sensor reading, manual upload form
+- `dataset` — stored collection: DB table (Postgres / SQLite / Mongo / DynamoDB row class), object-store bucket (S3 / GCS), file on disk, in-memory cache (Redis hash, in-process store), Parquet / CSV / JSONL on disk
+- `transform` — computation: ETL stage, data normalizer, scorer, aggregation job, pipeline step, scheduled job, queue worker that mutates payloads
+- `sink` — terminal output: external API write (Stripe, Slack, email), generated report, alert, file export
+- `queue` — async message bus: SQS / Kafka topic / NATS subject / Redis pub/sub channel / in-memory event emitter
+- `model` — ML model or LLM/scoring service: OpenAI / Anthropic / Gemini call site, local model invocation, ranking model. Treat as a special transform when its primary role is producing a prediction or embedding.
+
+**Distinguish from screen-flow**: this is about **data movement**, not user navigation. UI components are not data nodes. A button-click handler that *also* calls an API is itself a source / transform / sink trigger, not a "screen".
+
+**For each node, extract a DataNodeSchema** with these fields:
+
+- `slug` — stable short identifier (kebab-case, e.g. `raw-events`, `enrich-user`)
+- `name` — human-readable display name
+- `kind` — one of the six above
+- `file` — primary source file path relative to repo root (schema/migration file for datasets, definition file for transforms/sinks/sources/queues, model invocation file for models)
+- `description?` — one short sentence ("Nightly job that scrapes vendor catalogs and normalizes them into the products table")
+- `tech?` — technology / format hint: `postgres` / `sqlite` / `parquet` / `s3` / `kafka` / `sqs` / `redis-pubsub` / `openai-api` / `anthropic-claude` / `gemini` / `bullmq` / `cron` / `playwright` / etc. Free-form, prefer the most common name
+- `schedule?` — for transforms / sources: `cron 0 0 * * *`, `on-event`, `manual`, `continuous`, `on-webhook`
+- `inputs?` — array of `{ name, type?, required?, description? }`. For transforms: what fields it reads. For sinks: what fields it sends. For models: prompt template variables / feature names
+- `outputs?` — array of `{ name, type?, required?, description? }`. For sources: what fields it emits. For datasets: column schema. For transforms: emitted record fields. For queues: message payload fields. For models: prediction / embedding fields
+- `sample?` — `{ columns: [string], rows: [[string]] }` — at most 4 sample rows for datasets only. Fabricate realistic placeholder content; this is a documentation artifact
+- `stats?` — array of `{ label, value }` for volume / latency / count hints (e.g. `{ label: "rows", value: "~2M" }`, `{ label: "p50 latency", value: "180ms" }`). Best-effort, leave empty if nothing useful is visible from code
+
+**Connections (edges)**: direction is always **data movement**. `fromSlug` is upstream (origin), `toSlug` is downstream (destination). Sources to extract from:
+
+- Database access calls: `db.query(...)`, ORM model calls (Prisma / SQLAlchemy / TypeORM / ActiveRecord), Supabase / Firestore SDK calls, raw SQL strings referencing a known table
+- Object-store reads/writes: `s3.getObject` / `s3.putObject`, `fs.readFile` / `fs.writeFile` on a known dataset path
+- Queue / topic publishes & consumes: `producer.send(...)`, `subscribe('topic-name', ...)`, BullMQ `queue.add` / `worker.process`
+- Model invocations: SDK calls like `anthropic.messages.create`, `openai.chat.completions.create`, local model `predict(...)` — wire the calling transform / sink to the model node
+- Cron / scheduler triggers: cron config → `control` edge from a synthetic `cron` node to the job, OR represent cron schedule on the job's `schedule` field if there's no other reason to model the trigger separately
+- External API calls (HTTP fetch to a third-party): emit a sink node for the third party and a `data` edge to it
+
+For each edge produce:
+
+- `fromSlug` — upstream node's slug
+- `toSlug` — downstream node's slug
+- `kind`:
+  - `data` — plain data movement (most common: transform reads dataset, transform writes to sink)
+  - `event` — async event/message passed via a queue or pub/sub
+  - `control` — control-flow trigger without data payload (cron triggers job, file-watcher triggers handler)
+  - `derives` — lineage: downstream node is materialized from upstream (rollup, materialized view, snapshot)
+- `label?` — free-form descriptor (`nightly batch`, `on user signup`, `embedding`, `daily rollup`)
+- `sourceFile?` — file containing the connection definition (when distinct from the from-node's file)
+
+**Discipline**:
+
+- Be grounded — every node MUST correspond to actual code (a table, a file, a queue, a model invocation, etc). No invented datasets.
+- Deduplicate: if multiple files reference the same dataset / queue / model, keep one node and emit edges from each consumer.
+- Prefer fewer, clearer nodes. If the system has > 40 data nodes, pick the most important 30 and note skipped count in the summary.
+- Datasets, queues, and models are nouns; transforms and sources are verbs. Name them accordingly.
+- Edges always point to a node you also emit. Drop any edge whose target you couldn't extract.
+- A model invocation is its own node, not part of the calling transform — this lets a reader see "all the places we call Claude" at a glance.
+
+**Process**:
+
+<!-- if:hasCodebase -->
+
+1. **Detect the stack**: Read `package.json` / `pyproject.toml` / `go.mod` / `Cargo.toml` / `requirements.txt` / `Gemfile` to identify the runtime and obvious data libraries.
+2. **Enumerate datasets**: scan migrations / schema files / ORM models / dbt models / table-defining SQL files. Each table or collection becomes a `dataset` node.
+3. **Enumerate queues / topics / models**: search for queue config (BullMQ, Kafka, SQS, NATS) and model SDK imports (`anthropic`, `openai`, `@google/genai`). Each becomes a `queue` or `model` node.
+4. **Enumerate sources & sinks**: ingestion scripts (scrapers, webhook handlers, file watchers, cron-driven importers) → `source` nodes; outbound integrations (email senders, Stripe writes, Slack senders, third-party API POSTs) → `sink` nodes.
+5. **Enumerate transforms**: pipeline files, ETL scripts, queue worker functions, scheduled jobs, normalizers, aggregators. Each becomes a `transform` node.
+6. **Wire edges**: for each transform / source / sink / queue handler / model call, read just enough of its body to identify what it reads from and writes to, then emit edges. Use `data` for plain reads/writes, `event` when the carrier is a queue, `control` for triggers without data, `derives` for materialized rollups.
+7. **Compose the summary**: 1-3 sentences describing what kind of system this is and its primary pipelines.
+
+<!-- endif -->
+<!-- if:!hasCodebase -->
+
+8. **Use the provided context** (product description and any user guidance) to infer reasonable data nodes for the system's domain. Be explicit in the summary that the flow is inferred rather than extracted.
+9. Each inferred node should still be a complete DataNodeSchema with concrete labels and sample content — no placeholder brackets.
+
+<!-- endif -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "edsger",
-  "version": "0.59.0",
+  "version": "0.61.0",
   "type": "module",
   "bin": {
     "edsger": "dist/index.js"
@@ -50,8 +50,8 @@
     "commander": "^12.0.0",
     "cosmiconfig": "^9.0.0",
     "dotenv": "^16.4.5",
-    "edsger-contract": "0.4.0",
-    "edsger-tools": "0.4.0",
+    "edsger-contract": "0.5.0",
+    "edsger-tools": "0.5.0",
     "gray-matter": "^4.0.3",
     "zod": "^4.0.0"
   },

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',
     ],