@tuongaz/seeflow 0.1.3

package/src/process-spawner.ts

@@ -0,0 +1,75 @@
+/**
+ * Process spawn abstraction. `runPlay` (US-003) and the StatusRunner (US-004)
+ * depend on this interface so tests can drive them with an in-memory fake
+ * instead of actually spawning child processes.
+ *
+ * The default implementation wraps `Bun.spawn`. Bun exposes stdin as a
+ * `FileSink`; we wrap it in a standard `WritableStream<Uint8Array>` so
+ * consumers can write a chunk and `close()` it through the same surface used
+ * by tests with a fake spawner.
+ */
+
+export interface SpawnOptions {
+  cmd: string[];
+  cwd: string;
+  env: Record<string, string>;
+  stdin: 'pipe' | 'ignore';
+}
+
+export interface SpawnHandle {
+  pid: number;
+  stdout: ReadableStream<Uint8Array>;
+  stderr: ReadableStream<Uint8Array>;
+  /** Present iff `SpawnOptions.stdin === 'pipe'`. */
+  stdin?: WritableStream<Uint8Array>;
+  /** Resolves with the child's exit code (143 for SIGTERM, 137 for SIGKILL). */
+  exited: Promise<number>;
+  kill(signal: 'SIGTERM' | 'SIGKILL'): void;
+}
+
+export interface ProcessSpawner {
+  spawn(opts: SpawnOptions): SpawnHandle;
+}
+
+export const defaultProcessSpawner: ProcessSpawner = {
+  spawn(opts) {
+    const child = Bun.spawn({
+      cmd: opts.cmd,
+      cwd: opts.cwd,
+      env: opts.env,
+      stdin: opts.stdin === 'pipe' ? 'pipe' : 'ignore',
+      stdout: 'pipe',
+      stderr: 'pipe',
+    });
+
+    let stdinStream: WritableStream<Uint8Array> | undefined;
+    if (opts.stdin === 'pipe') {
+      const sink = child.stdin;
+      if (!sink) {
+        throw new Error('Bun.spawn returned no stdin sink despite stdin: pipe');
+      }
+      stdinStream = new WritableStream<Uint8Array>({
+        write(chunk) {
+          sink.write(chunk);
+        },
+        async close() {
+          await sink.end();
+        },
+        async abort() {
+          await sink.end();
+        },
+      });
+    }
+
+    return {
+      pid: child.pid,
+      stdout: child.stdout as ReadableStream<Uint8Array>,
+      stderr: child.stderr as ReadableStream<Uint8Array>,
+      stdin: stdinStream,
+      exited: child.exited,
+      kill(signal) {
+        child.kill(signal);
+      },
+    };
+  },
+};

package/src/proxy.ts

