@tuongaz/seeflow 0.1.31 → 0.1.39

package/src/api.ts

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, realpathSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, realpathSync } from 'node:fs';
 import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
 import { Hono } from 'hono';
 import { streamSSE } from 'hono/streaming';
@@ -12,6 +12,7 @@ import {
   validateDemo,
 } from './diagram.ts';
 import type { EventBus } from './events.ts';
+import { type LayoutOptions, computeLayout } from './layout.ts';
 import {
   ConnectorPatchBodySchema,
   CreateProjectBodySchema,
@@ -35,6 +36,7 @@ import {
   reorderNodeImpl,
   resolveFilePath,
   validateImpl,
+  writeFileAtomic,
 } from './operations.ts';
 import type { ProcessSpawner } from './process-spawner.ts';
 import {
@@ -47,7 +49,7 @@ import {
   stopAllPlays as defaultStopAllPlays,
 } from './proxy.ts';
 import type { Registry } from './registry.ts';
-import { FlowSchema } from './schema.ts';
+import { FlowSchema, ResolvedFlowSchema } from './schema.ts';
 import { type Spawner, defaultSpawner } from './shellout.ts';
 import type { StatusRunner } from './status-runner.ts';
 import { readMergedFlow } from './watcher.ts';
@@ -270,10 +272,10 @@ export function createApi(options: ApiOptions): Hono {
     return c.json(validateDemo(parsed.data));
   });
 
-  // POST /api/validate — stateless schema validator for the architecture +
-  // optional style files. No flow id, no registry side-effects, no file://
-  // resolution (validation is structural only). Returns 200 even on
-  // validation failure — the result is the validation report itself.
+  // POST /api/validate — stateless schema validator for the flow + optional
+  // style files. No flow id, no registry side-effects, no file:// resolution
+  // (validation is structural only). Returns 200 even on validation failure —
+  // the result is the validation report itself.
   api.post('/validate', async (c) => {
     let body: unknown;
     try {
@@ -281,8 +283,8 @@ export function createApi(options: ApiOptions): Hono {
     } catch {
       return c.json({ error: 'Invalid JSON body' }, 400);
     }
-    if (!body || typeof body !== 'object' || !('architecture' in body)) {
-      return c.json({ error: 'Body must be { architecture, style? }' }, 400);
+    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));
   });
@@ -307,7 +309,7 @@ export function createApi(options: ApiOptions): Hono {
   // POST /api/diagram/assemble — Phase 7a. The skill POSTs wiring + layout
   // and gets back the assembled demo (IDs normalized, dupes dropped, dangling
   // connectors removed, positions snapped to a 24px grid). Pure compute; the
-  // skill writes the response to $TARGET/.seeflow/seeflow.json. No schema
+  // skill writes the response to $TARGET/.seeflow/flow.json. No schema
   // validation here — call /demos/validate for that.
   api.post('/diagram/assemble', async (c) => {
     let body: unknown;
@@ -320,18 +322,117 @@ export function createApi(options: ApiOptions): Hono {
     if (!parsed.success) {
       return c.json({ error: 'Invalid assemble body', issues: parsed.error.issues }, 400);
     }
-    return c.json(assembleDemo(parsed.data));
+    return c.json(await assembleDemo(parsed.data));
+  });
+
+  // POST /api/layout — stateless ELK layout. Two request shapes:
+  //   1. `{ flow, options? }` — skill (Phase 3 + Phase 5). Flow is validated
+  //      through FlowSchema; failure returns `{ ok: false, issues }` matching
+  //      /api/validate's shape.
+  //   2. `{ nodes, edges, options? }` — canvas Tidy button. Loose structural
+  //      input (id + type + measured width/height per node, id + source +
+  //      target per edge). Skips FlowSchema validation since Tidy has DOM
+  //      sizes but not full node data payloads.
+  // Both return `{ ok: true, nodes, connectors }` — positions keyed by node
+  // id, handle assignments keyed by connector id. Pure compute; no
+  // persistence.
+  api.post('/layout', async (c) => {
+    let body: unknown;
+    try {
+      body = await c.req.json();
+    } catch {
+      return c.json({ error: 'Body must be valid JSON' }, 400);
+    }
+    if (!body || typeof body !== 'object') {
+      return c.json(
+        { error: 'Body must be { flow, options? } or { nodes, edges, options? }' },
+        400,
+      );
+    }
+    const options = (body as { options?: LayoutOptions }).options;
+
+    if ('flow' in body) {
+      const flowParse = FlowSchema.safeParse((body as { flow: unknown }).flow);
+      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,
+          })),
+        });
+      }
+      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,
+      );
+      return c.json({ ok: true as const, nodes: result.nodes, connectors: result.connectors });
+    }
+
+    if ('nodes' in body && 'edges' in body) {
+      const { nodes, edges } = body as { nodes: unknown; edges: unknown };
+      if (!Array.isArray(nodes) || !Array.isArray(edges)) {
+        return c.json({ error: '`nodes` and `edges` must be arrays' }, 400);
+      }
+      // Trust the caller-supplied structural input — Tidy already measures
+      // DOM dimensions, so we use them verbatim. Any malformed entry is
+      // dropped silently rather than failing the whole layout.
+      const layoutNodes = nodes
+        .filter(
+          (n): n is { id: string; type: string; width?: number; height?: number } =>
+            n && typeof n === 'object' && typeof (n as { id?: unknown }).id === 'string',
+        )
+        .map((n) => ({
+          id: n.id,
+          type: n.type as
+            | 'playNode'
+            | 'stateNode'
+            | 'shapeNode'
+            | 'imageNode'
+            | 'iconNode'
+            | 'htmlNode',
+          data:
+            typeof n.width === 'number' && typeof n.height === 'number'
+              ? { width: n.width, height: n.height }
+              : undefined,
+        }));
+      const layoutEdges = edges
+        .filter(
+          (e): e is { id: string; source: string; target: string } =>
+            e &&
+            typeof e === 'object' &&
+            typeof (e as { id?: unknown }).id === 'string' &&
+            typeof (e as { source?: unknown }).source === 'string' &&
+            typeof (e as { target?: unknown }).target === 'string',
+        )
+        .map((e) => ({ id: e.id, source: e.source, target: e.target }));
+      const result = await computeLayout(layoutNodes, layoutEdges, options);
+      return c.json({ ok: true as const, nodes: result.nodes, connectors: result.connectors });
+    }
+
+    return c.json({ error: 'Body must be { flow, options? } or { nodes, edges, options? }' }, 400);
   });
 
   // POST /api/projects — UI-driven "Create new project" flow (US-020). Two
   // branches based on whether the target folder already has a SeeFlow
