karajan-code 2.19.1 → 2.19.3

package/README.md

@@ -345,6 +345,10 @@ Opt out: set `telemetry: false` in `~/.karajan/kj.config.yml`
 
 ## Recent releases
 
+> **v2.19.3 released** — Patch. **HU Board now reads + writes plans from the canonical home dir** (KJC-BUG-0059). Reported by [@aitormf](https://github.com/aitormf): the top card showed `Directorio del proyecto — no detectado` even when the run had a valid `projectDir` and the coder was reading files from it. Root cause: five board call sites still hard-coded `~/.kj/plans/` as their plans root — leftover from the v2.19.0 home consolidation, which fixed `sync.js` but missed the rest. After the auto-migrator ran (or the user created new plans post-v2.19.0), plans landed under `~/.karajan/plans/<slug>/`; the board kept looking under `~/.kj/plans/<slug>/` and silently found nothing — so `GET /api/projects/:id/preflight` could not extract `projectDir` (the literal Aitor saw), `GET /api/projects/:id/plans-outcome` returned `plans: []` for every project, `DELETE /api/projects/:id` swept the wrong path leaving residue on disk, `DELETE /api/plans/:planId` failed silently, `plan-mutations.plansRoot` wrote new per-HU run logs to the legacy root splitting state across both, and `cleanup-zombies` never GC'd zombies under `~/.karajan/plans/`. PR #795 ships three new exports in `packages/hu-board/src/db.js`: `getHuBoardPlansDir()` (canonical, or `KJ_PLANS_DIR` override), `getHuBoardLegacyPlansDir()` (legacy, null when override set), `getHuBoardPlansDirs()` ordered `[canonical, legacy?]` for read callers. Single-write callers (`plan-mutations`) use the canonical root; read / delete / GC iterate both so users mid-migration with plans still under `~/.kj/` don't regress. 29 hu-board test files / 349 tests still green. **If your board shows "Directorio del proyecto — no detectado" on a project that clearly works in CLI, upgrade to v2.19.3.**
+>
+> **v2.19.2 released** — Patch. **SonarQube 401 now triggers automatic token re-bootstrap** instead of failing the run (KJC-BUG-0057). Until v2.19.1, when the Sonar token was missing / stale / revoked / pointed at a recreated Sonar instance, `kj run` / `kj audit` threw `SonarQube authentication failed (HTTP 401)` with the hint "Regenerate with `kj init`" — putting the user in the loop for plumbing Karajan can do itself. PR #793 wires `src/sonar/api.js::sonarFetchOnce` to invoke a new `src/sonar/token-recovery.js::recoverSonarToken()` on the first 401, which reuses `bootstrapSonarToken()` (already shipped in v2.10.2) — probes admin/admin, rotates the default password if still in place, revokes the existing `karajan-cli` token, generates a fresh GLOBAL_ANALYSIS_TOKEN, mutates `config.sonarqube.token` in place AND mirrors it to `~/.karajan/sonar-credentials.json` so future processes pick it up via the normal resolver chain instead of triggering recovery again. The original request retries once with the new token; the user never sees the 401 when recovery succeeds. Per-process latch ensures N endpoints 401-ing trigger ONE bootstrap, not N. Programmatic, **zero LLM involvement** — exactly the kind of plumbing Karajan should never delegate to the agent. Reported by [@aitormf](https://github.com/aitormf).
+>
 > **v2.19.1 released** — Patch. **APPLICATION BLOCKER fix** for the HU Board: every fresh `npm install -g karajan-code` since the HU Board feature shipped was producing tarballs without the `packages/hu-board/` directory (the `files` array in `package.json` did not include it), and even when the user copied that directory manually, the board crashed at startup with `Cannot find package 'helmet' imported from .../packages/hu-board/src/server.js` because its five dependencies (`helmet`, `chokidar`, `better-sqlite3`, `express`, `express-rate-limit`) were declared in `packages/hu-board/package.json` but missing from the root `dependencies`. PR #791 adds `packages/hu-board/{src,public,package.json}` to `files`, adds the five deps at root at the exact same versions so `npm dedupe` collapses to one copy resolvable by upward traversal, and regenerates `package-lock.json`. Verified end-to-end: `npm pack --dry-run` now ships 12 board files; `node packages/hu-board/src/server.js` boots cleanly. Also internal: 38 direct `os.homedir()` callers routed through the unified resolver (PR #790, `KARAJAN_HOME` now redirects every component) and 5 inline constructions of `~/.karajan/hu-board-runs/` unified under one helper (PR #789). Reported by [@aitormf](https://github.com/aitormf). **If you tried v2.19.0 and `kj board start` failed, upgrade to v2.19.1.**
 >
 > **v2.19.0 released** — Minor. Consolidates the HOME-level state of Karajan into a single root: **`~/.karajan/`**. Previously `~/.kj/` held plans, hibernated standby state, run-registry entries and worktrees, while `~/.karajan/` held sessions, hu-stories, config and the rest — no ADR justified the split and four divergent `getKjHome()` implementations had drifted. Three internal PRs land the change without breaking anyone: PR #781 unifies the resolver and introduces **`KARAJAN_HOME`** as the canonical env var (with `KJ_HOME` honoured + one-shot deprecation warning); PR #782 ships an idempotent **auto-migrator** that runs once on the next `kj` invocation — tarball backup at `~/.karajan/backup/kj-pre-migration-<ISO>.tar.gz` BEFORE moving, marker file `~/.karajan/.kj-migrated.json` prevents re-runs, cross-device safe (`rename` → `cp + rm` on `EXDEV`); PR #783 flips every default to `~/.karajan/` and adds a `legacy-kj-home` check to `kj doctor`. The HU Board reads BOTH locations until the migrator fires, so users who start the board first never see "missing plans". Restore is one `tar -xzf ~/.karajan/backup/kj-pre-migration-<ts>.tar.gz -C ~` away. Safe upgrade from 2.18.x.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "2.19.1",
+  "version": "2.19.3",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

package/packages/hu-board/src/cleanup-zombies.js

@@ -47,8 +47,12 @@ function isEphemeralId(id) {
   return EPHEMERAL_PREFIXES.some((p) => id.startsWith(p));
 }
 
-function plansRoot() {
-  return process.env.KJ_PLANS_DIR || path.join(homedir(), '.kj', 'plans');
+// KJC-BUG-0059 (v2.19.3): cleanup walks all known plan roots,
+// canonical first then legacy. Pre-fix hard-coded `~/.kj/plans/`
+// missed every plan post-v2.19.0 → zombies never garbage-collected.
+import { getHuBoardPlansDirs } from './db.js';
+function plansRoots() {
+  return getHuBoardPlansDirs();
 }
 
 function olderThanDays(isoStr, days) {
@@ -90,7 +94,7 @@ export function cleanupZombies(opts = {}) {
     const fsPaths = [
       ...storyIds.map((sid) => path.join(getKjHome(), 'hu-stories', sid)),
       ...sessionIds.map((sid) => path.join(getKjHome(), 'sessions', sid)),
-      path.join(plansRoot(), proj.id),
+      ...plansRoots().map((root) => path.join(root, proj.id)),
     ];
     deleteProject(proj.id);
     addTombstone('project', proj.id, { source: 'auto-cleanup', fsPaths });

package/packages/hu-board/src/db.js

@@ -56,6 +56,51 @@ export function getHuBoardRunsDir() {
   return join(getKjHome(), 'hu-board-runs');
 }
 
+/**
+ * Canonical path to the plans directory the board scans
+ * (`<karajan-home>/plans/`). Respects `KJ_PLANS_DIR` as an absolute
+ * override, mirroring sync.js. KJC-BUG-0059 (v2.19.3): preflight
+ * endpoint used a hard-coded `~/.kj/plans/` legacy fallback that
+ * survived the v2.19.0 consolidation, causing the board to report
+ * "directorio del proyecto: no detectado" even when the plan on disk
+ * had a valid `projectDir`.
+ *
+ * @returns {string}
+ */
+export function getHuBoardPlansDir() {
+  return process.env.KJ_PLANS_DIR || join(getKjHome(), 'plans');
+}
+
+/**
+ * Legacy `~/.kj/plans/` directory — only returned when KJ_PLANS_DIR
+ * is unset (it would be the same path anyway when overridden).
+ * Callers iterate canonical + legacy so users who have not yet run
+ * the v2.19.0 auto-migrator still see their plans. KJC-BUG-0059.
+ *
+ * @returns {string|null}
+ */
+export function getHuBoardLegacyPlansDir() {
+  if (process.env.KJ_PLANS_DIR) return null;
+  return join(process.env.HOME || '/root', '.kj', 'plans');
+}
+
+/**
+ * Ordered list of every plans root the board should scan: canonical
+ * first (`~/.karajan/plans/`), legacy second when applicable
+ * (`~/.kj/plans/`). Honours `KJ_PLANS_DIR` as a single override,
+ * matching `sync.js`'s fullScan / startWatcher precedence so the
+ * preflight, plans-outcome, delete-project and delete-plan endpoints
+ * see the same set of files the watcher sees. KJC-BUG-0059.
+ *
+ * @returns {string[]}
+ */
+export function getHuBoardPlansDirs() {
+  const dirs = [getHuBoardPlansDir()];
+  const legacy = getHuBoardLegacyPlansDir();
+  if (legacy) dirs.push(legacy);
+  return dirs;
+}
+
 // Bump when the schema gains a column / index / table that older
 // Karajan versions cannot understand. A DB written by a newer Karajan
 // refuses to open here so it does not get silently downgraded.

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

@@ -40,10 +40,13 @@ const KJ_CLI = join(REPO_ROOT, 'src', 'cli.js');
  * `KJ_PLANS_DIR` (tests) then `KJ_HOME/plans` (power users) then
  * `~/.kj/plans/` (default) — same precedence as `sync.js::fullScan`.
  */
+// KJC-BUG-0059: write operations go to the canonical plans dir.
+// Read operations should iterate getHuBoardPlansDirs() instead, to
+// pick up plans the user has under the legacy ~/.kj/plans/ tree
+// while the auto-migrator has not yet fired.
+import { getHuBoardPlansDir } from './db.js';
 function plansRoot() {
-  if (process.env.KJ_PLANS_DIR) return process.env.KJ_PLANS_DIR;
-  if (process.env.KJ_HOME) return join(process.env.KJ_HOME, 'plans');
-  return join(homedir(), '.kj', 'plans');
+  return getHuBoardPlansDir();
 }
 
 /**

package/packages/hu-board/src/preflight.js

@@ -30,6 +30,7 @@
 import { execSync } from 'node:child_process';
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
+import { getHuBoardPlansDirs } from './db.js';
 
 function runQuiet(cmd, opts = {}) {
   try {
@@ -221,13 +222,13 @@ function checkConfigYml() {
 }
 
 function checkPlans(projectId) {
-  // Plans live at ~/.kj/plans/<projectId>/*.json (or
-  // $KJ_HOME/plans/<projectId>/*.json under VITEST or custom config).
-  // Mirror plan-mutations.js::plansRoot() so the path matches reality.
-  const dir = process.env.KJ_HOME
-    ? join(process.env.KJ_HOME, 'plans', projectId)
-    : join(process.env.HOME || '', '.kj', 'plans', projectId);
-  if (!existsSync(dir)) {
+  // KJC-BUG-0059 (v2.19.3): scan canonical + legacy roots, same as
+  // the preflight route. Pre-fix this hard-coded `~/.kj/plans/`
+  // missed every plan post-v2.19.0 → preflight reported "sin plans
+  // aún" even when the user had a valid plan on disk.
+  const dirs = getHuBoardPlansDirs().map((root) => join(root, projectId));
+  const dir = dirs.find((d) => existsSync(d));
+  if (!dir) {
     return {
       id: 'plans', label: 'Plans en disco', status: 'info',
       detail: 'sin plans aún',

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

@@ -15,6 +15,9 @@ import {
   deleteSession,
   getKjHome,
   getHuBoardRunsDir,
+  getHuBoardPlansDir,
+  getHuBoardLegacyPlansDir,
+  getHuBoardPlansDirs,
   getStoryRow,
   listPlanIdsForProject,
   updateStoryStatus,
@@ -192,22 +195,23 @@ router.get('/projects/:id/preflight', async (req, res) => {
   try {
     const projectId = req.params.id;
     let projectDir = null;
+    // KJC-BUG-0059 (v2.19.3): scan plans in BOTH the canonical
+    // ~/.karajan/plans/ AND the legacy ~/.kj/plans/ — the legacy
+    // fallback covers users who started the board before running any
+    // `kj` command on a fresh install (so the auto-migrator from
+    // v2.19.0 has not fired yet). Pre-fix, this endpoint hard-coded
+    // ~/.kj/plans/ as the default, missing every plan post-2.19.0
+    // → board card showed "directorio del proyecto: no detectado"
+    // even though the plan on disk had a valid projectDir.
     try {
-      // Plans live at ~/.kj/plans/<slug>/ when KJ_HOME is unset, or
-      // $KJ_HOME/plans/<slug>/ when set. db.js::getKjHome() returns
-      // the .karajan root, NOT the .kj root — they are sister dirs.
-      // Mirror plan-mutations.js::plansRoot() exactly.
-      const plansBase = process.env.KJ_HOME
-        ? path.join(process.env.KJ_HOME, 'plans')
-        : path.join(process.env.HOME || '', '.kj', 'plans');
-      const plansDir = path.join(plansBase, projectId);
-      if (fs.existsSync(plansDir)) {
-        const files = fs.readdirSync(plansDir).filter((f) => f.endsWith('.json'));
-        for (const f of files) {
+      outer: for (const root of getHuBoardPlansDirs()) {
+        const plansDir = path.join(root, projectId);
+        if (!fs.existsSync(plansDir)) continue;
+        for (const f of fs.readdirSync(plansDir).filter((x) => x.endsWith('.json'))) {
           try {
             const plan = JSON.parse(fs.readFileSync(path.join(plansDir, f), 'utf8'));
-            if (plan?.projectDir) { projectDir = plan.projectDir; break; }
-          } catch { /* try next */ }
+            if (plan?.projectDir) { projectDir = plan.projectDir; break outer; }
+          } catch { /* try next file */ }
         }
       }
     } catch { /* projectDir stays null → preflight will report it */ }
