@fabrika/canvas-kernel 0.1.45 → 0.2.0

package/src/engine/channel.ts

@@ -1,278 +0,0 @@
-/**
- * The WebSocket notification channel: a two-role socket registry keyed by an
- * opaque topic string.
- *
- * The kernel owns the plumbing — who is registered under which topic, how a
- * message reaches browsers or waiters, when a waiter is announced as present,
- * and the ping/pong sweep that evicts dead waiters. It owns no vocabulary: the
- * host supplies the frames, decides what a frame does, and decides whether a
- * relayed frame closes the waiters that received it.
- *
- * Two hosts map onto it today:
- *
- * - agent-canvas (`engine/websocket.ts`) — topic = session id, waiter policy
- *   `close-on-delivery` (the CLI's `wait` socket is satisfied by one frame),
- *   frames `submit` / `render-error`, presence frame `watcher-status`.
- * - obrazovka — topic = Figma file key, waiter policy `keep-open` (a `--page`
- *   waiter must survive a relay meant for a different page and filter frames
- *   client-side), frames `confirm-screens` / `submit` registered by the host
- *   plus server-initiated relays `run` / `feedback`, presence frame `presence`.
- */
-
-export type ChannelRole = "browser" | "wait";
-
-/** The minimum a host socket must offer; `Bun.ServerWebSocket` satisfies it. */
-export interface ChannelSocket {
-  send(message: string): unknown;
-  close(): void;
-  ping(): unknown;
-}
-
-export interface RelayOptions {
-  /**
-   * Close every waiter the message was handed to and drop the topic's waiter
-   * set. Defaults to the channel's `waiterPolicy`.
-   */
-  close?: boolean;
-}
-
-/** Channel operations bound to one topic. */
-export interface TopicChannel {
-  readonly topic: string;
-  /** Send to every browser on the topic. */
-  broadcast(message: unknown): void;
-  /** Send to every waiter on the topic; `false` when there was none. */
-  relayToWaiters(message: unknown, options?: RelayOptions): boolean;
-  hasWaiter(): boolean;
-  /** Announce current waiter presence to the topic's browsers. */
-  broadcastPresence(): void;
-}
-
-export interface BrowserFrameHandler {
-  /** The bound work when the frame is this handler's, `undefined` otherwise. */
-  bind(frame: unknown, channel: TopicChannel): (() => void | Promise<void>) | undefined;
-}
-
-/**
- * Register one frame of a host's vocabulary. Matching is synchronous so the
- * socket's `message` handler stays synchronous; handling may be async.
- */
-export function browserFrame<T>(
-  match: (frame: unknown) => frame is T,
-  handle: (frame: T, channel: TopicChannel) => void | Promise<void>,
-): BrowserFrameHandler {
-  return {
-    bind: (frame, channel) => (match(frame) ? () => handle(frame, channel) : undefined),
-  };
-}
-
-export interface NotificationChannelOptions<S extends ChannelSocket> {
-  /** Which registry a socket belongs to. */
-  roleOf(socket: S): ChannelRole;
-  /** The socket's routing key — a canvas session id, a Figma file key, … */
-  topicOf(socket: S): string;
-  /** The host's browser-frame vocabulary, tried in order; first match wins. */
-  frames?: readonly BrowserFrameHandler[];
-  /** Builds the presence frame. Presence is not announced when omitted. */
-  presenceFrame?(hasWaiter: boolean, topic: string): unknown;
-  /** What a relay does to the waiters it reached. Default `"keep-open"`. */
-  waiterPolicy?: "close-on-delivery" | "keep-open";
-  /**
-   * Runs after a waiter is registered and before presence is announced, so a
-   * host that buffers events for an absent waiter can flush them here.
-   */
-  onWaiterOpen?(channel: TopicChannel): void;
-  /** Frame handler failures. Dropped when omitted. */
-  onError?(error: unknown): void;
-  /** Liveness sweep period; `false` leaves the sweep to the host. */
-  pingIntervalMs?: number | false;
-}
-
-export interface NotificationChannel<S extends ChannelSocket> {
-  handlers: {
-    open(socket: S): void;
-    message(socket: S, message: string | Buffer): void;
-    pong(socket: S): void;
-    close(socket: S): void;
-  };
-  broadcast(topic: string, message: unknown): void;
-  relayToWaiters(topic: string, message: unknown, options?: RelayOptions): boolean;
-  hasWaiter(topic: string): boolean;
-  broadcastPresence(topic: string): void;
-  /** The topic-bound view handed to frame handlers. */
-  topic(topic: string): TopicChannel;
-  /** One liveness sweep — ping live waiters, evict the ones that never ponged. */
-  pingWaiters(): void;
-  /** Stop the liveness timer. */
-  stop(): void;
-}
-
-const DEFAULT_PING_INTERVAL_MS = 5_000;
-
-function parseFrame(message: string | Buffer): unknown {
-  const text = typeof message === "string" ? message : new TextDecoder().decode(message);
-  try {
-    return JSON.parse(text);
-  } catch {
-    return undefined;
-  }
-}
-
-export function createNotificationChannel<S extends ChannelSocket>(
-  options: NotificationChannelOptions<S>,
-): NotificationChannel<S> {
-  const { roleOf, topicOf } = options;
-  const frames = options.frames ?? [];
-  const closeOnDelivery = (options.waiterPolicy ?? "keep-open") === "close-on-delivery";
-  const browserSockets = new Map<string, Set<S>>();
-  const waitSockets = new Map<string, Set<S>>();
-  const pongReceived = new WeakSet<S>();
-
-  function registry(role: ChannelRole): Map<string, Set<S>> {
-    return role === "browser" ? browserSockets : waitSockets;
-  }
-
-  function hasWaiter(topic: string): boolean {
-    return (waitSockets.get(topic)?.size ?? 0) > 0;
-  }
-
-  function broadcast(topic: string, message: unknown): void {
-    const sockets = browserSockets.get(topic);
-    if (!sockets || sockets.size === 0) return;
-    const payload = JSON.stringify(message);
-    for (const socket of sockets) socket.send(payload);
-  }
-
-  function presencePayload(topic: string): string | undefined {
-    if (!options.presenceFrame) return undefined;
-    return JSON.stringify(options.presenceFrame(hasWaiter(topic), topic));
-  }
-
-  function broadcastPresence(topic: string): void {
-    const payload = presencePayload(topic);
-    if (payload === undefined) return;
-    const sockets = browserSockets.get(topic);
-    if (!sockets) return;
-    for (const socket of sockets) socket.send(payload);
-  }
-
-  function relayToWaiters(topic: string, message: unknown, relay: RelayOptions = {}): boolean {
-    const sockets = waitSockets.get(topic);
-    if (!sockets || sockets.size === 0) return false;
-    const close = relay.close ?? closeOnDelivery;
-    if (close) waitSockets.delete(topic);
-    const payload = JSON.stringify(message);
-    for (const socket of sockets) {
-      socket.send(payload);
-      if (close) socket.close();
-    }
-    return true;
-  }
-
-  function topicChannel(topic: string): TopicChannel {
-    return {
-      topic,
-      broadcast: (message) => broadcast(topic, message),
-      relayToWaiters: (message, relay) => relayToWaiters(topic, message, relay),
-      hasWaiter: () => hasWaiter(topic),
-      broadcastPresence: () => broadcastPresence(topic),
-    };
-  }
-
-  function reportError(error: unknown): void {
-    options.onError?.(error);
-  }
-
-  function dropWaiter(topic: string, socket: S): void {
-    const sockets = waitSockets.get(topic);
-    if (sockets) {
-      sockets.delete(socket);
-      if (sockets.size === 0) waitSockets.delete(topic);
-    }
-    try { socket.close(); } catch {}
-    broadcastPresence(topic);
-  }
-
-  // A dead socket never fires `close`, so presence would stay stuck on `true`
-  // until the daemon restarts — sweep for the missing pong instead.
-  function pingWaiters(): void {
-    for (const [topic, sockets] of waitSockets) {
-      for (const socket of sockets) {
-        if (!pongReceived.has(socket)) {
-          dropWaiter(topic, socket);
-          continue;
-        }
-        pongReceived.delete(socket);
-        try { socket.ping(); } catch { dropWaiter(topic, socket); }
-      }
-    }
-  }
-
-  const interval = options.pingIntervalMs === false
-    ? undefined
-    : setInterval(pingWaiters, options.pingIntervalMs ?? DEFAULT_PING_INTERVAL_MS);
-  interval?.unref();
-
-  const handlers = {
-    open(socket: S): void {
-      const topic = topicOf(socket);
-      const role = roleOf(socket);
-      const sockets = registry(role).get(topic) ?? new Set<S>();
-      sockets.add(socket);
-      registry(role).set(topic, sockets);
-
-      if (role === "browser") {
-        const payload = presencePayload(topic);
-        if (payload !== undefined) socket.send(payload);
-        return;
-      }
-      pongReceived.add(socket); // free pass on the first sweep
-      options.onWaiterOpen?.(topicChannel(topic));
-      broadcastPresence(topic);
-    },
-
-    message(socket: S, message: string | Buffer): void {
-      if (roleOf(socket) !== "browser") return;
-      const frame = parseFrame(message);
-      if (frame === undefined) return;
-      const channel = topicChannel(topicOf(socket));
-      for (const handler of frames) {
-        const run = handler.bind(frame, channel);
-        if (!run) continue;
-        try {
-          const result = run();
-          if (result instanceof Promise) result.catch(reportError);
-        } catch (error) {
-          reportError(error);
-        }
-        return;
-      }
-    },
-
-    pong(socket: S): void {
-      if (roleOf(socket) === "wait") pongReceived.add(socket);
-    },
-
-    close(socket: S): void {
-      const topic = topicOf(socket);
-      const role = roleOf(socket);
-      const sockets = registry(role).get(topic);
-      sockets?.delete(socket);
-      if (sockets && sockets.size === 0) registry(role).delete(topic);
-      if (role === "wait") broadcastPresence(topic);
-    },
-  };
-
-  return {
-    handlers,
-    broadcast,
-    relayToWaiters,
-    hasWaiter,
-    broadcastPresence,
-    topic: topicChannel,
-    pingWaiters,
-    stop() {
-      if (interval) clearInterval(interval);
-    },
-  };
-}

