karajan-code 4.70.3 → 5.0.0

package/packages/hu-board/src/hu-zombie-reaper.js

@@ -73,10 +73,14 @@ export function reapZombieHus({ db, setHuStatus, setHuFailResult, opts = {}, now
     const localHuId = hu.id.includes("::") ? hu.id.split("::").slice(1).join("::") : hu.id;
     let planPersisted = false;
     if (hu.plan_id) {
+      let result = null;
       try {
-        const result = setHuStatus({ planId: hu.plan_id, huId: localHuId, status: "pending", projectId: hu.project_id });
+        result = setHuStatus({ planId: hu.plan_id, huId: localHuId, status: "pending", projectId: hu.project_id });
         planPersisted = !!(result && result.ok);
       } catch { /* swallow — never block startup */ }
+      // KJC-BUG-0405: a read-only plan mirrors the shared board; its running HU is a
+      // teammate's live work, not a zombie. Neither the plan nor the DB is touched.
+      if (result?.readonly) continue;
       // KJC-TSK-0404: además de resetear status=pending, marcar la HU con
       // result=fail + blocker. El siguiente `kj run` ve el blocker y se
       // lo inyecta al coder como "## PREVIOUS ATTEMPT FAILED" para que

package/packages/hu-board/src/plan-mutations.js

@@ -14,26 +14,14 @@
  * Steps 2-4 must share a single on-disk write: we never ack the mutation to
  * the UI without persisting it, otherwise a reload would silently revert.
  */
-import { readFileSync, existsSync, readdirSync, mkdirSync, openSync } from 'node:fs';
-import { join, dirname } from 'node:path';
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
 import { writeJsonAtomicSync } from 'karajan-core/atomic-write';
-import { spawn } from 'node:child_process';
-import { trackRun, untrack } from './run-tracker.js';
-import { getHuBoardRunsDir } from './db.js';
-import { fileURLToPath } from 'node:url';
 import { updateHuStatus, certifyAllHus, updateHu } from 'karajan-core/plan-hu-ops';
 import { validateBlockedByChange } from 'karajan-core/plan-validation';
 import { syncPlanFile } from './sync.js';
 import { getDb } from './db.js';
 
-// Repo root → so we can spawn `node <repo>/src/cli.js run ...` without
-// depending on `kj` being in $PATH of the board process.
-const REPO_ROOT = (() => {
-  const here = dirname(fileURLToPath(import.meta.url));       // packages/hu-board/src
-  return join(here, '..', '..', '..');                         // → repo root
-})();
-const KJ_CLI = join(REPO_ROOT, 'src', 'cli.js');
-
 /**
  * Root directory where `kj plan` writes `<slug>/<planId>.json`. Honours
  * `KJ_PLANS_DIR` (tests) then `KJ_HOME/plans` (power users) then
@@ -90,7 +78,7 @@ function readPlan(filePath) {
 // in the issues; the board shows it and refuses to edit it, so the two never diverge.
 function mirrorGuard(plan) {
   if (!plan?.readonly) return null;
-  return { ok: false, error: `this plan mirrors the shared board (${plan.readonly}) and is read-only here: change it with kj hu move` };
+  return { ok: false, readonly: true, error: `this plan mirrors the shared board (${plan.readonly}) and is read-only here: change it with kj hu move` };
 }
 
 function writePlan(filePath, plan) {
@@ -218,45 +206,6 @@ export function setHuFailResult({ planId, huId, blocker, projectId }) {
   return { ok: true, hu };
 }
 
-/**
- * KJC-TSK-0408 step 2/3: deshace los cambios de una HU restaurando
- * el snapshot git tomado pre-run. Marca status=pending, result=null
- * y outcome.reverted=true para que la UI muestre "deshecha".
- *
- * @param {object} args
- * @param {string} args.planId
- * @param {string} args.huId
- * @param {string} [args.projectId]
- * @returns {Promise<{ ok: boolean, sha?: string, error?: string }>}
- */
-export async function revertHuFromSnapshot({ planId, huId, projectId }) {
-  const filePath = findPlanFilePath(planId, projectId);
-  if (!filePath) return { ok: false, error: `plan not found: ${planId}` };
-  const plan = readPlan(filePath);
-  const mirrored = mirrorGuard(plan);
-  if (mirrored) return mirrored;
-  const hu = plan.hus?.find(h => h.id === huId);
-  if (!hu) return { ok: false, error: `hu not found: ${huId}` };
-  const snapshotSha = hu.outcome?.snapshot_sha;
-  if (!snapshotSha) {
-    return { ok: false, error: 'esta HU no tiene snapshot — solo HUs ejecutadas con KJC-TSK-0408 pueden deshacerse' };
-  }
-  const projectDir = plan.projectDir;
-  if (!projectDir) return { ok: false, error: 'plan sin projectDir' };
-
-  const { restoreHuSnapshot } = await import('karajan-core/hu-snapshot');
-  const restore = await restoreHuSnapshot({ projectDir, huId });
-  if (!restore.ok) return { ok: false, error: `restore falló: ${restore.error}` };
-
-  hu.status = 'pending';
-  hu.result = null;
-  hu.outcome = { ...(hu.outcome || {}), reverted: true, revertedAt: new Date().toISOString() };
-  hu.updatedAt = new Date().toISOString();
-  writePlan(filePath, plan);
-  syncPlanFile(filePath);
-  return { ok: true, sha: restore.sha };
-}
-
 /**
  * Bulk certify: equivalent to `kj plan ready <planId>` over HTTP. Flips
  * every pending HU to certified and sets `plan.status = "ready"`. No-op
@@ -344,102 +293,3 @@ export function markPlanReady({ planId, projectId }) {
   syncPlanFile(filePath);
   return { ok: true, count, planStatus: plan.status };
 }
-
-/**
- * Launch `kj run --plan <planId>` as a detached child. This is the
- * "Run plan" button's server-side handler: the board no longer asks the
- * user to drop to the terminal to kick off execution.
- *
- * We spawn against the repo's own CLI (`node <repo>/src/cli.js`) instead
- * of a `kj` binary on $PATH — the board is always shipped with the repo
- * that hosts it, so that entry point is guaranteed to exist. Tests set
- * `KJ_RUN_SPAWN_MODE=echo` to replace the spawn with a no-op that just
- * returns a fake pid, so we can assert payload shape without booting the
- * whole orchestrator inside vitest.
- *
- * Output is redirected to `~/.karajan/hu-board-runs/<planId>.log` so the
- * board can tail it later if we wire up a live log viewer — for now it's
- * just a durable trail. stdin is `ignore` (coder subprocess requirement
- * documented in CLAUDE.md).
- *
- * @param {object} args
- * @param {string} args.planId
- * @param {string} [args.projectId]
- * @param {string} [args.taskOverride] - optional custom task string
- * @returns {{ ok: true, pid: number, logPath: string } | { ok: false, error: string }}
- */
-export function runPlan({ planId, projectId, taskOverride, huIds = null } = {}) {
-  const filePath = findPlanFilePath(planId, projectId);
-  if (!filePath) return { ok: false, error: `plan not found: ${planId}` };
-
-  const plan = readPlan(filePath);
-  const mirrored = mirrorGuard(plan);
-  if (mirrored) return mirrored;
-  if (!Array.isArray(plan.hus) || plan.hus.length === 0) {
-    return { ok: false, error: 'plan has no hus[]' };
-  }
-  const projectDir = plan.projectDir;
-  if (!projectDir) {
-    return {
-      ok: false,
-      error:
-        'plan has no projectDir stamped — re-run `kj plan` to regenerate it, '
-        + 'then try again (plans pre-v2.7.4 did not persist the dir).',
-    };
-  }
-
-  // PR4: when huIds is set, validate they exist before spawning so
-  // we surface "unknown HU" as an HTTP 400 instead of letting the
-  // CLI fail mid-startup with a less obvious message.
-  let huFlag = null;
-  if (Array.isArray(huIds) && huIds.length > 0) {
-    const validIds = new Set(plan.hus.map((h) => h.id));
-    const unknown = huIds.filter((id) => !validIds.has(id));
-    if (unknown.length > 0) {
-      return { ok: false, error: `unknown HU id(s) in plan ${planId}: ${unknown.join(', ')}` };
-    }
-    huFlag = huIds.join(',');
-  }
-
-  const runsDir = getHuBoardRunsDir(); // KJC-TSK-0421 — centralised in db.js
-  mkdirSync(runsDir, { recursive: true });
-  // PR4: when running a single HU, suffix the log with the HU id so
-  // a subsequent full-plan run doesn't overwrite the per-HU log.
-  const logName = huFlag
-    ? `${planId}--hu-${huIds.join('-').replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 60)}.log`
-    : `${planId}.log`;
-  const logPath = join(runsDir, logName);
-
-  const task = taskOverride || plan.task || `run plan ${planId}`;
-  const args = [KJ_CLI, 'run', '--plan', planId];
-  if (huFlag) args.push('--hu', huFlag);
-  args.push(task);
-
-  // Escape hatch for tests — hard-kill the spawn so vitest doesn't boot
-  // the full orchestrator. The shape of the response is what we assert.
-  if (process.env.KJ_RUN_SPAWN_MODE === 'echo') {
-    return { ok: true, pid: 0, logPath, argv: [process.execPath, ...args], projectDir, huIds: huIds || null };
-  }
-
-  const out = openSync(logPath, 'a');
-  const err = openSync(logPath, 'a');
-  const child = spawn(process.execPath, args, {
-    cwd: projectDir,
-    detached: true,
-    stdio: ['ignore', out, err],
-    // Strip CLAUDECODE so the Claude agent subprocess trick in
-    // claude-agent.js doesn't misbehave (documented in CLAUDE.md).
-    env: { ...process.env, CLAUDECODE: undefined },
-  });
-  child.unref();
-  // KJC-TSK-0396: registrar el PID para que el botón ⏹ Stop del board
-  // sepa qué procesos matar. trackRun usa Set, así que llamadas
-  // duplicadas no inflan el registro. Cuando el proceso muera, el
-  // event 'exit' lo des-registra (defensa adicional: reaper periódico
-  // que limpia PIDs muertos cada 30s).
-  if (child.pid) {
-    trackRun(planId, { pid: child.pid, huIds: huIds || null });
-    child.on('exit', () => { untrack(planId, child.pid); });
-  }
-  return { ok: true, pid: child.pid ?? 0, logPath };
-}

package/packages/hu-board/src/plans-service.js

@@ -0,0 +1,55 @@
+// KJC-TSK-0541: reading the plan JSONs, shared by the API routers and testable without Express.
+// Every scan covers the canonical and the legacy plans roots (KJC-BUG-0059).
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+
+import { getHuBoardPlansDirs } from './db.js';
+
+/** Async existence probe (KJC-TSK-0539: no sync fs in handlers). */
+export const pathExists = (p) => fsp.access(p).then(() => true, () => false);
+
+/**
+ * mtime-keyed cache for parsed plan JSON (KJC-TSK-0539). The plan scans
+ * used to re-read and re-parse every plan file on EVERY request; with N
+ * plans and the board polling, that was O(N) parses per poll. The cache
+ * serves the parsed object while the file's mtime is unchanged and
+ * re-reads transparently when kj writes the plan.
+ */
+const planFileCache = new Map();
+export async function readPlanCached(p) {
+  const { mtimeMs } = await fsp.stat(p);
+  const hit = planFileCache.get(p);
+  if (hit && hit.mtimeMs === mtimeMs) return hit.plan;
+  const plan = JSON.parse(await fsp.readFile(p, 'utf8'));
+  planFileCache.set(p, { mtimeMs, plan });
+  return plan;
+}
+
+/** Every readable plan JSON of a project; an unreadable file is skipped. */
+export async function* projectPlans(projectId) {
+  for (const root of getHuBoardPlansDirs()) {
+    const plansDir = path.join(root, projectId);
+    if (!(await pathExists(plansDir))) continue;
+    for (const f of (await fsp.readdir(plansDir)).filter((n) => n.endsWith('.json'))) {
+      let plan;
+      try {
+        plan = await readPlanCached(path.join(plansDir, f));
+      } catch {
+        continue;
+      }
+      yield plan;
+    }
+  }
+}
+
+/** The path of `plan-<planId>.json` under any project of any plans root, or null. */
+export async function findPlanFile(planId) {
+  for (const plansRoot of getHuBoardPlansDirs()) {
+    if (!(await pathExists(plansRoot))) continue;
+    for (const projSlug of await fsp.readdir(plansRoot)) {
+      const candidate = path.join(plansRoot, projSlug, `plan-${planId}.json`);
+      if (await pathExists(candidate)) return candidate;
+    }
+  }
+  return null;
+}

package/packages/hu-board/src/routes/api/commands.js

@@ -0,0 +1,122 @@
+// KJC-TSK-0541: the kj commands the board launches, their run logs and the retired `kj run`
+// routes, composed by routes/api.js.
+import { Router } from 'express';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+
+import { getHuBoardRunsDir } from '../../db.js';
+import { runKjCommand, listSupportedCommands, startCardInLane } from '../../command-runner.js';
+import { pathExists } from '../../plans-service.js';
+import { requestProjectDir } from '../../project-dir.js';
+
+const router = Router();
+
+/**
+ * KJC-TSK-1319: the board launched `kj run` for a plan, an HU or a whole
+ * project. kj run is retired in 5.0 (your agent does the work, kj governs
+ * it), so these routes say so and launch nothing. The board never imports
+ * the CLI tree (KJC-TSK-0632): the notice lives here.
+ */
+const RUN_RETIRED = {
+  error: 'kj run was retired in 5.0. Your agent (Claude Code, OpenCode...) does the work now and kj governs it: split the task with kj brief planner + kj hu add, one lane per card with kj worktree start, and kj review --staged before every commit.',
+  guide: 'https://github.com/manufosela/karajan-code/blob/main/MIGRATION-v5.md',
+};
+router.post(['/plans/:planId/run', '/hus/:huId/run', '/projects/:id/run'], (_req, res) => {
+  res.status(410).json(RUN_RETIRED);
+});
+
+/**
+ * GET /api/commands - List the kj commands the board can launch.
+ * The UI uses this to render the Actions panel without hardcoding
+ * the command list on the client.
+ */
+router.get('/commands', (_req, res) => {
+  res.json({ commands: listSupportedCommands() });
+});
+
+/**
+ * POST /api/commands/:command - Spawn a kj <command> as a detached
+ * child. Body fields depend on the command (see command-runner.js
+ * for the per-command input schema). Returns a commandId the client
+ * can pass to GET /api/runs/:commandId/log to tail the output.
+ *
+ * The board never executes free-form arg arrays — the command name
+ * must be in the whitelist and each command builds its argv from a
+ * typed schema. Anything outside that fails 400.
+ */
+router.post('/commands/:command', (req, res) => {
+  try {
+    const result = runKjCommand({ command: req.params.command, input: req.body || {} });
+    if (!result.ok) return res.status(400).json({ error: result.error });
+    res.json({
+      ok: true,
+      commandId: result.commandId,
+      pid: result.pid,
+      logPath: result.logPath,
+    });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+/**
+ * POST /api/hu/:id/start - KJC-TSK-1324: the ▶ of a card. The body names the board project;
+ * its directory is resolved here, never taken from the client (ADR 0011). A card that already
+ * has a lane gets 409 with that lane and nothing is launched; otherwise `kj hu start <id>
+ * --code` runs detached and the response carries the commandId to tail.
+ */
+router.post('/hu/:id/start', (req, res) => {
+  let projectDir;
+  try {
+    projectDir = requestProjectDir(req.body?.project);
+  } catch (err) {
+    return res.status(400).json({ error: err.message });
+  }
+  if (!projectDir) return res.status(400).json({ error: 'name the board project the card belongs to' });
+  try {
+    const result = startCardInLane({ id: req.params.id, projectDir });
+    if (result.lane) return res.status(409).json({ error: result.error, lane: result.lane });
+    if (!result.ok) return res.status(400).json({ error: result.error });
+    return res.json({ ok: true, commandId: result.commandId, pid: result.pid, logPath: result.logPath });
+  } catch (err) {
+    return res.status(500).json({ error: err.message });
+  }
+});
+
+/**
+ * GET /api/runs/:commandId/log - Generalisation of the per-plan log
+ * tail. The original `/api/plans/:planId/log` reads
+ * `<runsDir>/<planId>.log`; this one reads `<runsDir>/<commandId>.log`
+ * where `commandId` is what `/api/commands/:command` returned.
+ *
+ * Same offset semantics + 1 MiB cap as the plans endpoint.
+ */
+router.get('/runs/:commandId/log', async (req, res) => {
+  try {
+    const runsDir = getHuBoardRunsDir(); // KJC-TSK-0421
+    const logPath = path.join(runsDir, `${req.params.commandId}.log`);
+    if (!(await pathExists(logPath))) {
+      return res.json({ exists: false, size: 0, content: '' });
+    }
+    const stat = await fsp.stat(logPath);
+    const offset = Math.max(0, Math.min(stat.size, Number(req.query.offset) || 0));
+    const MAX_READ = 1024 * 1024;
+    const length = Math.min(MAX_READ, stat.size - offset);
+    let content = '';
+    if (length > 0) {
+      const fh = await fsp.open(logPath, 'r');
+      try {
+        const buf = Buffer.alloc(length);
+        await fh.read(buf, 0, length, offset);
+        content = buf.toString('utf-8');
+      } finally {
+        await fh.close();
+      }
+    }
+    res.json({ exists: true, size: stat.size, content });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+export default router;

package/packages/hu-board/src/routes/api/plans.js

@@ -0,0 +1,55 @@
+// KJC-TSK-0541: the plan endpoints of /api, composed by routes/api.js.
+import { Router } from 'express';
+import fsp from 'node:fs/promises';
+
+import { addTombstone } from '../../db.js';
+import { markPlanReady } from '../../plan-mutations.js';
+import { findPlanFile } from '../../plans-service.js';
+
+const router = Router();
+
+/**
+ * DELETE /api/plans/:planId - Delete a single plan file.
+ *
+ * Removes `~/.kj/plans/<projectSlug>/plan-<planId>.json` and tombstones
+ * the plan id so the next watcher event doesn't re-sync it. Does NOT
+ * delete the project: a project can have multiple plans, deleting one
+ * plan only removes that plan's HUs from the board.
+ */
+router.delete('/plans/:planId', async (req, res) => {
+  try {
+    const planId = req.params.planId;
+    // Locate the plan file by scanning both canonical and legacy plans
+    // roots — KJC-BUG-0059 (v2.19.3). Pre-fix this hard-coded
+    // `getKjHome()/../.kj/plans` which silently misses plans saved by
+    // post-2.19.0 callers under `~/.karajan/plans/`.
+    let foundPath = null;
+    try {
+      foundPath = await findPlanFile(planId);
+    } catch { /* plansRoot missing */ }
+    addTombstone('plan', planId, { source: 'api', fsPaths: foundPath ? [foundPath] : [] });
+    if (foundPath) { try { await fsp.unlink(foundPath); } catch { /* */ } }
+    res.json({ deleted: true, fileRemoved: !!foundPath });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+/**
+ * POST /api/plans/:planId/ready - Bulk-certify every pending HU of a plan.
+ * Equivalent to the CLI `kj plan ready <planId>`. Body is optional — if the
+ * client knows the projectId we use it as a fast path, otherwise we fall
+ * back to scanning the plans dir.
+ */
+router.post('/plans/:planId/ready', (req, res) => {
+  try {
+    const { projectId } = req.body || {};
+    const result = markPlanReady({ planId: req.params.planId, projectId });
+    if (!result.ok) return res.status(404).json({ error: result.error });
+    res.json({ ready: true, planId: req.params.planId, count: result.count, planStatus: result.planStatus });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+export default router;