@worca/ui 0.1.0-rc.1

package/server/ws-modular.js

@@ -0,0 +1,309 @@
+/**
+ * Modular WebSocket server — facade wiring 7 extracted modules.
+ * Drop-in replacement for ws-legacy.js with identical behavior.
+ *
+ * Supports multi-project mode via WatcherSet map when projects.d/ exists.
+ * Supports dynamic project add/remove via fs.watch on projects.d/.
+ */
+
+import { existsSync, watch } from 'node:fs';
+import { join } from 'node:path';
+import { WebSocketServer } from 'ws';
+import { readProjects, synthesizeDefaultProject } from './project-registry.js';
+import { TIER_FULL, TIER_POLLING, WatcherSet } from './watcher-set.js';
+import { createBroadcaster } from './ws-broadcaster.js';
+import { createClientManager } from './ws-client-manager.js';
+import { createMessageRouter } from './ws-message-router.js';
+import { resolveActiveRunDir } from './ws-status-watcher.js';
+
+export { resolveActiveRunDir };
+
+/**
+ * Attach a WebSocket server to an existing HTTP server.
+ *
+ * @param {import('node:http').Server} httpServer
+ * @param {{ worcaDir: string, settingsPath: string, prefsPath: string, prefsDir?: string }} config
+ */
+export function attachWsServer(httpServer, config) {
+  const {
+    worcaDir,
+    settingsPath,
+    prefsPath,
+    webhookInbox,
+    projectRoot,
+    prefsDir,
+  } = config;
+  const wss = new WebSocketServer({ server: httpServer, path: '/ws' });
+
+  // 1. Client manager — owns subs WeakMap and heartbeat
+  const clientManager = createClientManager({ wss });
+
+  // 2. Broadcaster — stateless, uses wss.clients + subs
+  const broadcaster = createBroadcaster({
+    wss,
+    getSubs: clientManager.getSubs,
+  });
+
+  // 3. Create WatcherSet(s) — one per project
+  /** @type {Map<string, WatcherSet>} */
+  const watcherSets = new Map();
+
+  const projects = prefsDir ? readProjects(prefsDir) : [];
+  if (projects.length > 0) {
+    // Multi-project mode — start in Polling tier (promoted on client subscribe)
+    for (const proj of projects) {
+      const ws = new WatcherSet(
+        proj.name,
+        proj.worcaDir || join(proj.path, '.worca'),
+        {
+          broadcaster,
+          getSubs: clientManager.getSubs,
+          wss,
+          settingsPath:
+            proj.settingsPath || join(proj.path, '.claude', 'settings.json'),
+          projectRoot: proj.path,
+          webhookInbox,
+        },
+      );
+      ws.create();
+      watcherSets.set(proj.name, ws);
+    }
+  } else {
+    // Single-project mode — start in Full tier (backward compatible)
+    const effectiveRoot =
+      projectRoot || (worcaDir ? join(worcaDir, '..') : process.cwd());
+    const synth = synthesizeDefaultProject(effectiveRoot);
+    const effectiveWorcaDir = worcaDir || synth.worcaDir;
+    const ws = new WatcherSet(synth.name, effectiveWorcaDir, {
+      broadcaster,
+      getSubs: clientManager.getSubs,
+      wss,
+      settingsPath,
+      projectRoot,
+      webhookInbox,
+    });
+    ws.create();
+    ws.setTier(TIER_FULL);
+    watcherSets.set(synth.name, ws);
+  }
+
+  // Default WatcherSet — used by message router (Phase 1a: UI is single-project)
+  let defaultWs = watcherSets.values().next().value;
+
+  // 4. Dynamic project watching — watch projects.d/ for add/remove
+  let dirWatcher = null;
+  let debounceTimer = null;
+
+  if (prefsDir) {
+    const projectsDir = join(prefsDir, 'projects.d');
+    try {
+      if (existsSync(projectsDir)) {
+        dirWatcher = watch(projectsDir, { persistent: false }, () => {
+          if (debounceTimer) clearTimeout(debounceTimer);
+          debounceTimer = setTimeout(() => {
+            debounceTimer = null;
+            _syncProjects();
+          }, 500);
+        });
+      }
+    } catch {
+      // fs.watch not supported or dir doesn't exist yet — skip
+    }
+  }
+
+  function _syncProjects() {
+    if (!prefsDir) return;
+    const freshProjects = readProjects(prefsDir);
+    const freshNames = new Set(freshProjects.map((p) => p.name));
+    const currentNames = new Set(watcherSets.keys());
+
+    // Add new projects
+    for (const proj of freshProjects) {
+      if (!currentNames.has(proj.name)) {
+        const ws = new WatcherSet(
+          proj.name,
+          proj.worcaDir || join(proj.path, '.worca'),
+          {
+            broadcaster,
+            getSubs: clientManager.getSubs,
+            wss,
+            settingsPath:
+              proj.settingsPath || join(proj.path, '.claude', 'settings.json'),
+            projectRoot: proj.path,
+            webhookInbox,
+          },
+        );
+        ws.create();
+        watcherSets.set(proj.name, ws);
+      }
+    }
+
+    // Remove deleted projects
+    for (const name of currentNames) {
+      if (!freshNames.has(name)) {
+        const wset = watcherSets.get(name);
+        if (wset) {
+          wset.destroy();
+          watcherSets.delete(name);
+        }
+      }
+    }
+
+    // Update default — set to null when all projects removed (fix #5)
+    if (watcherSets.size > 0) {
+      defaultWs = watcherSets.values().next().value;
+    } else {
+      defaultWs = null;
+    }
+
+    // Broadcast projects-updated to all clients
+    const projectList = freshProjects.map((p) => ({
+      name: p.name,
+      path: p.path,
+    }));
+    broadcaster.broadcast('projects-updated', { projects: projectList });
+  }
+
+  // 5. Tier management — promote/demote based on client subscriptions
+  clientManager.onClientCountChange((projectId, count) => {
+    const wset = watcherSets.get(projectId);
+    if (!wset) return;
+    if (count > 0 && wset.getTier() === TIER_POLLING) {
+      wset.setTier(TIER_FULL);
+    } else if (count === 0 && wset.getTier() === TIER_FULL) {
+      // Demote after a grace period to avoid flip-flop on page refresh
+      setTimeout(() => {
+        if (
+          clientManager.getProjectClientCount(projectId) === 0 &&
+          wset.getTier() === TIER_FULL
+        ) {
+          wset.setTier(TIER_POLLING);
+        }
+      }, 5000);
+    }
+  });
+
+  // 6. Message router — resolves project per-request via watcherSets
+  //    Pass defaultWs via getter so the router always sees the current value (fix #6)
+  const messageRouter = createMessageRouter({
+    watcherSets,
+    getDefaultWs: () => defaultWs,
+    prefsPath,
+    webhookInbox,
+    clientManager,
+    broadcaster,
+  });
+
+  /**
+   * Scoped scheduleRefresh: with projectName refreshes one, without refreshes all.
+   */
+  function scheduleRefresh(projectName) {
+    if (projectName) {
+      const ws = watcherSets.get(projectName);
+      if (ws) {
+        ws.scheduleRefresh();
+        return true;
+      }
+      return false;
+    }
+    for (const ws of watcherSets.values()) ws.scheduleRefresh();
+    return true;
+  }
+
+  // Connection lifecycle
+  wss.on('connection', (ws) => {
+    ws.isAlive = true;
+    clientManager.ensureSubs(ws);
+
+    // Send hello handshake to all clients (both single- and multi-project mode).
+    // Protocol 2 clients reply with hello-ack; protocol 1 clients ignore it.
+    ws.send(
+      JSON.stringify({
+        id: `evt-${Date.now()}`,
+        ok: true,
+        type: 'hello',
+        payload: {
+          protocol: 2,
+          capabilities: prefsDir ? ['multi-project'] : [],
+        },
+      }),
+    );
+
+    // Timeout: if no hello-ack in 2s, client stays at protocol 1 (legacy)
+    const helloTimeout = setTimeout(() => {
+      // No-op: client stays at protocol 1 by default
+    }, 2000);
+    ws._helloTimeout = helloTimeout;
+
+    ws.on('pong', () => {
+      ws.isAlive = true;
+    });
+
+    ws.on('message', (data) => {
+      messageRouter.handleMessage(ws, data);
+    });
+
+    ws.on('close', () => {
+      // Clear hello timeout if still pending (fix #17)
+      if (ws._helloTimeout) {
+        clearTimeout(ws._helloTimeout);
+        ws._helloTimeout = null;
+      }
+      const s = clientManager.getSubs(ws);
+      const eventsRunId = s?.eventsRunId;
+      // Resolve the correct project's WatcherSet for cleanup (fix #4)
+      const projectId = s?.projectId || null;
+      clientManager.deleteSubs(ws);
+      if (eventsRunId) {
+        const wset = (projectId && watcherSets.get(projectId)) || defaultWs;
+        if (wset?.eventWatcher) {
+          wset.eventWatcher.maybeCloseEventWatcher(eventsRunId);
+        }
+      }
+    });
+  });
+
+  wss.on('close', () => {
+    clientManager.destroy();
+    if (dirWatcher) {
+      try {
+        dirWatcher.close();
+      } catch {
+        /* ignore */
+      }
+      dirWatcher = null;
+    }
+    if (debounceTimer) {
+      clearTimeout(debounceTimer);
+      debounceTimer = null;
+    }
+    for (const ws of watcherSets.values()) {
+      ws.destroy();
+    }
+    watcherSets.clear();
+  });
+
+  /**
+   * Resolve which project a run belongs to by checking watcherSets.
+   * @param {string} runId
+   * @returns {string|null} projectId or null
+   */
+  function resolveRunProject(runId) {
+    if (!runId) return null;
+    for (const [projectId, wset] of watcherSets) {
+      const runsPath = join(wset.worcaDir, 'runs', runId);
+      const resultsPath = join(wset.worcaDir, 'results', runId);
+      if (existsSync(runsPath) || existsSync(resultsPath)) {
+        return projectId;
+      }
+    }
+    return null;
+  }
+
+  return {
+    wss,
+    broadcast: broadcaster.broadcast,
+    scheduleRefresh,
+    resolveRunProject,
+  };
+}

