karajan-code 2.5.0 → 2.6.0

package/src/checks/dir-setup.js

@@ -0,0 +1,63 @@
+/**
+ * Ensure ~/.karajan/ directory tree exists. Strategy: auto — creating
+ * directories under the user's home is non-invasive.
+ */
+
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { STRATEGY } from "./types.js";
+
+const REQUIRED_DIRS = [
+  "", // ~/.karajan/
+  "sessions",
+  "skills-cache",
+  "logs",
+];
+
+export function createKarajanDirsCheck() {
+  return {
+    name: "karajan-dirs",
+    label: "~/.karajan directory tree",
+    strategy: STRATEGY.AUTO,
+    describe: "Create missing ~/.karajan subdirectories",
+    async detect() {
+      const home = os.homedir();
+      const root = path.join(home, ".karajan");
+      const missing = [];
+      for (const sub of REQUIRED_DIRS) {
+        const full = sub ? path.join(root, sub) : root;
+        try {
+          const stat = await fs.stat(full);
+          if (!stat.isDirectory()) missing.push(full);
+        } catch {
+          missing.push(full);
+        }
+      }
+      if (missing.length === 0) {
+        return { ok: true, severity: "info", detail: `All ${REQUIRED_DIRS.length} directories present under ${root}` };
+      }
+      return {
+        ok: false,
+        severity: "fail",
+        detail: `Missing: ${missing.map((m) => path.relative(home, m)).join(", ")}`,
+        fix: `mkdir -p ${missing.join(" ")}`,
+        extra: { missing },
+      };
+    },
+    async remediate({ extra }) {
+      const missing = extra?.missing || [];
+      for (const dir of missing) {
+        await fs.mkdir(dir, { recursive: true });
+      }
+      return {
+        fixed: true,
+        detail: `Created ${missing.length} director${missing.length === 1 ? "y" : "ies"} under ~/.karajan`,
+      };
+    },
+  };
+}
+
+export function getDirSetupChecks() {
+  return [createKarajanDirsCheck()];
+}

package/src/checks/mcp-health.js

