edsger 0.56.3 → 0.58.0

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

@@ -0,0 +1,262 @@
+/**
+ * In-process MCP server exposing a single tool — `submit_screen_flow` —
+ * that the Claude Agent SDK session calls to return the structured
+ * extraction.
+ *
+ * Using a tool call instead of parsing a fenced text block lets the SDK
+ * enforce the schema (via Zod) and lets the agent self-correct when
+ * validation fails — the validation error is returned to the agent as
+ * the tool result and it can re-call the tool with corrected data.
+ *
+ * The capture pattern: callers pass in a `ScreenFlowCaptureState`. The
+ * tool handler stores the validated args on `state.captured` and the
+ * orchestrator reads it after the SDK loop ends. If the agent never
+ * calls the tool, `state.captured` stays null and the caller can fall
+ * back to parsing the assistant text.
+ */
+import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+export function createScreenFlowCaptureState() {
+    return { captured: null };
+}
+// ---------------------------------------------------------------------------
+// Zod schemas (mirror types.ts — kept in sync by tests)
+// ---------------------------------------------------------------------------
+const formFieldSchema = z.object({
+    label: z.string(),
+    kind: z.enum([
+        'text',
+        'email',
+        'password',
+        'textarea',
+        'select',
+        'checkbox',
+        'date',
+        'number',
+    ]),
+    placeholder: z.string().optional(),
+    value: z.string().optional(),
+    required: z.boolean().optional(),
+});
+const listItemSchema = z.object({
+    title: z.string(),
+    subtitle: z.string().optional(),
+    meta: z.string().optional(),
+    icon: z.string().optional(),
+});
+const cardItemSchema = z.object({
+    title: z.string(),
+    subtitle: z.string().optional(),
+    meta: z.string().optional(),
+});
+const kanbanColumnSchema = z.object({
+    title: z.string(),
+    cards: z.array(z.object({ title: z.string(), meta: z.string().optional() })),
+});
+const sectionSchema = z.discriminatedUnion('type', [
+    z.object({
+        type: z.literal('form'),
+        fields: z.array(formFieldSchema),
+        submitLabel: z.string(),
+        secondaryLabel: z.string().optional(),
+    }),
+    z.object({
+        type: z.literal('list'),
+        items: z.array(listItemSchema),
+        emptyMessage: z.string().optional(),
+    }),
+    z.object({
+        type: z.literal('card-grid'),
+        cards: z.array(cardItemSchema),
+        columns: z.union([z.literal(2), z.literal(3), z.literal(4)]).optional(),
+    }),
+    z.object({
+        type: z.literal('table'),
+        columns: z.array(z.string()),
+        rows: z.array(z.array(z.string())),
+    }),
+    z.object({
+        type: z.literal('kanban'),
+        columns: z.array(kanbanColumnSchema),
+    }),
+    z.object({
+        type: z.literal('text'),
+        content: z.string(),
+    }),
+    z.object({
+        type: z.literal('image'),
+        alt: z.string(),
+        aspect: z.enum(['video', 'square', 'wide']).optional(),
+    }),
+    z.object({
+        type: z.literal('chart'),
+        chartKind: z.enum(['line', 'bar', 'pie']),
+        label: z.string().optional(),
+    }),
+    z.object({
+        type: z.literal('stats'),
+        items: z.array(z.object({
+            label: z.string(),
+            value: z.string(),
+            delta: z.string().optional(),
+        })),
+    }),
+    z.object({
+        type: z.literal('empty-state'),
+        title: z.string(),
+        message: z.string().optional(),
+        cta: z.string().optional(),
+    }),
+    z.object({
+        type: z.literal('tabs'),
+        tabs: z.array(z.string()),
+        activeIndex: z.number().optional(),
+    }),
+    z.object({
+        type: z.literal('custom'),
+        label: z.string(),
+    }),
+]);
+const screenActionSchema = z.object({
+    label: z.string(),
+    variant: z.enum(['primary', 'secondary', 'ghost', 'destructive']).optional(),
+    icon: z.string().optional(),
+});
+const screenHeaderSchema = z.object({
+    title: z.string(),
+    subtitle: z.string().optional(),
+    back: z.boolean().optional(),
+    actions: z.array(screenActionSchema).optional(),
+});
+const screenNodeSchema = z.object({
+    slug: z.string().min(1),
+    name: z.string().min(1),
+    route: z.string().optional(),
+    file: z.string().optional(),
+    kind: z.enum(['page', 'modal', 'drawer', 'tab', 'state']),
+    layout: z.enum([
+        'centered',
+        'sidebar',
+        'split',
+        'list-detail',
+        'tabs',
+        'stacked',
+    ]),
+    header: screenHeaderSchema.optional(),
+    body: z.array(sectionSchema),
+});
+const screenEdgeSchema = z.object({
+    fromSlug: z.string().min(1),
+    toSlug: z.string().min(1),
+    triggerLabel: z.string(),
+    triggerFile: z.string().optional(),
+    kind: z.enum(['navigate', 'modal', 'redirect', 'back']),
+});
+// ---------------------------------------------------------------------------
+// Cross-field consistency (Zod can't express this)
+// ---------------------------------------------------------------------------
+export function validateConsistency(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 flow. Re-call submit_screen_flow with deduplicated nodes.`,
+            };
+        }
+        slugs.add(node.slug);
+    }
+    for (const edge of extraction.edges) {
+        if (!slugs.has(edge.fromSlug)) {
+            return {
+                error: `Edge fromSlug "${edge.fromSlug}" → "${edge.toSlug}" does not match any node slug. Either add the missing node or drop the edge, then re-call submit_screen_flow.`,
+            };
+        }
+        if (!slugs.has(edge.toSlug)) {
+            return {
+                error: `Edge fromSlug "${edge.fromSlug}" → toSlug "${edge.toSlug}" does not match any node slug. Either add the missing node or drop the edge, then re-call submit_screen_flow.`,
+            };
+        }
+    }
+    return { error: null };
+}
+// ---------------------------------------------------------------------------
+// Tool factory + server factory
+// ---------------------------------------------------------------------------
+/**
+ * Build the `submit_screen_flow` tool. Exported separately from the server
+ * so tests can exercise the handler directly without going through the
+ * MCP transport.
+ */
+export function createSubmitScreenFlowTool(state) {
+    return tool('submit_screen_flow', [
+        'Submit the final screen flow extraction. Call this EXACTLY once,',
+        'when you have finished mapping every screen and transition. Pass the',
+        'full structured flow as the argument. After this call succeeds, end',
+        'your turn — do NOT also paste the same data as a fenced code block.',
+        'If validation fails, the error message tells you what to fix; call',
+        'the tool again with corrected data.',
+    ].join(' '), {
+        summary: z
+            .string()
+            .min(1)
+            .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.'),
+        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.'),
+    }, async (args) => {
+        const extraction = {
+            summary: args.summary,
+            nodes: args.nodes,
+            edges: args.edges,
+        };
+        const { error } = validateConsistency(extraction);
+        if (error) {
+            return {
+                content: [{ type: 'text', text: error }],
+                isError: true,
+            };
+        }
+        state.captured = extraction;
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Captured ${extraction.nodes.length} screens / ${extraction.edges.length} transitions. End your turn now.`,
+                },
+            ],
+        };
+    });
+}
+/**
+ * Build the `record_progress` tool. A side-channel that lets the agent
+ * push a human-readable status message to the CLI / desktop UI so a
+ * multi-minute extraction doesn't look frozen between text emissions.
+ * Returning `{ ok: true }` keeps it cheap — it has no semantic effect
+ * on the extraction.
+ */
+export 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 (after detecting the framework, after enumerating routes, while mapping screens, when about to submit) so the user sees progress.', {
+        phase: z
+            .enum(['detection', 'routing', 'screens', 'transitions', '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' }],
+        };
+    });
+}
+export function createScreenFlowMcpServer(state, options) {
+    return createSdkMcpServer({
+        name: 'screen-flow',
+        version: '1.0.0',
+        tools: [
+            createSubmitScreenFlowTool(state),
+            createRecordProgressTool(options?.onProgress),
+        ],
+    });
+}

