@tuongaz/seeflow 0.1.71 → 0.1.74

package/src/cli-manifest.ts

@@ -287,16 +287,21 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
   },
   {
     name: 'flows:play',
-    synopsis: 'seeflow flows:play <flowId> <nodeId>',
-    description: 'Trigger a play action on one node. Requires a running studio.',
+    synopsis: 'seeflow flows:play <flowId> <nodeId> [--no-start]',
+    description:
+      "Trigger the node's playAction on the studio and wait for the spawn-level " +
+      'result. The studio also broadcasts node:running/done/error events on the ' +
+      "flow's SSE stream — subscribe separately if you want live progress. " +
+      'Requires a running studio.',
     category: 'live',
     args: [
       { name: 'flowId', required: true, description: 'Flow id or slug' },
       { name: 'nodeId', required: true, description: 'Node id in the flow' },
     ],
     flags: [{ name: 'no-start', description: 'Fail if the studio is not already running' }],
-    outputKind: 'stream',
-    outputs: {},
+    outputs: {
+      okExample: { runId: 'run-9b3', status: 200, body: { ok: true } },
+    },
     requiresStudio: true,
     examples: ['seeflow flows:play abc12345 api-checkout'],
   },
@@ -350,14 +355,7 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
     },
     outputs: {
       okExample: { id: 'node-abc' },
-      errorKinds: [
-        'flowNotFound',
-        'fileNotFound',
-        'badJson',
-        'badSchema',
-        'idAlreadyExists',
-        'writeFailed',
-      ],
+      errorKinds: ['flowNotFound', 'fileNotFound', 'badJson', 'badSchema', 'writeFailed'],
     },
     requiresStudio: false,
     examples: ['seeflow nodes:add abc12345 --json \'{"type":"rectangle","data":{}}\''],
@@ -390,7 +388,14 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
     flags: BODY_FLAGS,
     body: { schemaRef: 'NodePatchBody' },
     outputs: {
-      errorKinds: ['flowNotFound', 'fileNotFound', 'unknownNode', 'badSchema', 'writeFailed'],
+      errorKinds: [
+        'flowNotFound',
+        'fileNotFound',
+        'unknownNode',
+        'badJson',
+        'badSchema',
+        'writeFailed',
+      ],
     },
     requiresStudio: false,
     examples: ['seeflow nodes:patch abc12345 api-checkout --json \'{"data":{"name":"renamed"}}\''],
@@ -409,7 +414,16 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
       { name: 'y', valuePlaceholder: '<n>', description: 'Y coordinate', required: true },
     ],
     body: { schemaRef: 'PositionBody' },
-    outputs: { errorKinds: ['flowNotFound', 'fileNotFound', 'unknownNode', 'writeFailed'] },
+    outputs: {
+      errorKinds: [
+        'flowNotFound',
+        'fileNotFound',
+        'unknownNode',
+        'badJson',
+        'badSchema',
+        'writeFailed',
+      ],
+    },
     requiresStudio: false,
     examples: ['seeflow nodes:move abc12345 api-checkout --x 250 --y 320'],
   },
@@ -433,7 +447,16 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
       { name: 'index', valuePlaceholder: '<n>', description: 'Required when --op toIndex' },
     ],
     body: { schemaRef: 'ReorderBody' },
