@worca/ui 0.23.0 → 0.25.0

package/server/app.js

@@ -13,6 +13,7 @@ import { createFleetRouter } from './fleet-routes.js';
 import { RAW_BODY } from './integrations/index.js';
 import { verify } from './integrations/verify.js';
 import { LaunchLock } from './launch-lock.js';
+import { fleetRunsDir, workspaceRunsDir, workspacesDir } from './paths.js';
 import { createPreferencesRouter } from './preferences-routes.js';
 import { ProcessManager } from './process-manager.js';
 import { scanDirectory } from './project-registry.js';
@@ -27,6 +28,30 @@ import { discoverSubagents } from './subagents-discovery.js';
 import { checkWorcaVersion } from './version-check.js';
 import { getVersionInfo } from './versions.js';
 import { createInbox } from './webhook-inbox.js';
+import { createWorkspaceRouter } from './workspace-routes.js';
+
+// Invokes `worca cleanup --<flag> <id>` as a subprocess and resolves once
+// the cleanup completes. Wired into the fleet/workspace router DELETE
+// ?cleanup=1 path so the UI Cleanup button actually removes the worktrees
+// + manifest dir (without this, the route falls back to a no-op default).
+function runWorcaCleanupSubprocess(flag, id) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(
+      'python3',
+      ['-m', 'worca.cli.main', 'cleanup', flag, id],
+      { stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env } },
+    );
+    let stderr = '';
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on('error', reject);
+    child.on('exit', (code) => {
+      if (code === 0) resolve({});
+      else reject(new Error(`worca cleanup exited ${code}: ${stderr.trim()}`));
+    });
+  });
+}
 
 export function createApp(options = {}) {
   const app = express();
@@ -554,8 +579,9 @@ export function createApp(options = {}) {
     app.use(
       '/api/fleet-runs',
       createFleetRouter({
-        fleetRunsDir: join(homedir(), '.worca', 'fleet-runs'),
+        fleetRunsDir: fleetRunsDir(),
         prefsDir,
+        runCleanup: (id) => runWorcaCleanupSubprocess('--fleet-id', id),
         // Spawn run_fleet.py in a detached subprocess so the route can return
         // immediately. We pass the pre-generated fleet_id so the in-flight
         // manifest path matches what the route just wrote.
@@ -617,6 +643,71 @@ export function createApp(options = {}) {
         },
       }),
     );
+
+    // Workspace routers — both definitions (/api/workspaces) and runs
+    // (/api/workspace-runs). The router factory exposes them as a pair.
+    const workspaceRouters = createWorkspaceRouter({
+      workspaceRunsDir: workspaceRunsDir(),
+      workspacesDir: workspacesDir(),
+      runCleanup: (id) => runWorcaCleanupSubprocess('--workspace-id', id),
+      // Spawn run_workspace.py in a detached subprocess, mirroring the fleet
+      // dispatcher. We pass --workspace-id so the script reuses the manifest
+      // the route just wrote instead of generating a fresh ID (which would
+      // orphan the manifest the UI navigated to).
+      dispatchWorkspace: async ({
+        workspace_id,
+        workspace_root,
+        manifest,
+        resume,
+      }) => {
+        if (resume) {
+          const child = spawn(
+            'python3',
+            [
+              '-m',
+              'worca.scripts.run_workspace',
+              workspace_root,
+              '--resume',
+              workspace_id,
+            ],
+            { detached: true, stdio: 'ignore', env: { ...process.env } },
+          );
+          child.unref();
+          return;
+        }
+        const args = [
+          '-m',
+          'worca.scripts.run_workspace',
+          workspace_root,
+          '--workspace-id',
+          workspace_id,
+        ];
+        if (manifest.work_request?.source) {
+          args.push('--source', manifest.work_request.source);
+        } else {
+          args.push('--prompt', manifest.work_request?.description ?? '');
+        }
+        if (manifest.branch_template) {
+          args.push('--branch', manifest.branch_template);
+        }
+        if (manifest.skip_integration) args.push('--skip-integration');
+        if (manifest.skip_planning) args.push('--skip-planning');
+        if (manifest.max_parallel) {
+          args.push('--max-parallel', String(manifest.max_parallel));
+        }
+        for (const p of manifest.guide?.paths || []) {
+          args.push('--guide', p);
+        }
+        const child = spawn('python3', args, {
+          detached: true,
+          stdio: 'ignore',
+          env: { ...process.env },
+        });
+        child.unref();
+      },
+    });
+    app.use('/api/workspaces', workspaceRouters.workspaces);
+    app.use('/api/workspace-runs', workspaceRouters.workspaceRuns);
   }
 
   // POST /api/integrations/telegram/detect — find chat IDs from recent messages.

package/server/fleet-routes.js

@@ -15,11 +15,10 @@ import {
   unlinkSync,
   writeFileSync,
 } from 'node:fs';
-import { homedir } from 'node:os';
 import { basename, join } from 'node:path';
 import { Router } from 'express';
+import { fleetRunsDir as resolveFleetRunsDir } from './paths.js';
 
-const DEFAULT_FLEET_RUNS_DIR = join(homedir(), '.worca', 'fleet-runs');
 const GUIDE_CAP_BYTES_DEFAULT = 64 * 1024; // 64 KB
 
 // Fleet IDs have the form f_<12 digits>_<hex>  — enforces no path traversal.
@@ -513,7 +512,7 @@ function defaultStopFleet(fleetId) {
  * entries that reference the fleet_id and includes them in the response.
  */
 export function createFleetRouter({
-  fleetRunsDir = DEFAULT_FLEET_RUNS_DIR,
+  fleetRunsDir: fleetRunsDirArg,
   prefsDir = null,
   dispatchFleet = null,
   runCleanup = defaultRunCleanup,
@@ -522,6 +521,9 @@ export function createFleetRouter({
   validateBaseBranch = defaultValidateBaseBranch,
   guideCapBytes = GUIDE_CAP_BYTES_DEFAULT,
 } = {}) {
+  // Lazy resolution honors $WORCA_HOME at router-construction time, falling
+  // back to ~/.worca/fleet-runs.  Issue #162.
+  const fleetRunsDir = resolveFleetRunsDir(fleetRunsDirArg);
   const router = Router();
 
   // ── GET /api/fleet-runs ─────────────────────────────────────────────────

package/server/index.js

@@ -1,11 +1,12 @@
 // server/index.js
 import { readFileSync } from 'node:fs';
 import { createServer } from 'node:http';
-import { homedir, platform } from 'node:os';
+import { platform } from 'node:os';
 import { join } from 'node:path';
 import { createApp } from './app.js';
 import { parseServerArgv } from './argv-parser.js';
 import { createIntegrations } from './integrations/index.js';
+import { preferencesPath, prefsDir as resolvePrefsDir } from './paths.js';
 import { attachWsServer } from './ws.js';
 
 // Parse argv (env vars provide defaults; argv flags take precedence)
@@ -49,7 +50,7 @@ if (isGlobal) {
   settingsPath = join(projectRoot, '.claude', 'settings.json');
 }
 
-const prefsDir = join(homedir(), '.worca');
+const prefsDir = resolvePrefsDir();
 const webhookInbox = createInbox();
 const app = createApp({
   settingsPath,
@@ -94,7 +95,7 @@ const { broadcast, scheduleRefresh, resolveRunProject } = attachWsServer(
   {
     worcaDir,
     settingsPath,
-    prefsPath: join(homedir(), '.worca', 'preferences.json'),
+    prefsPath: preferencesPath(),
     prefsDir,
     webhookInbox,
     projectRoot,

package/server/integrations/commands/fleet.js

@@ -161,7 +161,7 @@ export function createFleetHandlers({ chatContext, restClient }) {
     const resolved = await resolveFleet(restClient, args[0], 'fleet-children');
     if (resolved.disambig) return resolved.disambig;
     const f = resolved.fleet;
-    return `Children of \`${f.fleet_id}\`:\n\n` + fmtChildrenTable(f);
+    return `Children of \`${f.fleet_id}\`:\n\n${fmtChildrenTable(f)}`;
   }
 
   async function fleetHalt(_chatKey, args) {

package/server/integrations/commands/global.js

@@ -124,6 +124,15 @@ Fleet commands (cross-project):
 /fleet-pause <id> \u2014 pause every in-flight child
 /fleet-resume <id> \u2014 resume paused/interrupted, re-dispatch failed
 
+Workspace commands (DAG-ordered cross-project):
+/workspaces \u2014 list active workspaces
+/workspace [id|last] \u2014 workspace status
+/workspace-projects <id|last> \u2014 per-project status
+/workspace-tiers <id|last> \u2014 tier-by-tier DAG status
+/workspace-halt <id> \u2014 graceful halt (in-flight finish naturally)
+/workspace-resume <id> \u2014 re-dispatch failed/halted projects
+/workspace-prs <id> \u2014 list child PRs + umbrella issue
+
 Commands with [run_id] auto-resolve to the active run if omitted.
 Use \`*suffix\` to match by ending, e.g. /status \`*2db5\`
 Project commands require /use first.`;

package/server/integrations/commands/workspace.js

@@ -0,0 +1,295 @@
+/**
+ * Workspace-scoped chat commands.
+ *
+ *   /workspaces                       list active workspaces
+ *   /workspace [id|last]              show one workspace's summary
+ *   /workspace-projects <id|last>     per-project status grid (DAG)
+ *   /workspace-tiers <id|last>        tier-by-tier DAG status
+ *   /workspace-halt <id>              graceful halt (in-flight finish naturally)
+ *   /workspace-resume <id>            re-dispatch failed/halted children
+ *   /workspace-prs <id>               list child PRs + umbrella issue
+ *
+ * Mirrors the fleet command surface, but uses workspace terminology — the
+ * unit of work is a named project entry in workspace.json, not an arbitrary
+ * project path. /workspace-pause and /workspace-stop are intentionally
+ * absent: workspaces don't yet have pause/stop infrastructure (only halt
+ * via DELETE). When the lifecycle gains those, add commands here.
+ *
+ * Authz: every handler runs *after* the inbound allowlist gate in
+ * index.js — same gate that already guards /pause, /resume, /stop.
+ *
+ * @module commands/workspace
+ */
+
+import { statusEmoji } from './global.js';
+
+function pickLatest(workspaces) {
+  if (!workspaces || workspaces.length === 0) return null;
+  return [...workspaces].sort((a, b) => {
+    const at = a.created_at || '';
+    const bt = b.created_at || '';
+    return bt.localeCompare(at);
+  })[0];
+}
+
+async function fetchWorkspaces(restClient) {
+  const resp = await restClient.get('/api/workspace-runs');
+  const data = resp.data;
+  if (!data || data.ok === false) return [];
+  return Array.isArray(data.workspace_runs) ? data.workspace_runs : [];
+}
+
+async function fetchWorkspaceById(restClient, id) {
+  const resp = await restClient.get(
+    `/api/workspace-runs/${encodeURIComponent(id)}`,
+  );
+  const data = resp.data;
+  if (!data || data.ok === false) return null;
+  // GET /:id returns { ok, manifest, cost_usd } — flatten to a single object
+  // with the shape /workspace-runs list emits, so downstream formatters can
+  // be uniform.
+  if (data.manifest) {
+    return { ...data.manifest, cost_usd: data.cost_usd };
+  }
+  return null;
+}
+
+/**
+ * Resolve "last" / short-suffix / full-id into a workspace manifest object.
+ * Returns { workspace, disambig } — exactly one of them populated.
+ */
+async function resolveWorkspace(restClient, idArg, command) {
+  if (!idArg || idArg === 'last') {
+    const all = await fetchWorkspaces(restClient);
+    const latest = pickLatest(all);
+    if (!latest) return { disambig: 'No workspaces found.' };
+    return { workspace: latest };
+  }
+  if (idArg.startsWith('ws_')) {
+    const workspace = await fetchWorkspaceById(restClient, idArg);
+    if (!workspace) return { disambig: `Workspace \`${idArg}\` not found.` };
+    return { workspace };
+  }
+  // Short suffix match — `4318dbf9` matches `ws_..._4318dbf9`.
+  const all = await fetchWorkspaces(restClient);
+  const matches = all.filter((w) => w.workspace_id?.endsWith(idArg));
+  if (matches.length === 0) {
+    return { disambig: `No workspace matches \`${idArg}\`.` };
+  }
+  if (matches.length > 1) {
+    const lines = matches.map(
+      (w) => `   • \`${w.workspace_id}\` — ${w.status}`,
+    );
+    return {
+      disambig:
+        `Multiple workspaces match \`${idArg}\`:\n${lines.join('\n')}\n\n` +
+        `Usage: /${command} <workspace_id>`,
+    };
+  }
+  return { workspace: matches[0] };
+}
+
+function fmtWorkspaceSummary(ws) {
+  const id = ws.workspace_id;
+  const name = ws.workspace_name ? ` (${ws.workspace_name})` : '';
+  const status = ws.status || 'unknown';
+  const reason = ws.halt_reason ? ` (${ws.halt_reason})` : '';
+  const children = ws.children || [];
+  const childCount = ws.children_count ?? children.length;
+  const completed = children.filter((c) => c.status === 'completed').length;
+  const failed = children.filter(
+    (c) =>
+      c.status === 'failed' ||
+      c.status === 'blocked' ||
+      c.status === 'setup_failed',
+  ).length;
+  const parts = [`${statusEmoji(status)} **Workspace:** \`${id}\`${name}`];
+  parts.push(`   **Status:** ${status}${reason}`);
+  parts.push(
+    `   **Projects:** ${completed}/${childCount} completed${failed ? `, ${failed} failed` : ''}`,
+  );
+  const tiers = ws.dag?.tiers || [];
+  if (tiers.length > 0) {
+    parts.push(`   **Tiers:** ${tiers.length}`);
+  }
+  if (ws.cost_usd != null) {
+    parts.push(`   **Cost:** $${Number(ws.cost_usd).toFixed(2)}`);
+  }
+  return parts.join('\n');
+}
+
+function fmtProjectsTable(ws) {
+  const children = ws.children || [];
+  if (children.length === 0) return '   (no projects dispatched yet)';
+  return children
+    .map((c) => {
+      const project = c.project || '(?)';
+      const st = c.status || 'unknown';
+      const rid = c.run_id ? ` \`${c.run_id}\`` : '';
+      const tier = c.tier != null ? ` [tier ${c.tier}]` : '';
+      return `   ${statusEmoji(st)} **${project}**${tier} — ${st}${rid}`;
+    })
+    .join('\n');
+}
+
+function fmtTiersTable(ws) {
+  const tiers = ws.dag?.tiers || [];
+  if (tiers.length === 0) return '   (no tiers defined)';
+  const childByProject = new Map();
+  for (const c of ws.children || []) {
+    childByProject.set(c.project, c);
+  }
+  return tiers
+    .map((t) => {
+      const projects = t.projects || [];
+      const lines = projects.map((p) => {
+        const child = childByProject.get(p);
+        const st = child?.status || 'pending';
+        return `      ${statusEmoji(st)} ${p} — ${st}`;
+      });
+      const tierStatus = t.status || 'pending';
+      return [`   **Tier ${t.tier} (${tierStatus}):**`, ...lines].join('\n');
+    })
+    .join('\n');
+}
+
+function fmtPrsTable(ws) {
+  const children = ws.children || [];
+  const withPrs = children.filter((c) => c.pr_number || c.pr_url);
+  if (withPrs.length === 0 && !ws.umbrella_issue) {
+    return '   (no PRs created yet)';
+  }
+  const lines = [];
+  for (const c of withPrs) {
+    const ref = c.nwo && c.pr_number ? `${c.nwo}#${c.pr_number}` : c.pr_url;
+    lines.push(`   • **${c.project}** — ${ref}`);
+  }
+  if (ws.umbrella_issue?.url) {
+    lines.push('');
+    lines.push(`   \u{1F517} **Umbrella issue:** ${ws.umbrella_issue.url}`);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Creates handlers for the /workspace… commands.
+ *
+ * The chatContext is used to remember an `active_workspace` per chat,
+ * symmetrical to the existing `active_project` mechanism — so a user can
+ * `/workspace ws_…_abc` once, then `/workspace-halt` (no arg) on the same
+ * one. Implementation left for a follow-up if/when the UX warrants it.
+ *
+ * @param {{ chatContext, restClient }} deps
+ */
+export function createWorkspaceHandlers({
+  chatContext: _chatContext,
+  restClient,
+}) {
+  async function workspaces() {
+    const all = await fetchWorkspaces(restClient);
+    const active = all.filter((w) => {
+      const s = w.status;
+      return (
+        s === 'running' ||
+        s === 'planning' ||
+        s === 'integration_testing' ||
+        s === 'resuming' ||
+        s === 'paused'
+      );
+    });
+    if (active.length === 0) return 'No active workspaces.';
+    const lines = active.map((w) => {
+      const childCount = w.children_count ?? w.children?.length ?? 0;
+      const name = w.workspace_name ? ` (${w.workspace_name})` : '';
+      const reason = w.halt_reason ? ` (${w.halt_reason})` : '';
+      return [
+        `${statusEmoji(w.status)} **Workspace:** \`${w.workspace_id}\`${name}`,
+        `   **Status:** ${w.status}${reason} | **Projects:** ${childCount}`,
+      ].join('\n');
+    });
+    return `Active workspaces:\n\n${lines.join('\n')}`;
+  }
+
+  async function workspace(_chatKey, args) {
+    const resolved = await resolveWorkspace(restClient, args[0], 'workspace');
+    if (resolved.disambig) return resolved.disambig;
+    return fmtWorkspaceSummary(resolved.workspace);
+  }
+
+  async function workspaceProjects(_chatKey, args) {
+    const resolved = await resolveWorkspace(
+      restClient,
+      args[0],
+      'workspace-projects',
+    );
+    if (resolved.disambig) return resolved.disambig;
+    const w = resolved.workspace;
+    return `Projects in \`${w.workspace_id}\`:\n\n${fmtProjectsTable(w)}`;
+  }
+
+  async function workspaceTiers(_chatKey, args) {
+    const resolved = await resolveWorkspace(
+      restClient,
+      args[0],
+      'workspace-tiers',
+    );
+    if (resolved.disambig) return resolved.disambig;
+    const w = resolved.workspace;
+    return `DAG tiers for \`${w.workspace_id}\`:\n\n${fmtTiersTable(w)}`;
+  }
+
+  async function workspaceHalt(_chatKey, args) {
+    const resolved = await resolveWorkspace(
+      restClient,
+      args[0],
+      'workspace-halt',
+    );
+    if (resolved.disambig) return resolved.disambig;
+    const id = resolved.workspace.workspace_id;
+    const resp = await restClient.delete(
+      `/api/workspace-runs/${encodeURIComponent(id)}`,
+    );
+    if (!resp.data || resp.data.ok === false) {
+      return `Failed to halt workspace \`${id}\` (${resp.status}).`;
+    }
+    return `\u{1F7E1} Halted workspace \`${id}\`.\nIn-flight tier children will finish naturally.`;
+  }
+
+  async function workspaceResume(_chatKey, args) {
+    const resolved = await resolveWorkspace(
+      restClient,
+      args[0],
+      'workspace-resume',
+    );
+    if (resolved.disambig) return resolved.disambig;
+    const id = resolved.workspace.workspace_id;
+    const resp = await restClient.post(
+      `/api/workspace-runs/${encodeURIComponent(id)}/resume`,
+    );
+    if (!resp.data || resp.data.ok === false) {
+      return `Failed to resume workspace \`${id}\` (${resp.status}).`;
+    }
+    return `\u{1F7E2} Resumed workspace \`${id}\`. Re-dispatching pending project(s).`;
+  }
+
+  async function workspacePrs(_chatKey, args) {
+    const resolved = await resolveWorkspace(
+      restClient,
+      args[0],
+      'workspace-prs',
+    );
+    if (resolved.disambig) return resolved.disambig;
+    const w = resolved.workspace;
+    return `PRs for \`${w.workspace_id}\`:\n\n${fmtPrsTable(w)}`;
+  }
+
+  return {
+    workspaces,
+    workspace,
+    'workspace-projects': workspaceProjects,
+    'workspace-tiers': workspaceTiers,
+    'workspace-halt': workspaceHalt,
+    'workspace-resume': workspaceResume,
+    'workspace-prs': workspacePrs,
+  };
+}

package/server/integrations/index.js

@@ -16,6 +16,7 @@ import { createFleetHandlers } from './commands/fleet.js';
 import { createGlobalHandlers } from './commands/global.js';
 import { parseCommand } from './commands/parser.js';
 import { createProjectHandlers } from './commands/project.js';
+import { createWorkspaceHandlers } from './commands/workspace.js';
 import { loadIntegrationsConfig } from './config-loader.js';
 import { createRateLimiter } from './rate_limiter.js';
 import { renderEvent } from './renderers.js';
@@ -67,11 +68,16 @@ export function createIntegrations({
   const projectHandlers = createProjectHandlers({ chatContext, restClient });
   const controlHandlers = createControlHandlers({ chatContext, restClient });
   const fleetHandlers = createFleetHandlers({ chatContext, restClient });
+  const workspaceHandlers = createWorkspaceHandlers({
+    chatContext,
+    restClient,
+  });
   const allHandlers = {
     ...globalHandlers,
     ...projectHandlers,
     ...controlHandlers,
     ...fleetHandlers,
+    ...workspaceHandlers,
   };
 
   // Mutable adapter registry — keyed by adapter name