@worca/ui 0.1.0-rc.1

package/server/worca-setup.js

@@ -0,0 +1,114 @@
+/**
+ * Worca install/update logic for the UI server.
+ *
+ * Delegates to the `worca init` CLI for installation and upgrades.
+ * The UI only needs to check installation status and spawn the CLI.
+ *
+ * - checkWorcaInstalled(path)   → check if .claude/worca/ exists in a project
+ * - runWorcaSetup(targetPath, opts) → spawn `worca init --upgrade` in the project
+ */
+
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Check whether worca is installed in the given project path.
+ */
+export function checkWorcaInstalled(projectPath) {
+  return existsSync(join(projectPath, '.claude', 'worca'));
+}
+
+/**
+ * Spawn `worca init --upgrade` in the target project directory.
+ * Optionally passes --source if a source repo path is provided.
+ *
+ * Returns { pid } immediately. Writes progress to a status file
+ * at <targetPath>/.worca/setup-status.json.
+ *
+ * @param {string} targetPath - The project root directory
+ * @param {{ source?: string }} opts - Optional source repo path
+ * @returns {{ pid: number }}
+ */
+export function runWorcaSetup(targetPath, opts = {}) {
+  // Ensure .worca dir exists for status file
+  const worcaDir = join(targetPath, '.worca');
+  mkdirSync(worcaDir, { recursive: true });
+
+  const statusFile = join(worcaDir, 'setup-status.json');
+
+  // Write initial status
+  writeFileSync(
+    statusFile,
+    `${JSON.stringify(
+      {
+        status: 'running',
+        started_at: new Date().toISOString(),
+        target: targetPath,
+      },
+      null,
+      2,
+    )}\n`,
+    'utf8',
+  );
+
+  const args = ['init', '--upgrade'];
+  if (opts.source) {
+    args.push('--source', opts.source);
+  }
+
+  const child = spawn('worca', args, {
+    detached: true,
+    stdio: 'ignore',
+    cwd: targetPath,
+    env: { ...process.env },
+  });
+
+  // On error, write failure status
+  child.on('error', (err) => {
+    try {
+      writeFileSync(
+        statusFile,
+        `${JSON.stringify(
+          {
+            status: 'error',
+            error: err.message || 'spawn failed',
+            finished_at: new Date().toISOString(),
+          },
+          null,
+          2,
+        )}\n`,
+        'utf8',
+      );
+    } catch {
+      /* best effort */
+    }
+  });
+
+  child.on('exit', (code) => {
+    const payload =
+      code !== 0
+        ? {
+            status: 'error',
+            error: `Process exited with code ${code}`,
+            finished_at: new Date().toISOString(),
+          }
+        : {
+            status: 'done',
+            finished_at: new Date().toISOString(),
+          };
+    try {
+      writeFileSync(
+        statusFile,
+        `${JSON.stringify(payload, null, 2)}\n`,
+        'utf8',
+      );
+    } catch {
+      /* best effort */
+    }
+  });
+
+  child.unref();
+
+  return { pid: child.pid };
+}

package/server/ws-beads-watcher.js

