@tuongaz/seeflow 0.1.65 → 0.1.69

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';
@@ -850,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

package/src/cli.ts

@@ -350,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) {

package/src/component-action-runner.ts

@@ -0,0 +1,188 @@
+/**
+ * Dispatches a component node's `script`-kind ComponentAction over HTTP:
+ * resolves `scriptPath` under `<cwd>/nodes/<nodeId>/` with the same realpath
+ * escape check used by `runPlay` (see proxy.ts), spawns the interpreter via the
+ * injectable `ProcessSpawner` seam, pipes the request payload to stdin as JSON,
+ * and parses stdout back as JSON (falling back to the raw string).
+ *
+ * `set`-kind actions are intentionally rejected with statusHint 400: those
+ * mutate canvas state locally and never round-trip through the API. The runner
+ * is the single seam the API route calls; HTTP status mapping lives in the
+ * route handler via `statusHint`.
+ */
+
+import { realpathSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+import type { EventBus } from './events.ts';
+import { type ProcessSpawner, type SpawnHandle, defaultProcessSpawner } from './process-spawner.ts';
+import type { ComponentAction } from './schema.ts';
+import { shortId } from './short-id.ts';
+
+const DEFAULT_TIMEOUT_MS = 5_000;
+const SIGKILL_GRACE_MS = 2_000;
+const SCRIPT_PATH_ESCAPE = 'scriptPath escapes node root';
+const SET_KIND_REJECTION = 'Only script actions are dispatched over HTTP';
+
+export interface RunComponentActionOptions {
+  events: EventBus;
+  flowId: string;
+  nodeId: string;
+  /** Project root (`<repoPath>`). Script resolves under `<cwd>/nodes/<nodeId>/`. */
+  cwd: string;
+  actionName: string;
+  action: ComponentAction;
+  payload: unknown;
+  /** Injectable for tests; defaults to `defaultProcessSpawner`. */
+  spawner?: ProcessSpawner;
+}
+
+export interface ComponentActionResult {
+  ok: boolean;
+  body?: unknown;
+  error?: string;
+  /** Suggested HTTP status for the API handler. */
+  statusHint: number;
+}
+
+type Resolved = { ok: true; absPath: string } | { ok: false };
+
+// Resolve `<cwd>/nodes/<nodeId>/<scriptPath>` and verify via realpath it stays
+// inside the node folder. Mirrors proxy.ts:resolveScript — symlink-escape
+// defense in line with `resolveProjectFile` in api.ts.
+function resolveScript(cwd: string, nodeId: string, scriptPath: string): Resolved {
+  const nodeRoot = join(cwd, 'nodes', nodeId);
+  let realRoot: string;
+  try {
+    realRoot = realpathSync(nodeRoot);
+  } catch {
+    return { ok: false };
+  }
+  const target = resolve(nodeRoot, scriptPath);
+  let realTarget: string;
+  try {
+    realTarget = realpathSync(target);
+  } catch {
+    return { ok: false };
+  }
+  const rootWithSep = realRoot.endsWith(sep) ? realRoot : realRoot + sep;
+  if (realTarget !== realRoot && !realTarget.startsWith(rootWithSep)) {
+    return { ok: false };
+  }
+  return { ok: true, absPath: realTarget };
+}
+
+// Copy `process.env` into a string-only record, then layer the per-run extras.
+// Bun.spawn's env contract is `Record<string, string>` so the undefineds that
+// `process.env` advertises in its type must be filtered out first.
+function buildChildEnv(extra: Record<string, string>): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const [k, v] of Object.entries(process.env)) {
+    if (typeof v === 'string') env[k] = v;
+  }
+  return { ...env, ...extra };
+}
+
+async function writeStdinPayload(handle: SpawnHandle, payload: unknown): Promise<void> {
+  if (!handle.stdin) return;
+  const writer = handle.stdin.getWriter();
+  try {
+    await writer.write(new TextEncoder().encode(JSON.stringify(payload)));
+  } finally {
+    await writer.close().catch(() => {
+      /* stdin already closed by child — not fatal */
+    });
+  }
+}
+
+async function killWithGrace(handle: SpawnHandle): Promise<void> {
+  handle.kill('SIGTERM');
+  let graceTimer: ReturnType<typeof setTimeout> | undefined;
+  const gracePromise = new Promise<'grace'>((res) => {
+    graceTimer = setTimeout(() => res('grace'), SIGKILL_GRACE_MS);
+  });
+  const winner = await Promise.race([handle.exited.then(() => 'exited' as const), gracePromise]);
+  if (graceTimer) clearTimeout(graceTimer);
+  if (winner === 'grace') {
+    handle.kill('SIGKILL');
+    await handle.exited;
+  }
+}
+
+export async function runComponentAction(
+  opts: RunComponentActionOptions,
+): Promise<ComponentActionResult> {
+  if (opts.action.kind !== 'script') {
+    return { ok: false, error: SET_KIND_REJECTION, statusHint: 400 };
+  }
+  const spawner = opts.spawner ?? defaultProcessSpawner;
+  const resolved = resolveScript(opts.cwd, opts.nodeId, opts.action.scriptPath);
+  if (!resolved.ok) {
+    return { ok: false, error: SCRIPT_PATH_ESCAPE, statusHint: 400 };
+  }
+
+  const env = buildChildEnv({
+    SEEFLOW_DEMO_ID: opts.flowId,
+    SEEFLOW_NODE_ID: opts.nodeId,
+    SEEFLOW_ACTION_NAME: opts.actionName,
+    SEEFLOW_RUN_ID: shortId(),
+  });
+
+  let handle: SpawnHandle;
+  try {
+    handle = spawner.spawn({
+      cmd: [opts.action.interpreter, ...(opts.action.args ?? []), resolved.absPath],
+      cwd: opts.cwd,
+      env,
+      stdin: 'pipe',
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { ok: false, error: message, statusHint: 500 };
+  }
+
+  // Drain stdout AND stderr CONCURRENTLY with the process running so OS pipe
+  // buffers (~64 KB) don't fill up and deadlock the child.
+  const stdoutPromise = new Response(handle.stdout).text();
+  const stderrPromise = new Response(handle.stderr).text();
+
+  // Write stdin and close BEFORE awaiting exit (otherwise a child blocked on
+  // `read(stdin)` and a parent blocked on `exited` deadlock each other).
+  await writeStdinPayload(handle, opts.payload);
+
+  const timeoutMs = opts.action.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeoutPromise = new Promise<'timeout'>((res) => {
+    timer = setTimeout(() => res('timeout'), timeoutMs);
+  });
+  const exitPromise = handle.exited.then((code) => ({ code }) as const);
+
+  const race = await Promise.race([exitPromise, timeoutPromise]);
+  if (timer) clearTimeout(timer);
+
+  if (race === 'timeout') {
+    await killWithGrace(handle);
+    await Promise.allSettled([stdoutPromise, stderrPromise]);
+    return {
+      ok: false,
+      error: `action timed out after ${timeoutMs}ms`,
+      statusHint: 504,
+    };
+  }
+
+  const [stdout, stderr] = await Promise.all([stdoutPromise, stderrPromise]);
+  if (race.code !== 0) {
+    return {
+      ok: false,
+      error: stderr.trim() || `exit ${race.code}`,
+      statusHint: 500,
+    };
+  }
+
+  let body: unknown;
+  try {
+    body = JSON.parse(stdout);
+  } catch {
+    body = stdout;
+  }
+  return { ok: true, body, statusHint: 200 };
+}

package/src/component-spec-resolver.ts

@@ -0,0 +1,60 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { ResolvedFlow } from './schema.ts';
+
+export interface SpecInlineError {
+  /** Logical path into the merged flow shape, like 'nodes/<id>/data/spec'. */
+  path: string;
+  message: string;
+}
+
+export interface InlineComponentSpecsResult {
+  flow: ResolvedFlow;
+  errors: SpecInlineError[];
+  /** Project-root-relative paths the watcher should track for live reload. */
+  refs: string[];
+}
+
+/**
+ * For every `'component'` node in `flow`, read `nodes/<id>/spec.json`,
+ * JSON.parse, and attach the result as `data.spec`. Missing files surface
+ * as a SpecInlineError; malformed JSON surfaces likewise. Non-component
+ * nodes pass through untouched.
+ *
+ * Returns a NEW flow object (no mutation of the input) so the watcher's
+ * snapshot caching stays safe.
+ */
+export function inlineComponentSpecs(
+  flow: ResolvedFlow,
+  projectRoot: string,
+): InlineComponentSpecsResult {
+  const errors: SpecInlineError[] = [];
+  const refs: string[] = [];
+
+  const nodes = flow.nodes.map((node) => {
+    if (node.type !== 'component') return node;
+    const relPath = `nodes/${node.id}/spec.json`;
+    const absPath = join(projectRoot, relPath);
+    if (!existsSync(absPath)) {
+      errors.push({
+        path: `nodes/${node.id}/data/spec`,
+        message: `Missing spec file: ${relPath}`,
+      });
+      return node;
+    }
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(readFileSync(absPath, 'utf8'));
+    } catch (err) {
+      errors.push({
+        path: `nodes/${node.id}/data/spec`,
+        message: `Invalid JSON in ${relPath}: ${err instanceof Error ? err.message : String(err)}`,
+      });
+      return node;
+    }
+    refs.push(relPath);
+    return { ...node, data: { ...node.data, spec: parsed } } as typeof node;
+  });
+
+  return { flow: { ...flow, nodes } as ResolvedFlow, errors, refs };
+}

package/src/layout.ts

@@ -76,6 +76,7 @@ const DEFAULT_DIMENSIONS: Record<FlowNode['type'], { width: number; height: numb
   image: { width: 200, height: 150 },
   html: { width: 320, height: 200 },
   icon: { width: 80, height: 80 },
+  component: { width: 320, height: 240 },
 };
 
 // Sticky / text variants are floating annotations. They never participate in

package/src/merge.ts

@@ -67,6 +67,7 @@ const NODE_STYLE_KEYS = new Set([
   'fontSize',
   'textColor',
   'cornerRadius',
+  'shadow',
   'borderWidth',
   'color',
   'strokeWidth',
@@ -133,6 +134,10 @@ export function splitFlow(resolved: {
     const flowData: Record<string, unknown> = {};
     for (const [k, v] of Object.entries(data)) {
       if (v === undefined) continue;
+      // Component nodes externalize `spec` to <project>/nodes/<id>/spec.json
+      // (the sidecar). Drop it from flow.json so the strict on-disk schema
+      // doesn't reject it and the spec stays single-sourced on disk.
+      if (node.type === 'component' && k === 'spec') continue;
       if (NODE_DATA_FLOW_KEYS.has(k)) {
         flowData[k] = v;
       } else if (NODE_STYLE_KEYS.has(k)) {

package/src/operations.ts

@@ -11,6 +11,7 @@ import { existsSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSyn
 import { dirname, isAbsolute, join } from 'node:path';
 import { type ZodIssue, z } from 'zod';
 import { writeFileAtomic } from './atomic-write.ts';
+import { inlineComponentSpecs } from './component-spec-resolver.ts';
 import { type LayoutOptions, computeLayout } from './layout.ts';
 import { mergeFlowAndStyle, splitFlow } from './merge.ts';
 import {
@@ -24,6 +25,7 @@ import {
 import type { Registry } from './registry.ts';
 import {
   ColorTokenSchema,
+  ComponentSpecSchema,
   EdgePinSchema,
   type Flow,
   FlowSchema,
@@ -103,6 +105,7 @@ export const NodePatchBodySchema = z
     fontSize: z.number().positive().optional(),
     textColor: ColorTokenSchema.optional(),
     cornerRadius: z.number().min(0).optional(),
+    shadow: z.number().int().min(0).max(5).optional(),
     width: z.number().positive().optional(),
     height: z.number().positive().optional(),
     // type:'html'-only: when true, the renderer measures content and React Flow
@@ -141,6 +144,12 @@ export const NodePatchBodySchema = z
     playAction: PlayActionSchema.optional(),
     statusAction: StatusActionSchema.optional(),
     stateSource: StateSourceSchema.optional(),
+    // type:'component'-only: json-render spec describing the reactive UI.
+    // Externalized to `<project>/nodes/<id>/spec.json` by patchNodeImpl; the
+    // in-memory ResolvedFlow keeps `data.spec` populated for the post-merge
+    // reparse + SSE broadcast, but splitFlow strips it from flow.json so the
+    // sidecar is the source of truth on disk.
+    spec: ComponentSpecSchema.optional(),
   })
   .strict();
 export type NodePatchBody = z.infer<typeof NodePatchBodySchema>;
@@ -159,6 +168,7 @@ const NODE_DATA_PATCH_KEYS = [
   'fontSize',
   'textColor',
   'cornerRadius',
+  'shadow',
   'width',
   'height',
   'autoSize',
@@ -172,6 +182,7 @@ const NODE_DATA_PATCH_KEYS = [
   'playAction',
   'statusAction',
   'stateSource',
+  'spec',
 ] as const satisfies ReadonlyArray<keyof NodePatchBody>;
 
 const EXTERNALIZED_FIELD_NAMES = new Set<string>(EXTERNALIZED_NODE_FIELDS.map((e) => e.field));
@@ -238,6 +249,10 @@ const SEMANTIC_KEYS_BY_TYPE: Record<z.infer<typeof NodeTypeSchema>, ReadonlySet<
     'statusAction',
     'alt',
   ]),
+  // Component nodes externalize `spec` to <project>/nodes/<id>/spec.json; the
+  // semantic-key set covers only the universal capability fields so retype
+  // never drags `spec` through `data`. (US-007 wires the sidecar writer.)
+  component: GEOMETRIC_SEMANTIC_KEYS,
 };
 
 // Visual data keys — routed to style.json on write by splitFlow. Kept here
@@ -253,6 +268,7 @@ const NODE_VISUAL_KEYS = new Set([
   'fontSize',
   'textColor',
   'cornerRadius',
+  'shadow',
   'borderWidth',
   'color',
   'strokeWidth',
@@ -321,12 +337,13 @@ export const mergeNodeUpdates = (node: Record<string, unknown>, updates: NodePat
     }
   }
 
-  // type:'html'-only invariant enforcement:
+  // type:'html' + type:'component' invariant enforcement:
   //   autoSize === true ⊻ (width and height set).
   // autoSize: true is the dominant signal — it strips width/height even if
   // the same patch tried to write them. Writing width/height implicitly
-  // flips autoSize to false.
-  if (node.type === 'html') {
+  // flips autoSize to false. Both node types default to autoSize:true in the
+  // renderer and share the same shrink-wrap-to-content mechanism.
+  if (node.type === 'html' || node.type === 'component') {
     // The autoSize invariant requires `width`/`height` to be ABSENT from the
     // serialized JSON when autoSize is true — not present with value
     // `undefined` (which would serialize as a stray `"width": null` or get
@@ -757,7 +774,16 @@ export async function mutateMergedFlow<E extends { kind: string }>(
   const styleParse = StyleSchema.safeParse(read.rawStyle);
   if (!styleParse.success) return { kind: 'badSchema', issues: styleParse.error.issues };
 
-  const merged = mergeFlowAndStyle(flowParse.data, styleParse.data) as unknown as {
+  // Inline component spec sidecars (<project>/nodes/<id>/spec.json) before the
+  // mutator runs so the post-mutation ResolvedFlowSchema parse sees `data.spec`
+  // on every existing component node. splitFlow strips `spec` back out before
+  // we write flow.json, keeping the sidecar as the on-disk source of truth.
+  const projectRoot = dirname(flowPath);
+  const { flow: inlinedFlow } = inlineComponentSpecs(
+    mergeFlowAndStyle(flowParse.data, styleParse.data),
+    projectRoot,
+  );
+  const merged = inlinedFlow as unknown as {
     version: number;
     name: string;
     resetAction?: unknown;
@@ -1532,6 +1558,22 @@ export async function patchNodeImpl(
       }
       node.data = data;
     }
+    // Component spec sidecar — write the pretty-printed JSON to
+    // `<project>/nodes/<id>/spec.json` so the on-disk source of truth stays
+    // in sync. mergeNodeUpdates already put data.spec on the merged tree for
+    // the post-mutation ResolvedFlowSchema parse; splitFlow strips it from
+    // flow.json so we don't double-store the spec.
+    if (node.type === 'component' && updates.spec !== undefined) {
+      const specAbs = nodeFileAbsPath(entry.repoPath, nodeId, 'spec.json');
+      try {
+        writeNodeFile(specAbs, `${JSON.stringify(updates.spec, null, 2)}\n`);
+      } catch (err) {
+        return {
+          kind: 'writeFailed',
+          message: err instanceof Error ? err.message : String(err),
+        };
+      }
+    }
     return { kind: 'ok' };
   });
 }