@worca/ui 0.13.0 → 0.15.1

package/app/styles.css

@@ -1039,9 +1039,17 @@ sl-details.log-history-panel::part(content) {
   min-width: 140px;
 }
 
-.log-controls sl-input [slot="prefix"] {
+/* Prefix-slot icon centering. Inline SVGs default to baseline alignment,
+   which sits them at the top of an sl-input. Flex-center the slot wrapper
+   so any iconSvg(...) we drop into a prefix lines up with the placeholder
+   / value text. Generic rule covers every sl-input; .log-controls keeps
+   the extra left padding it always had. */
+sl-input [slot="prefix"] {
   display: flex;
   align-items: center;
+}
+
+.log-controls sl-input [slot="prefix"] {
   padding-left: 4px;
 }
 

package/bin/worca-ui.js

@@ -1,14 +1,17 @@
 #!/usr/bin/env node
 import { spawn } from 'node:child_process';
 import {
+  closeSync,
   existsSync,
   mkdirSync,
+  openSync,
   readdirSync,
   readFileSync,
+  realpathSync,
   unlinkSync,
   writeFileSync,
 } from 'node:fs';
-import { createServer } from 'node:net';
+import { connect, createServer } from 'node:net';
 import { homedir } from 'node:os';
 import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -110,6 +113,61 @@ export function parseArgs(argv) {
   return args;
 }
 
+/** Resolve log file path based on mode (mirrors PID file location). */
+function resolveLogPath(isGlobal) {
+  if (isGlobal) {
+    return join(PREFS_DIR, 'worca-ui-global.log');
+  }
+  const projectRoot = findProjectRoot(process.cwd());
+  return join(projectRoot, '.worca', 'worca-ui.log');
+}
+
+/** Try to open a TCP connection. Resolves true if a peer accepts within timeoutMs. */
+function canConnect(port, host, timeoutMs = 250) {
+  return new Promise((resolveProm) => {
+    let done = false;
+    const finish = (ok) => {
+      if (done) return;
+      done = true;
+      try {
+        sock.destroy();
+      } catch {
+        /* ignore */
+      }
+      resolveProm(ok);
+    };
+    const sock = connect({ port, host });
+    sock.once('connect', () => finish(true));
+    sock.once('error', () => finish(false));
+    setTimeout(() => finish(false), timeoutMs);
+  });
+}
+
+/**
+ * Wait for the spawned server to either start listening or die.
+ * Returns 'ready' (port open), 'died' (process exited), or 'timeout'.
+ */
+async function waitForServerStart({ pid, port, host, timeoutMs = 5000 }) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!isRunning(pid)) return 'died';
+    if (await canConnect(port, host, 250)) return 'ready';
+    await new Promise((r) => setTimeout(r, 150));
+  }
+  return isRunning(pid) ? 'timeout' : 'died';
+}
+
+/** Read the last N lines of a log file. Returns '' if unreadable. */
+function tailLogFile(logPath, maxLines = 60) {
+  try {
+    const content = readFileSync(logPath, 'utf8');
+    const lines = content.split('\n');
+    return lines.slice(-maxLines).join('\n').trimEnd();
+  } catch {
+    return '';
+  }
+}
+
 /** Resolve PID file path and dir based on mode. */
 function resolvePidPaths(isGlobal) {
   if (isGlobal) {
@@ -234,13 +292,55 @@ async function start({ port, host, open, global: isGlobal }) {
     spawnArgs.push('--global');
   }
 
+  // Capture child stdout+stderr to a log file so startup crashes are visible.
+  // Without this, errors thrown during module load (missing files, bad imports,
+  // config errors, port binding races) silently disappear and the CLI cheerfully
+  // reports "started (PID …)" — see CLAUDE.md "missing-module crash" note.
+  const logPath = resolveLogPath(isGlobal);
+  let logFd = null;
+  try {
+    mkdirSync(dirname(logPath), { recursive: true });
+    logFd = openSync(logPath, 'w'); // truncate previous run's output
+  } catch (e) {
+    console.warn(
+      `Warning: could not open log file ${logPath}: ${e.message}\nStartup errors will not be captured.`,
+    );
+  }
+
   const child = spawn(process.execPath, spawnArgs, {
     detached: true,
-    stdio: 'ignore',
+    stdio: logFd != null ? ['ignore', logFd, logFd] : 'ignore',
     cwd: process.cwd(),
   });
+  if (logFd != null) closeSync(logFd); // child holds its own dup
   child.unref();
 
+  const url = `http://${host}:${availablePort}`;
+  const state = await waitForServerStart({
+    pid: child.pid,
+    port: availablePort,
+    host,
+    timeoutMs: 5000,
+  });
+
+  if (state === 'died') {
+    const tail = tailLogFile(logPath);
+    console.error(
+      `\n  worca-ui failed to start. The server process exited during startup.\n`,
+    );
+    if (tail) {
+      console.error('  Last log output:\n');
+      const indented = tail
+        .split('\n')
+        .map((l) => `    ${l}`)
+        .join('\n');
+      console.error(indented);
+      console.error('');
+    }
+    console.error(`  Full log: ${logPath}`);
+    process.exit(1);
+  }
+
   const info = {
     pid: child.pid,
     port: availablePort,
@@ -248,12 +348,17 @@ async function start({ port, host, open, global: isGlobal }) {
     started_at: new Date().toISOString(),
     mode: isGlobal ? 'global' : 'per-project',
     projectPath: isGlobal ? null : findProjectRoot(process.cwd()),
+    logPath,
   };
   writePidFile(pidFile, pidDir, info);
-  const url = `http://${host}:${availablePort}`;
   console.log(
     `worca-ui ${isGlobal ? '(global) ' : ''}started (PID ${child.pid}) at ${url}`,
   );
+  if (state === 'timeout') {
+    console.warn(
+      `  Note: server did not accept connections within 5s but is still running.\n  Tail the log if it does not come up: ${logPath}`,
+    );
+  }
 
   // Hint: if global mode, empty projects.d/, and cwd has .worca/
   if (isGlobal) {
@@ -525,57 +630,66 @@ Options:
   -h, --help         Show this help`);
 }
 
-const args = parseArgs(process.argv);
-switch (args.command) {
-  case 'start':
-    start(args);
-    break;
-  case 'stop':
-    stop(args);
-    break;
-  case 'restart':
-    restart(args);
-    break;
-  case 'status':
-    status(args);
-    break;
-  case 'projects':
-    switch (args.subAction) {
-      case 'list':
-        projectsList();
-        break;
-      case 'add':
-        projectsAdd(args.projectPath, args.projectName);
-        break;
-      case 'remove':
-        projectsRemove(args.projectPath);
-        break;
-      default:
-        console.log('Usage: worca-ui projects [list|add|remove]');
-    }
-    break;
-  case 'migrate':
-    if (args.scanDir) {
-      migrateScan(args.scanDir, args.dryRun);
-    } else if (args.migrateAdd) {
-      migrateAdd(args.migrateAdd);
-    } else if (args.migrateStatus) {
-      migrateStatus();
-    } else {
-      console.log(
-        'Usage:\n' +
-          '  worca-ui migrate --scan <dir> [--dry-run]\n' +
-          '  worca-ui migrate --add /path/to/project\n' +
-          '  worca-ui migrate --status',
-      );
-    }
-    break;
-  case 'version':
-    console.log(pkg.version);
-    break;
-  case 'help':
-    printHelp();
-    break;
-  default:
-    printHelp();
+function main() {
+  const args = parseArgs(process.argv);
+  switch (args.command) {
+    case 'start':
+      start(args);
+      break;
+    case 'stop':
+      stop(args);
+      break;
+    case 'restart':
+      restart(args);
+      break;
+    case 'status':
+      status(args);
+      break;
+    case 'projects':
+      switch (args.subAction) {
+        case 'list':
+          projectsList();
+          break;
+        case 'add':
+          projectsAdd(args.projectPath, args.projectName);
+          break;
+        case 'remove':
+          projectsRemove(args.projectPath);
+          break;
+        default:
+          console.log('Usage: worca-ui projects [list|add|remove]');
+      }
+      break;
+    case 'migrate':
+      if (args.scanDir) {
+        migrateScan(args.scanDir, args.dryRun);
+      } else if (args.migrateAdd) {
+        migrateAdd(args.migrateAdd);
+      } else if (args.migrateStatus) {
+        migrateStatus();
+      } else {
+        console.log(
+          'Usage:\n' +
+            '  worca-ui migrate --scan <dir> [--dry-run]\n' +
+            '  worca-ui migrate --add /path/to/project\n' +
+            '  worca-ui migrate --status',
+        );
+      }
+      break;
+    case 'version':
+      console.log(pkg.version);
+      break;
+    case 'help':
+      printHelp();
+      break;
+    default:
+      printHelp();
+  }
+}
+
+// Only run the CLI when this file is the entry point — not when imported
+// by tests (which load the module to access exported helpers like parseArgs).
+const entry = process.argv[1] ? realpathSync(process.argv[1]) : null;
+if (entry === fileURLToPath(import.meta.url)) {
+  main();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@worca/ui",
-  "version": "0.13.0",
+  "version": "0.15.1",
   "description": "Pipeline monitoring UI for worca-cc",
   "license": "MIT",
   "author": "Sinisha Djukic",
@@ -24,6 +24,7 @@
   "files": [
     "bin/worca-ui.js",
     "server/**/*.js",
+    "server/schemas/keys.json",
     "!server/**/*.test.js",
     "!server/test/**",
     "!server/**/test/**",
@@ -63,6 +64,7 @@
     "lit-html": "^3.3.1",
     "lucide": "^0.577.0",
     "marked": "^17.0.1",
+    "proper-lockfile": "^4.1.2",
     "ws": "^8.18.3"
   },
   "devDependencies": {

package/scripts/build-frontend.js

@@ -10,9 +10,11 @@ async function run() {
   const entry = path.join(appDir, 'main.js');
   const outfile = path.join(appDir, 'main.bundle.js');
   const vendorDir = path.join(appDir, 'vendor');
+  const serverSchemasDir = path.join(repoRoot, 'server', 'schemas');
 
   mkdirSync(appDir, { recursive: true });
   mkdirSync(vendorDir, { recursive: true });
+  mkdirSync(serverSchemasDir, { recursive: true });
 
   // Copy vendor CSS assets
   const vendorAssets = [
@@ -26,6 +28,19 @@ async function run() {
     console.log('copied', dest);
   }
 
+  // Copy shared schema(s) from the Python source tree so the published npm
+  // package is self-contained (it does not ship src/worca/).
+  const sharedSchemas = [
+    [
+      path.join(repoRoot, '..', 'src', 'worca', 'schemas', 'keys.json'),
+      path.join(serverSchemasDir, 'keys.json'),
+    ],
+  ];
+  for (const [src, dest] of sharedSchemas) {
+    copyFileSync(src, dest);
+    console.log('copied', path.relative(repoRoot, dest));
+  }
+
   try {
     const esbuild = await import('esbuild');
     await esbuild.build({

package/server/app.js

@@ -11,6 +11,8 @@ 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 { LaunchLock } from './launch-lock.js';
+import { createPreferencesRouter } from './preferences-routes.js';
 import { ProcessManager } from './process-manager.js';
 import { scanDirectory } from './project-registry.js';
 import {
@@ -19,6 +21,7 @@ import {
   projectResolver,
 } from './project-routes.js';
 import { validateIntegrationsConfig } from './settings-validator.js';
+import { createStatusRouter } from './status-routes.js';
 import { discoverSubagents } from './subagents-discovery.js';
 import { checkWorcaVersion } from './version-check.js';
 import { getVersionInfo } from './versions.js';
@@ -89,6 +92,13 @@ export function createApp(options = {}) {
   const webhookInbox = options.webhookInbox || createInbox();
   app.locals.webhookInbox = webhookInbox;
 
+  // Single LaunchLock instance shared across BOTH legacy /api and
+  // /api/projects/:id mounts so the global max_concurrent_pipelines cap is
+  // enforced atomically across all entry points. Without this, two routers
+  // each held their own mutex and concurrent launches via /api/runs +
+  // /api/projects/:id/runs could both pass the cap check and start.
+  const launchLock = new LaunchLock();
+
   // ─── Legacy single-project API ─────────────────────────────────────────
   // Mounts the shared project-scoped routes at /api with a middleware that
   // injects req.project from the closure options, so /api/runs, /api/settings,
@@ -112,7 +122,12 @@ export function createApp(options = {}) {
       };
       next();
     },
-    createProjectScopedRoutes({ serverHost, serverPort }),
+    createProjectScopedRoutes({
+      prefsDir,
+      serverHost,
+      serverPort,
+      launchLock,
+    }),
   );
 
   // ─── Unique routes (not in project-scoped router) ──────────────────────
@@ -519,6 +534,8 @@ export function createApp(options = {}) {
 
   // ─── Multi-project routes ──────────────────────────────────────────────
   if (prefsDir) {
+    app.use('/api/preferences', createPreferencesRouter({ prefsDir }));
+    app.use('/api/status', createStatusRouter({ prefsDir }));
     app.use(
       '/api/projects',
       createProjectRoutes({ prefsDir, projectRoot, serverHost, serverPort }),
@@ -526,7 +543,12 @@ export function createApp(options = {}) {
     app.use(
       '/api/projects/:projectId',
       projectResolver({ prefsDir, projectRoot }),
-      createProjectScopedRoutes({ prefsDir, serverHost, serverPort }),
+      createProjectScopedRoutes({
+        prefsDir,
+        serverHost,
+        serverPort,
+        launchLock,
+      }),
     );
   }
 

package/server/atomic-write.js

@@ -0,0 +1,18 @@
+/**
+ * Atomic file write: write to a temp file then rename into place.
+ * Prevents partial reads when a reader opens the file mid-write.
+ */
+
+import { mkdirSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+export function atomicWriteSync(filePath, data, options = {}) {
+  const dir = dirname(filePath);
+  mkdirSync(dir, { recursive: true });
+  const tmp = join(
+    dir,
+    `.${Date.now()}-${Math.random().toString(36).slice(2)}.tmp`,
+  );
+  writeFileSync(tmp, data, options);
+  renameSync(tmp, filePath);
+}

package/server/beads-reader.js

@@ -89,15 +89,40 @@ export async function listUnlinkedIssues(beadsDb) {
   }
 }
 
+/**
+ * Returns { runId: { total, done } } for every run:<id> label in the beads db.
+ *
+ * `total` comes from the cheap `bd label list-all` count. `done` requires
+ * looking at issue status, so we query `bd list --label-any run:<id>` per
+ * run and count statuses === "closed". N+1 queries, but N is bounded by
+ * the number of pipeline runs and this endpoint is called on app load /
+ * project switch only, not on every render.
+ */
 export async function countIssuesByRunLabel(beadsDb) {
   try {
     const rows = await runBd(['label', 'list-all'], beadsDb);
     const counts = {};
-    for (const row of rows) {
-      if (row.label.startsWith('run:')) {
-        counts[row.label.replace('run:', '')] = row.count;
-      }
+    const runLabels = rows.filter((r) => r.label.startsWith('run:'));
+    for (const row of runLabels) {
+      counts[row.label.replace('run:', '')] = { total: row.count, done: 0 };
     }
+    // Count closed issues per label in parallel.
+    await Promise.all(
+      runLabels.map(async (row) => {
+        const runId = row.label.replace('run:', '');
+        try {
+          const issues = await runBd(
+            ['list', '--label-any', row.label, '--all', '--limit', '0'],
+            beadsDb,
+          );
+          counts[runId].done = issues.filter(
+            (i) => i.status === 'closed',
+          ).length;
+        } catch {
+          /* leave done at 0 on per-run failure */
+        }
+      }),
+    );
     return counts;
   } catch {
     return {};

package/server/global-keys.js

@@ -0,0 +1,49 @@
+import { GLOBAL_ONLY_KEYS } from './keys-schema.js';
+
+const INERT_MILESTONE_KEYS = ['pr_approval', 'deploy_approval'];
+
+/**
+ * Mutates `blob` in place: extracts misplaced global-only keys and strips
+ * inert milestone keys (pr_approval/deploy_approval when set to `true`).
+ *
+ * Returns { globalExtracted, removedMilestones } for the caller to merge
+ * into ~/.worca/settings.json and to surface in the response.
+ */
+export function extractAndStripGlobalKeys(blob) {
+  const globalExtracted = {};
+  const removedMilestones = [];
+
+  const worca = blob.worca;
+  if (!worca || typeof worca !== 'object') {
+    return { globalExtracted, removedMilestones };
+  }
+
+  for (const [section, key] of GLOBAL_ONLY_KEYS) {
+    const sectionObj = worca[section];
+    if (!sectionObj || typeof sectionObj !== 'object') continue;
+    if (!(key in sectionObj)) continue;
+
+    if (!globalExtracted[section]) globalExtracted[section] = {};
+    globalExtracted[section][key] = sectionObj[key];
+    delete sectionObj[key];
+
+    if (Object.keys(sectionObj).length === 0) {
+      delete worca[section];
+    }
+  }
+
+  const milestones = worca.milestones;
+  if (milestones && typeof milestones === 'object') {
+    for (const key of INERT_MILESTONE_KEYS) {
+      if (milestones[key] === true) {
+        delete milestones[key];
+        removedMilestones.push(key);
+      }
+    }
+    if (Object.keys(milestones).length === 0) {
+      delete worca.milestones;
+    }
+  }
+
+  return { globalExtracted, removedMilestones };
+}

package/server/keys-schema.js

@@ -0,0 +1,27 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Look for keys.json in two places:
+//   1. server/schemas/keys.json — the in-package copy populated by
+//      scripts/build-frontend.js. This is what ships in the npm tarball.
+//   2. ../../src/worca/schemas/keys.json — the canonical Python source,
+//      reachable from a fresh monorepo checkout before `npm run build` has run.
+const candidates = [
+  resolve(__dirname, './schemas/keys.json'),
+  resolve(__dirname, '../../src/worca/schemas/keys.json'),
+];
+const schemaPath = candidates.find((p) => existsSync(p));
+if (!schemaPath) {
+  throw new Error(
+    `worca-ui: keys.json not found. Run "npm run build" inside worca-ui/ before starting the server. Looked in:\n  ${candidates.join('\n  ')}`,
+  );
+}
+const schema = JSON.parse(readFileSync(schemaPath, 'utf-8'));
+
+export const GLOBAL_ONLY_KEYS = schema.global_only_keys;
+export const NORMALIZE_SKIP_KEYS = schema.normalize_skip_keys;
+export const GLOBAL_DEFAULTS = schema.defaults.global;
+export const PROJECT_DEFAULTS = schema.defaults.project;

package/server/launch-lock.js

@@ -0,0 +1,25 @@
+/**
+ * In-process async mutex using a promise chain.
+ * Used to serialize pipeline launches so max_concurrent_pipelines is enforced atomically.
+ */
+export class LaunchLock {
+  #tail = Promise.resolve();
+
+  acquire() {
+    let release;
+    const prev = this.#tail;
+    this.#tail = new Promise((resolve) => {
+      release = resolve;
+    });
+    return prev.then(() => release);
+  }
+
+  async withLock(fn) {
+    const release = await this.acquire();
+    try {
+      return await fn();
+    } finally {
+      release();
+    }
+  }
+}