edsger 0.69.0 → 0.71.0

package/dist/phases/er-diagram/types.js

@@ -0,0 +1,84 @@
+/**
+ * ER Diagram domain types.
+ *
+ * An ErEntity is a structured description of one persistence entity in a
+ * product — a table, a view, or an enum. The CLI extracts these from schema
+ * files (migrations, ORM models, type definitions) and the desktop renders
+ * them as an entity-relationship diagram.
+ *
+ * Companion to DataNodeSchema / ScreenSchema: same flow-graph shape (nodes +
+ * edges sharing the `diagrams` table storing the JSONB schema), different domain.
+ * ER edges describe foreign-key / inheritance relationships between entities,
+ * with a cardinality, not data movement or user navigation.
+ */
+// ============================================================================
+// Runtime validation for AI-produced extraction
+// ============================================================================
+const ENTITY_KINDS = new Set([
+    'entity',
+    'view',
+    'enum',
+    'junction',
+]);
+const RELATION_KINDS = new Set([
+    'one-to-one',
+    'one-to-many',
+    'many-to-many',
+    'inherits',
+]);
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function isErEntity(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    if (typeof value.slug !== 'string' || value.slug.length === 0) {
+        return false;
+    }
+    if (typeof value.name !== 'string' || value.name.length === 0) {
+        return false;
+    }
+    if (typeof value.kind !== 'string' ||
+        !ENTITY_KINDS.has(value.kind)) {
+        return false;
+    }
+    return true;
+}
+function isErRelation(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    if (typeof value.fromSlug !== 'string') {
+        return false;
+    }
+    if (typeof value.toSlug !== 'string') {
+        return false;
+    }
+    if (typeof value.kind !== 'string' ||
+        !RELATION_KINDS.has(value.kind)) {
+        return false;
+    }
+    return true;
+}
+export function isErDiagramExtraction(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    if (typeof value.summary !== 'string') {
+        return false;
+    }
+    if (!Array.isArray(value.entities)) {
+        return false;
+    }
+    if (!Array.isArray(value.relations)) {
+        return false;
+    }
+    if (!value.entities.every(isErEntity)) {
+        return false;
+    }
+    if (!value.relations.every(isErRelation)) {
+        return false;
+    }
+    return true;
+}

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

@@ -0,0 +1,15 @@
+/**
+ * flowchart phase: map the control flow of one process / function / algorithm
+ * as a flowchart — start/end, process steps, decisions (with branch labels),
+ * I/O, and subroutine calls. Persisted to the diagrams tables with
+ * `type = 'flowchart'`.
+ */
+import { type DiagramPhaseResult } from '../diagram-shared/generate.js';
+export interface FlowchartPhaseOptions {
+    productId?: string;
+    repoId?: string;
+    diagramId: string;
+    guidance?: string;
+    verbose?: boolean;
+}
+export declare function runFlowchartPhase(options: FlowchartPhaseOptions): Promise<DiagramPhaseResult>;

package/dist/phases/flowchart/index.js