-    outputs: { errorKinds: ['flowNotFound', 'fileNotFound', 'unknownNode', 'writeFailed'] },
+    outputs: {
+      errorKinds: [
+        'flowNotFound',
+        'fileNotFound',
+        'unknownNode',
+        'badJson',
+        'badSchema',
+        'writeFailed',
+      ],
+    },
     requiresStudio: false,
     examples: [
       'seeflow nodes:reorder abc12345 api-checkout --op forward',
@@ -452,7 +475,14 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
     flags: [],
     outputs: {
       okExample: { ok: true, removedConnectors: 0 },
-      errorKinds: ['flowNotFound', 'unknownNode'],
+      errorKinds: [
+        'flowNotFound',
+        'fileNotFound',
+        'unknownNode',
+        'badJson',
+        'badSchema',
+        'writeFailed',
+      ],
     },
     requiresStudio: false,
     examples: ['seeflow nodes:delete abc12345 api-checkout'],
@@ -461,21 +491,21 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
   {
     name: 'connectors:add',
     synopsis: 'seeflow connectors:add <flowId> [--json | --file | --stdin]',
-    description: 'Add a connector. Body is the connector object (source/target required).',
+    description:
+      'Add a connector. Body is the connector object — `source` and `target` are ' +
+      'the connected node ids (strings). Auto-generates an id when absent.',
     category: 'connectors',
     args: [{ name: 'flowId', required: true, description: 'Flow id or slug' }],
     flags: BODY_FLAGS,
     body: {
-      example: { source: { nodeId: 'a' }, target: { nodeId: 'b' } },
+      example: { source: 'a', target: 'b' },
     },
     outputs: {
       okExample: { id: 'conn-abc' },
-      errorKinds: ['flowNotFound', 'badSchema', 'idAlreadyExists', 'writeFailed'],
+      errorKinds: ['flowNotFound', 'fileNotFound', 'badJson', 'badSchema', 'writeFailed'],
     },
     requiresStudio: false,
-    examples: [
-      'seeflow connectors:add abc12345 --json \'{"source":{"nodeId":"a"},"target":{"nodeId":"b"}}\'',
-    ],
+    examples: ['seeflow connectors:add abc12345 --json \'{"source":"a","target":"b"}\''],
   },
   {
     name: 'connectors:patch',
@@ -488,7 +518,16 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
     ],
     flags: BODY_FLAGS,
     body: { schemaRef: 'ConnectorPatchBody' },
-    outputs: { errorKinds: ['flowNotFound', 'unknownConnector', 'badSchema', 'writeFailed'] },
+    outputs: {
+      errorKinds: [
+        'flowNotFound',
+        'fileNotFound',
+        'unknownConnector',
+        'badJson',
+        'badSchema',
+        'writeFailed',
+      ],
+    },
     requiresStudio: false,
     examples: ['seeflow connectors:patch abc12345 conn-1 --json \'{"label":"new"}\''],
   },
@@ -502,7 +541,17 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
       { name: 'connectorId', required: true, description: 'Connector id in the flow' },
     ],
     flags: [],
-    outputs: { okExample: { ok: true }, errorKinds: ['flowNotFound', 'unknownConnector'] },
+    outputs: {
+      okExample: { ok: true },
+      errorKinds: [
+        'flowNotFound',
+        'fileNotFound',
+        'unknownConnector',
+        'badJson',
+        'badSchema',
+        'writeFailed',
+      ],
+    },
     requiresStudio: false,
     examples: ['seeflow connectors:delete abc12345 conn-1'],
   },
@@ -563,18 +612,21 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
     name: 'schema',
     synopsis: 'seeflow schema [<category>]',
     description:
-      'Introspect the SeeFlow flow.json / style.json schemas at runtime. Call ' +
-      'without arguments to list the five categories (flow, node, connector, ' +
-      'action, style); call with a category name to get its full JSON Schema(s) ' +
-      '(Draft-07) plus a `notes` array of cross-field invariants the schema ' +
-      "can't express. Use this before authoring any flow.json write — never " +
-      'memorise field shapes.',
+      'Introspect the SeeFlow flow.json / style.json / spec.json schemas at ' +
+      'runtime. Call without arguments to list the six categories (flow, node, ' +
+      'connector, action, componentSpec, style); call with a category name to ' +
+      'get its full JSON Schema(s) (Draft-07) plus a `notes` array of cross-' +
+      "field invariants the schema can't express. The `node` payload includes " +
+      "all 13 flat variants (including type:'component', whose `spec` field " +
+      'lives in a sidecar — drill into `componentSpec` for that shape). Use ' +
+      'this before authoring any flow.json / spec.json write — never memorise ' +
+      'field shapes.',
     category: 'meta',
     args: [
       {
         name: 'category',
         required: false,
-        description: 'One of: flow, node, connector, action, style',
+        description: 'One of: flow, node, connector, action, componentSpec, style',
       },
     ],
     flags: [],
@@ -583,13 +635,23 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
       errorKinds: ['notFound'],
     },
     requiresStudio: false,
