@tuongaz/seeflow 0.1.31 → 0.1.40

package/src/cli.ts

@@ -1,11 +1,12 @@
 #!/usr/bin/env bun
-import { cpSync, existsSync } from 'node:fs';
-import { isAbsolute, join, resolve } from 'node:path';
+import { closeSync, cpSync, existsSync, mkdirSync, openSync, readFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { createEventBus } from './events.ts';
 import { seeflowHome } from './paths.ts';
 import { defaultProcessSpawner } from './process-spawner.ts';
 import { type Registry, createRegistry } from './registry.ts';
 import {
+  DEFAULT_CONFIG,
   clearPid,
   defaultPidPath,
   isPidAlive,
@@ -15,13 +16,15 @@ import {
   writeConfig,
   writePid,
 } from './runtime.ts';
-import { ArchitectureSchema, FlowSchema } from './schema.ts';
+import { FlowSchema } from './schema.ts';
 import { serve } from './server.ts';
 import { createStatusRunner } from './status-runner.ts';
 
-const DEFAULT_ARCHITECTURE_PATH = '.seeflow/architecture.json';
+const DEFAULT_FLOW_PATH = '.seeflow/flow.json';
 const HEALTH_TIMEOUT_MS = 10_000;
 const HEALTH_POLL_INTERVAL_MS = 150;
+const STOP_TIMEOUT_MS = 5_000;
+const STOP_POLL_INTERVAL_MS = 100;
 
 const argv = process.argv.slice(2);
 const sub = argv[0];
@@ -37,12 +40,22 @@ const flagValue = (name: string): string | undefined => {
 
 const hasFlag = (name: string): boolean => argv.includes(`--${name}`);
 
-if (!sub || sub === 'help' || sub === '--help' || sub === '-h') {
+const DEBUG = hasFlag('debug') || process.env.SEEFLOW_DEBUG === '1';
+const dbg = (msg: string) => {
+  if (DEBUG) console.error(`[debug] ${msg}`);
+};
+const daemonLogPath = () => join(seeflowHome(), 'seeflow.log');
+
+if (argv.includes('--version') || argv.includes('-v')) {
+  await printVersion();
+} else if (sub === 'help' || sub === '--help' || sub === '-h') {
   printHelp();
-} else if (sub === 'start') {
+} else if (sub === 'version') {
+  await printVersion();
+} else if (!sub || sub === 'start' || sub.startsWith('-')) {
   await runStart();
 } else if (sub === 'stop') {
-  runStop();
+  await runStop();
 } else if (sub === 'register') {
   await runRegister();
 } else if (['unregister', 'list'].includes(sub)) {
@@ -60,29 +73,36 @@ function printHelp() {
 seeflow — local studio for file-defined interactive demos
 
 Usage:
-  npx @tuongaz/seeflow <command> [options]
+  npx -y @tuongaz/seeflow@latest [command] [options]
 
 Commands:
-  start             Start the SeeFlow Studio server (default port 4321)
+  start             Start the SeeFlow Studio server (default port 4321) — default when no command is given
   stop              Stop a background studio instance
   register          Register a demo repo with the running studio
+  version           Print the CLI version
   help              Show this help message
 
+Global options:
+  --version, -v     Print the CLI version and exit
+
 Options (start):
   --port <n>        Listen on port n (default: 4321)
-  --daemon          Start in background and exit
+  --foreground      Run attached to the terminal (default: background)
+  --daemon          Deprecated alias — background is already the default
+  --debug           Verbose logs + pipe daemon output to ~/.seeflow/seeflow.log
 
 Options (register):
   --path <dir>      Path to repo root (default: current directory)
   --flow <file>     Path to flow JSON, relative to repo root
-                    (default: .seeflow/architecture.json)
+                    (default: .seeflow/flow.json)
   --no-start        Fail if studio is not already running
 
 Examples:
-  npx @tuongaz/seeflow start
-  npx @tuongaz/seeflow start --port 8080 --daemon
-  npx @tuongaz/seeflow register --path ./my-app
-  npx @tuongaz/seeflow stop
+  npx -y @tuongaz/seeflow@latest
+  npx -y @tuongaz/seeflow@latest --port 8080
+  npx -y @tuongaz/seeflow@latest start --foreground
+  npx -y @tuongaz/seeflow@latest register --path ./my-app
+  npx -y @tuongaz/seeflow@latest stop
 `.trim(),
   );
 }
@@ -90,13 +110,26 @@ Examples:
 async function runStart() {
   const config = readConfig();
   const portArg = flagValue('port');
-  const port = portArg ? Number(portArg) : config.port;
+  // --port wins; otherwise always fall back to the schema default (not the
+  // last persisted value) so a previous run's port doesn't silently stick.
+  const port = portArg ? Number(portArg) : DEFAULT_CONFIG.port;
   if (!Number.isFinite(port) || port <= 0) {
     console.error(`Invalid --port: ${portArg}`);
     process.exit(1);
   }
 
-  if (hasFlag('daemon')) {
+  // Default to background. `--foreground` (or `--no-daemon`) keeps us attached
+  // to the terminal; `--daemon` is a no-op alias kept for backwards compat. The
+  // SEEFLOW_DAEMON env var marks the spawned child, so it must always run in
+  // the foreground to avoid infinite re-spawning.
+  const isDaemonChild = process.env.SEEFLOW_DAEMON === '1';
+  const wantsForeground = hasFlag('foreground') || hasFlag('no-daemon');
+  dbg(
+    `runStart port=${port} host=${config.host} mode=${
+      isDaemonChild ? 'daemon-child' : wantsForeground ? 'foreground' : 'background'
+    }`,
+  );
+  if (!isDaemonChild && !wantsForeground) {
     await spawnDaemon(port, config.host);
     return;
   }
@@ -140,7 +173,7 @@ async function seedExamples(registry: Registry) {
 
 async function seedExample(registry: Registry, exampleName: string) {
   const destDir = join(seeflowHome(), exampleName);
-  const architecturePath = '.seeflow/architecture.json';
+  const flowPath = '.seeflow/flow.json';
 
   // Always sync from source so that schema changes and example updates are
   // reflected on every startup, even when the dest directory already exists.
@@ -148,9 +181,9 @@ async function seedExample(registry: Registry, exampleName: string) {
   if (!existsSync(srcDir)) return;
   cpSync(srcDir, destDir, { recursive: true });
 
-  if (registry.getByRepoPathAndArchitecturePath(destDir, architecturePath)) return;
+  if (registry.getByRepoPathAndFlowPath(destDir, flowPath)) return;
 
-  const flowFile = join(destDir, architecturePath);
+  const flowFile = join(destDir, flowPath);
   if (!existsSync(flowFile)) return;
 
   let demo: unknown;
@@ -160,15 +193,16 @@ async function seedExample(registry: Registry, exampleName: string) {
     return;
   }
 
-  const parsed = ArchitectureSchema.safeParse(demo);
+  const parsed = FlowSchema.safeParse(demo);
   if (!parsed.success) return;
 
-  registry.upsert({ name: parsed.data.name, repoPath: destDir, architecturePath });
+  registry.upsert({ name: parsed.data.name, repoPath: destDir, flowPath });
   console.log(`Seeded example: ${parsed.data.name} → ${destDir}`);
 }
 
 async function spawnDaemon(port: number, host: string) {
   const url = `http://${host}:${port}`;
+  dbg(`probing existing studio at ${url}/health`);
   if (await healthOk(url)) {
     console.log(`Studio already running at ${url}`);
     return;
@@ -177,25 +211,69 @@ async function spawnDaemon(port: number, host: string) {
   const proc = spawnDetachedStudio(port);
   writePid(proc.pid);
   writeConfig({ port, host });
+  dbg(`spawned daemon pid=${proc.pid}${proc.logPath ? ` log=${proc.logPath}` : ''}`);
 
   if (!(await waitForHealth(url, HEALTH_TIMEOUT_MS))) {
     console.error(`Timed out waiting for studio at ${url}/health`);
+    reportDaemonFailure(proc.logPath);
     process.exit(1);
   }
   console.log(`SeeFlow Studio started in background on ${url} (pid ${proc.pid})`);
+  if (proc.logPath) console.log(`Daemon log: ${proc.logPath}`);
 }
 
-function spawnDetachedStudio(port: number): { pid: number } {
+function spawnDetachedStudio(port: number): { pid: number; logPath?: string } {
+  let stdout: 'ignore' | number = 'ignore';
+  let stderr: 'ignore' | number = 'ignore';
+  let logPath: string | undefined;
+  if (DEBUG) {
+    logPath = daemonLogPath();
+    mkdirSync(dirname(logPath), { recursive: true });
+    const fd = openSync(logPath, 'a');
+    // Bun owns the fd once spawn runs; we close our handle after spawn returns.
+    stdout = fd;
+    stderr = fd;
+  }
+  const cmd = [process.execPath, import.meta.path, 'start', `--port=${port}`];
+  if (DEBUG) cmd.push('--debug');
   const proc = Bun.spawn({
-    cmd: [process.execPath, import.meta.path, 'start', `--port=${port}`],
-    stdio: ['ignore', 'ignore', 'ignore'],
-    env: { ...process.env, SEEFLOW_DAEMON: '1' },
+    cmd,
+    stdio: ['ignore', stdout, stderr],
+    env: {
+      ...process.env,
+      SEEFLOW_DAEMON: '1',
+      ...(DEBUG ? { SEEFLOW_DEBUG: '1' } : {}),
+    },
   });
   proc.unref();
-  return { pid: proc.pid };
+  if (typeof stdout === 'number') closeSync(stdout);
+  return { pid: proc.pid, logPath };
 }
 
-function runStop() {
+function reportDaemonFailure(logPath: string | undefined) {
+  if (!logPath) {
+    console.error('Hint: rerun with --debug to capture the daemon output.');
+    return;
+  }
+  let log: string;
+  try {
+    log = readFileSync(logPath, 'utf8');
+  } catch (err) {
+    console.error(`(could not read ${logPath}: ${err instanceof Error ? err.message : err})`);
+    return;
+  }
+  const tail = log.split('\n').slice(-50).join('\n');
+  console.error(`\nLast lines of ${logPath}:`);
+  console.error(tail || '(log is empty — daemon exited before writing anything)');
+}
+
+async function printVersion() {
+  const pkgPath = join(import.meta.dir, '../package.json');
+  const pkg = (await Bun.file(pkgPath).json()) as { version?: string };
+  console.log(pkg.version ?? 'unknown');
+}
+
+async function runStop() {
   const pid = readPid();
   if (!pid) {
     console.log(`No studio running (no pid file at ${defaultPidPath()}).`);
@@ -206,18 +284,57 @@ function runStop() {
     clearPid();
     return;
   }
+
   try {
     process.kill(pid, 'SIGTERM');
-    console.log(`Sent SIGTERM to studio (pid ${pid}).`);
   } catch (err) {
-    console.error(`Failed to stop pid ${pid}: ${String(err)}`);
+    if (isEsrch(err)) {
+      console.log(`Studio (pid ${pid}) was already gone.`);
+      clearPid();
+      return;
+    }
+    console.error(`Failed to signal pid ${pid}: ${String(err)}`);
+    process.exit(1);
+  }
+
+  if (await waitForExit(pid, STOP_TIMEOUT_MS)) {
+    console.log(`Stopped studio (pid ${pid}).`);
+    clearPid();
+    return;
+  }
+
+  // Still alive after timeout — escalate.
+  try {
+    process.kill(pid, 'SIGKILL');
+  } catch (err) {
+    if (isEsrch(err)) {
+      console.log(`Stopped studio (pid ${pid}).`);
+      clearPid();
+      return;
+    }
+    console.error(`Failed to force-kill pid ${pid}: ${String(err)}`);
     process.exit(1);
   }
+  console.warn(`Force-killed studio (pid ${pid}) after ${STOP_TIMEOUT_MS}ms.`);
+  clearPid();
+}
+
+async function waitForExit(pid: number, timeoutMs: number): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!isPidAlive(pid)) return true;
+    await Bun.sleep(STOP_POLL_INTERVAL_MS);
+  }
+  return !isPidAlive(pid);
+}
+
+function isEsrch(err: unknown): boolean {
+  return typeof err === 'object' && err !== null && (err as { code?: string }).code === 'ESRCH';
 }
 
 async function runRegister() {
   const repoPath = resolve(flagValue('path') ?? '.');
-  const demoPathArg = flagValue('flow') ?? DEFAULT_ARCHITECTURE_PATH;
+  const demoPathArg = flagValue('flow') ?? DEFAULT_FLOW_PATH;
   const noStart = hasFlag('no-start');
   const config = readConfig();
   const overrideUrl = process.env.SEEFLOW_STUDIO_URL?.replace(/\/+$/, '');
@@ -226,7 +343,7 @@ async function runRegister() {
   const fullPath = isAbsolute(demoPathArg) ? demoPathArg : join(repoPath, demoPathArg);
   if (!existsSync(fullPath)) {
     console.error(`No demo file at ${fullPath}`);
-    console.error(`Create ${DEFAULT_ARCHITECTURE_PATH} in your repo, or pass --flow <path>.`);
+    console.error(`Create ${DEFAULT_FLOW_PATH} in your repo, or pass --flow <path>.`);
     process.exit(1);
   }
 
@@ -238,7 +355,7 @@ async function runRegister() {
     process.exit(1);
   }
 
-  const parsed = ArchitectureSchema.safeParse(demo);
+  const parsed = FlowSchema.safeParse(demo);
   if (!parsed.success) {
     console.error(`${fullPath} failed schema validation:`);
     for (const issue of parsed.error.issues) {
@@ -257,7 +374,7 @@ async function runRegister() {
       body: JSON.stringify({
         name: parsed.data.name,
         repoPath,
-        architecturePath: demoPathArg,
+        flowPath: demoPathArg,
       }),
     });
   } catch (err) {
@@ -321,8 +438,12 @@ async function healthOk(url: string): Promise<boolean> {
 
 async function waitForHealth(url: string, timeoutMs: number): Promise<boolean> {
   const deadline = Date.now() + timeoutMs;
+  let probe = 0;
   while (Date.now() < deadline) {
-    if (await healthOk(url)) return true;
+    probe++;
+    const ok = await healthOk(url);
+    dbg(`health probe #${probe} → ${ok ? 'ok' : 'no'} (${url}/health)`);
+    if (ok) return true;
     await Bun.sleep(HEALTH_POLL_INTERVAL_MS);
   }
   return false;

package/src/diagram.ts

@@ -1,6 +1,6 @@
-import dagre from 'dagre';
 import { z } from 'zod';
-import { FlowSchema } from './schema.ts';
+import { type LayoutEdge, type LayoutNode, computeLayout } from './layout.ts';
+import { type FlowNode, ResolvedFlowSchema } from './schema.ts';
 
 // Pure-compute helpers backing the three diagram-pipeline endpoints. No file
 // I/O lives here — the skill writes responses to disk on the user's machine.
@@ -153,7 +153,7 @@ const slugify = (raw: string): string =>
     .replace(/^-+|-+$/g, '')
     .slice(0, 80);
 
-export const assembleDemo = (req: AssembleRequest): AssembleResult => {
+export const assembleDemo = async (req: AssembleRequest): Promise<AssembleResult> => {
   const stats: AssembleStats = {
     nodesIn: req.wiring.nodes.length,
     connectorsIn: req.wiring.connectors.length,
@@ -170,7 +170,7 @@ export const assembleDemo = (req: AssembleRequest): AssembleResult => {
   const nodes = normalizeNodes(req.wiring.nodes, positions, stats);
   const nodeIds = new Set(nodes.map((n) => n.id as string));
   const connectors = normalizeConnectors(req.wiring.connectors, nodeIds, stats);
-  const positionedNodes = autoLayout(nodes, connectors, stats);
+  const positionedNodes = await autoLayout(nodes, connectors, stats);
 
   stats.nodesOut = positionedNodes.length;
   stats.connectorsOut = connectors.length;
@@ -235,89 +235,49 @@ const normalizeConnectors = (
   return [...seen.values()];
 };
 
-// Dagre-based auto-layout — exactly the algorithm the web canvas's "Tidy
-// layout" button runs (apps/web/src/lib/auto-layout.ts), so pressing Tidy on
-// a freshly-assembled demo never reshuffles the diagram.
-//
-//   • Direction: left-to-right (LR) — Actors on the left, data stores on the
-//     right, matching the lifecycle-lane intent of the layout-arranger agent.
-//   • `nodesep` / `ranksep` defaults give connectors a bit of extra length so
-//     edge labels fit and the canvas reads at a glance.
-//   • Sticky / text shape nodes stay pinned to their input position — they
-//     are floating annotations, not part of the flow graph.
-const LAYOUT_NODESEP = 60;
-const LAYOUT_RANKSEP = 140;
-const LAYOUT_DEFAULT_W = 200;
-const LAYOUT_DEFAULT_H = 120;
-
+// ELK-backed auto-layout. Delegates to `computeLayout` in layout.ts, the
+// same engine that backs POST /api/layout and the canvas Tidy button — so
+// pressing Tidy on a freshly-assembled demo doesn't reshuffle the diagram.
+// 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';
 };
 
-const nodeDimensions = (n: Record<string, unknown>): { w: number; h: number } => {
-  const data = (n.data ?? {}) as { width?: number; height?: number; shape?: string };
-  const w =
-    typeof data.width === 'number'
-      ? data.width
-      : n.type === 'shapeNode' && data.shape === 'text'
-        ? 160
-        : LAYOUT_DEFAULT_W;
-  let h = LAYOUT_DEFAULT_H;
-  if (typeof data.height === 'number') h = data.height;
-  else if (n.type === 'shapeNode' && data.shape === 'text') h = 40;
-  else if (n.type === 'shapeNode' && data.shape === 'sticky') h = 180;
-  else if (n.type === 'imageNode') h = 150;
-  return { w, h };
-};
-
-const autoLayout = (
+const autoLayout = async (
   nodes: ReadonlyArray<Record<string, unknown>>,
   connectors: ReadonlyArray<Record<string, unknown>>,
   stats: AssembleStats,
-): Array<Record<string, unknown>> => {
+): Promise<Array<Record<string, unknown>>> => {
   if (nodes.length === 0) return [];
 
   const flowNodes = nodes.filter((n) => !isFloatingAnnotation(n));
-  // A single flow node has no layout to compute — keep its input position so
-  // callers can pin standalone nodes via `layout.positions`.
   if (flowNodes.length <= 1) return [...nodes];
 
-  const g = new dagre.graphlib.Graph({ multigraph: true });
-  g.setGraph({ rankdir: 'LR', nodesep: LAYOUT_NODESEP, ranksep: LAYOUT_RANKSEP });
-  g.setDefaultEdgeLabel(() => ({}));
-
-  const flowIds = new Set<string>();
-  const dims = new Map<string, { w: number; h: number }>();
-  for (const n of flowNodes) {
-    const id = n.id as string;
-    const { w, h } = nodeDimensions(n);
-    g.setNode(id, { width: w, height: h });
-    flowIds.add(id);
-    dims.set(id, { w, h });
-  }
-
-  let edgeCounter = 0;
-  for (const c of connectors) {
-    const s = c.source as string;
-    const t = c.target as string;
-    if (!flowIds.has(s) || !flowIds.has(t) || s === t) continue;
-    // multigraph + unique edge name preserves parallel connectors.
-    g.setEdge(s, t, {}, `e${edgeCounter++}`);
-  }
-
-  dagre.layout(g);
+  const layoutNodes: LayoutNode[] = nodes.map((n) => ({
+    id: n.id as string,
+    type: n.type as FlowNode['type'],
+    data: n.data as LayoutNode['data'],
+  }));
+  const layoutEdges: LayoutEdge[] = connectors
+    .filter((c) => c.source !== c.target)
+    .map((c, idx) => ({
+      id: (c.id as string | undefined) ?? `e${idx}`,
+      source: c.source as string,
+      target: c.target as string,
+    }));
+
+  const result = await computeLayout(layoutNodes, layoutEdges);
 
   const snap = (v: number) => Math.round(v / GRID) * GRID;
   return nodes.map((n) => {
     if (isFloatingAnnotation(n)) return n;
     const id = n.id as string;
-    const laid = g.node(id);
-    const d = dims.get(id);
-    if (!laid || !d) return n;
-    // dagre returns center coords; convert to top-left for React Flow.
-    const snapped = { x: snap(laid.x - d.w / 2), y: snap(laid.y - d.h / 2) };
+    const laid = result.nodes[id]?.position;
+    if (!laid) return n;
+    const snapped = { x: snap(laid.x), y: snap(laid.y) };
     const prev = (n.position as { x: number; y: number } | undefined) ?? { x: 0, y: 0 };
     if (snapped.x !== prev.x || snapped.y !== prev.y) stats.positionsShifted++;
     return { ...n, position: snapped };
@@ -364,7 +324,7 @@ export const validateDemo = (req: ValidateRequest): ValidateReport => {
   const issues: ValidateIssue[] = [];
   const warnings: ValidateIssue[] = [];
 
-  const parsed = FlowSchema.safeParse(req.demo);
+  const parsed = ResolvedFlowSchema.safeParse(req.demo);
   if (!parsed.success) {
     for (const issue of parsed.error.issues) {
       issues.push({