@tuongaz/seeflow 0.1.3

package/src/diagram.ts

@@ -0,0 +1,432 @@
+import dagre from 'dagre';
+import { z } from 'zod';
+import { DemoSchema } from './schema.ts';
+
+// Pure-compute helpers backing the three diagram-pipeline endpoints. No file
+// I/O lives here — the skill writes responses to disk on the user's machine.
+// Logic was extracted from skills/diagram/scripts/{propose-scope,assemble-demo,
+// validate-demo}.mjs so it can be exercised in-process and via HTTP.
+
+// === propose-scope =========================================================
+
+const ScanFileSchema = z
+  .object({
+    path: z.string(),
+    category: z.string(),
+  })
+  .passthrough();
+
+export const ProposeScopeRequestSchema = z.object({
+  files: z.array(ScanFileSchema),
+});
+
+export type ProposeScopeRequest = z.infer<typeof ProposeScopeRequestSchema>;
+
+export interface ScopeCandidate {
+  path: string;
+  score: number;
+  reasons: string[];
+}
+
+const ENTRY_NAMES = new Set([
+  'server.ts',
+  'server.js',
+  'index.ts',
+  'index.js',
+  'app.ts',
+  'app.js',
+  'main.ts',
+  'main.js',
+  'app.py',
+  'main.py',
+  'wsgi.py',
+  'asgi.py',
+  'manage.py',
+  'main.go',
+  'main.rs',
+  'application.rb',
+  'config.ru',
+]);
+
+const scoreFile = (path: string): number => {
+  let score = 0;
+  const base = path.split('/').pop() ?? '';
+  if (ENTRY_NAMES.has(base)) score += 10;
+  if (path.startsWith('src/')) score += 4;
+  if (path.startsWith('apps/')) score += 3;
+  const depth = path.split('/').length;
+  score += Math.max(0, 6 - depth);
+  if (/\bindex\.(ts|js)$/i.test(path)) score += 2;
+  if (/\b(server|app|main)\.(ts|js|py|go|rs)$/i.test(path)) score += 5;
+  if (/test|spec|__tests__|\.test\.|\.spec\./i.test(path)) score -= 8;
+  if (path.includes('node_modules')) score -= 50;
+  return score;
+};
+
+const scoreReasons = (path: string): string[] => {
+  const reasons: string[] = [];
+  const base = path.split('/').pop() ?? '';
+  if (ENTRY_NAMES.has(base)) reasons.push(`canonical entry name: ${base}`);
+  if (path.startsWith('src/') || path.startsWith('apps/'))
+    reasons.push('top-level src/apps directory');
+  if (path.split('/').length <= 3) reasons.push('shallow path');
+  return reasons;
+};
+
+export const proposeScope = (req: ProposeScopeRequest): { candidates: ScopeCandidate[] } => {
+  const candidates: ScopeCandidate[] = [];
+  for (const f of req.files) {
+    if (f.category !== 'code') continue;
+    const score = scoreFile(f.path);
+    if (score > 0) candidates.push({ path: f.path, score, reasons: scoreReasons(f.path) });
+  }
+  candidates.sort((a, b) => b.score - a.score);
+  return { candidates: candidates.slice(0, 30) };
+};
+
+// === assemble ==============================================================
+
+const GRID = 24;
+
+const WiringNodeSchema = z
+  .object({
+    id: z.string().min(1),
+    position: z
+      .object({
+        x: z.number(),
+        y: z.number(),
+      })
+      .optional(),
+  })
+  .passthrough();
+
+const WiringConnectorSchema = z
+  .object({
+    id: z.string().optional(),
+    source: z.string().min(1),
+    target: z.string().min(1),
+  })
+  .passthrough();
+
+export const AssembleRequestSchema = z.object({
+  wiring: z.object({
+    name: z.string().optional(),
+    nodes: z.array(WiringNodeSchema),
+    connectors: z.array(WiringConnectorSchema),
+  }),
+  layout: z
+    .object({
+      positions: z.record(z.string(), z.object({ x: z.number(), y: z.number() })).optional(),
+    })
+    .optional(),
+});
+
+export type AssembleRequest = z.infer<typeof AssembleRequestSchema>;
+
+export interface AssembleStats {
+  nodesIn: number;
+  connectorsIn: number;
+  nodesOut: number;
+  connectorsOut: number;
+  duplicateNodesDropped: number;
+  duplicateConnectorsDropped: number;
+  danglingConnectorsDropped: number;
+  positionsSnapped: number;
+  positionsShifted: number;
+}
+
+export interface AssembleResult {
+  demo: {
+    version: 1;
+    name: string;
+    nodes: Array<Record<string, unknown>>;
+    connectors: Array<Record<string, unknown>>;
+  };
+  stats: AssembleStats;
+}
+
+const slugify = (raw: string): string =>
+  String(raw)
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 80);
+
+export const assembleDemo = (req: AssembleRequest): AssembleResult => {
+  const stats: AssembleStats = {
+    nodesIn: req.wiring.nodes.length,
+    connectorsIn: req.wiring.connectors.length,
+    nodesOut: 0,
+    connectorsOut: 0,
+    duplicateNodesDropped: 0,
+    duplicateConnectorsDropped: 0,
+    danglingConnectorsDropped: 0,
+    positionsSnapped: 0,
+    positionsShifted: 0,
+  };
+
+  const positions = req.layout?.positions ?? {};
+  const nodes = normalizeNodes(req.wiring.nodes, positions, stats);
+  const nodeIds = new Set(nodes.map((n) => n.id as string));
+  const connectors = normalizeConnectors(req.wiring.connectors, nodeIds, stats);
+  const positionedNodes = autoLayout(nodes, connectors, stats);
+
+  stats.nodesOut = positionedNodes.length;
+  stats.connectorsOut = connectors.length;
+
+  return {
+    demo: {
+      version: 1,
+      name: req.wiring.name ?? 'Untitled diagram',
+      nodes: positionedNodes,
+      connectors,
+    },
+    stats,
+  };
+};
+
+const normalizeNodes = (
+  rawNodes: ReadonlyArray<Record<string, unknown>>,
+  positionMap: Record<string, { x: number; y: number }>,
+  stats: AssembleStats,
+): Array<Record<string, unknown>> => {
+  const seen = new Map<string, Record<string, unknown>>();
+  for (const raw of rawNodes) {
+    const id = slugify(String(raw.id ?? ''));
+    if (!id) continue;
+    const rawPos = positionMap[id] ??
+      (raw.position as { x: number; y: number } | undefined) ?? { x: 0, y: 0 };
+    const snapped = {
+      x: Math.round(rawPos.x / GRID) * GRID,
+      y: Math.round(rawPos.y / GRID) * GRID,
+    };
+    if (snapped.x !== rawPos.x || snapped.y !== rawPos.y) stats.positionsSnapped++;
+    if (seen.has(id)) stats.duplicateNodesDropped++;
+    seen.set(id, { ...raw, id, position: snapped });
+  }
+  return [...seen.values()];
+};
+
+const normalizeConnectors = (
+  rawConnectors: ReadonlyArray<Record<string, unknown>>,
+  nodeIds: Set<string>,
+  stats: AssembleStats,
+): Array<Record<string, unknown>> => {
+  const seen = new Map<string, Record<string, unknown>>();
+  for (const raw of rawConnectors) {
+    const source = slugify(String(raw.source ?? ''));
+    const target = slugify(String(raw.target ?? ''));
+    const id = slugify(String(raw.id ?? `c-${source}-${target}`));
+    if (!nodeIds.has(source) || !nodeIds.has(target)) {
+      stats.danglingConnectorsDropped++;
+      continue;
+    }
+    const key = [
+      source,
+      target,
+      String(raw.kind ?? ''),
+      String(raw.sourceHandle ?? ''),
+      String(raw.targetHandle ?? ''),
+    ].join('\t');
+    if (seen.has(key)) stats.duplicateConnectorsDropped++;
+    seen.set(key, { ...raw, id, source, target });
+  }
+  return [...seen.values()];
+};
+
+// Dagre-based auto-layout — exactly the algorithm the web canvas's "Tidy
+// layout" button runs (apps/web/src/lib/auto-layout.ts), so pressing Tidy on
+// a freshly-assembled demo never reshuffles the diagram.
+//
+//   • Direction: left-to-right (LR) — Actors on the left, data stores on the
+//     right, matching the lifecycle-lane intent of the layout-arranger agent.
+//   • `nodesep` / `ranksep` defaults give connectors a bit of extra length so
+//     edge labels fit and the canvas reads at a glance.
+//   • Sticky / text shape nodes stay pinned to their input position — they
+//     are floating annotations, not part of the flow graph.
+const LAYOUT_NODESEP = 60;
+const LAYOUT_RANKSEP = 140;
+const LAYOUT_DEFAULT_W = 200;
+const LAYOUT_DEFAULT_H = 120;
+
+const isFloatingAnnotation = (n: Record<string, unknown>): boolean => {
+  if (n.type !== 'shapeNode') return false;
+  const shape = (n.data as { shape?: string } | undefined)?.shape;
+  return shape === 'sticky' || shape === 'text';
+};
+
+const nodeDimensions = (n: Record<string, unknown>): { w: number; h: number } => {
+  const data = (n.data ?? {}) as { width?: number; height?: number; shape?: string };
+  const w =
+    typeof data.width === 'number'
+      ? data.width
+      : n.type === 'shapeNode' && data.shape === 'text'
+        ? 160
+        : LAYOUT_DEFAULT_W;
+  let h = LAYOUT_DEFAULT_H;
+  if (typeof data.height === 'number') h = data.height;
+  else if (n.type === 'shapeNode' && data.shape === 'text') h = 40;
+  else if (n.type === 'shapeNode' && data.shape === 'sticky') h = 180;
+  else if (n.type === 'imageNode') h = 150;
+  return { w, h };
+};
+
+const autoLayout = (
+  nodes: ReadonlyArray<Record<string, unknown>>,
+  connectors: ReadonlyArray<Record<string, unknown>>,
+  stats: AssembleStats,
+): Array<Record<string, unknown>> => {
+  if (nodes.length === 0) return [];
+
+  const flowNodes = nodes.filter((n) => !isFloatingAnnotation(n));
+  // A single flow node has no layout to compute — keep its input position so
+  // callers can pin standalone nodes via `layout.positions`.
+  if (flowNodes.length <= 1) return [...nodes];
+
+  const g = new dagre.graphlib.Graph({ multigraph: true });
+  g.setGraph({ rankdir: 'LR', nodesep: LAYOUT_NODESEP, ranksep: LAYOUT_RANKSEP });
+  g.setDefaultEdgeLabel(() => ({}));
+
+  const flowIds = new Set<string>();
+  const dims = new Map<string, { w: number; h: number }>();
+  for (const n of flowNodes) {
+    const id = n.id as string;
+    const { w, h } = nodeDimensions(n);
+    g.setNode(id, { width: w, height: h });
+    flowIds.add(id);
+    dims.set(id, { w, h });
+  }
+
+  let edgeCounter = 0;
+  for (const c of connectors) {
+    const s = c.source as string;
+    const t = c.target as string;
+    if (!flowIds.has(s) || !flowIds.has(t) || s === t) continue;
+    // multigraph + unique edge name preserves parallel connectors.
+    g.setEdge(s, t, {}, `e${edgeCounter++}`);
+  }
+
+  dagre.layout(g);
+
+  const snap = (v: number) => Math.round(v / GRID) * GRID;
+  return nodes.map((n) => {
+    if (isFloatingAnnotation(n)) return n;
+    const id = n.id as string;
+    const laid = g.node(id);
+    const d = dims.get(id);
+    if (!laid || !d) return n;
+    // dagre returns center coords; convert to top-left for React Flow.
+    const snapped = { x: snap(laid.x - d.w / 2), y: snap(laid.y - d.h / 2) };
+    const prev = (n.position as { x: number; y: number } | undefined) ?? { x: 0, y: 0 };
+    if (snapped.x !== prev.x || snapped.y !== prev.y) stats.positionsShifted++;
+    return { ...n, position: snapped };
+  });
+};
+
+// === validate ==============================================================
+
+export const TierSchema = z.enum(['real', 'mock', 'static']);
+export type Tier = z.infer<typeof TierSchema>;
+
+export const ValidateRequestSchema = z.object({
+  demo: z.unknown(),
+  tier: TierSchema.optional(),
+});
+
+export type ValidateRequest = z.infer<typeof ValidateRequestSchema>;
+
+export interface ValidateIssue {
+  kind: string;
+  path?: string;
+  message: string;
+}
+
+export interface ValidateReport {
+  ok: boolean;
+  stats: {
+    tier: Tier;
+    nodeCount: number;
+    connectorCount: number;
+    playableCount: number;
+    issueCount: number;
+    warningCount: number;
+  };
+  issues: ValidateIssue[];
+  warnings: ValidateIssue[];
+}
+
+// Filesystem-bound checks (harness coverage, event-emitter index) deliberately
+// stay in the skill — the studio doesn't reach into the user's `$TARGET`. The
+// endpoint covers schema + node-count cap + tier playability only.
+export const validateDemo = (req: ValidateRequest): ValidateReport => {
+  const tier: Tier = req.tier ?? 'static';
+  const issues: ValidateIssue[] = [];
+  const warnings: ValidateIssue[] = [];
+
+  const parsed = DemoSchema.safeParse(req.demo);
+  if (!parsed.success) {
+    for (const issue of parsed.error.issues) {
+      issues.push({
+        kind: 'zod',
+        path: issue.path.join('.') || '<root>',
+        message: issue.message,
+      });
+    }
+  }
+
+  // Best-effort access to nodes/connectors so cap + tier checks still surface
+  // on a demo that fails Zod (e.g. one extra/missing field shouldn't hide a
+  // 50-node count problem).
+  const rawDemo = (req.demo ?? {}) as {
+    nodes?: unknown;
+    connectors?: unknown;
+  };
+  const nodes: Array<Record<string, unknown>> = Array.isArray(rawDemo.nodes)
+    ? (rawDemo.nodes as Array<Record<string, unknown>>)
+    : [];
+  const connectors: unknown[] = Array.isArray(rawDemo.connectors) ? rawDemo.connectors : [];
+
+  if (nodes.length > 30) {
+    issues.push({ kind: 'cap', message: `Node count ${nodes.length} exceeds soft cap 30` });
+  } else if (nodes.length > 25) {
+    warnings.push({ kind: 'cap', message: `Node count ${nodes.length} approaching cap 30` });
+  }
+
+  const playable = nodes.filter((n) => {
+    const data = n.data as { playAction?: unknown } | undefined;
+    return n.type === 'playNode' || (n.type === 'stateNode' && data?.playAction !== undefined);
+  });
+  if (tier !== 'static' && playable.length === 0) {
+    issues.push({
+      kind: 'tier-mismatch',
+      message: `Tier '${tier}' requires at least one playable node; found 0. Either add a playNode or set tier=static.`,
+    });
+  }
+
+  if (tier === 'real') {
+    for (const n of nodes) {
+      const action = (n.data as { playAction?: { kind?: string; method?: string; url?: string } })
+        ?.playAction;
+      if (action?.kind !== 'http' || !action.url) continue;
+      warnings.push({
+        kind: 'real-tier-reachability',
+        message: `Node '${String(n.id)}': ensure ${action.method ?? '?'} ${action.url} is reachable in your dev server before clicking.`,
+      });
+    }
+  }
+
+  return {
+    ok: issues.length === 0,
+    stats: {
+      tier,
+      nodeCount: nodes.length,
+      connectorCount: connectors.length,
+      playableCount: playable.length,
+      issueCount: issues.length,
+      warningCount: warnings.length,
+    },
+    issues,
+    warnings,
+  };
+};

