@tuongaz/seeflow 0.1.64 → 0.1.68

package/examples/ecommerce-platform/flow.json

@@ -4,23 +4,22 @@
   "nodes": [
     {
       "id": "node-cQOUPXanaX",
-      "type": "shapeNode",
+      "type": "user",
       "data": {
-        "shape": "user",
         "name": "Customer",
         "description": "Web / Mobile / Partner"
       }
     },
     {
       "id": "node-CbwYqb7NfB",
-      "type": "playNode",
+      "type": "rectangle",
       "data": {
         "name": "API Gateway",
+        "description": "Auth, rate-limiting, routing.",
+        "detail": "file://detail.md",
         "stateSource": {
           "kind": "request"
         },
-        "description": "Auth, rate-limiting, routing.",
-        "detail": "file://detail.md",
         "playAction": {
           "kind": "script",
           "interpreter": "bun",
@@ -31,38 +30,38 @@
     },
     {
       "id": "node-3zFtHg6ENc",
-      "type": "stateNode",
+      "type": "rectangle",
       "data": {
         "name": "Auth Service",
+        "description": "JWT issuance + OAuth2 / OIDC.",
+        "detail": "file://detail.md",
         "stateSource": {
           "kind": "request"
-        },
-        "description": "JWT issuance + OAuth2 / OIDC.",
-        "detail": "file://detail.md"
+        }
       }
     },
     {
       "id": "node-kwBY8YPmYM",
-      "type": "stateNode",
+      "type": "rectangle",
       "data": {
         "name": "Product Catalog",
+        "description": "SKUs, variants, pricing, full-text search.",
+        "detail": "file://detail.md",
         "stateSource": {
           "kind": "request"
-        },
-        "description": "SKUs, variants, pricing, full-text search.",
-        "detail": "file://detail.md"
+        }
       }
     },
     {
       "id": "node-5F424NWbEu",
-      "type": "playNode",
+      "type": "rectangle",
       "data": {
         "name": "Cart Service",
+        "description": "Add/remove items, apply coupons, checkout.",
+        "detail": "file://detail.md",
         "stateSource": {
           "kind": "request"
         },
-        "description": "Add/remove items, apply coupons, checkout.",
-        "detail": "file://detail.md",
         "playAction": {
           "kind": "script",
           "interpreter": "bun",
@@ -73,14 +72,14 @@
     },
     {
       "id": "node-yKrg9DV5fJ",
-      "type": "playNode",
+      "type": "rectangle",
       "data": {
         "name": "Order Service",
+        "description": "pending → confirmed → shipped → delivered.",
+        "detail": "file://detail.md",
         "stateSource": {
           "kind": "event"
         },
-        "description": "pending → confirmed → shipped → delivered.",
-        "detail": "file://detail.md",
         "playAction": {
           "kind": "script",
           "interpreter": "bun",
@@ -91,40 +90,39 @@
     },
     {
       "id": "node-mPqan8rFYN",
-      "type": "stateNode",
+      "type": "rectangle",
       "data": {
         "name": "Payment Service",
+        "description": "Stripe + PayPal gateway integration.",
+        "detail": "file://detail.md",
         "stateSource": {
           "kind": "event"
-        },
-        "description": "Stripe + PayPal gateway integration.",
-        "detail": "file://detail.md"
+        }
       }
     },
     {
       "id": "node-fkptXw7uvs",
-      "type": "stateNode",
+      "type": "rectangle",
       "data": {
         "name": "Notification Service",
+        "description": "Email + SMS + push via AWS SES / SNS.",
+        "detail": "file://detail.md",
         "stateSource": {
           "kind": "event"
-        },
-        "description": "Email + SMS + push via AWS SES / SNS.",
-        "detail": "file://detail.md"
+        }
       }
     },
     {
       "id": "node-5SDiw3Wz6s",
-      "type": "shapeNode",
+      "type": "database",
       "data": {
-        "shape": "database",
         "name": "PostgreSQL",
         "description": "Orders, users, products — primary OLTP store"
       }
     },
     {
       "id": "node-XwygzfKPZ5",
-      "type": "htmlNode",
+      "type": "html",
       "data": {
         "name": "Platform Health",
         "html": "file://view.html"

package/examples/order-pipeline/flow.json

@@ -4,14 +4,14 @@
   "nodes": [
     {
       "id": "node-XKIyds0TDg",
-      "type": "playNode",
+      "type": "rectangle",
       "data": {
         "name": "POST /orders",
+        "description": "Creates order, kicks off the pipeline.",
+        "detail": "file://detail.md",
         "stateSource": {
           "kind": "request"
         },
-        "description": "Creates order, kicks off the pipeline.",
-        "detail": "file://detail.md",
         "playAction": {
           "kind": "script",
           "interpreter": "bun",
@@ -22,39 +22,39 @@
     },
     {
       "id": "node-GXTKUcE3ye",
-      "type": "stateNode",
+      "type": "rectangle",
       "data": {
         "name": "Inventory Service",
-        "stateSource": {
-          "kind": "event"
-        },
         "description": "Reserves stock.",
         "detail": "file://detail.md",
-        "icon": "a-arrow-down-icon"
+        "icon": "a-arrow-down-icon",
+        "stateSource": {
+          "kind": "event"
+        }
       }
     },
     {
       "id": "node-YOYiHJpY0i",
-      "type": "stateNode",
+      "type": "rectangle",
       "data": {
         "name": "Payment Service",
+        "description": "Charges card.",
+        "detail": "file://detail.md",
         "stateSource": {
           "kind": "event"
-        },
-        "description": "Charges card.",
-        "detail": "file://detail.md"
+        }
       }
     },
     {
       "id": "node-zUIH7WFnhK",
-      "type": "stateNode",
+      "type": "rectangle",
       "data": {
         "name": "Fulfillment Service",
+        "description": "Enqueues shipment.",
+        "detail": "file://detail.md",
         "stateSource": {
           "kind": "event"
-        },
-        "description": "Enqueues shipment.",
-        "detail": "file://detail.md"
+        }
       }
     }
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tuongaz/seeflow",
-  "version": "0.1.64",
+  "version": "0.1.68",
   "description": "Local studio that hosts file-defined demos as React Flow canvases wired to a running app via REST + SSE + Zod schema.",
   "keywords": [
     "seeflow",
@@ -43,6 +43,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "@seeflow/canvas": "workspace:*",
     "elkjs": "^0.11.1",
     "hono": "^4.6.14",
     "zod": "^3.23.8",

package/src/api.ts

@@ -3,6 +3,7 @@ import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
 import { Hono } from 'hono';
 import { streamSSE } from 'hono/streaming';
 import { z } from 'zod';
+import { runComponentAction } from './component-action-runner.ts';
 import {
   AssembleRequestSchema,
   ProposeScopeRequestSchema,
@@ -38,6 +39,7 @@ import {
 } from './proxy.ts';
 import type { Registry } from './registry.ts';
 import { getSchemaCategory, listSchemaCategories, schemaCategoryNames } from './schema-catalog.ts';
+import type { ComponentAction } from './schema.ts';
 import { FlowSchema, ResolvedFlowSchema } from './schema.ts';
 import { type Spawner, defaultSpawner } from './shellout.ts';
 import { ID_TYPES, MAX_ID_COUNT, generateIds, isIdType } from './short-id.ts';
@@ -345,14 +347,7 @@ 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.nodes.map((n) => ({ id: n.id, type: n.type })),
         flow.connectors.map((c) => ({ id: c.id, source: c.source, target: c.target })),
         options,
       );
@@ -375,12 +370,18 @@ export function createApi(options: ApiOptions): Hono {
         .map((n) => ({
           id: n.id,
           type: n.type as
-            | 'playNode'
-            | 'stateNode'
-            | 'shapeNode'
-            | 'imageNode'
-            | 'iconNode'
-            | 'htmlNode',
+            | 'rectangle'
+            | 'ellipse'
+            | 'sticky'
+            | 'text'
+            | 'database'
+            | 'server'
+            | 'user'
+            | 'queue'
+            | 'cloud'
+            | 'image'
+            | 'html'
+            | 'icon',
           data:
             typeof n.width === 'number' && typeof n.height === 'number'
               ? { width: n.width, height: n.height }
@@ -582,7 +583,7 @@ export function createApi(options: ApiOptions): Hono {
   });
 
   // POST /api/projects/:id/files/open — shell out to `$EDITOR <abs>` so the
-  // user can edit a project-scoped file (htmlNode block, image asset) in
+  // user can edit a project-scoped file (type:'html' block, image asset) in
   // their IDE. The endpoint always returns the resolved absolute path in
   // the response body so the frontend can copy-to-clipboard when $EDITOR
   // isn't set or the spawn fails. Path safety mirrors the GET route.
@@ -815,13 +816,10 @@ export function createApi(options: ApiOptions): Hono {
 
     const node = merged.flow.nodes.find((n) => n.id === nodeId);
     if (!node) return c.json({ error: `Unknown nodeId: ${nodeId}` }, 404);
-    if (
-      node.type === 'shapeNode' ||
-      node.type === 'imageNode' ||
-      node.type === 'iconNode' ||
-      node.type === 'htmlNode' ||
-      !node.data.playAction
-    ) {
+    // playAction is optional on every node type post-flat-types. The runtime
+    // gate is purely "is the field set?" — visual kind doesn't constrain
+    // playability.
+    if (!node.data.playAction) {
       return c.json({ error: `Node ${nodeId} has no playAction` }, 400);
     }
 
@@ -854,6 +852,58 @@ export function createApi(options: ApiOptions): Hono {
     return c.json(result);
   });
 
+  // POST /api/flows/:id/nodes/:nodeId/actions/:name — dispatch a component
+  // node's named action over HTTP. Only `script`-kind actions cross this seam;
+  // `set`-kind actions mutate canvas state locally and never round-trip
+  // through the API (the runner rejects them with statusHint 400).
+  // Payload is the JSON request body (defaults to {} on parse failure) and is
+  // piped to the script's stdin by `runComponentAction`. Response is the
+  // script's parsed JSON stdout on success.
+  api.post('/flows/:id/nodes/:nodeId/actions/:name', async (c) => {
+    const id = c.req.param('id');
+    const nodeId = c.req.param('nodeId');
+    const actionName = c.req.param('name');
+
+    const entry = registry.getById(id);
+    if (!entry) return c.json({ error: 'unknown demo' }, 404);
+    if (!events) return c.json({ error: 'events not enabled' }, 500);
+
+    const fullPath = resolveFilePath(entry.repoPath, entry.flowPath);
+    if (!existsSync(fullPath)) {
+      return c.json({ error: `Flow file not found: ${fullPath}` }, 404);
+    }
+    const merged = readMergedFlow(fullPath);
+    if (!merged.flow) {
+      return c.json({ error: merged.error ?? 'Flow read failed' }, 400);
+    }
+
+    const node = merged.flow.nodes.find((n) => n.id === nodeId);
+    if (!node) return c.json({ error: `Unknown nodeId: ${nodeId}` }, 404);
+    if (node.type !== 'component') {
+      return c.json({ error: `Node ${nodeId} is not a component node` }, 400);
+    }
+
+    const action = (node.data as { spec: { actions?: Record<string, ComponentAction> } }).spec
+      .actions?.[actionName];
+    if (!action) return c.json({ error: `Unknown action: ${actionName}` }, 404);
+
+    const payload = await c.req.json().catch(() => ({}));
+    const result = await runComponentAction({
+      events,
+      flowId: id,
+      nodeId,
+      cwd: entry.repoPath,
+      actionName,
+      action,
+      payload,
+      spawner: processSpawner,
+    });
+    if (!result.ok) {
+      return c.json({ error: result.error }, result.statusHint as 400 | 404 | 500 | 504);
+    }
+    return c.json(result.body);
+  });
+
   // POST /api/flows/:id/reset — the "Restart demo" workflow (US-008). Order:
   //   1. Stop every live play-script + every long-running status-script for
   //      this demo in parallel — both must complete before any reset script
@@ -1007,7 +1057,7 @@ export function createApi(options: ApiOptions): Hono {
   });
 
   // PATCH a single node — partial update of position, label, detail, visual
-  // fields, or shapeNode-only fields. Every UI-driven node edit (other than
+  // fields, or geometric-only fields. Every UI-driven node edit (other than
   // the high-frequency drag fast-path above) flows through here. The mutation
   // is performed against the raw parsed JSON (so unknown v2 fields the schema
   // doesn't yet recognize survive round-trips) and the WHOLE resulting demo

package/src/cli-e2e.ts

@@ -1,5 +1,5 @@
 // End-to-end validator used by `seeflow e2e <flowId>`. Opens an SSE channel to
-// the studio, triggers every playNode's playAction (sequentially), then drains
+// the studio, triggers every node carrying a playAction (sequentially), then drains
 // the channel for node:done/error + node:status reports. Mirrors the algorithm
 // in skills/seeflow/scripts/validate-end-to-end.ts — kept here so the CLI does
 // not depend on the skill folder.
@@ -167,15 +167,14 @@ function openSseChannel(body: ReadableStream<Uint8Array>): SseChannel {
 }
 
 function hasPlayAction(node: NodeShape): boolean {
-  return (
-    (node.type === 'playNode' || node.type === 'stateNode') && node.data?.playAction !== undefined
-  );
+  // Flat-types refactor: capabilities are top-level data fields on every
+  // type, not gated by the type tag. The e2e runner iterates every node
+  // carrying a playAction regardless of variant.
+  return node.data?.playAction !== undefined;
 }
 
 function hasStatusAction(node: NodeShape): boolean {
-  return (
-    (node.type === 'playNode' || node.type === 'stateNode') && node.data?.statusAction !== undefined
-  );
+  return node.data?.statusAction !== undefined;
 }
 
 export async function validateEndToEnd(options: ValidateOptions): Promise<ValidationReport> {

package/src/cli-manifest.ts

@@ -281,7 +281,7 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
     },
     requiresStudio: false,
     examples: [
-      'seeflow flow:add-bulk abc12345 --json \'{"nodes":[{"id":"a","type":"shapeNode","data":{"shape":"rectangle"}}],"connectors":[]}\'',
+      'seeflow flow:add-bulk abc12345 --json \'{"nodes":[{"id":"a","type":"rectangle","data":{}}],"connectors":[]}\'',
       'seeflow flow:add-bulk abc12345 --file batch.json',
     ],
   },
@@ -344,7 +344,7 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
     flags: BODY_FLAGS,
     body: {
       example: {
-        type: 'stateNode',
+        type: 'rectangle',
         data: { name: 'hello', stateSource: { kind: 'request' } },
       },
     },
@@ -360,9 +360,7 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
       ],
     },
     requiresStudio: false,
-    examples: [
-      'seeflow nodes:add abc12345 --json \'{"type":"shapeNode","data":{"shape":"rectangle"}}\'',
-    ],
+    examples: ['seeflow nodes:add abc12345 --json \'{"type":"rectangle","data":{}}\''],
   },
   {
     name: 'nodes:get',

package/src/cli.ts

@@ -20,6 +20,7 @@ import {
   clearPid,
   defaultPidPath,
   isPidAlive,
+  portInUse,
   readConfig,
   readPid,
   studioUrl,
@@ -266,6 +267,20 @@ async function runHelp() {
   console.log(renderCommandList());
 }
 
+// Pre-flight: refuse to start if the studio port already has a TCP listener.
+// We deliberately do NOT probe Vite's port (5173) here — `bun run dev` spawns
+// Vite alongside the studio, so Vite legitimately owns 5173 in dev mode and a
+// probe can't distinguish "our Vite" from a stranger. If Vite's port is taken
+// by something else, Vite itself surfaces the conflict.
+async function assertPortFree(studioPort: number, host: string): Promise<void> {
+  if (!(await portInUse(host, studioPort))) return;
+  console.error(
+    `Cannot start SeeFlow: port ${studioPort} already in use.\n` +
+      `Stop the running server on ${studioPort} first, then retry.`,
+  );
+  process.exit(1);
+}
+
 async function runStart() {
   mkdirSync(seeflowHome(), { recursive: true });
   const config = readConfig();
@@ -294,6 +309,12 @@ async function runStart() {
     return;
   }
 
+  // Defense-in-depth: parent already checked in spawnDaemon, but a race
+  // between parent-check and child-bind can still let another process grab
+  // the port. Re-check here so the child fails fast with a clear error
+  // instead of EADDRINUSE at bind time.
+  await assertPortFree(port, config.host);
+
   // persist the chosen address so other subcommands can find us
   writeConfig({ port, host: config.host });
 
@@ -329,6 +350,7 @@ async function runStart() {
 async function seedExamples(registry: Registry) {
   await seedExample(registry, 'order-pipeline');
   await seedExample(registry, 'ecommerce-platform');
+  await seedExample(registry, 'component-showcase');
 }
 
 async function seedExample(registry: Registry, exampleName: string) {
@@ -368,6 +390,11 @@ async function spawnDaemon(port: number, host: string) {
     return;
   }
 
+  // Studio port must be free before we fork a detached child — otherwise the
+  // user waits HEALTH_TIMEOUT_MS for a doomed health probe before seeing a
+  // generic timeout error.
+  await assertPortFree(port, host);
+
   const proc = spawnDetachedStudio(port);
   writePid(proc.pid);
   writeConfig({ port, host });