@tuongaz/seeflow 0.1.42 → 0.1.51

package/examples/order-pipeline/.seeflow/flow.json

@@ -12,7 +12,7 @@
           "kind": "request"
         },
         "description": "Creates order, kicks off the pipeline.",
-        "detail": "file://nodes/node-XKIyds0TDg/detail.md",
+        "detail": "file://detail.md",
         "playAction": {
           "kind": "script",
           "interpreter": "bun",
@@ -33,7 +33,7 @@
           "kind": "event"
         },
         "description": "Reserves stock.",
-        "detail": "file://nodes/node-GXTKUcE3ye/detail.md",
+        "detail": "file://detail.md",
         "icon": "a-arrow-down-icon"
       }
     },
@@ -47,7 +47,7 @@
           "kind": "event"
         },
         "description": "Charges card.",
-        "detail": "file://nodes/node-YOYiHJpY0i/detail.md"
+        "detail": "file://detail.md"
       }
     },
     {
@@ -60,7 +60,7 @@
           "kind": "event"
         },
         "description": "Enqueues shipment.",
-        "detail": "file://nodes/node-zUIH7WFnhK/detail.md"
+        "detail": "file://detail.md"
       }
     }
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tuongaz/seeflow",
-  "version": "0.1.42",
+  "version": "0.1.51",
   "description": "Local studio that hosts file-defined demos as React Flow canvases wired to a running app via REST + SSE + Zod schema.",
   "keywords": [
     "seeflow",
@@ -49,6 +49,7 @@
     "zod-to-json-schema": "^3.25.2"
   },
   "devDependencies": {
+    "@playwright/test": "^1.60.0",
     "@tailwindcss/browser": "^4.3.0",
     "@types/bun": "^1.1.14",
     "typescript": "^5.6.3"

package/src/api.ts

@@ -23,23 +23,8 @@ import {
   RegisterBodySchema,
   ReorderBodySchema,
   type ValidateBody,
-  addConnectorImpl,
-  addConnectorsBulkImpl,
-  addNodeImpl,
-  addNodesBulkImpl,
-  createProjectImpl,
-  deleteConnectorImpl,
-  deleteFlowImpl,
-  deleteNodeImpl,
-  getFlowImpl,
-  listDemosImpl,
-  moveNodeImpl,
-  patchConnectorImpl,
-  patchNodeImpl,
-  registerFlowImpl,
-  reorderNodeImpl,
+  createOperations,
   resolveFilePath,
-  validateImpl,
   writeFileAtomic,
 } from './operations.ts';
 import type { ProcessSpawner } from './process-spawner.ts';
@@ -220,6 +205,7 @@ export function createApi(options: ApiOptions): Hono {
   const processSpawner = options.processSpawner;
   const proxy = options.proxy ?? defaultProxyFacade;
   const projectBaseDir = options.projectBaseDir;
+  const ops = createOperations({ registry, watcher, projectBaseDir });
   const api = new Hono();
 
   api.post('/flows/register', async (c) => {
@@ -235,7 +221,7 @@ export function createApi(options: ApiOptions): Hono {
       return c.json({ error: 'Invalid register body', issues: parsed.error.issues }, 400);
     }
 
-    const result = await registerFlowImpl({ registry, watcher }, parsed.data);
+    const result = await ops.registerFlow(parsed.data);
     switch (result.kind) {
       case 'ok':
         return c.json(result.data);
@@ -290,7 +276,7 @@ export function createApi(options: ApiOptions): Hono {
     if (!body || typeof body !== 'object' || !('flow' in body)) {
       return c.json({ error: 'Body must be { flow, style? }' }, 400);
     }
-    return c.json(validateImpl(body as ValidateBody));
+    return c.json(ops.validate(body as ValidateBody));
   });
 
   // POST /api/diagram/propose-scope — Phase 2 helper. The skill POSTs the
@@ -452,7 +438,7 @@ export function createApi(options: ApiOptions): Hono {
       return c.json({ error: 'Invalid create project body', issues: parsed.error.issues }, 400);
     }
 
-    const result = await createProjectImpl({ registry, watcher, projectBaseDir }, parsed.data);
+    const result = await ops.createProject(parsed.data);
     switch (result.kind) {
       case 'ok':
         return c.json(result.data);
@@ -471,12 +457,50 @@ export function createApi(options: ApiOptions): Hono {
   });
 
   api.get('/flows', (c) => {
-    const result = listDemosImpl({ registry });
+    const result = ops.listFlows();
+    return c.json(result.data);
+  });
+
+  // Lightweight projection: id, name, description only. Reads from the
+  // watcher snapshot when available so author edits to flow.json show up
+  // immediately; falls back to the registry copy persisted at register time.
+  api.get('/flows/summary', (c) => {
+    const result = ops.listFlowsSummary();
     return c.json(result.data);
   });
 
   api.get('/flows/:id', async (c) => {
-    const result = await getFlowImpl({ registry, watcher }, c.req.param('id'));
+    const result = await ops.getFlow(c.req.param('id'));
+    switch (result.kind) {
+      case 'ok':
+        return c.json(result.data);
+      case 'notFound':
+        return c.json({ error: 'not found' }, 404);
+      case 'fileNotFound':
+        return c.json({ error: `Flow file not found: ${result.path}` }, 404);
+    }
+  });
+
+  // Flow skeleton without per-node file content (detail.md / view.html).
+  // Pairs with GET /flows/:id/nodes/:nodeId for full per-node detail.
+  api.get('/flows/:id/graph', async (c) => {
+    const result = await ops.getFlowGraph(c.req.param('id'));
+    switch (result.kind) {
+      case 'ok':
+        return c.json(result.data);
+      case 'notFound':
+        return c.json({ error: 'not found' }, 404);
+      case 'fileNotFound':
+        return c.json({ error: `Flow file not found: ${result.path}` }, 404);
+      case 'badJson':
+        return c.json({ error: 'Flow file is not valid JSON', detail: result.detail }, 400);
+      case 'badSchema':
+        return c.json({ error: 'Flow file failed schema validation', issues: result.issues }, 400);
+    }
+  });
+
+  api.get('/flows/:id/nodes/:nodeId', async (c) => {
+    const result = await ops.getNode(c.req.param('id'), c.req.param('nodeId'));
     switch (result.kind) {
       case 'ok':
         return c.json(result.data);
@@ -484,6 +508,12 @@ export function createApi(options: ApiOptions): Hono {
         return c.json({ error: 'not found' }, 404);
       case 'fileNotFound':
         return c.json({ error: `Flow file not found: ${result.path}` }, 404);
+      case 'unknownNode':
+        return c.json({ error: `Unknown nodeId: ${c.req.param('nodeId')}` }, 404);
+      case 'badJson':
+        return c.json({ error: 'Flow file is not valid JSON', detail: result.detail }, 400);
+      case 'badSchema':
+        return c.json({ error: 'Flow file failed schema validation', issues: result.issues }, 400);
     }
   });
 
@@ -680,7 +710,7 @@ export function createApi(options: ApiOptions): Hono {
   });
 
   api.delete('/flows/:id', (c) => {
-    const result = deleteFlowImpl({ registry, watcher }, c.req.param('id'));
+    const result = ops.deleteFlow(c.req.param('id'));
     switch (result.kind) {
       case 'ok':
         return c.json({ ok: true });
@@ -698,37 +728,6 @@ export function createApi(options: ApiOptions): Hono {
   // file / unknown id / bad JSON / write failure returns HTTP 4xx/5xx.
   api.post('/flows/:id/layout', async (c) => {
     const id = c.req.param('id');
-    const entry = registry.getById(id);
-    if (!entry) return c.json({ error: 'unknown demo' }, 404);
-
-    const flowAbs = resolveFilePath(entry.repoPath, entry.flowPath);
-    if (!existsSync(flowAbs)) return c.json({ error: `Flow file not found: ${flowAbs}` }, 404);
-
-    let raw: unknown;
-    try {
-      raw = JSON.parse(readFileSync(flowAbs, 'utf8'));
-    } catch (err) {
-      return c.json(
-        {
-          error: 'Flow file is not valid JSON',
-          detail: err instanceof Error ? err.message : String(err),
-        },
-        400,
-      );
-    }
-
-    const flowParse = FlowSchema.safeParse(raw);
-    if (!flowParse.success) {
-      return c.json({
-        ok: false as const,
-        issues: flowParse.error.issues.map((i) => ({
-          scope: 'flow' as const,
-          path: [...i.path],
-          message: i.message,
-          code: i.code,
-        })),
-      });
-    }
 
     // Empty body is valid — the skill always uses defaults. Only parse if the
     // caller actually sent something.
@@ -743,41 +742,27 @@ export function createApi(options: ApiOptions): Hono {
       }
     }
 
-    const flow = flowParse.data;
-    const result = await computeLayout(
-      flow.nodes.map((n) => ({
-        id: n.id,
-        type: n.type,
-        // Only `shape` matters for layout (floating-annotation detection +
-        // shape-specific sizing). Other Flow data fields are irrelevant.
-        data: n.type === 'shapeNode' ? { shape: (n.data as { shape?: string }).shape } : undefined,
-      })),
-      flow.connectors.map((c) => ({ id: c.id, source: c.source, target: c.target })),
-      options,
-    );
-
-    const styleAbs = join(dirname(flowAbs), 'style.json');
-    const styleContent = `${JSON.stringify(result, null, 2)}\n`;
-    try {
-      writeFileAtomic(styleAbs, styleContent);
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      return c.json({ error: `Failed to write style file: ${msg}` }, 500);
-    }
-
-    // Reparse + notifyWritten: the watcher seeds its snapshot AND broadcasts
-    // flow:reload with the new merged payload directly, while suppressing the
-    // fs-watcher echo that the style.json write would otherwise trigger.
-    const snap = watcher?.reparse(id);
-    if (watcher && snap) {
-      const flowContent = readFileSync(flowAbs, 'utf8');
-      watcher.notifyWritten(id, snap, flowContent, styleContent);
-    } else {
-      // No watcher (test harness, or watch() hasn't been called yet) — emit a
-      // bare flow:reload so any subscribers still react.
-      events?.broadcast({ type: 'flow:reload', flowId: id, payload: {} });
-    }
-    return c.json({ ok: true as const });
+    const result = await ops.applyLayout(id, options);
+    switch (result.kind) {
+      case 'ok':
+        // No watcher (test harness, or watch() hasn't been called yet) — emit
+        // a bare flow:reload so any subscribers still react. When the watcher
+        // exists, applyLayoutImpl already notified it directly.
+        if (!watcher) {
+          events?.broadcast({ type: 'flow:reload', flowId: id, payload: {} });
+        }
+        return c.json({ ok: true as const });
+      case 'flowNotFound':
+        return c.json({ error: 'unknown demo' }, 404);
+      case 'fileNotFound':
+        return c.json({ error: `Flow file not found: ${result.path}` }, 404);
+      case 'badJson':
+        return c.json({ error: 'Flow file is not valid JSON', detail: result.detail }, 400);
+      case 'badSchema':
+        return c.json({ ok: false as const, issues: result.issues });
+      case 'writeFailed':
+        return c.json({ error: `Failed to write style file: ${result.message}` }, 500);
+    }
   });
 
   api.post('/flows/:id/play/:nodeId', async (c) => {
@@ -934,7 +919,7 @@ export function createApi(options: ApiOptions): Hono {
       return c.json({ error: 'Invalid position body', issues: parsed.error.issues }, 400);
     }
 
-    const result = await moveNodeImpl({ registry, watcher }, id, nodeId, parsed.data);
+    const result = await ops.moveNode(id, nodeId, parsed.data);
     switch (result.kind) {
       case 'ok':
         return c.json({ ok: true, position: result.data.position });
@@ -975,7 +960,7 @@ export function createApi(options: ApiOptions): Hono {
       return c.json({ error: 'Invalid reorder body', issues: parsed.error.issues }, 400);
     }
 
-    const result = await reorderNodeImpl({ registry, watcher }, id, nodeId, parsed.data);
+    const result = await ops.reorderNode(id, nodeId, parsed.data);
     switch (result.kind) {
       case 'ok':
         return c.json({ ok: true });
@@ -1016,7 +1001,7 @@ export function createApi(options: ApiOptions): Hono {
       return c.json({ error: 'Invalid node patch body', issues: parsed.error.issues }, 400);
     }
 
-    const result = await patchNodeImpl({ registry, watcher }, id, nodeId, parsed.data);
+    const result = await ops.patchNode(id, nodeId, parsed.data);
     switch (result.kind) {
       case 'ok':
         return c.json({ ok: true });
@@ -1051,7 +1036,7 @@ export function createApi(options: ApiOptions): Hono {
       return c.json({ error: 'Body must be an object' }, 400);
     }
 
-    const result = await addNodeImpl({ registry, watcher }, id, body as Record<string, unknown>);
+    const result = await ops.addNode(id, body as Record<string, unknown>);
     switch (result.kind) {
       case 'ok':
         return c.json({ ok: true, id: result.data.id, node: result.data.node });
@@ -1086,7 +1071,7 @@ export function createApi(options: ApiOptions): Hono {
       return c.json({ error: 'Invalid bulk nodes body', issues: parsed.error.issues }, 400);
     }
 
-    const result = await addNodesBulkImpl({ registry, watcher }, id, parsed.data);
+    const result = await ops.addNodesBulk(id, parsed.data);
     switch (result.kind) {
       case 'ok':
         return c.json({ ok: true, nodes: result.data.nodes });
@@ -1116,7 +1101,7 @@ export function createApi(options: ApiOptions): Hono {
     const id = c.req.param('id');
     const nodeId = c.req.param('nodeId');
 
-    const result = await deleteNodeImpl({ registry, watcher }, id, nodeId);
+    const result = await ops.deleteNode(id, nodeId);
     switch (result.kind) {
       case 'ok':
         return c.json({ ok: true });
@@ -1157,7 +1142,7 @@ export function createApi(options: ApiOptions): Hono {
       return c.json({ error: 'Invalid connector patch body', issues: parsed.error.issues }, 400);
     }
 
-    const result = await patchConnectorImpl({ registry, watcher }, id, connId, parsed.data);
+    const result = await ops.patchConnector(id, connId, parsed.data);
     switch (result.kind) {
       case 'ok':
         return c.json({ ok: true });
@@ -1193,11 +1178,7 @@ export function createApi(options: ApiOptions): Hono {
       return c.json({ error: 'Body must be an object' }, 400);
     }
 
-    const result = await addConnectorImpl(
-      { registry, watcher },
-      id,
-      body as Record<string, unknown>,
-    );
+    const result = await ops.addConnector(id, body as Record<string, unknown>);
     switch (result.kind) {
       case 'ok':
         return c.json({ ok: true, id: result.data.id });
@@ -1231,7 +1212,7 @@ export function createApi(options: ApiOptions): Hono {
       return c.json({ error: 'Invalid bulk connectors body', issues: parsed.error.issues }, 400);
     }
 
-    const result = await addConnectorsBulkImpl({ registry, watcher }, id, parsed.data);
+    const result = await ops.addConnectorsBulk(id, parsed.data);
     switch (result.kind) {
       case 'ok':
         return c.json({ ok: true, connectors: result.data.connectors });
@@ -1258,7 +1239,7 @@ export function createApi(options: ApiOptions): Hono {
     const id = c.req.param('id');
     const connId = c.req.param('connId');
 
-    const result = await deleteConnectorImpl({ registry, watcher }, id, connId);
+    const result = await ops.deleteConnector(id, connId);
     switch (result.kind) {
       case 'ok':
         return c.json({ ok: true });
@@ -1368,5 +1349,60 @@ export function createApi(options: ApiOptions): Hono {
     });
   });
 
+  // Global registry channel — broadcasts `registry:reload` when an external
+  // process (e.g. the CLI) writes to ~/.seeflow/registry.json. Subscribers
+  // re-fetch the flow list. The channel id is the internal sentinel from
+  // registry-watcher.ts (kept inline to avoid leaking the constant into
+  // every SSE consumer).
+  api.get('/registry/events', (c) => {
+    if (!events) return c.json({ error: 'events not enabled' }, 500);
+
+    return streamSSE(c, async (stream) => {
+      let active = true;
+      const queue: Array<{ event: string; data: string }> = [];
+      let resume: (() => void) | null = null;
+
+      const wake = () => {
+        if (resume) {
+          const r = resume;
+          resume = null;
+          r();
+        }
+      };
+
+      const unsubscribe = events.subscribe('__registry__', (e) => {
+        queue.push({ event: e.type, data: JSON.stringify({ ts: e.ts }) });
+        wake();
+      });
+
+      stream.onAbort(() => {
+        active = false;
+        unsubscribe();
+        wake();
+      });
+
+      await stream.writeSSE({
+        event: 'hello',
+        data: JSON.stringify({ channel: 'registry', ts: Date.now() }),
+      });
+
+      try {
+        while (active) {
+          while (queue.length > 0) {
+            const next = queue.shift();
+            if (!next) break;
+            await stream.writeSSE(next);
+          }
+          if (!active) break;
+          await new Promise<void>((r) => {
+            resume = r;
+          });
+        }
+      } finally {
+        unsubscribe();
+      }
+    });
+  });
+
   return api;
 }

package/src/cli-e2e.ts

@@ -63,7 +63,7 @@ interface NodeShape {
   };
 }
 
-interface DemoShape {
+interface FlowBody {
   nodes?: NodeShape[];
 }
 
@@ -71,7 +71,11 @@ interface FlowGetResponse {
   id?: string;
   valid?: boolean;
   error?: string | null;
-  demo?: DemoShape | null;
+  // GET /api/flows/:id returns the resolved flow under the `flow` key (see
+  // FlowGetResponse in operations.ts). Older versions of this file used `demo`,
+  // which left the validator effectively broken (every call returned `ok:false`
+  // with "demo not valid"). Renamed to match the wire format.
+  flow?: FlowBody | null;
 }
 
 interface SseEvent {
@@ -200,21 +204,21 @@ export async function validateEndToEnd(options: ValidateOptions): Promise<Valida
     };
   }
   const demoData = (await demoRes.json()) as FlowGetResponse;
-  if (!demoData.valid || !demoData.demo) {
+  if (!demoData.valid || !demoData.flow) {
     return {
       ok: false,
       plays,
       statuses,
       skipped: [
         {
-          nodeId: '<demo>',
-          reason: `demo not valid: ${demoData.error ?? '<no error>'}`,
+          nodeId: '<flow>',
+          reason: `flow not valid: ${demoData.error ?? '<no error>'}`,
         },
       ],
     };
   }
 
-  const nodes = demoData.demo.nodes ?? [];
+  const nodes = demoData.flow.nodes ?? [];
 
   const skipSet = new Set(options.skipNodes ?? []);
   const playTargets: string[] = [];

package/src/cli-helpers.ts

@@ -56,6 +56,85 @@ export function printError(message: string, opts: CliOutcomeOptions = {}): never
   return (opts.exit ?? (process.exit as (code: number) => never))(1);
 }
 
+/**
+ * Print an Operations Outcome and exit with the differentiated exit code:
+ *  - kind === 'ok'                → printOk(data), exit 0
+ *  - kind === 'badSchema'|'badJson'                   → exit 2
+ *  - kind === 'notFound'|'flowNotFound'|'fileNotFound'|
+ *             'unknownNode'|'unknownConnector'        → exit 3
+ *  - kind === 'duplicateIdInBatch'|'idAlreadyExists'  → exit 4
+ *  - kind === 'writeFailed'|'sdkWriteFailed'|'scaffoldFailed' → exit 5
+ *  - anything else                                    → exit 1
+ *
+ * The error message mirrors the strings used by api.ts so the CLI's
+ * stderr output stays stable across the HTTP-to-in-process migration.
+ */
+export function printOutcome<T extends { kind: string }>(
+  outcome: T,
+  opts: CliOutcomeOptions = {},
+): never {
+  if (outcome.kind === 'ok') {
+    const data = (outcome as unknown as { data: unknown }).data;
+    return printOk(
+      data && typeof data === 'object' && !Array.isArray(data) ? data : { data },
+      opts,
+    );
+  }
+  const err = opts.stderr ?? ((s) => process.stderr.write(s));
+  const message = describeOutcome(outcome);
+  err(`${JSON.stringify({ error: message, code: outcome.kind })}\n`);
+  return (opts.exit ?? (process.exit as (code: number) => never))(exitCodeForKind(outcome.kind));
+}
+
+function describeOutcome(outcome: { kind: string } & Record<string, unknown>): string {
+  switch (outcome.kind) {
+    case 'notFound':
+    case 'flowNotFound':
+      return 'not found';
+    case 'fileNotFound':
+      return `Flow file not found: ${String(outcome.path ?? '')}`;
+    case 'unknownNode':
+      return `Unknown nodeId: ${String(outcome.nodeId ?? '')}`;
+    case 'unknownConnector':
+      return `Unknown connectorId: ${String(outcome.connectorId ?? '')}`;
+    case 'badJson':
+      return `Flow file is not valid JSON: ${String(outcome.detail ?? outcome.message ?? '')}`;
+    case 'badSchema':
+      return `Flow failed schema validation: ${JSON.stringify(outcome.issues ?? [])}`;
+    case 'duplicateIdInBatch':
+      return `Duplicate id in batch: ${String(outcome.id ?? '')}`;
+    case 'idAlreadyExists':
+      return `Id already exists: ${String(outcome.id ?? '')}`;
+    case 'writeFailed':
+      return `Failed to write demo file: ${String(outcome.message ?? '')}`;
+    case 'sdkWriteFailed':
+      return `Failed to write SDK helper: ${String(outcome.message ?? '')}`;
+    case 'scaffoldFailed':
+      return `Failed to scaffold project: ${String(outcome.message ?? '')}`;
+    default:
+      return String(outcome.message ?? outcome.kind);
+  }
+}
+
+export const EXIT_CODE_BY_KIND: Record<string, number> = {
+  badSchema: 2,
+  badJson: 2,
+  notFound: 3,
+  flowNotFound: 3,
+  fileNotFound: 3,
+  unknownNode: 3,
+  unknownConnector: 3,
+  duplicateIdInBatch: 4,
+  idAlreadyExists: 4,
+  writeFailed: 5,
+  sdkWriteFailed: 5,
+  scaffoldFailed: 5,
+};
+
+export function exitCodeForKind(kind: string): number {
+  return EXIT_CODE_BY_KIND[kind] ?? 1;
+}
+
 export const drainStdin: StdinReader = async () => {
   const chunks: Uint8Array[] = [];
   for await (const chunk of process.stdin as unknown as AsyncIterable<Uint8Array>) {