edsger 0.69.0 → 0.70.0

package/dist/phases/architecture-diagram/index.js

@@ -0,0 +1,51 @@
+/**
+ * architecture-diagram phase: map a component/dependency diagram (C4-ish) —
+ * the modules / services / packages / datastores / external systems that make
+ * up the product and how they depend on one another. Persisted to the
+ * diagrams tables with `type = 'architecture'`.
+ */
+import { z } from 'zod';
+import { generateDiagram, } from '../diagram-shared/generate.js';
+import { buildDiagramSystemPrompt, buildDiagramUserPrompt, } from '../diagram-shared/prompts.js';
+const archNode = z.object({
+    slug: z.string().min(1),
+    name: z.string().min(1),
+    kind: z.enum(['module', 'service', 'package', 'ui', 'datastore', 'external']),
+    file: z.string().optional(),
+    description: z.string().optional(),
+    tech: z.string().optional(),
+    responsibilities: z.array(z.string()).optional(),
+});
+const archEdge = z.object({
+    fromSlug: z.string().min(1),
+    toSlug: z.string().min(1),
+    kind: z.enum(['depends-on', 'calls', 'imports', 'data']),
+    label: z.string().optional(),
+    sourceFile: z.string().optional(),
+});
+export function runArchitectureDiagramPhase(options) {
+    return generateDiagram({
+        ...options,
+        workspaceKey: 'architecture-diagram',
+        fenceName: 'architecture_diagram',
+        nounPlural: 'components',
+        edgeNounPlural: 'dependencies',
+        mcpConfig: {
+            name: 'architecture-diagram',
+            toolName: 'architecture_diagram',
+            summaryDescribe: '1-3 sentence narrative of the system architecture and its main building blocks.',
+            nodesSchema: z.array(archNode),
+            nodesDescribe: 'Every component: module / service / package / ui / datastore / external. slug MUST be unique.',
+            edgesSchema: z.array(archEdge),
+            edgesDescribe: 'Dependencies. kind = depends-on / calls / imports / data. fromSlug is the depender. Endpoints MUST reference emitted components.',
+        },
+        buildSystemPrompt: (a) => buildDiagramSystemPrompt('phase/architecture-diagram', 'architecture-diagram', a),
+        buildUserPrompt: (a) => buildDiagramUserPrompt({
+            ...a,
+            task: 'Map the architecture (component & dependency) diagram for',
+            mcpName: 'architecture-diagram',
+            toolName: 'architecture_diagram',
+            process: 'Detect the stack and the top-level structure (workspaces/packages, service boundaries, top-level src dirs, deployment units). Treat each meaningful unit as a component of the right kind (a UI/front-end, backend services, internal modules/packages, datastores, third-party/external systems). Wire dependency edges from the import graph, cross-service calls, and datastore/external access. Aim for a readable ~10-25 components — group leaf files into their module; do not draw a file-level graph.',
+        }),
+    });
+}

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

@@ -0,0 +1,14 @@
+/**
+ * class-diagram phase: map a UML class diagram — classes / interfaces / enums
+ * with their members, and the inheritance / composition / association edges
+ * between them. Persisted to the diagrams tables with `type = 'class'`.
+ */
+import { type DiagramPhaseResult } from '../diagram-shared/generate.js';
+export interface ClassDiagramPhaseOptions {
+    productId?: string;
+    repoId?: string;
+    diagramId: string;
+    guidance?: string;
+    verbose?: boolean;
+}
+export declare function runClassDiagramPhase(options: ClassDiagramPhaseOptions): Promise<DiagramPhaseResult>;

package/dist/phases/class-diagram/index.js

