@tuongaz/seeflow 0.1.47 → 0.1.52

package/src/registry-watcher.ts

@@ -0,0 +1,86 @@
+import { type FSWatcher, existsSync, readFileSync, watch } from 'node:fs';
+import { basename, dirname } from 'node:path';
+import type { EventBus } from './events.ts';
+import type { Registry } from './registry.ts';
+
+const DEFAULT_DEBOUNCE_MS = 100;
+
+/**
+ * Internal sentinel flowId used to broadcast registry-scoped events on the
+ * (flowId-keyed) EventBus. SSE consumers subscribe to this exact channel.
+ */
+export const REGISTRY_CHANNEL = '__registry__';
+
+export interface RegistryWatcherDeps {
+  registry: Registry;
+  events: EventBus;
+  /** Override for tests. */
+  debounceMs?: number;
+}
+
+export interface RegistryWatcher {
+  start(): void;
+  close(): void;
+}
+
+export function createRegistryWatcher(deps: RegistryWatcherDeps): RegistryWatcher {
+  const { registry, events } = deps;
+  const debounceMs = deps.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+
+  const filePath = registry.path;
+  const dir = dirname(filePath);
+  const base = basename(filePath);
+
+  let fsWatcher: FSWatcher | null = null;
+  let debounceTimer: ReturnType<typeof setTimeout> | null = null;
+  let started = false;
+
+  const onChange = () => {
+    if (!existsSync(filePath)) return;
+    let contents: string;
+    try {
+      contents = readFileSync(filePath, 'utf8');
+    } catch {
+      return;
+    }
+    if (registry.isOwnWrite(contents)) return;
+    registry.reload();
+    events.broadcast({
+      type: 'registry:reload',
+      flowId: REGISTRY_CHANNEL,
+      payload: {},
+    });
+  };
+
+  return {
+    start() {
+      if (started) return;
+      started = true;
+      if (!existsSync(dir)) {
+        // Parent directory may not exist yet on a clean machine. The studio
+        // creates it on first persist, but we'd miss that event. Bail without
+        // throwing — callers can choose to start() again later.
+        return;
+      }
+      try {
+        fsWatcher = watch(dir, { persistent: true }, (_event, changed) => {
+          if (changed && changed !== base) return;
+          if (debounceTimer) clearTimeout(debounceTimer);
+          debounceTimer = setTimeout(() => {
+            debounceTimer = null;
+            onChange();
+          }, debounceMs);
+        });
+      } catch (err) {
+        console.error(`[registry-watcher] failed to watch ${dir}:`, err);
+      }
+    },
+    close() {
+      if (debounceTimer) clearTimeout(debounceTimer);
+      debounceTimer = null;
+      if (fsWatcher) fsWatcher.close();
+      fsWatcher = null;
+      started = false;
+    },
+  };
+}

package/src/registry.ts

@@ -1,5 +1,7 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, statSync } from 'node:fs';
 import { dirname, join } from 'node:path';
+import { writeFileAtomic } from './atomic-write.ts';
 import { seeflowHome } from './paths.ts';
 import { shortId } from './short-id.ts';
 
