karajan-code 2.4.1 → 2.6.0

package/src/hu/store.js

@@ -1,3 +1,12 @@
+/**
+ * HU (Historia de Usuario / User Story) storage. Persists HU batches and
+ * their stories to the session directory.
+ *
+ * @typedef {import("../types/hu.js").HUStory} HUStory
+ * @typedef {import("../types/hu.js").HUBatch} HUBatch
+ * @typedef {import("../types/hu.js").HUStatus} HUStatus
+ */
+
 import fs from "node:fs/promises";
 import path from "node:path";
 import { execFile } from "node:child_process";

package/src/infrastructure/command-runner.js

@@ -0,0 +1,44 @@
+/**
+ * CommandRunner — DI-friendly adapter over execa / runCommand.
+ *
+ * Why: agent adapters (claude, codex, gemini, ...) all end up invoking
+ * src/utils/process.js -> runCommand. That makes unit-testing the agent layer
+ * slow and flaky — every test either spins up a real child process or stubs
+ * execa deep inside Vitest's module graph.
+ *
+ * This adapter preserves the runCommand API exactly, so current consumers
+ * can opt-in to DI without behavioural changes. A matching MockCommandRunner
+ * lives in src/infrastructure/mocks.js and lets tests script outputs per
+ * invocation.
+ *
+ * @typedef {Object} CommandRunResult
+ * @property {number} exitCode
+ * @property {string} stdout
+ * @property {string} stderr
+ * @property {boolean} [timedOut]
+ * @property {string|null} [signal]
+ *
+ * @typedef {Object} CommandRunOptions
+ * @property {number} [timeout]
+ * @property {(evt: {stream: string, line: string}) => void} [onOutput]
+ * @property {number} [silenceTimeoutMs]
+ * @property {number} [partialOutputFlushMs]
+ * @property {string|Buffer} [input]
+ * @property {string} [cwd]
+ * @property {Record<string,string>} [env]
+ *
+ * @typedef {Object} CommandRunner
+ * @property {(command: string, args?: string[], options?: CommandRunOptions) => Promise<CommandRunResult>} run
+ */
+
+import { runCommand } from "../utils/process.js";
+
+/**
+ * Default implementation — delegates to runCommand.
+ * @type {CommandRunner}
+ */
+export const defaultCommandRunner = {
+  async run(command, args = [], options = {}) {
+    return runCommand(command, args, options);
+  }
+};

package/src/infrastructure/environment.js

@@ -0,0 +1,38 @@
+/**
+ * Environment — the DI bundle passed to services that need filesystem + command
+ * execution. Grouping them keeps call sites small: `new BaseAgent(..., env)`
+ * instead of `new BaseAgent(..., fs, runner)`.
+ *
+ * @typedef {import("./file-system-service.js").FileSystemService} FileSystemService
+ * @typedef {import("./command-runner.js").CommandRunner} CommandRunner
+ *
+ * @typedef {Object} Environment
+ * @property {FileSystemService} fs
+ * @property {CommandRunner} runner
+ */
+
+import { defaultFileSystem } from "./file-system-service.js";
+import { defaultCommandRunner } from "./command-runner.js";
+
+/**
+ * Default environment uses native fs + real execa-based runner.
+ * Tests should inject a custom environment via buildEnvironment() below.
+ * @type {Environment}
+ */
+export const defaultEnvironment = Object.freeze({
+  fs: defaultFileSystem,
+  runner: defaultCommandRunner
+});
+
+/**
+ * Merge overrides on top of the default environment. Missing properties fall
+ * back to defaults, so callers can replace only the pieces they care about.
+ * @param {Partial<Environment>} [overrides]
+ * @returns {Environment}
+ */
+export function buildEnvironment(overrides = {}) {
+  return Object.freeze({
+    fs: overrides.fs ?? defaultFileSystem,
+    runner: overrides.runner ?? defaultCommandRunner
+  });
+}

package/src/infrastructure/file-system-service.js