@@ -229,17 +233,17 @@ router.get('/projects/:id/preflight', async (req, res) => {
 router.get('/projects/:id/plans-outcome', (req, res) => {
   try {
     const projectId = req.params.id;
-    const plansBase = process.env.KJ_HOME
-      ? path.join(process.env.KJ_HOME, 'plans')
-      : path.join(process.env.HOME || '', '.kj', 'plans');
-    const plansDir = path.join(plansBase, projectId);
-    if (!fs.existsSync(plansDir)) return res.json({ projectId, plans: [] });
+    // KJC-BUG-0059 (v2.19.3): scan canonical + legacy roots so users
+    // who have not yet run the auto-migrator still see their plans.
     const out = [];
-    for (const f of fs.readdirSync(plansDir).filter(n => n.endsWith('.json'))) {
-      try {
-        const plan = JSON.parse(fs.readFileSync(path.join(plansDir, f), 'utf8'));
-        if (plan?.version !== 2) continue;
-        out.push({
+    for (const root of getHuBoardPlansDirs()) {
+      const plansDir = path.join(root, projectId);
+      if (!fs.existsSync(plansDir)) continue;
+      for (const f of fs.readdirSync(plansDir).filter(n => n.endsWith('.json'))) {
+        try {
+          const plan = JSON.parse(fs.readFileSync(path.join(plansDir, f), 'utf8'));
+          if (plan?.version !== 2) continue;
+          out.push({
           planId: plan.planId,
           name: plan.name || (plan.task ? plan.task.slice(0, 80) : plan.planId),
           status: plan.status || 'draft',
@@ -248,6 +252,7 @@ router.get('/projects/:id/plans-outcome', (req, res) => {
           huCount: Array.isArray(plan.hus) ? plan.hus.length : 0,
         });
       } catch { /* skip unreadable plan */ }
+      }
     }
     res.json({ projectId, plans: out });
   } catch (err) {
@@ -356,12 +361,13 @@ router.delete('/projects/:id', (req, res) => {
     // ~/.kj/plans relative to KJ_HOME's parent, which broke when the
     // two homes were configured separately and left orphan plan dirs
     // on disk after a 🗑️ delete.
-    const plansRoot = process.env.KJ_PLANS_DIR
-      || path.join(os.homedir(), '.kj', 'plans');
+    // KJC-BUG-0059 (v2.19.3): when removing a deleted project's
+    // residual plan dirs, sweep BOTH the canonical and legacy roots
+    // so the cleanup is consistent for users mid-migration.
     const fsPaths = [
       ...storyIds.map((sid) => path.join(huStoriesDir(), sid)),
       ...sessionIds.map((sid) => path.join(getKjHome(), 'sessions', sid)),
-      path.join(plansRoot, id),
+      ...getHuBoardPlansDirs().map((root) => path.join(root, id)),
     ];
 
     const existed = deleteProject(id);
@@ -464,13 +470,18 @@ router.delete('/sessions/:id', (req, res) => {
 router.delete('/plans/:planId', (req, res) => {
   try {
     const planId = req.params.planId;
-    // Locate the plan file by scanning the plans dir for filename match.
-    const plansRoot = process.env.KJ_PLANS_DIR || path.join(getKjHome(), '..', '.kj', 'plans');
+    // 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 {
-      for (const projSlug of fs.readdirSync(plansRoot)) {
-        const candidate = path.join(plansRoot, projSlug, `plan-${planId}.json`);
-        if (fs.existsSync(candidate)) { foundPath = candidate; break; }
+      outer: for (const plansRoot of getHuBoardPlansDirs()) {
+        if (!fs.existsSync(plansRoot)) continue;
+        for (const projSlug of fs.readdirSync(plansRoot)) {
+          const candidate = path.join(plansRoot, projSlug, `plan-${planId}.json`);
+          if (fs.existsSync(candidate)) { foundPath = candidate; break outer; }
+        }
       }
     } catch { /* plansRoot missing */ }
     addTombstone('plan', planId, { source: 'api', fsPaths: foundPath ? [foundPath] : [] });

package/src/sonar/api.js

@@ -3,6 +3,7 @@ import { withRetry } from "../utils/retry.js";
 import { resolveSonarProjectKey } from "./project-key.js";
 import { resolveSonarToken } from "./config-resolver.js";
 import { filterFalsePositives } from "./issue-filter.js";
+import { recoverSonarToken } from "./token-recovery.js";
 
 class SonarApiError extends Error {
   constructor(message, { url, httpStatus, hint } = {}) {
@@ -25,7 +26,7 @@ function parseHttpResponse(stdout) {
   return { httpCode, body };
 }
 
-async function sonarFetchOnce(config, urlPath) {
+async function sonarFetchOnce(config, urlPath, { _retriedAfterRecovery = false, logger = null } = {}) {
   const token = tokenFromConfig(config);
   const url = `${config.sonarqube.host}${urlPath}`;
   const res = await runCommand("curl", ["-s", "-w", "\n%{http_code}", "-u", `${token}:`, url]);
@@ -42,9 +43,22 @@ async function sonarFetchOnce(config, urlPath) {
   const { httpCode, body } = parseHttpResponse(res.stdout);
 
   if (httpCode === 401) {
+    // KJC-BUG-0057 (v2.19.2): try to bootstrap a fresh token via the Sonar
+    // REST API and retry ONCE. If recovery still fails — or this was already
+    // the retry — surface the actionable error like before.
+    if (!_retriedAfterRecovery) {
+      const recovery = await recoverSonarToken(config, logger);
+      if (recovery.ok) {
+        return sonarFetchOnce(config, urlPath, { _retriedAfterRecovery: true, logger });
+      }
+      throw new SonarApiError(
+        `SonarQube authentication failed (HTTP 401) and auto-recovery failed: ${recovery.reason}. Regenerate the token manually with 'kj init' or save admin user/password in ~/.karajan/sonar-credentials.json.`,
+        { url, httpStatus: 401, hint: "Run 'kj init' to regenerate the SonarQube token, or save admin credentials in ~/.karajan/sonar-credentials.json so Karajan can re-bootstrap automatically." }
+      );
+    }
     throw new SonarApiError(
-      `SonarQube authentication failed (HTTP 401). Token may be invalid or expired. Regenerate with 'kj init'.`,
-      { url, httpStatus: 401, hint: "Run 'kj init' to regenerate the SonarQube token." }
+      `SonarQube authentication failed (HTTP 401) even after auto-recovery. The newly generated token is also being rejected — the Sonar instance may be in an inconsistent state.`,
+      { url, httpStatus: 401, hint: "Inspect the Sonar UI directly; consider 'kj sonar restart'." }
     );
   }
 

package/src/sonar/token-recovery.js

@@ -0,0 +1,67 @@
+// Sonar 401 auto-recovery — KJC-BUG-0057 / v2.19.2.
+//
+// When the Sonar API returns 401 (token missing / invalid / expired / revoked)
+// and we still have admin/admin (or a user/pass we saved at `kj init` time),
+// regenerate the analysis token VIA THE REST API and persist it. The caller
+// retries the original request once with the new token.
+//
+// Programmatic, no LLM involvement. The whole point of the user feedback was
+// that this is plumbing, not a decision: Karajan has the credentials to
+// re-bootstrap and should do it without asking.
+
+import { bootstrapSonarToken } from "./token-bootstrap.js";
+import { saveSonarToken } from "./credentials.js";
+
+// Per-process latch: a single Sonar run that 401s on every endpoint must
+// only trigger ONE bootstrap attempt — not one per endpoint. The latch
+// resets when the process exits.
+let _recoveryAttempted = false;
+
+/**
+ * @internal Reset the latch between tests (mirrors __resetKjHomeWarningForTests).
+ */
+export function __resetSonarRecoveryLatchForTests() {
+  _recoveryAttempted = false;
+}
+
+/**
+ * Attempt to re-bootstrap the Sonar token after a 401. Mutates `config`
+ * in place when successful so the immediate retry picks up the new token.
+ *
+ * @param {object} config       Karajan config (will be mutated on success).
+ * @param {object} [logger]
+ * @returns {Promise<{ ok: boolean, reason?: string, newToken?: string, savedTo?: string, passwordRotated?: boolean }>}
+ */
+export async function recoverSonarToken(config, logger = null) {
+  if (_recoveryAttempted) {
+    return { ok: false, reason: "recovery already attempted in this process" };
+  }
+  _recoveryAttempted = true;
+
+  const host = config?.sonarqube?.host || "http://localhost:9000";
+  logger?.warn?.(`[sonar-recovery] 401 from ${host} — attempting token re-bootstrap`);
+
+  const result = await bootstrapSonarToken({ host });
+
+  if (!result.ok) {
+    logger?.warn?.(`[sonar-recovery] bootstrap failed: ${result.reason}`);
+    return { ok: false, reason: result.reason };
+  }
+
+  // Mutate the in-memory config so the caller's retry sees the new token.
+  config.sonarqube = config.sonarqube || {};
+  config.sonarqube.token = result.token;
+
+  // Also persist to ~/.karajan/sonar-credentials.json so future processes
+  // pick it up via the normal config-resolver chain instead of triggering
+  // recovery again. token-bootstrap.js already wrote sonar.token; this
+  // mirrors it into the structured credentials file the resolver reads.
+  try {
+    await saveSonarToken(result.token);
+  } catch (err) {
+    logger?.warn?.(`[sonar-recovery] persist to sonar-credentials.json failed (non-blocking): ${err.message}`);
+  }
+
+  logger?.info?.(`[sonar-recovery] new token persisted to ${result.savedTo}${result.passwordRotated ? " (admin password rotated)" : ""} — retrying original request`);
+  return { ok: true, newToken: result.token, savedTo: result.savedTo, passwordRotated: result.passwordRotated };
+}