-    examples: ['seeflow schema', 'seeflow schema node', 'seeflow schema connector'],
+    examples: [
+      'seeflow schema',
+      'seeflow schema node',
+      'seeflow schema connector',
+      'seeflow schema componentSpec',
+    ],
   },
   // ---- live --------------------------------------------------------------
   {
     name: 'e2e',
-    synopsis: 'seeflow e2e <flowId> [--skip-nodes a,b]',
-    description: 'End-to-end validate a registered flow. Requires a running studio.',
+    synopsis: 'seeflow e2e <flowId> [--skip-nodes a,b] [--no-start]',
+    description:
+      'End-to-end validate a registered flow. Walks every node with a playAction ' +
+      "in flow.json order, POSTs each play, then drains the flow's SSE stream " +
+      'for node:done/error + node:status reports. Returns a single JSON report ' +
+      'when finished; exits non-zero if any play failed, any statusAction failed ' +
+      'to report, or the 120s ceiling was exceeded. Requires a running studio.',
     category: 'live',
     args: [{ name: 'flowId', required: true, description: 'Flow id or slug' }],
     flags: [
@@ -600,10 +662,16 @@ export const COMMAND_MANIFEST: CommandManifestEntry[] = [
       },
       { name: 'no-start', description: 'Fail if the studio is not already running' },
     ],
-    outputKind: 'stream',
-    outputs: {},
+    outputs: {
+      okExample: {
+        ok: true,
+        plays: [{ nodeId: 'api-checkout', outcome: 'ok', runId: 'run-9b3' }],
+        statuses: [],
+        skipped: [],
+      },
+    },
     requiresStudio: true,
-    examples: ['seeflow e2e abc12345'],
+    examples: ['seeflow e2e abc12345', 'seeflow e2e abc12345 --skip-nodes flaky-1,flaky-2'],
   },
   {
     name: 'emit',

package/src/mcp.ts

@@ -196,10 +196,14 @@ const buildTools = (ops: Operations): McpTool[] => [
   {
     name: 'seeflow_schema',
     description:
-      'Get the SeeFlow flow.json schema. Call with no args for a category index; ' +
-      "call with `name` for one category's full JSON Schemas. Use this to learn " +
-      'what a node, connector, action, or flow envelope looks like before authoring ' +
-      'writes. Categories: `flow`, `node`, `connector`, `action`, `style`.',
+      'Get the SeeFlow flow.json / spec.json schemas. Call with no args for a ' +
+      "category index; call with `name` for one category's full JSON Schemas. " +
+      'Use this to learn what a node, connector, action, component spec, or ' +
+      'flow envelope looks like before authoring writes. Categories: `flow`, ' +
+      '`node` (13 flat variants — rectangle/ellipse/sticky/text/database/server/' +
+      'user/queue/cloud/image/html/icon/component), `connector`, `action` ' +
+      '(playAction/statusAction/resetAction/statusReport/componentAction), ' +
+      "`componentSpec` (sidecar shape for type:'component' nodes), `style`.",
     inputSchema: {
       type: 'object',
       properties: {

package/src/schema-catalog.ts

@@ -8,7 +8,11 @@
 import type { ZodTypeAny } from 'zod';
 import { zodToJsonSchema } from 'zod-to-json-schema';
 import {
+  ComponentActionSchema,
+  ComponentSpecElementSchema,
+  ComponentSpecSchema,
   FlowCloudNodeSchema,
+  FlowComponentNodeSchema,
   FlowConnectorSchema,
   FlowDatabaseNodeSchema,
   FlowEllipseNodeSchema,
@@ -50,7 +54,7 @@ const CATEGORIES: SchemaCategory[] = [
   {
     name: 'node',
     description:
-      'All 12 flat node variants (rectangle, ellipse, sticky, text, database, server, user, queue, cloud, image, html, icon). Visual kind is the type; capabilities (playAction / statusAction / stateSource) are independent optional fields on every variant.',
+      'All 13 flat node variants (rectangle, ellipse, sticky, text, database, server, user, queue, cloud, image, html, icon, component). Visual kind is the type; capabilities (playAction / statusAction / stateSource) are independent optional fields on every variant.',
   },
   {
     name: 'connector',
@@ -58,7 +62,13 @@ const CATEGORIES: SchemaCategory[] = [
   },
   {
     name: 'action',
-    description: 'playAction, statusAction, resetAction, statusReport.',
+    description:
+      'playAction, statusAction, resetAction, statusReport, plus componentAction (the set | script discriminated union dispatched on component-node action handles).',
+  },
+  {
+    name: 'componentSpec',
+    description:
+      "Sidecar shape written to <project>/nodes/<id>/spec.json for type:'component' nodes. Carries the json-render element tree, initial state, and named actions the renderer dispatches on user input.",
   },
   { name: 'style', description: 'style.json (studio-owned).' },
 ];
@@ -82,10 +92,12 @@ const PAYLOADS: Record<string, SchemaPayload> = {
       image: toJsonSchema(FlowImageNodeSchema),
       html: toJsonSchema(FlowHtmlNodeSchema),
       icon: toJsonSchema(FlowIconNodeSchema),
+      component: toJsonSchema(FlowComponentNodeSchema),
     },
     notes: [
       "type:'image' data.path must start with 'nodes/<id>/'.",
       "scriptPath in playAction/statusAction is relative to nodes/<nodeId>/ and may not contain '..' or absolute paths.",
+      "type:'component' nodes have no `spec` field on disk — the spec lives in <project>/nodes/<id>/spec.json (see `seeflow schema componentSpec`). The resolver inlines it into data.spec for runtime / SSE broadcasts.",
     ],
   },
   connector: {
@@ -100,9 +112,22 @@ const PAYLOADS: Record<string, SchemaPayload> = {
       statusAction: toJsonSchema(StatusActionSchema),
       resetAction: toJsonSchema(ResetActionSchema),
       statusReport: toJsonSchema(StatusReportSchema),
+      componentAction: toJsonSchema(ComponentActionSchema),
     },
     notes: [
       "scriptPath in playAction/statusAction is relative to nodes/<nodeId>/ and may not contain '..' or absolute paths.",
+      "componentAction is a `set | script` discriminated union: `set` mutates canvas state locally (path is a JSON Pointer starting with '/'), `script` shells out via POST /api/flows/:id/nodes/:nodeId/actions/:name with the same scriptPath rooting rules as playAction.",
+    ],
+  },
+  componentSpec: {
+    schemas: {
+      componentSpec: toJsonSchema(ComponentSpecSchema),
+      componentSpecElement: toJsonSchema(ComponentSpecElementSchema),
+    },
+    notes: [
+      "spec.json is the on-disk source of truth for type:'component' nodes; the resolver inlines it into data.spec at read time and splitFlow strips it back out before writing flow.json so the sidecar is never double-stored.",
+      'elements is keyed by element id; `root` names the entry element. Element ids referenced from children / actions must exist in elements.',
+      'state and actions are both keyed by user-chosen names. Action handles in the rendered UI reference these names; see `seeflow schema action` for the per-action shape.',
     ],
   },
   style: {

package/src/schema.ts

@@ -141,10 +141,10 @@ const NodeCapabilitiesShape = {
   handlerModule: z.string().optional(),
 };
 
-// 12 flat node types. The first 9 are geometric/illustrative and share
-// GeometricNodeData. `image`, `html`, `icon` carry per-type fields.
-// The renderer picks the SVG / chrome by `type`; the schema treats them
-// (apart from the per-type fields below) as identical.
+// 13 flat node types. The first 9 are geometric/illustrative and share
+// GeometricNodeData. `image`, `html`, `icon`, `component` carry per-type
+// fields. The renderer picks the SVG / chrome by `type`; the schema treats
+// them (apart from the per-type fields below) as identical.
 export const GEOMETRIC_NODE_TYPES = [
   'rectangle',
   'ellipse',

package/src/watcher.ts

@@ -20,6 +20,15 @@ import {
 
 const DEFAULT_DEBOUNCE_MS = 100;
 
+/**
+ * Polling backup interval. fs.watch on macOS occasionally drops events
+ * (notably right after a fresh watcher is registered), so a low-frequency
+ * stat poll over every watched handle guarantees external writes still
+ * trigger reparse+broadcast. Own-write echoes are still suppressed by
+ * the writtenHashes ring, so this doesn't double-fire on server writes.
+ */
+const DEFAULT_POLL_INTERVAL_MS = 500;
+
 /** Max recent self-write hashes retained per flow for own-echo suppression. */
 const WRITTEN_HASH_RING_SIZE = 4;
 
@@ -52,6 +61,12 @@ export interface WatcherDeps {
   events: EventBus;
   /** Override for tests. */
   debounceMs?: number;
+  /**
+   * Polling backup interval for missed fs.watch events. Defaults to 500ms.
+   * Pass `0` to disable (tests that rely on deterministic fs.watch-only
+   * behaviour).
+   */
+  pollIntervalMs?: number;
 }
 
 export interface FlowWatcher {
@@ -276,6 +291,7 @@ const closeFileWatchers = (handle: WatchHandle): void => {
 export function createWatcher(deps: WatcherDeps): FlowWatcher {
   const { registry, events } = deps;
   const debounceMs = deps.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+  const pollIntervalMs = deps.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
 
   const handles = new Map<string, WatchHandle>();
   const snapshots = new Map<string, FlowSnapshot>();
@@ -455,6 +471,49 @@ export function createWatcher(deps: WatcherDeps): FlowWatcher {
     });
   };
 
+  /**
+   * Common path for "something on disk may have changed" — used by both
+   * fs.watch callbacks and the polling backup. Debounces, drops own-write
+   * echoes, then reparses + broadcasts. Idempotent under repeated calls
+   * within the debounce window.
+   */
+  const scheduleChange = (flowId: string): void => {
+    const handle = handles.get(flowId);
+    if (!handle) return;
+    if (handle.debounceTimer) clearTimeout(handle.debounceTimer);
+    handle.debounceTimer = setTimeout(() => {
+      handle.debounceTimer = null;
+      // Own-write dedupe: if the on-disk bytes match what the server just
+      // wrote (recent hash in the ring), this is our own echo — drop it.
+      // notifyWritten already broadcast and seeded the snapshot.
+      const combined = readCombinedFromDisk(handle.filePath);
+      if (combined !== null && isOwnWriteEcho(flowId, sha256Hex(combined))) return;
+      const snap = reparse(flowId);
+      if (snap) broadcastReload(flowId, snap);
+    }, debounceMs);
+  };
+
+  // Single shared interval that stat-polls every watched handle. Cheap (one
+  // statSync per watched flow per tick) and bounded — flows that registry
+  // doesn't know about aren't watched, so the loop scales with active
+  // projects, not historic ones. Backs up macOS fs.watch's occasional
+  // dropped events; the debounce + own-write dedupe in scheduleChange
+  // keeps it from double-firing alongside a fs.watch hit.
+  const pollTimer: ReturnType<typeof setInterval> | null =
+    pollIntervalMs > 0
+      ? setInterval(() => {
+          for (const [flowId, handle] of handles) {
+            const seen = lastSeenMtimes.get(flowId);
+            if (seen === undefined) continue;
+            const now = combinedMtimeMs(handle.filePath);
+            if (now > seen) scheduleChange(flowId);
+          }
+        }, pollIntervalMs)
+      : null;
+  // Don't keep the event loop alive on this timer alone — the studio process
+  // should exit cleanly when nothing else is pending.
+  pollTimer?.unref?.();
+
   const startWatch = (flowId: string) => {
     const existing = handles.get(flowId);
     if (existing) {
@@ -484,19 +543,7 @@ export function createWatcher(deps: WatcherDeps): FlowWatcher {
         // React to flow.json, style.json, or rename-on-save events
         // (some platforms emit those with no filename).
         if (changed && changed !== base && changed !== 'style.json') return;
-        const handle = handles.get(flowId);
-        if (!handle) return;
-        if (handle.debounceTimer) clearTimeout(handle.debounceTimer);
-        handle.debounceTimer = setTimeout(() => {
-          handle.debounceTimer = null;
-          // Own-write dedupe: if the on-disk bytes match what the server just
-          // wrote (recent hash in the ring), this is our own echo — drop it.
-          // notifyWritten already broadcast and seeded the snapshot.
-          const combined = readCombinedFromDisk(filePath);
-          if (combined !== null && isOwnWriteEcho(flowId, sha256Hex(combined))) return;
-          const snap = reparse(flowId);
-          if (snap) broadcastReload(flowId, snap);
-        }, debounceMs);
+        scheduleChange(flowId);
       });
     } catch (err) {
       console.error(`[watcher] failed to watch ${dir} for flow ${flowId}:`, err);
@@ -551,6 +598,7 @@ export function createWatcher(deps: WatcherDeps): FlowWatcher {
       for (const entry of registry.list()) startWatch(entry.id);
     },
     closeAll() {
+      if (pollTimer) clearInterval(pollTimer);
       for (const [, h] of handles) {
         h.fsWatcher.close();
         if (h.debounceTimer) clearTimeout(h.debounceTimer);