@worca/ui 0.9.0 → 0.11.0

package/server/app.js

@@ -2,13 +2,15 @@
 
 import { execFileSync } from 'node:child_process';
 import { createHmac, randomUUID } from 'node:crypto';
-import { existsSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { basename, dirname, isAbsolute, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import express from 'express';
 
 import { dbExists, getIssue, listIssues } from './beads-reader.js';
+import { RAW_BODY } from './integrations/index.js';
+import { verify } from './integrations/verify.js';
 import { ProcessManager } from './process-manager.js';
 import { scanDirectory } from './project-registry.js';
 import {
@@ -16,19 +18,34 @@ import {
   createProjectScopedRoutes,
   projectResolver,
 } from './project-routes.js';
+import { validateIntegrationsConfig } from './settings-validator.js';
 import { discoverSubagents } from './subagents-discovery.js';
+import { checkWorcaVersion } from './version-check.js';
 import { getVersionInfo } from './versions.js';
 import { createInbox } from './webhook-inbox.js';
 
 export function createApp(options = {}) {
   const app = express();
   const appDir = join(dirname(fileURLToPath(import.meta.url)), '..', 'app');
-  const { settingsPath, worcaDir, projectRoot, prefsDir } = options;
+  const {
+    settingsPath,
+    worcaDir,
+    projectRoot,
+    prefsDir,
+    serverHost,
+    serverPort,
+  } = options;
   // subagentDirs is a test-injection seam; production calls omit it and we
   // resolve from homedir() + projectRoot.
   const subagentDirs = options.subagentDirs || null;
 
-  app.use(express.json());
+  app.use(
+    express.json({
+      verify: (req, _res, buf) => {
+        req.rawBody = buf;
+      },
+    }),
+  );
 
   // ─── Security headers ──────────────────────────────────────────────────
   app.use((_req, res, next) => {
@@ -89,12 +106,13 @@ export function createApp(options = {}) {
           ? new ProcessManager({
               worcaDir,
               projectRoot: projectRoot || process.cwd(),
+              settingsPath,
             })
           : null,
       };
       next();
     },
-    createProjectScopedRoutes(),
+    createProjectScopedRoutes({ serverHost, serverPort }),
   );
 
   // ─── Unique routes (not in project-scoped router) ──────────────────────
@@ -282,6 +300,16 @@ export function createApp(options = {}) {
 
   // POST /api/webhooks/inbox — receive webhook events
   app.post('/api/webhooks/inbox', (req, res) => {
+    const integrations = app.locals.integrations;
+    if (integrations?.strictInboxVerification) {
+      const ok = verify(
+        req.rawBody || Buffer.alloc(0),
+        req.headers['x-worca-signature'],
+        integrations.secrets || [],
+      );
+      if (!ok)
+        return res.status(401).json({ ok: false, error: 'invalid signature' });
+    }
     const headers = {
       'x-worca-event': req.headers['x-worca-event'] || '',
       'x-worca-delivery': req.headers['x-worca-delivery'] || '',
@@ -298,9 +326,11 @@ export function createApp(options = {}) {
       envelope: req.body || {},
       projectId,
     });
+    if (req.rawBody) stored[RAW_BODY] = req.rawBody;
     if (app.locals.broadcast) {
       app.locals.broadcast('webhook-inbox-event', stored);
     }
+    app.locals.integrations?.onEvent(stored);
     res.json({ control: { action: webhookInbox.getControlAction() } });
   });
 
@@ -332,6 +362,16 @@ export function createApp(options = {}) {
 
   // PUT /api/webhooks/inbox/control — set control action
   app.put('/api/webhooks/inbox/control', (req, res) => {
+    const integrations = app.locals.integrations;
+    if (integrations?.strictInboxVerification) {
+      const ok = verify(
+        req.rawBody || Buffer.alloc(0),
+        req.headers['x-worca-signature'],
+        integrations.secrets || [],
+      );
+      if (!ok)
+        return res.status(401).json({ ok: false, error: 'invalid signature' });
+    }
     const { action } = req.body || {};
     if (!['continue', 'pause', 'abort'].includes(action)) {
       return res.status(400).json({
@@ -464,6 +504,10 @@ export function createApp(options = {}) {
   app.get('/api/versions', async (req, res) => {
     const force = req.query.force === '1';
     const prefsPath = prefsDir ? join(prefsDir, 'preferences.json') : null;
+    // Re-check installed worca-cc version on force refresh
+    if (force) {
+      app.locals.worcaVersion = await checkWorcaVersion();
+    }
     const worcaVersion = app.locals.worcaVersion || null;
     try {
       const data = await getVersionInfo({ prefsPath, worcaVersion, force });
@@ -475,14 +519,255 @@ export function createApp(options = {}) {
 
   // ─── Multi-project routes ──────────────────────────────────────────────
   if (prefsDir) {
-    app.use('/api/projects', createProjectRoutes({ prefsDir, projectRoot }));
+    app.use(
+      '/api/projects',
+      createProjectRoutes({ prefsDir, projectRoot, serverHost, serverPort }),
+    );
     app.use(
       '/api/projects/:projectId',
       projectResolver({ prefsDir, projectRoot }),
-      createProjectScopedRoutes({ prefsDir }),
+      createProjectScopedRoutes({ prefsDir, serverHost, serverPort }),
     );
   }
 
+  // POST /api/integrations/telegram/detect — find chat IDs from recent messages.
+  // If the Telegram adapter is running, temporarily pauses its poll loop so
+  // getUpdates returns results instead of being consumed by the long-poller.
+  app.post('/api/integrations/telegram/detect', async (req, res) => {
+    let token = req.body?.token;
+    if (!token) {
+      try {
+        const cfgRaw = readFileSync(
+          join(prefsDir, 'integrations', 'config.json'),
+          'utf8',
+        );
+        token = JSON.parse(cfgRaw).telegram?.bot_token;
+      } catch {
+        /* no config */
+      }
+    }
+    if (!token) token = process.env.TELEGRAM_BOT_TOKEN;
+    if (!token) {
+      return res.status(400).json({ error: 'No bot token provided' });
+    }
+
+    // Pause the running adapter so getUpdates isn't consumed by the poll loop
+    const integrations = app.locals.integrations;
+    const adapterEntry = integrations?._getAdapter?.('telegram');
+    let wasStopped = false;
+    if (adapterEntry) {
+      try {
+        await adapterEntry.adapter.stop();
+        wasStopped = true;
+        // Brief delay to let the in-flight long-poll request complete
+        await new Promise((r) => setTimeout(r, 200));
+      } catch {
+        /* ignore */
+      }
+    }
+
+    try {
+      const meRes = await fetch(`https://api.telegram.org/bot${token}/getMe`);
+      const me = await meRes.json();
+      const botUsername = me.ok ? me.result.username : null;
+
+      const updRes = await fetch(
+        `https://api.telegram.org/bot${token}/getUpdates?timeout=0&limit=20`,
+      );
+      const upd = await updRes.json();
+
+      const chats = [];
+      if (upd.ok) {
+        for (const u of upd.result) {
+          const msg = u.message;
+          if (msg?.chat?.id) {
+            const existing = chats.find((c) => c.id === msg.chat.id);
+            if (!existing) {
+              chats.push({
+                id: msg.chat.id,
+                type: msg.chat.type,
+                title:
+                  msg.chat.title || msg.chat.first_name || String(msg.chat.id),
+              });
+            }
+          }
+        }
+      }
+
+      res.json({ ok: true, botUsername, chats });
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    } finally {
+      // Restart the adapter if we paused it
+      if (wasStopped && adapterEntry) {
+        adapterEntry.adapter.start().catch(() => {});
+      }
+    }
+  });
+
+  // GET /api/integrations/status — adapter states, chat states, counters
+  app.get('/api/integrations/status', (_req, res) => {
+    const integrations = app.locals.integrations;
+    if (!integrations) return res.json({ enabled: false });
+    res.json(integrations.status());
+  });
+
+  // GET /api/integrations/config — return saved config (secrets redacted)
+  app.get('/api/integrations/config', (_req, res) => {
+    const configPath = join(prefsDir, 'integrations', 'config.json');
+    let cfg;
+    try {
+      cfg = JSON.parse(readFileSync(configPath, 'utf8'));
+    } catch {
+      return res.json({});
+    }
+    res.json(cfg);
+  });
+
+  // DELETE /api/integrations/config/:adapter — remove an adapter
+  // PATCH /api/integrations/config/:adapter/enabled — toggle adapter on/off
+  app.patch('/api/integrations/config/:adapter/enabled', async (req, res) => {
+    const { adapter } = req.params;
+    const { enabled } = req.body;
+    if (typeof enabled !== 'boolean') {
+      return res.status(400).json({ error: 'enabled must be a boolean' });
+    }
+    const adapterKeys = ['telegram', 'discord', 'slack'];
+    if (!adapterKeys.includes(adapter)) {
+      return res.status(400).json({ error: `Invalid adapter: ${adapter}` });
+    }
+    const configPath = join(prefsDir, 'integrations', 'config.json');
+    let cfg;
+    try {
+      cfg = JSON.parse(readFileSync(configPath, 'utf8'));
+    } catch {
+      return res.status(404).json({ error: 'No integrations config' });
+    }
+    if (!cfg[adapter]) {
+      return res
+        .status(404)
+        .json({ error: `Adapter ${adapter} not configured` });
+    }
+    cfg[adapter].enabled = enabled;
+    writeFileSync(configPath, `${JSON.stringify(cfg, null, 2)}\n`);
+
+    // Hot-reload: if disabling, remove the adapter; if enabling, reload it
+    if (app.locals.ensureIntegrations) app.locals.ensureIntegrations();
+    if (enabled) {
+      if (app.locals.integrations?.reloadAdapter) {
+        await app.locals.integrations.reloadAdapter(adapter);
+      }
+    } else {
+      if (app.locals.integrations?.removeAdapter) {
+        await app.locals.integrations.removeAdapter(adapter);
+      }
+    }
+    res.json({ ok: true, enabled });
+  });
+
+  app.delete('/api/integrations/config/:adapter', async (req, res) => {
+    const { adapter } = req.params;
+    const adapterKeys = ['telegram', 'discord', 'slack'];
+    if (!adapterKeys.includes(adapter)) {
+      return res.status(400).json({ error: `Invalid adapter: ${adapter}` });
+    }
+    const configDir = join(prefsDir, 'integrations');
+    const configPath = join(configDir, 'config.json');
+    let cfg;
+    try {
+      cfg = JSON.parse(readFileSync(configPath, 'utf8'));
+    } catch {
+      return res.json({ ok: true });
+    }
+    delete cfg[adapter];
+    const hasAdapters = adapterKeys.some((k) => cfg[k]?.enabled);
+    if (!hasAdapters) cfg.enabled = false;
+    try {
+      writeFileSync(configPath, `${JSON.stringify(cfg, null, 2)}\n`);
+    } catch (err) {
+      return res
+        .status(500)
+        .json({ error: `Failed to write config: ${err.message}` });
+    }
+    if (app.locals.integrations?.removeAdapter) {
+      await app.locals.integrations.removeAdapter(adapter);
+    }
+    res.json({ ok: true });
+  });
+
+  // POST /api/integrations/config — save adapter config
+  const ADAPTER_SCHEMA = {
+    telegram: { tokenKey: 'bot_token', idKey: 'chat_id' },
+    discord: { tokenKey: 'bot_token', idKey: 'channel_id' },
+    slack: { tokenKey: 'webhook_url', idKey: 'chat_id' },
+  };
+
+  app.post('/api/integrations/config', async (req, res) => {
+    const { adapter, token, chatId, events } = req.body;
+    if (
+      !adapter ||
+      !token ||
+      !chatId ||
+      !Array.isArray(events) ||
+      events.length === 0
+    ) {
+      return res.status(400).json({
+        error: 'Missing required fields: adapter, token, chatId, events',
+      });
+    }
+    const schema = ADAPTER_SCHEMA[adapter];
+    if (!schema) {
+      return res.status(400).json({
+        error: `Invalid adapter: ${adapter}. Must be one of: ${Object.keys(ADAPTER_SCHEMA).join(', ')}`,
+      });
+    }
+
+    const configDir = join(prefsDir, 'integrations');
+    const configPath = join(configDir, 'config.json');
+
+    // Load existing config or start fresh
+    let cfg = { schema_version: 1, enabled: true };
+    try {
+      const raw = readFileSync(configPath, 'utf8');
+      cfg = JSON.parse(raw);
+    } catch {
+      /* start fresh */
+    }
+
+    // Build adapter block — store token directly in config
+    const adapterBlock = { enabled: true, events };
+    adapterBlock[schema.tokenKey] = token;
+    adapterBlock[schema.idKey] = chatId;
+
+    cfg[adapter] = adapterBlock;
+    cfg.enabled = true;
+    if (!cfg.schema_version) cfg.schema_version = 1;
+
+    const result = validateIntegrationsConfig(cfg);
+    if (!result.valid) {
+      return res
+        .status(400)
+        .json({ error: `Validation failed: ${result.details.join('; ')}` });
+    }
+
+    try {
+      mkdirSync(configDir, { recursive: true });
+      writeFileSync(configPath, `${JSON.stringify(cfg, null, 2)}\n`);
+    } catch (err) {
+      return res
+        .status(500)
+        .json({ error: `Failed to write config: ${err.message}` });
+    }
+
+    // Hot-reload just this adapter (no full restart)
+    if (app.locals.ensureIntegrations) app.locals.ensureIntegrations();
+    if (app.locals.integrations?.reloadAdapter) {
+      await app.locals.integrations.reloadAdapter(adapter);
+    }
+
+    res.json({ ok: true, path: configPath });
+  });
+
   // ─── Dynamic favicon ──────────────────────────────────────────────────
   // Serve mode-specific favicon before express.static so it takes precedence.
   app.get('/favicon.svg', (_req, res) => {

package/server/beads-reader.js

@@ -5,7 +5,7 @@ import { promisify } from 'node:util';
 const execFileAsync = promisify(execFile);
 
 async function runBd(args, dbPath) {
-  const fullArgs = [...args, '--json', '--db', dbPath, '--readonly'];
+  const fullArgs = [...args, '--json', '--db', dbPath];
   const { stdout } = await execFileAsync('bd', fullArgs, {
     encoding: 'utf8',
     timeout: 10000,

package/server/dispatch-external.js

@@ -0,0 +1,106 @@
+import { spawn } from 'node:child_process';
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+export function resolvePythonCmd() {
+  if (process.env.WORCA_PYTHON) {
+    return [process.env.WORCA_PYTHON];
+  }
+  if (process.platform === 'win32') {
+    return ['py', 'python3', 'python'];
+  }
+  return ['python3', 'python'];
+}
+
+export function dispatchExternal({
+  runDir,
+  settingsPath,
+  eventType,
+  payload,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+}) {
+  const candidates = resolvePythonCmd();
+  const args = [
+    '-m',
+    'worca.events.dispatch_external',
+    '--run-dir',
+    runDir,
+    '--settings',
+    settingsPath,
+    '--event-type',
+    eventType,
+    '--payload-json',
+    JSON.stringify(payload),
+  ];
+
+  let candidateIdx = 0;
+
+  function trySpawn(resolve) {
+    if (candidateIdx >= candidates.length) {
+      resolve({ ok: false, reason: 'python_not_found' });
+      return;
+    }
+
+    const cmd = candidates[candidateIdx];
+    const spawnArgs = cmd === 'py' ? ['-3', ...args] : args;
+
+    const child = spawn(cmd, spawnArgs, { stdio: ['ignore', 'pipe', 'pipe'] });
+
+    let stdoutBuf = '';
+    let stderrBuf = '';
+    let settled = false;
+
+    const timer = setTimeout(() => {
+      if (!settled) {
+        settled = true;
+        child.kill();
+        resolve({ ok: false, reason: 'timeout' });
+      }
+    }, timeoutMs);
+
+    child.stdout.on('data', (chunk) => {
+      stdoutBuf += chunk;
+    });
+    child.stderr.on('data', (chunk) => {
+      stderrBuf += chunk;
+    });
+
+    child.on('error', (err) => {
+      if (!settled && err.code === 'ENOENT') {
+        clearTimeout(timer);
+        candidateIdx++;
+        trySpawn(resolve);
+        return;
+      }
+      if (!settled) {
+        settled = true;
+        clearTimeout(timer);
+        resolve({ ok: false, reason: 'spawn_error', stderr: err.message });
+      }
+    });
+
+    child.on('close', (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+
+      if (code !== 0) {
+        resolve({
+          ok: false,
+          reason: `exit_code_${code}`,
+          stderr: stderrBuf,
+        });
+        return;
+      }
+
+      try {
+        const parsed = JSON.parse(stdoutBuf);
+        resolve(parsed);
+      } catch {
+        resolve({ ok: false, reason: 'invalid_response', stdout: stdoutBuf });
+      }
+    });
+  }
+
+  return new Promise((resolve) => trySpawn(resolve));
+}

package/server/ensure-webhook.js

@@ -0,0 +1,66 @@
+// ensure-webhook.js — auto-configure a webhook pointing to this worca-ui instance
+// in a project's settings.local.json so the pipeline sends events to the UI.
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { localPathFor } from './settings-merge.js';
+
+/**
+ * Ensure a webhook entry exists in the project's settings.local.json
+ * pointing to the worca-ui inbox at the given host:port.
+ *
+ * Skips if a webhook for this host:port already exists.
+ * Creates settings.local.json if it doesn't exist.
+ *
+ * @param {string} projectPath — absolute path to the project root
+ * @param {{ host: string, port: number }} server — worca-ui server address
+ */
+export function ensureWebhookForUi(projectPath, { host, port }) {
+  const settingsPath = join(projectPath, '.claude', 'settings.json');
+  const localPath = localPathFor(settingsPath);
+  // Use localhost instead of 127.0.0.1 — the pipeline validator only allows
+  // https:// or http://localhost for security.
+  const displayHost =
+    host === '127.0.0.1' || host === '::1' ? 'localhost' : host;
+  const inboxUrl = `http://${displayHost}:${port}/api/webhooks/inbox`;
+
+  // Read existing local settings (or start fresh)
+  let local = {};
+  if (existsSync(localPath)) {
+    try {
+      local = JSON.parse(readFileSync(localPath, 'utf8'));
+    } catch {
+      local = {};
+    }
+  }
+
+  if (!local.worca) local.worca = {};
+  if (!Array.isArray(local.worca.webhooks)) local.worca.webhooks = [];
+
+  // Check if a webhook for this URL already exists
+  const exists = local.worca.webhooks.some((wh) => wh.url === inboxUrl);
+  if (exists) return false;
+
+  // Also check base settings.json (in case it was manually configured there)
+  try {
+    const base = JSON.parse(readFileSync(settingsPath, 'utf8'));
+    const baseWebhooks = base?.worca?.webhooks || [];
+    if (baseWebhooks.some((wh) => wh.url === inboxUrl)) return false;
+  } catch {
+    // no base settings — proceed
+  }
+
+  local.worca.webhooks.push({
+    url: inboxUrl,
+    events: ['pipeline.*'],
+  });
+
+  // Ensure events are enabled
+  if (!local.worca.events) local.worca.events = {};
+  if (local.worca.events.enabled === undefined) {
+    local.worca.events.enabled = true;
+  }
+
+  writeFileSync(localPath, `${JSON.stringify(local, null, 2)}\n`, 'utf8');
+  return true;
+}

package/server/index.js

@@ -4,6 +4,7 @@ import { createServer } from 'node:http';
 import { homedir, platform } from 'node:os';
 import { join } from 'node:path';
 import { createApp } from './app.js';
+import { createIntegrations } from './integrations/index.js';
 import { attachWsServer } from './ws.js';
 
 // Parse argv
@@ -57,6 +58,8 @@ const app = createApp({
   projectRoot,
   webhookInbox,
   prefsDir,
+  serverHost: host,
+  serverPort: port,
 });
 const server = createServer(app);
 
@@ -104,6 +107,25 @@ app.locals.broadcast = broadcast;
 app.locals.scheduleRefresh = scheduleRefresh;
 app.locals.resolveRunProject = resolveRunProject;
 
+// Boot chat integrations only in global mode — project-scoped instances skip
+// integrations to avoid duplicate Telegram long-poll connections on the same bot.
+if (isGlobal) {
+  const integrationsOpts = {
+    port,
+    host,
+    prefsDir,
+    configPath: join(prefsDir, 'integrations', 'config.json'),
+  };
+  app.locals.integrations = createIntegrations(integrationsOpts);
+  app.locals.ensureIntegrations = () => {
+    if (!app.locals.integrations?.reloadAdapter) {
+      app.locals.integrations = createIntegrations(integrationsOpts);
+    }
+  };
+} else {
+  console.log('[integrations] Skipped — integrations only run in global mode');
+}
+
 // ─── worca-cc version check (non-blocking) ─────────────────────────────
 checkWorcaVersion().then((result) => {
   app.locals.worcaVersion = result;

package/server/integrations/adapter.js

@@ -0,0 +1,91 @@
+/**
+ * @typedef {('text'|'bold'|'code'|'code_block'|'link')} MessageSegmentKind
+ *
+ * @typedef {{
+ *   kind: MessageSegmentKind,
+ *   value: string,
+ *   href?: string
+ * }} MessageSegment
+ *
+ * @typedef {{
+ *   title: string|null,
+ *   body: MessageSegment[],
+ *   severity: 'info'|'success'|'warning'|'error'
+ * }} NormalizedMessage
+ *
+ * @typedef {{
+ *   platform: string,
+ *   chatId: string,
+ *   userId: string,
+ *   text: string,
+ *   raw: object
+ * }} IncomingMessage
+ *
+ * @typedef {object} ChatAdapter
+ * @property {string} name
+ * @property {boolean} supportsInbound
+ * @property {() => Promise<void>} start
+ * @property {() => Promise<void>} stop
+ * @property {(chatId: string, msg: NormalizedMessage) => Promise<void>} send
+ * @property {(cb: (msg: IncomingMessage) => void) => void} onInbound
+ */
+
+export const MESSAGE_SEGMENT_KINDS = [
+  'text',
+  'bold',
+  'code',
+  'code_block',
+  'link',
+  'markdown',
+];
+
+export const SEVERITY_LEVELS = ['info', 'success', 'warning', 'error'];
+
+export const ADAPTER_INTERFACE_KEYS = [
+  'name',
+  'supportsInbound',
+  'start',
+  'stop',
+  'send',
+  'onInbound',
+];
+
+/** @param {unknown} seg @returns {seg is MessageSegment} */
+export function isValidSegment(seg) {
+  if (!seg || typeof seg !== 'object') return false;
+  return (
+    MESSAGE_SEGMENT_KINDS.includes(seg.kind) && typeof seg.value === 'string'
+  );
+}
+
+/** @param {unknown} msg @returns {msg is NormalizedMessage} */
+export function isValidMessage(msg) {
+  if (!msg || typeof msg !== 'object') return false;
+  if (msg.title !== null && typeof msg.title !== 'string') return false;
+  if (!Array.isArray(msg.body) || !msg.body.every(isValidSegment)) return false;
+  return SEVERITY_LEVELS.includes(msg.severity);
+}
+
+/** @param {unknown} inc @returns {inc is IncomingMessage} */
+export function isValidIncoming(inc) {
+  if (!inc || typeof inc !== 'object') return false;
+  return (
+    typeof inc.platform === 'string' &&
+    typeof inc.chatId === 'string' &&
+    typeof inc.userId === 'string' &&
+    typeof inc.text === 'string' &&
+    inc.raw !== undefined
+  );
+}
+
+/** @param {unknown} adapter @returns {adapter is ChatAdapter} */
+export function isValidAdapter(adapter) {
+  if (!adapter || typeof adapter !== 'object') return false;
+  return (
+    typeof adapter.name === 'string' &&
+    typeof adapter.supportsInbound === 'boolean' &&
+    typeof adapter.start === 'function' &&
+    typeof adapter.send === 'function' &&
+    typeof adapter.onInbound === 'function'
+  );
+}