@karajan-family/code 4.21.0

package/src/checks/node.js

@@ -0,0 +1,70 @@
+/**
+ * Node.js runtime version check. Requires Node >= 22 — the Active LTS
+ * baseline since Karajan v3.0.0 (KJC-TSK-0500, 2026-06-03). Node 20 was
+ * dropped because (a) Node 20 reaches EOL on 2026-04-30 and (b) three
+ * dependencies forced the bump: commander 15 needs ≥22.12.0 and
+ * better-sqlite3 v12.10+ dropped Node 20 prebuilds. engines.node is
+ * ">=22.12.0" — the highest RUNTIME floor. KJC-BUG-0111: it briefly sat
+ * at 22.22.1 (lint-staged 17's floor — a devDependency end users never
+ * run) and npm silently served karajan-code@2.34.0 to every Node
+ * 22.0-22.21 install; keep dev-tool floors out of engines.
+ * Strategy: manual — we cannot auto-upgrade the runtime. Users on older
+ * Node get a clear upgrade instruction with nvm + brew hints instead of a
+ * silent runtime crash.
+ */
+
+import { STRATEGY } from "./types.js";
+
+export const MIN_NODE_MAJOR = 22;
+
+/**
+ * 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/ollama.js

@@ -0,0 +1,41 @@
+// KJC-TSK-0437 — `kj doctor` check for the RAG embedder.
+// Only fires when rag.preload.enabled === true; otherwise reports
+// "Disabled in config" so doctor stays quiet on greenfield projects
+// that never opted in to RAG.
+import { isOllamaReachable } from "../rag/ollama-manager.js";
+import { STRATEGY } from "./types.js";
+
+function ragEnabled(config) {
+  return config?.rag?.preload?.enabled === true;
+}
+function ollamaHost(config) {
+  const port = config?.rag?.embedder?.port || 11434;
+  return config?.rag?.embedder?.host || `http://localhost:${port}`;
+}
+
+function createOllamaStatusCheck() {
+  return {
+    name: "ollama",
+    label: "Ollama (RAG embedder)",
+    strategy: STRATEGY.NONE,
+    async detect({ config }) {
+      if (!ragEnabled(config)) {
+        return { ok: true, severity: "info", detail: "Disabled in config (rag.preload.enabled=false)" };
+      }
+      const host = ollamaHost(config);
+      let reachable;
+      try { reachable = await isOllamaReachable(host); } catch { reachable = false; }
+      return {
+        ok: reachable,
+        severity: reachable ? "info" : "warn",
+        detail: reachable ? `Reachable at ${host}` : `Not reachable at ${host}`,
+        fix: reachable ? undefined : "Run `kj ollama start` to bootstrap the container, or `kj init --no-ollama` to opt out.",
+        extra: { host, reachable },
+      };
+    },
+  };
+}
+
+export function getOllamaChecks() {
+  return [createOllamaStatusCheck()];
+}

package/src/checks/orphans.js

@@ -0,0 +1,77 @@
+/**
+ * Orphaned scanner detection for `kj doctor` (KJC-TSK-0668). After the CPU
+ * storm, timed-out scans left semgrep-core processes reparented to init /
+ * systemd, silently burning cores. This check finds processes of tools kj
+ * governs whose parent is init (pid 1) or a systemd reaper, reports them,
+ * and — strategy "prompt" — offers to kill them.
+ */
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { STRATEGY } from "./types.js";
+
+const execFileAsync = promisify(execFile);
+const GOVERNED_TOOLS = new Set(["semgrep", "semgrep-core", "osv-scanner", "lighthouse"]);
+
+/**
+ * Scan the process table for governed tools whose parent is init or a
+ * systemd reaper (where the kernel sends orphans). `runPs` injectable.
+ */
+export async function findOrphanToolProcesses(runPs = execFileAsync) {
+  if (process.platform === "win32") return { supported: false, orphans: [] };
+  let stdout;
+  try {
+    ({ stdout } = await runPs("ps", ["-eo", "pid=,ppid=,comm="]));
+  } catch {
+    return { supported: false, orphans: [] };
+  }
+  const rows = [];
+  const commByPid = new Map();
+  for (const line of String(stdout).split("\n")) {
+    const m = line.trim().match(/^(\d+)\s+(\d+)\s+(.+)$/);
+    if (!m) continue;
+    const row = { pid: Number(m[1]), ppid: Number(m[2]), comm: m[3].trim() };
+    rows.push(row);
+    commByPid.set(row.pid, row.comm);
+  }
+  const orphans = rows.filter((r) =>
+    GOVERNED_TOOLS.has(r.comm) && (r.ppid === 1 || commByPid.get(r.ppid) === "systemd")
+  );
+  return { supported: true, orphans };
+}
+
+function createOrphanCheck() {
+  return {
+    name: "tool-orphans",
+    label: "Orphaned scanner processes",
+    strategy: STRATEGY.PROMPT,
+    describe: "Kill orphaned scanner processes left behind by interrupted runs",
+    async detect({ runPs } = {}) {
+      const { supported, orphans } = await findOrphanToolProcesses(runPs || execFileAsync);
+      if (!supported) return { ok: true, severity: "info", detail: "orphan detection not supported on this platform" };
+      if (orphans.length === 0) return { ok: true, severity: "info", detail: "no orphaned scanner processes" };
+      const list = orphans.map((o) => `${o.comm}(${o.pid})`).join(", ");
+      return {
+        ok: false,
+        severity: "warn",
+        detail: `${orphans.length} orphaned scanner process(es) burning CPU: ${list}`,
+        fix: `kill -9 ${orphans.map((o) => o.pid).join(" ")}`,
+        extra: { orphans },
+      };
+    },
+    async remediate({ extra, kill = process.kill } = {}) {
+      let killed = 0;
+      for (const o of extra?.orphans || []) {
+        try {
+          kill(o.pid, "SIGKILL");
+          killed += 1;
+        } catch { /* already gone */ }
+      }
+      return { fixed: killed > 0, detail: `killed ${killed} orphaned scanner process(es)` };
+    },
+  };
+}
+
+export function getOrphanChecks() {
+  return [createOrphanCheck()];
+}