@@ -0,0 +1,157 @@
+/**
+ * MCP server health checks.
+ *
+ * Karajan integrates with several MCP servers — karajan-mcp (stdio), Serena,
+ * Sonar MCP, Planning Game MCP, etc. This module verifies they respond to
+ * a minimal JSON-RPC `initialize` call within a short deadline.
+ *
+ * For stdio MCPs that Karajan spawns itself (karajan-mcp), a failed ping is
+ * auto-remediable by re-spawning. External MCPs (Serena) are warn-only.
+ */
+
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import { STRATEGY } from "./types.js";
+import { withTimeout, TimeoutError } from "../utils/with-timeout.js";
+import { checkBinary } from "../utils/agent-detect.js";
+
+const PING_TIMEOUT_MS = 3000;
+
+/**
+ * Send a JSON-RPC `initialize` to an MCP server over stdio and wait for
+ * any response. Kills the process immediately after.
+ *
+ * @param {string} command
+ * @param {string[]} args
+ * @returns {Promise<{ok: boolean, detail: string}>}
+ */
+async function pingMcpStdio(command, args) {
+  const handshake = () =>
+    new Promise((resolve) => {
+      let child;
+      try {
+        child = spawn(command, args, { stdio: ["pipe", "pipe", "pipe"] });
+      } catch (err) {
+        resolve({ ok: false, detail: `spawn failed: ${err.message}` });
+        return;
+      }
+      let settled = false;
+      const finish = (ok, detail) => {
+        if (settled) return;
+        settled = true;
+        try {
+          child.kill();
+        } catch { /* already exited */ }
+        resolve({ ok, detail });
+      };
+      child.on("error", (err) => finish(false, `process error: ${err.message}`));
+      child.on("exit", (code) => {
+        if (!settled) finish(false, `exited with code ${code} before response`);
+      });
+      child.stdout.on("data", (buf) => {
+        const text = buf.toString();
+        // Any JSON-RPC response line counts as alive.
+        if (text.includes("\"jsonrpc\"") || text.includes("\"result\"") || text.includes("\"error\"")) {
+          finish(true, "Responded to initialize");
+        }
+      });
+      // Send initialize request
+      const req = JSON.stringify({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: {
+          protocolVersion: "2024-11-05",
+          clientInfo: { name: "kj-doctor", version: "1.0.0" },
+          capabilities: {},
+        },
+      });
+      try {
+        child.stdin.write(req + "\n");
+      } catch (err) {
+        finish(false, `stdin write failed: ${err.message}`);
+      }
+    });
+  try {
+    return await withTimeout(handshake(), PING_TIMEOUT_MS, "mcp-ping");
+  } catch (err) {
+    if (err instanceof TimeoutError) {
+      return { ok: false, detail: `No response within ${PING_TIMEOUT_MS}ms` };
+    }
+    return { ok: false, detail: err.message };
+  }
+}
+
+/**
+ * karajan-mcp health — stdio server bundled with this package.
+ * Strategy: auto (we can re-spawn it ourselves).
+ */
+export function createKarajanMcpCheck() {
+  return {
+    name: "mcp:karajan",
+    label: "MCP: karajan-mcp",
+    strategy: STRATEGY.AUTO,
+    describe: "Respawn karajan-mcp stdio process",
+    async detect() {
+      const binPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../bin/karajan-mcp.js");
+      const result = await pingMcpStdio(process.execPath, [binPath]);
+      return {
+        ok: result.ok,
+        severity: result.ok ? "info" : "warn",
+        detail: result.ok ? result.detail : `karajan-mcp did not respond: ${result.detail}`,
+        fix: result.ok ? undefined : "Re-run karajan-mcp via `node bin/karajan-mcp.js`",
+        extra: { binPath },
+      };
+    },
+    async remediate({ extra }) {
+      // Spawn once detached so the MCP client can pick it up for subsequent runs.
+      // This is idempotent: if one instance is already listening, another will
+      // coexist over a different pipe.
+      try {
+        spawn(process.execPath, [extra.binPath], { detached: true, stdio: "ignore" }).unref();
+        return { fixed: true, detail: "Re-spawned karajan-mcp in background" };
+      } catch (err) {
+        return { fixed: false, detail: `Failed to respawn: ${err.message}` };
+      }
+    },
+  };
+}
+
+/**
+ * Serena MCP — external tool the user installs themselves. Warn only when
+ * enabled in config. Strategy: manual (we don't manage its lifecycle).
+ */
+export function createSerenaMcpCheck() {
+  return {
+    name: "mcp:serena",
+    label: "MCP: serena",
+    strategy: STRATEGY.MANUAL,
+    applies: (config) => config?.serena?.enabled === true,
+    async detect() {
+      const bin = await checkBinary("serena");
+      if (!bin.ok) {
+        return {
+          ok: false,
+          severity: "warn",
+          detail: "serena binary not on PATH",
+          fix: "Install Serena: uvx --from git+https://github.com/oraios/serena serena",
+        };
+      }
+      const result = await pingMcpStdio("serena", ["start", "--mcp"]);
+      return {
+        ok: result.ok,
+        severity: result.ok ? "info" : "warn",
+        detail: result.ok ? "Serena responded to initialize" : `No response: ${result.detail}`,
+        fix: result.ok ? undefined : "Restart Serena manually and verify connectivity.",
+      };
+    },
+  };
+}
+
+/**
+ * Aggregate of MCP health checks. Only enabled servers run their ping.
+ */
+export function getMcpHealthChecks() {
+  return [createKarajanMcpCheck(), createSerenaMcpCheck()];
+}

package/src/checks/node.js

