@tuongaz/seeflow 0.1.3

package/src/server.ts

@@ -0,0 +1,211 @@
+import { existsSync } from 'node:fs';
+import { resolve as resolvePath } from 'node:path';
+import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
+import { Hono } from 'hono';
+import { serveStatic } from 'hono/bun';
+import { type ProxyFacade, createApi } from './api.ts';
+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 Registry, createRegistry } from './registry.ts';
+import type { Spawner } from './shellout.ts';
+import { type StatusRunner, createStatusRunner } from './status-runner.ts';
+import { type DemoWatcher, createWatcher } from './watcher.ts';
+
+/** Absolute path to the vendored runtime asset directory. Resolved relative
+ *  to this source file so the path is stable whether the studio runs from
+ *  `apps/studio/` in dev or from `node_modules/@tuongaz/seeflow/` when the
+ *  package is installed as a dependency. */
+export const RUNTIME_ASSETS_DIR = resolvePath(import.meta.dir, '../public/runtime');
+
+export type AppMode = 'dev' | 'prod';
+
+export interface CreateAppOptions {
+  mode?: AppMode;
+  /** Where the Vite dev server is reachable in dev mode. */
+  viteDevUrl?: string;
+  /** Filesystem root for the built web bundle in prod mode. */
+  staticRoot?: string;
+  /** Inject a registry; defaults to one persisted at ~/.seeflow/registry.json. */
+  registry?: Registry;
+  /** Inject an event bus; defaults to a fresh in-memory bus. */
+  events?: EventBus;
+  /** Inject a watcher; defaults to one wired to the registry + event bus. */
+  watcher?: DemoWatcher;
+  /** Skip starting fs.watch on registered demos. Useful for tests. */
+  watchAllOnBoot?: boolean;
+  /** Disable file watching entirely (no fs handles leaked). Useful for tests. */
+  disableWatcher?: boolean;
+  /** Inject a shellout spawner; tests use this to avoid launching $EDITOR/Finder. */
+  spawner?: Spawner;
+  /** Override the host platform for tests covering darwin/win32/linux branches. */
+  platform?: NodeJS.Platform;
+  /** Inject a StatusRunner; defaults to one wired to the registry + event bus. */
+  statusRunner?: StatusRunner;
+  /** Inject a ProcessSpawner for the play-action script; defaults to letting
+   *  proxy.ts pick `defaultProcessSpawner`. Tests use this to drive runPlay
+   *  with an in-memory fake spawner. */
+  processSpawner?: ProcessSpawner;
+  /** Inject a ProxyFacade — tests use this to short-circuit runPlay /
+   *  runReset / stopAllPlays and assert call order. */
+  proxy?: ProxyFacade;
+  /** Override base directory for new projects. Defaults to ~/.seeflow. Tests inject a tmp dir. */
+  projectBaseDir?: string;
+}
+
+const DEFAULT_VITE_DEV_URL = 'http://localhost:5173';
+const DEFAULT_STATIC_ROOT = resolvePath(import.meta.dir, '../dist/web');
+
+const inferMode = (): AppMode => {
+  if (process.env.NODE_ENV === 'production') return 'prod';
+  if (process.env.NODE_ENV === 'development') return 'dev';
+  // No NODE_ENV: use prod if the built web bundle exists, dev otherwise.
+  const distIndex = resolvePath(import.meta.dir, '../dist/web/index.html');
+  return existsSync(distIndex) ? 'prod' : 'dev';
+};
+
+export function createApp(options: CreateAppOptions = {}): Hono {
+  const mode = options.mode ?? inferMode();
+  const viteDevUrl = options.viteDevUrl ?? DEFAULT_VITE_DEV_URL;
+  const staticRoot = options.staticRoot ?? DEFAULT_STATIC_ROOT;
+  const registry = options.registry ?? createRegistry();
+  const events = options.events ?? createEventBus();
+  const watcher = options.disableWatcher
+    ? undefined
+    : (options.watcher ?? createWatcher({ registry, events }));
+  const statusRunner =
+    options.statusRunner ??
+    createStatusRunner({ registry, events, spawner: defaultProcessSpawner });
+
+  if (watcher && (options.watchAllOnBoot ?? true)) {
+    watcher.watchAll();
+  }
+
+  const app = new Hono();
+
+  app.get('/health', (c) => c.json({ ok: true }));
+
+  // Vendored runtime assets (e.g. Tailwind Play CDN for htmlNode). Served
+  // identically in dev and prod so they don't depend on the web bundle.
+  // The `{[A-Za-z0-9._-]+}` regex constrains :file to a single safe segment,
+  // making traversal (`..`, `/`) impossible by construction.
+  app.get('/runtime/:file{[A-Za-z0-9._-]+}', async (c) => {
+    const file = c.req.param('file');
+    const abs = resolvePath(RUNTIME_ASSETS_DIR, file);
+    const f = Bun.file(abs);
+    if (!(await f.exists())) return c.notFound();
+    return new Response(f.stream(), {
+      headers: {
+        'content-type': f.type || 'application/octet-stream',
+        'cache-control': 'public, max-age=31536000, immutable',
+      },
+    });
+  });
+
+  app.route('/demo', createDemoRouter(events));
+
+  app.route(
+    '/api',
+    createApi({
+      registry,
+      events,
+      watcher,
+      spawner: options.spawner,
+      platform: options.platform,
+      statusRunner,
+      processSpawner: options.processSpawner,
+      proxy: options.proxy,
+      projectBaseDir: options.projectBaseDir,
+    }),
+  );
+
+  // Per-request stateless MCP transport: every /mcp call builds a fresh
+  // Server + Streamable HTTP transport pair. The transport's stateless mode
+  // forbids reuse across requests (it would collide JSON-RPC ids between
+  // clients), and a per-request server is cheap since registry/watcher are
+  // injected references. `enableJsonResponse: true` keeps responses as plain
+  // JSON instead of SSE — simpler for non-streaming clients and what the
+  // stdio shim forwards from the MCP Client.
+  app.all('/mcp', async (c) => {
+    const transport = new WebStandardStreamableHTTPServerTransport({
+      sessionIdGenerator: undefined,
+      enableJsonResponse: true,
+    });
+    const mcpServer = createMcpServer({
+      registry,
+      watcher,
+      projectBaseDir: options.projectBaseDir,
+    });
+    await mcpServer.connect(transport);
+    try {
+      return await transport.handleRequest(c.req.raw);
+    } finally {
+      await mcpServer.close().catch(() => undefined);
+    }
+  });
+
+  if (mode === 'dev') {
+    app.all('*', async (c) => {
+      const url = new URL(c.req.url);
+      if (url.pathname.startsWith('/api/') || url.pathname === '/mcp') return c.notFound();
+
+      const target = `${viteDevUrl}${url.pathname}${url.search}`;
+      try {
+        const upstream = await fetch(target, {
+          method: c.req.method,
+          headers: c.req.raw.headers,
+          body: c.req.method === 'GET' || c.req.method === 'HEAD' ? undefined : c.req.raw.body,
+          redirect: 'manual',
+        });
+        return new Response(upstream.body, {
+          status: upstream.status,
+          statusText: upstream.statusText,
+          headers: upstream.headers,
+        });
+      } catch (_err) {
+        return c.text(
+          `SeeFlow dev proxy could not reach Vite at ${viteDevUrl}.\nMake sure \`bun run dev\` is running so Vite is up.\n`,
+          502,
+        );
+      }
+    });
+  } else {
+    app.use('/*', serveStatic({ root: staticRoot }));
+    app.get('*', serveStatic({ root: staticRoot, path: 'index.html' }));
+  }
+
+  return app;
+}
+
+export interface ServeOptions extends CreateAppOptions {
+  port?: number;
+  hostname?: string;
+}
+
+export function serve(options: ServeOptions = {}) {
+  const port = options.port ?? 4321;
+  const hostname = options.hostname ?? '0.0.0.0';
+  const app = createApp(options);
+  return Bun.serve({ port, hostname, fetch: app.fetch });
+}
+
+if (import.meta.main) {
+  const registry = createRegistry();
+  const events = createEventBus();
+  const statusRunner = createStatusRunner({ registry, events, spawner: defaultProcessSpawner });
+  const server = serve({ registry, events, statusRunner });
+  const shutdown = async () => {
+    try {
+      await statusRunner.stopAll();
+    } catch (err) {
+      console.warn(
+        `[server] statusRunner.stopAll() failed: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+    process.exit(0);
+  };
+  process.once('SIGINT', () => void shutdown());
+  process.once('SIGTERM', () => void shutdown());
+  console.log(`SeeFlow Studio listening on http://${server.hostname}:${server.port}`);
+}

package/src/shellout.ts

@@ -0,0 +1,30 @@
+/**
+ * Fire-and-forget shellout used by the `/files/open` and `/files/reveal`
+ * endpoints. The spawner is injectable so tests can verify the exact command
+ * and arguments without actually launching $EDITOR or Finder.
+ *
+ * The default implementation uses `Bun.spawn` in detached fire-and-forget
+ * mode: spawn-time failures (ENOENT, EACCES) throw synchronously from
+ * `Bun.spawn` and we surface them as `{ ok: false, error }`. On success we
+ * unref the child so the studio process doesn't wait for it to exit.
+ */
+
+export interface ShellRunResult {
+  ok: boolean;
+  error?: string;
+}
+
+export type Spawner = (cmd: string, args: string[]) => Promise<ShellRunResult>;
+
+export const defaultSpawner: Spawner = async (cmd, args) => {
+  try {
+    const proc = Bun.spawn({
+      cmd: [cmd, ...args],
+      stdio: ['ignore', 'ignore', 'ignore'],
+    });
+    proc.unref();
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+};

package/src/status-runner.ts

@@ -0,0 +1,374 @@
+/**
+ * StatusRunner: spawns the long-running `statusAction` scripts declared on a
+ * demo's nodes, kills the previous batch on respawn, and streams each script's
+ * 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
+ *     parallel) → re-read demo from disk → spawn each `statusAction` node in
+ *     parallel.
+ *   stop(demoId) / 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`,
+ * on failure console.warn. A `maxLifetimeMs` timer kills the process and emits a
+ * final error report. An unsolicited exit with code !== 0 emits a final error
+ * report. A solicited kill (restart / stop / maxLifetimeMs) is silent on exit.
+ *
+ * Defense-in-depth on scriptPath mirrors proxy.ts:`resolveScript` — realpath
+ * the resolved file against `<repoPath>/.seeflow/` so a symlink-escape can't
+ * spawn arbitrary scripts outside the project.
+ */
+
+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';
+
+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 all status scripts for every demo. Used at studio shutdown. */
+  stopAll(): Promise<void>;
+}
+
+export interface CreateStatusRunnerOptions {
+  registry: Registry;
+  events: EventBus;
+  /** Injectable for tests; defaults to `defaultProcessSpawner`. */
+  spawner?: ProcessSpawner;
+}
+
+const DEFAULT_MAX_LIFETIME_MS = 3_600_000;
+const SIGKILL_GRACE_MS = 2_000;
+const MALFORMED_LINE_TRUNCATE = 200;
+const SCRIPT_PATH_ESCAPE = 'scriptPath escapes project root';
+
+interface TrackedHandle {
+  nodeId: string;
+  handle: SpawnHandle;
+  lifetimeTimer: ReturnType<typeof setTimeout> | undefined;
+  /** True when our own code initiated the kill (restart / stop / lifetime). */
+  expectingKill: boolean;
+  /** Resolves once stdout drain + stderr drain + exit handler have all run. */
+  lifecycle: Promise<void>;
+}
+
+type ResolvedScript = { ok: true; absPath: string } | { ok: false };
+
+function resolveScript(repoPath: string, scriptPath: string): ResolvedScript {
+  const seeflowRoot = join(repoPath, '.seeflow');
+  let realRoot: string;
+  try {
+    realRoot = realpathSync(seeflowRoot);
+  } catch {
+    return { ok: false };
+  }
+  const target = resolve(seeflowRoot, scriptPath);
+  let realTarget: string;
+  try {
+    realTarget = realpathSync(target);
+  } catch {
+    return { ok: false };
+  }
+  const rootWithSep = realRoot.endsWith(sep) ? realRoot : realRoot + sep;
+  if (realTarget !== realRoot && !realTarget.startsWith(rootWithSep)) {
+    return { ok: false };
+  }
+  return { ok: true, absPath: realTarget };
+}
+
+function buildChildEnv(extra: Record<string, string>): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const [k, v] of Object.entries(process.env)) {
+    if (typeof v === 'string') env[k] = v;
+  }
+  return { ...env, ...extra };
+}
+
+async function killAndWait(handle: SpawnHandle): Promise<void> {
+  handle.kill('SIGTERM');
+  let graceTimer: ReturnType<typeof setTimeout> | undefined;
+  const gracePromise = new Promise<'grace'>((res) => {
+    graceTimer = setTimeout(() => res('grace'), SIGKILL_GRACE_MS);
+  });
+  const winner = await Promise.race([handle.exited.then(() => 'exited' as const), gracePromise]);
+  if (graceTimer) clearTimeout(graceTimer);
+  if (winner === 'grace') {
+    handle.kill('SIGKILL');
+    await handle.exited;
+  }
+}
+
+// Read newline-delimited UTF-8 from `stream`, invoke `onLine` for each
+// non-empty line (CRLF tolerated). Returns when the stream ends — including
+// any trailing chunk that has no final newline.
+async function streamLines(
+  stream: ReadableStream<Uint8Array>,
+  onLine: (line: string) => void,
+): Promise<void> {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let buf = '';
+  try {
+    while (true) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      buf += decoder.decode(value, { stream: true });
+      while (true) {
+        const nl = buf.indexOf('\n');
+        if (nl === -1) break;
+        const raw = buf.slice(0, nl);
+        buf = buf.slice(nl + 1);
+        const line = raw.endsWith('\r') ? raw.slice(0, -1) : raw;
+        if (line.length > 0) onLine(line);
+      }
+    }
+    buf += decoder.decode();
+    const tail = buf.endsWith('\r') ? buf.slice(0, -1) : buf;
+    if (tail.length > 0) onLine(tail);
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+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);
+  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;
+  }
+}
+
+interface StatusNode {
+  nodeId: string;
+  action: StatusAction;
+}
+
+function collectStatusNodes(demo: Demo): StatusNode[] {
+  const out: StatusNode[] = [];
+  for (const node of demo.nodes) {
+    if (node.type !== 'playNode' && node.type !== 'stateNode') continue;
+    const action = node.data.statusAction;
+    if (!action) continue;
+    out.push({ nodeId: node.id, action });
+  }
+  return out;
+}
+
+export function createStatusRunner(options: CreateStatusRunnerOptions): StatusRunner {
+  const { registry, events } = options;
+  const spawner = options.spawner ?? defaultProcessSpawner;
+  const trackedByDemo = new Map<string, TrackedHandle[]>();
+
+  function spawnStatusScript(
+    demoId: string,
+    repoPath: string,
+    sn: StatusNode,
+  ): TrackedHandle | undefined {
+    const { nodeId, action } = sn;
+
+    const resolved = resolveScript(repoPath, action.scriptPath);
+    if (!resolved.ok) {
+      events.broadcast({
+        type: 'node:status',
+        demoId,
+        payload: {
+          nodeId,
+          state: 'error',
+          summary: SCRIPT_PATH_ESCAPE,
+          ts: Date.now(),
+        },
+      });
+      return undefined;
+    }
+
+    const runId = crypto.randomUUID();
+    const env = buildChildEnv({
+      SEEFLOW_DEMO_ID: demoId,
+      SEEFLOW_NODE_ID: nodeId,
+      SEEFLOW_RUN_ID: runId,
+    });
+
+    let handle: SpawnHandle;
+    try {
+      handle = spawner.spawn({
+        cmd: [action.interpreter, ...(action.args ?? []), resolved.absPath],
+        cwd: repoPath,
+        env,
+        stdin: 'ignore',
+      });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      events.broadcast({
+        type: 'node:status',
+        demoId,
+        payload: {
+          nodeId,
+          state: 'error',
+          summary: 'status script failed to spawn',
+          detail: message,
+          ts: Date.now(),
+        },
+      });
+      return undefined;
+    }
+
+    const tracked: TrackedHandle = {
+      nodeId,
+      handle,
+      lifetimeTimer: undefined,
+      expectingKill: false,
+      // Assigned below; allSettled ensures lifecycle resolves regardless of
+      // which leg errored. Initialized eagerly so the struct is fully built.
+      lifecycle: Promise.resolve(),
+    };
+
+    const maxLifetimeMs = action.maxLifetimeMs ?? DEFAULT_MAX_LIFETIME_MS;
+    tracked.lifetimeTimer = setTimeout(() => {
+      // We're killing it; suppress the unsolicited-exit error branch.
+      tracked.expectingKill = true;
+      events.broadcast({
+        type: 'node:status',
+        demoId,
+        payload: {
+          nodeId,
+          state: 'error',
+          summary: 'status script exceeded maxLifetimeMs',
+          ts: Date.now(),
+        },
+      });
+      void killAndWait(handle);
+    }, maxLifetimeMs);
+
+    const stdoutDrain = streamLines(handle.stdout, (rawLine) => {
+      const trimmed = rawLine.trim();
+      if (trimmed.length === 0) return;
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(trimmed);
+      } 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})`,
+        );
+        return;
+      }
+      const result = StatusReportSchema.safeParse(parsed);
+      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})`,
+        );
+        return;
+      }
+      const report = result.data;
+      events.broadcast({
+        type: 'node:status',
+        demoId,
+        payload: {
+          nodeId,
+          state: report.state,
+          summary: report.summary,
+          detail: report.detail,
+          data: report.data,
+          ts: report.ts ?? Date.now(),
+        },
+      });
+    });
+
+    const stderrDrain = new Response(handle.stderr).text();
+
+    const onExit = handle.exited.then((code) => {
+      if (tracked.lifetimeTimer) {
+        clearTimeout(tracked.lifetimeTimer);
+        tracked.lifetimeTimer = undefined;
+      }
+      if (tracked.expectingKill) return;
+      if (code !== 0) {
+        events.broadcast({
+          type: 'node:status',
+          demoId,
+          payload: {
+            nodeId,
+            state: 'error',
+            summary: `status script exited with code ${code}`,
+            ts: Date.now(),
+          },
+        });
+      }
+    });
+
+    tracked.lifecycle = Promise.allSettled([stdoutDrain, stderrDrain, onExit]).then(() => {
+      /* swallow — lifecycle is observed only for await-on-stop */
+    });
+
+    return tracked;
+  }
+
+  async function killBatch(existing: TrackedHandle[]): Promise<void> {
+    for (const t of existing) {
+      t.expectingKill = true;
+      if (t.lifetimeTimer) {
+        clearTimeout(t.lifetimeTimer);
+        t.lifetimeTimer = undefined;
+      }
+    }
+    await Promise.all(
+      existing.map(async (t) => {
+        await killAndWait(t.handle);
+        await t.lifecycle;
+      }),
+    );
+  }
+
+  async function restart(demoId: string): Promise<void> {
+    const existing = trackedByDemo.get(demoId);
+    if (existing) {
+      trackedByDemo.delete(demoId);
+      await killBatch(existing);
+    }
+
+    const entry = registry.getById(demoId);
+    if (!entry) return;
+    const demo = await loadDemo(entry);
+    if (!demo) return;
+    const statusNodes = collectStatusNodes(demo);
+    if (statusNodes.length === 0) return;
+
+    const batch: TrackedHandle[] = [];
+    for (const sn of statusNodes) {
+      const t = spawnStatusScript(demoId, entry.repoPath, sn);
+      if (t) batch.push(t);
+    }
+    if (batch.length > 0) trackedByDemo.set(demoId, batch);
+  }
+
+  async function stop(demoId: string): Promise<void> {
+    const existing = trackedByDemo.get(demoId);
+    if (!existing) return;
+    trackedByDemo.delete(demoId);
+    await killBatch(existing);
+  }
+
+  async function stopAll(): Promise<void> {
+    const demoIds = [...trackedByDemo.keys()];
+    await Promise.all(demoIds.map((id) => stop(id)));
+  }
+
+  return { restart, stop, stopAll };
+}