@worca/ui 0.1.0-rc.1

package/server/watcher-set.js

@@ -0,0 +1,286 @@
+/**
+ * WatcherSet — groups all file watchers for a single project.
+ * Wraps createStatusWatcher, createLogWatcher, createBeadsWatcher, createEventWatcher
+ * into a single lifecycle-managed unit.
+ *
+ * Supports activity-based tiering:
+ * - Full:    all 4 watchers active (75ms debounce)
+ * - Polling: status watcher only (5s debounce)
+ */
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { MultiWatcher } from './multi-watcher.js';
+import { createBeadsWatcher } from './ws-beads-watcher.js';
+import { createEventWatcher } from './ws-event-watcher.js';
+import { createLogWatcher } from './ws-log-watcher.js';
+import { createStatusWatcher } from './ws-status-watcher.js';
+
+export const TIER_FULL = 'full';
+export const TIER_POLLING = 'polling';
+
+export class WatcherSet {
+  /**
+   * @param {string} projectId
+   * @param {string} worcaDir
+   * @param {{ broadcaster, getSubs, wss, settingsPath, projectRoot, webhookInbox }} deps
+   * @param {object} [factoryOverrides] - Optional factory overrides for testing
+   */
+  constructor(projectId, worcaDir, deps, factoryOverrides = {}) {
+    this.projectId = projectId;
+    this._worcaDir = worcaDir;
+    this._deps = deps;
+    this._closed = false;
+    this._tier = TIER_POLLING;
+    this._skipMultiWatcher = !!factoryOverrides._skipMultiWatcher;
+    const { _skipMultiWatcher, ...factories } = factoryOverrides;
+    this._factories = {
+      createStatusWatcher,
+      createLogWatcher,
+      createBeadsWatcher,
+      createEventWatcher,
+      ...factories,
+    };
+
+    /** @type {ReturnType<typeof createStatusWatcher> | null} */
+    this.statusWatcher = null;
+    /** @type {ReturnType<typeof createLogWatcher> | null} */
+    this.logWatcher = null;
+    /** @type {ReturnType<typeof createBeadsWatcher> | null} */
+    this.beadsWatcher = null;
+    /** @type {ReturnType<typeof createEventWatcher> | null} */
+    this.eventWatcher = null;
+    /** @type {MultiWatcher | null} */
+    this.multiWatcher = null;
+  }
+
+  get worcaDir() {
+    return this._worcaDir;
+  }
+  get settingsPath() {
+    return this._deps.settingsPath;
+  }
+  get projectRoot() {
+    return this._deps.projectRoot;
+  }
+
+  /** Get current tier. */
+  getTier() {
+    return this._tier;
+  }
+
+  /**
+   * Set tier. Promote to Full creates missing watchers, demote to Polling
+   * destroys log/beads/event watchers.
+   */
+  setTier(tier) {
+    if (tier === this._tier || this._closed) return;
+    const oldTier = this._tier;
+    this._tier = tier;
+
+    if (tier === TIER_FULL && oldTier === TIER_POLLING) {
+      // Promote: create log, beads, event watchers
+      this._createSecondaryWatchers();
+    } else if (tier === TIER_POLLING && oldTier === TIER_FULL) {
+      // Demote: destroy log, beads, event watchers
+      this._destroySecondaryWatchers();
+    }
+  }
+
+  /** Create all watchers. Starts in current tier (creates status always, others only if Full). */
+  create() {
+    this._createStatusWatcher();
+    if (this._tier === TIER_FULL) {
+      this._createSecondaryWatchers();
+    }
+    // Start multi-pipeline watcher (skip for pipeline-level WatcherSets to avoid recursion)
+    if (!this._skipMultiWatcher) {
+      this._createMultiWatcher();
+    }
+  }
+
+  /** Create multi-pipeline watcher for this project's .worca/multi/pipelines.d/. */
+  _createMultiWatcher() {
+    try {
+      this.multiWatcher = new MultiWatcher(
+        this.projectId,
+        this._worcaDir,
+        this._deps,
+      );
+      this.multiWatcher.start();
+    } catch (err) {
+      console.error(
+        `[WatcherSet:${this.projectId}] multiWatcher failed:`,
+        err.message,
+      );
+      this.multiWatcher = null;
+    }
+  }
+
+  /** Create status watcher (always needed). */
+  _createStatusWatcher() {
+    const { broadcaster, getSubs, wss, settingsPath } = this._deps;
+    const worcaDir = this._worcaDir;
+
+    try {
+      this.statusWatcher = this._factories.createStatusWatcher({
+        worcaDir,
+        settingsPath,
+        broadcaster,
+        getSubs,
+        wss,
+        projectId: this.projectId,
+        onActiveRunChange: () => {
+          if (this.logWatcher) this.logWatcher.clearLogWatchers();
+        },
+      });
+    } catch (err) {
+      console.error(
+        `[WatcherSet:${this.projectId}] statusWatcher failed:`,
+        err.message,
+      );
+      this.statusWatcher = null;
+    }
+  }
+
+  /** Create secondary watchers (log, beads, event). */
+  _createSecondaryWatchers() {
+    const { broadcaster, getSubs, wss } = this._deps;
+    const worcaDir = this._worcaDir;
+
+    // Log watcher
+    if (!this.logWatcher) {
+      try {
+        this.logWatcher = this._factories.createLogWatcher({
+          broadcaster,
+          resolveActiveRunDir: this.statusWatcher
+            ? this.statusWatcher.resolveActiveRunDir
+            : () => worcaDir,
+          worcaDir,
+          currentActiveRunId: this.statusWatcher
+            ? this.statusWatcher.currentActiveRunId
+            : () => null,
+        });
+      } catch (err) {
+        console.error(
+          `[WatcherSet:${this.projectId}] logWatcher failed:`,
+          err.message,
+        );
+        this.logWatcher = null;
+      }
+    }
+
+    // Beads watcher
+    if (!this.beadsWatcher) {
+      try {
+        this.beadsWatcher = this._factories.createBeadsWatcher({
+          worcaDir,
+          broadcaster,
+          projectId: this.projectId,
+        });
+      } catch (err) {
+        console.error(
+          `[WatcherSet:${this.projectId}] beadsWatcher failed:`,
+          err.message,
+        );
+        this.beadsWatcher = null;
+      }
+    }
+
+    // Event watcher
+    if (!this.eventWatcher) {
+      try {
+        const resolveRunDirById = (runId) => {
+          const candidates = [
+            join(worcaDir, 'runs', runId),
+            join(worcaDir, 'results', runId),
+          ];
+          for (const c of candidates) {
+            if (existsSync(c)) return c;
+          }
+          return join(worcaDir, 'runs', runId);
+        };
+
+        this.eventWatcher = this._factories.createEventWatcher({
+          broadcaster,
+          getSubs,
+          wss,
+          resolveRunDirById,
+        });
+      } catch (err) {
+        console.error(
+          `[WatcherSet:${this.projectId}] eventWatcher failed:`,
+          err.message,
+        );
+        this.eventWatcher = null;
+      }
+    }
+  }
+
+  /** Destroy secondary watchers (keep status). */
+  _destroySecondaryWatchers() {
+    for (const w of [this.logWatcher, this.beadsWatcher, this.eventWatcher]) {
+      try {
+        w?.destroy();
+      } catch {
+        // ignore cleanup errors
+      }
+    }
+    this.logWatcher = null;
+    this.beadsWatcher = null;
+    this.eventWatcher = null;
+  }
+
+  /** Destroy all child watchers. Idempotent. */
+  destroy() {
+    if (this._closed) return;
+    this._closed = true;
+
+    if (this.multiWatcher) {
+      try {
+        this.multiWatcher.destroy();
+      } catch {
+        // ignore cleanup errors
+      }
+      this.multiWatcher = null;
+    }
+
+    for (const w of [
+      this.statusWatcher,
+      this.logWatcher,
+      this.beadsWatcher,
+      this.eventWatcher,
+    ]) {
+      try {
+        w?.destroy();
+      } catch {
+        // ignore cleanup errors
+      }
+    }
+  }
+
+  /** Check if this WatcherSet is still usable. */
+  isAlive() {
+    return !this._closed && existsSync(this._worcaDir);
+  }
+
+  /** Approximate number of active watcher modules. */
+  getWatcherCount() {
+    let count = 0;
+    if (this.statusWatcher) count++;
+    if (this.logWatcher) count++;
+    if (this.beadsWatcher) count++;
+    if (this.eventWatcher) count++;
+    return count;
+  }
+
+  /** Get multi-pipeline watcher (may be null for pipeline-level WatcherSets). */
+  getMultiWatcher() {
+    return this.multiWatcher;
+  }
+
+  /** Delegate to status watcher's scheduleRefresh. */
+  scheduleRefresh() {
+    this.statusWatcher?.scheduleRefresh();
+  }
+}