package/dist/phases/screen-flow/prompts.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Prompts for the screen-flow phase.
+ *
+ * The system prompt body lives in the edsger-skills package
+ * (`skills/phase/screen-flow/SKILL.md`) so it can be project-overridden via
+ * `.claude/skills/edsger/phase/screen-flow/SKILL.md`, edited as plain MD
+ * without TS recompilation, and shared with the Claude Code plugin chain.
+ * The JSON output contract is appended from `output-contracts.ts` and is NOT
+ * user-overridable — the persistence layer relies on its exact shape.
+ */
+export declare function createScreenFlowSystemPrompt(options?: {
+    projectDir?: string;
+    hasCodebase?: boolean;
+}): Promise<string>;
+export declare function createScreenFlowUserPrompt(args: {
+    productName: string;
+    productDescription?: string;
+    guidance?: string;
+}): string;

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

@@ -0,0 +1,41 @@
+/**
+ * Prompts for the screen-flow phase.
+ *
+ * The system prompt body lives in the edsger-skills package
+ * (`skills/phase/screen-flow/SKILL.md`) so it can be project-overridden via
+ * `.claude/skills/edsger/phase/screen-flow/SKILL.md`, edited as plain MD
+ * without TS recompilation, and shared with the Claude Code plugin chain.
+ * The JSON output contract is appended from `output-contracts.ts` and is NOT
+ * user-overridable — the persistence layer relies on its exact shape.
+ */
+import { processConditionals, resolveSkill, } from '../../services/skill-resolver.js';
+import { OUTPUT_CONTRACTS } from '../output-contracts.js';
+export async function createScreenFlowSystemPrompt(options) {
+    const skill = await resolveSkill('phase/screen-flow', {
+        projectDir: options?.projectDir,
+    });
+    if (!skill) {
+        throw new Error('Failed to load skill: phase/screen-flow');
+    }
+    const prompt = processConditionals(skill.prompt, {
+        hasCodebase: options?.hasCodebase ?? true,
+    });
+    return `${prompt}
+
+${OUTPUT_CONTRACTS['screen-flow']}`;
+}
+export function createScreenFlowUserPrompt(args) {
+    const guidanceBlock = args.guidance
+        ? `\n\n**Human guidance for this run** (focus or exclude as instructed):\n${args.guidance}`
+        : '';
+    const descBlock = args.productDescription
+        ? `\n**Product description**: ${args.productDescription}`
+        : '';
+    return `Map the user-facing screen flow for **${args.productName}**.${descBlock}${guidanceBlock}
+
+Start by detecting the framework (check package.json / pubspec.yaml / Package.swift), then locate the router definition or pages directory. Read just enough source per screen to fill in a useful ScreenSchema — do not need to read everything.
+
+Call \`mcp__screen-flow__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__screen-flow__submit_screen_flow\` tool exactly once** with \`summary\`, \`nodes\`, and \`edges\` as arguments. 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/screen-flow/theme.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Theme extraction for screen-flow renders.
+ *
+ * The repo is already cloned on disk when this runs; we do best-effort
+ * static parsing of Tailwind config (and a couple of common alternatives)
+ * to pull out a primary color, a neutral color, a radius, and a font.
+ * Misses are fine — the renderer falls back to its own defaults.
+ *
+ * Intentionally simple: regex over the source text. We're not building an
+ * AST evaluator. If the user has anything exotic, they can edit the theme
+ * later from the desktop UI.
+ */
+export interface ScreenFlowTheme {
+    primary?: string;
+    neutral?: string;
+    radius?: string;
+    font?: string;
+}
+export declare function extractTheme(repoPath: string): ScreenFlowTheme;

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

@@ -0,0 +1,193 @@
+/**
+ * Theme extraction for screen-flow renders.
+ *
+ * The repo is already cloned on disk when this runs; we do best-effort
+ * static parsing of Tailwind config (and a couple of common alternatives)
+ * to pull out a primary color, a neutral color, a radius, and a font.
+ * Misses are fine — the renderer falls back to its own defaults.
+ *
+ * Intentionally simple: regex over the source text. We're not building an
+ * AST evaluator. If the user has anything exotic, they can edit the theme
+ * later from the desktop UI.
+ */
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+const TAILWIND_CONFIG_CANDIDATES = [
+    'tailwind.config.ts',
+    'tailwind.config.js',
+    'tailwind.config.cjs',
+    'tailwind.config.mjs',
+];
+// Common alternatives a project might use for a "tokens" file.
+const TOKENS_CANDIDATES = [
+    'src/theme.json',
+    'theme.json',
+    'src/design-tokens.json',
+];
+const HEX_RE = /#[0-9a-fA-F]{3,8}\b/g;
+const RGB_RE = /rgba?\([^)]+\)/g;
+const HSL_RE = /hsla?\([^)]+\)/g;
+const OKLCH_RE = /oklch\([^)]+\)/g;
+export function extractTheme(repoPath) {
+    const theme = {};
+    // Tailwind config — pull primary/neutral colors out of the colors block
+    for (const candidate of TAILWIND_CONFIG_CANDIDATES) {
+        const fullPath = join(repoPath, candidate);
+        if (!existsSync(fullPath)) {
+            continue;
+        }
+        try {
+            const source = readFileSync(fullPath, 'utf-8');
+            const fromTw = parseTailwindColors(source);
+            Object.assign(theme, stripUndefined(fromTw));
+            break;
+        }
+        catch {
+            // Best-effort
+        }
+    }
+    // Common project-side tokens
+    for (const candidate of TOKENS_CANDIDATES) {
+        const fullPath = join(repoPath, candidate);
+        if (!existsSync(fullPath)) {
+            continue;
+        }
+        try {
+            const parsed = JSON.parse(readFileSync(fullPath, 'utf-8'));
+            const fromTokens = parseTokensJson(parsed);
+            Object.assign(theme, stripUndefined(fromTokens));
+        }
+        catch {
+            // Skip
+        }
+    }
+    // CSS variables in a global stylesheet — last-ditch fallback
+    const globalCssCandidates = [
+        'src/index.css',
+        'src/styles/globals.css',
+        'src/app/globals.css',
+        'app/globals.css',
+        'styles/globals.css',
+    ];
+    if (!theme.primary || !theme.radius || !theme.font) {
+        for (const candidate of globalCssCandidates) {
+            const fullPath = join(repoPath, candidate);
+            if (!existsSync(fullPath)) {
+                continue;
+            }
+            try {
+                const source = readFileSync(fullPath, 'utf-8');
+                const fromCss = parseGlobalCss(source);
+                Object.assign(theme, stripUndefined({ ...fromCss, ...theme }));
+                break;
+            }
+            catch {
+                // Skip
+            }
+        }
+    }
+    return theme;
+}
+function parseTailwindColors(source) {
+    const theme = {};
+    // Look for `primary:` and `neutral:` keys in any nested object. Accept
+    // either a single string ("primary: '#ff0066'") or an object containing
+    // a 500 key (the Tailwind convention).
+    const primaryString = matchColorEntry(source, 'primary');
+    if (primaryString) {
+        theme.primary = primaryString;
+    }
+    const neutralString = matchColorEntry(source, 'neutral');
+    if (neutralString) {
+        theme.neutral = neutralString;
+    }
+    // Pull a radius default if defined under theme.borderRadius
+    const radiusMatch = source.match(/borderRadius\s*:\s*{[^}]*?(?:DEFAULT|md|lg)\s*:\s*['"]([^'"]+)['"]/);
+    if (radiusMatch) {
+        theme.radius = radiusMatch[1];
+    }
+    // Pull the default sans font family
+    const fontMatch = source.match(/fontFamily\s*:\s*{[^}]*?sans\s*:\s*\[?\s*['"]([^'"]+)['"]/);
+    if (fontMatch) {
+        theme.font = fontMatch[1];
+    }
+    return theme;
+}
+function matchColorEntry(source, key) {
+    // Match `<key>: '#abc'` or `<key>: "rgb(…)" / hsl(…) / oklch(…)`
+    const stringRe = new RegExp(`${key}\\s*:\\s*['\"\`](#[0-9a-fA-F]{3,8}|rgba?\\([^)]+\\)|hsla?\\([^)]+\\)|oklch\\([^)]+\\))['\"\`]`);
+    const strMatch = source.match(stringRe);
+    if (strMatch) {
+        return strMatch[1];
+    }
+    // Match nested `<key>: { ... 500: '#abc' ... }`
+    const nestedRe = new RegExp(`${key}\\s*:\\s*\\{[^}]*?500\\s*:\\s*['\"\`]([^'\"\`]+)['\"\`]`);
+    const nested = source.match(nestedRe);
+    if (nested) {
+        const value = nested[1];
+        if (isColorish(value)) {
+            return value;
+        }
+    }
+    return undefined;
+}
+function parseTokensJson(json) {
+    const theme = {};
+    const colors = (json.colors ?? json.color);
+    if (colors && typeof colors === 'object') {
+        const primary = colors.primary;
+        if (typeof primary === 'string') {
+            theme.primary = primary;
+        }
+        else if (primary && typeof primary === 'object' && '500' in primary) {
+            theme.primary = primary['500'];
+        }
+        const neutral = colors.neutral;
+        if (typeof neutral === 'string') {
+            theme.neutral = neutral;
+        }
+        else if (neutral && typeof neutral === 'object' && '500' in neutral) {
+            theme.neutral = neutral['500'];
+        }
+    }
+    if (typeof json.radius === 'string') {
+        theme.radius = json.radius;
+    }
+    if (typeof json.font === 'string') {
+        theme.font = json.font;
+    }
+    return theme;
+}
+function parseGlobalCss(source) {
+    const theme = {};
+    const primaryMatch = source.match(/--primary\s*:\s*([^;]+);/);
+    if (primaryMatch) {
+        const value = primaryMatch[1].trim();
+        if (isColorish(value)) {
+            theme.primary = value;
+        }
+        else {
+            theme.primary = `hsl(${value})`;
+        } // common shadcn pattern
+    }
+    const radiusMatch = source.match(/--radius\s*:\s*([^;]+);/);
+    if (radiusMatch) {
+        theme.radius = radiusMatch[1].trim();
+    }
+    return theme;
+}
+function isColorish(value) {
+    return (HEX_RE.test(value) ||
+        RGB_RE.test(value) ||
+        HSL_RE.test(value) ||
+        OKLCH_RE.test(value));
+}
+function stripUndefined(obj) {
+    const out = {};
+    for (const k of Object.keys(obj)) {
+        if (obj[k] !== undefined && obj[k] !== '') {
+            out[k] = obj[k];
+        }
+    }
+    return out;
+}

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

@@ -0,0 +1,130 @@
+/**
+ * Screen Flow domain types.
+ *
+ * A ScreenSchema is a structured, framework-agnostic description of one
+ * screen in a product. The CLI extracts these from source code and the
+ * desktop renders them with a unified <ScreenPreview> component — that's
+ * what gives every flow a consistent visual style regardless of the
+ * underlying app's design system.
+ *
+ * The schema deliberately stays high-level (sections, not pixels). When the
+ * agent encounters something it can't model cleanly, it falls back to
+ * `{ type: 'custom', label }` rather than guessing.
+ */
+export type ScreenKind = 'page' | 'modal' | 'drawer' | 'tab' | 'state';
+export type ScreenLayout = 'centered' | 'sidebar' | 'split' | 'list-detail' | 'tabs' | 'stacked';
+export interface ScreenAction {
+    label: string;
+    variant?: 'primary' | 'secondary' | 'ghost' | 'destructive';
+    icon?: string;
+}
+export interface ScreenHeader {
+    title: string;
+    subtitle?: string;
+    back?: boolean;
+    actions?: ScreenAction[];
+}
+export interface FormField {
+    label: string;
+    kind: 'text' | 'email' | 'password' | 'textarea' | 'select' | 'checkbox' | 'date' | 'number';
+    placeholder?: string;
+    value?: string;
+    required?: boolean;
+}
+export interface ListItem {
+    title: string;
+    subtitle?: string;
+    meta?: string;
+    icon?: string;
+}
+export interface CardItem {
+    title: string;
+    subtitle?: string;
+    meta?: string;
+}
+export interface KanbanColumn {
+    title: string;
+    cards: {
+        title: string;
+        meta?: string;
+    }[];
+}
+export type ScreenSection = {
+    type: 'form';
+    fields: FormField[];
+    submitLabel: string;
+    secondaryLabel?: string;
+} | {
+    type: 'list';
+    items: ListItem[];
+    emptyMessage?: string;
+} | {
+    type: 'card-grid';
+    cards: CardItem[];
+    columns?: 2 | 3 | 4;
+} | {
+    type: 'table';
+    columns: string[];
+    rows: string[][];
+} | {
+    type: 'kanban';
+    columns: KanbanColumn[];
+} | {
+    type: 'text';
+    content: string;
+} | {
+    type: 'image';
+    alt: string;
+    aspect?: 'video' | 'square' | 'wide';
+} | {
+    type: 'chart';
+    chartKind: 'line' | 'bar' | 'pie';
+    label?: string;
+} | {
+    type: 'stats';
+    items: {
+        label: string;
+        value: string;
+        delta?: string;
+    }[];
+} | {
+    type: 'empty-state';
+    title: string;
+    message?: string;
+    cta?: string;
+} | {
+    type: 'tabs';
+    tabs: string[];
+    activeIndex?: number;
+} | {
+    type: 'custom';
+    label: string;
+};
+export interface ScreenSchema {
+    /** Stable slug within the flow (e.g. 'login', 'product-detail') */
+    slug: string;
+    /** Human-readable name */
+    name: string;
+    /** URL path or navigator key; null/undefined for modals */
+    route?: string;
+    /** Source file path (jump anchor) */
+    file?: string;
+    kind: ScreenKind;
+    layout: ScreenLayout;
+    header?: ScreenHeader;
+    body: ScreenSection[];
+}
+export type ScreenEdgeKind = 'navigate' | 'modal' | 'redirect' | 'back';
+export interface ScreenEdge {
+    fromSlug: string;
+    toSlug: string;
+    triggerLabel: string;
+    triggerFile?: string;
+    kind: ScreenEdgeKind;
+}
+export interface ScreenFlowExtraction {
+    summary: string;
+    nodes: ScreenSchema[];
+    edges: ScreenEdge[];
+}
+export declare function isScreenFlowExtraction(value: unknown): value is ScreenFlowExtraction;