@@ -0,0 +1,61 @@
+/**
+ * Node.js runtime version check. Requires Node >= 20 (minimum version that
+ * ships structuredClone, Array.prototype.findLast, AbortSignal.timeout, and
+ * stable fetch). Strategy: manual — we cannot auto-upgrade the runtime.
+ */
+
+import { STRATEGY } from "./types.js";
+
+export const MIN_NODE_MAJOR = 20;
+
+/**
+ * Accepts a version string in the form "v20.12.1" or "20.12.1" and returns
+ * an object { major, minor, patch } or null when the shape is invalid.
+ */
+export function parseNodeVersion(versionString) {
+  const str = String(versionString || "").trim();
+  const m = str.match(/^v?(\d+)\.(\d+)\.(\d+)/);
+  if (!m) return null;
+  return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]) };
+}
+
+/**
+ * Create the Node version check. Accepts an optional override of the
+ * reported version (useful in tests).
+ *
+ * @param {{ version?: string }} [opts]
+ * @returns {import("./types.js").Check}
+ */
+export function createNodeVersionCheck(opts = {}) {
+  return {
+    name: "node-version",
+    label: "Node.js runtime",
+    strategy: STRATEGY.MANUAL,
+    async detect() {
+      const raw = opts.version ?? process.env.KJ_FORCE_NODE_VERSION ?? process.version;
+      const parsed = parseNodeVersion(raw);
+      if (!parsed) {
+        return {
+          ok: false,
+          severity: "fail",
+          detail: `Unrecognized Node version: ${raw}`,
+          fix: `Install Node ${MIN_NODE_MAJOR}+ from https://nodejs.org/ (current: ${raw}).`,
+        };
+      }
+      if (parsed.major < MIN_NODE_MAJOR) {
+        return {
+          ok: false,
+          severity: "fail",
+          detail: `Node ${raw} detected, requires >=${MIN_NODE_MAJOR}`,
+          fix: `Upgrade Node to ${MIN_NODE_MAJOR}+ (nvm install ${MIN_NODE_MAJOR} && nvm use ${MIN_NODE_MAJOR}, or brew upgrade node).`,
+          extra: { detected: parsed, required: MIN_NODE_MAJOR },
+        };
+      }
+      return { ok: true, severity: "info", detail: `${raw} (>= ${MIN_NODE_MAJOR} required)` };
+    },
+  };
+}
+
+export function getNodeChecks() {
+  return [createNodeVersionCheck()];
+}

package/src/checks/ports.js

@@ -0,0 +1,110 @@
+/**
+ * Port availability checks for services Karajan controls.
+ *
+ *   - SonarQube port (default 9000): the Docker container binds a fixed port,
+ *     so if it's occupied by a non-Karajan process we cannot "move" it; we
+ *     report FAIL with the occupant PID/command to help the user stop the
+ *     conflicting process. Strategy: manual.
+ *
+ *   - HU Board port (default 4000): an in-process Node server we can rebind
+ *     to any free port in runtime overrides. Strategy: auto.
+ */
+
+import { isPortAvailable, findAvailablePort } from "../utils/port-check.js";
+import { getPortOccupant } from "../utils/port-occupant.js";
+import { STRATEGY } from "./types.js";
+
+const DEFAULT_SONAR_PORT = 9000;
+const DEFAULT_HU_BOARD_PORT = 4000;
+
+function extractPortFromHost(host, fallback) {
+  const m = String(host || "").match(/:(\d+)(?:\/|$)/);
+  return m ? Number(m[1]) : fallback;
+}
+
+/**
+ * Whether the occupant looks like the Karajan-managed Sonar container.
+ * Docker Desktop's proxy is typically `com.docker.backend` / `com.docker.vmnetd`
+ * on macOS and `docker-proxy` on Linux. We treat those as OK.
+ */
+function isKarajanSonarOccupant(occupant) {
+  if (!occupant?.command) return false;
+  const cmd = occupant.command.toLowerCase();
+  return cmd.includes("docker") || cmd.includes("sonar");
+}
+
+export function createSonarPortCheck() {
+  return {
+    name: "port:sonar",
+    label: "SonarQube port",
+    strategy: STRATEGY.MANUAL,
+    applies: (config) => config?.sonarqube?.enabled !== false,
+    async detect({ config }) {
+      const port = extractPortFromHost(config?.sonarqube?.host, DEFAULT_SONAR_PORT);
+      const free = await isPortAvailable(port);
+      if (free) {
+        return { ok: true, severity: "info", detail: `Port ${port} is free (Sonar container not yet running)` };
+      }
+      // Busy — is it our container?
+      const occupant = await getPortOccupant(port);
+      if (occupant && isKarajanSonarOccupant(occupant)) {
+        return {
+          ok: true,
+          severity: "info",
+          detail: `Port ${port} held by Karajan-managed Sonar (${occupant.command} PID ${occupant.pid})`,
+        };
+      }
+      const who = occupant
+        ? `${occupant.command || "unknown"} (PID ${occupant.pid ?? "?"})`
+        : "unknown process";
+      return {
+        ok: false,
+        severity: "fail",
+        detail: `Port ${port} occupied by ${who}`,
+        fix: `Stop the process holding port ${port} or change sonarqube.host in kj.config.yml.`,
+        extra: { port, occupant },
+      };
+    },
+  };
+}
+
+export function createHuBoardPortCheck() {
+  return {
+    name: "port:hu-board",
+    label: "HU Board port",
+    strategy: STRATEGY.AUTO,
+    applies: (config) => config?.hu_board?.enabled !== false,
+    describe: "Rebind HU Board to the next free port",
+    async detect({ config }) {
+      const port = config?.hu_board?.port || DEFAULT_HU_BOARD_PORT;
+      const free = await isPortAvailable(port);
+      if (free) {
+        return { ok: true, severity: "info", detail: `Port ${port} is free` };
+      }
+      const occupant = await getPortOccupant(port);
+      const who = occupant
+        ? `${occupant.command || "unknown"} (PID ${occupant.pid ?? "?"})`
+        : "unknown process";
+      return {
+        ok: false,
+        severity: "warn",
+        detail: `Port ${port} occupied by ${who}`,
+        fix: `Free port ${port} or set hu_board.port in kj.config.yml`,
+        extra: { port, occupant },
+      };
+    },
+    async remediate({ extra }) {
+      const start = (extra?.port ?? DEFAULT_HU_BOARD_PORT) + 1;
+      const found = await findAvailablePort(start, 20);
+      return {
+        fixed: true,
+        detail: `Rebound HU Board to port ${found} (in-memory override)`,
+        changes: { hu_board: { port: found } },
+      };
+    },
+  };
+}
+
+export function getPortChecks() {
+  return [createSonarPortCheck(), createHuBoardPortCheck()];
+}