package/server/watcher.js

@@ -0,0 +1,357 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readdirSync, readFileSync, watch } from 'node:fs';
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+export function createRunId(status) {
+  // Prefer run_id from status (new per-run format)
+  if (status.run_id) return status.run_id;
+  // Legacy: hash-based ID
+  const key = `${status.started_at}:${status.work_request?.title || ''}`;
+  return createHash('sha256').update(key).digest('hex').slice(0, 12);
+}
+
+function isTerminal(status) {
+  if (status.completed_at) return true;
+  if (!status.stages) return false;
+  const values = Object.values(status.stages);
+  return (
+    values.length > 0 &&
+    values.every(
+      (s) =>
+        s.status === 'completed' ||
+        s.status === 'error' ||
+        s.status === 'interrupted',
+    )
+  );
+}
+
+function isPipelineRunning(worcaDir) {
+  const pidPath = join(worcaDir, 'pipeline.pid');
+  if (!existsSync(pidPath)) return false;
+  try {
+    const pid = parseInt(readFileSync(pidPath, 'utf8').trim(), 10);
+    process.kill(pid, 0); // signal 0 = check if alive
+    return true;
+  } catch {
+    return false; // stale PID or unreadable
+  }
+}
+
+export function discoverRuns(worcaDir) {
+  const runs = [];
+  const seenIds = new Set();
+  const pipelineRunning = isPipelineRunning(worcaDir);
+
+  // 1. Check active_run pointer for the current run
+  const activeRunPath = join(worcaDir, 'active_run');
+  if (existsSync(activeRunPath)) {
+    try {
+      const activeId = readFileSync(activeRunPath, 'utf8').trim();
+      const candidate = join(worcaDir, 'runs', activeId, 'status.json');
+      if (existsSync(candidate)) {
+        const status = JSON.parse(readFileSync(candidate, 'utf8'));
+        const active = !isTerminal(status) && pipelineRunning;
+        const id = createRunId(status);
+        runs.push({ id, active, ...status });
+        seenIds.add(id);
+      }
+    } catch {
+      /* ignore */
+    }
+  }
+
+  // 2. Scan .worca/runs/ for other runs
+  const runsDir = join(worcaDir, 'runs');
+  if (existsSync(runsDir)) {
+    for (const entry of readdirSync(runsDir)) {
+      const statusPath = join(runsDir, entry, 'status.json');
+      if (!existsSync(statusPath)) continue;
+      try {
+        const status = JSON.parse(readFileSync(statusPath, 'utf8'));
+        const id = createRunId(status);
+        if (seenIds.has(id)) continue;
+        seenIds.add(id);
+        const active =
+          !isTerminal(status) && status.pipeline_status === 'running';
+        runs.push({ id, active, ...status });
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+
+  // 3. Legacy: flat .worca/status.json
+  const statusPath = join(worcaDir, 'status.json');
+  if (existsSync(statusPath)) {
+    try {
+      const status = JSON.parse(readFileSync(statusPath, 'utf8'));
+      const id = createRunId(status);
+      if (!seenIds.has(id)) {
+        const active = !isTerminal(status) && pipelineRunning;
+        runs.push({ id, active, ...status });
+        seenIds.add(id);
+      }
+    } catch {
+      /* ignore malformed */
+    }
+  }
+
+  // 4. Results: handle both dir format (results/{id}/status.json) and file format (results/{id}.json)
+  const resultsDir = join(worcaDir, 'results');
+  if (existsSync(resultsDir)) {
+    for (const entry of readdirSync(resultsDir, { withFileTypes: true })) {
+      try {
+        if (entry.isFile() && entry.name.endsWith('.json')) {
+          // Legacy file format
+          const data = JSON.parse(
+            readFileSync(join(resultsDir, entry.name), 'utf8'),
+          );
+          if (data.started_at) {
+            const id = createRunId(data);
+            if (!seenIds.has(id)) {
+              seenIds.add(id);
+              runs.push({ id, active: false, ...data });
+            }
+          }
+        } else if (entry.isDirectory()) {
+          // New dir format
+          const sp = join(resultsDir, entry.name, 'status.json');
+          if (existsSync(sp)) {
+            const data = JSON.parse(readFileSync(sp, 'utf8'));
+            const id = createRunId(data);
+            if (!seenIds.has(id)) {
+              seenIds.add(id);
+              runs.push({ id, active: false, ...data });
+            }
+          }
+        }
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+
+  return runs;
+}
+
+/**
+ * Async version of discoverRuns — avoids blocking the event loop.
+ * Used by the status watcher's debounced refresh.
+ */
+export async function discoverRunsAsync(worcaDir) {
+  const runs = [];
+  const seenIds = new Set();
+  const pipelineRunning = isPipelineRunning(worcaDir); // cheap check (one stat + one kill)
+
+  // 1. Active run
+  const activeRunPath = join(worcaDir, 'active_run');
+  try {
+    const activeId = (await readFile(activeRunPath, 'utf8')).trim();
+    const candidate = join(worcaDir, 'runs', activeId, 'status.json');
+    const status = JSON.parse(await readFile(candidate, 'utf8'));
+    const active = !isTerminal(status) && pipelineRunning;
+    const id = createRunId(status);
+    runs.push({ id, active, ...status });
+    seenIds.add(id);
+  } catch {
+    /* ignore */
+  }
+
+  // 2. Scan .worca/runs/
+  const runsDir = join(worcaDir, 'runs');
+  try {
+    const entries = await readdir(runsDir);
+    const readPromises = entries.map(async (entry) => {
+      try {
+        const statusPath = join(runsDir, entry, 'status.json');
+        const status = JSON.parse(await readFile(statusPath, 'utf8'));
+        return status;
+      } catch {
+        return null;
+      }
+    });
+    for (const status of await Promise.all(readPromises)) {
+      if (!status) continue;
+      const id = createRunId(status);
+      if (seenIds.has(id)) continue;
+      seenIds.add(id);
+      const active =
+        !isTerminal(status) && status.pipeline_status === 'running';
+      runs.push({ id, active, ...status });
+    }
+  } catch {
+    /* ignore */
+  }
+
+  // 3. Legacy flat status.json
+  try {
+    const status = JSON.parse(
+      await readFile(join(worcaDir, 'status.json'), 'utf8'),
+    );
+    const id = createRunId(status);
+    if (!seenIds.has(id)) {
+      const active = !isTerminal(status) && pipelineRunning;
+      runs.push({ id, active, ...status });
+      seenIds.add(id);
+    }
+  } catch {
+    /* ignore */
+  }
+
+  // 4. Results
+  const resultsDir = join(worcaDir, 'results');
+  try {
+    const entries = await readdir(resultsDir, { withFileTypes: true });
+    const readPromises = entries.map(async (entry) => {
+      try {
+        if (entry.isFile() && entry.name.endsWith('.json')) {
+          return JSON.parse(
+            await readFile(join(resultsDir, entry.name), 'utf8'),
+          );
+        }
+        if (entry.isDirectory()) {
+          const sp = join(resultsDir, entry.name, 'status.json');
+          return JSON.parse(await readFile(sp, 'utf8'));
+        }
+      } catch {
+        /* ignore */
+      }
+      return null;
+    });
+    for (const data of await Promise.all(readPromises)) {
+      if (!data || !data.started_at) continue;
+      const id = createRunId(data);
+      if (!seenIds.has(id)) {
+        seenIds.add(id);
+        runs.push({ id, active: false, ...data });
+      }
+    }
+  } catch {
+    /* ignore */
+  }
+
+  return runs;
+}
+
+/**
+ * Watch {runDir}/events.jsonl for new lines (byte-offset tracking).
+ * Handles file creation if the file doesn't exist yet.
+ * Calls callback(event) for each parsed JSON line; skips malformed lines.
+ *
+ * @param {string} runDir - Run directory that may contain events.jsonl
+ * @param {(event: object) => void} callback
+ * @returns {{ close: () => void }}
+ */
+export function watchEvents(runDir, callback) {
+  const eventsPath = join(runDir, 'events.jsonl');
+  let byteOffset = 0;
+  let fileWatcher = null;
+  let dirWatcher = null;
+  let closed = false;
+
+  function processNewContent() {
+    if (closed) return;
+    try {
+      if (!existsSync(eventsPath)) return;
+      const buf = readFileSync(eventsPath);
+      if (buf.length <= byteOffset) return;
+      const newContent = buf.slice(byteOffset).toString('utf8');
+      byteOffset = buf.length;
+      for (const line of newContent.split('\n')) {
+        if (!line.trim()) continue;
+        try {
+          callback(JSON.parse(line));
+        } catch {
+          /* skip malformed */
+        }
+      }
+    } catch {
+      /* ignore read errors */
+    }
+  }
+
+  function startFileWatcher() {
+    if (closed || fileWatcher) return;
+    try {
+      fileWatcher = watch(eventsPath, (eventType) => {
+        if (eventType === 'change') {
+          processNewContent();
+        } else if (eventType === 'rename') {
+          // File deleted or recreated — reset and retry
+          if (fileWatcher) {
+            try {
+              fileWatcher.close();
+            } catch {
+              /* ignore */
+            }
+            fileWatcher = null;
+          }
+          setTimeout(() => {
+            if (!closed && existsSync(eventsPath)) {
+              startFileWatcher();
+              processNewContent();
+            }
+          }, 100);
+        }
+      });
+    } catch {
+      /* ignore — file may have been deleted */
+    }
+  }
+
+  if (existsSync(eventsPath)) {
+    // Start from current end of file (tail only new content)
+    try {
+      byteOffset = readFileSync(eventsPath).length;
+    } catch {
+      /* ignore */
+    }
+    startFileWatcher();
+  }
+
+  // Watch the run directory so we detect events.jsonl being created
+  if (existsSync(runDir)) {
+    try {
+      dirWatcher = watch(
+        runDir,
+        { recursive: false },
+        (_eventType, filename) => {
+          if (
+            filename === 'events.jsonl' &&
+            existsSync(eventsPath) &&
+            !fileWatcher
+          ) {
+            byteOffset = 0; // Newly created — read from the beginning
+            startFileWatcher();
+            processNewContent();
+          }
+        },
+      );
+    } catch {
+      /* ignore */
+    }
+  }
+
+  return {
+    close() {
+      closed = true;
+      if (fileWatcher) {
+        try {
+          fileWatcher.close();
+        } catch {
+          /* ignore */
+        }
+        fileWatcher = null;
+      }
+      if (dirWatcher) {
+        try {
+          dirWatcher.close();
+        } catch {
+          /* ignore */
+        }
+        dirWatcher = null;
+      }
+    },
+  };
+}

package/server/webhook-inbox.js

@@ -0,0 +1,59 @@
+/**
+ * In-memory ring buffer store for webhook inbox events.
+ * No persistence — cleared on server restart.
+ */
+
+export function createInbox(maxSize = 500) {
+  const events = [];
+  let nextId = 1;
+  let controlAction = 'continue'; // 'continue' | 'pause' | 'abort'
+
+  return {
+    push(event) {
+      const stored = {
+        id: nextId++,
+        receivedAt: new Date().toISOString(),
+        headers: event.headers || {},
+        envelope: event.envelope || {},
+        projectId: event.projectId || null,
+        controlResponse: { action: controlAction },
+      };
+      events.push(stored);
+      if (events.length > maxSize) {
+        events.splice(0, events.length - maxSize);
+      }
+      return stored;
+    },
+
+    list(sinceId, projectId) {
+      let result = events;
+      if (sinceId != null) {
+        result = result.filter((e) => e.id > sinceId);
+      }
+      if (projectId) {
+        result = result.filter(
+          (e) => !e.projectId || e.projectId === projectId,
+        );
+      }
+      return [...result];
+    },
+
+    clear() {
+      events.length = 0;
+    },
+
+    size() {
+      return events.length;
+    },
+
+    getControlAction() {
+      return controlAction;
+    },
+
+    setControlAction(action) {
+      if (['continue', 'pause', 'abort'].includes(action)) {
+        controlAction = action;
+      }
+    },
+  };
+}