karajan-code 1.34.0 → 1.34.2

package/package.json

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

package/src/cli.js

@@ -23,6 +23,7 @@ import { triageCommand } from "./commands/triage.js";
 import { researcherCommand } from "./commands/researcher.js";
 import { architectCommand } from "./commands/architect.js";
 import { auditCommand } from "./commands/audit.js";
+import { boardCommand } from "./commands/board.js";
 
 const PKG_PATH = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../package.json");
 const PKG_VERSION = JSON.parse(readFileSync(PKG_PATH, "utf8")).version;
@@ -305,6 +306,17 @@ program
     }
   });
 
+program
+  .command("board [action]")
+  .description("Manage HU Board (start|stop|status|open)")
+  .option("--port <number>", "Port (default: 4000)", "4000")
+  .action(async (action = "start", opts) => {
+    await withConfig("board", opts, async ({ config, logger }) => {
+      const port = Number(opts.port) || config.hu_board?.port || 4000;
+      await boardCommand({ action, port, logger });
+    });
+  });
+
 const sonar = program.command("sonar").description("Manage SonarQube container");
 sonar.command("status").action(async () => sonarCommand({ action: "status" }));
 sonar.command("start").action(async () => sonarCommand({ action: "start" }));

package/src/commands/board.js

@@ -0,0 +1,125 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { getKarajanHome } from "../utils/paths.js";
+
+const BOARD_DIR = path.resolve(import.meta.dirname, "../../packages/hu-board");
+const PID_FILE = path.join(getKarajanHome(), "hu-board.pid");
+
+function readPid() {
+  try {
+    const pid = Number.parseInt(fs.readFileSync(PID_FILE, "utf8").trim(), 10);
+    return Number.isFinite(pid) ? pid : null;
+  } catch {
+    return null;
+  }
+}
+
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function startBoard(port = 4000) {
+  const existingPid = readPid();
+  if (existingPid && isProcessAlive(existingPid)) {
+    return { ok: true, alreadyRunning: true, pid: existingPid, url: `http://localhost:${port}` };
+  }
+
+  const serverPath = path.join(BOARD_DIR, "src/server.js");
+  const karajanHome = getKarajanHome();
+  fs.mkdirSync(karajanHome, { recursive: true });
+
+  const child = spawn("node", [serverPath], {
+    env: { ...process.env, PORT: String(port) },
+    detached: true,
+    stdio: "ignore",
+    cwd: BOARD_DIR
+  });
+  child.unref();
+
+  fs.writeFileSync(PID_FILE, String(child.pid));
+  return { ok: true, alreadyRunning: false, pid: child.pid, url: `http://localhost:${port}` };
+}
+
+export async function stopBoard() {
+  const pid = readPid();
+  if (!pid || !isProcessAlive(pid)) {
+    try { fs.unlinkSync(PID_FILE); } catch { /* ignore */ }
+    return { ok: true, wasRunning: false };
+  }
+
+  try {
+    process.kill(pid, "SIGTERM");
+  } catch {
+    // already dead
+  }
+  try { fs.unlinkSync(PID_FILE); } catch { /* ignore */ }
+  return { ok: true, wasRunning: true, pid };
+}
+
+export async function boardStatus(port = 4000) {
+  const pid = readPid();
+  const running = pid !== null && isProcessAlive(pid);
+  return {
+    ok: true,
+    running,
+    pid: running ? pid : null,
+    url: running ? `http://localhost:${port}` : null
+  };
+}
+
+export async function boardCommand({ action = "start", port = 4000, logger }) {
+  switch (action) {
+    case "start": {
+      const result = await startBoard(port);
+      if (result.alreadyRunning) {
+        logger.info(`HU Board already running (PID ${result.pid}) at ${result.url}`);
+      } else {
+        logger.info(`HU Board started (PID ${result.pid}) at ${result.url}`);
+      }
+      return result;
+    }
+    case "stop": {
+      const result = await stopBoard();
+      if (result.wasRunning) {
+        logger.info(`HU Board stopped (PID ${result.pid})`);
+      } else {
+        logger.info("HU Board was not running");
+      }
+      return result;
+    }
+    case "status": {
+      const result = await boardStatus(port);
+      if (result.running) {
+        logger.info(`HU Board is running (PID ${result.pid}) at ${result.url}`);
+      } else {
+        logger.info("HU Board is not running");
+      }
+      return result;
+    }
+    case "open": {
+      const status = await boardStatus(port);
+      if (!status.running) {
+        logger.info("HU Board is not running. Starting it first...");
+        await startBoard(port);
+      }
+      const url = `http://localhost:${port}`;
+      const { default: open } = await import("open").catch(() => ({ default: null }));
+      if (open) {
+        await open(url);
+        logger.info(`Opened ${url}`);
+      } else {
+        logger.info(`Open in browser: ${url}`);
+      }
+      return { ok: true, url };
+    }
+    default:
+      logger.error(`Unknown board action: ${action}. Use start|stop|status|open`);
+      return { ok: false, error: `Unknown action: ${action}` };
+  }
+}

package/src/commands/init.js