package/src/events.ts

@@ -0,0 +1,70 @@
+/**
+ * In-memory pub/sub keyed by demoId. Subscribers receive every event published
+ * for that demo until they unsubscribe; subscribers for other demos are not
+ * notified.
+ */
+
+export type StudioEventType =
+  | 'demo:reload'
+  | 'demo:reset'
+  | 'node:running'
+  | 'node:done'
+  | 'node:error'
+  | 'node:status'
+  | 'file:changed';
+
+export interface StudioEvent {
+  type: StudioEventType;
+  demoId: string;
+  /** Arbitrary JSON-serializable payload. Shape depends on event type. */
+  payload: unknown;
+  /** Server-side timestamp (ms since epoch). */
+  ts: number;
+}
+
+export type Subscriber = (event: StudioEvent) => void;
+
+export interface EventBus {
+  /** Subscribe to events for a specific demo. Returns an unsubscribe fn. */
+  subscribe(demoId: string, fn: Subscriber): () => void;
+  /** Broadcast an event to all subscribers of `demoId`. */
+  broadcast(event: Omit<StudioEvent, 'ts'> & { ts?: number }): void;
+  /** Number of active subscribers for a given demo (used in tests). */
+  subscriberCount(demoId: string): number;
+}
+
+export function createEventBus(): EventBus {
+  const subs = new Map<string, Set<Subscriber>>();
+
+  return {
+    subscribe(demoId, fn) {
+      let set = subs.get(demoId);
+      if (!set) {
+        set = new Set();
+        subs.set(demoId, set);
+      }
+      set.add(fn);
+      return () => {
+        const current = subs.get(demoId);
+        if (!current) return;
+        current.delete(fn);
+        if (current.size === 0) subs.delete(demoId);
+      };
+    },
+    broadcast(event) {
+      const set = subs.get(event.demoId);
+      if (!set) return;
+      const full: StudioEvent = { ...event, ts: event.ts ?? Date.now() };
+      for (const fn of set) {
+        try {
+          fn(full);
+        } catch (err) {
+          console.error('[events] subscriber threw, dropping:', err);
+        }
+      }
+    },
+    subscriberCount(demoId) {
+      return subs.get(demoId)?.size ?? 0;
+    },
+  };
+}