@@ -0,0 +1,63 @@
+/**
+ * FileSystemService — thin DI-friendly adapter over node:fs/promises.
+ *
+ * Why: existing code uses node:fs directly (see src/utils/fs.js and consumers),
+ * which makes unit-testing orchestrator/agent paths slow and flaky — every test
+ * that exercises a code path touching fs has to stage real files on disk.
+ *
+ * This adapter preserves the exact native API shapes for the handful of
+ * operations actually used in the codebase, so consumers can opt-in to DI
+ * without rewriting call sites. A matching MockFileSystem lives in
+ * src/infrastructure/mocks.js.
+ *
+ * Scope for TSK-0316: intentionally minimal. Only the operations already used
+ * by orchestrator + agents. Additional methods added on demand.
+ *
+ * @typedef {Object} FileSystemService
+ * @property {(path: string, encoding?: string) => Promise<string|Buffer>} readFile
+ * @property {(path: string, data: string|Buffer, encoding?: string) => Promise<void>} writeFile
+ * @property {(path: string, data: string|Buffer, encoding?: string) => Promise<void>} appendFile
+ * @property {(path: string) => Promise<boolean>} exists
+ * @property {(path: string) => Promise<void>} ensureDir
+ * @property {(path: string) => Promise<string[]>} readdir
+ * @property {(src: string, dest: string) => Promise<void>} copyFile
+ * @property {(path: string) => Promise<{size: number, isDirectory: () => boolean, isFile: () => boolean}>} stat
+ */
+
+import fs from "node:fs/promises";
+
+/**
+ * Default implementation backed by node:fs/promises.
+ * @type {FileSystemService}
+ */
+export const defaultFileSystem = {
+  async readFile(path, encoding = "utf8") {
+    return fs.readFile(path, encoding);
+  },
+  async writeFile(path, data, encoding = "utf8") {
+    await fs.writeFile(path, data, encoding);
+  },
+  async appendFile(path, data, encoding = "utf8") {
+    await fs.appendFile(path, data, encoding);
+  },
+  async exists(path) {
+    try {
+      await fs.access(path);
+      return true;
+    } catch {
+      return false;
+    }
+  },
+  async ensureDir(path) {
+    await fs.mkdir(path, { recursive: true });
+  },
+  async readdir(path) {
+    return fs.readdir(path);
+  },
+  async copyFile(src, dest) {
+    await fs.copyFile(src, dest);
+  },
+  async stat(path) {
+    return fs.stat(path);
+  }
+};

package/src/infrastructure/mocks.js

