@tuongaz/seeflow 0.1.101 → 0.1.103

package/src/api.ts

@@ -47,6 +47,7 @@ import {
 } from './schema-catalog.ts';
 import type { ComponentAction, SeeflowManifest } from './schema.ts';
 import { FlowIdPattern, FlowSchema, ResolvedFlowSchema } from './schema.ts';
+import type { AttributionEvent, ShareController, ShareState } from './share.ts';
 import { type Spawner, defaultSpawner } from './shellout.ts';
 import { ID_TYPES, MAX_ID_COUNT, generateIds, isIdType } from './short-id.ts';
 import type { StatusRunner } from './status-runner.ts';
@@ -236,8 +237,14 @@ export interface ApiOptions {
   /** Override the icon installer fetcher. Production uses fetchWithProgress;
    *  integration tests inject a fixture-returning closure. */
   iconFetcher?: IconFetcher;
+  /** Live Share controller. The studio bootstrap instantiates one per process
+   *  (see server.ts); tests inject a fake to drive the /api/share/* routes
+   *  without touching the relay or a real WebSocket. */
+  share?: ShareController;
 }
 
+const KickBodySchema = z.object({ peerId: z.string().min(1) });
+
 /**
  * Thin call-through wrapper around the proxy.ts module exports. Lets tests
  * inject a recording fake to observe runPlay invocations — the play-run map
@@ -2090,6 +2097,240 @@ export function createApi(options: ApiOptions): Hono {
     });
   });
 
+  // Live Share local API. Five routes that delegate to the injected
+  // ShareController. The controller is optional — when absent (e.g. tests
+  // that don't exercise share) every endpoint returns 503 so misconfigured
+  // deployments fail visibly instead of silently 404ing.
+  const share = options.share;
+
+  // Map a controller rejection to an HTTP status + error body. share-not-active
+  // and share-peer-not-found are the two domain-specific reasons; everything
+  // else surfaces as 500 with the raw message so misconfigurations (bad relay
+  // URL, network failures, etc.) are debuggable from the response.
+  const shareErrorStatus = (err: unknown): { status: 400 | 404 | 409 | 500; error: string } => {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg === 'share-not-active') return { status: 409, error: msg };
+    if (msg === 'share-peer-not-found') return { status: 404, error: msg };
+    if (msg === 'share-already-active') return { status: 409, error: msg };
+    return { status: 500, error: msg };
+  };
+
+  api.post('/share/start', async (c) => {
+    if (!share) return c.json({ error: 'share controller not configured' }, 503);
+    try {
+      const result = await share.start();
+      return c.json(result);
+    } catch (err) {
+      const mapped = shareErrorStatus(err);
+      return c.json({ error: mapped.error }, mapped.status);
+    }
+  });
+
+  api.post('/share/stop', async (c) => {
+    if (!share) return c.json({ error: 'share controller not configured' }, 503);
+    try {
+      await share.stop();
+      return c.body(null, 204);
+    } catch (err) {
+      const mapped = shareErrorStatus(err);
+      return c.json({ error: mapped.error }, mapped.status);
+    }
+  });
+
+  api.post('/share/kick', async (c) => {
+    if (!share) return c.json({ error: 'share controller not configured' }, 503);
+    let body: unknown;
+    try {
+      body = await c.req.json();
+    } catch {
+      return c.json({ error: 'Body must be valid JSON' }, 400);
+    }
+    const parsed = KickBodySchema.safeParse(body);
+    if (!parsed.success) {
+      return c.json({ error: 'Invalid kick body', issues: parsed.error.issues }, 400);
+    }
+    try {
+      await share.kick(parsed.data.peerId);
+      return c.body(null, 204);
+    } catch (err) {
+      const mapped = shareErrorStatus(err);
+      return c.json({ error: mapped.error }, mapped.status);
+    }
+  });
+
+  api.post('/share/rotate', async (c) => {
+    if (!share) return c.json({ error: 'share controller not configured' }, 503);
+    try {
+      const result = await share.rotateUrl();
+      return c.json(result);
+    } catch (err) {
+      const mapped = shareErrorStatus(err);
+      return c.json({ error: mapped.error }, mapped.status);
+    }
+  });
+
+  // POST /api/share/kill-all — host kill-switch (US-081). Revokes every
+  // session this studio has tracked in `active.json`, not just the active
+  // one. Local-only by the cors.ts middleware. Returns the counts surfaced
+  // by the controller so the UI toast can show "Ended N live sessions".
+  api.post('/share/kill-all', async (c) => {
+    if (!share) return c.json({ error: 'share controller not configured' }, 503);
+    try {
+      const result = await share.killAll();
+      return c.json(result);
+    } catch (err) {
+      const mapped = shareErrorStatus(err);
+      return c.json({ error: mapped.error }, mapped.status);
+    }
+  });
+
+  // GET /api/share/audit — page through the per-session AuditEntry JSONL log.
+  // Local-only by virtue of the cors.ts middleware. Requires an active session
+  // — when the controller is idle there is no logger to read from, so respond
+  // 400 rather than silently returning an empty page (consumers can use the
+  // status code to distinguish "no entries yet" from "no session").
+  api.get('/share/audit', async (c) => {
+    if (!share) return c.json({ error: 'share controller not configured' }, 503);
+    if (share.state().status !== 'active') {
+      return c.json({ error: 'share-not-active' }, 400);
+    }
+    const limitRaw = c.req.query('limit');
+    const cursorRaw = c.req.query('cursor');
+    const limit = limitRaw !== undefined ? Number.parseInt(limitRaw, 10) : undefined;
+    const cursor = cursorRaw !== undefined ? Number.parseInt(cursorRaw, 10) : undefined;
+    const opts: { limit?: number; cursor?: number } = {};
+    if (typeof limit === 'number' && Number.isFinite(limit)) opts.limit = limit;
+    if (typeof cursor === 'number' && Number.isFinite(cursor)) opts.cursor = cursor;
+    try {
+      const page = await share.audit.list(opts);
+      return c.json(page);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return c.json({ error: message }, 500);
+    }
+  });
+
+  // GET /api/share/state — SSE stream of ShareState transitions. Initial frame
+  // is the current state; subsequent frames are pushed on each controller
+  // subscribe callback. Mirrors the /api/events shape (queue + wake + heartbeat)
+  // so the UI can use the same EventSource handling.
+  api.get('/share/state', (c) => {
+    if (!share) return c.json({ error: 'share controller not configured' }, 503);
+    const controller = share;
+
+    return streamSSE(c, async (stream) => {
+      let active = true;
+      const queue: Array<{ event: string; data: string }> = [];
+      let resume: (() => void) | null = null;
+
+      const wake = () => {
+        if (resume) {
+          const r = resume;
+          resume = null;
+          r();
+        }
+      };
+
+      const enqueue = (s: ShareState) => {
+        queue.push({ event: 'state', data: JSON.stringify(s) });
+        wake();
+      };
+
+      // subscribe() invokes fn synchronously with the current state, so the
+      // initial frame lands in the queue automatically — no explicit prologue.
+      const unsubscribe = controller.subscribe(enqueue);
+
+      stream.onAbort(() => {
+        active = false;
+        unsubscribe();
+        wake();
+      });
+
+      try {
+        while (active) {
+          while (queue.length > 0) {
+            const next = queue.shift();
+            if (!next) break;
+            await stream.writeSSE(next);
+          }
+          if (!active) break;
+          let heartbeat: ReturnType<typeof setTimeout> | null = null;
+          const reason = await new Promise<'event' | 'heartbeat'>((r) => {
+            resume = () => r('event');
+            heartbeat = setTimeout(() => r('heartbeat'), SSE_HEARTBEAT_MS);
+          });
+          if (heartbeat) clearTimeout(heartbeat);
+          resume = null;
+          if (reason === 'heartbeat' && active) {
+            await stream.write(': ping\n\n');
+          }
+        }
+      } finally {
+        unsubscribe();
+      }
+    });
+  });
+
+  // GET /api/share/attributions — SSE stream of `node-patched` attribution
+  // events for the host studio's apps/web UI (US-053). Fires once per accepted
+  // op (peer-originated AND host-originated), carrying `{flowId, op, diff,
+  // version, attributedTo, ts}`. No initial replay — the toast stack is for
+  // live activity only.
+  api.get('/share/attributions', (c) => {
+    if (!share) return c.json({ error: 'share controller not configured' }, 503);
+    const controller = share;
+
+    return streamSSE(c, async (stream) => {
+      let active = true;
+      const queue: Array<{ event: string; data: string }> = [];
+      let resume: (() => void) | null = null;
+
+      const wake = () => {
+        if (resume) {
+          const r = resume;
+          resume = null;
+          r();
+        }
+      };
+
+      const enqueue = (event: AttributionEvent) => {
+        queue.push({ event: 'attribution', data: JSON.stringify(event) });
+        wake();
+      };
+
+      const unsubscribe = controller.subscribeAttributions(enqueue);
+
+      stream.onAbort(() => {
+        active = false;
+        unsubscribe();
+        wake();
+      });
+
+      try {
+        while (active) {
+          while (queue.length > 0) {
+            const next = queue.shift();
+            if (!next) break;
+            await stream.writeSSE(next);
+          }
+          if (!active) break;
+          let heartbeat: ReturnType<typeof setTimeout> | null = null;
+          const reason = await new Promise<'event' | 'heartbeat'>((r) => {
+            resume = () => r('event');
+            heartbeat = setTimeout(() => r('heartbeat'), SSE_HEARTBEAT_MS);
+          });
+          if (heartbeat) clearTimeout(heartbeat);
+          resume = null;
+          if (reason === 'heartbeat' && active) {
+            await stream.write(': ping\n\n');
+          }
+        }
+      } finally {
+        unsubscribe();
+      }
+    });
+  });
+
   // Global registry channel — broadcasts `registry:reload` when an external
   // process (e.g. the CLI) writes to ~/.seeflow/registry.json. Subscribers
   // re-fetch the flow list. The channel id is the internal sentinel from

package/src/atomic-write.ts

@@ -1,6 +1,6 @@
 import { existsSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 
-export const writeFileAtomic = (filePath: string, content: string): void => {
+export const writeFileAtomic = (filePath: string, content: string | Uint8Array): void => {
   const tempPath = `${filePath}.tmp.${process.pid}.${Date.now()}`;
   try {
     writeFileSync(tempPath, content);

package/src/server.ts

@@ -14,6 +14,7 @@ import { seeflowHome } from './paths.ts';
 import { type ProcessSpawner, defaultProcessSpawner } from './process-spawner.ts';
 import { type RegistryWatcher, createRegistryWatcher } from './registry-watcher.ts';
 import { type Registry, createRegistry, manifestOnlyEntryFilter } from './registry.ts';
+import { type ShareController, createShareController, resolveHostDisplayName } from './share.ts';
 import type { Spawner } from './shellout.ts';
 import { type StatusRunner, createStatusRunner } from './status-runner.ts';
 import { type FlowWatcher, createWatcher } from './watcher.ts';
@@ -79,8 +80,16 @@ export interface CreateAppOptions {
   /** Override the icon installer's fetcher. Production uses fetchWithProgress
    *  (real network); integration tests inject a fixture-returning closure. */
   iconFetcher?: IconFetcher;
