@tuongaz/seeflow 0.1.25 → 0.1.27

package/src/status-runner.ts

@@ -4,10 +4,10 @@
  * newline-delimited JSON stdout into `node:status` SSE events.
  *
  * Lifecycle per demo (held in `trackedByDemo`):
- *   restart(demoId) → kill previous batch (SIGTERM → 2s grace → SIGKILL in
+ *   restart(flowId) → kill previous batch (SIGTERM → 2s grace → SIGKILL in
  *     parallel) → re-read demo from disk → spawn each `statusAction` node in
  *     parallel.
- *   stop(demoId) / stopAll() → kill without respawn.
+ *   stop(flowId) / stopAll() → kill without respawn.
  *
  * Per-script lifecycle: spawn → drain stdout line-by-line → for each line,
  * JSON.parse + StatusReportSchema.safeParse → on success broadcast `node:status`,
@@ -24,14 +24,15 @@ import { existsSync, realpathSync } from 'node:fs';
 import { isAbsolute, join, resolve, sep } from 'node:path';
 import type { EventBus } from './events.ts';
 import { type ProcessSpawner, type SpawnHandle, defaultProcessSpawner } from './process-spawner.ts';
-import type { DemoEntry, Registry } from './registry.ts';
-import { type Demo, DemoSchema, type StatusAction, StatusReportSchema } from './schema.ts';
+import type { FlowEntry, Registry } from './registry.ts';
+import { type Flow, type StatusAction, StatusReportSchema } from './schema.ts';
+import { readMergedFlow } from './watcher.ts';
 
 export interface StatusRunner {
-  /** Kill the current batch for `demoId` and respawn from the on-disk demo. */
-  restart(demoId: string): Promise<void>;
-  /** Kill all status scripts for `demoId`. */
-  stop(demoId: string): Promise<void>;
+  /** Kill the current batch for `flowId` and respawn from the on-disk demo. */
+  restart(flowId: string): Promise<void>;
+  /** Kill all status scripts for `flowId`. */
+  stop(flowId: string): Promise<void>;
   /** Kill all status scripts for every demo. Used at studio shutdown. */
   stopAll(): Promise<void>;
 }
@@ -140,18 +141,13 @@ function truncate(s: string, n: number): string {
   return s.length > n ? `${s.slice(0, n)}…` : s;
 }
 
-async function loadDemo(entry: DemoEntry): Promise<Demo | undefined> {
-  const fullPath = isAbsolute(entry.demoPath)
-    ? entry.demoPath
-    : join(entry.repoPath, entry.demoPath);
+async function loadDemo(entry: FlowEntry): Promise<Flow | undefined> {
+  const fullPath = isAbsolute(entry.architecturePath)
+    ? entry.architecturePath
+    : join(entry.repoPath, entry.architecturePath);
   if (!existsSync(fullPath)) return undefined;
-  try {
-    const raw = await Bun.file(fullPath).json();
-    const parsed = DemoSchema.safeParse(raw);
-    return parsed.success ? parsed.data : undefined;
-  } catch {
-    return undefined;
-  }
+  const result = readMergedFlow(fullPath);
+  return result.flow ?? undefined;
 }
 
 interface StatusNode {
@@ -159,7 +155,7 @@ interface StatusNode {
   action: StatusAction;
 }
 
-function collectStatusNodes(demo: Demo): StatusNode[] {
+function collectStatusNodes(demo: Flow): StatusNode[] {
   const out: StatusNode[] = [];
   for (const node of demo.nodes) {
     if (node.type !== 'playNode' && node.type !== 'stateNode') continue;
@@ -176,7 +172,7 @@ export function createStatusRunner(options: CreateStatusRunnerOptions): StatusRu
   const trackedByDemo = new Map<string, TrackedHandle[]>();
 
   function spawnStatusScript(
-    demoId: string,
+    flowId: string,
     repoPath: string,
     sn: StatusNode,
   ): TrackedHandle | undefined {
@@ -186,7 +182,7 @@ export function createStatusRunner(options: CreateStatusRunnerOptions): StatusRu
     if (!resolved.ok) {
       events.broadcast({
         type: 'node:status',
-        demoId,
+        flowId,
         payload: {
           nodeId,
           state: 'error',
@@ -199,7 +195,7 @@ export function createStatusRunner(options: CreateStatusRunnerOptions): StatusRu
 
     const runId = crypto.randomUUID();
     const env = buildChildEnv({
-      SEEFLOW_DEMO_ID: demoId,
+      SEEFLOW_DEMO_ID: flowId,
       SEEFLOW_NODE_ID: nodeId,
       SEEFLOW_RUN_ID: runId,
     });
@@ -216,7 +212,7 @@ export function createStatusRunner(options: CreateStatusRunnerOptions): StatusRu
       const message = err instanceof Error ? err.message : String(err);
       events.broadcast({
         type: 'node:status',
-        demoId,
+        flowId,
         payload: {
           nodeId,
           state: 'error',
@@ -244,7 +240,7 @@ export function createStatusRunner(options: CreateStatusRunnerOptions): StatusRu
       tracked.expectingKill = true;
       events.broadcast({
         type: 'node:status',
-        demoId,
+        flowId,
         payload: {
           nodeId,
           state: 'error',
@@ -264,7 +260,7 @@ export function createStatusRunner(options: CreateStatusRunnerOptions): StatusRu
       } catch (err) {
         const reason = err instanceof Error ? err.message : String(err);
         console.warn(
-          `[status-runner] malformed status line (demo=${demoId} node=${nodeId}): ${truncate(trimmed, MALFORMED_LINE_TRUNCATE)} (${reason})`,
+          `[status-runner] malformed status line (demo=${flowId} node=${nodeId}): ${truncate(trimmed, MALFORMED_LINE_TRUNCATE)} (${reason})`,
         );
         return;
       }
@@ -272,14 +268,14 @@ export function createStatusRunner(options: CreateStatusRunnerOptions): StatusRu
       if (!result.success) {
         const reason = result.error.issues[0]?.message ?? 'schema validation failed';
         console.warn(
-          `[status-runner] invalid status report (demo=${demoId} node=${nodeId}): ${truncate(trimmed, MALFORMED_LINE_TRUNCATE)} (${reason})`,
+          `[status-runner] invalid status report (demo=${flowId} node=${nodeId}): ${truncate(trimmed, MALFORMED_LINE_TRUNCATE)} (${reason})`,
         );
         return;
       }
       const report = result.data;
       events.broadcast({
         type: 'node:status',
-        demoId,
+        flowId,
         payload: {
           nodeId,
           state: report.state,
@@ -302,7 +298,7 @@ export function createStatusRunner(options: CreateStatusRunnerOptions): StatusRu
       if (code !== 0) {
         events.broadcast({
           type: 'node:status',
-          demoId,
+          flowId,
           payload: {
             nodeId,
             state: 'error',
@@ -336,14 +332,14 @@ export function createStatusRunner(options: CreateStatusRunnerOptions): StatusRu
     );
   }
 
-  async function restart(demoId: string): Promise<void> {
-    const existing = trackedByDemo.get(demoId);
+  async function restart(flowId: string): Promise<void> {
+    const existing = trackedByDemo.get(flowId);
     if (existing) {
-      trackedByDemo.delete(demoId);
+      trackedByDemo.delete(flowId);
       await killBatch(existing);
     }
 
-    const entry = registry.getById(demoId);
+    const entry = registry.getById(flowId);
     if (!entry) return;
     const demo = await loadDemo(entry);
     if (!demo) return;
@@ -352,16 +348,16 @@ export function createStatusRunner(options: CreateStatusRunnerOptions): StatusRu
 
     const batch: TrackedHandle[] = [];
     for (const sn of statusNodes) {
-      const t = spawnStatusScript(demoId, entry.repoPath, sn);
+      const t = spawnStatusScript(flowId, entry.repoPath, sn);
       if (t) batch.push(t);
     }
-    if (batch.length > 0) trackedByDemo.set(demoId, batch);
+    if (batch.length > 0) trackedByDemo.set(flowId, batch);
   }
 
-  async function stop(demoId: string): Promise<void> {
-    const existing = trackedByDemo.get(demoId);
+  async function stop(flowId: string): Promise<void> {
+    const existing = trackedByDemo.get(flowId);
     if (!existing) return;
-    trackedByDemo.delete(demoId);
+    trackedByDemo.delete(flowId);
     await killBatch(existing);
   }
 

package/src/watcher.ts

@@ -1,14 +1,16 @@
 import { type FSWatcher, existsSync, readFileSync, watch } from 'node:fs';
 import { basename, dirname, isAbsolute, join } from 'node:path';
 import type { EventBus } from './events.ts';
+import { resolveFileRefs } from './file-ref.ts';
+import { mergeArchitectureAndStyle } from './merge.ts';
 import type { Registry } from './registry.ts';
-import { type Demo, DemoSchema } from './schema.ts';
+import { type Architecture, ArchitectureSchema, type Flow, StyleSchema } from './schema.ts';
 
 const DEFAULT_DEBOUNCE_MS = 100;
 
-export interface DemoSnapshot {
-  /** Last successfully parsed demo, if we ever saw one. */
-  demo: Demo | null;
+export interface FlowSnapshot {
+  /** Last successfully parsed flow, if we ever saw one. */
+  flow: Flow | null;
   /** Result of the most recent parse attempt. */
   valid: boolean;
   /** Human-readable error from the most recent parse, when `valid: false`. */
@@ -26,25 +28,25 @@ export interface WatcherDeps {
   debounceMs?: number;
 }
 
-export interface DemoWatcher {
+export interface FlowWatcher {
   /** Read the current snapshot for a demo, or null if unknown. */
-  snapshot(demoId: string): DemoSnapshot | null;
+  snapshot(flowId: string): FlowSnapshot | null;
   /** Begin watching the file backing the given demo id. Idempotent. */
-  watch(demoId: string): void;
+  watch(flowId: string): void;
   /** Stop watching a single demo. */
-  unwatch(demoId: string): void;
+  unwatch(flowId: string): void;
   /** Start watchers for every entry currently in the registry. */
   watchAll(): void;
   /** Stop everything (used in tests + on shutdown). */
   closeAll(): void;
   /** Force a reparse synchronously. Useful for tests + initial load. */
-  reparse(demoId: string): DemoSnapshot | null;
+  reparse(flowId: string): FlowSnapshot | null;
   /**
    * Relative paths (under `<project>/.seeflow/`) currently being watched
    * because they're referenced by a node's `data.htmlPath` or `data.path`.
    * Sorted for stable assertion order. Used by tests.
    */
-  referencedPaths(demoId: string): string[];
+  referencedPaths(flowId: string): string[];
 }
 
 interface FileWatchEntry {
@@ -67,8 +69,8 @@ interface WatchHandle {
   fileWatchers: Map<string, FileWatchEntry>;
 }
 
-const resolveFilePath = (repoPath: string, demoPath: string): string =>
-  isAbsolute(demoPath) ? demoPath : join(repoPath, demoPath);
+const resolveFilePath = (repoPath: string, architecturePath: string): string =>
+  isAbsolute(architecturePath) ? architecturePath : join(repoPath, architecturePath);
 
 const isCleanRelativePath = (p: string): boolean => {
   if (!p) return false;
@@ -83,11 +85,10 @@ const isCleanRelativePath = (p: string): boolean => {
 };
 
 /**
- * Walk raw demo JSON (pre-schema-parse) collecting referenced file paths:
- * `nodes[].data.htmlPath` (htmlNode) and `nodes[].data.path` (imageNode after
- * US-004). Operates on the raw JSON so the watcher works before those fields
- * are formally declared in the schema — Zod's default-strip would drop them
- * during validation, but the file watcher still needs to know about them.
+ * Walk raw architecture JSON (pre-schema-parse) collecting referenced file
+ * paths: `nodes[].data.htmlPath` (htmlNode) and `nodes[].data.path`
+ * (imageNode). Operates on the raw JSON so the watcher works before those
+ * fields are formally validated.
  */
 const collectReferencedPaths = (raw: unknown): string[] => {
   if (!raw || typeof raw !== 'object') return [];
@@ -108,6 +109,93 @@ const collectReferencedPaths = (raw: unknown): string[] => {
   return [...out];
 };
 
+/**
+ * Read architecture.json + optional style.json, resolve file:// refs in the
+ * architecture, validate both, and merge into a Flow. Shared by the watcher
+ * and by sync read fallbacks (getFlowImpl) so they produce identical results.
+ */
+export interface ReadMergedFlowResult {
+  flow: Flow | null;
+  valid: boolean;
+  error: string | null;
+  /** Sorted relative paths under `<seeflowRoot>` resolved via file://. */
+  fileRefs: string[];
+  /** Architecture file paths referenced via htmlPath / imageNode.path. */
+  staticRefs: string[];
+}
+
+export function readMergedFlow(archPath: string): ReadMergedFlowResult {
+  const empty: ReadMergedFlowResult = {
+    flow: null,
+    valid: false,
+    error: null,
+    fileRefs: [],
+    staticRefs: [],
+  };
+  if (!existsSync(archPath)) {
+    return { ...empty, error: `Architecture file not found: ${archPath}` };
+  }
+
+  const seeflowRoot = dirname(archPath);
+  const stylePath = join(seeflowRoot, 'style.json');
+
+  let rawArch: unknown;
+  try {
+    rawArch = JSON.parse(readFileSync(archPath, 'utf8'));
+  } catch (err) {
+    return {
+      ...empty,
+      error: `Invalid JSON in architecture.json: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+
+  const { resolved, refs } = resolveFileRefs(rawArch, seeflowRoot);
+  const staticRefs = collectReferencedPaths(rawArch);
+
+  const archParse = ArchitectureSchema.safeParse(resolved);
+  if (!archParse.success) {
+    const message = archParse.error.issues
+      .map((i) => `${i.path.join('.') || '<root>'}: ${i.message}`)
+      .join('; ');
+    return {
+      ...empty,
+      error: `Architecture schema validation failed: ${message}`,
+      fileRefs: refs,
+      staticRefs,
+    };
+  }
+
+  let rawStyle: unknown = {};
+  if (existsSync(stylePath)) {
+    try {
+      rawStyle = JSON.parse(readFileSync(stylePath, 'utf8'));
+    } catch (err) {
+      return {
+        ...empty,
+        error: `Invalid JSON in style.json: ${err instanceof Error ? err.message : String(err)}`,
+        fileRefs: refs,
+        staticRefs,
+      };
+    }
+  }
+
+  const styleParse = StyleSchema.safeParse(rawStyle);
+  if (!styleParse.success) {
+    const message = styleParse.error.issues
+      .map((i) => `${i.path.join('.') || '<root>'}: ${i.message}`)
+      .join('; ');
+    return {
+      ...empty,
+      error: `Style schema validation failed: ${message}`,
+      fileRefs: refs,
+      staticRefs,
+    };
+  }
+
+  const flow = mergeArchitectureAndStyle(archParse.data as Architecture, styleParse.data);
+  return { flow, valid: true, error: null, fileRefs: refs, staticRefs };
+}
+
 const closeFileWatchers = (handle: WatchHandle): void => {
   for (const entry of handle.fileWatchers.values()) {
     entry.fsWatcher.close();
@@ -116,18 +204,18 @@ const closeFileWatchers = (handle: WatchHandle): void => {
   handle.fileWatchers.clear();
 };
 
-export function createWatcher(deps: WatcherDeps): DemoWatcher {
+export function createWatcher(deps: WatcherDeps): FlowWatcher {
   const { registry, events } = deps;
   const debounceMs = deps.debounceMs ?? DEFAULT_DEBOUNCE_MS;
 
   const handles = new Map<string, WatchHandle>();
-  const snapshots = new Map<string, DemoSnapshot>();
+  const snapshots = new Map<string, FlowSnapshot>();
 
-  // Reconcile the file-watch set for `demoId` against the desired referenced
+  // Reconcile the file-watch set for `flowId` against the desired referenced
   // paths. Closes watchers for dirs that disappeared, updates the basename
   // map for dirs that survived, opens new fs.watch handles for new dirs.
   const reconcileFileWatchers = (
-    demoId: string,
+    flowId: string,
     handle: WatchHandle,
     seeflowRoot: string,
     refs: string[],
@@ -190,14 +278,14 @@ export function createWatcher(deps: WatcherDeps): DemoWatcher {
             cur.timers.delete(changed);
             events.broadcast({
               type: 'file:changed',
-              demoId,
+              flowId,
               payload: { path: rel },
             });
           }, debounceMs);
           cur.timers.set(changed, timer);
         });
       } catch (err) {
-        console.error(`[watcher] failed to watch ${dir} for demo ${demoId}:`, err);
+        console.error(`[watcher] failed to watch ${dir} for demo ${flowId}:`, err);
         continue;
       }
 
@@ -209,153 +297,116 @@ export function createWatcher(deps: WatcherDeps): DemoWatcher {
     }
   };
 
-  const reparse = (demoId: string): DemoSnapshot | null => {
-    const entry = registry.getById(demoId);
+  const reparse = (flowId: string): FlowSnapshot | null => {
+    const entry = registry.getById(flowId);
     if (!entry) return null;
-    const filePath = resolveFilePath(entry.repoPath, entry.demoPath);
+    const filePath = resolveFilePath(entry.repoPath, entry.architecturePath);
 
-    const previous = snapshots.get(demoId) ?? null;
+    const previous = snapshots.get(flowId) ?? null;
     const parsedAt = Date.now();
-    const fail = (error: string): DemoSnapshot => ({
-      demo: previous?.demo ?? null,
-      valid: false,
-      error,
-      filePath,
-      parsedAt,
-    });
-
-    let next: DemoSnapshot;
-    let raw: unknown = null;
-    let rawOk = false;
-
-    if (!existsSync(filePath)) {
-      next = fail(`Demo file not found: ${filePath}`);
-    } else {
-      let parseError: string | null = null;
-      try {
-        raw = JSON.parse(readFileSync(filePath, 'utf8'));
-        rawOk = true;
-      } catch (err) {
-        parseError = `Invalid JSON: ${err instanceof Error ? err.message : String(err)}`;
-      }
-
-      if (!rawOk) {
-        next = fail(parseError ?? 'Invalid JSON');
-      } else {
-        const parsed = DemoSchema.safeParse(raw);
-        if (!parsed.success) {
-          const message = parsed.error.issues
-            .map((i) => `${i.path.join('.') || '<root>'}: ${i.message}`)
-            .join('; ');
-          next = fail(`Schema validation failed: ${message}`);
-        } else {
-          next = { demo: parsed.data, valid: true, error: null, filePath, parsedAt };
-        }
-      }
-    }
-
-    snapshots.set(demoId, next);
-
-    // Recompute the referenced-files watch set whenever raw JSON parsed
-    // cleanly (regardless of schema validity). Schema errors shouldn't drop
-    // the watch set — the user is mid-edit and the referenced files are
-    // still valid targets.
-    if (rawOk) {
-      const handle = handles.get(demoId);
-      if (handle) {
-        reconcileFileWatchers(
-          demoId,
-          handle,
-          join(entry.repoPath, '.seeflow'),
-          collectReferencedPaths(raw),
-        );
-      }
+    const result = readMergedFlow(filePath);
+
+    const next: FlowSnapshot = result.valid
+      ? { flow: result.flow, valid: true, error: null, filePath, parsedAt }
+      : { flow: previous?.flow ?? null, valid: false, error: result.error, filePath, parsedAt };
+
+    snapshots.set(flowId, next);
+
+    // Reconcile the referenced-file watch set: htmlPath/imageNode.path from
+    // architecture + any file:// targets that resolved cleanly. Schema errors
+    // shouldn't drop the watch set — the user is mid-edit and the referenced
+    // files are still valid targets, so this reconciles whenever the JSON
+    // parsed (even if schema validation failed).
+    const handle = handles.get(flowId);
+    if (handle) {
+      const allRefs = [...result.fileRefs, ...result.staticRefs];
+      reconcileFileWatchers(flowId, handle, dirname(filePath), allRefs);
     }
 
     return next;
   };
 
-  const broadcastReload = (demoId: string, snap: DemoSnapshot) => {
+  const broadcastReload = (flowId: string, snap: FlowSnapshot) => {
     events.broadcast({
-      type: 'demo:reload',
-      demoId,
-      payload: snap.valid ? { valid: true, demo: snap.demo } : { valid: false, error: snap.error },
+      type: 'flow:reload',
+      flowId,
+      payload: snap.valid ? { valid: true, flow: snap.flow } : { valid: false, error: snap.error },
     });
   };
 
-  const startWatch = (demoId: string) => {
-    const existing = handles.get(demoId);
+  const startWatch = (flowId: string) => {
+    const existing = handles.get(flowId);
     if (existing) {
       existing.fsWatcher.close();
       if (existing.debounceTimer) clearTimeout(existing.debounceTimer);
       closeFileWatchers(existing);
-      handles.delete(demoId);
+      handles.delete(flowId);
     }
 
-    const entry = registry.getById(demoId);
+    const entry = registry.getById(flowId);
     if (!entry) return;
 
-    const filePath = resolveFilePath(entry.repoPath, entry.demoPath);
+    const filePath = resolveFilePath(entry.repoPath, entry.architecturePath);
     const dir = dirname(filePath);
     const base = basename(filePath);
 
     if (!existsSync(dir)) {
       // Directory missing — record an invalid snapshot but don't try to watch.
-      const snap = reparse(demoId);
-      if (snap) broadcastReload(demoId, snap);
+      const snap = reparse(flowId);
+      if (snap) broadcastReload(flowId, snap);
       return;
     }
 
     let fsWatcher: FSWatcher;
     try {
       fsWatcher = watch(dir, { persistent: true }, (_event, changed) => {
-        // Only react to the demo file (or to events with no filename, which
-        // some platforms emit for rename-on-save patterns).
-        if (changed && changed !== base) return;
-        const handle = handles.get(demoId);
+        // React to architecture.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;
-          const snap = reparse(demoId);
-          if (snap) broadcastReload(demoId, snap);
+          const snap = reparse(flowId);
+          if (snap) broadcastReload(flowId, snap);
         }, debounceMs);
       });
     } catch (err) {
-      console.error(`[watcher] failed to watch ${dir} for demo ${demoId}:`, err);
-      const snap = reparse(demoId);
-      if (snap) broadcastReload(demoId, snap);
+      console.error(`[watcher] failed to watch ${dir} for flow ${flowId}:`, err);
+      const snap = reparse(flowId);
+      if (snap) broadcastReload(flowId, snap);
       return;
     }
 
-    handles.set(demoId, {
+    handles.set(flowId, {
       fsWatcher,
       debounceTimer: null,
       filePath,
       fileWatchers: new Map(),
     });
 
-    // Seed the snapshot from disk so callers can serve GET /api/demos/:id
+    // Seed the snapshot from disk so callers can serve GET /api/flows/:id
     // without having to wait for the first fs event. Also seeds the
     // referenced-file watch set via reconcileFileWatchers().
-    reparse(demoId);
+    reparse(flowId);
   };
 
   return {
-    snapshot(demoId) {
-      return snapshots.get(demoId) ?? null;
+    snapshot(flowId) {
+      return snapshots.get(flowId) ?? null;
     },
-    watch(demoId) {
-      startWatch(demoId);
+    watch(flowId) {
+      startWatch(flowId);
     },
-    unwatch(demoId) {
-      const h = handles.get(demoId);
+    unwatch(flowId) {
+      const h = handles.get(flowId);
       if (!h) return;
       h.fsWatcher.close();
       if (h.debounceTimer) clearTimeout(h.debounceTimer);
       closeFileWatchers(h);
-      handles.delete(demoId);
-      snapshots.delete(demoId);
+      handles.delete(flowId);
+      snapshots.delete(flowId);
     },
     watchAll() {
       for (const entry of registry.list()) startWatch(entry.id);
@@ -370,8 +421,8 @@ export function createWatcher(deps: WatcherDeps): DemoWatcher {
       snapshots.clear();
     },
     reparse,
-    referencedPaths(demoId) {
-      const h = handles.get(demoId);
+    referencedPaths(flowId) {
+      const h = handles.get(flowId);
       if (!h) return [];
       const paths: string[] = [];
       for (const entry of h.fileWatchers.values()) {