@karajan-family/code 4.21.0

package/src/checks/rag-hooks.js

@@ -0,0 +1,54 @@
+/**
+ * RAG post-merge hook wiring check (KJC-BUG-0100).
+ *
+ * `kj rag install-hooks` used to write the hook into `.git/hooks/post-merge`,
+ * but when a repo is hardened `git config core.hooksPath` points at
+ * `.karajan/hooks` and git ignores `.git/hooks/` entirely — so the RAG index
+ * silently never refreshes after a merge. This check resolves the *effective*
+ * hooks dir and reports whether the post-merge hook there reindexes the RAG.
+ * The pre-run drift check in `kj run` already covers the gap, so a missing
+ * hook is advisory (info), not a failure — it surfaces the state without
+ * nagging every repo that never ran `kj rag install-hooks`.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { STRATEGY } from "./types.js";
+import { resolveHooksDir } from "../rag/auto-update.js";
+
+export function createRagHooksCheck({ projectDir } = {}) {
+  return {
+    name: "rag-hooks",
+    label: "RAG post-merge refresh",
+    strategy: STRATEGY.MANUAL,
+    async detect() {
+      const dir = projectDir || process.cwd();
+      let hooks;
+      try {
+        hooks = await resolveHooksDir(dir);
+      } catch {
+        return { ok: true, severity: "info", detail: "not a git repository — no post-merge hook to wire" };
+      }
+      const target = join(hooks.dir, "post-merge");
+      const wired = existsSync(target) && /kj\s+rag\s+index/.test(readFileSync(target, "utf8"));
+      if (wired) {
+        return {
+          ok: true,
+          severity: "info",
+          detail: `post-merge reindexes the RAG (${hooks.hooksPath || ".git/hooks"})`,
+        };
+      }
+      const where = hooks.hooksPath ? ` — core.hooksPath=${hooks.hooksPath}` : "";
+      return {
+        ok: false,
+        severity: "info",
+        detail: `RAG index won't auto-refresh after merges${where}; pre-run drift check still covers \`kj run\``,
+        fix: "Wire the post-merge hook: `kj rag install-hooks`",
+      };
+    },
+  };
+}
+
+export function getRagHooksChecks({ projectDir } = {}) {
+  return [createRagHooksCheck({ projectDir })];
+}

package/src/checks/release-check.js

@@ -0,0 +1,102 @@
+/**
+ * release-check (KJC-TSK-0712) — the release checklist made verifiable:
+ * a note loses salience; a check fails RED with the exact list. Generics
+ * fit any karajan project; each project extends via `release_check.items`
+ * (file_contains with {version}, or command with exit-0 semantics).
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { runCommand } from "../utils/process.js";
+import { loadPrivacyList, scanPaths } from "../privacy/scan.js";
+
+const semverCmp = (a, b) => {
+  const pa = a.split(".").map(Number), pb = b.split(".").map(Number);
+  for (let i = 0; i < 3; i++) if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) - (pb[i] || 0);
+  return 0;
+};
+
+async function genericChecks(projectDir) {
+  const checks = [];
+  const pkgPath = join(projectDir, "package.json");
+  if (!existsSync(pkgPath)) {
+    checks.push({ name: "manifest", ok: true, detail: "no package.json — generic version checks skipped (declared items still run)" });
+    return { checks, version: null, pkg: null };
+  }
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+  const version = pkg.version;
+  checks.push({ name: "manifest", ok: Boolean(version), detail: version ? `version ${version}` : "package.json has no version" });
+
+  const clPath = join(projectDir, "CHANGELOG.md");
+  if (existsSync(clPath)) {
+    const cl = readFileSync(clPath, "utf8");
+    const topVersioned = (cl.match(/^## \[(\d+\.\d+\.\d+)\]/m) || [])[1] || null;
+    // Content still sitting under [Unreleased] means unpromoted entries —
+    // the tarball would ship changes its release notes do not tell.
+    const afterUnreleased = cl.split(/^## \[Unreleased\]\s*$/m)[1] ?? "";
+    const unreleasedBody = afterUnreleased.split(/^## \[/m)[0] ?? "";
+    const pending = /\S/.test(unreleasedBody);
+    const ok = topVersioned === version && !pending;
+    let detail = `top section is [${version}], Unreleased empty`;
+    if (pending) detail = `[Unreleased] still carries content — promote it into [${version}] before releasing`;
+    else if (!ok) detail = `top CHANGELOG section is [${topVersioned ?? "none"}] but the manifest says ${version} — promote Unreleased before releasing`;
+    checks.push({ name: "changelog-current", ok, detail });
+  } else {
+    checks.push({ name: "changelog-current", ok: false, detail: "no CHANGELOG.md — the release story must exist before the release" });
+  }
+
+  const tagsOut = await runCommand("git", ["-C", projectDir, "tag", "--list", "v[0-9]*"]);
+  const tags = (tagsOut.stdout || "").split("\n").map((t) => t.trim().replace(/^v/, "")).filter((t) => /^\d+\.\d+\.\d+$/.test(t));
+  const ahead = version ? tags.filter((t) => semverCmp(t, version) > 0) : [];
+  let tagDetail = tags.includes(version) ? `v${version} already tagged` : `tag v${version} pending (created after publish)`;
+  if (ahead.length > 0) tagDetail = `tag(s) ahead of the manifest exist: v${ahead.join(", v")}`;
+  checks.push({ name: "tags", ok: ahead.length === 0, detail: tagDetail });
+  return { checks, version, pkg };
+}
+
+async function packPrivacyCheck(projectDir, pkg) {
+  // Every non-private named package is publishable (exports/files-based
+  // packages carry no main/bin) — they all get the scan.
+  if (!pkg || pkg.private === true || !pkg.name || !pkg.version) return null;
+  try {
+    const out = await runCommand("npm", ["pack", "--dry-run", "--json", "--silent"], { cwd: projectDir });
+    const files = (JSON.parse(out.stdout || "[]")[0]?.files || []).map((f) => join(projectDir, f.path));
+    const blocks = scanPaths(files, { list: loadPrivacyList() }).filter((f) => f.severity === "block");
+    return { name: "pack-privacy", ok: blocks.length === 0, detail: blocks.length ? `${blocks.length} personal-data/secret hit(s) in the publishable files` : `${files.length} publishable file(s) clean` };
+  } catch (err) {
+    return { name: "pack-privacy", ok: false, detail: `npm pack --dry-run failed: ${err.message}` };
+  }
+}
+
+async function declaredItems(projectDir, config, version) {
+  const items = config?.release_check?.items;
+  if (!Array.isArray(items)) return [];
+  const checks = [];
+  for (const item of items) {
+    const name = item?.name || "unnamed item";
+    if (item?.file_contains?.path && item.file_contains.pattern != null) {
+      const p = isAbsolute(item.file_contains.path) ? item.file_contains.path : join(projectDir, item.file_contains.path);
+      const needle = String(item.file_contains.pattern).replaceAll("{version}", version ?? "");
+      const ok = existsSync(p) && readFileSync(p, "utf8").includes(needle);
+      checks.push({ name, ok, detail: ok ? `"${needle}" found in ${item.file_contains.path}` : `"${needle}" NOT found in ${item.file_contains.path}` });
+    } else if (item?.command) {
+      try {
+        const res = await runCommand("sh", ["-c", String(item.command).replaceAll("{version}", version ?? "")], { cwd: projectDir });
+        checks.push({ name, ok: res.exitCode === 0, detail: res.exitCode === 0 ? "command exited 0" : `command exited ${res.exitCode}` });
+      } catch (err) {
+        checks.push({ name, ok: false, detail: `command failed to run: ${err.message}` });
+      }
+    } else {
+      checks.push({ name, ok: false, detail: "unknown item shape — use file_contains {path, pattern} or command" });
+    }
+  }
+  return checks;
+}
+
+export async function runReleaseCheck({ projectDir = process.cwd(), config = {} } = {}) {
+  const { checks, version, pkg } = await genericChecks(projectDir);
+  const pack = await packPrivacyCheck(projectDir, pkg);
+  if (pack) checks.push(pack);
+  checks.push(...await declaredItems(projectDir, config, version));
+  return { ok: checks.every((c) => c.ok), version, checks };
+}

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";
+
+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,326 @@
+/**
+ * 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).
+  // A check.applies(config) may return:
+  //   - true / false — boolean form (back-compat).
+  //   - an object { applies: boolean, reason?: string } — when false, `reason`
+  //     is shown verbatim so users see WHY (e.g. "sonarqube.enabled is false
+  //     in kj.config.yml") instead of the opaque "Not applicable" message
+  //     that confused users debugging their config.
+  for (const check of checks) {
+    if (typeof check.applies !== "function") {
+      entries.push({ check, status: null, detail: null, runMs: 0, detectResult: null, remediated: false });
+      continue;
+    }
+    const verdict = check.applies(config);
+    const isObj = verdict && typeof verdict === "object" && "applies" in verdict;
+    const applies = isObj ? Boolean(verdict.applies) : Boolean(verdict);
+    if (applies) {
+      entries.push({ check, status: null, detail: null, runMs: 0, detectResult: null, remediated: false });
+      continue;
+    }
+    const reason = (isObj && typeof verdict.reason === "string" && verdict.reason.trim())
+      ? verdict.reason.trim()
+      : "Not applicable for current configuration";
+    entries.push({
+      check,
+      status: STATUS.SKIPPED,
+      detail: reason,
+      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;
+        // KJC-BUG-0049: si el check es degradable y falló (status FAIL/WARN tras
+        // resolveStatusFromDetect), aplicar disables al overrides y degradar a WARN.
+        // Así el preflight no aborta — la feature opcional se desactiva con aviso.
+        if (!result.ok && entry.check.degradable && (entry.status === STATUS.FAIL || entry.status === STATUS.WARN)) {
+          for (const dotPath of entry.check.degradable.disables || []) {
+            setDotPath(overrides, dotPath, false);
+          }
+          entry.status = STATUS.WARN;
+          entry.detail = `${result.detail} → ${entry.check.degradable.warn}`;
+          entry.degraded = true;
+        }
+      } 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,
+    // Forward optional structured metadata so the doctor printer can
+    // surface per-tool remediation tips (KJC-TSK v2.18). Undefined when
+    // the check didn't set one — kept minimal so JSON output stays tight.
+    extra: e.detectResult?.extra,
+  }));
+
+  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;
+}
+
+/**
+ * Set a dot-path on a target object, creating intermediate objects as needed.
+ * Used by the `degradable` check support (KJC-BUG-0049) to disable feature
+ * flags like `git.auto_pr` when their preflight check fails.
+ *
+ * @example setDotPath({}, "git.auto_pr", false) // → { git: { auto_pr: false } }
+ */
+// KJC-BUG-0076: prototype-pollution guard. dot-paths come from check
+// remediation outputs (internal but LLM-generated), so a malformed
+// `__proto__.x` would mutate Object.prototype. Skip the whole write
+// when any segment matches a forbidden key.
+const UNSAFE_DOT_KEY_RE = /^(?:__proto__|constructor|prototype)$/;
+
+function setDotPath(target, dotPath, value) {
+  const parts = String(dotPath).split(".");
+  if (parts.some((p) => UNSAFE_DOT_KEY_RE.test(p))) return;
+  let cursor = target;
+  for (let i = 0; i < parts.length - 1; i++) {
+    const k = parts[i];
+    if (cursor[k] == null || typeof cursor[k] !== "object") cursor[k] = {};
+    cursor = cursor[k];
+  }
+  cursor[parts.at(-1)] = value;
+}
+
+/**
+ * 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,
+  }));
+}
+
+// Exposed for prototype-pollution regression tests (KJC-BUG-0076).
+export const __pollutionInternals = { setDotPath };

package/src/checks/skills.js

@@ -0,0 +1,53 @@
+/**
+ * OpenSkills CLI availability check. Only runs when skills are enabled.
+ * Strategy: prompt — we can offer to run `npm install -g openskills`,
+ * but global installs are invasive enough that they need user consent.
+ */
+
+import { isOpenSkillsAvailable } from "../skills/openskills-client.js";
+import { runCommand } from "../utils/process.js";
+import { STRATEGY } from "./types.js";
+
+function skillsEnabled(config) {
+  return config?.skills?.enabled !== false;
+}
+
+/**
+ * @internal Exported for dynamic import from tests/checks/skills.test.js
+ * and tests/checks/auto-remediation-e2e.test.js. Knip false positive.
+ */
+export function createOpenSkillsCheck() {
+  return {
+    name: "openskills",
+    label: "OpenSkills CLI",
+    strategy: STRATEGY.PROMPT,
+    applies: skillsEnabled,
+    describe: "Install OpenSkills globally: npm install -g openskills",
+    async detect() {
+      const available = await isOpenSkillsAvailable();
+      if (available) {
+        return { ok: true, severity: "info", detail: "Available via `npx openskills`" };
+      }
+      return {
+        ok: false,
+        severity: "warn", // skills enabled but missing → degrade gracefully
+        detail: "`npx openskills` not available — skill injection will be skipped",
+        fix: "Install OpenSkills: npm install -g openskills",
+      };
+    },
+    async remediate() {
+      const res = await runCommand("npm", ["install", "-g", "openskills"], { timeout: 60000 });
+      if (res.exitCode === 0) {
+        return { fixed: true, detail: "Installed openskills globally via npm" };
+      }
+      return {
+        fixed: false,
+        detail: `npm install -g openskills failed (exit ${res.exitCode}): ${res.stderr.split("\n")[0]}`,
+      };
+    },
+  };
+}
+
+export function getSkillsChecks() {
+  return [createOpenSkillsCheck()];
+}