@@ -0,0 +1,393 @@
+/**
+ * Play proxy: spawns the script declared on a node's `playAction` and
+ * broadcasts `node:running` / `node:done` / `node:error` SSE events around the
+ * spawn so the canvas can animate. The interpreter, args, scriptPath, optional
+ * stdin input, and timeoutMs come from the validated `PlayAction` (see
+ * schema.ts). Process spawning goes through the `ProcessSpawner` seam from
+ * US-002 so tests inject an in-memory fake.
+ *
+ * Defense-in-depth on scriptPath: schema.ts already rejects absolute paths
+ * and `..` traversal textually. Here we additionally realpath-resolve the
+ * script under `<cwd>/.seeflow/` and reject anything that escapes that root —
+ * symlink-escape defense in line with `resolveProjectFile` in api.ts.
+ */
+
+import { realpathSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+import type { EventBus } from './events.ts';
+import { type ProcessSpawner, type SpawnHandle, defaultProcessSpawner } from './process-spawner.ts';
+import type { PlayAction, ResetAction } from './schema.ts';
+
+export interface PlayResult {
+  /** Correlates this run across SSE events + the synchronous response. */
+  runId: string;
+  /** Synthetic status: 200 when the script exited 0, undefined otherwise. */
+  status?: number;
+  /** Parsed JSON stdout when valid JSON, else the raw stdout string. */
+  body?: unknown;
+  /** Spawn-level error (path escape, ENOENT, exit !== 0, timeout, …). */
+  error?: string;
+}
+
+export interface RunPlayOptions {
+  events: EventBus;
+  demoId: string;
+  nodeId: string;
+  /** Project root (`<repoPath>`). Script resolves under `<cwd>/.seeflow/`. */
+  cwd: string;
+  action: PlayAction;
+  /** Injectable for tests; defaults to `defaultProcessSpawner`. */
+  spawner?: ProcessSpawner;
+}
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+const SIGKILL_GRACE_MS = 2_000;
+const STDERR_TRUNCATE = 500;
+const SCRIPT_PATH_ESCAPE = 'scriptPath escapes project root';
+
+type Resolved = { ok: true; absPath: string } | { ok: false };
+
+// Resolve `<cwd>/.seeflow/<scriptPath>` and verify via realpath it stays inside
+// the `.seeflow` root. Mirrors `resolveProjectFile` in api.ts.
+function resolveScript(cwd: string, scriptPath: string): Resolved {
+  const seeflowRoot = join(cwd, '.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 };
+}
+
+// Copy `process.env` into a string-only record, then layer the per-run extras.
+// Bun.spawn's env contract is `Record<string, string>` so the undefineds that
+// `process.env` advertises in its type must be filtered out first.
+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 };
+}
+
+function lastNonEmptyLine(s: string): string {
+  const lines = s.split(/\r?\n/);
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i]?.trim();
+    if (line) return line;
+  }
+  return '';
+}
+
+async function writeStdinPayload(handle: SpawnHandle, input: unknown): Promise<void> {
+  if (!handle.stdin) return;
+  const writer = handle.stdin.getWriter();
+  try {
+    await writer.write(new TextEncoder().encode(JSON.stringify(input)));
+  } finally {
+    await writer.close().catch(() => {
+      /* stdin already closed by child — not fatal */
+    });
+  }
+}
+
+// Live play-script handles indexed by demoId. Populated by runPlay() on spawn;
+// entries are removed when each handle's `exited` promise resolves (success
+// AND error paths). `stopAllPlays(demoId)` consults this map to terminate
+// every in-flight play for a demo on /reset.
+const livePlayHandles = new Map<string, Set<SpawnHandle>>();
+
+function registerLiveHandle(demoId: string, handle: SpawnHandle): void {
+  let set = livePlayHandles.get(demoId);
+  if (!set) {
+    set = new Set();
+    livePlayHandles.set(demoId, set);
+  }
+  set.add(handle);
+  handle.exited.finally(() => {
+    const current = livePlayHandles.get(demoId);
+    if (!current) return;
+    current.delete(handle);
+    if (current.size === 0) livePlayHandles.delete(demoId);
+  });
+}
+
+async function killWithGrace(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;
+  }
+}
+
+// Kill every live play-script for `demoId` (SIGTERM → 2s grace → SIGKILL in
+// parallel) and wait for each to exit. Idempotent on an unknown demoId. The
+// map is keyed by demoId so a stop on demo A never touches demo B.
+export async function stopAllPlays(demoId: string): Promise<void> {
+  const set = livePlayHandles.get(demoId);
+  if (!set || set.size === 0) return;
+  const handles = [...set];
+  // Clear eagerly so a parallel runPlay can't double-count an entry we're
+  // about to await on. The exited.finally() will no-op the second delete.
+  livePlayHandles.delete(demoId);
+  await Promise.all(handles.map((h) => killWithGrace(h)));
+}
+
+export async function runPlay(options: RunPlayOptions): Promise<PlayResult> {
+  const { events, demoId, nodeId, cwd, action } = options;
+  const spawner = options.spawner ?? defaultProcessSpawner;
+  const runId = crypto.randomUUID();
+
+  const resolved = resolveScript(cwd, action.scriptPath);
+  if (!resolved.ok) {
+    events.broadcast({
+      type: 'node:error',
+      demoId,
+      payload: { nodeId, runId, message: SCRIPT_PATH_ESCAPE },
+    });
+    return { runId, error: SCRIPT_PATH_ESCAPE };
+  }
+
+  events.broadcast({
+    type: 'node:running',
+    demoId,
+    payload: {
+      nodeId,
+      runId,
+      interpreter: action.interpreter,
+      scriptPath: action.scriptPath,
+    },
+  });
+
+  const wantsStdin = action.input !== undefined;
+  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,
+      env,
+      stdin: wantsStdin ? 'pipe' : 'ignore',
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    events.broadcast({
+      type: 'node:error',
+      demoId,
+      payload: { nodeId, runId, message },
+    });
+    return { runId, error: message };
+  }
+
+  registerLiveHandle(demoId, handle);
+
+  // Drain stdout AND stderr CONCURRENTLY with the process running so OS pipe
+  // buffers (~64 KB) don't fill up and deadlock the child.
+  const stdoutPromise = new Response(handle.stdout).text();
+  const stderrPromise = new Response(handle.stderr).text();
+
+  // Write stdin and close BEFORE awaiting exit (otherwise a child blocked on
+  // `read(stdin)` and a parent blocked on `exited` deadlock each other).
+  if (wantsStdin) {
+    await writeStdinPayload(handle, action.input);
+  }
+
+  const timeoutMs = action.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeoutPromise = new Promise<'timeout'>((res) => {
+    timer = setTimeout(() => res('timeout'), timeoutMs);
+  });
+  const exitPromise = handle.exited.then((code) => ({ code }) as const);
+
+  const race = await Promise.race([exitPromise, timeoutPromise]);
+  if (timer) clearTimeout(timer);
+
+  if (race === 'timeout') {
+    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;
+    }
+    // Best-effort drain so consumers don't leak an open ReadableStream.
+    await Promise.allSettled([stdoutPromise, stderrPromise]);
+    const message = `script timed out after ${timeoutMs}ms`;
+    events.broadcast({
+      type: 'node:error',
+      demoId,
+      payload: { nodeId, runId, message },
+    });
+    return { runId, error: message };
+  }
+
+  const code = race.code;
+  const [stdout, stderr] = await Promise.all([stdoutPromise, stderrPromise]);
+
+  if (code === 0) {
+    let body: unknown;
+    try {
+      body = JSON.parse(stdout);
+    } catch {
+      body = stdout;
+    }
+    events.broadcast({
+      type: 'node:done',
+      demoId,
+      payload: { nodeId, runId, status: 200, body },
+    });
+    return { runId, status: 200, body };
+  }
+
+  const lastLine = lastNonEmptyLine(stderr);
+  const truncated = lastLine.slice(0, STDERR_TRUNCATE);
+  const message = truncated.length > 0 ? truncated : `script exited with code ${code}`;
+  events.broadcast({
+    type: 'node:error',
+    demoId,
+    payload: { nodeId, runId, message },
+  });
+  return { runId, error: message };
+}
+
+export interface RunResetOptions {
+  events: EventBus;
+  demoId: string;
+  /** Project root (`<repoPath>`). Script resolves under `<cwd>/.seeflow/`. */
+  cwd: string;
+  action: ResetAction;
+  /** Injectable for tests; defaults to `defaultProcessSpawner`. */
+  spawner?: ProcessSpawner;
+}
+
+export interface ResetResult {
+  ok: boolean;
+  body?: unknown;
+  error?: string;
+}
+
+// Run the demo's one-shot `resetAction` script. Same spawn discipline as
+// runPlay (realpath-guarded scriptPath, concurrent stdout/stderr drain,
+// optional stdin payload, SIGTERM→2s→SIGKILL escalation on timeout) but the
+// lifecycle SSE event is the single `demo:reset` broadcast that mirrors the
+// returned shape. Callers (the /reset endpoint) decide what HTTP status to
+// surface; this returns `{ ok }` plus body/error so the endpoint can map.
+export async function runReset(options: RunResetOptions): Promise<ResetResult> {
+  const { events, demoId, cwd, action } = options;
+  const spawner = options.spawner ?? defaultProcessSpawner;
+
+  const resolved = resolveScript(cwd, action.scriptPath);
+  if (!resolved.ok) {
+    events.broadcast({
+      type: 'demo:reset',
+      demoId,
+      payload: { ok: false, error: SCRIPT_PATH_ESCAPE },
+    });
+    return { ok: false, error: SCRIPT_PATH_ESCAPE };
+  }
+
+  const wantsStdin = action.input !== undefined;
+  const env = buildChildEnv({ SEEFLOW_DEMO_ID: demoId });
+
+  let handle: SpawnHandle;
+  try {
+    handle = spawner.spawn({
+      cmd: [action.interpreter, ...(action.args ?? []), resolved.absPath],
+      cwd,
+      env,
+      stdin: wantsStdin ? 'pipe' : 'ignore',
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    events.broadcast({
+      type: 'demo:reset',
+      demoId,
+      payload: { ok: false, error: message },
+    });
+    return { ok: false, error: message };
+  }
+
+  const stdoutPromise = new Response(handle.stdout).text();
+  const stderrPromise = new Response(handle.stderr).text();
+
+  if (wantsStdin) {
+    await writeStdinPayload(handle, action.input);
+  }
+
+  const timeoutMs = action.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeoutPromise = new Promise<'timeout'>((res) => {
+    timer = setTimeout(() => res('timeout'), timeoutMs);
+  });
+  const exitPromise = handle.exited.then((code) => ({ code }) as const);
+
+  const race = await Promise.race([exitPromise, timeoutPromise]);
+  if (timer) clearTimeout(timer);
+
+  if (race === 'timeout') {
+    await killWithGrace(handle);
+    await Promise.allSettled([stdoutPromise, stderrPromise]);
+    const message = `reset script timed out after ${timeoutMs}ms`;
+    events.broadcast({
+      type: 'demo:reset',
+      demoId,
+      payload: { ok: false, error: message },
+    });
+    return { ok: false, error: message };
+  }
+
+  const code = race.code;
+  const [stdout, stderr] = await Promise.all([stdoutPromise, stderrPromise]);
+
+  if (code === 0) {
+    let body: unknown;
+    try {
+      body = JSON.parse(stdout);
+    } catch {
+      body = stdout;
+    }
+    events.broadcast({
+      type: 'demo:reset',
+      demoId,
+      payload: { ok: true, body },
+    });
+    return { ok: true, body };
+  }
+
+  const lastLine = lastNonEmptyLine(stderr);
+  const truncated = lastLine.slice(0, STDERR_TRUNCATE);
+  const message = truncated.length > 0 ? truncated : `reset script exited with code ${code}`;
+  events.broadcast({
+    type: 'demo:reset',
+    demoId,
+    payload: { ok: false, error: message },
+  });
+  return { ok: false, error: message };
+}

package/src/registry.ts

@@ -0,0 +1,139 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+export interface DemoEntry {
+  id: string;
+  slug: string;
+  name: string;
+  repoPath: string;
+  demoPath: string;
+  lastModified: number;
+  valid: boolean;
+}
+
+export interface RegisterInput {
+  name: string;
+  repoPath: string;
+  demoPath: string;
+  valid?: boolean;
+  lastModified?: number;
+}
+
+export interface Registry {
+  list(): DemoEntry[];
+  getById(id: string): DemoEntry | undefined;
+  getBySlug(slug: string): DemoEntry | undefined;
+  getByRepoPath(repoPath: string): DemoEntry | undefined;
+  getByRepoPathAndDemoPath(repoPath: string, demoPath: string): DemoEntry | undefined;
+  upsert(input: RegisterInput): DemoEntry;
+  remove(id: string): boolean;
+}
+
+export function defaultRegistryPath(): string {
+  return join(homedir(), '.seeflow', 'registry.json');
+}
+
+export function slugify(name: string): string {
+  const slug = name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return slug || 'demo';
+}
+
+export function createRegistry(options: { path?: string } = {}): Registry {
+  const path = options.path ?? defaultRegistryPath();
+  const entries = new Map<string, DemoEntry>();
+
+  if (existsSync(path)) {
+    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'
+          ) {
+            entries.set(e.id, e as DemoEntry);
+          }
+        }
+      }
+    } catch (err) {
+      console.error(`[registry] failed to load ${path}, starting empty:`, err);
+    }
+  }
+
+  const persist = () => {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify([...entries.values()], null, 2));
+  };
+
+  const findByRepoPath = (repoPath: string): DemoEntry | undefined => {
+    for (const e of entries.values()) {
+      if (e.repoPath === repoPath) return e;
+    }
+    return undefined;
+  };
+
+  const findByRepoPathAndDemoPath = (repoPath: string, demoPath: string): DemoEntry | undefined => {
+    for (const e of entries.values()) {
+      if (e.repoPath === repoPath && e.demoPath === demoPath) return e;
+    }
+    return undefined;
+  };
+
+  const uniqueSlug = (base: string): string => {
+    const taken = new Set([...entries.values()].map((e) => e.slug));
+    if (!taken.has(base)) return base;
+    let n = 2;
+    while (taken.has(`${base}-${n}`)) n++;
+    return `${base}-${n}`;
+  };
+
+  return {
+    list: () => [...entries.values()],
+    getById: (id) => entries.get(id),
+    getBySlug: (slug) => [...entries.values()].find((e) => e.slug === slug),
+    getByRepoPath: findByRepoPath,
+    getByRepoPathAndDemoPath: findByRepoPathAndDemoPath,
+    upsert(input) {
+      const lastModified = input.lastModified ?? Date.now();
+      const valid = input.valid ?? true;
+      const existing = findByRepoPathAndDemoPath(input.repoPath, input.demoPath);
+      if (existing) {
+        const updated: DemoEntry = {
+          ...existing,
+          name: input.name,
+          demoPath: input.demoPath,
+          lastModified,
+          valid,
+        };
+        entries.set(existing.id, updated);
+        persist();
+        return updated;
+      }
+      const id = crypto.randomUUID();
+      const slug = uniqueSlug(slugify(input.name));
+      const entry: DemoEntry = {
+        id,
+        slug,
+        name: input.name,
+        repoPath: input.repoPath,
+        demoPath: input.demoPath,
+        lastModified,
+        valid,
+      };
+      entries.set(id, entry);
+      persist();
+      return entry;
+    },
+    remove(id) {
+      const removed = entries.delete(id);
+      if (removed) persist();
+      return removed;
+    },
+  };
+}

