@karajan-family/code 4.21.0

package/src/checks/dir-setup.js

@@ -0,0 +1,103 @@
+/**
+ * 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";
+import { getKarajanHome } from "../utils/paths.js";
+
+const REQUIRED_DIRS = [
+  "", // ~/.karajan/
+  "sessions",
+  "skills-cache",
+  "logs",
+];
+
+/**
+ * @internal Exported for dynamic import from tests/checks/dir-setup.test.js
+ * and tests/checks/auto-remediation-e2e.test.js. Knip false positive.
+ */
+export function createKarajanDirsCheck() {
+  return {
+    name: "karajan-dirs",
+    label: "~/.karajan directory tree",
+    strategy: STRATEGY.AUTO,
+    describe: "Create missing ~/.karajan subdirectories",
+    async detect() {
+      // KJC-TSK-0420: KARAJAN_HOME / KJ_HOME aware via getKarajanHome().
+      const root = getKarajanHome();
+      const home = os.homedir(); // still needed for path.relative() below
+      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`,
+      };
+    },
+  };
+}
+
+/**
+ * Detect a populated legacy `~/.kj/` left over from before
+ * KJC-PCS-0047 PR 3. The auto-migrator (src/utils/home-migration.js)
+ * moves its contents to `~/.karajan/` on the next `kj` invocation,
+ * so the fix is simply "run any kj command". Severity is `warn`
+ * (informational) because the legacy dir does not break anything —
+ * it just won't get read by the board until the migration runs.
+ * @internal Exported for dynamic import from tests.
+ */
+export function createLegacyKjHomeCheck() {
+  return {
+    name: "legacy-kj-home",
+    label: "legacy ~/.kj/ directory",
+    strategy: STRATEGY.MANUAL,
+    describe: "Detect unmigrated ~/.kj/ left over from pre-2.19 layout",
+    async detect() {
+      const legacy = path.join(os.homedir(), ".kj");
+      try {
+        const entries = await fs.readdir(legacy);
+        if (entries.length === 0) return { ok: true, severity: "info", detail: "Empty legacy ~/.kj/" };
+        const marker = path.join(getKarajanHome(), ".kj-migrated.json"); // KJC-TSK-0420
+        try { await fs.access(marker); return { ok: true, severity: "info", detail: "Already migrated" }; }
+        catch { /* no marker, still pending */ }
+        return {
+          ok: false,
+          severity: "warn",
+          detail: `~/.kj/ still has ${entries.length} entries; will be migrated on the next kj invocation`,
+          fix: "Run any kj command (e.g. `kj doctor`) — the migrator runs automatically",
+        };
+      } catch { return { ok: true, severity: "info", detail: "No legacy ~/.kj/" }; }
+    },
+  };
+}
+
+export function getDirSetupChecks() {
+  return [createKarajanDirsCheck(), createLegacyKjHomeCheck()];
+}

package/src/checks/guarantee-level.js

@@ -0,0 +1,38 @@
+/**
+ * Guarantee level en runtime (KJC-TSK-0756, hallazgo de campo de Pedro):
+ * la doctrina "kj jamás finge una supervisión que no puede aplicar" vivía
+ * solo en el README — ahora kj doctor la DECLARA para el host actual, con
+ * el porqué. El acoplamiento a Claude es UNA capa (tier A: hooks síncronos
+ * bloqueantes, que hoy solo ese harness expone) y es decisión de ADR
+ * (v4.13), no accidente; el tier B (git gates) es el suelo agnóstico.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { detectHostAgent } from "../utils/agent-detect.js";
+
+/** Pure: computes the three tiers from observable facts. */
+export function guaranteeLevel({ host, harnessWired, policyDeclared, policyWorkflow }) {
+  const tierA = host === "claude" && harnessWired
+    ? { active: true, reason: "Claude Code expone hooks síncronos bloqueantes y el harness del Sentinel está instalado (kj harden)" }
+    : host === "claude"
+      ? { active: false, reason: "host Claude sin harness instalado — corre kj harden para activar la supervisión en el turno" }
+      : { active: false, reason: `el host ${host ?? "desconocido"} no expone hooks síncronos bloqueantes — no se finge la supervisión; el tier B sigue siendo el suelo de garantía` };
+  const tierB = { active: true, reason: "los gates viven en el repositorio, no en el harness: cualquier host, el diff violador no entra" };
+  const tierC = policyDeclared && policyWorkflow
+    ? { active: true, reason: "kj-policy.yml re-verifica el PR contra la policy declarada (merge-blocking)" }
+    : policyDeclared
+      ? { active: false, reason: "hay policy declarada pero sin workflow de CI — corre kj harden para sembrar kj-policy.yml" }
+      : { active: false, reason: "sin .karajan/policy.yml declarada — el tier C solo existe donde hay policy que verificar" };
+  return { host: host ?? null, tierA, tierB, tierC };
+}
+
+/** Facts from disk + env; injectable for tests. */
+export function collectGuaranteeFacts({ projectDir = process.cwd(), deps = {} } = {}) {
+  const { detectHost = detectHostAgent, exists = existsSync } = deps;
+  return guaranteeLevel({
+    host: detectHost(),
+    harnessWired: exists(join(projectDir, ".karajan", "harness", "pretooluse-sentinel.mjs")),
+    policyDeclared: exists(join(projectDir, ".karajan", "policy.yml")),
+    policyWorkflow: exists(join(projectDir, ".github", "workflows", "kj-policy.yml")),
+  });
+}

package/src/checks/hardware.js

@@ -0,0 +1,150 @@
+// Advisory hardware checks: warn (not fail) so the pipeline keeps running.
+// RAM < 4 GB silently OOM-kills the RAG embedder; disk < 5 GB corrupts
+// Ollama model shards. GPU detection is best-effort and never throws.
+
+import os from "node:os";
+import { statfs } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import { STRATEGY } from "./types.js";
+
+const RAM_WARN_GB = 4;
+const RAM_RECOMMENDED_GB = 8;
+const DISK_WARN_GB = 5;
+const DISK_RECOMMENDED_GB = 20;
+const GPU_DETECT_TIMEOUT_MS = 1500;
+
+const bytesToGb = (bytes) => Math.round((bytes / 1024 ** 3) * 10) / 10;
+const info = (detail, extra) => ({ ok: true, severity: "info", detail, extra });
+const warn = (detail, fix, extra) => ({ ok: false, severity: "warn", detail, fix, extra });
+
+function createRamCheck() {
+  return {
+    name: "hw-ram",
+    label: "System RAM",
+    strategy: STRATEGY.MANUAL,
+    async detect() {
+      const totalGb = bytesToGb(os.totalmem());
+      const freeGb = bytesToGb(os.freemem());
+      const base = `${totalGb} GB total, ${freeGb} GB free`;
+      if (totalGb < RAM_WARN_GB) {
+        return warn(
+          `${base} (RAG embedder needs >=${RAM_WARN_GB} GB)`,
+          "Disable local RAG (kj init --no-rag) or switch rag.embedder.provider to openai/voyage/cohere.",
+          { totalGb, freeGb, threshold: RAM_WARN_GB }
+        );
+      }
+      if (totalGb < RAM_RECOMMENDED_GB) {
+        return info(`${base} (>=${RAM_RECOMMENDED_GB} GB recommended for parallel runs)`, { totalGb, freeGb });
+      }
+      return info(base, { totalGb, freeGb });
+    },
+  };
+}
+
+function createCpuCheck() {
+  return {
+    name: "hw-cpu",
+    label: "CPU",
+    strategy: STRATEGY.NONE,
+    async detect() {
+      const cpus = os.cpus();
+      const model = cpus[0]?.model?.trim() || "unknown";
+      const cores = cpus.length;
+      const arch = os.arch();
+      return info(`${cores} cores, ${arch} (${model})`, { cores, arch, model });
+    },
+  };
+}
+
+function createDiskCheck() {
+  return {
+    name: "hw-disk",
+    label: "Disk space (cwd)",
+    strategy: STRATEGY.MANUAL,
+    async detect() {
+      try {
+        const stat = await statfs(process.cwd());
+        const freeGb = bytesToGb(stat.bsize * stat.bavail);
+        if (freeGb < DISK_WARN_GB) {
+          return warn(
+            `${freeGb} GB free (>=${DISK_WARN_GB} GB recommended)`,
+            "Free disk space. Ollama models alone take 3-5 GB; the RAG store grows ~50 MB per 1k LOC indexed.",
+            { freeGb, threshold: DISK_WARN_GB }
+          );
+        }
+        const note = freeGb < DISK_RECOMMENDED_GB ? ` (>=${DISK_RECOMMENDED_GB} GB recommended)` : "";
+        return info(`${freeGb} GB free${note}`, { freeGb });
+      } catch (err) {
+        return info(`Cannot read free disk space: ${err.message}`);
+      }
+    },
+  };
+}
+
+function runGpuCommand(cmd, args) {
+  return new Promise((resolve) => {
+    let stdout = "";
+    let settled = false;
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      resolve(value);
+    };
+    try {
+      const child = spawn(cmd, args, { stdio: ["ignore", "pipe", "ignore"] });
+      const timer = setTimeout(() => {
+        try { child.kill("SIGKILL"); } catch { /* noop */ }
+        finish(null);
+      }, GPU_DETECT_TIMEOUT_MS);
+      child.stdout.on("data", (chunk) => { stdout += chunk.toString(); });
+      child.on("error", () => { clearTimeout(timer); finish(null); });
+      child.on("close", (code) => {
+        clearTimeout(timer);
+        finish(code === 0 ? stdout : null);
+      });
+    } catch {
+      finish(null);
+    }
+  });
+}
+
+async function detectGpu() {
+  const platform = process.platform;
+  if (platform === "linux" || platform === "win32") {
+    const out = await runGpuCommand("nvidia-smi", ["--query-gpu=name", "--format=csv,noheader"]);
+    const model = out?.split("\n").map((l) => l.trim()).find(Boolean);
+    if (model) return { vendor: "NVIDIA", model };
+    return null;
+  }
+  if (platform === "darwin") {
+    const out = await runGpuCommand("system_profiler", ["SPDisplaysDataType"]);
+    if (!out) return null;
+    const match = out.match(/Chipset Model:\s*(.+)/);
+    if (!match) return null;
+    const model = match[1].trim();
+    const vendor = /Apple/i.test(model) ? "Apple" : /AMD|Radeon/i.test(model) ? "AMD" : /Intel/i.test(model) ? "Intel" : "GPU";
+    return { vendor, model };
+  }
+  return null;
+}
+
+function createGpuCheck() {
+  return {
+    name: "hw-gpu",
+    label: "GPU",
+    strategy: STRATEGY.NONE,
+    async detect() {
+      const gpu = await detectGpu();
+      if (!gpu) {
+        return info("No discrete GPU detected (CPU-only)", { detected: false });
+      }
+      return info(`${gpu.vendor} ${gpu.model}`, { detected: true, vendor: gpu.vendor, model: gpu.model });
+    },
+  };
+}
+
+export function getHardwareChecks() {
+  return [createRamCheck(), createCpuCheck(), createDiskCheck(), createGpuCheck()];
+}
+
+export const __test = { RAM_WARN_GB, RAM_RECOMMENDED_GB, DISK_WARN_GB, DISK_RECOMMENDED_GB, GPU_DETECT_TIMEOUT_MS, bytesToGb, detectGpu };

package/src/checks/harness-scorecard.js

@@ -0,0 +1,41 @@
+// KJC-TSK-0470 — `kj doctor` check for the AI Harness Scorecard image.
+// Reports Disabled / Docker missing / Image not pulled / OK. The image
+// is pulled lazily by `kj audit` on first use; this check is informational.
+import { isDockerAvailable, isHarnessImagePresent, normalizeHarnessConfig } from "../audit/harness-scorecard.js";
+import { STRATEGY } from "./types.js";
+
+function harnessEnabled(config) { return config?.audit?.harness?.enabled !== false; }
+
+function createHarnessScorecardCheck() {
+  return {
+    name: "harness-scorecard",
+    label: "AI Harness Scorecard (audit)",
+    strategy: STRATEGY.NONE,
+    async detect({ config }) {
+      const cfg = normalizeHarnessConfig(config?.audit?.harness || {});
+      if (!harnessEnabled(config)) {
+        return { ok: true, severity: "info", detail: "Disabled in config (audit.harness.enabled=false)" };
+      }
+      let docker; try { docker = await isDockerAvailable(); } catch { docker = false; }
+      if (!docker) return {
+        ok: false, severity: "warn",
+        detail: "Docker not available — kj audit will skip the harness step.",
+        fix: "Install Docker (or run `kj audit --no-harness` to silence this).",
+        extra: { docker: false, image: cfg.image },
+      };
+      let cached; try { cached = await isHarnessImagePresent(cfg.image); } catch { cached = false; }
+      if (!cached) return {
+        ok: true, severity: "info",
+        detail: `Will be pulled on first \`kj audit\` run (${cfg.image}).`,
+        extra: { docker: true, cached: false, image: cfg.image },
+      };
+      return {
+        ok: true, severity: "info",
+        detail: `Image cached locally (${cfg.image}).`,
+        extra: { docker: true, cached: true, image: cfg.image },
+      };
+    },
+  };
+}
+
+export function getHarnessScorecardChecks() { return [createHarnessScorecardCheck()]; }