package/src/checks/rtk.js

@@ -0,0 +1,36 @@
+/**
+ * RTK (Rust Token Killer) availability check. Manual strategy — installation
+ * depends on the host platform and is handled by getInstallCommand().
+ */
+
+import { runCommand } from "../utils/process.js";
+import { getInstallCommand } from "../utils/os-detect.js";
+import { withDocLink } from "../utils/doc-links.js";
+import { STRATEGY } from "./types.js";
+
+export function createRtkCheck() {
+  return {
+    name: "rtk",
+    label: "RTK (Rust Token Killer)",
+    strategy: STRATEGY.MANUAL,
+    async detect() {
+      try {
+        const res = await runCommand("rtk", ["--version"]);
+        if (res.exitCode === 0) {
+          return { ok: true, severity: "info", detail: `${res.stdout.trim()} — token savings active` };
+        }
+      } catch { /* not installed */ }
+      const installCmd = getInstallCommand("rtk");
+      return {
+        ok: false,
+        severity: "warn",
+        detail: "Not found — 60-90% token savings available",
+        fix: withDocLink(`Install: ${installCmd}`, "rtk_install"),
+      };
+    },
+  };
+}
+
+export function getRtkChecks() {
+  return [createRtkCheck()];
+}

package/src/checks/runner.js

