@tuongaz/seeflow 0.1.64 → 0.1.68

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/diagram.ts

@@ -240,9 +240,10 @@ const normalizeConnectors = (
 // Single-flow-node graphs short-circuit so callers can pin standalone
 // nodes via `layout.positions`.
 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';
+  // Flat-types refactor: visual kind IS the type. The annotation shapes
+  // (sticky + text) live as top-level type tags rather than nested shape
+  // under a generic shape variant.
+  return n.type === 'sticky' || n.type === 'text';
 };
 
 const autoLayout = async (
@@ -354,12 +355,14 @@ export const validateDemo = (req: ValidateRequest): ValidateReport => {
 
   const playable = nodes.filter((n) => {
     const data = n.data as { playAction?: unknown } | undefined;
-    return n.type === 'playNode' || (n.type === 'stateNode' && data?.playAction !== undefined);
+    // Flat-types refactor: a node is playable iff it carries a playAction
+    // capability, regardless of variant.
+    return 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.`,
+      message: `Tier '${tier}' requires at least one playable node; found 0. Set data.playAction on a node or set tier=static.`,
     });
   }
 

package/src/layout.ts

@@ -51,7 +51,7 @@ export interface LayoutResult {
 export interface LayoutNode {
   id: string;
   type: FlowNode['type'];
-  data?: { width?: number; height?: number; shape?: string };
+  data?: { width?: number; height?: number };
 }
 
 export interface LayoutEdge {
@@ -60,42 +60,39 @@ export interface LayoutEdge {
   target: string;
 }
 
+// Per-type default size used when a node has no explicit width/height. Mirrors
+// the canvas's SHAPE_DEFAULT_SIZE so ELK's layout matches what the canvas will
+// paint.
 const DEFAULT_DIMENSIONS: Record<FlowNode['type'], { width: number; height: number }> = {
-  playNode: { width: 220, height: 100 },
-  stateNode: { width: 220, height: 100 },
-  shapeNode: { width: 160, height: 80 },
-  iconNode: { width: 80, height: 80 },
-  htmlNode: { width: 320, height: 200 },
-  imageNode: { width: 200, height: 150 },
-};
-
-const SHAPE_OVERRIDES: Record<string, { width: number; height: number }> = {
+  rectangle: { width: 200, height: 120 },
+  ellipse: { width: 200, height: 120 },
+  sticky: { width: 180, height: 180 },
   text: { width: 160, height: 40 },
-  sticky: { width: 160, height: 180 },
+  database: { width: 120, height: 140 },
+  server: { width: 140, height: 120 },
+  user: { width: 100, height: 140 },
+  queue: { width: 220, height: 80 },
+  cloud: { width: 180, height: 120 },
+  image: { width: 200, height: 150 },
+  html: { width: 320, height: 200 },
+  icon: { width: 80, height: 80 },
+  component: { width: 320, height: 240 },
 };
 
-const FLOATING_SHAPES = new Set(['sticky', 'text']);
+// Sticky / text variants are floating annotations. They never participate in
+// layered layout — they sit in a side column so the orthogonal flow stays
+// clean.
+const FLOATING_TYPES: ReadonlySet<FlowNode['type']> = new Set(['sticky', 'text']);
 
 const nodeDimensions = (node: LayoutNode): { width: number; height: number } => {
   const data = node.data ?? {};
   if (typeof data.width === 'number' && typeof data.height === 'number') {
     return { width: data.width, height: data.height };
   }
-  if (node.type === 'shapeNode' && data.shape) {
-    const override = SHAPE_OVERRIDES[data.shape];
-    if (override) return override;
-  }
   return DEFAULT_DIMENSIONS[node.type];
 };
 
-// Sticky / text shapes are floating annotations. They never participate in
-// layered layout — they sit in a side column so the orthogonal flow stays
-// clean.
-const isFloatingAnnotation = (node: LayoutNode): boolean => {
-  if (node.type !== 'shapeNode') return false;
-  const shape = node.data?.shape;
-  return shape !== undefined && FLOATING_SHAPES.has(shape);
-};
+const isFloatingAnnotation = (node: LayoutNode): boolean => FLOATING_TYPES.has(node.type);
 
 // Schema vocabulary: SourceHandle ∈ {r, b}, TargetHandle ∈ {t, l}. After
 // ELK lays out positions we pick handles geometrically — the layered LR
@@ -162,7 +159,7 @@ export const computeLayout = async (
         'elk.separateConnectedComponents': 'true',
       },
       children: laidOut.map((n) => {
-        const d = dims.get(n.id) ?? DEFAULT_DIMENSIONS.playNode;
+        const d = dims.get(n.id) ?? DEFAULT_DIMENSIONS.rectangle;
         return { id: n.id, width: d.width, height: d.height };
       }),
       edges: connectors
@@ -193,7 +190,7 @@ export const computeLayout = async (
     const columnX = laidOut.length > 0 ? maxRight + 200 : 0;
     let cursorY = 0;
     for (const n of floatingNodes) {
-      const d = dims.get(n.id) ?? DEFAULT_DIMENSIONS.shapeNode;
+      const d = dims.get(n.id) ?? DEFAULT_DIMENSIONS.rectangle;
       result.nodes[n.id] = { position: { x: columnX, y: cursorY } };
       cursorY += d.height + nodeSpacing;
     }

package/src/mcp.ts

@@ -461,7 +461,7 @@ const buildTools = (ops: Operations): McpTool[] => [
   {
     name: 'seeflow_add_node',
     description:
-      'Append a new node to a flow (cascade-safe; id auto-generated when omitted). Text content fields (detail on every node; html on htmlNode) are auto-externalized to <project>/nodes/<id>/ and stored as file:// refs in flow.json; reads inline the resolved content transparently.',
+      "Append a new node to a flow (cascade-safe; id auto-generated when omitted). Text content fields (detail on every node; html on type:'html') are auto-externalized to <project>/nodes/<id>/ and stored as file:// refs in flow.json; reads inline the resolved content transparently.",
     inputSchema: inputSchemaFromZod(AddNodeInputSchema),
     handler: async (args) => {
       const parsed = AddNodeInputSchema.safeParse(args);
@@ -585,7 +585,7 @@ const buildTools = (ops: Operations): McpTool[] => [
   {
     name: 'seeflow_patch_node',
     description:
-      'Update fields on an existing node (position, name, description, detail, icon, colors, border, font, shape, dimensions, autoSize, plus iconNode-only color/strokeWidth/alt). Setting detail (every node) or html (htmlNode) writes the content to <project>/nodes/<id>/{detail.md|view.html}; the file:// ref on the node persists. Empty-string detail empties the file but keeps the ref.',
+      "Update fields on an existing node (position, name, description, detail, icon, colors, border, font, dimensions, autoSize, plus type:'icon'-only color/strokeWidth/alt and capabilities playAction/statusAction/stateSource). `type` can flip a node between any of the 12 visual variants (rectangle/ellipse/sticky/text/database/server/user/queue/cloud/image/html/icon); the post-merge schema reparse gates required fields on the new type (image.data.path, icon.data.icon). Setting detail (every node) or html (type:'html') writes the content to <project>/nodes/<id>/{detail.md|view.html}; the file:// ref on the node persists. Empty-string detail empties the file but keeps the ref.",
     inputSchema: inputSchemaFromZod(PatchNodeInputSchema),
     handler: async (args) => {
       const parsed = PatchNodeInputSchema.safeParse(args);

package/src/merge.ts

@@ -39,10 +39,12 @@ export function mergeFlowAndStyle(flow: Flow, style: Style): ResolvedFlow {
 }
 
 // Fields that live in a node's `data` block on flow.json. Every other data
-// field is visual and routes to style.json.
+// field is visual and routes to style.json. The flat-types refactor folds
+// the visual kind into `node.type` itself (no more nested data.shape / data.kind)
+// and makes every capability (playAction / statusAction / stateSource) valid
+// on every type.
 const NODE_DATA_FLOW_KEYS = new Set([
   'name',
-  'kind',
   'stateSource',
   'handlerModule',
   'icon',
@@ -50,7 +52,6 @@ const NODE_DATA_FLOW_KEYS = new Set([
   'detail',
   'playAction',
   'statusAction',
-  'shape',
   'path',
   'alt',
   'html',
@@ -132,6 +133,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/node-files.ts

@@ -14,7 +14,7 @@ export interface ExternalizedFieldSpec {
 
 export const EXTERNALIZED_NODE_FIELDS: readonly ExternalizedFieldSpec[] = [
   { field: 'detail', fileName: 'detail.md' },
-  { field: 'html', fileName: 'view.html', nodeTypes: ['htmlNode'] },
+  { field: 'html', fileName: 'view.html', nodeTypes: ['html'] },
 ];
 
 export const externalizedFieldsForNodeType = (