@tuongaz/seeflow 0.1.42 → 0.1.51

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 { type LayoutOptions, computeLayout } from './layout.ts';
 import { mergeFlowAndStyle, splitFlow } from './merge.ts';
 import {
   EXTERNALIZED_NODE_FIELDS,
@@ -281,11 +282,58 @@ export interface CreateProjectSuccess {
 
 export type ListFlowsOutcome = { kind: 'ok'; data: FlowListItem[] };
 
+// Minimal projection for agent/CLI discovery — `description` and `name` come
+// from the live watcher snapshot when available so author edits to flow.json
+// surface immediately; fall back to the registry value at startup before
+// any reparse has happened.
+export interface FlowSummary {
+  id: string;
+  name: string;
+  description?: string;
+}
+
+export type ListFlowsSummaryOutcome = { kind: 'ok'; data: FlowSummary[] };
+
 export type GetFlowOutcome =
   | { kind: 'ok'; data: FlowGetResponse }
   | { kind: 'notFound' }
   | { kind: 'fileNotFound'; path: string };
 
+// Lightweight graph projection — flow + nodes + connectors with file-backed
+// fields (`detail` on every node, `html` on htmlNode) stripped so the
+// caller can navigate the topology without paying for inlined bodies.
+export interface FlowGraphResponse {
+  id: string;
+  slug: string;
+  name: string;
+  description?: string;
+  nodes: Array<Record<string, unknown>>;
+  connectors: Array<Record<string, unknown>>;
+}
+
+export type GetFlowGraphOutcome =
+  | { kind: 'ok'; data: FlowGraphResponse }
+  | { kind: 'notFound' }
+  | { kind: 'fileNotFound'; path: string }
+  | { kind: 'badJson'; detail: string }
+  | { kind: 'badSchema'; issues: ZodIssue[] };
+
+// Single node, content resolved. The node shape mirrors the on-disk Flow
+// node shape (no position / style) with `file://` refs already inlined.
+export interface GetNodeResponse {
+  id: string;
+  flowId: string;
+  node: Record<string, unknown>;
+}
+
+export type GetNodeOutcome =
+  | { kind: 'ok'; data: GetNodeResponse }
+  | { kind: 'notFound' }
+  | { kind: 'fileNotFound'; path: string }
+  | { kind: 'badJson'; detail: string }
+  | { kind: 'badSchema'; issues: ZodIssue[] }
+  | { kind: 'unknownNode' };
+
 export type RegisterFlowOutcome =
   | { kind: 'ok'; data: RegisterFlowSuccess }
   | { kind: 'fileNotFound'; path: string }
@@ -658,13 +706,27 @@ export async function mutateMergedFlow<E extends { kind: string }>(
     return { kind: 'writeFailed', message: err instanceof Error ? err.message : String(err) };
   }
 
-  const snap: FlowSnapshot = {
-    flow: finalParse.data as ResolvedFlow,
-    valid: true,
-    error: null,
-    filePath: flowPath,
-    parsedAt: Date.now(),
-  };
+  // Re-read through readMergedFlow so the snapshot we hand to notifyWritten
+  // carries file://-resolved content (detail.md, view.html, …). The in-memory
+  // `merged` tree above still holds raw `file://<name>` strings — broadcasting
+  // it would clobber the watcher's resolved seed and ship unresolved refs to
+  // every SSE subscriber until the next reparse.
+  const reread = readMergedFlow(flowPath);
+  const snap: FlowSnapshot = reread.valid
+    ? {
+        flow: reread.flow,
+        valid: true,
+        error: null,
+        filePath: flowPath,
+        parsedAt: Date.now(),
+      }
+    : {
+        flow: finalParse.data as ResolvedFlow,
+        valid: true,
+        error: null,
+        filePath: flowPath,
+        parsedAt: Date.now(),
+      };
   return { kind: 'ok', snap, flowContent, styleContent };
 }
 
@@ -762,6 +824,22 @@ export function listDemosImpl(deps: OperationsDeps): ListFlowsOutcome {
   return { kind: 'ok', data };
 }
 
+export function listFlowsSummaryImpl(deps: OperationsDeps): ListFlowsSummaryOutcome {
+  const { registry, watcher } = deps;
+  const data = registry.list().map((e) => {
+    const snap = watcher?.snapshot(e.id) ?? null;
+    const liveFlow = snap?.valid ? snap.flow : null;
+    const item: FlowSummary = {
+      id: e.id,
+      name: liveFlow?.name ?? e.name,
+    };
+    const description = liveFlow?.description ?? e.description;
+    if (description !== undefined) item.description = description;
+    return item;
+  });
+  return { kind: 'ok', data };
+}
+
 export async function getFlowImpl(deps: OperationsDeps, flowId: string): Promise<GetFlowOutcome> {
   const { registry, watcher } = deps;
   const entry = registry.getById(flowId);
@@ -799,6 +877,101 @@ export async function getFlowImpl(deps: OperationsDeps, flowId: string): Promise
   };
 }
 