package/src/checks/ports.js

@@ -0,0 +1,188 @@
+/**
+ * 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 { discoverRunningSonar } from "../sonar/discovery.js";
+import { isSonarReachable } from "../sonar/manager.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;
+}
+
+/**
+ * @internal Exported for dynamic import from tests/checks/ports.test.js
+ * and tests/checks/auto-remediation-e2e.test.js. Knip false positive.
+ */
+export function createSonarPortCheck() {
+  return {
+    name: "port:sonar",
+    label: "SonarQube port",
+    // AUTO since v2.7.5 — Karajan now resolves SonarQube discovery on
+    // its own. If a Sonar container is running anywhere (any name, any
+    // image tag), point Karajan at it. If port 9000 is occupied by
+    // someone non-Sonar, rebind to the next free port. Asking the user
+    // to "stop the unknown process" was busywork.
+    strategy: STRATEGY.AUTO,
+    applies: (config) => {
+      if (config?.sonarqube?.external === true) {
+        return { applies: false, reason: "sonarqube.external is true — port managed outside Karajan" };
+      }
+      return true;
+    },
+    describe: "Discover or rebind SonarQube port (no user action needed)",
+    async detect({ config }) {
+      const configuredPort = extractPortFromHost(config?.sonarqube?.host, DEFAULT_SONAR_PORT);
+
+      // Step 1 — is there ANY running SonarQube container we can reuse?
+      // Container name doesn't matter; we just need a published host port
+      // that responds to /api/system/status. This avoids "port 9000 is
+      // taken by an unknown process" errors when the unknown process is
+      // actually a perfectly good SonarQube from another project.
+      const discovered = await discoverRunningSonar();
+      if (discovered.found && discovered.reachable) {
+        // If the discovered host matches what's already configured,
+        // there's nothing to fix — happy path.
+        if (discovered.port === configuredPort) {
+          return {
+            ok: true,
+            severity: "info",
+            detail: `Reusing running SonarQube container "${discovered.containerName}" on port ${discovered.port}`,
+          };
+        }
+        // Otherwise we want to rewrite the host config at runtime.
+        return {
+          ok: false,
+          severity: "warn",
+          detail: `Found running SonarQube container "${discovered.containerName}" on port ${discovered.port} (config points at ${configuredPort})`,
+          extra: { remap: { host: discovered.host, port: discovered.port, container: discovered.containerName } },
+        };
+      }
+
+      // Step 2 — no running container. Is the configured port even free?
+      const free = await isPortAvailable(configuredPort);
+      if (free) {
+        return {
+          ok: true,
+          severity: "info",
+          detail: `Port ${configuredPort} is free (Sonar container will be started on demand)`,
+        };
+      }
+
+      // Step 3 — port is busy. Maybe the occupant IS Sonar but not
+      // discovered by `docker ps` (rare: bare-metal Sonar, host-network
+      // container, etc.). HTTP-probe to find out.
+      const probeHost = `http://localhost:${configuredPort}`;
+      if (await isSonarReachable(probeHost)) {
+        return {
+          ok: true,
+          severity: "info",
+          detail: `Port ${configuredPort} held by a Sonar instance (HTTP /api/system/status responds) — reusing it`,
+        };
+      }
+
+      // Step 4 — really not Sonar. Find an alternate free port and tell
+      // the runtime to use it. The compose template's published port is
+      // hardcoded at 9000 so we can't auto-rebind the container itself,
+      // but we CAN warn loudly with a clear, fixable message.
+      const occupant = await getPortOccupant(configuredPort);
+      const alt = await findAvailablePort(configuredPort + 1, 20);
+      if (alt) {
+        return {
+          ok: false,
+          severity: "warn",
+          detail: `Port ${configuredPort} occupied by ${occupant?.command || "unknown"} (PID ${occupant?.pid ?? "?"}). Will rebind Karajan-managed Sonar to ${alt}.`,
+          extra: { remap: { host: `http://localhost:${alt}`, port: alt, fromPort: configuredPort } },
+        };
+      }
+      // Last-resort failure (no free port in the next 20).
+      return {
+        ok: false,
+        severity: "fail",
+        detail: `Port ${configuredPort} occupied by ${occupant?.command || "unknown"} (PID ${occupant?.pid ?? "?"}) and no free port in ${configuredPort + 1}..${configuredPort + 20}`,
+        fix: "Stop the conflicting process or set sonarqube.host in kj.config.yml.",
+      };
+    },
+    async remediate({ extra }) {
+      if (!extra?.remap) {
+        return { fixed: false, detail: "No remap available" };
+      }
+      const { host, container, fromPort } = extra.remap;
+      const detail = container
+        ? `Pointed Karajan at running SonarQube ${container} (${host})`
+        : `Rebound Karajan-managed Sonar from port ${fromPort} to ${host}`;
+      return {
+        fixed: true,
+        detail,
+        // The runner merges this into the runtime config so every
+        // downstream Sonar caller (scanner, manager, MCP handler) sees
+        // the new host without the user touching kj.config.yml.
+        changes: { sonarqube: { host } },
+      };
+    },
+  };
+}
+
+/**
+ * @internal Exported for dynamic import from tests/checks/ports.test.js
+ * and tests/checks/auto-remediation-e2e.test.js. Knip false positive.
+ */
+export function createHuBoardPortCheck() {
+  return {
+    name: "port:hu-board",
+    label: "HU Board port",
+    strategy: STRATEGY.AUTO,
+    applies: (config) => {
+      if (config?.hu_board?.enabled === false) {
+        return { applies: false, reason: "hu_board.enabled is false in kj.config.yml — HU Board dashboard skipped" };
+      }
+      return true;
+    },
+    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/project-checks.js

@@ -0,0 +1,245 @@
+/**
+ * Project-aware preflight checks (KJC-TSK-0393).
+ *
+ * `kj doctor` (global) y el preflight estándar verifican el ENTORNO de Karajan
+ * (CLIs instaladas, node, dirs ~/.karajan/, sonar). Pero **nada** validaba que
+ * el PROYECTO actual tuviera lo que necesita: tools detectables por signals
+ * (docker si hay Dockerfile, firebase si hay firebase.json, etc.), permisos
+ * write sobre projectDir, configuración inicializada, .env consistente con
+ * .env.example.
+ *
+ * Este módulo registra checks dinámicos basados en signals del proyecto. Se
+ * integra en preflight-checks.js como "fase project-aware" tras la fase global.
+ * También expone `kj doctor --project` para ejecutar solo esta fase manualmente.
+ *
+ * Filosofía: si un check falla, el mensaje incluye el comando EJECUTABLE para
+ * resolverlo (no "Run X or Y"), y siempre que sea posible se marca como
+ * `degradable` (KJC-BUG-0049) para no abortar runs por features opcionales.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { runCommand } from "../utils/process.js";
+import { checkBinary } from "../utils/agent-detect.js";
+import { getInstallCommand } from "../utils/os-detect.js";
+import { STRATEGY } from "./types.js";
+
+/**
+ * Detect signals del proyecto. Devuelve un set de tags con qué hay en el
+ * projectDir. Pure-function, solo I/O de filesystem síncrono (rápido).
+ *
+ * @param {string} projectDir
+ * @returns {Set<string>}
+ */
+export function detectProjectSignals(projectDir) {
+  const signals = new Set();
+  if (!projectDir || !fs.existsSync(projectDir)) return signals;
+  const has = (rel) => fs.existsSync(path.join(projectDir, rel));
+  if (has("package.json")) signals.add("node");
+  if (has("Dockerfile") || has("docker-compose.yml") || has("compose.yml")) signals.add("docker");
+  if (has("firebase.json") || has(".firebaserc")) signals.add("firebase");
+  if (has("pyproject.toml") || has("requirements.txt") || has("setup.py")) signals.add("python");
+  if (has("Cargo.toml")) signals.add("rust");
+  if (has("go.mod")) signals.add("go");
+  if (has(".env.example") || has(".env.sample") || has(".env.template")) signals.add("env-example");
+  if (has(".env")) signals.add("env");
+  // Terraform / OpenTofu
+  try {
+    const entries = fs.readdirSync(projectDir);
+    if (entries.some((e) => e.endsWith(".tf") || e.endsWith(".tofu"))) signals.add("terraform");
+  } catch { /* unreadable dir */ }
+  return signals;
+}
+
+/**
+ * Check de tool específico del signal. Si el signal está presente pero la tool
+ * no, emite WARN con install command ejecutable.
+ */
+function createToolCheck({ signal, tool, label, signals }) {
+  return {
+    name: `project:tool:${tool}`,
+    label,
+    strategy: STRATEGY.MANUAL,
+    applies: () => signals.has(signal),
+    async detect() {
+      const res = await checkBinary(tool);
+      if (res.ok) {
+        return { ok: true, severity: "info", detail: `${tool} ${res.version} — required by ${signal} signal` };
+      }
+      const installCmd = getInstallCommand(tool) || `<install ${tool} for your OS>`;
+      return {
+        ok: false,
+        severity: "warn",
+        detail: `${tool} no instalada pero el proyecto tiene signal '${signal}' (puede no necesitarla para esta HU, pero la mayoría sí)`,
+        fix: installCmd,
+      };
+    },
+  };
+}
+
+/**
+ * Permisos write check. Critical: si projectDir, .kj/ o .karajan/ no son
+ * escribibles, el pipeline va a fallar muy tarde con errores oscuros.
+ */
+function createWritePermsCheck({ projectDir }) {
+  return {
+    name: "project:write-perms",
+    label: "Write permissions (projectDir + .kj/ + .karajan/)",
+    strategy: STRATEGY.MANUAL,
+    async detect() {
+      const targets = [
+        projectDir,
+        path.join(projectDir, ".kj"),
+        path.join(projectDir, ".karajan"),
+      ];
+      const failed = [];
+      for (const target of targets) {
+        try {
+          if (!fs.existsSync(target)) continue;
+          fs.accessSync(target, fs.constants.W_OK);
+        } catch {
+          failed.push(target);
+        }
+      }
+      if (failed.length === 0) {
+        return { ok: true, severity: "info", detail: "Karajan puede escribir en projectDir, .kj/ y .karajan/" };
+      }
+      return {
+        ok: false,
+        severity: "fail",
+        detail: `Sin permisos de escritura en: ${failed.join(", ")}`,
+        fix: `chmod -R u+w ${failed.join(" ")}`,
+      };
+    },
+  };
+}
+
+/**
+ * .env consistency check: si existe .env.example pero NO .env, o si las vars
+ * que .env.example declara faltan en .env, emite WARN con la lista.
+ */
+function createEnvConsistencyCheck({ projectDir, signals }) {
+  return {
+    name: "project:env-consistency",
+    label: ".env consistency (vs .env.example)",
+    strategy: STRATEGY.MANUAL,
+    applies: () => signals.has("env-example"),
+    async detect() {
+      const exampleFile = ["env.example", ".env.sample", ".env.template"]
+        .map((n) => path.join(projectDir, n.startsWith(".") ? n : `.${n}`))
+        .find((p) => fs.existsSync(p));
+      const realFile = path.join(projectDir, ".env");
+      const declaredVars = parseEnvKeys(exampleFile);
+      if (declaredVars.length === 0) {
+        return { ok: true, severity: "info", detail: ".env.example sin variables declaradas" };
+      }
+      const realVars = fs.existsSync(realFile) ? new Set(parseEnvKeys(realFile)) : new Set();
+      const missing = declaredVars.filter((k) => !realVars.has(k));
+      if (missing.length === 0) {
+        return { ok: true, severity: "info", detail: `.env tiene las ${declaredVars.length} variables declaradas en .env.example` };
+      }
+      return {
+        ok: false,
+        severity: "warn",
+        detail: `.env no declara ${missing.length} variable(s) que sí están en .env.example: ${missing.slice(0, 5).join(", ")}${missing.length > 5 ? "..." : ""}`,
+        fix: `cp ${path.basename(exampleFile)} .env && edit it`,
+      };
+    },
+  };
+}
+
+function parseEnvKeys(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, "utf8");
+    return content
+      .split("\n")
+      .map((l) => l.trim())
+      .filter((l) => l && !l.startsWith("#") && l.includes("="))
+      .map((l) => l.split("=")[0].trim())
+      .filter(Boolean);
+  } catch { return []; }
+}
+
+/**
+ * gh remote-specific check: cuando auto_pr está activo, no basta con que `gh`
+ * esté autenticado en general (eso lo cubre token:gh ya). Hay que verificar
+ * que el usuario tiene push access AL REMOTE de este proyecto.
+ */
+function createGhRemoteCheck({ projectDir }) {
+  return {
+    name: "project:gh-remote-access",
+    label: "GitHub push access (current remote)",
+    strategy: STRATEGY.MANUAL,
+    applies: (config) => config?.git?.auto_pr === true,
+    degradable: {
+      disables: ["git.auto_pr"],
+      warn: "auto_pr DESACTIVADO — no se pueden crear PRs al remote actual. Verifica permisos con `gh repo view`",
+    },
+    async detect() {
+      // Verifica que el remote responde a ls-remote (read access mínimo,
+      // proxy para push access — el push real solo se valida al pushear).
+      try {
+        const res = await runCommand("git", ["-C", projectDir, "ls-remote", "--heads", "origin"], { reject: false });
+        if (res.exitCode === 0) {
+          return { ok: true, severity: "info", detail: "Remote origin accesible vía git ls-remote" };
+        }
+        return {
+          ok: false,
+          severity: "warn",
+          detail: `git ls-remote origin falló (exit ${res.exitCode}): ${(res.stderr || "").slice(0, 120)}`,
+          fix: "Verifica el remote con `git remote -v` y la auth con `gh repo view`",
+        };
+      } catch (err) {
+        return { ok: false, severity: "warn", detail: `git ls-remote error: ${err.message}`, fix: "Verifica git remote y auth gh" };
+      }
+    },
+  };
+}
+
+/**
+ * `kj init` ran check: si no existe ~/.karajan/kj.config.yml NI .karajan/coder-rules.md,
+ * el usuario probablemente no ejecutó `kj init`. WARN con instrucción ejecutable.
+ */
+function createKjInitCheck({ projectDir }) {
+  return {
+    name: "project:kj-init-ran",
+    label: "Karajan project initialized",
+    strategy: STRATEGY.MANUAL,
+    async detect() {
+      const projectKjFile = path.join(projectDir, ".karajan", "coder-rules.md");
+      const globalKjFile = path.join(process.env.HOME || "", ".karajan", "kj.config.yml");
+      if (fs.existsSync(projectKjFile) || fs.existsSync(globalKjFile)) {
+        return { ok: true, severity: "info", detail: "Karajan config presente (global o local del proyecto)" };
+      }
+      return {
+        ok: false,
+        severity: "warn",
+        detail: "No se encontró kj.config.yml global ni .karajan/coder-rules.md local — probablemente falta `kj init`",
+        fix: "kj init",
+      };
+    },
+  };
+}
+
+/**
+ * Construye el set completo de project-aware checks basado en projectDir.
+ *
+ * @param {{ projectDir: string }} ctx
+ * @returns {Check[]}
+ */
+export function getProjectChecks({ projectDir }) {
+  if (!projectDir) return [];
+  const signals = detectProjectSignals(projectDir);
+  return [
+    createKjInitCheck({ projectDir }),
+    createWritePermsCheck({ projectDir }),
+    createToolCheck({ signal: "docker", tool: "docker", label: "Docker (project signal)", signals }),
+    createToolCheck({ signal: "firebase", tool: "firebase", label: "firebase-cli (project signal)", signals }),
+    createToolCheck({ signal: "python", tool: "python3", label: "Python 3 (project signal)", signals }),
+    createToolCheck({ signal: "rust", tool: "cargo", label: "Cargo / Rust (project signal)", signals }),
+    createToolCheck({ signal: "go", tool: "go", label: "Go (project signal)", signals }),
+    createToolCheck({ signal: "terraform", tool: "terraform", label: "Terraform (project signal)", signals }),
+    createEnvConsistencyCheck({ projectDir, signals }),
+    createGhRemoteCheck({ projectDir }),
+  ];
+}

package/src/checks/qmd.js

@@ -0,0 +1,41 @@
+/**
+ * QMD availability check. Manual strategy — installation
+ * depends on the host platform and is handled by getInstallCommand().
+ *
+ * QMD (Quick Markdown Search) provides semantic search over the
+ * user's wiki / docs / notes collections. Karajan ships it as a
+ * default integration (mirror of Squeezr): kj init installs it,
+ * kj doctor reports its presence.
+ */
+
+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";
+
+function createQmdCheck() {
+  return {
+    name: "qmd",
+    label: "QMD",
+    strategy: STRATEGY.MANUAL,
+    async detect() {
+      try {
+        const res = await runCommand("qmd", ["--version"]);
+        if (res.exitCode === 0) {
+          return { ok: true, severity: "info", detail: `${res.stdout.trim()} — semantic wiki active` };
+        }
+      } catch { /* not installed */ }
+      const installCmd = getInstallCommand("qmd");
+      return {
+        ok: false,
+        severity: "warn",
+        detail: "Not found — semantic wiki via QMD available",
+        fix: withDocLink(`Install: ${installCmd}`, "qmd_install"),
+      };
+    },
+  };
+}
+
+export function getQmdChecks() {
+  return [createQmdCheck()];
+}