edsger 0.69.0 → 0.70.0

package/dist/phases/diagram-shared/generate.js

@@ -0,0 +1,162 @@
+/**
+ * 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 { 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 { cleanupIssueRepo } from '../../workspace/workspace-manager.js';
+import { fetchProductBasics } from '../find-shared/mcp.js';
+import { createPromptGenerator, extractTextFromContent, tryExtractResult, } from '../pr-shared/agent-utils.js';
+import { cloneDiagramRepos, describeRepoScope } from './clone-repos.js';
+import { getDiagramRepositoryIds, isDiagramExtraction, markDiagramFailed, markDiagramRunning, markDiagramSuccess, persistDiagramGraph, validateGraphConsistency, } from './graph.js';
+import { createDiagramCaptureState, createDiagramMcpServer, } from './mcp.js';
+const MAX_TURNS = 150;
+export async function generateDiagram(options) {
+    const { productId, repoId, diagramId, guidance, verbose } = options;
+    const repoOnly = !productId && Boolean(repoId);
+    const label = options.mcpConfig.name;
+    logInfo(productId
+        ? `Starting ${label} generation for product ${productId}`
+        : `Starting ${label} generation for repository ${repoId}`);
+    const supabase = getSupabase();
+    await markDiagramRunning(supabase, diagramId);
+    const repositoryIds = await getDiagramRepositoryIds(supabase, diagramId);
+    const cloneResult = await cloneDiagramRepos({
+        productId,
+        repoId,
+        repositoryIds,
+        workspaceKey: options.workspaceKey,
+        verbose,
+    });
+    if (!cloneResult.ok) {
+        await markDiagramFailed(supabase, diagramId, cloneResult.message);
+        return { status: 'error', message: cloneResult.message };
+    }
+    const { projectDir, cleanupDir, repos } = cloneResult;
+    let succeeded = false;
+    try {
+        const product = repoOnly
+            ? await resolveRepoBasics(repoId, repos)
+            : await fetchProductBasics(productId);
+        const systemPrompt = await options.buildSystemPrompt({
+            projectDir,
+            hasCodebase: true,
+        });
+        const repoScope = describeRepoScope(repos);
+        const userPrompt = options.buildUserPrompt({
+            productName: product.name,
+            productDescription: product.description,
+            guidance: [guidance, repoScope].filter(Boolean).join('\n\n') || undefined,
+        });
+        logInfo(`Running Claude ${label} extraction...`);
+        const captureState = createDiagramCaptureState();
+        const mcpServer = createDiagramMcpServer(options.mcpConfig, captureState, {
+            onProgress: ({ phase, message }) => logInfo(`[${phase}] ${message}`),
+        });
+        let assistantBuffer = '';
+        let extraction = null;
+        const stream = query({
+            prompt: createPromptGenerator(userPrompt),
+            options: {
+                systemPrompt: {
+                    type: 'preset',
+                    preset: 'claude_code',
+                    append: systemPrompt,
+                },
+                model: DEFAULT_MODEL,
+                maxTurns: MAX_TURNS,
+                permissionMode: 'bypassPermissions',
+                cwd: projectDir,
+                mcpServers: { [options.mcpConfig.name]: mcpServer },
+            },
+        });
+        for await (const rawMessage of stream) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const message = rawMessage;
+            if (message.type === 'assistant') {
+                assistantBuffer += extractTextFromContent(message.message?.content ?? [], verbose);
+                continue;
+            }
+            if (message.type === 'user' && verbose) {
+                const userContent = message.message?.content;
+                if (Array.isArray(userContent)) {
+                    extractTextFromContent(userContent, verbose);
+                }
+                continue;
+            }
+            if (message.type !== 'result') {
+                continue;
+            }
+            if (captureState.captured) {
+                extraction = captureState.captured;
+                break;
+            }
+            const fallback = tryFallbackParse(message, assistantBuffer, options.fenceName);
+            if (fallback) {
+                logWarning(`Agent emitted a fenced ${options.fenceName} block instead of calling the submit tool; using the parsed text as a fallback.`);
+                extraction = fallback;
+            }
+            else if (message.subtype !== 'success') {
+                logError(`Extraction incomplete: ${message.subtype}`);
+            }
+        }
+        if (!extraction) {
+            const msg = `${label} extraction failed: agent did not call the submit tool and no parseable ${options.fenceName} block was found.`;
+            await markDiagramFailed(supabase, diagramId, msg);
+            return { status: 'error', message: msg };
+        }
+        logInfo(`Extraction produced ${extraction.nodes.length} ${options.nounPlural} / ${extraction.edges.length} ${options.edgeNounPlural}`);
+        const { nodesCreated, edgesCreated } = await persistDiagramGraph(supabase, diagramId, extraction);
+        await markDiagramSuccess(supabase, diagramId, extraction.summary);
+        succeeded = true;
+        logSuccess(`${label} generated: ${nodesCreated} ${options.nounPlural}, ${edgesCreated} ${options.edgeNounPlural}`);
+        return {
+            status: 'success',
+            message: `${label} generated (${nodesCreated} ${options.nounPlural}, ${edgesCreated} ${options.edgeNounPlural})`,
+            nodesCreated,
+            edgesCreated,
+            summary: extraction.summary,
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logError(`${label} failed: ${errorMessage}`);
+        await markDiagramFailed(supabase, diagramId, errorMessage);
+        return { status: 'error', message: errorMessage };
+    }
+    finally {
+        if (succeeded) {
+            cleanupIssueRepo(cleanupDir);
+        }
+    }
+}
+async function resolveRepoBasics(repositoryId, repos) {
+    const basics = await getRepositoryBasics(repositoryId).catch(() => null);
+    return {
+        name: basics?.fullName ?? repos[0]?.fullName ?? repositoryId,
+        description: basics?.description ?? undefined,
+    };
+}
+function tryFallbackParse(resultMessage, assistantText, fenceName) {
+    const responseText = resultMessage.subtype === 'success'
+        ? resultMessage.result || assistantText
+        : assistantText;
+    const parsed = tryExtractResult(responseText, fenceName);
+    if (!isDiagramExtraction(parsed)) {
+        return null;
+    }
+    const { error } = validateGraphConsistency(parsed);
+    if (error) {
+        logWarning(`Fallback extraction failed consistency check: ${error}`);
+        return null;
+    }
+    return parsed;
+}

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

@@ -0,0 +1,62 @@
+/**
+ * Shared graph model + persistence for node/edge diagram types.
+ *
+ * Every diagram type (screen / data / er / sequence and the lean types built
+ * on this framework — state / class / architecture / flowchart) is a graph of
+ * nodes + edges stored in the generic `diagrams` / `diagram_nodes` /
+ * `diagram_edges` tables, discriminated by `diagrams.type`. This module owns
+ * the type-agnostic extraction shape, its consistency validation, and the
+ * persistence + status-transition helpers so each phase only has to describe
+ * its own domain schema and prompts.
+ */
+import type { SupabaseClient } from '@supabase/supabase-js';
+/** One node in a diagram. Domain-specific fields ride along and are stored
+ *  verbatim in `diagram_nodes.schema`. */
+export interface GraphNode {
+    /** Stable slug, unique within the diagram. */
+    slug: string;
+    name: string;
+    kind: string;
+    [key: string]: unknown;
+}
+/** One directed edge. fromSlug → toSlug must reference emitted node slugs. */
+export interface GraphEdge {
+    fromSlug: string;
+    toSlug: string;
+    kind: string;
+    label?: string;
+    /** File (jump-to-code) for the connection, stored as source_anchor. */
+    sourceFile?: string;
+    /** Extra per-edge data stored in diagram_edges.metadata (order, columns…). */
+    metadata?: Record<string, unknown>;
+}
+export interface DiagramExtraction {
+    summary: string;
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+}
+export declare function isGraphNode(value: unknown): value is GraphNode;
+export declare function isGraphEdge(value: unknown): value is GraphEdge;
+export declare function isDiagramExtraction(value: unknown): value is DiagramExtraction;
+/**
+ * Cross-field checks: unique node slugs and every edge endpoint references a
+ * node that was emitted. Returns a human-readable instruction on failure so
+ * the agent can self-correct and re-submit.
+ */
+export declare function validateGraphConsistency(extraction: DiagramExtraction): {
+    error: string | null;
+};
+export declare function markDiagramRunning(supabase: SupabaseClient, diagramId: string): Promise<void>;
+export declare function markDiagramFailed(supabase: SupabaseClient, diagramId: string, errorMessage: string): Promise<void>;
+export declare function markDiagramSuccess(supabase: SupabaseClient, diagramId: string, summary: string): Promise<void>;
+/** Read the ordered repo set a diagram was scoped to (may be empty). */
+export declare function getDiagramRepositoryIds(supabase: SupabaseClient, diagramId: string): Promise<string[]>;
+/**
+ * Replace the diagram's nodes and edges with a freshly extracted graph.
+ * Slugs are resolved to node ids for the edge foreign keys; edges whose
+ * endpoints weren't emitted are dropped.
+ */
+export declare function persistDiagramGraph(supabase: SupabaseClient, diagramId: string, extraction: DiagramExtraction): Promise<{
+    nodesCreated: number;
+    edgesCreated: number;
+}>;