@@ -0,0 +1,76 @@
+/**
+ * class-diagram phase: map a UML class diagram — classes / interfaces / enums
+ * with their members, and the inheritance / composition / association edges
+ * between them. Persisted to the diagrams tables with `type = 'class'`.
+ */
+import { z } from 'zod';
+import { generateDiagram, } from '../diagram-shared/generate.js';
+import { buildDiagramSystemPrompt, buildDiagramUserPrompt, } from '../diagram-shared/prompts.js';
+const visibility = z.enum(['public', 'private', 'protected']);
+const classNode = z.object({
+    slug: z.string().min(1),
+    name: z.string().min(1),
+    kind: z.enum(['class', 'interface', 'abstract', 'enum']),
+    file: z.string().optional(),
+    description: z.string().optional(),
+    stereotype: z.string().optional(),
+    attributes: z
+        .array(z.object({
+        name: z.string(),
+        type: z.string().optional(),
+        visibility: visibility.optional(),
+        isStatic: z.boolean().optional(),
+    }))
+        .optional(),
+    methods: z
+        .array(z.object({
+        name: z.string(),
+        params: z.string().optional(),
+        returnType: z.string().optional(),
+        visibility: visibility.optional(),
+        isStatic: z.boolean().optional(),
+        isAbstract: z.boolean().optional(),
+    }))
+        .optional(),
+});
+const classEdge = z.object({
+    fromSlug: z.string().min(1),
+    toSlug: z.string().min(1),
+    kind: z.enum([
+        'inheritance',
+        'implementation',
+        'composition',
+        'aggregation',
+        'association',
+        'dependency',
+    ]),
+    /** Role name or multiplicity, e.g. "1..*", "owns". */
+    label: z.string().optional(),
+    sourceFile: z.string().optional(),
+});
+export function runClassDiagramPhase(options) {
+    return generateDiagram({
+        ...options,
+        workspaceKey: 'class-diagram',
+        fenceName: 'class_diagram',
+        nounPlural: 'classes',
+        edgeNounPlural: 'relationships',
+        mcpConfig: {
+            name: 'class-diagram',
+            toolName: 'class_diagram',
+            summaryDescribe: '1-3 sentence narrative of the core types and how they relate.',
+            nodesSchema: z.array(classNode),
+            nodesDescribe: 'Every class / interface / abstract / enum with its key attributes and methods. slug MUST be unique.',
+            edgesSchema: z.array(classEdge),
+            edgesDescribe: 'Relationships. kind = inheritance / implementation / composition / aggregation / association / dependency. fromSlug is the child / owner / dependent side. Endpoints MUST reference emitted classes.',
+        },
+        buildSystemPrompt: (a) => buildDiagramSystemPrompt('phase/class-diagram', 'class-diagram', a),
+        buildUserPrompt: (a) => buildDiagramUserPrompt({
+            ...a,
+            task: 'Map a UML class diagram for',
+            mcpName: 'class-diagram',
+            toolName: 'class_diagram',
+            process: 'Detect the language/OO model, then map the core domain types — classes, interfaces, abstract base types, enums — capturing each one\'s defining attributes and methods (visibility + static/abstract where it matters; you need not list every member of huge types). Wire edges: `inheritance` (extends), `implementation` (implements), `composition`/`aggregation` (owns/holds), `association` (references), `dependency` (uses). Prefer the ~30 most important types if there are many.',
+        }),
+    });
+}

package/dist/phases/data-flow/index.d.ts

@@ -2,7 +2,7 @@
  * data-flow phase: clone the product's repo, ask Claude to map every data
  * node (source / dataset / transform / sink / queue / model) and the
  * connections between them into a structured DataFlowExtraction, then