+// Strip the only file-backed fields that ride on `node.data` today.
+// Keep narrow on purpose — if file-ref.ts ever grows another resolved field,
+// this list must grow with it (covered by the operations.test.ts coverage).
+const FILE_BACKED_NODE_DATA_FIELDS = ['detail', 'html'] as const;
+
+function stripFileBackedFields(node: Record<string, unknown>): Record<string, unknown> {
+  const data = node.data;
+  if (!data || typeof data !== 'object') return node;
+  const stripped: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(data as Record<string, unknown>)) {
+    if ((FILE_BACKED_NODE_DATA_FIELDS as readonly string[]).includes(k)) continue;
+    stripped[k] = v;
+  }
+  return { ...node, data: stripped };
+}
+
+export async function getFlowGraphImpl(
+  deps: OperationsDeps,
+  flowId: string,
+): Promise<GetFlowGraphOutcome> {
+  const entry = deps.registry.getById(flowId);
+  if (!entry) return { kind: 'notFound' };
+
+  const fullPath = resolveFilePath(entry.repoPath, entry.flowPath);
+  if (!existsSync(fullPath)) return { kind: 'fileNotFound', path: fullPath };
+
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(fullPath, 'utf8'));
+  } catch (err) {
+    return { kind: 'badJson', detail: err instanceof Error ? err.message : String(err) };
+  }
+
+  // Parse the on-disk Flow shape directly (no resolveFileRefs, no style.json
+  // merge) so we never read the per-node detail/html files from disk.
+  const parsed = FlowSchema.safeParse(raw);
+  if (!parsed.success) return { kind: 'badSchema', issues: parsed.error.issues };
+
+  const data: FlowGraphResponse = {
+    id: entry.id,
+    slug: entry.slug,
+    name: parsed.data.name,
+    nodes: parsed.data.nodes.map((n) => stripFileBackedFields(n as Record<string, unknown>)),
+    connectors: parsed.data.connectors as Array<Record<string, unknown>>,
+  };
+  if (parsed.data.description !== undefined) data.description = parsed.data.description;
+  return { kind: 'ok', data };
+}
+
+export async function getNodeImpl(
+  deps: OperationsDeps,
+  flowId: string,
+  nodeId: string,
+): Promise<GetNodeOutcome> {
+  const { registry, watcher } = deps;
+  const entry = registry.getById(flowId);
+  if (!entry) return { kind: 'notFound' };
+
+  const fullPath = resolveFilePath(entry.repoPath, entry.flowPath);
+
+  // Prefer a live snapshot (already has file:// refs resolved) so we don't
+  // re-walk the filesystem on every call. Fall back to readMergedFlow for
+  // callers without a watcher (CLI, MCP-only setups).
+  const snap = watcher?.snapshot(flowId) ?? watcher?.reparse(flowId) ?? null;
+  let flow: ResolvedFlow | null = snap?.valid ? snap.flow : null;
+
+  if (!flow) {
+    if (!existsSync(fullPath)) return { kind: 'fileNotFound', path: fullPath };
+    const result = readMergedFlow(fullPath);
+    if (!result.valid || !result.flow) {
+      if (result.error?.startsWith('Invalid JSON')) {
+        return { kind: 'badJson', detail: result.error };
+      }
+      // Schema failed — re-parse to surface ZodIssues.
+      try {
+        const raw = JSON.parse(readFileSync(fullPath, 'utf8'));
+        const parsed = FlowSchema.safeParse(raw);
+        if (!parsed.success) return { kind: 'badSchema', issues: parsed.error.issues };
+      } catch (err) {
+        return { kind: 'badJson', detail: err instanceof Error ? err.message : String(err) };
+      }
+      return { kind: 'badJson', detail: result.error ?? 'unknown error' };
+    }
+    flow = result.flow;
+  }
+
+  const node = flow.nodes.find((n) => n.id === nodeId);
+  if (!node) return { kind: 'unknownNode' };
+
+  return {
+    kind: 'ok',
+    data: { id: nodeId, flowId, node: node as unknown as Record<string, unknown> },
+  };
+}
+
 export async function registerFlowImpl(
   deps: OperationsDeps,
   body: RegisterBody,
@@ -831,6 +1004,7 @@ export async function registerFlowImpl(
   const lastModified = statSync(fullPath).mtimeMs;
   const entry = registry.upsert({
     name: body.name ?? merged.flow.name,
+    description: merged.flow.description,
     repoPath,
     flowPath,
     valid: true,
@@ -1508,3 +1682,163 @@ export function validateImpl(body: ValidateBody): ValidateOutcome {
 
   return issues.length === 0 ? { ok: true } : { ok: false, issues };
 }
+
+// ---------------------------------------------------------------------------
+// applyLayoutImpl — ELK layout for a registered flow. Reads flow.json from
+// the registry-resolved path, validates it, computes layout, writes
+// style.json atomically, and (if a watcher is present) calls notifyWritten so
+// the studio's flow watcher seeds its snapshot and broadcasts flow:reload
+// without echoing the style.json fs event.
+// ---------------------------------------------------------------------------
+
+export type ApplyLayoutOutcome =
+  | { kind: 'ok' }
+  | { kind: 'flowNotFound' }
+  | { kind: 'fileNotFound'; path: string }
+  | { kind: 'badJson'; detail: string }
+  | { kind: 'badSchema'; issues: ValidationIssue[] }
+  | { kind: 'writeFailed'; message: string };
+
+export async function applyLayoutImpl(
+  deps: OperationsDeps,
+  flowId: string,
+  options: LayoutOptions | undefined,
+): Promise<ApplyLayoutOutcome> {
+  const entry = deps.registry.getById(flowId);
+  if (!entry) return { kind: 'flowNotFound' };
+
+  const flowAbs = resolveFilePath(entry.repoPath, entry.flowPath);
+  if (!existsSync(flowAbs)) return { kind: 'fileNotFound', path: flowAbs };
+
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(flowAbs, 'utf8'));
+  } catch (err) {
+    return { kind: 'badJson', detail: err instanceof Error ? err.message : String(err) };
+  }
+
+  const flowParse = FlowSchema.safeParse(raw);
+  if (!flowParse.success) {
+    return {
+      kind: 'badSchema',
+      issues: flowParse.error.issues.map((i) => ({
+        scope: 'flow',
+        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,
+      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) {
+    return { kind: 'writeFailed', message: err instanceof Error ? err.message : String(err) };
+  }
+
+  // Inform the watcher so it broadcasts flow:reload with the new payload and
+  // suppresses the upcoming fs-watcher echo for this style.json write.
+  const snap = deps.watcher?.reparse(flowId);
+  if (deps.watcher && snap) {
+    const flowContent = readFileSync(flowAbs, 'utf8');
+    deps.watcher.notifyWritten(flowId, snap, flowContent, styleContent);
+  }
+
+  return { kind: 'ok' };
+}
+
+// ---------------------------------------------------------------------------
+// createOperations — thin handle that exposes every *Impl as a bound method.
+// Consumers (api.ts, mcp.ts, cli.ts) construct one of these at startup so they
+// don't re-thread `deps` through every call site. No behaviour change — every
+// method delegates to the existing *Impl function.
+// ---------------------------------------------------------------------------
+
+export interface Operations {
+  listFlows(): ReturnType<typeof listDemosImpl>;
+  listFlowsSummary(): ReturnType<typeof listFlowsSummaryImpl>;
+  getFlow(id: string): ReturnType<typeof getFlowImpl>;
+  getFlowGraph(id: string): ReturnType<typeof getFlowGraphImpl>;
+  getNode(flowId: string, nodeId: string): ReturnType<typeof getNodeImpl>;
+  addNode(flowId: string, body: Record<string, unknown>): ReturnType<typeof addNodeImpl>;
+  addNodesBulk(
+    flowId: string,
+    body: Parameters<typeof addNodesBulkImpl>[2],
+  ): ReturnType<typeof addNodesBulkImpl>;
+  patchNode(
+    flowId: string,
+    nodeId: string,
+    body: Parameters<typeof patchNodeImpl>[3],
+  ): ReturnType<typeof patchNodeImpl>;
+  moveNode(
+    flowId: string,
+    nodeId: string,
+    body: Parameters<typeof moveNodeImpl>[3],
+  ): ReturnType<typeof moveNodeImpl>;
+  reorderNode(
+    flowId: string,
+    nodeId: string,
+    body: Parameters<typeof reorderNodeImpl>[3],
+  ): ReturnType<typeof reorderNodeImpl>;
+  deleteNode(flowId: string, nodeId: string): ReturnType<typeof deleteNodeImpl>;
+  addConnector(flowId: string, body: Record<string, unknown>): ReturnType<typeof addConnectorImpl>;
+  addConnectorsBulk(
+    flowId: string,
+    body: Parameters<typeof addConnectorsBulkImpl>[2],
+  ): ReturnType<typeof addConnectorsBulkImpl>;
+  patchConnector(
+    flowId: string,
+    connectorId: string,
+    body: Parameters<typeof patchConnectorImpl>[3],
+  ): ReturnType<typeof patchConnectorImpl>;
+  deleteConnector(flowId: string, connectorId: string): ReturnType<typeof deleteConnectorImpl>;
+  registerFlow(body: Parameters<typeof registerFlowImpl>[1]): ReturnType<typeof registerFlowImpl>;
+  createProject(
+    body: Parameters<typeof createProjectImpl>[1],
+  ): ReturnType<typeof createProjectImpl>;
+  deleteFlow(id: string): ReturnType<typeof deleteFlowImpl>;
+  validate(body: ValidateBody): ReturnType<typeof validateImpl>;
+  applyLayout(
+    flowId: string,
+    options: LayoutOptions | undefined,
+  ): ReturnType<typeof applyLayoutImpl>;
+}
+
+export function createOperations(deps: OperationsDeps): Operations {
+  return {
+    listFlows: () => listDemosImpl(deps),
+    listFlowsSummary: () => listFlowsSummaryImpl(deps),
+    getFlow: (id) => getFlowImpl(deps, id),
+    getFlowGraph: (id) => getFlowGraphImpl(deps, id),
+    getNode: (flowId, nodeId) => getNodeImpl(deps, flowId, nodeId),
+    addNode: (flowId, body) => addNodeImpl(deps, flowId, body),
+    addNodesBulk: (flowId, body) => addNodesBulkImpl(deps, flowId, body),
+    patchNode: (flowId, nodeId, body) => patchNodeImpl(deps, flowId, nodeId, body),
+    moveNode: (flowId, nodeId, body) => moveNodeImpl(deps, flowId, nodeId, body),
+    reorderNode: (flowId, nodeId, body) => reorderNodeImpl(deps, flowId, nodeId, body),
+    deleteNode: (flowId, nodeId) => deleteNodeImpl(deps, flowId, nodeId),
+    addConnector: (flowId, body) => addConnectorImpl(deps, flowId, body),
+    addConnectorsBulk: (flowId, body) => addConnectorsBulkImpl(deps, flowId, body),
+    patchConnector: (flowId, connectorId, body) =>
+      patchConnectorImpl(deps, flowId, connectorId, body),
+    deleteConnector: (flowId, connectorId) => deleteConnectorImpl(deps, flowId, connectorId),
+    registerFlow: (body) => registerFlowImpl(deps, body),
+    createProject: (body) => createProjectImpl(deps, body),
+    deleteFlow: (id) => deleteFlowImpl(deps, id),
+    validate: (body) => validateImpl(body),
+    applyLayout: (flowId, options) => applyLayoutImpl(deps, flowId, options),
+  };
+}

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;
+    },
+  };
+}