package/src/mcp-shim.ts

@@ -0,0 +1,93 @@
+#!/usr/bin/env bun
+// SeeFlow MCP stdio shim.
+//
+// Bridges an MCP stdio client (e.g. Claude Code via .mcp.json) to the studio's
+// HTTP `/mcp` endpoint. Every JSON-RPC message received on stdin is forwarded
+// to the studio via a Streamable HTTP MCP client transport; every response is
+// piped back to stdout. The shim never interprets tool semantics — it's a
+// transparent JSON-RPC proxy keyed off message ids.
+//
+// Default target: http://127.0.0.1:4321/mcp. Override with SEEFLOW_STUDIO_URL.
+
+import {
+  StreamableHTTPClientTransport,
+  StreamableHTTPError,
+} from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { type JSONRPCMessage, isJSONRPCRequest } from '@modelcontextprotocol/sdk/types.js';
+
+const DEFAULT_URL = 'http://127.0.0.1:4321/mcp';
+const STUDIO_NOT_RUNNING_MSG = 'SeeFlow studio is not running. Start it with `bun run dev` first.';
+const STUDIO_WITHOUT_MCP_MSG = 'This studio version does not expose MCP. Upgrade required.';
+
+const url = new URL(process.env.SEEFLOW_STUDIO_URL ?? DEFAULT_URL);
+
+const stdio = new StdioServerTransport();
+const http = new StreamableHTTPClientTransport(url);
+
+// Walk the error and its `cause` chain looking for the signatures Bun and
+// Node use for refused TCP connects. Bun's fetch surfaces this as a
+// TypeError whose cause carries `code: 'ConnectionRefused'`; Node's undici
+// uses `code: 'ECONNREFUSED'` on the cause. Match either pattern, plus the
+// human-readable variants seen in the wild.
+const isConnectionRefused = (err: unknown): boolean => {
+  const seen = new Set<unknown>();
+  const visit = (e: unknown): boolean => {
+    if (!e || typeof e !== 'object' || seen.has(e)) return false;
+    seen.add(e);
+    const obj = e as Record<string, unknown>;
+    const code = typeof obj.code === 'string' ? obj.code : '';
+    if (code === 'ECONNREFUSED' || code === 'ConnectionRefused') return true;
+    const message = typeof obj.message === 'string' ? obj.message : '';
+    if (/econnrefused|connection refused|unable to connect/i.test(message)) return true;
+    return visit(obj.cause);
+  };
+  return visit(err);
+};
+
+const isMcpNotMounted = (err: unknown): boolean =>
+  err instanceof StreamableHTTPError && err.code === 404;
+
+const errorMessageFor = (err: unknown): string => {
+  if (isConnectionRefused(err)) return STUDIO_NOT_RUNNING_MSG;
+  if (isMcpNotMounted(err)) return STUDIO_WITHOUT_MCP_MSG;
+  return err instanceof Error ? err.message : String(err);
+};
+
+// Forward studio responses → stdout.
+http.onmessage = (msg) => {
+  void stdio.send(msg);
+};
+http.onerror = () => {
+  // Errors are surfaced as JSON-RPC error responses by the stdio.onmessage
+  // catch block below. Silence the transport's own onerror so a single fetch
+  // failure doesn't double-log to stderr.
+};
+
+// Forward stdin requests → studio. On transport failure, synthesize a
+// JSON-RPC error response so the upstream client sees a graceful error
+// instead of a hang.
+stdio.onmessage = async (msg) => {
+  try {
+    await http.send(msg);
+  } catch (err) {
+    if (!isJSONRPCRequest(msg)) return;
+    const errorResponse: JSONRPCMessage = {
+      jsonrpc: '2.0',
+      id: msg.id,
+      error: { code: -32000, message: errorMessageFor(err) },
+    };
+    await stdio.send(errorResponse).catch(() => undefined);
+  }
+};
+
+await http.start();
+await stdio.start();
+
+const shutdown = async () => {
+  await stdio.close().catch(() => undefined);
+  await http.close().catch(() => undefined);
+  process.exit(0);
+};
+process.on('SIGINT', () => void shutdown());
+process.on('SIGTERM', () => void shutdown());