package/src/checks/sonar.js

@@ -0,0 +1,67 @@
+/**
+ * SonarQube reachability + auth checks.
+ *
+ * Auto-remediation strategy (preserving existing behavior from
+ * preflight-checks.js): if Sonar is not reachable, try `sonarUp()` which
+ * starts the Docker container, then poll for readiness. If auth fails but
+ * admin credentials exist, generate a fresh token and persist it.
+ */
+
+import { isSonarReachable } from "../sonar/manager.js";
+import { STRATEGY } from "./types.js";
+import { withDocLink } from "../utils/doc-links.js";
+
+/**
+ * Whether Sonar is enabled in the active config.
+ */
+function sonarEnabled(config) {
+  return config.sonarqube?.enabled !== false;
+}
+
+function sonarHost(config) {
+  return config.sonarqube?.host || "http://localhost:9000";
+}
+
+/**
+ * Informative check: Sonar enabled/disabled status.
+ * Produces an OK result with disabled description when Sonar is off.
+ */
+function createSonarStatusCheck() {
+  return {
+    name: "sonarqube",
+    label: "SonarQube",
+    strategy: STRATEGY.NONE,
+    async detect({ config }) {
+      const host = sonarHost(config);
+      if (!sonarEnabled(config)) {
+        return { ok: true, severity: "info", detail: "Disabled in config" };
+      }
+      let reachable;
+      try {
+        reachable = await isSonarReachable(host);
+      } catch {
+        reachable = false;
+      }
+      return {
+        ok: reachable,
+        severity: "fail",
+        detail: reachable ? `Reachable at ${host}` : `Not reachable at ${host}`,
+        fix: reachable
+          ? undefined
+          : withDocLink(
+              "Run 'kj sonar start' or 'docker start karajan-sonarqube'. Use --no-sonar to skip.",
+              "sonar_docker"
+            ),
+        extra: { host, reachable },
+      };
+    },
+  };
+}
+
+/**
+ * All Sonar-related checks. Keeps just the status check for commit 1;
+ * auth + auto-remediation are layered in commit 3.
+ */
+export function getSonarChecks() {
+  return [createSonarStatusCheck()];
+}

package/src/checks/squeezr.js

@@ -0,0 +1,36 @@
+/**
+ * Squeezr 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";
+
+function createSqueezrCheck() {
+  return {
+    name: "squeezr",
+    label: "Squeezr",
+    strategy: STRATEGY.MANUAL,
+    async detect() {
+      try {
+        const res = await runCommand("squeezr", ["--version"]);
+        if (res.exitCode === 0) {
+          return { ok: true, severity: "info", detail: `${res.stdout.trim()} — context compression active` };
+        }
+      } catch { /* not installed */ }
+      const installCmd = getInstallCommand("squeezr");
+      return {
+        ok: false,
+        severity: "warn",
+        detail: "Not found — context compression via Squeezr available",
+        fix: withDocLink(`Install: ${installCmd}`, "squeezr_install"),
+      };
+    },
+  };
+}
+
+export function getSqueezrChecks() {
+  return [createSqueezrCheck()];
+}