-  // project set up at `<folderPath>/.seeflow/seeflow.json`:
+  // project set up at `<folderPath>/.seeflow/flow.json`:
   //   1. Existing setup: read + validate the on-disk demo and register it
   //      as-is (no overwrite, no scaffolding). The user-supplied `name`
   //      becomes the registry display name; the on-disk demo's `name` is
   //      preserved on disk.
   //   2. Fresh scaffold: mkdir -p the folder + .seeflow/, write a default
-  //      scaffold seeflow.json keyed off `name`, and run the same SDK-emit
+  //      scaffold flow.json keyed off `name`, and run the same SDK-emit
   //      helper write the CLI register flow uses (a no-op for an empty
   //      scaffold, but kept for parity).
   api.post('/projects', async (c) => {
@@ -578,6 +679,97 @@ export function createApi(options: ApiOptions): Hono {
     }
   });
 
+  // POST /api/flows/:id/layout — registered-flow ELK layout. Reads flow.json
+  // from disk via the registry entry, computes layout, writes style.json
+  // atomically next to flow.json, and broadcasts flow:reload so any open
+  // canvas refreshes. Body is empty or `{ options? }`. Response on success is
+  // just `{ ok: true }` — the layout is already on disk. On schema failure
+  // returns `{ ok: false, issues }` mirroring /api/validate; on missing flow
+  // 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.
+    let options: LayoutOptions | undefined;
+    const text = await c.req.text();
+    if (text.length > 0) {
+      try {
+        const parsed = JSON.parse(text) as { options?: LayoutOptions };
+        options = parsed?.options;
+      } catch {
+        return c.json({ error: 'Body must be valid JSON' }, 400);
+      }
+    }
+
+    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 });
+  });
+
   api.post('/flows/:id/play/:nodeId', async (c) => {
     const id = c.req.param('id');
     const nodeId = c.req.param('nodeId');
@@ -587,7 +779,7 @@ export function createApi(options: ApiOptions): Hono {
 
     // Always re-read from disk so the user's most recent edit (validated or
     // not yet observed by the watcher) drives the actual fetch.
-    const fullPath = resolveFilePath(entry.repoPath, entry.architecturePath);
+    const fullPath = resolveFilePath(entry.repoPath, entry.flowPath);
     if (!existsSync(fullPath)) {
       return c.json({ error: `Flow file not found: ${fullPath}` }, 404);
     }
@@ -655,7 +847,7 @@ export function createApi(options: ApiOptions): Hono {
     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.architecturePath);
+    const fullPath = resolveFilePath(entry.repoPath, entry.flowPath);
     if (!existsSync(fullPath)) {
       return c.json({ error: `Flow file not found: ${fullPath}` }, 404);
     }
@@ -713,7 +905,7 @@ export function createApi(options: ApiOptions): Hono {
     return c.json({ ok: true, calledResetAction });
   });
 
-  // PATCH a single node's position back into the on-disk seeflow.json. This is
+  // PATCH a single node's position back into the on-disk flow.json. This is
   // the second (and only other) place the studio mutates user files — the
   // first being the SDK helper write in `register`. Atomic write via tempfile
   // + rename keeps editor diffs clean and avoids corruption mid-write.
@@ -797,7 +989,7 @@ export function createApi(options: ApiOptions): Hono {
   // 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
-  // is re-validated through FlowSchema before commit, preventing partial
+  // is re-validated through ResolvedFlowSchema before commit, preventing partial
   // writes from breaking invariants like the connector→node superRefine.
   api.patch('/flows/:id/nodes/:nodeId', async (c) => {
     const id = c.req.param('id');
@@ -834,7 +1026,7 @@ export function createApi(options: ApiOptions): Hono {
   });
 
   // POST a new node into the demo. Body is the node payload (id auto-generated
-  // server-side if absent). Atomicity + final-FlowSchema validation match the
+  // server-side if absent). Atomicity + final-ResolvedFlowSchema validation match the
   // PATCH path above, so a malformed node never produces a half-written file.
   api.post('/flows/:id/nodes', async (c) => {
     const id = c.req.param('id');
@@ -867,7 +1059,7 @@ export function createApi(options: ApiOptions): Hono {
   });
 
   // DELETE a node and cascade-remove every connector with source === nodeId or
-  // target === nodeId in the same atomic write. Final-FlowSchema validation
+  // target === nodeId in the same atomic write. Final-ResolvedFlowSchema validation
   // is still run after the mutation — connector cascade closure means it
   // should always pass, but the check makes the failure mode honest if the
   // file had a pre-existing schema violation we'd otherwise paper over.
@@ -897,7 +1089,7 @@ export function createApi(options: ApiOptions): Hono {
   // PATCH a single connector — partial update of label/style/color/direction
   // and (optionally) kind + per-kind payload fields. When `kind` changes,
   // stale kind-specific fields are dropped before the merge. The whole demo
-  // is re-validated through FlowSchema before commit so the discriminated
+  // is re-validated through ResolvedFlowSchema before commit so the discriminated
   // union catches missing-required-fields (e.g. kind='event' without
   // eventName) and the superRefine still gates source/target referential
   // integrity.
@@ -938,7 +1130,7 @@ export function createApi(options: ApiOptions): Hono {
   // POST a new connector. Body is the connector payload; `id` is auto-generated
   // server-side if absent and `kind` defaults to 'default' (the no-semantics
   // user-drawn variant). Source/target referential integrity is enforced by
-  // FlowSchema's superRefine on the post-mutation parse.
+  // ResolvedFlowSchema's superRefine on the post-mutation parse.
   api.post('/flows/:id/connectors', async (c) => {
     const id = c.req.param('id');