@@ -0,0 +1,182 @@
+/**
+ * Test doubles for the DI surfaces. Intentionally dumb — tests stage inputs
+ * through simple setters and assert on recorded calls.
+ *
+ * @typedef {import("./file-system-service.js").FileSystemService} FileSystemService
+ * @typedef {import("./command-runner.js").CommandRunner} CommandRunner
+ * @typedef {import("./command-runner.js").CommandRunResult} CommandRunResult
+ * @typedef {import("./command-runner.js").CommandRunOptions} CommandRunOptions
+ */
+
+/**
+ * In-memory file system. Paths are stored as-is (no normalization) to keep
+ * behaviour predictable in tests.
+ */
+export class MockFileSystem {
+  constructor(initial = {}) {
+    /** @type {Map<string, string|Buffer>} */
+    this.files = new Map(Object.entries(initial));
+    /** @type {Set<string>} */
+    this.directories = new Set();
+    /** @type {Array<{op: string, path: string, args?: unknown}>} */
+    this.calls = [];
+  }
+
+  _record(op, path, args) {
+    this.calls.push({ op, path, args });
+  }
+
+  async readFile(path, encoding = "utf8") {
+    this._record("readFile", path, { encoding });
+    if (!this.files.has(path)) {
+      const err = new Error(`ENOENT: no such file or directory, open '${path}'`);
+      err.code = "ENOENT";
+      throw err;
+    }
+    const data = this.files.get(path);
+    if (Buffer.isBuffer(data) && encoding) return data.toString(encoding);
+    return data;
+  }
+
+  async writeFile(path, data, encoding = "utf8") {
+    this._record("writeFile", path, { encoding });
+    this.files.set(path, data);
+  }
+
+  async appendFile(path, data, encoding = "utf8") {
+    this._record("appendFile", path, { encoding });
+    const prev = this.files.get(path) ?? "";
+    this.files.set(path, String(prev) + String(data));
+  }
+
+  async exists(path) {
+    this._record("exists", path);
+    return this.files.has(path) || this.directories.has(path);
+  }
+
+  async ensureDir(path) {
+    this._record("ensureDir", path);
+    this.directories.add(path);
+  }
+
+  async readdir(path) {
+    this._record("readdir", path);
+    const prefix = path.endsWith("/") ? path : path + "/";
+    const entries = new Set();
+    for (const p of this.files.keys()) {
+      if (p.startsWith(prefix)) {
+        const tail = p.slice(prefix.length).split("/")[0];
+        if (tail) entries.add(tail);
+      }
+    }
+    if (!entries.size && !this.directories.has(path)) {
+      const err = new Error(`ENOENT: no such file or directory, scandir '${path}'`);
+      err.code = "ENOENT";
+      throw err;
+    }
+    return [...entries];
+  }
+
+  async copyFile(src, dest) {
+    this._record("copyFile", src, { dest });
+    if (!this.files.has(src)) {
+      const err = new Error(`ENOENT: no such file or directory, copyfile '${src}' -> '${dest}'`);
+      err.code = "ENOENT";
+      throw err;
+    }
+    this.files.set(dest, this.files.get(src));
+  }
+
+  async stat(path) {
+    this._record("stat", path);
+    if (this.files.has(path)) {
+      const data = this.files.get(path);
+      const size = Buffer.isBuffer(data) ? data.length : Buffer.byteLength(String(data));
+      return {
+        size,
+        isDirectory: () => false,
+        isFile: () => true
+      };
+    }
+    if (this.directories.has(path)) {
+      return {
+        size: 0,
+        isDirectory: () => true,
+        isFile: () => false
+      };
+    }
+    const err = new Error(`ENOENT: no such file or directory, stat '${path}'`);
+    err.code = "ENOENT";
+    throw err;
+  }
+}
+
+/**
+ * Scripted command runner. Tests call enqueue() to stage responses in order,
+ * or setResponder() for a per-invocation decision. Every run() is recorded.
+ */
+export class MockCommandRunner {
+  constructor() {
+    /** @type {Array<CommandRunResult>} */
+    this.queue = [];
+    /** @type {Array<{command: string, args: string[], options: CommandRunOptions}>} */
+    this.calls = [];
+    /** @type {null | ((args: {command: string, args: string[], options: CommandRunOptions}) => CommandRunResult|Promise<CommandRunResult>)} */
+    this.responder = null;
+    /** @type {CommandRunResult} */
+    this.defaultResponse = { exitCode: 0, stdout: "", stderr: "" };
+  }
+
+  /**
+   * Queue a response. FIFO — first enqueued is returned on the first run().
+   * @param {Partial<CommandRunResult>} response
+   */
+  enqueue(response) {
+    this.queue.push({ exitCode: 0, stdout: "", stderr: "", ...response });
+    return this;
+  }
+
+  /**
+   * Replace FIFO queue with a function that decides per-call.
+   * @param {(args: {command: string, args: string[], options: CommandRunOptions}) => CommandRunResult|Promise<CommandRunResult>} fn
+   */
+  setResponder(fn) {
+    this.responder = fn;
+    return this;
+  }
+
+  /**
+   * @param {string} command
+   * @param {string[]} args
+   * @param {CommandRunOptions} options
+   * @returns {Promise<CommandRunResult>}
+   */
+  async run(command, args = [], options = {}) {
+    this.calls.push({ command, args: [...args], options: { ...options } });
+    if (this.responder) return this.responder({ command, args, options });
+    if (this.queue.length > 0) return this.queue.shift();
+    return { ...this.defaultResponse };
+  }
+
+  /**
+   * Convenience: last recorded invocation, or null.
+   */
+  get lastCall() {
+    return this.calls.at(-1) ?? null;
+  }
+}
+
+/**
+ * Build an Environment backed by the mocks above. Useful shorthand in tests:
+ *
+ *   const { env, fs, runner } = buildMockEnvironment();
+ *   const agent = new BaseAgent(..., env);
+ *
+ * @param {{files?: Record<string, string|Buffer>}} [opts]
+ */
+export function buildMockEnvironment({ files } = {}) {
+  const fs = new MockFileSystem(files);
+  const runner = new MockCommandRunner();
+  const env = Object.freeze({ fs, runner });
+  return { env, fs, runner };
+}

package/src/mcp/handlers/management-handlers.js

@@ -157,8 +157,13 @@ export function handleInit(a) {
   return runKjCommand({ command: "init", options: a });
 }
 
