@worca/app 1.1.1 → 1.2.0-rc.2

package/src/core/settings.mjs

@@ -11,6 +11,12 @@
 //   contextMaxBytesPerFile — §5.4 per-source-file inlining cap.
 //   contextMaxBytesTotal   — §5.4 total memory budget.
 //   skillMount             — §5.6 'copy' (default) | 'symlink' (opt-in).
+//   debugSpawnEnabled      — the stored spawn-diagnostics preference (a UI checkbox).
+//                            claude-runner.mjs reads it fresh on every spawn through
+//                            effectiveDebugSpawn(), so it applies to the UI server AND
+//                            to CLI runs with no restart. A NON-EMPTY WORCA_DEBUG_SPAWN
+//                            in the process environment overrides it (power-user
+//                            override); this module never writes process.env.
 //   pipelineCostLimitUsd   — per-pipeline lifetime USD spend cap; unset = no limit.
 //   totalCostLimitUsd      — windowed all-pipelines USD spend cap; unset = no limit.
 //   costLimitResetPeriod   — total-budget window, 'weekly' | 'monthly' (default).
@@ -42,7 +48,7 @@ import { readFileSync, existsSync, statSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { homedir } from 'node:os';
 import { randomBytes } from 'node:crypto';
-import { EFFORTS, isReservedModelEnvKey, assertModelCost } from './model-env.mjs';
+import { EFFORTS, isReservedModelEnvKey, assertModelCost, envFlag } from './model-env.mjs';
 
 /**
  * The real OS home base, honoring HOME/USERPROFILE so tests can sandbox it.
@@ -526,6 +532,75 @@ export async function setCostLimitResetPeriod(input) {
   return { costLimitResetPeriod: costLimitResetPeriod() };
 }
 
+// ── The keys POST /api/settings understands ──────────────────────────────────
+// The route keeps a legacy contract: a body naming NONE of these clears root
+// (test/settings-projects-root.test.mjs "a bodyless POST resets root"). Every
+// setter's key is listed HERE, beside the setters, so a new key cannot forget
+// to join a hand-maintained exclusion list in the route and wipe the root on
+// its first save.
+export const SETTINGS_POST_KEYS = Object.freeze([
+  'root', 'projectsRoot', 'chat',
+  'pipelineCostLimitUsd', 'totalCostLimitUsd', 'costLimitResetPeriod',
+  'askMaxTurns', 'askMaxBudgetUsd',
+  'debugSpawnEnabled',
+]);
+
+// ── Spawn-debug diagnostics toggle (the stored side of WORCA_DEBUG_SPAWN) ────
+// Like every other stored setting (skillMount, the cost caps, the ask caps) this
+// is READ AT USE TIME: claude-runner.mjs#debugSpawnEnabled calls
+// effectiveDebugSpawn() on every spawn, so a UI save reaches the very next spawn
+// in this process and in any CLI process with no restart, and nothing here ever
+// mutates process.env (a runtime env write would leak an explicit
+// WORCA_DEBUG_SPAWN=0 into every inherited child env and break the runner's
+// "OFF ⇒ byte-identical spawn env" invariant).
+export const DEFAULT_DEBUG_SPAWN_ENABLED = false;
+
+const isBool = (v) => typeof v === 'boolean';
+
+/** @throws {Error} unless `input` is a boolean (the route and the setter share this). */
+export function assertDebugSpawnInput(input) {
+  if (!isBool(input)) throw new Error('debugSpawnEnabled must be true or false');
+}
+
+/** STORED spawn-debug preference: boolean, default OFF. Invalid stored value ⇒ OFF (loudly). */
+export function debugSpawnEnabled() {
+  const v = readSettings().debugSpawnEnabled;
+  if (v === undefined) return DEFAULT_DEBUG_SPAWN_ENABLED;
+  if (isBool(v)) return v;
+  console.warn(`[worca] invalid debugSpawnEnabled ${JSON.stringify(v)} — using the default (${DEFAULT_DEBUG_SPAWN_ENABLED})`);
+  return DEFAULT_DEBUG_SPAWN_ENABLED;
+}
+
+/**
+ * What the runner will actually do on the next spawn, and why. ONE precedence
+ * rule, shared by the runner gate and the settings API: a NON-EMPTY
+ * WORCA_DEBUG_SPAWN in the environment wins (parsed with the envFlag rule, so an
+ * exported "0"/"false" is an explicit OFF override), otherwise the stored
+ * preference applies. An empty export (`export WORCA_DEBUG_SPAWN=` in a profile
+ * or a dotenv template) is NOT an override — the runner would read it as OFF
+ * while the UI showed the stored value checked, with nothing explaining why.
+ * @returns {{enabled: boolean, source: 'env'|'settings'}}
+ */
+export function effectiveDebugSpawn() {
+  const v = process.env.WORCA_DEBUG_SPAWN;
+  if (v !== undefined && v !== '') return { enabled: envFlag('WORCA_DEBUG_SPAWN'), source: 'env' };
+  return { enabled: debugSpawnEnabled(), source: 'settings' };
+}
+
+/**
+ * Persist the preference. Nothing else: the runner reads it back per spawn, so
+ * the change is live everywhere without touching this process's environment.
+ * @throws {Error} unless `input` is a boolean.
+ */
+export async function setDebugSpawnEnabled(input) {
+  assertDebugSpawnInput(input);
+  const settings = readSettings();
+  if (input === DEFAULT_DEBUG_SPAWN_ENABLED) delete settings.debugSpawnEnabled;
+  else settings.debugSpawnEnabled = input;
+  await persistSettings(settings);
+  return { debugSpawnEnabled: debugSpawnEnabled() };
+}
+
 // ---------------------------------------------------------------------------
 // Global model catalog (configurable-models-design.md §4.1). Stored entries are
 // MINIMAL — label only when it differs from id, efforts only when a proper

package/src/core/ui-instance.mjs

@@ -0,0 +1,235 @@
+// src/core/ui-instance.mjs
+// The web UI is a singleton over the machine-wide store, so `worca ui` needs to
+// know whether one is already up before it spawns another — and needs a way to
+// stop the one that is. This module is the CLI side of that lifecycle; the server
+// side (GET /api/health, POST /api/shutdown, the instance file) lives in
+// ui/server.mjs.
+//
+// Discovery is the Jupyter runtime-file pattern: the server writes
+// <worcaHome>/ui.json ({ pid, host, port, token, version, startedAt }) once it is
+// listening and removes it on exit. The file is a HINT, never the truth — a
+// crashed server leaves it behind, so every decision re-probes the port:
+//
+//   probeUi({ port })  -> { state: 'worca', info }   a Worca UI answered /api/health
+//                      -> { state: 'busy' }          something else owns the port
+//                      -> { state: 'free' }          nothing is listening
+//
+// Stopping goes through POST /api/shutdown with the file's bearer token so the
+// server runs its graceful path (chat channel workers die cleanly) on every
+// platform — a bare signal is a hard kill on Windows. The signal is the fallback
+// when the token is unavailable (file missing, or a server too old to have one).
+
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import process from 'node:process';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+
+import { worcaHome } from './projects.mjs';
+
+export const DEFAULT_UI_PORT = 4317;
+export const DEFAULT_UI_HOST = '127.0.0.1';
+/** What GET /api/health must report as `name` for the occupant to count as a Worca UI. */
+export const UI_HEALTH_NAME = '@worca/app';
+
+/** Absolute path of the instance file for the current worcaHome. */
+export function uiInstanceFile() {
+  return join(worcaHome(), 'ui.json');
+}
+
+/** A fresh shutdown token (hex, 32 bytes of entropy). */
+export function newUiToken() {
+  return randomBytes(32).toString('hex');
+}
+
+/**
+ * Persist the running instance's coordinates. Atomic (tmp + rename) and 0600:
+ * the token authorizes a shutdown, so it must not be world-readable.
+ */
+export async function writeUiInstance({ pid, host, port, token, version, startedAt }) {
+  const file = uiInstanceFile();
+  await fsp.mkdir(join(file, '..'), { recursive: true });
+  const tmp = `${file}.${pid}.tmp`;
+  const body = JSON.stringify({ pid, host, port, token, version, startedAt }, null, 2) + '\n';
+  await fsp.writeFile(tmp, body, { mode: 0o600 });
+  await fsp.rename(tmp, file);
+  return file;
+}
+
+/** The instance file's contents, or null when missing/corrupt/not an object. */
+export function readUiInstance() {
+  try {
+    const data = JSON.parse(fs.readFileSync(uiInstanceFile(), 'utf8'));
+    if (!data || typeof data !== 'object' || Array.isArray(data)) return null;
+    const port = Number(data.port);
+    if (!Number.isInteger(port) || port <= 0) return null;
+    return { ...data, port, pid: Number(data.pid) || null };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Remove the instance file. With `ifPid`, only when the file still belongs to
+ * that process — an old server exiting late must not delete the file a newer
+ * one just wrote. Synchronous so it is usable from a process 'exit' handler.
+ */
+export function removeUiInstance({ ifPid } = {}) {
+  const file = uiInstanceFile();
+  try {
+    if (ifPid !== undefined) {
+      const cur = readUiInstance();
+      if (cur && cur.pid && cur.pid !== ifPid) return false;
+    }
+    fs.unlinkSync(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Host as it appears inside a URL (IPv6 literals need brackets). */
+export function urlHost(host) {
+  if (!host) return 'localhost';
+  if (host === '127.0.0.1' || host === '::1' || host === '[::1]' || host === 'localhost') return 'localhost';
+  return host.includes(':') && !host.startsWith('[') ? `[${host}]` : host;
+}
+
+/** The URL a browser should open for a UI bound to host:port. */
+export function uiUrl({ host = DEFAULT_UI_HOST, port = DEFAULT_UI_PORT } = {}) {
+  return `http://${urlHost(host)}:${port}`;
+}
+
+/** Host to CONNECT to (bind-any addresses are not dialable). */
+function dialHost(host) {
+  if (!host || host === '0.0.0.0' || host === '::') return DEFAULT_UI_HOST;
+  return host.includes(':') && !host.startsWith('[') ? `[${host}]` : host;
+}
+
+/** Every error code nested in a fetch failure (Node wraps them in `cause`, sometimes an AggregateError). */
+function errorCodes(err) {
+  const out = new Set();
+  const walk = (e, depth) => {
+    if (!e || depth > 4) return;
+    if (typeof e.code === 'string') out.add(e.code);
+    if (e.cause) walk(e.cause, depth + 1);
+    if (Array.isArray(e.errors)) for (const inner of e.errors) walk(inner, depth + 1);
+  };
+  walk(err, 0);
+  return out;
+}
+
+/** GET a JSON object from the UI, or null (non-2xx, non-JSON, non-object). Network errors propagate. */
+async function getJson(url, signal) {
+  const res = await fetch(url, { signal, headers: { accept: 'application/json' } });
+  if (!res.ok) return null;
+  try {
+    const data = await res.json();
+    return data && typeof data === 'object' && !Array.isArray(data) ? data : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Ask host:port whether a Worca UI is listening there.
+ *
+ * @returns {Promise<{state:'worca', info:object} | {state:'busy'} | {state:'free'}>}
+ *   'busy' covers every occupant that is not a Worca UI: a non-JSON answer, a
+ *   different `name`, a hang (timeout) or a reset. Only a clean connection
+ *   refusal is 'free'. A Worca UI from before /api/health existed is recognised
+ *   by its settings route and reported with `info.legacy = true` (no pid, no
+ *   token — it cannot be stopped from here, only from its own terminal).
+ */
+export async function probeUi({ host = DEFAULT_UI_HOST, port = DEFAULT_UI_PORT, timeoutMs = 1500 } = {}) {
+  const ctl = new AbortController();
+  const timer = setTimeout(() => ctl.abort(), timeoutMs);
+  const base = `http://${dialHost(host)}:${port}`;
+  try {
+    const info = await getJson(`${base}/api/health`, ctl.signal);
+    if (info) return info.name === UI_HEALTH_NAME ? { state: 'worca', info } : { state: 'busy' };
+    const legacy = await getJson(`${base}/api/settings`, ctl.signal);
+    if (legacy && typeof legacy.projectsRootDefault === 'string' && 'askMaxTurns' in legacy) {
+      return { state: 'worca', info: { name: UI_HEALTH_NAME, legacy: true } };
+    }
+    return { state: 'busy' };
+  } catch (err) {
+    const codes = errorCodes(err);
+    if (codes.has('ECONNREFUSED')) return { state: 'free' };
+    return { state: 'busy' };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** Poll until probeUi reports `state` (or any of `states`), or give up after timeoutMs. */
+export async function waitForUiState({ host, port, states, timeoutMs = 10000, intervalMs = 100 } = {}) {
+  const want = new Set(Array.isArray(states) ? states : [states]);
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    const r = await probeUi({ host, port, timeoutMs: Math.min(1500, Math.max(200, deadline - Date.now())) });
+    if (want.has(r.state)) return r;
+    if (Date.now() >= deadline) return null;
+    await sleep(intervalMs);
+  }
+}
+
+/** True when a process with that pid exists (signal 0 probes without killing). */
+export function processAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; } catch (err) { return err && err.code === 'EPERM'; }
+}
+
+/**
+ * Stop the Worca UI on host:port, gracefully when possible.
+ *
+ * Order: (1) POST /api/shutdown with the instance file's token — the server
+ * answers 202 and exits through its signal path; (2) if that is refused or no
+ * token is known, SIGTERM the pid the health probe reported; (3) wait for the
+ * port to free up. Idempotent: a port with no Worca UI is `notRunning`, not an
+ * error. The instance file is cleaned up whenever the port ends up free.
+ *
+ * @returns {Promise<{status:'stopped', method:'request'|'signal', pid:number|null}
+ *                  |{status:'not-running'}
+ *                  |{status:'busy'}
+ *                  |{status:'failed', pid:number|null, reason:string}
+ *                  |{status:'timeout', pid:number|null}>}
+ */
+export async function stopUi({ host = DEFAULT_UI_HOST, port = DEFAULT_UI_PORT, token, timeoutMs = 10000 } = {}) {
+  const probe = await probeUi({ host, port });
+  if (probe.state === 'free') { removeUiInstance(); return { status: 'not-running' }; }
+  if (probe.state === 'busy') return { status: 'busy' };
+  if (probe.info.legacy) {
+    return { status: 'failed', pid: null, reason: 'it is an older Worca UI without shutdown support — stop it from its own terminal (Ctrl+C) and start again' };
+  }
+  const pid = Number(probe.info.pid) || null;
+
+  const file = readUiInstance();
+  const bearer = token || (file && file.port === port ? file.token : null);
+  let method = null;
+
+  if (bearer) {
+    try {
+      const res = await fetch(`http://${dialHost(host)}:${port}/api/shutdown`, {
+        method: 'POST',
+        headers: { authorization: `Bearer ${bearer}`, accept: 'application/json' },
+        signal: AbortSignal.timeout(3000),
+      });
+      if (res.status === 202 || res.status === 200) method = 'request';
+    } catch {
+      // The server may drop the connection while exiting — the wait below decides.
+      method = 'request';
+    }
+  }
+  if (!method && pid) {
+    try { process.kill(pid, 'SIGTERM'); method = 'signal'; } catch { /* already gone, or not ours */ }
+  }
+  if (!method) return { status: 'failed', pid, reason: 'no shutdown token in the instance file and no pid to signal' };
+
+  const freed = await waitForUiState({ host, port, states: ['free'], timeoutMs });
+  if (!freed) return { status: 'timeout', pid };
+  removeUiInstance();
+  return { status: 'stopped', method, pid };
+}