@@ -0,0 +1,62 @@
+/**
+ * Beads database watcher — monitors .beads/beads.db for changes.
+ * Watches the directory (not just the file) because SQLite WAL mode
+ * writes to beads.db-wal first.
+ */
+
+import { existsSync, watch } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { listIssues } from './beads-reader.js';
+
+const BEADS_DEBOUNCE_MS = 200;
+
+/**
+ * @param {{ worcaDir: string, broadcaster: { broadcast: Function }, projectId?: string }} deps
+ */
+export function createBeadsWatcher({ worcaDir, broadcaster, projectId }) {
+  const beadsDbPath = resolve(join(worcaDir, '..', '.beads', 'beads.db'));
+  const beadsDir = resolve(join(worcaDir, '..', '.beads'));
+  let beadsWatcher = null;
+  let BEADS_REFRESH_TIMER = null;
+
+  function scheduleBeadsRefresh() {
+    if (BEADS_REFRESH_TIMER) clearTimeout(BEADS_REFRESH_TIMER);
+    BEADS_REFRESH_TIMER = setTimeout(() => {
+      BEADS_REFRESH_TIMER = null;
+      try {
+        const issues = listIssues(beadsDbPath);
+        broadcaster.broadcast(
+          'beads-update',
+          {
+            issues,
+            dbExists: true,
+            dbPath: beadsDbPath,
+          },
+          projectId,
+        );
+      } catch {
+        /* ignore */
+      }
+    }, BEADS_DEBOUNCE_MS);
+  }
+
+  if (existsSync(beadsDir)) {
+    try {
+      beadsWatcher = watch(beadsDir, (_event, filename) => {
+        if (filename?.startsWith('beads.db')) scheduleBeadsRefresh();
+      });
+    } catch {
+      /* ignore */
+    }
+  }
+
+  function getBeadsDbPath() {
+    return beadsDbPath;
+  }
+
+  function destroy() {
+    if (beadsWatcher) beadsWatcher.close();
+  }
+
+  return { getBeadsDbPath, destroy };
+}

package/server/ws-broadcaster.js

@@ -0,0 +1,106 @@
+/**
+ * WebSocket broadcast utilities.
+ * Stateless — uses wss.clients and the subs WeakMap from client-manager.
+ *
+ * Protocol 2 clients receive an extra `project` field in broadcast messages.
+ * Protocol 1 clients receive messages identical to pre-multi-project behavior.
+ */
+
+/**
+ * @param {{ wss: import('ws').WebSocketServer, getSubs: Function }} deps
+ */
+export function createBroadcaster({ wss, getSubs }) {
+  /**
+   * Build a message envelope. For protocol 2 clients with a projectId,
+   * a `project` field is added to the top-level message.
+   */
+  function sendToClient(ws, baseMsg) {
+    const s = getSubs(ws);
+    if (s && s.protocolVersion >= 2 && s.projectId) {
+      ws.send(JSON.stringify({ ...baseMsg, project: s.projectId }));
+    } else {
+      ws.send(JSON.stringify(baseMsg));
+    }
+  }
+
+  function broadcast(type, payload, projectId) {
+    const base = {
+      id: `evt-${Date.now()}`,
+      ok: true,
+      type,
+      payload,
+    };
+    for (const ws of wss.clients) {
+      if (ws.readyState !== ws.OPEN) continue;
+      if (projectId) {
+        const s = getSubs(ws);
+        // Skip clients subscribed to a different project.
+        // Send to unscoped clients (protocol 1) and matching protocol 2 clients.
+        if (
+          s &&
+          s.protocolVersion >= 2 &&
+          s.projectId &&
+          s.projectId !== projectId
+        )
+          continue;
+      }
+      sendToClient(ws, base);
+    }
+  }
+
+  function broadcastToSubscribers(runId, type, payload) {
+    const base = {
+      id: `evt-${Date.now()}`,
+      ok: true,
+      type,
+      payload,
+    };
+    for (const ws of wss.clients) {
+      if (ws.readyState !== ws.OPEN) continue;
+      const s = getSubs(ws);
+      if (s && s.runId === runId) {
+        sendToClient(ws, base);
+      }
+    }
+  }
+
+  function broadcastToLogSubscribers(stage, type, payload, runId) {
+    const base = {
+      id: `evt-${Date.now()}`,
+      ok: true,
+      type,
+      payload,
+    };
+    for (const ws of wss.clients) {
+      if (ws.readyState !== ws.OPEN) continue;
+      const s = getSubs(ws);
+      if (s && (s.logStage === stage || s.logStage === '*')) {
+        if (runId && s.logRunId && s.logRunId !== runId) continue;
+        sendToClient(ws, base);
+      }
+    }
+  }
+
+  function broadcastPipelineEvent(runId, event) {
+    const base = {
+      id: `evt-${Date.now()}`,
+      ok: true,
+      type: 'pipeline-event',
+      payload: event,
+    };
+    for (const ws of wss.clients) {
+      if (ws.readyState !== ws.OPEN) continue;
+      const s = getSubs(ws);
+      if (s && s.eventsRunId === runId) {
+        sendToClient(ws, base);
+      }
+    }
+  }
+
+  return {
+    broadcast,
+    broadcastToSubscribers,
+    broadcastToLogSubscribers,
+    broadcastPipelineEvent,
+  };
+}