package/src/runtime.ts

@@ -0,0 +1,78 @@
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+export interface StudioConfig {
+  port: number;
+  host: string;
+}
+
+export const DEFAULT_CONFIG: StudioConfig = { port: 4321, host: '0.0.0.0' };
+
+export function defaultConfigPath(): string {
+  return join(homedir(), '.seeflow', 'config.json');
+}
+
+export function defaultPidPath(): string {
+  return join(homedir(), '.seeflow', 'seeflow.pid');
+}
+
+export function readConfig(path = defaultConfigPath()): StudioConfig {
+  if (!existsSync(path)) return { ...DEFAULT_CONFIG };
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8')) as Partial<StudioConfig>;
+    return {
+      port: typeof parsed.port === 'number' && parsed.port > 0 ? parsed.port : DEFAULT_CONFIG.port,
+      host:
+        typeof parsed.host === 'string' && parsed.host.length > 0
+          ? parsed.host
+          : DEFAULT_CONFIG.host,
+    };
+  } catch {
+    return { ...DEFAULT_CONFIG };
+  }
+}
+
+export function writeConfig(config: StudioConfig, path = defaultConfigPath()): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(config, null, 2));
+}
+
+export function studioUrl(config: StudioConfig = readConfig()): string {
+  return `http://${config.host}:${config.port}`;
+}
+
+export function writePid(pid: number, path = defaultPidPath()): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, String(pid));
+}
+
+export function readPid(path = defaultPidPath()): number | undefined {
+  if (!existsSync(path)) return undefined;
+  try {
+    const raw = readFileSync(path, 'utf8').trim();
+    const pid = Number(raw);
+    if (!Number.isFinite(pid) || pid <= 0) return undefined;
+    return pid;
+  } catch {
+    return undefined;
+  }
+}
+
+export function clearPid(path = defaultPidPath()): void {
+  if (!existsSync(path)) return;
+  try {
+    unlinkSync(path);
+  } catch {
+    // ignore — best-effort cleanup
+  }
+}
+
+export function isPidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}