@@ -0,0 +1,50 @@
+/**
+ * flowchart phase: map the control flow of one process / function / algorithm
+ * as a flowchart — start/end, process steps, decisions (with branch labels),
+ * I/O, and subroutine calls. Persisted to the diagrams tables with
+ * `type = 'flowchart'`.
+ */
+import { z } from 'zod';
+import { generateDiagram, } from '../diagram-shared/generate.js';
+import { buildDiagramSystemPrompt, buildDiagramUserPrompt, } from '../diagram-shared/prompts.js';
+const flowchartNode = z.object({
+    slug: z.string().min(1),
+    name: z.string().min(1),
+    kind: z.enum(['start', 'end', 'process', 'decision', 'io', 'subroutine']),
+    file: z.string().optional(),
+    description: z.string().optional(),
+});
+const flowchartEdge = z.object({
+    fromSlug: z.string().min(1),
+    toSlug: z.string().min(1),
+    kind: z.enum(['flow', 'branch']),
+    /** Branch label for edges out of a decision, e.g. "yes" / "no" / "error". */
+    label: z.string().optional(),
+    sourceFile: z.string().optional(),
+});
+export function runFlowchartPhase(options) {
+    return generateDiagram({
+        ...options,
+        workspaceKey: 'flowchart',
+        fenceName: 'flowchart',
+        nounPlural: 'steps',
+        edgeNounPlural: 'arrows',
+        mcpConfig: {
+            name: 'flowchart',
+            toolName: 'flowchart',
+            summaryDescribe: '1-3 sentence narrative of the process this flowchart captures.',
+            nodesSchema: z.array(flowchartNode),
+            nodesDescribe: 'Every step: start / end / process / decision / io / subroutine. slug MUST be unique. Use exactly one `start`.',
+            edgesSchema: z.array(flowchartEdge),
+            edgesDescribe: 'Arrows. kind = flow (plain) or branch (out of a decision; set label to the branch condition like "yes"/"no"). Endpoints MUST reference emitted steps.',
+        },
+        buildSystemPrompt: (a) => buildDiagramSystemPrompt('phase/flowchart', 'flowchart', a),
+        buildUserPrompt: (a) => buildDiagramUserPrompt({
+            ...a,
+            task: 'Map a flowchart for',
+            mcpName: 'flowchart',
+            toolName: 'flowchart',
+            process: 'Pick ONE important process / function / algorithm (guidance may name it; otherwise choose a central one — a request handler, a core algorithm, a job). Read it top to bottom and translate its control flow into steps: a single `start`, `process` steps for actions, `decision` diamonds for branches (each outgoing edge a `branch` with a "yes"/"no"/condition label), `io` for reads/writes, `subroutine` for significant calls, and `end` node(s) for returns/exits. Follow the happy path plus the important branches.',
+        }),
+    });
+}

package/dist/phases/output-contracts.js

@@ -917,7 +917,7 @@ to keep the user informed during long runs. This is observability only — it
 does not affect the extraction.
 
 ScreenSchema fields:
-- \`slug\` (unique within the flow), \`name\`, \`route?\`, \`file?\`
+- \`slug\` (unique within the diagram), \`name\`, \`route?\`, \`file?\`
 - \`kind\`: one of \`page\`, \`modal\`, \`drawer\`, \`tab\`, \`state\`
 - \`layout\`: one of \`centered\`, \`sidebar\`, \`split\`, \`list-detail\`, \`tabs\`, \`stacked\`
 - \`header?\`: \`{ title, subtitle?, back?, actions?: [{ label, variant?, icon? }] }\`
@@ -971,7 +971,7 @@ to keep the user informed during long runs. This is observability only — it
 does not affect the extraction.
 
 DataNodeSchema fields:
-- \`slug\` (unique within the flow), \`name\`, \`kind\`, \`file?\`
+- \`slug\` (unique within the diagram), \`name\`, \`kind\`, \`file?\`
 - \`kind\`: one of \`source\`, \`dataset\`, \`transform\`, \`sink\`, \`queue\`, \`model\`
 - \`description?\`: one-sentence summary
 - \`tech?\`: technology / format hint (e.g. \`postgres\`, \`parquet\`, \`kafka\`, \`openai-api\`)
@@ -1021,5 +1021,181 @@ submit_data_flow({
   ]
 })
 \`\`\`
+`,
+    'er-diagram': `
+**CRITICAL — How to return the result**:
+
+Return the extraction by calling the MCP tool
+\`mcp__er-diagram__submit_er_diagram\` **exactly once** with three arguments:
+
+- \`summary\` — 1-3 sentence narrative of the data model (core entities + relationships)
+- \`entities\` — array of ErEntity objects (every table / view / enum / junction)
+- \`relations\` — array of ErRelation objects (foreign-key / inheritance edges)
+
+The tool validates the arguments against the schema. If it returns an error,
+fix the issue it describes and call the tool again. After a successful call,
+end your turn — do not also paste the same data as a fenced text block.
+
+You can also call \`mcp__er-diagram__record_progress({ phase, message })\` at
+each phase boundary (detection / enumeration / entities / relations / submission)
+to keep the user informed during long runs. This is observability only — it
+does not affect the extraction.
+
+ErEntity fields:
+- \`slug\` (unique within the diagram), \`name\`, \`kind\`, \`file?\`
+- \`kind\`: one of \`entity\`, \`view\`, \`enum\`, \`junction\`
+- \`description?\`: one-sentence summary
+- \`columns?\`: array of \`{ name, type?, isPrimaryKey?, isForeignKey?, isNullable?, isUnique?, description?, references? }\`
+  - \`references\`: for FKs, \`target-entity-slug.column\` (e.g. \`users.id\`)
+- \`stats?\`: array of \`{ label, value }\` (row counts, cardinality hints)
+
+ErRelation fields:
+- \`fromSlug\` (child / FK holder), \`toSlug\` (parent / referenced) — both MUST appear in entities
+- \`kind\`: one of \`one-to-one\`, \`one-to-many\`, \`many-to-many\`, \`inherits\`
+- \`label?\`: free-form descriptor (e.g. \`placed by\`, \`belongs to\`)
+- \`sourceColumn?\` / \`targetColumn?\`: the FK column and the referenced column
+- \`sourceFile?\`: file containing the FK constraint / association
+
+Direction convention: fromSlug holds the foreign key (child / "many" side),
+toSlug is the referenced entity (parent / "one" side). \`orders.user_id → users.id\`
+becomes \`{ fromSlug: "orders", toSlug: "users", kind: "one-to-many" }\`.
+
+Schematic example of the tool call:
+
+\`\`\`
+submit_er_diagram({
+  summary: "Storefront schema: users place orders made of order-items that reference products; roles are linked to users through a junction table.",
+  entities: [
+    { slug: "users", name: "users", kind: "entity",
+      file: "db/migrations/0001_users.sql",
+      columns: [
+        { name: "id", type: "uuid", isPrimaryKey: true },
+        { name: "email", type: "varchar(255)", isUnique: true },
+        { name: "created_at", type: "timestamptz" }
+      ] },
+    { slug: "orders", name: "orders", kind: "entity",
+      file: "db/migrations/0002_orders.sql",
+      columns: [
+        { name: "id", type: "uuid", isPrimaryKey: true },
+        { name: "user_id", type: "uuid", isForeignKey: true, references: "users.id" },
+        { name: "status", type: "order_status" }
+      ] },
+    { slug: "order-status", name: "order_status", kind: "enum",
+      file: "db/migrations/0002_orders.sql" }
+  ],
+  relations: [
+    { fromSlug: "orders", toSlug: "users", kind: "one-to-many",
+      label: "placed by", sourceColumn: "user_id", targetColumn: "id",
+      sourceFile: "db/migrations/0002_orders.sql" }
+  ]
+})
+\`\`\`
+`,
+    'sequence-diagram': `
+**CRITICAL — How to return the result**:
+
+Return the extraction by calling the MCP tool
+\`mcp__sequence-diagram__submit_sequence_diagram\` **exactly once** with three arguments:
+
+- \`summary\` — 1-3 sentence narrative naming the scenario, the participants, and the outcome
+- \`participants\` — array of SequenceParticipant objects (every lifeline)
+- \`messages\` — array of SequenceMessage objects, each with an explicit \`order\`
+
+The tool validates the arguments against the schema. If it returns an error,
+fix the issue it describes and call the tool again. After a successful call,
+end your turn — do not also paste the same data as a fenced text block.
+
+You can also call \`mcp__sequence-diagram__record_progress({ phase, message })\`
+at each phase boundary (detection / enumeration / participants / messages /
+submission) to keep the user informed during long runs. This is observability
+only — it does not affect the extraction.
+
+A sequence diagram captures ONE scenario. Map a single end-to-end flow of control.
+
+SequenceParticipant fields:
+- \`slug\` (unique within the diagram), \`name\`, \`kind\`, \`file?\`
+- \`kind\`: one of \`actor\`, \`service\`, \`component\`, \`database\`, \`queue\`, \`external\`
+- \`description?\`: one-sentence role summary
+
+SequenceMessage fields:
+- \`fromSlug\` (sender), \`toSlug\` (receiver) — both MUST appear in participants
+- \`kind\`: one of \`sync\`, \`async\`, \`return\`, \`self\`
+- \`order\`: **1-based integer** position in the execution timeline (do not skip or reuse numbers)
+- \`label?\`: the call / message text (\`POST /login\`, \`validateToken(jwt)\`, \`rows\`)
+- \`sourceFile?\`: file (+ line) where the call happens
+
+Order convention: number messages in real execution order; a \`return\` comes
+after the \`sync\` call it answers. A \`self\` message has \`fromSlug === toSlug\`.
+
+Schematic example of the tool call:
+
+\`\`\`
+submit_sequence_diagram({
+  summary: "Email/password login: the browser posts credentials to AuthService, which verifies them against the users table and issues a JWT.",
+  participants: [
+    { slug: "user", name: "User", kind: "actor" },
+    { slug: "auth-service", name: "AuthService", kind: "service",
+      file: "src/routes/auth.ts" },
+    { slug: "users", name: "users", kind: "database",
+      file: "db/migrations/0001_users.sql" }
+  ],
+  messages: [
+    { fromSlug: "user", toSlug: "auth-service", kind: "sync", order: 1,
+      label: "POST /login {email, password}", sourceFile: "src/routes/auth.ts" },
+    { fromSlug: "auth-service", toSlug: "users", kind: "sync", order: 2,
+      label: "SELECT … WHERE email = ?", sourceFile: "src/routes/auth.ts" },
+    { fromSlug: "users", toSlug: "auth-service", kind: "return", order: 3,
+      label: "user row" },
+    { fromSlug: "auth-service", toSlug: "auth-service", kind: "self", order: 4,
+      label: "verifyPassword()" },
+    { fromSlug: "auth-service", toSlug: "user", kind: "return", order: 5,
+      label: "200 {token}" }
+  ]
+})
+\`\`\`
+`,
+    'state-diagram': `
+**CRITICAL — How to return the result**:
+
+Call \`mcp__state-diagram__submit_state_diagram\` **exactly once** with:
+- \`summary\` — what this state machine models
+- \`nodes\` — states: \`{ slug, name, kind, file?, description?, onEntry?, onExit?, activity? }\`; \`kind\` ∈ \`initial\` | \`state\` | \`final\` | \`choice\` | \`composite\` (exactly one \`initial\`)
+- \`edges\` — transitions: \`{ fromSlug, toSlug, kind: "transition", label?, sourceFile? }\`; put \`trigger [guard] / action\` in \`label\`
+
+Every fromSlug / toSlug MUST reference a node slug. The tool validates; on error,
+fix and call again. You may call \`mcp__state-diagram__record_progress\` for status.
+`,
+    'class-diagram': `
+**CRITICAL — How to return the result**:
+
+Call \`mcp__class-diagram__submit_class_diagram\` **exactly once** with:
+- \`summary\` — the core types and how they relate
+- \`nodes\` — \`{ slug, name, kind, file?, description?, stereotype?, attributes?: [{ name, type?, visibility?, isStatic? }], methods?: [{ name, params?, returnType?, visibility?, isStatic?, isAbstract? }] }\`; \`kind\` ∈ \`class\` | \`interface\` | \`abstract\` | \`enum\`
+- \`edges\` — \`{ fromSlug, toSlug, kind, label?, sourceFile? }\`; \`kind\` ∈ \`inheritance\` | \`implementation\` | \`composition\` | \`aggregation\` | \`association\` | \`dependency\` (fromSlug = child/owner/dependent)
+
+Every fromSlug / toSlug MUST reference a node slug. The tool validates; on error,
+fix and call again. You may call \`mcp__class-diagram__record_progress\` for status.
+`,
+    'architecture-diagram': `
+**CRITICAL — How to return the result**:
+
+Call \`mcp__architecture-diagram__submit_architecture_diagram\` **exactly once** with:
+- \`summary\` — the architecture and its main building blocks
+- \`nodes\` — components: \`{ slug, name, kind, file?, description?, tech?, responsibilities?: [string] }\`; \`kind\` ∈ \`module\` | \`service\` | \`package\` | \`ui\` | \`datastore\` | \`external\`
+- \`edges\` — dependencies: \`{ fromSlug, toSlug, kind, label?, sourceFile? }\`; \`kind\` ∈ \`depends-on\` | \`calls\` | \`imports\` | \`data\` (fromSlug = depender)
+
+Every fromSlug / toSlug MUST reference a node slug. The tool validates; on error,
+fix and call again. You may call \`mcp__architecture-diagram__record_progress\` for status.
+`,
+    flowchart: `
+**CRITICAL — How to return the result**:
+
+Call \`mcp__flowchart__submit_flowchart\` **exactly once** with:
+- \`summary\` — the process this flowchart captures
+- \`nodes\` — steps: \`{ slug, name, kind, file?, description? }\`; \`kind\` ∈ \`start\` | \`end\` | \`process\` | \`decision\` | \`io\` | \`subroutine\` (exactly one \`start\`)
+- \`edges\` — \`{ fromSlug, toSlug, kind, label?, sourceFile? }\`; \`kind\` ∈ \`flow\` | \`branch\` (branch edges out of a \`decision\` set \`label\` to "yes"/"no"/condition)
+
+Every fromSlug / toSlug MUST reference a node slug. The tool validates; on error,
+fix and call again. You may call \`mcp__flowchart__record_progress\` for status.
 `,
 };

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 flows / flow_nodes /
- * flow_edges (rows tagged `type = 'screen'`) via the Supabase SDK.
+ * ScreenFlowExtraction, then persist the result to diagrams / diagram_nodes /
+ * diagram_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.
@@ -12,7 +12,7 @@ export interface ScreenFlowOptions {
     productId?: string;
     /** Repo-only flow: a single repositories row, no product context. */
     repoId?: string;
-    flowId: string;
+    diagramId: string;
     guidance?: string;
     verbose?: boolean;
 }

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 flows / flow_nodes /
- * flow_edges (rows tagged `type = 'screen'`) via the Supabase SDK.
+ * ScreenFlowExtraction, then persist the result to diagrams / diagram_nodes /
+ * diagram_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.
@@ -11,10 +11,10 @@ import { query } from '@anthropic-ai/claude-agent-sdk';
 import { getRepositoryBasics } 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 { logError, logInfo, logSuccess, logWarning, } from '../../utils/logger.js';
 import { cleanupIssueRepo } from '../../workspace/workspace-manager.js';