package/server/ws-client-manager.js

@@ -0,0 +1,129 @@
+/**
+ * WebSocket client subscription and heartbeat management.
+ * Owns the subs WeakMap that tracks per-client subscriptions.
+ * Tracks per-project client counts for activity-based tiering.
+ */
+
+/**
+ * @param {{ wss: import('ws').WebSocketServer }} deps
+ */
+export function createClientManager({ wss }) {
+  /** @type {WeakMap<import('ws').WebSocket, { runId: string | null, logStage: string | null, logRunId: string | null, eventsRunId: string | null, protocolVersion: number, projectId: string | null }>} */
+  const subs = new WeakMap();
+
+  /** @type {Map<string, number>} per-project connected client count */
+  const projectClientCounts = new Map();
+
+  /** @type {Set<(projectId: string, count: number) => void>} */
+  const clientCountHandlers = new Set();
+
+  function ensureSubs(ws) {
+    let s = subs.get(ws);
+    if (!s) {
+      s = {
+        runId: null,
+        logStage: null,
+        logRunId: null,
+        eventsRunId: null,
+        protocolVersion: 1,
+        projectId: null,
+      };
+      subs.set(ws, s);
+    }
+    return s;
+  }
+
+  function getSubs(ws) {
+    return subs.get(ws);
+  }
+
+  function deleteSubs(ws) {
+    const s = subs.get(ws);
+    if (s?.projectId) {
+      _decrementProject(s.projectId);
+    }
+    subs.delete(ws);
+  }
+
+  function setProtocol(ws, version, projectId) {
+    const s = ensureSubs(ws);
+    const oldProjectId = s.projectId;
+    s.protocolVersion = version;
+    s.projectId = projectId ?? null;
+
+    // Update project client counts
+    if (oldProjectId && oldProjectId !== projectId) {
+      _decrementProject(oldProjectId);
+    }
+    if (projectId && projectId !== oldProjectId) {
+      _incrementProject(projectId);
+    }
+  }
+
+  function _incrementProject(projectId) {
+    const current = projectClientCounts.get(projectId) || 0;
+    const newCount = current + 1;
+    projectClientCounts.set(projectId, newCount);
+    _notifyCountChange(projectId, newCount);
+  }
+
+  function _decrementProject(projectId) {
+    const current = projectClientCounts.get(projectId) || 0;
+    const newCount = Math.max(0, current - 1);
+    if (newCount === 0) {
+      projectClientCounts.delete(projectId);
+    } else {
+      projectClientCounts.set(projectId, newCount);
+    }
+    _notifyCountChange(projectId, newCount);
+  }
+
+  function _notifyCountChange(projectId, count) {
+    for (const fn of clientCountHandlers) {
+      try {
+        fn(projectId, count);
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+
+  function getProjectClientCount(projectId) {
+    return projectClientCounts.get(projectId) || 0;
+  }
+
+  function onClientCountChange(handler) {
+    clientCountHandlers.add(handler);
+    return () => {
+      clientCountHandlers.delete(handler);
+    };
+  }
+
+  // Heartbeat — ping all clients every 30s, terminate unresponsive ones
+  const heartbeat = setInterval(() => {
+    for (const ws of wss.clients) {
+      if (ws.isAlive === false) {
+        ws.terminate();
+        continue;
+      }
+      ws.isAlive = false;
+      ws.ping();
+    }
+  }, 30000);
+  heartbeat.unref?.();
+
+  function destroy() {
+    clearInterval(heartbeat);
+    clientCountHandlers.clear();
+  }
+
+  return {
+    ensureSubs,
+    getSubs,
+    deleteSubs,
+    setProtocol,
+    getProjectClientCount,
+    onClientCountChange,
+    destroy,
+  };
+}

package/server/ws-event-watcher.js

@@ -0,0 +1,124 @@
+/**
+ * Pipeline event file watcher — manages events.jsonl subscriptions.
+ * Owns the eventWatchers map and event reading/filtering logic.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { watchEvents } from './watcher.js';
+
+/**
+ * Convert a glob pattern (with * and **) to a RegExp for matching event type strings.
+ * - `*`  matches any sequence of non-dot characters
+ * - `**` matches any sequence of characters (including dots)
+ *
+ * @param {string} pattern
+ * @param {string} str
+ * @returns {boolean}
+ */
+export function matchesGlob(pattern, str) {
+  const regexStr = pattern
+    .split('**')
+    .map((part) =>
+      part
+        .split('*')
+        .map((s) => s.replace(/[.+^${}()|[\]\\]/g, '\\$&'))
+        .join('[^.]*'),
+    )
+    .join('.*');
+  return new RegExp(`^${regexStr}$`).test(str);
+}
+
+/**
+ * @param {{
+ *   broadcaster: { broadcastPipelineEvent: Function },
+ *   getSubs: Function,
+ *   wss: import('ws').WebSocketServer,
+ *   resolveRunDirById: Function
+ * }} deps
+ */
+export function createEventWatcher({
+  broadcaster,
+  getSubs,
+  wss,
+  resolveRunDirById,
+}) {
+  /** @type {Map<string, { close: () => void }>} */
+  const eventWatchers = new Map();
+
+  function readEventsFromFile(
+    runId,
+    { since_event_id, event_types, limit = 100 } = {},
+  ) {
+    const eventsPath = join(resolveRunDirById(runId), 'events.jsonl');
+    if (!existsSync(eventsPath)) return [];
+    try {
+      const content = readFileSync(eventsPath, 'utf8');
+      let events = [];
+      for (const line of content.split('\n')) {
+        if (!line.trim()) continue;
+        try {
+          events.push(JSON.parse(line));
+        } catch {
+          /* skip malformed */
+        }
+      }
+      if (since_event_id) {
+        const idx = events.findIndex((e) => e.event_id === since_event_id);
+        if (idx >= 0) events = events.slice(idx + 1);
+      }
+      if (event_types && event_types.length > 0) {
+        events = events.filter((e) =>
+          event_types.some((p) => matchesGlob(p, e.event_type)),
+        );
+      }
+      return events.slice(0, limit);
+    } catch {
+      return [];
+    }
+  }
+
+  function subscribeEvents(runId) {
+    if (!eventWatchers.has(runId)) {
+      const runDir = resolveRunDirById(runId);
+      const w = watchEvents(runDir, (event) =>
+        broadcaster.broadcastPipelineEvent(runId, event),
+      );
+      eventWatchers.set(runId, w);
+    }
+  }
+
+  function maybeCloseEventWatcher(runId) {
+    for (const ws of wss.clients) {
+      const s = getSubs(ws);
+      if (s?.eventsRunId === runId) return; // still in use
+    }
+    const w = eventWatchers.get(runId);
+    if (w) {
+      try {
+        w.close();
+      } catch {
+        /* ignore */
+      }
+      eventWatchers.delete(runId);
+    }
+  }
+
+  function destroy() {
+    for (const w of eventWatchers.values()) {
+      try {
+        w.close();
+      } catch {
+        /* ignore */
+      }
+    }
+    eventWatchers.clear();
+  }
+
+  return {
+    readEventsFromFile,
+    subscribeEvents,
+    maybeCloseEventWatcher,
+    destroy,
+  };
+}