@@ -7,6 +9,7 @@ export interface FlowEntry {
   id: string;
   slug: string;
   name: string;
+  description?: string;
   repoPath: string;
   flowPath: string;
   lastModified: number;
@@ -15,6 +18,7 @@ export interface FlowEntry {
 
 export interface RegisterInput {
   name: string;
+  description?: string;
   repoPath: string;
   flowPath: string;
   valid?: boolean;
@@ -22,6 +26,8 @@ export interface RegisterInput {
 }
 
 export interface Registry {
+  /** Resolved path of the registry file on disk. */
+  readonly path: string;
   list(): FlowEntry[];
   getById(id: string): FlowEntry | undefined;
   getBySlug(slug: string): FlowEntry | undefined;
@@ -29,6 +35,12 @@ export interface Registry {
   getByRepoPathAndFlowPath(repoPath: string, flowPath: string): FlowEntry | undefined;
   upsert(input: RegisterInput): FlowEntry;
   remove(id: string): boolean;
+  /** Subscribe to external changes detected via reload(). Returns unsubscribe. */
+  onChange(fn: () => void): () => void;
+  /** Drop the in-memory cache and re-read from disk. Fires onChange listeners. */
+  reload(): void;
+  /** True when `contents` matches a hash this registry recently persisted. */
+  isOwnWrite(contents: string): boolean;
 }
 
 export function defaultRegistryPath(): string {
@@ -43,39 +55,95 @@ export function slugify(name: string): string {
   return slug || 'demo';
 }
 
+const OWN_WRITE_RING_SIZE = 4;
+
 export function createRegistry(options: { path?: string } = {}): Registry {
   const path = options.path ?? defaultRegistryPath();
   const entries = new Map<string, FlowEntry>();
+  const writtenHashes: string[] = [];
+  const listeners = new Set<() => void>();
+
+  const sha256 = (s: string): string => createHash('sha256').update(s).digest('hex');
+
+  const rememberWrite = (contents: string) => {
+    writtenHashes.push(sha256(contents));
+    if (writtenHashes.length > OWN_WRITE_RING_SIZE) writtenHashes.shift();
+  };
+
+  // Mtime of the last on-disk state we observed (load or persist). Used by
+  // refreshIfStale() to detect external writes (notably the in-process CLI
+  // mutating registry.json while the studio is running) without waiting for
+  // the debounced fs.watch callback.
+  let lastSeenMtimeMs = 0;
+
+  const statMtimeMs = (): number | null => {
+    try {
+      return statSync(path).mtimeMs;
+    } catch {
+      return null;
+    }
+  };
 
-  if (existsSync(path)) {
+  const loadFromDisk = () => {
+    entries.clear();
+    if (!existsSync(path)) {
+      lastSeenMtimeMs = 0;
+      return;
+    }
     try {
       const parsed = JSON.parse(readFileSync(path, 'utf8'));
-      if (Array.isArray(parsed)) {
-        for (const e of parsed) {
-          if (
-            e &&
-            typeof e.id === 'string' &&
-            typeof e.slug === 'string' &&
-            typeof e.repoPath === 'string'
-          ) {
-            if (typeof e.flowPath !== 'string') {
-              console.warn(
-                `[registry] ignoring legacy entry ${e.id} (${e.slug}) — pre-split format, please re-register`,
-              );
-              continue;
-            }
-            entries.set(e.id, e as FlowEntry);
+      if (!Array.isArray(parsed)) {
+        lastSeenMtimeMs = statMtimeMs() ?? 0;
+        return;
+      }
+      for (const e of parsed) {
+        if (
+          e &&
+          typeof e.id === 'string' &&
+          typeof e.slug === 'string' &&
+          typeof e.repoPath === 'string'
+        ) {
+          if (typeof e.flowPath !== 'string') {
+            console.warn(
+              `[registry] ignoring legacy entry ${e.id} (${e.slug}) — pre-split format, please re-register`,
+            );
+            continue;
           }
+          const entry = e as FlowEntry;
+          if (entry.description !== undefined && typeof entry.description !== 'string') {
+            entry.description = undefined;
+          }
+          entries.set(entry.id, entry);
         }
       }
+      lastSeenMtimeMs = statMtimeMs() ?? 0;
     } catch (err) {
       console.error(`[registry] failed to load ${path}, starting empty:`, err);
+      lastSeenMtimeMs = statMtimeMs() ?? 0;
+    }
+  };
+
+  loadFromDisk();
+
+  // Cheap stat-and-reload guard for read paths. When another process (the
+  // in-process CLI) has written registry.json since our last load, the
+  // debounced fs.watch reload can lag the next HTTP read; this closes that
+  // gap with one stat() per request.
+  const refreshIfStale = () => {
+    const mtime = statMtimeMs();
+    if (mtime === null) {
+      if (lastSeenMtimeMs !== 0) loadFromDisk();
+      return;
     }
-  }
+    if (mtime !== lastSeenMtimeMs) loadFromDisk();
+  };
 
   const persist = () => {
     mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, JSON.stringify([...entries.values()], null, 2));
+    const contents = JSON.stringify([...entries.values()], null, 2);
+    rememberWrite(contents);
+    writeFileAtomic(path, contents);
+    lastSeenMtimeMs = statMtimeMs() ?? lastSeenMtimeMs;
   };
 
   const findByRepoPath = (repoPath: string): FlowEntry | undefined => {
@@ -101,19 +169,39 @@ export function createRegistry(options: { path?: string } = {}): Registry {
   };
 
   return {
-    list: () => [...entries.values()],
-    getById: (id) => entries.get(id),
-    getBySlug: (slug) => [...entries.values()].find((e) => e.slug === slug),
-    getByRepoPath: findByRepoPath,
-    getByRepoPathAndFlowPath: findByRepoPathAndFlowPath,
+    path,
+    list: () => {
+      refreshIfStale();
+      return [...entries.values()];
+    },
+    getById: (id) => {
+      refreshIfStale();
+      return entries.get(id);
+    },
+    getBySlug: (slug) => {
+      refreshIfStale();
+      return [...entries.values()].find((e) => e.slug === slug);
+    },
+    getByRepoPath: (repoPath) => {
+      refreshIfStale();
+      return findByRepoPath(repoPath);
+    },
+    getByRepoPathAndFlowPath: (repoPath, flowPath) => {
+      refreshIfStale();
+      return findByRepoPathAndFlowPath(repoPath, flowPath);
+    },
     upsert(input) {
       const lastModified = input.lastModified ?? Date.now();
       const valid = input.valid ?? true;
       const existing = findByRepoPathAndFlowPath(input.repoPath, input.flowPath);
       if (existing) {
+        // input.description reflects the current flow.json on every call —
+        // when an author removes the description, we drop it from the entry
+        // too (JSON.stringify skips undefined values on persist).
         const updated: FlowEntry = {
           ...existing,
           name: input.name,
+          description: input.description,
           flowPath: input.flowPath,
           lastModified,
           valid,
@@ -128,6 +216,7 @@ export function createRegistry(options: { path?: string } = {}): Registry {
         id,
         slug,
         name: input.name,
+        description: input.description,
         repoPath: input.repoPath,
         flowPath: input.flowPath,
         lastModified,
@@ -142,5 +231,24 @@ export function createRegistry(options: { path?: string } = {}): Registry {
       if (removed) persist();
       return removed;
     },
+    onChange(fn) {
+      listeners.add(fn);
+      return () => {
+        listeners.delete(fn);
+      };
+    },
+    reload() {
+      loadFromDisk();
+      for (const fn of listeners) {
+        try {
+          fn();
+        } catch (err) {
+          console.error('[registry] onChange listener threw:', err);
+        }
+      }
+    },
+    isOwnWrite(contents) {
+      return writtenHashes.includes(sha256(contents));
+    },
   };
 }

package/src/schema.ts

@@ -385,6 +385,7 @@ export const ResolvedFlowSchema = z
   .object({
     version: z.literal(2),
     name: z.string().min(1),
+    description: z.string().optional(),
     nodes: z.array(NodeSchema),
     connectors: z.array(ConnectorSchema),
     // Optional one-shot script the studio runs when the user clicks Restart.
@@ -610,6 +611,7 @@ export const FlowSchema = z
   .object({
     version: z.literal(2),
     name: z.string().min(1),
+    description: z.string().optional(),
     resetAction: ResetActionSchema.optional(),
     nodes: z.array(FlowNodeSchema),
     connectors: z.array(FlowConnectorSchema),

package/src/server.ts

@@ -8,6 +8,7 @@ import { createDemoRouter } from './demo.ts';
 import { type EventBus, createEventBus } from './events.ts';
 import { createMcpServer } from './mcp.ts';
 import { type ProcessSpawner, defaultProcessSpawner } from './process-spawner.ts';
+import { type RegistryWatcher, createRegistryWatcher } from './registry-watcher.ts';
 import { type Registry, createRegistry } from './registry.ts';
 import type { Spawner } from './shellout.ts';
 import { type StatusRunner, createStatusRunner } from './status-runner.ts';
@@ -33,6 +34,8 @@ export interface CreateAppOptions {
   events?: EventBus;
   /** Inject a watcher; defaults to one wired to the registry + event bus. */
   watcher?: FlowWatcher;
+  /** Inject a registry-watcher; defaults to one wired to the registry + event bus. */
+  registryWatcher?: RegistryWatcher;
   /** Skip starting fs.watch on registered demos. Useful for tests. */
   watchAllOnBoot?: boolean;
   /** Disable file watching entirely (no fs handles leaked). Useful for tests. */
@@ -74,6 +77,9 @@ export function createApp(options: CreateAppOptions = {}): Hono {
   const watcher = options.disableWatcher
     ? undefined
     : (options.watcher ?? createWatcher({ registry, events }));
+  const registryWatcher = options.disableWatcher
+    ? undefined
+    : (options.registryWatcher ?? createRegistryWatcher({ registry, events }));
   const statusRunner =
     options.statusRunner ??
     createStatusRunner({ registry, events, spawner: defaultProcessSpawner });
@@ -81,6 +87,9 @@ export function createApp(options: CreateAppOptions = {}): Hono {
   if (watcher && (options.watchAllOnBoot ?? true)) {
     watcher.watchAll();
   }
+  if (registryWatcher && (options.watchAllOnBoot ?? true)) {
+    registryWatcher.start();
+  }
 
   const app = new Hono();
 

package/src/watcher.ts

@@ -1,5 +1,5 @@
 import { createHash } from 'node:crypto';
-import { type FSWatcher, existsSync, readFileSync, watch } from 'node:fs';
+import { type FSWatcher, existsSync, readFileSync, statSync, watch } from 'node:fs';
 import { basename, dirname, isAbsolute, join } from 'node:path';
 import type { EventBus } from './events.ts';
 import { resolveFileRefs } from './file-ref.ts';
@@ -255,6 +255,13 @@ export function createWatcher(deps: WatcherDeps): FlowWatcher {
 
   const handles = new Map<string, WatchHandle>();
   const snapshots = new Map<string, FlowSnapshot>();
+  /**
+   * Combined flow+style mtime witnessed during the most recent reparse, per
+   * flowId. Used by snapshot() to detect external writes (notably the
+   * in-process CLI) that the debounced fs watcher hasn't dispatched yet.
+   * Two files → larger of the two mtimes; missing style.json contributes 0.
+   */
+  const lastSeenMtimes = new Map<string, number>();
   /**
    * Ring buffer of recent self-write content hashes per flow. The fs watcher
    * computes the same hash on its debounced callback and short-circuits when
@@ -379,6 +386,13 @@ export function createWatcher(deps: WatcherDeps): FlowWatcher {
     }
   };
 
+  const combinedMtimeMs = (filePath: string): number => {
+    const stylePath = join(dirname(filePath), 'style.json');
+    const flowMtime = existsSync(filePath) ? statSync(filePath).mtimeMs : 0;
+    const styleMtime = existsSync(stylePath) ? statSync(stylePath).mtimeMs : 0;
+    return Math.max(flowMtime, styleMtime);
+  };
+
   const reparse = (flowId: string): FlowSnapshot | null => {
     const entry = registry.getById(flowId);
     if (!entry) return null;
@@ -393,6 +407,7 @@ export function createWatcher(deps: WatcherDeps): FlowWatcher {
       : { flow: previous?.flow ?? null, valid: false, error: result.error, filePath, parsedAt };
 
     snapshots.set(flowId, next);
+    lastSeenMtimes.set(flowId, combinedMtimeMs(filePath));
 
     // Reconcile the referenced-file watch set: imageNode.path from
     // flow + any file:// targets that resolved cleanly. Schema errors
@@ -481,7 +496,19 @@ export function createWatcher(deps: WatcherDeps): FlowWatcher {
 
   return {
     snapshot(flowId) {
-      return snapshots.get(flowId) ?? null;
+      const current = snapshots.get(flowId) ?? null;
+      if (!current) return null;
+      // Stat-and-reparse guard: when an external process (notably the
+      // in-process CLI) rewrites flow.json or style.json, the fs.watch
+      // callback is debounced by ~100ms — long enough for a fast HTTP read
+      // to hit a stale snapshot. Catching it here closes the gap with one
+      // stat() per read.
+      const seen = lastSeenMtimes.get(flowId);
+      const now = combinedMtimeMs(current.filePath);
+      if (seen !== undefined && now > seen) {
+        return reparse(flowId) ?? current;
+      }
+      return current;
     },
     watch(flowId) {
       startWatch(flowId);
@@ -494,6 +521,7 @@ export function createWatcher(deps: WatcherDeps): FlowWatcher {
       closeFileWatchers(h);
       handles.delete(flowId);
       snapshots.delete(flowId);
+      lastSeenMtimes.delete(flowId);
     },
     watchAll() {
       for (const entry of registry.list()) startWatch(entry.id);
@@ -506,11 +534,13 @@ export function createWatcher(deps: WatcherDeps): FlowWatcher {
       }
       handles.clear();
       snapshots.clear();
+      lastSeenMtimes.clear();
       writtenHashes.clear();
     },
     reparse,
     notifyWritten(flowId, snap, flowContent, styleContent) {
       snapshots.set(flowId, snap);
+      lastSeenMtimes.set(flowId, combinedMtimeMs(snap.filePath));
       rememberWrittenHash(flowId, sha256Hex(combinedContent(flowContent, styleContent)));
       broadcastReload(flowId, snap);
     },