package/src/engine/http-utils.ts

@@ -1,14 +0,0 @@
-export function jsonResponse(data: unknown, status = 200): Response {
-  return new Response(JSON.stringify(data), {
-    status,
-    headers: { "Content-Type": "application/json" },
-  });
-}
-
-export function corsHeaders(port: number): Record<string, string> {
-  return {
-    "Access-Control-Allow-Origin": "http://localhost:" + port,
-    "Access-Control-Allow-Methods": "GET, POST, DELETE, OPTIONS",
-    "Access-Control-Allow-Headers": "Content-Type",
-  };
-}

package/src/engine/lifecycle.ts

@@ -1,302 +0,0 @@
-/**
- * Daemon process lifecycle: is it up, start it, stop it, keep it in step with
- * the CLI that talks to it.
- *
- * The kernel owns the algorithm — health probing, the concurrent-start race,
- * which pid may be signalled — and the host owns every location: base URL, pid
- * file, spawn argv, log file, health shape, timeouts.
- *
- * The daemon's own pid, reported through `/health`, is the only pid this module
- * will signal. A pid file is written at spawn and read only to notice that
- * *someone* is already booting a daemon; a stale file or a reused pid must
- * never let the CLI kill an unrelated process.
- */
-
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync, appendFileSync } from "fs";
-import { dirname } from "path";
-
-/** Every host health shape must carry the daemon's own pid. */
-export interface DaemonPid {
-  pid: number;
-}
-
-export type DaemonHealthUp<H extends DaemonPid> = { status: "up"; ok: true; url: string } & H;
-
-export interface DaemonHealthDown {
-  status: "down";
-  ok: false;
-  url: string;
-  error?: string;
-}
-
-export type DaemonHealth<H extends DaemonPid> = DaemonHealthUp<H> | DaemonHealthDown;
-
-export type DaemonStopReason =
-  | "stopped"
-  | "not-running"
-  /** Nothing was running; a pid file left behind was cleaned up. */
-  | "stale-pid"
-  /** A daemon answered `/health`, but signalling its pid failed. */
-  | "signal-failed"
-  | "refused-self";
-
-export interface DaemonStopResult {
-  stopped: boolean;
-  /** The daemon's own pid, or the stale pid-file value that was cleaned up. */
-  pid?: number;
-  reason: DaemonStopReason;
-  message: string;
-}
-
-/** Progress worth telling a user about; the host writes the words. */
-export type DaemonEvent =
-  | { type: "version-mismatch"; running: string; expected: string }
-  | { type: "starting"; command: readonly string[] }
-  | { type: "started"; pid: number }
-  | { type: "stopped"; pid: number };
-
-export interface DaemonTimeouts {
-  /** Per `/health` request. Default 1000. */
-  health?: number;
-  /** Wait for a daemon this process spawned. Default 3000. */
-  start?: number;
-  /** Wait for a daemon another process is already starting. Default 1000. */
-  concurrentStart?: number;
-  /** Wait for a signalled daemon to go down. Default 2000. */
-  stop?: number;
-}
-
-export interface DaemonLifecycleConfig<H extends DaemonPid> {
-  /** Daemon origin, e.g. `http://localhost:19400`. */
-  baseUrl: string;
-  /** Health endpoint path. Default `/health`. */
-  healthPath?: string;
-  /** Narrows the `/health` body; `undefined` means "not a daemon we can talk to". */
-  parseHealth(body: unknown): H | undefined;
-  /** Written at spawn, so a concurrent start can see a daemon that is still booting. */
-  pidFile: string;
-  /** argv of the daemon process, e.g. `[process.execPath, entry, "serve"]`. */
-  command: readonly string[];
-  /** Working directory of the spawned daemon. Defaults to the current one. */
-  cwd?: string;
-  /** File the daemon's stdout and stderr are appended to. */
-  logFile: string;
-  /** Restart the daemon when its version differs from this CLI's. Off when omitted. */
-  versionCheck?: {
-    expected: string;
-    of(health: H): string | undefined;
-  };
-  /** Removed with the pid file when the daemon stops (auth tokens, sockets, …). */
-  cleanupFiles?: readonly string[];
-  timeouts?: DaemonTimeouts;
-  onEvent?(event: DaemonEvent): void;
-}
-
-export class DaemonStartError extends Error {
-  constructor(message: string, readonly logFile: string, readonly logTail: string) {
-    super(message);
-    this.name = "DaemonStartError";
-  }
-}
-
-export interface DaemonLifecycle<H extends DaemonPid> {
-  health(timeoutMs?: number): Promise<DaemonHealth<H>>;
-  isRunning(): Promise<boolean>;
-  start(): Promise<DaemonHealthUp<H>>;
-  /** A healthy daemon of the expected version, starting or restarting one if needed. */
-  ensure(): Promise<DaemonHealthUp<H>>;
-  stop(): Promise<DaemonStopResult>;
-  restart(): Promise<DaemonHealthUp<H>>;
-}
-
-const LOG_TAIL_BYTES = 4096;
-
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-function errorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
-export function createDaemonLifecycle<H extends DaemonPid>(
-  config: DaemonLifecycleConfig<H>,
-): DaemonLifecycle<H> {
-  const healthUrl = `${config.baseUrl}${config.healthPath ?? "/health"}`;
-  const timeouts = {
-    health: config.timeouts?.health ?? 1_000,
-    start: config.timeouts?.start ?? 3_000,
-    concurrentStart: config.timeouts?.concurrentStart ?? 1_000,
-    stop: config.timeouts?.stop ?? 2_000,
-  };
-
-  function emit(event: DaemonEvent): void {
-    config.onEvent?.(event);
-  }
-
-  async function health(timeoutMs: number = timeouts.health): Promise<DaemonHealth<H>> {
-    const url = config.baseUrl;
-    try {
-      const response = await fetch(healthUrl, { signal: AbortSignal.timeout(timeoutMs) });
-      if (!response.ok) return { status: "down", ok: false, url, error: `HTTP ${response.status}` };
-      const parsed = config.parseHealth(await response.json());
-      if (!parsed) return { status: "down", ok: false, url, error: "invalid health response" };
-      return { status: "up", ok: true, url, ...parsed };
-    } catch (error) {
-      return { status: "down", ok: false, url, error: errorMessage(error) };
-    }
-  }
-
-  async function pollHealthy(timeoutMs: number): Promise<DaemonHealth<H>> {
-    const deadline = Date.now() + timeoutMs;
-    let last = await health();
-    while (last.status === "down" && Date.now() < deadline) {
-      await sleep(100);
-      last = await health();
-    }
-    return last;
-  }
-
-  function readPid(): number | undefined {
-    try {
-      const pid = Number(readFileSync(config.pidFile, "utf-8").trim());
-      return Number.isInteger(pid) && pid > 0 ? pid : undefined;
-    } catch {
-      return undefined;
-    }
-  }
-
-  function processIsAlive(pid: number): boolean {
-    try {
-      process.kill(pid, 0);
-      return true;
-    } catch {
-      return false;
-    }
-  }
-
-  function cleanupFiles(): void {
-    for (const file of [config.pidFile, ...(config.cleanupFiles ?? [])]) {
-      try { rmSync(file, { force: true }); } catch {}
-    }
-  }
-
-  function readLogTail(): string {
-    if (!existsSync(config.logFile)) return "";
-    try {
-      const log = readFileSync(config.logFile, "utf-8");
-      return log.slice(-LOG_TAIL_BYTES).trim();
-    } catch {
-      return "";
-    }
-  }
-
-  function spawnDaemon(): number {
-    mkdirSync(dirname(config.logFile), { recursive: true });
-    appendFileSync(config.logFile, `--- daemon start ${new Date().toISOString()}\n`);
-    const stdout = openSync(config.logFile, "a");
-    const stderr = openSync(config.logFile, "a");
-    try {
-      const child = Bun.spawn([...config.command], {
-        cwd: config.cwd ?? process.cwd(),
-        stdin: "ignore",
-        stdout,
-        stderr,
-        detached: true,
-      });
-      child.unref();
-      mkdirSync(dirname(config.pidFile), { recursive: true });
-      writeFileSync(config.pidFile, `${child.pid}\n`);
-      return child.pid;
-    } finally {
-      closeSync(stdout);
-      closeSync(stderr);
-    }
-  }
-
-  async function start(): Promise<DaemonHealthUp<H>> {
-    emit({ type: "starting", command: config.command });
-    spawnDaemon();
-    const started = await pollHealthy(timeouts.start);
-    if (started.status === "up") {
-      emit({ type: "started", pid: started.pid });
-      return started;
-    }
-    throw new DaemonStartError(
-      `Daemon did not become healthy within ${timeouts.start}ms.`,
-      config.logFile,
-      readLogTail(),
-    );
-  }
-
-  async function stop(): Promise<DaemonStopResult> {
-    const current = await health();
-
-    if (current.status === "down") {
-      const stale = readPid();
-      if (stale === undefined) return { stopped: false, reason: "not-running", message: "Daemon is not running." };
-      cleanupFiles();
-      return { stopped: false, pid: stale, reason: "stale-pid", message: `Daemon is not running; removed stale pid ${stale}.` };
-    }
-
-    const pid = current.pid;
-    if (pid === process.pid) {
-      return { stopped: false, pid, reason: "refused-self", message: `Daemon pid ${pid} is this process; refusing to stop self.` };
-    }
-
-    try {
-      process.kill(pid, "SIGTERM");
-    } catch {
-      cleanupFiles();
-      return { stopped: false, pid, reason: "signal-failed", message: `Daemon pid ${pid} could not be signalled.` };
-    }
-
-    const deadline = Date.now() + timeouts.stop;
-    while (Date.now() < deadline && (await health()).status === "up") {
-      await sleep(100);
-    }
-    cleanupFiles();
-    emit({ type: "stopped", pid });
-    return { stopped: true, pid, reason: "stopped", message: `Stopped daemon pid ${pid}.` };
-  }
-
-  async function ensure(): Promise<DaemonHealthUp<H>> {
-    const current = await health();
-    if (current.status === "up") {
-      const check = config.versionCheck;
-      const running = check?.of(current);
-      if (check && running && running !== check.expected) {
-        emit({ type: "version-mismatch", running, expected: check.expected });
-        await stop();
-        return await start();
-      }
-      return current;
-    }
-
-    // Someone else may be mid-spawn: a live pid with no health yet is a daemon
-    // still booting, and racing it would put a second one on the same port.
-    const pid = readPid();
-    if (pid !== undefined && processIsAlive(pid)) {
-      const starting = await pollHealthy(timeouts.concurrentStart);
-      if (starting.status === "up") return starting;
-    }
-
-    return await start();
-  }
-
-  async function restart(): Promise<DaemonHealthUp<H>> {
-    await stop();
-    return await start();
-  }
-
-  return {
-    health,
-    async isRunning() {
-      return (await health()).status === "up";
-    },
-    start,
-    ensure,
-    stop,
-    restart,
-  };
-}

package/src/engine/router.ts

@@ -1,16 +0,0 @@
-export type RouteHandler = (req: Request, url: URL, match: URLPatternResult) => Response | Promise<Response>;
-
-export interface Route {
-  method: string;
-  pattern: URLPattern;
-  handler: RouteHandler;
-}
-
-export function dispatch(routes: Route[], req: Request, url: URL): Response | Promise<Response> | null {
-  for (const route of routes) {
-    if (route.method !== req.method) continue;
-    const match = route.pattern.exec(url);
-    if (match) return route.handler(req, url, match);
-  }
-  return null;
-}