package/src/checks/mcp-health.js

@@ -0,0 +1,169 @@
+/**
+ * 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).
+ *
+ * @internal Exported for dynamic import from tests/checks/mcp-health.test.js.
+ * Knip false positive.
+ */
+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",
+        // KJC-BUG-0118: the MCP is OPTIONAL in the v4 environment (the host
+        // agent drives kj via CLI) — a dead MCP must read as a degraded
+        // optional, never as a broken install. The standalone (curl) binary
+        // cannot run it at all (no bundled native modules).
+        detail: result.ok
+          ? result.detail
+          : `karajan-mcp did not respond: ${result.detail} — OPTIONAL in v4: your agent runs kj directly; only shell-less hosts need MCP`,
+        fix: result.ok ? undefined : "Only if you need MCP: install via npm (`npm i -g karajan-code`) — the standalone binary does not bundle it",
+        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).
+ *
+ * @internal Exported for dynamic import from tests/checks/mcp-health.test.js.
+ * Knip false positive.
+ */
+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/method.js

@@ -0,0 +1,73 @@
+/**
+ * Method report (KJC-TSK-0689, MG-D of épica KJC-PCS-0068). Individual
+ * deviations can each be legitimate — the AGGREGATE trail is the drift
+ * detector. Three measurable signals over the recent history: commit
+ * subjects without a card reference, review verdicts by workspace
+ * ([root] vs lanes), and source commits without a single test change.
+ * Informative by design; only a card-ref drought turns it into a warn.
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { runCommand } from "../utils/process.js";
+import { checkTestsWithCode } from "../review/tests-with-code.js";
+import { CARD_REF_RE } from "../review/card-first.js";
+import { STRATEGY } from "./types.js";
+
+function recentVerdicts(projectDir, sample) {
+  try {
+    const dir = path.join(projectDir, ".karajan", "reviews");
+    return readdirSync(dir).filter((f) => f.endsWith(".json"))
+      .map((f) => JSON.parse(readFileSync(path.join(dir, f), "utf8")))
+      .sort((a, b) => String(b.timestamp).localeCompare(String(a.timestamp)))
+      .slice(0, sample);
+  } catch {
+    return [];
+  }
+}
+
+export async function collectMethodStats({ projectDir, run = runCommand, sample = 20 } = {}) {
+  const subjectsRes = await run("git", ["log", `-${sample}`, "--no-merges", "--format=%s"], { cwd: projectDir });
+  const subjects = subjectsRes.exitCode === 0 ? subjectsRes.stdout.split("\n").filter(Boolean) : [];
+
+  // "@%h" carries a % so git treats it as a literal format string — a bare
+  // "@" is rejected as an unknown pretty alias (caught in a live smoke).
+  const blocksRes = await run("git", ["log", `-${Math.min(sample, 10)}`, "--no-merges", "--name-only", "--format=@%h"], { cwd: projectDir });
+  const blocks = blocksRes.exitCode === 0
+    ? blocksRes.stdout.split(/^@.*$/m).map((b) => b.split("\n").map((l) => l.trim()).filter(Boolean)).filter((b) => b.length > 0)
+    : [];
+  const offenders = blocks.filter((files) => checkTestsWithCode({ config: {}, stagedFiles: files, env: {} }).mode !== "pass").length;
+
+  const verdicts = recentVerdicts(projectDir, sample);
+  const stamped = verdicts.filter((v) => v.workspace);
+
+  return {
+    commits: { total: subjects.length, withCard: subjects.filter((s) => CARD_REF_RE.test(s)).length },
+    verdicts: { total: verdicts.length, stamped: stamped.length, root: stamped.filter((v) => v.workspace === "root").length },
+    testless: { sampled: blocks.length, offenders },
+  };
+}
+
+export function formatMethodStats(s) {
+  return `commits with card ref ${s.commits.withCard}/${s.commits.total} · verdict workspaces root ${s.verdicts.root}/${s.verdicts.stamped || 0} stamped (${s.verdicts.total} total) · source commits without tests ${s.testless.offenders}/${s.testless.sampled}`;
+}
+
+function createMethodCheck() {
+  return {
+    name: "method",
+    label: "Method adherence (recent history)",
+    strategy: STRATEGY.NONE,
+    async detect({ config = {}, projectDir = process.cwd(), run = runCommand } = {}) {
+      const stats = await collectMethodStats({ projectDir, run, sample: config.method_gates?.report_sample || 20 });
+      const detail = formatMethodStats(stats);
+      const drought = stats.commits.total >= 5 && stats.commits.withCard / stats.commits.total < 0.5;
+      if (drought) {
+        return { ok: false, severity: "warn", detail: `most recent commits carry no card reference — ${detail}` };
+      }
+      return { ok: true, severity: "info", detail };
+    },
+  };
+}
+
+export function getMethodChecks() {
+  return [createMethodCheck()];
+}

package/src/checks/native-build.js

@@ -0,0 +1,67 @@
+/**
+ * Native build availability check (KJC-BUG-0092).
+ *
+ * better-sqlite3 ships a native addon compiled in a postinstall step. pnpm
+ * blocks dependency build scripts by default (ERR_PNPM_IGNORED_BUILDS), so a
+ * `pnpm add -g karajan-code` leaves the addon uncompiled: `kj --version` still
+ * works (it never opens a DB) but any DB-backed command (board, rag, cost
+ * tracking) crashes with "Cannot find module 'better-sqlite3'". This surfaces a
+ * WARN in `kj doctor` with the exact remedy instead of a cryptic runtime crash.
+ */
+
+import { STRATEGY } from "./types.js";
+
+/** pnpm lays packages out under a `.pnpm` virtual store and symlinks them in. */
+function isPnpmInstall() {
+  return (
+    import.meta.url.includes("/.pnpm/") ||
+    (process.env.npm_config_user_agent || "").includes("pnpm")
+  );
+}
+
+/** Force the native binding to load by opening an in-memory database. */
+async function defaultLoadDb() {
+  const Database = (await import("better-sqlite3")).default;
+  new Database(":memory:").close();
+}
+
+export function createNativeBuildCheck({ loadDb = defaultLoadDb, isPnpm = isPnpmInstall } = {}) {
+  return {
+    name: "native-build",
+    label: "native modules (better-sqlite3)",
+    strategy: STRATEGY.MANUAL,
+    async detect() {
+      try {
+        await loadDb();
+        return {
+          ok: true,
+          severity: "info",
+          detail: "better-sqlite3 native addon loads — DB-backed commands available",
+        };
+      } catch (err) {
+        const firstLine = String(err?.message || err).split("\n")[0];
+        if (isPnpm()) {
+          return {
+            ok: false,
+            severity: "warn",
+            detail: "better-sqlite3 native build was skipped — pnpm blocks dependency build scripts by default",
+            fix: "Approve the build then reinstall: `pnpm approve-builds better-sqlite3` — or install with npm: `npm i -g karajan-code`",
+          };
+        }
+        return {
+          ok: false,
+          severity: "warn",
+          // KJC-BUG-0118: the standalone (curl) binary ships without native
+          // modules by design — name the consequence (RAG/board/MCP need the
+          // npm install) instead of implying the install is broken.
+          detail: `better-sqlite3 failed to load: ${firstLine} — DB-backed features (RAG, board, MCP) unavailable; the standalone binary does not bundle native modules`,
+          fix: "Reinstall to rebuild native modules: `npm i -g karajan-code`",
+        };
+      }
+    },
+  };
+}
+
+export function getNativeBuildChecks() {
+  return [createNativeBuildCheck()];
+}