+import { cloneDiagramRepos, describeRepoScope, } from '../diagram-shared/clone-repos.js';
 import { fetchProductBasics } from '../find-shared/mcp.js';
-import { cloneFlowRepos, describeRepoScope } from '../flow-shared/clone-repos.js';
 import { createPromptGenerator, extractTextFromContent, tryExtractResult, } from '../pr-shared/agent-utils.js';
 import { createScreenFlowCaptureState, createScreenFlowMcpServer, validateConsistency, } from './mcp-server.js';
 import { createScreenFlowSystemPrompt, createScreenFlowUserPrompt, } from './prompts.js';
@@ -27,7 +27,7 @@ const COLUMN_WIDTH = 380;
 const ROW_HEIGHT = 480;
 const COLUMNS = 4;
 export async function runScreenFlowPhase(options) {
-    const { productId, repoId, flowId, guidance, verbose } = options;
+    const { productId, repoId, diagramId, guidance, verbose } = options;
     const repoOnly = !productId && Boolean(repoId);
     if (productId) {
         logInfo(`Starting screen-flow generation for product ${productId}`);
@@ -36,9 +36,9 @@ export async function runScreenFlowPhase(options) {
         logInfo(`Starting screen-flow generation for repository ${repoId}`);
     }
     const supabase = getSupabase();
-    await markFlowRunning(supabase, flowId);
-    const repositoryIds = await getFlowRepositoryIds(supabase, flowId);
-    const cloneResult = await cloneFlowRepos({
+    await markDiagramRunning(supabase, diagramId);
+    const repositoryIds = await getDiagramRepositoryIds(supabase, diagramId);
+    const cloneResult = await cloneDiagramRepos({
         productId,
         repoId,
         repositoryIds,
@@ -46,7 +46,7 @@ export async function runScreenFlowPhase(options) {
         verbose,
     });
     if (!cloneResult.ok) {
-        await markFlowFailed(supabase, flowId, cloneResult.message);
+        await markDiagramFailed(supabase, diagramId, cloneResult.message);
         return { status: 'error', message: cloneResult.message };
     }
     const { projectDir, cleanupDir, repos } = cloneResult;
@@ -104,17 +104,19 @@ export async function runScreenFlowPhase(options) {
         }
         if (!extraction) {
             const msg = 'Screen flow extraction failed: agent did not call submit_screen_flow and no parseable screen_flow block was found in the response';
-            await markFlowFailed(supabase, flowId, msg);
+            await markDiagramFailed(supabase, diagramId, msg);
             return { status: 'error', message: msg };
         }
         logInfo(`Extraction produced ${extraction.nodes.length} screens / ${extraction.edges.length} transitions`);
         const theme = resolveTheme(extraction.theme, repos);
         if (Object.keys(theme).length > 0) {
-            logInfo(`Theme: ${Object.entries(theme).map(([k, v]) => `${k}=${v}`).join(', ')}`);
-            await persistTheme(supabase, flowId, theme);
+            logInfo(`Theme: ${Object.entries(theme)
+                .map(([k, v]) => `${k}=${v}`)
+                .join(', ')}`);
+            await persistTheme(supabase, diagramId, theme);
         }
-        const { nodesCreated, edgesCreated } = await persistFlow(supabase, flowId, extraction);
-        await markFlowSuccess(supabase, flowId, extraction.summary);
+        const { nodesCreated, edgesCreated } = await persistDiagram(supabase, diagramId, extraction);
+        await markDiagramSuccess(supabase, diagramId, extraction.summary);
         succeeded = true;
         logSuccess(`Screen flow generated: ${nodesCreated} screens, ${edgesCreated} transitions`);
         return {
@@ -128,7 +130,7 @@ export async function runScreenFlowPhase(options) {
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);
         logError(`Screen flow failed: ${errorMessage}`);
-        await markFlowFailed(supabase, flowId, errorMessage);
+        await markDiagramFailed(supabase, diagramId, errorMessage);
         return { status: 'error', message: errorMessage };
     }
     finally {
@@ -169,12 +171,12 @@ async function resolveRepoBasics(repositoryId, repos) {
         description: basics?.description ?? undefined,
     };
 }
-/** Read the ordered repo set a flow was scoped to (may be empty). */
-async function getFlowRepositoryIds(supabase, flowId) {
+/** Read the ordered repo set a diagram was scoped to (may be empty). */
+async function getDiagramRepositoryIds(supabase, diagramId) {
     const { data } = await supabase
-        .from('flows')
+        .from('diagrams')
         .select('repository_ids')
-        .eq('id', flowId)
+        .eq('id', diagramId)
         .single();
     return (data?.repository_ids ?? []).filter(Boolean);
 }
@@ -234,31 +236,31 @@ function tryFallbackParse(resultMessage, assistantText) {
 // ============================================================================
 // Persistence
 // ============================================================================
-async function markFlowRunning(supabase, flowId) {
+async function markDiagramRunning(supabase, diagramId) {
     const { error } = await supabase
-        .from('flows')
+        .from('diagrams')
         .update({ status: 'running', error: null })
-        .eq('id', flowId);
+        .eq('id', diagramId);
     if (error) {
-        logWarning(`Could not mark flow as running: ${error.message}`);
+        logWarning(`Could not mark diagram as running: ${error.message}`);
     }
 }
-async function markFlowFailed(supabase, flowId, errorMessage) {
+async function markDiagramFailed(supabase, diagramId, errorMessage) {
     await supabase
-        .from('flows')
+        .from('diagrams')
         .update({
         status: 'failed',
         error: errorMessage,
         completed_at: new Date().toISOString(),
     })
-        .eq('id', flowId);
+        .eq('id', diagramId);
 }
-async function persistTheme(supabase, flowId, theme) {
+async function persistTheme(supabase, diagramId, theme) {
     // Theme is screen-flow-specific; stash it inside the generic options JSONB.
     const { data, error: readError } = await supabase
-        .from('flows')
+        .from('diagrams')
         .select('options')
-        .eq('id', flowId)
+        .eq('id', diagramId)
         .single();
     if (readError) {
         logWarning(`Could not read flow options: ${readError.message}`);
@@ -269,34 +271,34 @@ async function persistTheme(supabase, flowId, theme) {
         theme,
     };
     const { error } = await supabase
-        .from('flows')
+        .from('diagrams')
         .update({ options: nextOptions })
-        .eq('id', flowId);
+        .eq('id', diagramId);
     if (error) {
         logWarning(`Could not persist extracted theme: ${error.message}`);
     }
 }
-async function markFlowSuccess(supabase, flowId, summary) {
+async function markDiagramSuccess(supabase, diagramId, summary) {
     await supabase
-        .from('flows')
+        .from('diagrams')
         .update({
         status: 'success',
         summary,
         error: null,
         completed_at: new Date().toISOString(),
     })
-        .eq('id', flowId);
+        .eq('id', diagramId);
 }
-async function persistFlow(supabase, flowId, extraction) {
+async function persistDiagram(supabase, diagramId, extraction) {
     // Re-runs replace prior content for the same flow row.
-    await supabase.from('flow_edges').delete().eq('flow_id', flowId);
-    await supabase.from('flow_nodes').delete().eq('flow_id', flowId);
+    await supabase.from('diagram_edges').delete().eq('diagram_id', diagramId);
+    await supabase.from('diagram_nodes').delete().eq('diagram_id', diagramId);
     if (extraction.nodes.length === 0) {
         return { nodesCreated: 0, edgesCreated: 0 };
     }
-    const nodeRows = extraction.nodes.map((n, i) => buildNodeRow(flowId, n, i));
+    const nodeRows = extraction.nodes.map((n, i) => buildNodeRow(diagramId, n, i));
     const { data: insertedNodes, error: nodesError } = await supabase
-        .from('flow_nodes')
+        .from('diagram_nodes')
         .insert(nodeRows)
         .select('id, slug');
     if (nodesError) {
@@ -304,11 +306,11 @@ async function persistFlow(supabase, flowId, extraction) {
     }
     const slugToId = new Map((insertedNodes ?? []).map((n) => [n.slug, n.id]));
     const edgeRows = extraction.edges
-        .map((e) => buildEdgeRow(flowId, e, slugToId))
+        .map((e) => buildEdgeRow(diagramId, e, slugToId))
         .filter((e) => e !== null);
     if (edgeRows.length > 0) {
         const { error: edgesError } = await supabase
-            .from('flow_edges')
+            .from('diagram_edges')
             .insert(edgeRows);
         if (edgesError) {
             throw new Error(`Failed to insert edges: ${edgesError.message}`);
@@ -319,9 +321,9 @@ async function persistFlow(supabase, flowId, extraction) {
         edgesCreated: edgeRows.length,
     };
 }
-function buildNodeRow(flowId, node, index) {
+function buildNodeRow(diagramId, node, index) {
     return {
-        flow_id: flowId,
+        diagram_id: diagramId,
         slug: node.slug,
         name: node.name,
         kind: node.kind,
@@ -330,14 +332,14 @@ function buildNodeRow(flowId, node, index) {
         position_y: Math.floor(index / COLUMNS) * ROW_HEIGHT,
     };
 }
-function buildEdgeRow(flowId, edge, slugToId) {
+function buildEdgeRow(diagramId, edge, slugToId) {
     const fromId = slugToId.get(edge.fromSlug);
     const toId = slugToId.get(edge.toSlug);
     if (!fromId || !toId) {
         return null;
     }
     return {
-        flow_id: flowId,
+        diagram_id: diagramId,
         from_node_id: fromId,
         to_node_id: toId,
         label: edge.triggerLabel,

package/dist/phases/screen-flow/mcp-server.js

@@ -166,7 +166,7 @@ export function validateConsistency(extraction) {
     for (const node of extraction.nodes) {
         if (slugs.has(node.slug)) {
             return {
-                error: `Duplicate node slug "${node.slug}". Each node.slug MUST be unique within the flow. Re-call submit_screen_flow with deduplicated nodes.`,
+                error: `Duplicate node slug "${node.slug}". Each node.slug MUST be unique within the diagram. Re-call submit_screen_flow with deduplicated nodes.`,
             };
         }
         slugs.add(node.slug);
@@ -208,7 +208,7 @@ export function createSubmitScreenFlowTool(state) {
             .describe('1-3 sentence narrative of what kind of app this is and its primary user flows.'),
         nodes: z
             .array(screenNodeSchema)
-            .describe('Every user-facing screen, modal, drawer, tab, or named state. node.slug MUST be unique within the flow.'),
+            .describe('Every user-facing screen, modal, drawer, tab, or named state. node.slug MUST be unique within the diagram.'),
         edges: z
             .array(screenEdgeSchema)
             .describe('Transitions between screens. Every fromSlug / toSlug MUST reference a slug present in nodes; drop edges whose endpoints you did not emit.'),

package/dist/phases/sequence-diagram/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * sequence-diagram phase: clone the product's repo, ask Claude to trace one
+ * scenario through the code and map the participants (actor / service /
+ * component / database / queue / external) and the ordered messages between
+ * them into a structured SequenceDiagramExtraction, then persist the result
+ * to diagrams / diagram_nodes / diagram_edges (rows tagged `type = 'sequence'`) via the
+ * Supabase SDK.
+ *
+ * Companion to data-flow / screen-flow / er-diagram: same generation pattern
+ * (workspace clone + Claude Agent SDK + in-process MCP server), same storage
+ * tables, different domain. Message ordering is persisted in the edge's
+ * `metadata.order`.
+ */
+export interface SequenceDiagramPhaseOptions {
+    /** Product-scoped diagram. Mutually exclusive with `repoId`. */
+    productId?: string;
+    /** Repo-only diagram: a single repositories row, no product context. */
+    repoId?: string;
+    diagramId: string;
+    guidance?: string;
+    verbose?: boolean;
+}
+export interface SequenceDiagramPhaseResult {
+    status: 'success' | 'error';
+    message: string;
+    nodesCreated?: number;
+    edgesCreated?: number;
+    summary?: string;
+}
+export declare function runSequenceDiagramPhase(options: SequenceDiagramPhaseOptions): Promise<SequenceDiagramPhaseResult>;