package/dist/phases/diagram-shared/graph.js

@@ -0,0 +1,169 @@
+/**
+ * Shared graph model + persistence for node/edge diagram types.
+ *
+ * Every diagram type (screen / data / er / sequence and the lean types built
+ * on this framework — state / class / architecture / flowchart) is a graph of
+ * nodes + edges stored in the generic `diagrams` / `diagram_nodes` /
+ * `diagram_edges` tables, discriminated by `diagrams.type`. This module owns
+ * the type-agnostic extraction shape, its consistency validation, and the
+ * persistence + status-transition helpers so each phase only has to describe
+ * its own domain schema and prompts.
+ */
+import { logWarning } from '../../utils/logger.js';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+export function isGraphNode(value) {
+    return (isRecord(value) &&
+        typeof value.slug === 'string' &&
+        value.slug.length > 0 &&
+        typeof value.name === 'string' &&
+        value.name.length > 0 &&
+        typeof value.kind === 'string' &&
+        value.kind.length > 0);
+}
+export function isGraphEdge(value) {
+    return (isRecord(value) &&
+        typeof value.fromSlug === 'string' &&
+        typeof value.toSlug === 'string' &&
+        typeof value.kind === 'string');
+}
+export function isDiagramExtraction(value) {
+    return (isRecord(value) &&
+        typeof value.summary === 'string' &&
+        Array.isArray(value.nodes) &&
+        Array.isArray(value.edges) &&
+        value.nodes.every(isGraphNode) &&
+        value.edges.every(isGraphEdge));
+}
+/**
+ * Cross-field checks: unique node slugs and every edge endpoint references a
+ * node that was emitted. Returns a human-readable instruction on failure so
+ * the agent can self-correct and re-submit.
+ */
+export function validateGraphConsistency(extraction) {
+    const slugs = new Set();
+    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 diagram. Re-submit with deduplicated nodes.`,
+            };
+        }
+        slugs.add(node.slug);
+    }
+    for (const edge of extraction.edges) {
+        if (!slugs.has(edge.fromSlug)) {
+            return {
+                error: `Edge "${edge.fromSlug}" → "${edge.toSlug}": fromSlug does not match any node slug. Add the missing node or drop the edge, then re-submit.`,
+            };
+        }
+        if (!slugs.has(edge.toSlug)) {
+            return {
+                error: `Edge "${edge.fromSlug}" → "${edge.toSlug}": toSlug does not match any node slug. Add the missing node or drop the edge, then re-submit.`,
+            };
+        }
+    }
+    return { error: null };
+}
+// ============================================================================
+// Persistence
+// ============================================================================
+// Auto-layout grid; users drag afterwards and positions persist.
+const COLUMN_WIDTH = 320;
+const ROW_HEIGHT = 240;
+const COLUMNS = 4;
+export async function markDiagramRunning(supabase, diagramId) {
+    const { error } = await supabase
+        .from('diagrams')
+        .update({ status: 'running', error: null })
+        .eq('id', diagramId);
+    if (error) {
+        logWarning(`Could not mark diagram as running: ${error.message}`);
+    }
+}
+export async function markDiagramFailed(supabase, diagramId, errorMessage) {
+    await supabase
+        .from('diagrams')
+        .update({
+        status: 'failed',
+        error: errorMessage,
+        completed_at: new Date().toISOString(),
+    })
+        .eq('id', diagramId);
+}
+export async function markDiagramSuccess(supabase, diagramId, summary) {
+    await supabase
+        .from('diagrams')
+        .update({
+        status: 'success',
+        summary,
+        error: null,
+        completed_at: new Date().toISOString(),
+    })
+        .eq('id', diagramId);
+}
+/** Read the ordered repo set a diagram was scoped to (may be empty). */
+export async function getDiagramRepositoryIds(supabase, diagramId) {
+    const { data } = await supabase
+        .from('diagrams')
+        .select('repository_ids')
+        .eq('id', diagramId)
+        .single();
+    return (data?.repository_ids ?? []).filter(Boolean);
+}
+/**
+ * Replace the diagram's nodes and edges with a freshly extracted graph.
+ * Slugs are resolved to node ids for the edge foreign keys; edges whose
+ * endpoints weren't emitted are dropped.
+ */
+export async function persistDiagramGraph(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((node, i) => ({
+        diagram_id: diagramId,
+        slug: node.slug,
+        name: node.name,
+        kind: node.kind,
+        schema: node,
+        position_x: (i % COLUMNS) * COLUMN_WIDTH,
+        position_y: Math.floor(i / COLUMNS) * ROW_HEIGHT,
+    }));
+    const { data: insertedNodes, error: nodesError } = await supabase
+        .from('diagram_nodes')
+        .insert(nodeRows)
+        .select('id, slug');
+    if (nodesError) {
+        throw new Error(`Failed to insert nodes: ${nodesError.message}`);
+    }
+    const slugToId = new Map((insertedNodes ?? []).map((n) => [n.slug, n.id]));
+    const edgeRows = extraction.edges
+        .map((edge) => {
+        const fromId = slugToId.get(edge.fromSlug);
+        const toId = slugToId.get(edge.toSlug);
+        if (!fromId || !toId) {
+            return null;
+        }
+        return {
+            diagram_id: diagramId,
+            from_node_id: fromId,
+            to_node_id: toId,
+            label: edge.label ?? null,
+            source_anchor: edge.sourceFile ?? null,
+            kind: edge.kind,
+            metadata: edge.metadata ?? {},
+        };
+    })
+        .filter((e) => e !== null);
+    if (edgeRows.length > 0) {
+        const { error: edgesError } = await supabase
+            .from('diagram_edges')
+            .insert(edgeRows);
+        if (edgesError) {
+            throw new Error(`Failed to insert edges: ${edgesError.message}`);
+        }
+    }
+    return { nodesCreated: nodeRows.length, edgesCreated: edgeRows.length };
+}

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

@@ -0,0 +1,35 @@
+/**
+ * Shared in-process MCP server builder for graph diagram types.
+ *
+ * Each lean diagram phase (state / class / architecture / flowchart) supplies
+ * its own zod node/edge schemas + tool name; this assembles the standard
+ * `submit_<type>` capture tool (validated against the shared graph consistency
+ * rules) plus a `record_progress` status tool.
+ */
+import { type ZodTypeAny } from 'zod';
+import { type DiagramExtraction } from './graph.js';
+export interface DiagramCaptureState {
+    captured: DiagramExtraction | null;
+}
+export declare function createDiagramCaptureState(): DiagramCaptureState;
+export type DiagramProgressSink = (event: {
+    phase: 'detection' | 'enumeration' | 'nodes' | 'edges' | 'submission';
+    message: string;
+}) => void;
+export interface DiagramMcpConfig {
+    /** Server name + submit tool become `submit_<toolName>`. */
+    name: string;
+    toolName: string;
+    summaryDescribe: string;
+    nodesSchema: ZodTypeAny;
+    nodesDescribe: string;
+    edgesSchema: ZodTypeAny;
+    edgesDescribe: string;
+}
+/**
+ * Build the MCP server for one diagram type. The submit tool captures the
+ * extraction into `state` after passing the shared consistency check.
+ */
+export declare function createDiagramMcpServer(config: DiagramMcpConfig, state: DiagramCaptureState, options?: {
+    onProgress?: DiagramProgressSink;
+}): import("@anthropic-ai/claude-agent-sdk").McpSdkServerConfigWithInstance;

package/dist/phases/diagram-shared/mcp.js

@@ -0,0 +1,68 @@
+/**
+ * Shared in-process MCP server builder for graph diagram types.
+ *
+ * Each lean diagram phase (state / class / architecture / flowchart) supplies
+ * its own zod node/edge schemas + tool name; this assembles the standard
+ * `submit_<type>` capture tool (validated against the shared graph consistency
+ * rules) plus a `record_progress` status tool.
+ */
+import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { validateGraphConsistency, } from './graph.js';
+export function createDiagramCaptureState() {
+    return { captured: null };
+}
+function createRecordProgressTool(sink) {
+    return tool('record_progress', 'Send a short status update to the user. Does not affect the extraction. Call it at each phase boundary so the user sees progress.', {
+        phase: z
+            .enum(['detection', 'enumeration', 'nodes', 'edges', 'submission'])
+            .describe('Which phase the message belongs to.'),
+        message: z.string().min(1).describe('Human-readable status update.'),
+    }, async (args) => {
+        sink?.({ phase: args.phase, message: args.message });
+        return { content: [{ type: 'text', text: 'ok' }] };
+    });
+}
+/**
+ * Build the MCP server for one diagram type. The submit tool captures the
+ * extraction into `state` after passing the shared consistency check.
+ */
+export function createDiagramMcpServer(config, state, options) {
+    const submitTool = tool(`submit_${config.toolName}`, [
+        `Submit the final ${config.name}. Call this EXACTLY once, when you have`,
+        'finished mapping every node and edge. After it succeeds, end your turn —',
+        'do NOT also paste the same data as a fenced code block. If validation',
+        'fails, the error tells you what to fix; call the tool again.',
+    ].join(' '), {
+        summary: z.string().min(1).describe(config.summaryDescribe),
+        nodes: config.nodesSchema.describe(config.nodesDescribe),
+        edges: config.edgesSchema.describe(config.edgesDescribe),
+    }, async (args) => {
+        const extraction = {
+            summary: args.summary,
+            nodes: args.nodes,
+            edges: args.edges,
+        };
+        const { error } = validateGraphConsistency(extraction);
+        if (error) {
+            return {
+                content: [{ type: 'text', text: error }],
+                isError: true,
+            };
+        }
+        state.captured = extraction;
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Captured ${extraction.nodes.length} nodes / ${extraction.edges.length} edges. End your turn now.`,
+                },
+            ],
+        };
+    });
+    return createSdkMcpServer({
+        name: config.name,
+        version: '1.0.0',
+        tools: [submitTool, createRecordProgressTool(options?.onProgress)],
+    });
+}

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

