karajan-code 2.5.0 → 2.6.0

package/src/config/schema.js

@@ -0,0 +1,222 @@
+/**
+ * Central Valibot schema for Karajan's configuration surface (KJC-TSK-0318).
+ *
+ * Origin: this schema is based on Jorge del Casar's original work in PR #379
+ * (closed). The full 650-line mirror-of-DEFAULTS approach he proposed drifted
+ * heavily against `main` by the time it was reviewed, so this file takes the
+ * same intent — validating Karajan config at load time with Valibot — but
+ * narrows the scope to the handful of fields where validation actually
+ * catches real bugs (review_mode, methodology, max_iterations, percentage
+ * budgets, port numbers). Everything else is defined with `v.looseObject` /
+ * `v.unknown()` so existing consumers who touch undeclared keys keep working.
+ *
+ * The runtime DEFAULTS object still lives in src/config.js — it is the source
+ * of truth for default values. This schema exists to reject invalid input
+ * early (e.g. `max_iterations: 0`, `review_mode: "yolo"`) with a clear error,
+ * and to give downstream consumers a typed handle via `KarajanConfig`.
+ *
+ * @typedef {import("valibot").InferOutput<typeof ConfigSchema>} KarajanConfig
+ */
+
+import * as v from "valibot";
+
+/**
+ * Positive integer (>= 1). Used where 0 / negative would be a clear bug
+ * (max_iterations, port, most timeout knobs when they gate the loop itself).
+ */
+const PositiveInt = v.pipe(
+  v.number("must be a number"),
+  v.integer("must be an integer"),
+  v.minValue(1, "must be >= 1")
+);
+
+/**
+ * Non-negative integer (>= 0). Used for retry counts where 0 is a valid
+ * "don't retry" signal.
+ */
+const NonNegativeInt = v.pipe(
+  v.number("must be a number"),
+  v.integer("must be an integer"),
+  v.minValue(0, "must be >= 0")
+);
+
+/**
+ * review_mode picklist — anything outside this set is a typo.
+ */
+const ReviewMode = v.picklist(
+  ["paranoid", "strict", "standard", "relaxed", "custom"],
+  "review_mode must be one of: paranoid | strict | standard | relaxed | custom"
+);
+
+const Methodology = v.picklist(
+  ["tdd", "standard"],
+  "development.methodology must be one of: tdd | standard"
+);
+
+/**
+ * Role entry — provider + model, both nullable. Extra keys allowed.
+ */
+const RoleEntry = v.looseObject({
+  provider: v.optional(v.nullable(v.string())),
+  model: v.optional(v.nullable(v.string())),
+});
+
+const RolesMap = v.optional(v.looseObject({
+  planner: v.optional(RoleEntry),
+  coder: v.optional(RoleEntry),
+  reviewer: v.optional(RoleEntry),
+  refactorer: v.optional(RoleEntry),
+  solomon: v.optional(RoleEntry),
+  researcher: v.optional(RoleEntry),
+  tester: v.optional(RoleEntry),
+  security: v.optional(RoleEntry),
+  impeccable: v.optional(RoleEntry),
+  triage: v.optional(RoleEntry),
+  discover: v.optional(RoleEntry),
+  architect: v.optional(RoleEntry),
+  hu_reviewer: v.optional(RoleEntry),
+}));
+
+const PipelineEntry = v.looseObject({
+  enabled: v.optional(v.boolean()),
+});
+
+const PipelineMap = v.optional(v.looseObject({
+  planner: v.optional(PipelineEntry),
+  refactorer: v.optional(PipelineEntry),
+  solomon: v.optional(PipelineEntry),
+  researcher: v.optional(PipelineEntry),
+  tester: v.optional(PipelineEntry),
+  security: v.optional(PipelineEntry),
+  impeccable: v.optional(PipelineEntry),
+  triage: v.optional(PipelineEntry),
+  discover: v.optional(PipelineEntry),
+  architect: v.optional(PipelineEntry),
+  hu_reviewer: v.optional(PipelineEntry),
+  auto_simplify: v.optional(v.boolean()),
+}));
+
+const Development = v.optional(v.looseObject({
+  methodology: v.optional(Methodology),
+  require_test_changes: v.optional(v.boolean()),
+  test_file_patterns: v.optional(v.array(v.string())),
+  source_file_extensions: v.optional(v.array(v.string())),
+}));
+
+const Git = v.optional(v.looseObject({
+  auto_commit: v.optional(v.boolean()),
+  auto_push: v.optional(v.boolean()),
+  auto_pr: v.optional(v.boolean()),
+  auto_rebase: v.optional(v.boolean()),
+  branch_prefix: v.optional(v.string()),
+}));
+
+const ReviewerOptions = v.optional(v.looseObject({
+  output_format: v.optional(v.string()),
+  require_schema: v.optional(v.boolean()),
+  model: v.optional(v.nullable(v.string())),
+  deterministic: v.optional(v.boolean()),
+  retries: v.optional(NonNegativeInt, 1),
+  fallback_reviewer: v.optional(v.nullable(v.string())),
+}));
+
+const CoderOptions = v.optional(v.looseObject({
+  model: v.optional(v.nullable(v.string())),
+  auto_approve: v.optional(v.boolean()),
+  fallback_coder: v.optional(v.nullable(v.string())),
+}));
+
+const HuBoard = v.optional(v.looseObject({
+  enabled: v.optional(v.boolean()),
+  port: v.optional(v.pipe(
+    v.number("hu_board.port must be a number"),
+    v.integer(),
+    v.minValue(1, "hu_board.port must be >= 1"),
+    v.maxValue(65535, "hu_board.port must be <= 65535")
+  )),
+  auto_start: v.optional(v.boolean()),
+}));
+
+/**
+ * Budget warn threshold: 0-100 percent. Anything outside is nonsense.
+ */
+const Budget = v.optional(v.looseObject({
+  warn_threshold_pct: v.optional(v.pipe(
+    v.number(),
+    v.minValue(0, "budget.warn_threshold_pct must be 0-100"),
+    v.maxValue(100, "budget.warn_threshold_pct must be 0-100")
+  )),
+  currency: v.optional(v.string()),
+  exchange_rate_eur: v.optional(v.number()),
+  pricing: v.optional(v.unknown()),
+}));
+
+/**
+ * Main config schema. `looseObject` lets every consumer that reads an
+ * undeclared key keep working while the schema catches the bugs we care
+ * about.
+ */
+export const ConfigSchema = v.looseObject({
+  coder: v.optional(v.string()),
+  reviewer: v.optional(v.string()),
+  roles: RolesMap,
+  pipeline: PipelineMap,
+  review_mode: v.optional(ReviewMode),
+  max_iterations: v.optional(PositiveInt, 5),
+  hu_max_iterations: v.optional(PositiveInt, 3),
+  max_budget_usd: v.optional(v.nullable(v.pipe(
+    v.number(),
+    v.minValue(0, "max_budget_usd must be >= 0")
+  ))),
+  review_rules: v.optional(v.string()),
+  coder_rules: v.optional(v.string()),
+  base_branch: v.optional(v.string()),
+  coder_options: CoderOptions,
+  reviewer_options: ReviewerOptions,
+  development: Development,
+  git: Git,
+  hu_board: HuBoard,
+  budget: Budget,
+  language: v.optional(v.string()),
+  hu_language: v.optional(v.string()),
+  policies: v.optional(v.record(v.string(), v.unknown())),
+  telemetry: v.optional(v.boolean()),
+});
+
+/**
+ * Parse a raw merged config against the schema. Returns the normalized
+ * config or throws a Valibot ValiError. Call sites should wrap this in a
+ * try/catch that re-throws with a friendlier prefix.
+ *
+ * @param {unknown} input
+ * @returns {KarajanConfig}
+ */
+export function parseConfig(input) {
+  return v.parse(ConfigSchema, input);
+}
+
+/**
+ * Safe variant — returns { success, data } | { success: false, issues } so
+ * callers can decide how to report errors without catching ValiError.
+ * @param {unknown} input
+ */
+export function safeParseConfig(input) {
+  const result = v.safeParse(ConfigSchema, input);
+  if (result.success) return { success: true, data: result.output };
+  return {
+    success: false,
+    issues: result.issues.map(i => ({
+      path: (i.path || []).map(p => p.key).join("."),
+      message: i.message,
+    })),
+  };
+}
+
+/**
+ * Aggregate Valibot issues into a single readable string. Used by loadConfig
+ * to produce actionable error messages instead of the default ValiError dump.
+ * @param {Array<{path: string, message: string}>} issues
+ */
+export function formatConfigIssues(issues) {
+  return issues.map(i => (i.path ? `${i.path}: ${i.message}` : i.message)).join("\n");
+}