+  /** Inject a Live Share controller. Defaults to one pointed at
+   *  https://seeflow.dev (SEEFLOW_SHARE_RELAY_URL) with share URLs rooted at
+   *  https://share.seeflow.dev (SEEFLOW_SHARE_URL_BASE). Tests inject a fake
+   *  to exercise the /api/share/* routes without a real relay. */
+  share?: ShareController;
 }
 
+const DEFAULT_SHARE_RELAY_URL = 'https://seeflow.dev';
+const DEFAULT_SHARE_URL_BASE = 'https://share.seeflow.dev';
+
 const DEFAULT_VITE_DEV_URL = 'http://localhost:5173';
 const DEFAULT_STATIC_ROOT = resolvePath(import.meta.dir, '../dist/web');
 
@@ -108,6 +117,15 @@ export function createApp(options: CreateAppOptions = {}): Hono {
     options.statusRunner ??
     createStatusRunner({ registry, events, spawner: defaultProcessSpawner });
   const iconJobs = options.iconJobs ?? createJobRegistry();
+  const share =
+    options.share ??
+    createShareController({
+      relayHttpUrl: process.env.SEEFLOW_SHARE_RELAY_URL ?? DEFAULT_SHARE_RELAY_URL,
+      shareUrlBase: process.env.SEEFLOW_SHARE_URL_BASE ?? DEFAULT_SHARE_URL_BASE,
+      eventBus: events,
+      flowIdsForBroadcast: () => registry.list().map((e) => e.id),
+      hostDisplayName: resolveHostDisplayName(),
+    });
 
   if (watcher && (options.watchAllOnBoot ?? true)) {
     watcher.watchAll();
@@ -171,6 +189,7 @@ export function createApp(options: CreateAppOptions = {}): Hono {
       iconJobs,
       iconCacheRoot: options.iconCacheRoot,
       iconFetcher: options.iconFetcher,
+      share,
     }),
   );
 