@@ -0,0 +1,23 @@
+/**
+ * Shared prompt builders for graph diagram phases. The system prompt loads the
+ * type's SKILL.md (project-overridable) and appends its JSON output contract;
+ * the user prompt wraps a type-specific task + process paragraph in the
+ * standard "call the submit tool" envelope.
+ */
+export declare function buildDiagramSystemPrompt(skillRef: string, contractKey: string, opts?: {
+    projectDir?: string;
+    hasCodebase?: boolean;
+}): Promise<string>;
+export declare function buildDiagramUserPrompt(args: {
+    /** e.g. "Map the state machine for". The product name is appended. */
+    task: string;
+    productName: string;
+    productDescription?: string;
+    guidance?: string;
+    /** One paragraph telling the agent what to scan / how to proceed. */
+    process: string;
+    /** MCP server name, e.g. 'state-diagram'. */
+    mcpName: string;
+    /** Submit tool suffix, e.g. 'state_diagram' → submit_state_diagram. */
+    toolName: string;
+}): string;

package/dist/phases/diagram-shared/prompts.js

@@ -0,0 +1,35 @@
+/**
+ * Shared prompt builders for graph diagram phases. The system prompt loads the
+ * type's SKILL.md (project-overridable) and appends its JSON output contract;
+ * the user prompt wraps a type-specific task + process paragraph in the
+ * standard "call the submit tool" envelope.
+ */
+import { processConditionals, resolveSkill, } from '../../services/skill-resolver.js';
+import { OUTPUT_CONTRACTS } from '../output-contracts.js';
+export async function buildDiagramSystemPrompt(skillRef, contractKey, opts) {
+    const skill = await resolveSkill(skillRef, { projectDir: opts?.projectDir });
+    if (!skill) {
+        throw new Error(`Failed to load skill: ${skillRef}`);
+    }
+    const prompt = processConditionals(skill.prompt, {
+        hasCodebase: opts?.hasCodebase ?? true,
+    });
+    return `${prompt}
+
+${OUTPUT_CONTRACTS[contractKey]}`;
+}
+export function buildDiagramUserPrompt(args) {
+    const descBlock = args.productDescription
+        ? `\n**Product description**: ${args.productDescription}`
+        : '';
+    const guidanceBlock = args.guidance
+        ? `\n\n**Human guidance for this run** (focus or exclude as instructed):\n${args.guidance}`
+        : '';
+    return `${args.task} **${args.productName}**.${descBlock}${guidanceBlock}
+
+${args.process}
+
+Call \`mcp__${args.mcpName}__record_progress\` at each phase boundary so the user can see your progress (otherwise the CLI looks frozen).
+
+When you are done, return the result by **calling the \`mcp__${args.mcpName}__submit_${args.toolName}\` tool exactly once**. Do not paste the JSON as a fenced text block — the tool call is the deliverable. If the tool returns an error, fix the issue it describes and call the tool again.`;
+}

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

@@ -0,0 +1,28 @@
+/**
+ * er-diagram phase: clone the product's repo, ask Claude to map every
+ * persistence entity (table / view / enum / junction) and the relationships
+ * between them into a structured ErDiagramExtraction, then persist the result
+ * to diagrams / diagram_nodes / diagram_edges (rows tagged `type = 'er'`) via the
+ * Supabase SDK.
+ *
+ * Companion to data-flow / screen-flow: same generation pattern (workspace
+ * clone + Claude Agent SDK + in-process MCP server), same storage tables,
+ * different domain.
+ */
+export interface ErDiagramPhaseOptions {
+    /** 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 ErDiagramPhaseResult {
+    status: 'success' | 'error';
+    message: string;
+    nodesCreated?: number;
+    edgesCreated?: number;
+    summary?: string;
+}
+export declare function runErDiagramPhase(options: ErDiagramPhaseOptions): Promise<ErDiagramPhaseResult>;