package/server/ws-status-watcher.js

@@ -0,0 +1,259 @@
+/**
+ * Status file watcher — monitors status.json and active_run for changes.
+ * Owns refresh scheduling, lastPipelineStatus tracking, and the status/activeRun FSWatchers.
+ */
+
+import { existsSync, readFileSync, watch } from 'node:fs';
+import { join } from 'node:path';
+import { readSettings } from './settings-reader.js';
+import { discoverRunsAsync } from './watcher.js';
+
+const REFRESH_DEBOUNCE_MS = 75;
+
+/**
+ * Resolve the active run directory for a given worca base dir.
+ * Returns `<worcaDir>/runs/<runId>` as long as runId is non-empty,
+ * without gating on the existence of status.json.
+ *
+ * @param {string} worcaDir
+ * @returns {string}
+ */
+export function resolveActiveRunDir(worcaDir) {
+  const activeRunPath = join(worcaDir, 'active_run');
+  if (existsSync(activeRunPath)) {
+    try {
+      const runId = readFileSync(activeRunPath, 'utf8').trim();
+      if (runId) return join(worcaDir, 'runs', runId);
+    } catch {
+      /* ignore */
+    }
+  }
+  return worcaDir; // legacy fallback
+}
+
+/**
+ * @param {{
+ *   worcaDir: string,
+ *   settingsPath: string,
+ *   broadcaster: { broadcast: Function, broadcastToSubscribers: Function },
+ *   getSubs: Function,
+ *   wss: import('ws').WebSocketServer,
+ *   onActiveRunChange?: () => void,
+ *   projectId?: string
+ * }} deps
+ */
+export function createStatusWatcher({
+  worcaDir,
+  settingsPath,
+  broadcaster,
+  getSubs,
+  wss,
+  onActiveRunChange,
+  projectId,
+}) {
+  let REFRESH_TIMER = null;
+  const lastPipelineStatus = new Map();
+  let statusWatcher = null;
+  let watchedRunDir = null;
+  let activeRunWatcher = null;
+  let runsDirWatcher = null;
+
+  function currentActiveRunId() {
+    if (!watchedRunDir) return null;
+    return watchedRunDir.split('/').pop() || null;
+  }
+
+  function _resolveActiveRunDir() {
+    return resolveActiveRunDir(worcaDir);
+  }
+
+  function scheduleRefresh() {
+    if (REFRESH_TIMER) clearTimeout(REFRESH_TIMER);
+    REFRESH_TIMER = setTimeout(async () => {
+      REFRESH_TIMER = null;
+      let settings = {};
+      try {
+        settings = readSettings(settingsPath);
+      } catch {
+        /* ignore */
+      }
+      try {
+        const runs = await discoverRunsAsync(worcaDir);
+        const subscribedIds = new Set();
+        for (const ws of wss.clients) {
+          const s = getSubs(ws);
+          if (s?.runId) subscribedIds.add(s.runId);
+        }
+        // Evict stale entries from lastPipelineStatus (fix #18)
+        const activeRunIds = new Set(runs.map((r) => r.id));
+        for (const id of lastPipelineStatus.keys()) {
+          if (!activeRunIds.has(id)) lastPipelineStatus.delete(id);
+        }
+
+        for (const run of runs) {
+          if (subscribedIds.has(run.id)) {
+            broadcaster.broadcastToSubscribers(run.id, 'run-snapshot', run);
+          }
+          const currStatus = run.pipeline_status;
+          if (currStatus !== undefined) {
+            const prevStatus = lastPipelineStatus.get(run.id);
+            if (prevStatus !== undefined && prevStatus !== currStatus) {
+              if (currStatus === 'paused') {
+                broadcaster.broadcastToSubscribers(run.id, 'pipeline-paused', {
+                  runId: run.id,
+                  pipeline_status: currStatus,
+                });
+              } else if (
+                currStatus === 'running' &&
+                (prevStatus === 'paused' || prevStatus === 'resuming')
+              ) {
+                broadcaster.broadcastToSubscribers(run.id, 'pipeline-resumed', {
+                  runId: run.id,
+                  pipeline_status: currStatus,
+                });
+              }
+            }
+            lastPipelineStatus.set(run.id, currStatus);
+          }
+        }
+        broadcaster.broadcast('runs-list', { runs, settings }, projectId);
+      } catch {
+        /* ignore */
+      }
+    }, REFRESH_DEBOUNCE_MS);
+  }
+
+  function setupStatusWatcher() {
+    if (statusWatcher) {
+      statusWatcher.close();
+      statusWatcher = null;
+    }
+    const runDir = _resolveActiveRunDir();
+    if (watchedRunDir !== null && runDir !== watchedRunDir) {
+      if (onActiveRunChange) onActiveRunChange();
+    }
+    watchedRunDir = runDir;
+
+    function tryWatch() {
+      if (statusWatcher) return;
+      try {
+        const statusFile = join(runDir, 'status.json');
+        if (existsSync(statusFile)) {
+          // Watch the file directly — on macOS, kqueue directory watchers
+          // don't fire for in-place content modifications of existing files.
+          // Watching the file itself ensures we detect status.json writes.
+          //
+          // IMPORTANT: On macOS kqueue, atomic writes (write-to-temp +
+          // rename-over) replace the inode.  After one 'rename' event the
+          // watcher goes dead because it tracked the old inode.  We
+          // re-establish the watcher on the new file after a short delay.
+          statusWatcher = watch(statusFile, (eventType) => {
+            scheduleRefresh();
+            if (eventType === 'rename') {
+              // File replaced (atomic write) — re-watch the new inode
+              try {
+                statusWatcher.close();
+              } catch {
+                /* ignore */
+              }
+              statusWatcher = null;
+              setTimeout(() => tryWatch(), 50);
+            }
+          });
+        } else if (existsSync(runDir)) {
+          // status.json doesn't exist yet — watch the directory for its creation,
+          // then switch to watching the file once it appears.
+          statusWatcher = watch(
+            runDir,
+            { recursive: false },
+            (_eventType, filename) => {
+              if (!filename || filename === 'status.json') {
+                const statusPath = join(runDir, 'status.json');
+                if (existsSync(statusPath)) {
+                  // status.json appeared — switch to file-level watch
+                  statusWatcher.close();
+                  statusWatcher = null;
+                  tryWatch();
+                }
+                scheduleRefresh();
+              }
+            },
+          );
+        } else {
+          setTimeout(() => {
+            if (_resolveActiveRunDir() === runDir) tryWatch();
+          }, 500);
+        }
+      } catch {
+        /* ignore */
+      }
+    }
+
+    tryWatch();
+  }
+
+  // Initialize status watcher
+  setupStatusWatcher();
+
+  // Watch worcaDir for active_run pointer changes
+  try {
+    if (existsSync(worcaDir)) {
+      activeRunWatcher = watch(
+        worcaDir,
+        { recursive: false },
+        (_eventType, filename) => {
+          if (
+            !filename ||
+            filename === 'active_run' ||
+            filename === 'status.json'
+          ) {
+            const newRunDir = _resolveActiveRunDir();
+            if (newRunDir !== watchedRunDir) {
+              setupStatusWatcher();
+            }
+            scheduleRefresh();
+          }
+        },
+      );
+    }
+  } catch {
+    /* ignore */
+  }
+
+  // Watch .worca/runs/ for status changes in ANY run (concurrent pipelines)
+  const runsDir = join(worcaDir, 'runs');
+  try {
+    if (existsSync(runsDir)) {
+      runsDirWatcher = watch(
+        runsDir,
+        { recursive: true },
+        (_eventType, filename) => {
+          if (!filename || filename.endsWith('status.json')) {
+            scheduleRefresh();
+          }
+        },
+      );
+    }
+  } catch {
+    /* ignore */
+  }
+
+  function getWatchedRunDir() {
+    return watchedRunDir;
+  }
+
+  function destroy() {
+    if (statusWatcher) statusWatcher.close();
+    if (activeRunWatcher) activeRunWatcher.close();
+    if (runsDirWatcher) runsDirWatcher.close();
+  }
+
+  return {
+    scheduleRefresh,
+    currentActiveRunId,
+    resolveActiveRunDir: _resolveActiveRunDir,
+    getWatchedRunDir,
+    lastPipelineStatus,
+    destroy,
+  };
+}

package/server/ws.js

@@ -0,0 +1,5 @@
+/**
+ * WebSocket server entry point.
+ */
+
+export { attachWsServer, resolveActiveRunDir } from './ws-modular.js';