package/src/share/sse-frame.ts

@@ -0,0 +1,85 @@
+/**
+ * SSE bridge envelope payload schema for live-share `sse` frames.
+ *
+ * Single source of truth for the wire shape of runtime events relayed from
+ * the host studio's local EventBus to peers over the share WebSocket. Both
+ * sides parse against the same Zod schema; drift between this file and the
+ * peer SPA's mirror (`seeflow-viewer/src/lib/share-sse-frame.ts`) is gated
+ * by `apps/studio/scripts/check-sse-frame-sync.ts`.
+ */
+
+import { z } from 'zod';
+import type { StudioEvent } from '../events.ts';
+
+// SYNC-WITH-PEER:BEGIN
+export const SSE_EVENT_TYPES = [
+  'flow:reload',
+  'node:running',
+  'node:done',
+  'node:error',
+  'node:status',
+] as const;
+
+export const SseEventTypeSchema = z.enum(SSE_EVENT_TYPES);
+export type SseEventType = z.infer<typeof SseEventTypeSchema>;
+
+export const SsePayloadSchema = z.object({
+  t: SseEventTypeSchema,
+  flowId: z.string().min(1),
+  ts: z.number().int().nonnegative(),
+  data: z.unknown(),
+  seq: z.number().int().nonnegative(),
+});
+
+export type SsePayload = z.infer<typeof SsePayloadSchema>;
+
+export interface SseEnvelope {
+  v: 1;
+  type: 'sse';
+  from: 'host';
+  to: 'all';
+  payload: SsePayload;
+}
+
+export function isSseEventType(t: string): t is SseEventType {
+  return (SSE_EVENT_TYPES as readonly string[]).includes(t);
+}
+
+/**
+ * Snapshot replay payload sent to a freshly-joined peer so its canvas badges
+ * match the host without waiting for the next live tick. `flows` is a 2-level
+ * map of flowId -> nodeId -> latest SsePayload observed by the host's tap.
+ * When the serialized snapshot exceeds the 256 KB per-frame cap, the host
+ * splits per-flow and stamps each frame with `chunk` (zero-based) + `total`
+ * so the peer can reassemble before applying.
+ */
+export const SseSnapshotPayloadSchema = z.object({
+  flows: z.record(z.string(), z.record(z.string(), SsePayloadSchema)),
+  chunk: z.number().int().nonnegative().optional(),
+  total: z.number().int().positive().optional(),
+});
+
+export type SseSnapshotPayload = z.infer<typeof SseSnapshotPayloadSchema>;
+// SYNC-WITH-PEER:END
+
+/**
+ * Wrap a local StudioEvent into a relay-shaped `sse` envelope. Returns null
+ * when the event type is not one of the SSE-bridged kinds (`file:changed`,
+ * `registry:reload`) so callers can filter without try/catch.
+ */
+export function wrapAsSseFrame(event: StudioEvent, seq: number): SseEnvelope | null {
+  if (!isSseEventType(event.type)) return null;
+  return {
+    v: 1,
+    type: 'sse',
+    from: 'host',
+    to: 'all',
+    payload: {
+      t: event.type,
+      flowId: event.flowId,
+      ts: event.ts,
+      data: event.payload,
+      seq,
+    },
+  };
+}