@@ -0,0 +1,267 @@
+/**
+ * Check runner. Orchestrates the detect → remediate → re-verify phases for
+ * a list of Check objects.
+ *
+ * Phase 1 (detect): executed in parallel with per-check timeout. Timeouts
+ * are reported as TIMEOUT status (WARN-level), never throw.
+ *
+ * Phase 2 (remediate): sequential, only for failures with strategy auto or
+ * prompt (and user consent for prompt). Skipped entirely when mode is
+ * "check-only". Each remediation has its own timeout (5s default, 60s for
+ * prompted actions like npm install).
+ *
+ * Phase 3 (re-verify): re-runs `detect` once for each check that was
+ * remediated, to confirm the fix actually worked. If re-verify fails, the
+ * status is FAIL (remediation lied).
+ *
+ * Runtime overrides returned by remediations are merged into `runReport.overrides`
+ * for consumers (e.g. preflight → orchestrator) to apply to the active session.
+ */
+
+import { STATUS, STRATEGY } from "./types.js";
+import { withTimeout, TimeoutError } from "../utils/with-timeout.js";
+
+const DEFAULT_DETECT_TIMEOUT_MS = 5000;
+const DEFAULT_REMEDIATE_TIMEOUT_MS = 60000;
+
+/**
+ * @param {import("./types.js").Check[]} checks
+ * @param {{ config: Object }} ctx
+ * @param {{
+ *   mode?: "fix"|"check-only",
+ *   yes?: boolean,
+ *   onConfirm?: (describe: string) => Promise<boolean>,
+ *   timeoutMs?: number,
+ *   remediateTimeoutMs?: number,
+ *   signal?: AbortSignal,
+ *   logger?: { info: Function, warn: Function, error: Function }
+ * }} [options]
+ * @returns {Promise<import("./types.js").RunReport>}
+ */
+export async function runChecks(checks, ctx, options = {}) {
+  const {
+    mode = "fix",
+    yes = false,
+    onConfirm = defaultOnConfirm,
+    timeoutMs = DEFAULT_DETECT_TIMEOUT_MS,
+    remediateTimeoutMs = DEFAULT_REMEDIATE_TIMEOUT_MS,
+    signal,
+    logger = silentLogger(),
+  } = options;
+
+  const { config } = ctx;
+  const startTotal = Date.now();
+  const entries = [];
+  const overrides = {};
+
+  // Build applicable entries (skipped checks noted up front).
+  for (const check of checks) {
+    if (typeof check.applies === "function" && !check.applies(config)) {
+      entries.push({
+        check,
+        status: STATUS.SKIPPED,
+        detail: "Not applicable for current configuration",
+        runMs: 0,
+        detectResult: null,
+        remediated: false,
+      });
+    } else {
+      entries.push({ check, status: null, detail: null, runMs: 0, detectResult: null, remediated: false });
+    }
+  }
+
+  // Phase 1: detect in parallel with timeout.
+  const detectBase = Date.now();
+  await Promise.all(
+    entries.map(async (entry) => {
+      if (entry.status === STATUS.SKIPPED) return;
+      const start = Date.now();
+      try {
+        const result = await withTimeout(entry.check.detect({ config, signal }), timeoutMs, entry.check.name);
+        entry.detectResult = result;
+        entry.runMs = Date.now() - start;
+        entry.status = resolveStatusFromDetect(entry.check, result);
+        entry.detail = result.detail;
+      } catch (err) {
+        entry.runMs = Date.now() - start;
+        if (err instanceof TimeoutError) {
+          entry.detectResult = { ok: false, severity: "warn", detail: `Timeout after ${timeoutMs}ms` };
+          entry.status = STATUS.TIMEOUT;
+          entry.detail = entry.detectResult.detail;
+        } else {
+          entry.detectResult = { ok: false, severity: "fail", detail: `Detection error: ${err.message}` };
+          entry.status = STATUS.FAIL;
+          entry.detail = entry.detectResult.detail;
+        }
+      }
+    })
+  );
+  logger.info?.(`Detect phase done in ${Date.now() - detectBase}ms`);
+
+  // Phase 2: remediate sequentially (only in "fix" mode, only failing checks).
+  if (mode !== "check-only") {
+    for (const entry of entries) {
+      if (!shouldAttemptRemediation(entry)) continue;
+      const { check, detectResult } = entry;
+      if (check.strategy === STRATEGY.PROMPT && !yes) {
+        const approved = await onConfirm(check.describe || `Fix: ${check.name}`);
+        if (!approved) {
+          logger.info?.(`User declined remediation for ${check.name}`);
+          continue;
+        }
+      }
+      const start = Date.now();
+      try {
+        const rem = await withTimeout(
+          check.remediate({ config, extra: detectResult.extra, signal, logger }),
+          remediateTimeoutMs,
+          `${check.name}:remediate`
+        );
+        entry.remediated = rem.fixed === true;
+        entry.runMs += Date.now() - start;
+        if (rem.fixed) {
+          if (rem.changes) mergeOverrides(overrides, rem.changes);
+          entry.detail = rem.detail;
+          entry.status = STATUS.FIXED;
+        } else {
+          entry.detail = rem.detail || entry.detail;
+          entry.status = STATUS.FAIL;
+        }
+      } catch (err) {
+        entry.runMs += Date.now() - start;
+        const msg = err instanceof TimeoutError ? `Remediation timeout after ${remediateTimeoutMs}ms` : `Remediation error: ${err.message}`;
+        entry.detail = msg;
+        entry.status = STATUS.FAIL;
+        logger.warn?.(`Remediation failed for ${check.name}: ${msg}`);
+      }
+    }
+
+    // Phase 3: re-verify fixed checks using the config merged with any
+    // runtime overrides applied by remediations. Without this merge, a check
+    // that rebinds to a new port (override) would re-verify against the old
+    // config and wrongly report failure.
+    const verifyConfig = mergeConfigAndOverrides(config, overrides);
+    await Promise.all(
+      entries.filter((e) => e.remediated).map(async (entry) => {
+        const start = Date.now();
+        try {
+          const result = await withTimeout(entry.check.detect({ config: verifyConfig, signal }), timeoutMs, `${entry.check.name}:reverify`);
+          entry.runMs += Date.now() - start;
+          if (!result.ok) {
+            entry.status = STATUS.FAIL;
+            entry.detail = `${entry.detail} (but re-verify failed: ${result.detail})`;
+          }
+        } catch (err) {
+          entry.runMs += Date.now() - start;
+          entry.status = STATUS.FAIL;
+          entry.detail = `${entry.detail} (re-verify error: ${err.message})`;
+        }
+      })
+    );
+  }
+
+  // Flatten into reports.
+  const reports = entries.map((e) => ({
+    name: e.check.name,
+    label: e.check.label,
+    status: e.status,
+    strategy: e.check.strategy,
+    detail: e.detail ?? "",
+    fix: e.detectResult?.fix,
+    runMs: e.runMs,
+  }));
+
+  const summary = summarize(reports);
+
+  return {
+    checks: reports,
+    overrides,
+    totalMs: Date.now() - startTotal,
+    summary,
+  };
+}
+
+function shouldAttemptRemediation(entry) {
+  if (entry.status === STATUS.SKIPPED) return false;
+  if (entry.status === STATUS.OK) return false;
+  if (entry.status === STATUS.TIMEOUT) return false; // don't remediate when detect itself timed out
+  const { check, detectResult } = entry;
+  if (!check.remediate || !detectResult) return false;
+  if (check.strategy === STRATEGY.MANUAL || check.strategy === STRATEGY.NONE) return false;
+  // Soft failures (WARN) with PROMPT strategy: don't nag the user for optional issues.
+  if (entry.status === STATUS.WARN && check.strategy === STRATEGY.PROMPT) return false;
+  return true;
+}
+
+function resolveStatusFromDetect(check, result) {
+  if (result.ok) return STATUS.OK;
+  const severity = result.severity || "fail";
+  if (severity === "warn") return STATUS.WARN;
+  if (severity === "info") return STATUS.OK; // info is always non-failing
+  if (check.strategy === STRATEGY.NONE) return STATUS.WARN;
+  return STATUS.FAIL;
+}
+
+function summarize(reports) {
+  const summary = { ok: 0, fixed: 0, warn: 0, fail: 0, skipped: 0, timeout: 0 };
+  for (const r of reports) {
+    const k = r.status.toLowerCase();
+    if (k in summary) summary[k]++;
+  }
+  return summary;
+}
+
+/**
+ * Deep-merge (shallow for now, one level deep) remediation changes into overrides.
+ * Remediation outputs like { hu_board: { port: 4007 } } should not overwrite a
+ * sibling key { hu_board: { enabled: true } } that a prior check set.
+ */
+function mergeOverrides(target, source) {
+  for (const [key, value] of Object.entries(source)) {
+    if (value && typeof value === "object" && !Array.isArray(value) && typeof target[key] === "object") {
+      Object.assign(target[key], value);
+    } else {
+      target[key] = value;
+    }
+  }
+}
+
+/**
+ * Produce a shallow-merged copy of config + overrides used during re-verify.
+ * Does not mutate the original config.
+ */
+function mergeConfigAndOverrides(config, overrides) {
+  if (!overrides || Object.keys(overrides).length === 0) return config;
+  const merged = { ...config };
+  for (const [key, value] of Object.entries(overrides)) {
+    if (value && typeof value === "object" && !Array.isArray(value) && typeof config[key] === "object") {
+      merged[key] = { ...config[key], ...value };
+    } else {
+      merged[key] = value;
+    }
+  }
+  return merged;
+}
+
+function defaultOnConfirm() {
+  // Non-interactive by default: refuse prompts unless the caller supplies a real handler.
+  return Promise.resolve(false);
+}
+
+function silentLogger() {
+  return { info() {}, warn() {}, error() {} };
+}
+
+/**
+ * Flatten a RunReport into the legacy doctor.js shape.
+ * OK/FIXED/SKIPPED → ok:true. WARN/FAIL/TIMEOUT → ok:false.
+ */
+export function toLegacyShape(runReport) {
+  return runReport.checks.map((c) => ({
+    name: c.name,
+    label: c.label,
+    ok: c.status === STATUS.OK || c.status === STATUS.FIXED || c.status === STATUS.SKIPPED,
+    detail: c.detail,
+    fix: c.fix ?? null,
+  }));
+}