-export function handleDoctor(a) {
-  return runKjCommand({ command: "doctor", options: a });
+export function handleDoctor(a = {}) {
+  const commandArgs = [];
+  if (a.checkOnly) commandArgs.push("--check-only");
+  if (a.yes) commandArgs.push("--yes");
+  if (a.json) commandArgs.push("--json");
+  if (a.verbose) commandArgs.push("--verbose");
+  return runKjCommand({ command: "doctor", commandArgs, options: a });
 }
 
 export function handleConfig(a) {

package/src/mcp/tools.js

@@ -12,12 +12,16 @@ export const tools = [
   },
   {
     name: "kj_doctor",
-    description: "Check system dependencies and agent CLIs",
+    description: "Check system dependencies, agent CLIs, ports, tokens and MCP health — auto-remediates when possible",
     inputSchema: {
       type: "object",
       properties: {
         kjHome: { type: "string" },
-        timeoutMs: { type: "number" }
+        timeoutMs: { type: "number" },
+        checkOnly: { type: "boolean", description: "Detect only, do not apply fixes" },
+        yes: { type: "boolean", description: "Auto-confirm prompts for invasive remediations" },
+        json: { type: "boolean", description: "Emit machine-readable JSON output" },
+        verbose: { type: "boolean", description: "Include fix hints and timing per check" }
       }
     }
   },
@@ -105,7 +109,10 @@ export const tools = [
         kjHome: { type: "string" },
         sonarToken: { type: "string" },
         timeoutMs: { type: "number" },
-        domain: { type: "string", description: "Domain knowledge: inline text describing the project domain, or absolute path to a .md file. Auto-saved to .karajan/domains/ for the curator." }
+        domain: { type: "string", description: "Domain knowledge: inline text describing the project domain, or absolute path to a .md file. Auto-saved to .karajan/domains/ for the curator." },
+        brain: { type: "string", enum: ["on", "off"], description: "Brain decisor: on|off. Controls whether intent-driven routing overrides pipeline flags." },
+        forceRole: { type: "array", items: { type: "string" }, description: "Force roles ON regardless of triage (e.g. [\"security\"])" },
+        skipRole: { type: "array", items: { type: "string" }, description: "Force roles OFF regardless of triage (e.g. [\"tester\"])" }
       }
     }
   },

package/src/orchestrator/config-init.js

@@ -10,6 +10,7 @@ import { buildReviewerPrompt } from "../prompts/reviewer.js";
 import { resolveRole } from "../config.js";
 import { emitProgress, makeEvent } from "../utils/events.js";
 import { BudgetTracker, extractUsageMetrics } from "../utils/budget.js";
+import { computeKjComparison } from "../budget/comparison.js";
 import { resolveRoleMdPath, loadFirstExisting } from "../roles/base-role.js";
 import { applyPolicies } from "../guards/policy-resolver.js";
 import { resolveReviewProfile } from "../review/profiles.js";
@@ -280,7 +281,7 @@ export async function handleDryRun({ task, config, flags, emitter, pipelineFlags
   return summary;
 }
 
-export function createBudgetManager({ config, emitter, eventBase }) {
+export function createBudgetManager({ config, emitter, eventBase, getCompressionStats = null }) {
   const budgetTracker = new BudgetTracker({ pricing: config?.budget?.pricing });
   const budgetLimit = Number(config?.max_budget_usd);
   const hasBudgetLimit = Number.isFinite(budgetLimit) && budgetLimit >= 0;
@@ -290,6 +291,20 @@ export function createBudgetManager({ config, emitter, eventBase }) {
   function budgetSummary() {
     const s = budgetTracker.summary();
     s.trace = budgetTracker.trace();
+    // Attach the "With KJ vs Without KJ" comparison when compression data
+    // is available (TSK-0274). hasCompression: false means no savings to
+    // report; the display falls back to the plain cost line.
+    if (typeof getCompressionStats === "function") {
+      try {
+        const stats = getCompressionStats() || {};
+        s.kj_comparison = computeKjComparison({
+          realTokens: s.total_tokens,
+          realCost: s.total_cost_usd,
+          rtkSavings: stats.rtkSavings,
+          brainCtx: stats.brainCtx,
+        });
+      } catch { /* best-effort — omit comparison on failure */ }
+    }
     return s;
   }