package/src/share/sse-outbound-queue.ts

@@ -0,0 +1,173 @@
+/**
+ * US-072 — Per-peer outbound SSE queue with drop-on-slow-consumer.
+ *
+ * A bounded async queue, one instance per connected peer, that decouples the
+ * host's SSE bridge (synchronous EventBus -> tap -> per-peer enqueue) from the
+ * relay WebSocket's send path. If a peer's drain is slow, frames accumulate up
+ * to `maxFrames` (default 256). On overflow:
+ *
+ *   - Non-terminal new frame: evict the OLDEST non-terminal entry. If no
+ *     non-terminal entries exist (queue full of terminals), drop the new one.
+ *   - Terminal new frame (`node:done` / `node:error`): evict the OLDEST entry
+ *     regardless of type so the terminal is always queued.
+ *
+ * Per-peer metrics (`queueDepth`, `droppedFrames`, `lastSendMs`) are surfaced
+ * to the LiveShareDialog via the local `/api/share/state` SSE stream. When the
+ * rolling 60s drop count exceeds 100, the queue fires `onResyncTriggered` so
+ * the host can emit an `sse-snapshot` to recover the peer's canvas state.
+ *
+ * Enqueue is synchronous and non-blocking; the producer (the SSE tap) never
+ * awaits the WebSocket send. The drain runs as a single concurrent async loop
+ * — at most one in-flight send per peer keeps frame ordering stable while
+ * still letting different peers' queues drain in parallel.
+ */
+
+import type { SsePayload } from './sse-frame.ts';
+
+const TERMINAL_TYPES = new Set<SsePayload['t']>(['node:done', 'node:error']);
+
+export const DEFAULT_MAX_FRAMES = 256;
+export const DEFAULT_DROP_RESYNC_THRESHOLD = 100;
+export const DEFAULT_DROP_RESYNC_WINDOW_MS = 60_000;
+
+const isTerminalPayload = (p: SsePayload): boolean => TERMINAL_TYPES.has(p.t);
+
+export interface PeerSseQueueMetrics {
+  /** Frames currently waiting to be sent (excludes the in-flight frame). */
+  queueDepth: number;
+  /** Lifetime count of frames evicted due to overflow. */
+  droppedFrames: number;
+  /** Duration in ms of the last awaited `send` call (null until first send). */
+  lastSendMs: number | null;
+}
+
+export interface PeerSseQueueOpts {
+  peerConnId: string;
+  /**
+   * Underlying send for the queue. Awaited per-frame so slow consumers create
+   * backpressure here rather than in the producer. Resolves on success; any
+   * error is swallowed (logged) so a single bad frame doesn't stall the drain.
+   */
+  send: (payload: SsePayload, peerConnId: string) => Promise<void> | void;
+  /** Defaults to 256. */
+  maxFrames?: number;
+  /**
+   * Called when `droppedFrames` within `dropResyncWindowMs` exceeds
+   * `dropResyncThreshold`. The window counter is reset after firing so the
+   * next trigger requires another full window of drops.
+   */
+  onResyncTriggered?: () => void;
+  /** Defaults to 100. */
+  dropResyncThreshold?: number;
+  /** Defaults to 60_000. */
+  dropResyncWindowMs?: number;
+  /** Defaults to `Date.now`. */
+  now?: () => number;
+}
+
+export interface PeerSseQueue {
+  /** Synchronously enqueue. Returns void; never awaits the underlying send. */
+  enqueue(payload: SsePayload): void;
+  metrics(): PeerSseQueueMetrics;
+  /** Stops the drain loop and discards pending frames. Idempotent. */
+  dispose(): void;
+}
+
+interface QueuedFrame {
+  payload: SsePayload;
+  terminal: boolean;
+}
+
+export function createPeerSseQueue(opts: PeerSseQueueOpts): PeerSseQueue {
+  const maxFrames = opts.maxFrames ?? DEFAULT_MAX_FRAMES;
+  const dropThreshold = opts.dropResyncThreshold ?? DEFAULT_DROP_RESYNC_THRESHOLD;
+  const dropWindowMs = opts.dropResyncWindowMs ?? DEFAULT_DROP_RESYNC_WINDOW_MS;
+  const now = opts.now ?? Date.now;
+
+  const queue: QueuedFrame[] = [];
+  const dropTimestamps: number[] = [];
+  let droppedFrames = 0;
+  let lastSendMs: number | null = null;
+  let disposed = false;
+  let draining = false;
+
+  const recordDrop = (): void => {
+    droppedFrames += 1;
+    const ts = now();
+    dropTimestamps.push(ts);
+    const cutoff = ts - dropWindowMs;
+    while (dropTimestamps.length > 0 && (dropTimestamps[0] ?? 0) < cutoff) {
+      dropTimestamps.shift();
+    }
+    if (dropTimestamps.length > dropThreshold) {
+      dropTimestamps.length = 0;
+      try {
+        opts.onResyncTriggered?.();
+      } catch (err) {
+        console.warn('[share] sse-outbound onResyncTriggered threw:', err);
+      }
+    }
+  };
+
+  const drain = async (): Promise<void> => {
+    if (draining || disposed) return;
+    draining = true;
+    try {
+      while (queue.length > 0 && !disposed) {
+        const frame = queue.shift();
+        if (!frame) break;
+        const start = now();
+        try {
+          await opts.send(frame.payload, opts.peerConnId);
+        } catch (err) {
+          console.warn('[share] sse-outbound send failed:', err);
+        }
+        lastSendMs = now() - start;
+      }
+    } finally {
+      draining = false;
+    }
+  };
+
+  const enqueue = (payload: SsePayload): void => {
+    if (disposed) return;
+    const terminal = isTerminalPayload(payload);
+
+    if (queue.length >= maxFrames) {
+      if (terminal) {
+        // Drop the oldest entry regardless of type so the terminal frame
+        // always finds a slot — terminal-wins semantics drive the peer's
+        // visual reconciliation back to a settled state.
+        queue.shift();
+        recordDrop();
+      } else {
+        const idx = queue.findIndex((f) => !f.terminal);
+        if (idx === -1) {
+          // Queue is full of terminals — drop the incoming non-terminal so
+          // we don't displace a settled state with a stale running tick.
+          recordDrop();
+          return;
+        }
+        queue.splice(idx, 1);
+        recordDrop();
+      }
+    }
+
+    queue.push({ payload, terminal });
+    void drain();
+  };
+
+  return {
+    enqueue,
+    metrics: (): PeerSseQueueMetrics => ({
+      queueDepth: queue.length,
+      droppedFrames,
+      lastSendMs,
+    }),
+    dispose: (): void => {
+      disposed = true;
+      queue.length = 0;
+      dropTimestamps.length = 0;
+    },
+  };
+}