- * persist the result to flows / flow_nodes / flow_edges (rows tagged
+ * persist the result to diagrams / diagram_nodes / diagram_edges (rows tagged
  * `type = 'data'`) via the Supabase SDK.
  *
  * Companion to screen-flow: same generation pattern (workspace clone +
@@ -14,7 +14,7 @@ export interface DataFlowPhaseOptions {
     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/data-flow/index.js

@@ -2,7 +2,7 @@
  * data-flow phase: clone the product's repo, ask Claude to map every data
  * node (source / dataset / transform / sink / queue / model) and the
  * connections between them into a structured DataFlowExtraction, then
- * persist the result to flows / flow_nodes / flow_edges (rows tagged
+ * persist the result to diagrams / diagram_nodes / diagram_edges (rows tagged
  * `type = 'data'`) via the Supabase SDK.
  *
  * Companion to screen-flow: same generation pattern (workspace clone +
@@ -16,7 +16,7 @@ import { getSupabase } from '../../supabase/client.js';
 import { logError, logInfo, logSuccess, logWarning } from '../../utils/logger.js';
 import { cleanupIssueRepo } from '../../workspace/workspace-manager.js';
 import { fetchProductBasics } from '../find-shared/mcp.js';
-import { cloneFlowRepos, describeRepoScope } from '../flow-shared/clone-repos.js';
+import { cloneDiagramRepos, describeRepoScope } from '../diagram-shared/clone-repos.js';
 import { createPromptGenerator, extractTextFromContent, tryExtractResult, } from '../pr-shared/agent-utils.js';
 import { createDataFlowCaptureState, createDataFlowMcpServer, validateConsistency, } from './mcp-server.js';
 import { createDataFlowSystemPrompt, createDataFlowUserPrompt, } from './prompts.js';
@@ -28,7 +28,7 @@ const COLUMN_WIDTH = 320;
 const ROW_HEIGHT = 220;
 const COLUMNS = 4;
 export async function runDataFlowPhase(options) {
-    const { productId, repoId, flowId, guidance, verbose } = options;
+    const { productId, repoId, diagramId, guidance, verbose } = options;
     const repoOnly = !productId && Boolean(repoId);
     if (productId) {
         logInfo(`Starting data-flow generation for product ${productId}`);
@@ -37,9 +37,9 @@ export async function runDataFlowPhase(options) {
         logInfo(`Starting data-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,
@@ -47,7 +47,7 @@ export async function runDataFlowPhase(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;
@@ -100,12 +100,12 @@ export async function runDataFlowPhase(options) {
         }
         if (!extraction) {
             const msg = 'Data flow extraction failed: agent did not call submit_data_flow and no parseable data_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} nodes / ${extraction.edges.length} connections`);
-        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(`Data flow generated: ${nodesCreated} nodes, ${edgesCreated} connections`);
         return {
@@ -119,7 +119,7 @@ export async function runDataFlowPhase(options) {
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);
         logError(`Data flow failed: ${errorMessage}`);
-        await markFlowFailed(supabase, flowId, errorMessage);
+        await markDiagramFailed(supabase, diagramId, errorMessage);
         return { status: 'error', message: errorMessage };
     }
     finally {
@@ -139,12 +139,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);
 }
@@ -197,45 +197,45 @@ 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 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) {
-    await supabase.from('flow_edges').delete().eq('flow_id', flowId);
-    await supabase.from('flow_nodes').delete().eq('flow_id', flowId);
+async function persistDiagram(supabase, diagramId, extraction) {
+    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) {
@@ -243,11 +243,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}`);
@@ -258,9 +258,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,
@@ -269,14 +269,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.label ?? null,

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

@@ -27,8 +27,8 @@ export declare function createSubmitDataFlowTool(state: DataFlowCaptureState): i
         kind: z.ZodEnum<{
             model: "model";
             source: "source";
-            dataset: "dataset";
             transform: "transform";
+            dataset: "dataset";
             sink: "sink";
             queue: "queue";
         }>;

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

@@ -53,7 +53,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_data_flow with deduplicated nodes.`,
+                error: `Duplicate node slug "${node.slug}". Each node.slug MUST be unique within the diagram. Re-call submit_data_flow with deduplicated nodes.`,
             };
         }
         slugs.add(node.slug);
@@ -87,7 +87,7 @@ export function createSubmitDataFlowTool(state) {
             .describe('1-3 sentence narrative of what this system does with data and the primary pipelines.'),
         nodes: z
             .array(dataNodeSchema)
-            .describe('Every data node: source / dataset / transform / sink / queue / model. node.slug MUST be unique within the flow.'),
+            .describe('Every data node: source / dataset / transform / sink / queue / model. node.slug MUST be unique within the diagram.'),
         edges: z
             .array(dataEdgeSchema)
             .describe('Connections. fromSlug = upstream, toSlug = downstream. Every fromSlug / toSlug MUST reference a slug present in nodes; drop edges whose endpoints you did not emit.'),

package/dist/phases/data-flow/types.d.ts

@@ -8,7 +8,7 @@
  * unified <DataNodePreview> component.
  *
  * Companion to ScreenSchema: same flow-graph shape (nodes + edges with a
- * shared `flows` table storing the JSONB schema), different domain. Data
+ * shared `diagrams` table storing the JSONB schema), different domain. Data
  * flow edges describe how data moves between nodes, not user navigation.
  */
 export type DataNodeKind = 'source' | 'dataset' | 'transform' | 'sink' | 'queue' | 'model';

package/dist/phases/data-flow/types.js

@@ -8,7 +8,7 @@
  * unified <DataNodePreview> component.
  *
  * Companion to ScreenSchema: same flow-graph shape (nodes + edges with a
- * shared `flows` table storing the JSONB schema), different domain. Data
+ * shared `diagrams` table storing the JSONB schema), different domain. Data
  * flow edges describe how data moves between nodes, not user navigation.
  */
 // ============================================================================

package/dist/phases/diagram-shared/clone-repos.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Shared multi-repo cloning for flow generation (screen-flow / data-flow).
+ *
+ * A flow can be scoped to one or several repositories (the user picks them in
+ * the desktop UI; the chosen set is stored on `diagrams.repository_ids`). This
+ * helper resolves that set, clones each repo into a per-flow parent workspace
+ * directory, and returns the directory the agent should run against:
+ *   - single repo  → the repo's own clone dir
+ *   - many repos   → the parent dir holding every clone as a subdirectory,
+ *                    so the agent can explore them all and produce one unified
+ *                    flow.
+ *
+ * Falls back to the product's primary repo when `repository_ids` is empty
+ * (older diagrams, or single-repo products).
+ */
+export interface ClonedRepo {
+    fullName: string;
+    owner: string;
+    repo: string;
+    dir: string;
+}
+export interface CloneFlowReposSuccess {
+    ok: true;
+    /** Directory to point the agent at (parent dir for multi-repo). */
+    projectDir: string;
+    /** Directory to clean up afterwards (always the per-flow parent). */
+    cleanupDir: string;
+    repos: ClonedRepo[];
+}
+export interface CloneFlowReposFailure {
+    ok: false;
+    message: string;
+}
+export declare function safeDirName(fullName: string): string;
+/**
+ * Resolve the repositories a flow targets (by id, preserving the stored
+ * order), falling back to the product's primary repo.
+ *
+ * In repo-only mode there is no product, so no `fallback` is provided: the
+ * set is resolved purely from `repositoryIds`.
+ */
+export declare function resolveTargetRepos(productId: string | undefined, repositoryIds: string[], fallback?: {
+    owner: string;
+    repo: string;
+}): Promise<{
+    fullName: string;
+    owner: string;
+    repo: string;
+}[]>;
+export declare function cloneDiagramRepos(opts: {
+    /** Product-scoped flow. Mutually exclusive with `repoId`. */
+    productId?: string;
+    /** Repo-only flow: a single repositories row, no product context. */
+    repoId?: string;
+    repositoryIds: string[];
+    workspaceKey: string;
+    verbose?: boolean;
+}): Promise<CloneFlowReposSuccess | CloneFlowReposFailure>;
+/**
+ * Build a short note describing the repo scope, appended to the agent's user
+ * prompt so it knows whether to map one repo or unify several.
+ */
+export declare function describeRepoScope(repos: ClonedRepo[]): string;

package/dist/phases/diagram-shared/clone-repos.js

@@ -0,0 +1,153 @@
+/**
+ * Shared multi-repo cloning for flow generation (screen-flow / data-flow).
+ *
+ * A flow can be scoped to one or several repositories (the user picks them in
+ * the desktop UI; the chosen set is stored on `diagrams.repository_ids`). This
+ * helper resolves that set, clones each repo into a per-flow parent workspace
+ * directory, and returns the directory the agent should run against:
+ *   - single repo  → the repo's own clone dir
+ *   - many repos   → the parent dir holding every clone as a subdirectory,
+ *                    so the agent can explore them all and produce one unified
+ *                    flow.
+ *
+ * Falls back to the product's primary repo when `repository_ids` is empty
+ * (older diagrams, or single-repo products).
+ */
+import { getGitHubConfigByProduct, getGitHubConfigByRepository, } from '../../api/github.js';
+import { getSupabase } from '../../supabase/client.js';
+import { logInfo, logWarning } from '../../utils/logger.js';
+import { cloneIssueRepo, ensureWorkspaceDir, getIssueRepoPath, } from '../../workspace/workspace-manager.js';
+export function safeDirName(fullName) {
+    return fullName.replace(/[^a-zA-Z0-9._-]/g, '_');
+}
+/**
+ * Resolve the repositories a flow targets (by id, preserving the stored
+ * order), falling back to the product's primary repo.
+ *
+ * In repo-only mode there is no product, so no `fallback` is provided: the
+ * set is resolved purely from `repositoryIds`.
+ */
+export async function resolveTargetRepos(productId, repositoryIds, fallback) {
+    if (repositoryIds.length === 0) {
+        if (fallback) {
+            return [
+                {
+                    fullName: `${fallback.owner}/${fallback.repo}`,
+                    owner: fallback.owner,
+                    repo: fallback.repo,
+                },
+            ];
+        }
+        return [];
+    }
+    const supabase = getSupabase();
+    const { data } = await supabase
+        .from('repositories')
+        .select('id, full_name')
+        .in('id', repositoryIds);
+    const byId = new Map((data ?? []).map((r) => [r.id, r.full_name]));
+    // Preserve the caller's order (diagrams.repository_ids is ordered).
+    const resolved = [];
+    for (const id of repositoryIds) {
+        const fullName = byId.get(id);
+        if (!fullName) {
+            continue;
+        }
+        const [owner, repo] = fullName.split('/');
+        if (!owner || !repo) {
+            continue;
+        }
+        resolved.push({ fullName, owner, repo });
+    }
+    // If none resolved (deleted repos / RLS), fall back to the primary repo so
+    // generation still produces something useful (product mode only).
+    if (resolved.length === 0 && fallback) {
+        return [
+            {
+                fullName: `${fallback.owner}/${fallback.repo}`,
+                owner: fallback.owner,
+                repo: fallback.repo,
+            },
+        ];
+    }
+    return resolved;
+}
+export async function cloneDiagramRepos(opts) {
+    const { productId, repoId, repositoryIds, workspaceKey, verbose } = opts;
+    const repoOnly = !productId && Boolean(repoId);
+    // Resolve the auth token. Product mode reuses the product's installation /
+    // PAT for every repo; repo-only mode resolves it from the first (only) repo.
+    const gh = repoOnly
+        ? await getGitHubConfigByRepository(repositoryIds[0] ?? repoId, verbose)
+        : await getGitHubConfigByProduct(productId, verbose);
+    if (!gh.configured || !gh.token || !gh.owner || !gh.repo) {
+        return {
+            ok: false,
+            message: gh.message ||
+                (repoOnly
+                    ? 'GitHub repository not configured. Connect the repo first.'
+                    : 'GitHub repository not configured for this product. Connect a repo first.'),
+        };
+    }
+    // In repo-only mode there is no product primary-repo fallback; targets come
+    // purely from repositoryIds.
+    const targets = await resolveTargetRepos(productId, repositoryIds, repoOnly ? undefined : { owner: gh.owner, repo: gh.repo });
+    if (targets.length === 0) {
+        return {
+            ok: false,
+            message: 'No repositories resolved for this flow.',
+        };
+    }
+    const workspaceRoot = ensureWorkspaceDir();
+    const parentDir = getIssueRepoPath(workspaceRoot, `${workspaceKey}-${repoOnly ? `repo-${repoId}` : productId}`);
+    const repos = [];
+    for (const target of targets) {
+        try {
+            // The product-level token (installation or user PAT/OAuth) is reused for
+            // every repo; if it can't access one, that clone fails and we skip it
+            // rather than aborting the whole generation.
+            const { repoPath } = cloneIssueRepo(parentDir, safeDirName(target.fullName), target.owner, target.repo, gh.token);
+            repos.push({
+                fullName: target.fullName,
+                owner: target.owner,
+                repo: target.repo,
+                dir: repoPath,
+            });
+        }
+        catch (err) {
+            logWarning(`Skipping ${target.fullName}: clone failed (${err instanceof Error ? err.message : String(err)})`);
+        }
+    }
+    if (repos.length === 0) {
+        return {
+            ok: false,
+            message: 'Failed to clone any of the selected repositories.',
+        };
+    }
+    if (repos.length > 1) {
+        logInfo(`Cloned ${repos.length} repos for ${workspaceKey}: ${repos.map((r) => r.fullName).join(', ')}`);
+    }
+    return {
+        ok: true,
+        // Single repo: run directly in its dir. Multi-repo: run in the parent so
+        // the agent sees every clone as a subdirectory.
+        projectDir: repos.length === 1 ? repos[0].dir : parentDir,
+        cleanupDir: parentDir,
+        repos,
+    };
+}
+/**
+ * Build a short note describing the repo scope, appended to the agent's user
+ * prompt so it knows whether to map one repo or unify several.
+ */
+export function describeRepoScope(repos) {
+    if (repos.length <= 1) {
+        return '';
+    }
+    const list = repos.map((r) => `- ${r.fullName} (subdirectory: ${safeDirName(r.fullName)})`);
+    return [
+        `This product spans ${repos.length} repositories, each cloned into its own subdirectory of the working directory:`,
+        ...list,
+        'Explore all of them and produce a single unified flow that spans the repositories.',
+    ].join('\n');
+}

package/dist/phases/diagram-shared/generate.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Shared diagram generation runner.
+ *
+ * Encapsulates the common pipeline every node/edge diagram phase uses: clone
+ * the repo(s), resolve product/repo basics, build prompts, run the Claude
+ * Agent SDK loop with an in-process MCP capture server, fall back to a fenced
+ * block if the agent forgot the tool, then persist to the diagrams tables and
+ * flip status. Each lean phase just supplies its domain MCP config + prompts.
+ */
+import { type DiagramMcpConfig } from './mcp.js';
+export interface GenerateDiagramOptions {
+    productId?: string;
+    repoId?: string;
+    diagramId: string;
+    guidance?: string;
+    verbose?: boolean;
+    /** Workspace clone key, e.g. 'state-diagram'. */
+    workspaceKey: string;
+    /** Fenced block name for the fallback parser, e.g. 'state_diagram'. */
+    fenceName: string;
+    /** Plural noun for log/result messages, e.g. 'states', 'classes'. */
+    nounPlural: string;
+    edgeNounPlural: string;
+    mcpConfig: DiagramMcpConfig;
+    buildSystemPrompt: (args: {
+        projectDir: string;
+        hasCodebase: boolean;
+    }) => Promise<string>;
+    buildUserPrompt: (args: {
+        productName: string;
+        productDescription?: string;
+        guidance?: string;
+    }) => string;
+}
+export interface DiagramPhaseResult {
+    status: 'success' | 'error';
+    message: string;
+    nodesCreated?: number;
+    edgesCreated?: number;
+    summary?: string;
+}
+export declare function generateDiagram(options: GenerateDiagramOptions): Promise<DiagramPhaseResult>;