package/src/config.js

@@ -3,6 +3,11 @@ import path from "node:path";
 import yaml from "js-yaml";
 import { ensureDir, exists } from "./utils/fs.js";
 import { getKarajanHome } from "./utils/paths.js";
+import { safeParseConfig, formatConfigIssues } from "./config/schema.js";
+
+/**
+ * @typedef {import("./config/schema.js").KarajanConfig} KarajanConfig
+ */
 
 const DEFAULTS = {
   coder: "claude",
@@ -266,6 +271,16 @@ export async function loadConfig(projectDir) {
     merged.budget = mergeDeep(merged.budget || {}, { pricing: projectPricing });
   }
 
+  // KJC-TSK-0318 — schema-validate the merged config so invalid values
+  // (review_mode typos, max_iterations=0, out-of-range ports) surface at
+  // load time with a clear error instead of crashing deep inside the
+  // orchestrator. safeParse + explicit error prefix keeps the message
+  // actionable.
+  const validation = safeParseConfig(merged);
+  if (!validation.success) {
+    throw new Error(`Invalid Karajan config:\n${formatConfigIssues(validation.issues)}`);
+  }
+
   return { config: merged, path: configPath, exists: globalExists, hasProjectConfig: !!projectConfig };
 }
 
@@ -303,10 +318,13 @@ const PIPELINE_ENABLE_FLAGS = [
 
 const AUTO_SIMPLIFY_FLAG = "autoSimplify";
 
-// Scalar flags: [flagName, setter] — truthy check
+// Scalar flags: [flagName, setter] — truthy check.
+// Note: max_iterations was previously here but `0` was silently ignored
+// (truthy check skipped it). It now lives in UNDEF_CHECK_FLAGS so
+// `--max-iterations 0` reaches the schema validator and errors cleanly
+// instead of falling through to the default (KJC-TSK-0318).
 const SCALAR_FLAGS = [
   ["mode", (out, v) => { out.review_mode = v; }],
-  ["maxIterations", (out, v) => { out.max_iterations = Number(v); }],
   ["maxIterationMinutes", (out, v) => { out.session.max_iteration_minutes = Number(v); }],
   ["maxTotalMinutes", (out, v) => { out.session.max_total_minutes = Number(v); }],
   ["checkpointInterval", (out, v) => { out.session.checkpoint_interval_minutes = Number(v); }],
@@ -317,8 +335,11 @@ const SCALAR_FLAGS = [
   ["branchPrefix", (out, v) => { out.git.branch_prefix = String(v); }]
 ];
 
-// Boolean/undefined-check flags: [flagName, setter] — !== undefined check
+// Boolean/undefined-check flags: [flagName, setter] — !== undefined check.
+// These preserve falsy values (false, 0) so --no-rebase correctly sets
+// auto_rebase=false and --reviewer-retries 0 correctly disables retries.
 const UNDEF_CHECK_FLAGS = [
+  ["maxIterations", (out, v) => { out.max_iterations = Number(v); }],
   ["reviewerRetries", (out, v) => { out.reviewer_options.retries = Number(v); }],
   ["autoCommit", (out, v) => { out.git.auto_commit = Boolean(v); }],
   ["autoPush", (out, v) => { out.git.auto_push = Boolean(v); }],
@@ -431,6 +452,14 @@ export function applyRunOverrides(config, flags) {
   applyMiscOverrides(out, flags);
   applyOutputModeOverrides(out, flags);
 
+  // KJC-TSK-0318 — re-run schema validation after overrides so CLI flags
+  // that would produce an invalid config (e.g. --max-iterations 0) fail
+  // fast with the same clear message loadConfig would have produced.
+  const validation = safeParseConfig(out);
+  if (!validation.success) {
+    throw new Error(`Invalid Karajan config after CLI overrides:\n${formatConfigIssues(validation.issues)}`);
+  }
+
   return out;
 }
 

package/src/guards/policy-resolver.js

@@ -1,3 +1,11 @@
+/**
+ * Policy resolution: map task type + config toggles to concrete pipeline
+ * flags (TDD, Sonar, reviewer retries, tests required, coder required, ...).
+ *
+ * @typedef {import("../types/policy.js").ResolvedPolicies} ResolvedPolicies
+ * @typedef {import("../types/config.js").KarajanConfig} KarajanConfig
+ */
+
 export const VALID_TASK_TYPES = new Set(["sw", "infra", "doc", "add-tests", "refactor", "audit", "analysis", "no-code"]);
 
 export const DEFAULT_POLICIES = {

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) {