@@ -70,6 +70,15 @@ async function runWizard(config, logger) {
     config.sonarqube.enabled = enableSonar;
     logger.info(`  -> SonarQube: ${enableSonar ? "enabled" : "disabled"}`);
 
+    const enableHuBoard = await wizard.confirm("Enable HU Board for story tracking?", false);
+    config.hu_board = config.hu_board || {};
+    config.hu_board.enabled = enableHuBoard;
+    if (enableHuBoard) {
+      config.hu_board.port = 4000;
+      config.hu_board.auto_start = true;
+    }
+    logger.info(`  -> HU Board: ${enableHuBoard ? "enabled (auto-start on kj run)" : "disabled"}`);
+
     const methodology = await wizard.select("Development methodology:", [
       { label: "TDD (test-driven development)", value: "tdd", available: true },
       { label: "Standard (no TDD enforcement)", value: "standard", available: true }

package/src/config.js

@@ -118,6 +118,11 @@ const DEFAULTS = {
       test_inclusions: "**/*.test.js,**/*.spec.js,**/tests/**,**/__tests__/**"
     }
   },
+  hu_board: {
+    enabled: false,
+    port: 4000,
+    auto_start: false
+  },
   policies: {},
   serena: { enabled: false },
   planning_game: { enabled: false, project_id: null, codeveloper: null },

package/src/mcp/server-handlers.js

@@ -863,6 +863,20 @@ async function handleAudit(a, server, extra) {
   return handleAuditDirect(a, server, extra);
 }
 
+async function handleBoard(a) {
+  const action = a.action || "status";
+  const { loadConfig: lc } = await import("../config.js");
+  const { config } = await lc();
+  const port = a.port || config.hu_board?.port || 4000;
+  const { startBoard, stopBoard, boardStatus } = await import("../commands/board.js");
+  switch (action) {
+    case "start": return startBoard(port);
+    case "stop": return stopBoard();
+    case "status": return boardStatus(port);
+    default: return failPayload(`Unknown board action: ${action}`);
+  }
+}
+
 /* ── Handler dispatch map ─────────────────────────────────────────── */
 
 const toolHandlers = {
@@ -884,7 +898,8 @@ const toolHandlers = {
   kj_triage:      (a, server, extra) => handleTriage(a, server, extra),
   kj_researcher:  (a, server, extra) => handleResearcher(a, server, extra),
   kj_architect:   (a, server, extra) => handleArchitect(a, server, extra),
-  kj_audit:       (a, server, extra) => handleAudit(a, server, extra)
+  kj_audit:       (a, server, extra) => handleAudit(a, server, extra),
+  kj_board:       (a) => handleBoard(a)
 };
 
 export async function handleToolCall(name, args, server, extra) {

package/src/mcp/tools.js

@@ -306,5 +306,16 @@ export const tools = [
         kjHome: { type: "string" }
       }
     }
+  },
+  {
+    name: "kj_board",
+    description: "Start, stop, or check status of the HU Board dashboard",
+    inputSchema: {
+      type: "object",
+      properties: {
+        action: { type: "string", enum: ["start", "stop", "status"], description: "Action to perform (default: status)" },
+        port: { type: "number", description: "Port (default: 4000)" }
+      }
+    }
   }
 ];

package/src/orchestrator.js

@@ -156,8 +156,10 @@ function createBudgetManager({ config, emitter, eventBase }) {
     return s;
   }
 
-  function trackBudget({ role, provider, model, result, duration_ms }) {
-    const metrics = extractUsageMetrics(result, model);
+  function trackBudget({ role, provider, model, result, duration_ms, promptSize }) {
+    // Attach promptSize to result if provided, so extractUsageMetrics can estimate tokens
+    const enrichedResult = promptSize && result ? { ...result, promptSize } : result;
+    const metrics = extractUsageMetrics(enrichedResult, model);
     budgetTracker.record({ role, provider, ...metrics, duration_ms, stage_index: stageCounter++ });
 
     if (!hasBudgetLimit) return;
@@ -1124,6 +1126,26 @@ async function initFlowContext({ task, config, logger, emitter, askQuestion, pgT
     }));
   }
 
+  // --- HU Board auto-start ---
+  if (config.hu_board?.enabled && config.hu_board?.auto_start) {
+    try {
+      const { startBoard } = await import("./commands/board.js");
+      const boardPort = config.hu_board.port || 4000;
+      const boardResult = await startBoard(boardPort);
+      if (boardResult.alreadyRunning) {
+        logger.info(`HU Board already running at ${boardResult.url}`);
+      } else {
+        logger.info(`HU Board started at ${boardResult.url}`);
+      }
+      emitProgress(emitter, makeEvent("board:started", ctx.eventBase, {
+        message: `HU Board running at ${boardResult.url}`,
+        detail: { pid: boardResult.pid, port: boardPort }
+      }));
+    } catch (err) {
+      logger.warn(`HU Board auto-start failed (non-blocking): ${err.message}`);
+    }
+  }
+
   // --- Product Context ---
   const ctxProjectDir = config.projectDir || process.cwd();
   const { content: productContext, source: productContextSource } = await loadProductContext(ctxProjectDir);

package/templates/skills/kj-board.md

@@ -0,0 +1,16 @@
+# kj-board — HU Board Dashboard
+
+Manage the Karajan HU Board for visualizing user stories and sessions.
+
+## Your task
+
+$ARGUMENTS
+
+## Actions
+
+- **Start**: Run `kj board start` to launch the dashboard
+- **Stop**: Run `kj board stop` to stop it
+- **Status**: Run `kj board status` to check if running
+- **Open**: Run `kj board open` to open in browser
+
+The board auto-syncs with KJ pipeline data. No manual refresh needed.

package/templates/skills/kj-run.md

@@ -61,6 +61,10 @@ If all steps pass:
 2. Commit with conventional commit message: `feat:`, `fix:`, `refactor:`, etc.
 3. Do NOT push unless the user explicitly asks
 
+## HU Board Integration
+If HU Board is enabled (`hu_board.enabled: true` in config), stories and sessions
+are automatically tracked and visible at the board URL. Run `kj board` to start it.
+
 ## Important rules
 
 - **Never skip steps** — execute all applicable steps in order