@worca/ui 0.14.0 → 0.15.2

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.14.0",
+  "version": "0.15.2",
   "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/**",

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/keys-schema.js

@@ -1,14 +1,25 @@
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const schema = JSON.parse(
-  readFileSync(
-    resolve(__dirname, '../../src/worca/schemas/keys.json'),
-    'utf-8',
-  ),
-);
+
+// 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;

package/server/process-manager.js

@@ -371,7 +371,21 @@ export class ProcessManager {
    * @returns {Promise<{ pid: number }>}
    */
   async startPipeline(opts = {}) {
-    const cwd = opts.projectRoot || this.projectRoot;
+    // Resume must spawn inside the run's own working tree. Worktree-hosted
+    // runs live under <worktree>/.worca/runs/<id>; if we spawn from the parent
+    // project root, git operations and relative settings paths target the
+    // wrong tree and the resumed pipeline corrupts state on the parent
+    // branch. Worktree wins over opts.projectRoot for resume — callers
+    // routinely pass proj.projectRoot without knowing whether the run is
+    // worktree-hosted. Mirrors the cwd derivation in restartStage.
+    let resumeCtx = null;
+    if (opts.resume && opts.runId) {
+      resumeCtx = this.resolveRunContext(opts.runId);
+    }
+    const cwd =
+      resumeCtx && resumeCtx.worcaDir !== this.worcaDir
+        ? join(resumeCtx.worcaDir, '..')
+        : opts.projectRoot || this.projectRoot;
     const pipelineScriptRel = '.claude/worca/scripts/run_pipeline.py';
     const worktreeScriptRel = '.claude/worca/scripts/run_worktree.py';
 
@@ -408,9 +422,8 @@ export class ProcessManager {
     if (opts.resume) {
       args.push('--resume');
       if (opts.runId) {
-        const ctx = this.resolveRunContext(opts.runId);
-        const statusDir = ctx
-          ? ctx.runDir
+        const statusDir = resumeCtx
+          ? resumeCtx.runDir
           : join(this.worcaDir, 'runs', opts.runId);
         args.push('--status-dir', statusDir);
       }

package/server/project-routes.js

@@ -71,7 +71,7 @@ function validateRunId(runId) {
 // Re-exported from run-dir-resolver so callers (including older tests) can
 // continue importing from project-routes. The implementation now overlays
 // worktree runs registered in <worcaDir>/multi/pipelines.d/.
-import { findRunStatusPath } from './run-dir-resolver.js';
+import { findRunStatusPath, readPipelineOverlay } from './run-dir-resolver.js';
 export { findRunStatusPath };
 
 /** Validate a branch name — alphanumeric, dots, hyphens, underscores, slashes */
@@ -686,8 +686,14 @@ export function createProjectScopedRoutes({
     }
     try {
       let status = JSON.parse(readFileSync(statusPath, 'utf8'));
-      // Reconcile stale "running" status when no process is alive
-      if (status.pipeline_status === 'running' && pm && !pm.getRunningPid()) {
+      // Reconcile stale "running" status when no process is alive.
+      // Pass runId so worktree-hosted pipelines (PID lives under
+      // <worktree>/.worca/runs/<id>/pipeline.pid) are detected correctly.
+      if (
+        status.pipeline_status === 'running' &&
+        pm &&
+        !pm.getRunningPid(runId)
+      ) {
         try {
           pm.reconcileStatus();
           status = JSON.parse(readFileSync(statusPath, 'utf8'));
@@ -1337,7 +1343,7 @@ export function createProjectScopedRoutes({
         .json({ ok: false, error: `Run "${runId}" not found` });
     }
 
-    const running = req.project.pm.getRunningPid();
+    const running = req.project.pm.getRunningPid(runId);
     if (running) {
       return res.status(409).json({
         ok: false,
@@ -1366,7 +1372,11 @@ export function createProjectScopedRoutes({
       }
     }
 
-    const cwd = projectRoot || process.cwd();
+    // Worktree-hosted runs live outside the parent project. Spawn the learner
+    // inside the worktree so its default --status-dir=.worca and any git
+    // operations land on the right tree, mirroring run_pipeline.py resume.
+    const overlay = readPipelineOverlay(worcaDir, runId);
+    const cwd = overlay?.worktree_path || projectRoot || process.cwd();
     const env = { ...process.env };
     delete env.CLAUDECODE;
 

package/server/schemas/keys.json

@@ -0,0 +1,39 @@
+{
+  "global_only_keys": [
+    ["parallel", "cleanup_policy"],
+    ["parallel", "max_concurrent_pipelines"],
+    ["ui", "worktree_disk_warning_bytes"],
+    ["circuit_breaker", "classifier_model"]
+  ],
+  "normalize_skip_keys": [
+    ["milestones", "pr_approval"]
+  ],
+  "defaults": {
+    "global": {
+      "parallel": {
+        "cleanup_policy": "never",
+        "max_concurrent_pipelines": 10
+      },
+      "ui": {
+        "worktree_disk_warning_bytes": 2000000000
+      },
+      "circuit_breaker": {
+        "classifier_model": "haiku"
+      }
+    },
+    "project": {
+      "parallel": {
+        "worktree_base_dir": ".worktrees",
+        "default_base_branch": "main"
+      },
+      "circuit_breaker": {
+        "enabled": true,
+        "max_consecutive_failures": 3
+      },
+      "milestones": {
+        "plan_approval": true,
+        "pr_approval": false
+      }
+    }
+  }
+}