karajan-code 2.17.0 → 2.17.1

package/README.md

@@ -23,7 +23,9 @@
 
 ---
 
-> **v2.17.0 released** — Minor. `kj audit` gains two new deterministic structural collectors and the v2.16 Sonar false-positive filter is generalised to apply across every collector. **Knip dead-exports collector** (codeQuality dim): reports unused exports/types (MINOR) and unused files (MAJOR), stack-aware (JS/TS only, needs package.json), subprocess via `--reporter json`, 120s timeout. **Madge circular-import collector** (architecture dim): detects import cycles, severity by chain length (≥4 files = MAJOR), honours tsconfig.json path aliases, 60s timeout. **Generalised FP filter**: every collector (sonar, knip, madge, osv, semgrep) now uses the same `config.audit.false_positives` shape with `tool` field plus inline marker `// karajan-audit-ignore: <tool>:<ruleId>`; legacy `config.sonar.false_positives` and `// karajan-sonar-ignore:` keep working. **Built-in catalogue** ships 4 entries by default (knip:unused-files in tests/fixtures + examples, knip:unused-exports on barrel files, madge cycles in node_modules). **BREAKING(engines)**: Node `>=20.10` → `>=20.19` (knip 6.x requirement; same flavour as the v2.8 18→20.10 bump). 4 872/4 872 tests passing across 402 files. Safe upgrade from 2.16.0 if you're on Node ≥ 20.19.
+> **v2.17.1 released** — Patch. Fixes **KJC-BUG-0055**: a project deleted from the HU Board (🗑️) no longer resurrects on the next `kj plan` or board restart. Four independent leaks closed: (1) **`sync.js` temporal gate** — the unconditional `removeTombstone` from KJC-BUG-0050 becomes a `plan.updatedAt > tombstone.deleted_at` comparison, so a tombstoned project revives only when the plan is genuinely newer than the delete; (2) **`ephemeral-cleaner.js`** now writes a tombstone and `rm -rf`'s `hu-stories/`, `sessions/` and `~/.kj/plans/` dirs when wiping ephemeral projects at boot — previously the orphan directories revived the project on the next scan; (3) **`fullScan` boot GC** sweeps orphan tombstoned dirs (the manual DB-wipe case); (4) **`DELETE /api/projects/:id`** honours `KJ_PLANS_DIR` instead of the hardcoded path. New `getTombstone()` helper in `db.js`. **Also fixes a silent `kj board start` failure (#753)**: the daemon's entry-point guard compared `import.meta.url` to a hand-built `file://` path, which wrongly returned false on Windows, symlinked/global installs and paths with spaces — the board exited 0 with an empty log. `server.js` now trusts a `KJ_BOARD_DAEMON` launcher flag, adds `uncaughtException`/`unhandledRejection` handlers and an actionable `better-sqlite3` load error; `board.js` detects an early daemon exit instead of reporting a phantom PID. 4 909/4 909 tests passing across 408 files. Safe upgrade from 2.17.0.
+>
+> **v2.17.0** — Minor. `kj audit` gains two new deterministic structural collectors and the v2.16 Sonar false-positive filter is generalised to apply across every collector. **Knip dead-exports collector** (codeQuality dim): reports unused exports/types (MINOR) and unused files (MAJOR), stack-aware (JS/TS only, needs package.json), subprocess via `--reporter json`, 120s timeout. **Madge circular-import collector** (architecture dim): detects import cycles, severity by chain length (≥4 files = MAJOR), honours tsconfig.json path aliases, 60s timeout. **Generalised FP filter**: every collector (sonar, knip, madge, osv, semgrep) now uses the same `config.audit.false_positives` shape with `tool` field plus inline marker `// karajan-audit-ignore: <tool>:<ruleId>`; legacy `config.sonar.false_positives` and `// karajan-sonar-ignore:` keep working. **Built-in catalogue** ships 4 entries by default (knip:unused-files in tests/fixtures + examples, knip:unused-exports on barrel files, madge cycles in node_modules). **BREAKING(engines)**: Node `>=20.10` → `>=20.19` (knip 6.x requirement; same flavour as the v2.8 18→20.10 bump). 4 872/4 872 tests passing across 402 files. Safe upgrade from 2.16.0 if you're on Node ≥ 20.19.
 >
 > **v2.16.0** — Minor. Quality-focused release: **deterministic Sonar false-positive filter** (KJC-TSK-0416), wire universal de Brain Recovery completado en `semantic-detector` (TSK-0413 step D), codemod `replace(/regex/g, …)` → `replaceAll(/regex/g, …)` en 41 sitios, y limpieza de hallazgos del propio `kj audit` v2.15.0. The Sonar filter combines two mechanisms: (1) **static rules** `{ rule, filePattern, reason }` from a built-in catalog (covering common false positives like `javascript:S2699` on `tests/architecture/`) plus extensible via `config.sonar.false_positives`; (2) **inline ignores** with `// karajan-sonar-ignore: <ruleId>` on the issue line. Result: the coder stops burning tokens "fixing" non-broken assertions. Brain Recovery now wraps **every** AI call in the pipeline — `semantic-detector` was the last legacy caller. 4 846/4 846 tests passing across 401 files. Safe upgrade from 2.15.0.
 >

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "2.17.0",
+  "version": "2.17.1",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

package/src/checks/binaries.js

@@ -15,6 +15,7 @@
 import { checkBinary, KNOWN_AGENTS } from "../utils/agent-detect.js";
 import { runCommand } from "../utils/process.js";
 import { withDocLink } from "../utils/doc-links.js";
+import { getInstallHint, appliesToStack } from "../utils/install-hints.js";
 import { STRATEGY } from "./types.js";
 
 /**
@@ -105,6 +106,56 @@ function createSerenaCheck() {
   };
 }
 
+/**
+ * Audit-side external tool (semgrep, osv-scanner, lighthouse) check.
+ *
+ * These are not blockers: `kj audit` and `kj webperf` degrade to
+ * available:false when missing. We surface them in `kj doctor` so the
+ * user can see at a glance which audit dimensions are active, and we
+ * point to `kj install-tools` for one-line remediation.
+ *
+ * `lighthouse` is stack-gated: only flagged when the project is
+ * frontend / fullstack. On backend-only projects the check is a no-op
+ * (returns ok:true with detail "n/a") to keep doctor output focused.
+ */
+function createAuditToolCheck(tool, { gatedByStack = false, label }) {
+  return {
+    name: `audit-tool:${tool}`,
+    label,
+    strategy: STRATEGY.MANUAL,
+    async detect({ config } = {}) {
+      if (gatedByStack) {
+        // Stack detection is best-effort — failing here just means we
+        // treat the project as backend-only (skip the check). Keeps the
+        // doctor pipeline resilient to weird repos.
+        let stack = null;
+        try {
+          const { detectProjectStack } = await import("../utils/stack-detect.js");
+          stack = await detectProjectStack(config?.projectDir || process.cwd());
+        } catch { /* ignore */ }
+        if (!appliesToStack(tool, stack)) {
+          return { ok: true, severity: "info", detail: "n/a (no frontend stack detected)" };
+        }
+      }
+      const result = await checkBinary(tool);
+      if (result.ok) {
+        return { ok: true, severity: "info", detail: result.version || "available" };
+      }
+      const hint = await getInstallHint(tool);
+      const fixLine = hint.command
+        ? `Run \`kj install-tools --only ${tool}\` or: ${hint.command}`
+        : `Run \`kj install-tools --only ${tool}\` or see ${hint.manualUrl}`;
+      return {
+        ok: false,
+        severity: "warn",
+        detail: "Not found — `kj audit` dimension will degrade",
+        fix: fixLine,
+        extra: { tool, suggested: hint.command, manager: hint.manager, manualUrl: hint.manualUrl },
+      };
+    },
+  };
+}
+
 /**
  * Aggregate: all binary-related checks for the current config.
  * @returns {import("./types.js").Check[]}
@@ -119,5 +170,10 @@ export function getBinaryChecks() {
   }
   checks.push(createDockerCheck());
   checks.push(createSerenaCheck());
+  // KJC-TSK v2.18 — surface audit-side tools in doctor so the user knows
+  // which dimensions will work. lighthouse is gated to frontend stacks.
+  checks.push(createAuditToolCheck("semgrep", { label: "Semgrep (audit/security)" }));
+  checks.push(createAuditToolCheck("osv-scanner", { label: "OSV-Scanner (audit/security)" }));
+  checks.push(createAuditToolCheck("lighthouse", { label: "Lighthouse (webperf)", gatedByStack: true }));
   return checks;
 }

package/src/checks/runner.js

@@ -196,6 +196,10 @@ export async function runChecks(checks, ctx, options = {}) {
     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);

package/src/cli/register-pipeline.js

@@ -3,6 +3,7 @@ import { configCommand } from "../commands/config.js";
 import { codeCommand } from "../commands/code.js";
 import { reviewCommand } from "../commands/review.js";
 import { scanCommand } from "../commands/scan.js";
+import { installToolsCommand } from "../commands/install-tools.js";
 import { doctorCommand } from "../commands/doctor.js";
 import { reportCommand } from "../commands/report.js";
 import { runCommandHandler } from "../commands/run.js";
@@ -192,6 +193,26 @@ export function registerPipeline(program, { pkgVersion }) {
       if (Number.isInteger(exitCode)) process.exit(exitCode);
     });
 
+  program
+    .command("install-tools")
+    .description("Install external audit tools (semgrep, osv-scanner, lighthouse, docker, sonar) using the package manager available on your system")
+    .option("--only <tools>", "Comma-separated subset (e.g. \"semgrep,osv-scanner\"). Bypasses stack-gating.")
+    .option("-y, --yes", "Auto-accept all prompts (non-interactive)")
+    .option("--dry-run", "Show what would be installed without running anything")
+    .action(async (flags) => {
+      try {
+        const { exitCode } = await installToolsCommand({
+          only: flags.only,
+          yes: !!flags.yes,
+          dryRun: !!flags.dryRun,
+        });
+        if (Number.isInteger(exitCode)) process.exit(exitCode);
+      } catch (err) {
+        console.error(`kj install-tools: ${err?.message || err}`);
+        process.exit(1);
+      }
+    });
+
   program
     .command("status")
     .description("Show pipeline dashboard with HU progress")

package/src/commands/board.js

@@ -88,6 +88,40 @@ function buildBoardUrl(port, projectSlug) {
   return projectSlug ? `${base}/p/${projectSlug}` : base;
 }
 
+/**
+ * After spawning the board daemon, watch for an early exit. Resolves to
+ * an error string when the child dies within the window — a broken
+ * native module, a crash on boot, or the silent entry-point mismatch
+ * that made the daemon exit 0 without a trace — and to `null` when it
+ * survives. This is what stops `startBoard` from reporting `ok` for a
+ * daemon that died milliseconds after spawn. The window is overridable
+ * via KJ_BOARD_START_WINDOW_MS (tests set it low to stay fast).
+ * @param {import('node:child_process').ChildProcess} child
+ * @param {string} logPath
+ * @returns {Promise<string|null>}
+ */
+export function waitForEarlyExit(child, logPath) {
+  const envWindow = Number(process.env.KJ_BOARD_START_WINDOW_MS);
+  const windowMs = Number.isFinite(envWindow) && envWindow >= 0 ? envWindow : 1500;
+  return new Promise((resolve) => {
+    let settled = false;
+    let timer = null;
+    const onExit = (code, signal) => {
+      const how = signal ? `signal ${signal}` : `exit code ${code}`;
+      finish(`HU Board daemon died on startup (${how}). See ${logPath} for the cause.`);
+    };
+    function finish(value) {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      child.removeListener("exit", onExit);
+      resolve(value);
+    }
+    child.once("exit", onExit);
+    timer = setTimeout(() => finish(null), windowMs);
+  });
+}
+
 export async function startBoard(desiredPort = 4000, opts = {}) {
   const { projectSlug = null, bind = "127.0.0.1" } = opts;
   const existingPid = readPid();
@@ -141,8 +175,11 @@ export async function startBoard(desiredPort = 4000, opts = {}) {
 
   // Use process.execPath (absolute path to current node binary) instead of "node".
   // Fixes ENOENT on nvm setups where `node` is not in the spawned process's PATH.
+  // KJ_BOARD_DAEMON=1 tells server.js to run main() regardless of how
+  // its entry-point path compares — the symlink/Windows/space-in-path
+  // mismatch that used to make the daemon exit 0 in total silence.
   const child = spawn(process.execPath, [serverPath], {
-    env: { ...process.env, PORT: String(port), BIND_HOST: bind },
+    env: { ...process.env, PORT: String(port), BIND_HOST: bind, KJ_BOARD_DAEMON: "1" },
     detached: true,
     stdio: ["ignore", logFd, logFd],
     cwd: BOARD_DIR
@@ -154,6 +191,14 @@ export async function startBoard(desiredPort = 4000, opts = {}) {
   if (!child.pid) {
     throw new Error("Failed to spawn HU Board server");
   }
+  // Don't report success blindly: a crash on boot (e.g. broken
+  // better-sqlite3, or the silent entry-point mismatch) used to be
+  // reported as ok:true, leaving the user with a dead board and a log
+  // showing only the start line. Catch the early exit here.
+  const failure = await waitForEarlyExit(child, logPath);
+  if (failure) {
+    throw new Error(failure);
+  }
   fs.writeFileSync(PID_FILE, String(child.pid));
   // Detach for real: `detached: true` only sets up the new session;
   // without `unref()` the parent's event loop still holds a reference
@@ -289,7 +334,18 @@ export function renderBoardBanner({ url, status, projectName }) {
 export async function boardCommand({ action = "start", port = 4000, bind = "127.0.0.1", logger }) {
   switch (action) {
     case "start": {
-      const result = await startBoard(port, { bind });
+      let result;
+      try {
+        result = await startBoard(port, { bind });
+      } catch (err) {
+        // The daemon died on boot (broken native module, crash) or no
+        // free port was found. Surface it cleanly — the whole point of
+        // this fix is that `kj board start` never reports a phantom
+        // success while leaving a dead board behind.
+        logger.error(`HU Board failed to start: ${err.message}`);
+        process.exitCode = 1;
+        return { ok: false, error: err.message };
+      }
       if (result.alreadyRunning) {
         logger.info(`HU Board already running (PID ${result.pid}) at ${result.url}`);
       } else {

package/src/commands/doctor.js

@@ -171,4 +171,21 @@ function printHuman(report, { verbose }) {
   if (Object.keys(report.overrides).length > 0) {
     console.log(`Runtime overrides applied: ${JSON.stringify(report.overrides)}`);
   }
+
+  // KJC-TSK v2.18 — if any external audit tool (semgrep, osv-scanner,
+  // lighthouse) reported missing, surface the one-line remediation so
+  // the user doesn't have to dig the fix lines out of the wall of
+  // checks. The audit-tool checks emit names like "audit-tool:semgrep"
+  // and embed { tool, suggested } in `extra` (see binaries.js).
+  const installable = report.checks
+    .filter((c) => c.name?.startsWith("audit-tool:") && c.status === STATUS.WARN && c.extra?.tool)
+    .map((c) => c.extra.tool);
+  if (installable.length > 0) {
+    console.log();
+    const list = installable.join(", ");
+    const only = installable.length === 1 ? ` --only ${installable[0]}` : "";
+    console.log(`Tip: run \`kj install-tools${only}\` to install: ${list}.`);
+  }
 }
+
+export const __test = { printHuman };

package/src/commands/install-tools.js

@@ -0,0 +1,211 @@
+// `kj install-tools` — install the external audit tools that `kj audit`
+// and `kj webperf` rely on but does not bundle.
+//
+// Covers semgrep, osv-scanner, lighthouse, docker, sonar. Picks the
+// install command per tool from `getInstallHint` (HU1) so the command
+// matches the package manager available on the user's system.
+//
+// Lighthouse is stack-gated: by default we only prompt about it when
+// the project is frontend/fullstack. Pass `--only lighthouse` to bypass
+// the gate.
+//
+// Docker and sonar are special cases — see TOOL_HANDLERS below.
+
+import readline from "node:readline";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import path from "node:path";
+import fs from "node:fs/promises";
+import { checkBinary } from "../utils/agent-detect.js";
+import { getInstallHint, detectPackageManagers, appliesToStack } from "../utils/install-hints.js";
+import { detectProjectStack } from "../utils/stack-detect.js";
+
+const execFileAsync = promisify(execFile);
+
+const ALL_TOOLS = ["semgrep", "osv-scanner", "lighthouse", "docker", "sonar"];
+
+function parseOnlyList(raw) {
+  if (!raw) return null;
+  const wanted = String(raw).split(",").map((t) => t.trim()).filter(Boolean);
+  const invalid = wanted.filter((t) => !ALL_TOOLS.includes(t));
+  if (invalid.length > 0) {
+    throw new Error(`Unknown tool(s) in --only: ${invalid.join(", ")}. Valid: ${ALL_TOOLS.join(", ")}`);
+  }
+  return wanted;
+}
+
+function promptYesNo(question, defaultYes = true) {
+  return new Promise((resolve) => {
+    if (!process.stdin.isTTY) { resolve(defaultYes); return; } // non-TTY → assume default
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const hint = defaultYes ? "Y/n" : "y/N";
+    rl.question(`${question} [${hint}] `, (answer) => {
+      rl.close();
+      const a = (answer || "").trim().toLowerCase();
+      if (!a) return resolve(defaultYes);
+      resolve(a === "y" || a === "yes");
+    });
+  });
+}
+
+async function isInstalled(tool) {
+  // sonar is a Docker container, not a binary. We check it separately
+  // by looking at running containers via `docker ps`.
+  if (tool === "sonar") return checkSonarRunning();
+  if (tool === "lighthouse") return (await checkBinary("lighthouse")).ok;
+  if (tool === "docker") return (await checkBinary("docker")).ok;
+  return (await checkBinary(tool)).ok;
+}
+
+async function checkSonarRunning() {
+  try {
+    const { stdout } = await execFileAsync("docker", ["ps", "--format", "{{.Names}}", "--filter", "name=sonarqube"], { timeout: 5000 });
+    return stdout.trim().length > 0;
+  } catch { return false; }
+}
+
+async function runInstall(command) {
+  // Split on whitespace (commands here are simple, no nested quoting).
+  const [bin, ...args] = command.split(/\s+/);
+  try {
+    const { stdout, stderr } = await execFileAsync(bin, args, { timeout: 300_000, maxBuffer: 32 * 1024 * 1024 });
+    return { ok: true, stdout, stderr };
+  } catch (err) {
+    return { ok: false, error: err?.shortMessage || err?.message || String(err), stderr: err?.stderr };
+  }
+}
+
+/**
+ * Sonar handler: special case. Cannot install Sonar via package manager;
+ * the install is `docker compose -f <our-template> up -d` if Docker is
+ * available. Falls back to a manual URL otherwise.
+ */
+async function handleSonar({ available, dryRun }) {
+  if (!available.docker) {
+    return {
+      tool: "sonar",
+      action: "manual",
+      reason: "docker not available — sonar needs docker. Install docker first.",
+      manualUrl: "https://docs.docker.com/get-docker/",
+    };
+  }
+  const composePath = path.join(process.cwd(), "docker-compose.yml");
+  let composeExists = false;
+  try { await fs.access(composePath); composeExists = true; } catch { /* missing */ }
+  const command = composeExists
+    ? "docker compose up -d"
+    : "docker run -d --name sonarqube -p 9000:9000 sonarqube:lts-community";
+  return {
+    tool: "sonar",
+    action: dryRun ? "dry-run" : "ready",
+    command,
+    manualUrl: "https://docs.sonarsource.com/sonarqube-community-build/try-out-sonarqube/",
+  };
+}
+
+/**
+ * Docker handler: never auto-install (platform-specific, invasive).
+ * Always point at the official docs.
+ */
+function handleDocker(available) {
+  return {
+    tool: "docker",
+    action: "manual",
+    reason: "Docker install is platform-specific — see official docs.",
+    manualUrl: "https://docs.docker.com/get-docker/",
+    suggested: available.brew ? "brew install --cask docker" : null,
+  };
+}
+
+/**
+ * Plan + (optionally execute) the install of every requested tool.
+ *
+ * @param {Object} opts
+ * @param {string|null} [opts.only] - comma-separated subset
+ * @param {boolean} [opts.yes] - skip prompts
+ * @param {boolean} [opts.dryRun] - plan-only, no execution
+ * @param {Object} [opts.logger]
+ * @returns {Promise<{ results: Array<Object>, exitCode: number }>}
+ */
+export async function installToolsCommand(opts = {}) {
+  const only = parseOnlyList(opts.only);
+  const yes = !!opts.yes;
+  const dryRun = !!opts.dryRun;
+  const logger = opts.logger || console;
+
+  const targetTools = only || ALL_TOOLS;
+  const available = await detectPackageManagers();
+  const stack = await detectProjectStack(process.cwd()).catch(() => null);
+
+  const results = [];
+  for (const tool of targetTools) {
+    // Stack gating — lighthouse on backend-only projects is skipped
+    // UNLESS the user passed --only lighthouse explicitly.
+    if (tool === "lighthouse" && !only && !appliesToStack(tool, stack)) {
+      results.push({ tool, action: "skipped", reason: "no frontend stack detected" });
+      logger.info?.(`⊘ ${tool}: skipped (no frontend stack detected; use --only lighthouse to force)`);
+      continue;
+    }
+
+    if (await isInstalled(tool)) {
+      results.push({ tool, action: "already-installed" });
+      logger.info?.(`✓ ${tool}: already installed`);
+      continue;
+    }
+
+    if (tool === "sonar") {
+      const result = await handleSonar({ available, dryRun });
+      results.push(result);
+      logger.info?.(`▸ sonar: ${result.command || result.manualUrl}`);
+      if (!dryRun && result.action === "ready") {
+        const proceed = yes || await promptYesNo(`Start SonarQube with: ${result.command}?`);
+        if (proceed) {
+          const r = await runInstall(result.command);
+          result.action = r.ok ? "installed" : "failed";
+          if (!r.ok) result.error = r.error;
+        }
+      }
+      continue;
+    }
+
+    if (tool === "docker") {
+      const result = handleDocker(available);
+      results.push(result);
+      logger.info?.(`▸ docker: ${result.suggested || result.manualUrl}`);
+      continue;
+    }
+
+    // semgrep / osv-scanner / lighthouse — package-manager driven.
+    const hint = await getInstallHint(tool, available);
+    if (!hint.command || !hint.manager) {
+      results.push({ tool, action: "manual", reason: "no compatible package manager found", manualUrl: hint.manualUrl, suggested: hint.command });
+      logger.warn?.(`✗ ${tool}: no compatible package manager. Manual: ${hint.manualUrl}`);
+      continue;
+    }
+    if (dryRun) {
+      results.push({ tool, action: "dry-run", command: hint.command, manager: hint.manager });
+      logger.info?.(`▸ ${tool}: would run \`${hint.command}\` (manager: ${hint.manager})`);
+      continue;
+    }
+    const proceed = yes || await promptYesNo(`Install ${tool} with: ${hint.command}?`);
+    if (!proceed) {
+      results.push({ tool, action: "declined", command: hint.command });
+      logger.info?.(`⊘ ${tool}: declined`);
+      continue;
+    }
+    logger.info?.(`▸ ${tool}: running \`${hint.command}\`...`);
+    const r = await runInstall(hint.command);
+    if (r.ok) {
+      results.push({ tool, action: "installed", command: hint.command, manager: hint.manager });
+      logger.info?.(`✓ ${tool}: installed via ${hint.manager}`);
+    } else {
+      results.push({ tool, action: "failed", command: hint.command, error: r.error });
+      logger.warn?.(`✗ ${tool}: install failed (${r.error})`);
+    }
+  }
+
+  const failures = results.filter((r) => r.action === "failed").length;
+  return { results, exitCode: failures > 0 ? 1 : 0 };
+}
+
+export const __test = { parseOnlyList, isInstalled, ALL_TOOLS };

package/src/utils/install-hints.js

@@ -0,0 +1,136 @@
+// Platform-aware install hints for external tools that `kj audit` /
+// `kj webperf` use (semgrep, osv-scanner, lighthouse).
+//
+// `kj doctor` calls these to render hint strings ("Install with:
+// pipx install semgrep") that match what's actually available on the
+// user's machine, rather than a generic "see docs" message. The same
+// metadata drives `kj install-tools` (HU2) — it decides which package
+// manager to invoke per tool.
+//
+// We probe each package manager once with `which`/`where`-style checks
+// and cache the result for the lifetime of the process.
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * @typedef {"pipx"|"brew"|"go"|"npm"|"pip"|"apt"|"dnf"|"choco"|"scoop"|"docker"} PackageManager
+ */
+
+/** @type {Record<PackageManager, boolean>|null} */
+let cachedAvailability = null;
+
+const PROBES = [
+  ["pipx", ["--version"]],
+  ["brew", ["--version"]],
+  ["go", ["version"]],
+  ["npm", ["--version"]],
+  ["pip", ["--version"]],
+  ["apt", ["--version"]],
+  ["dnf", ["--version"]],
+  ["choco", ["--version"]],
+  ["scoop", ["--version"]],
+  ["docker", ["--version"]],
+];
+
+async function probeOne(bin, args) {
+  try {
+    await execFileAsync(bin, args, { timeout: 3000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Detect which package managers are reachable on PATH. Cached on first
+ * call. Exported for tests; production callers go through getInstallHint.
+ */
+export async function detectPackageManagers() {
+  if (cachedAvailability) return cachedAvailability;
+  const entries = await Promise.all(
+    PROBES.map(async ([bin, args]) => [bin, await probeOne(bin, args)]),
+  );
+  cachedAvailability = Object.fromEntries(entries);
+  return cachedAvailability;
+}
+
+/** Test helper — reset the cache between unit cases. */
+export function resetPackageManagerCache() {
+  cachedAvailability = null;
+}
+
+/**
+ * Returns the install command for a tool, preferring the highest-priority
+ * package manager available on the current system.
+ *
+ * The order encodes our recommendation when multiple managers can install
+ * the same tool. We prefer isolated installs (pipx, brew) over global
+ * `pip install` so we don't pollute the user's site-packages.
+ *
+ * @param {"semgrep"|"osv-scanner"|"lighthouse"|"docker"} tool
+ * @param {Record<PackageManager, boolean>} [available] — pre-computed availability; if omitted, detects.
+ * @returns {Promise<{ command: string|null, manager: PackageManager|null, manualUrl: string }>}
+ */
+export async function getInstallHint(tool, available = null) {
+  const avail = available || (await detectPackageManagers());
+  const candidates = INSTALL_CANDIDATES[tool] || [];
+  for (const { manager, command } of candidates) {
+    if (avail[manager]) return { command, manager, manualUrl: MANUAL_URLS[tool] };
+  }
+  // Nothing matched — fall back to the first candidate's command as a
+  // suggestion, so the user at least sees a working recipe.
+  const first = candidates[0];
+  return {
+    command: first ? first.command : null,
+    manager: null,
+    manualUrl: MANUAL_URLS[tool],
+  };
+}
+
+const INSTALL_CANDIDATES = {
+  semgrep: [
+    { manager: "pipx", command: "pipx install semgrep" },
+    { manager: "brew", command: "brew install semgrep" },
+    { manager: "pip", command: "pip install semgrep" },
+  ],
+  "osv-scanner": [
+    { manager: "go", command: "go install github.com/google/osv-scanner@latest" },
+    { manager: "brew", command: "brew install osv-scanner" },
+  ],
+  lighthouse: [
+    { manager: "npm", command: "npm install -g lighthouse" },
+  ],
+  docker: [
+    // Docker Desktop / Engine cannot be installed by a package manager
+    // reliably across platforms — always point users to the official docs.
+    // Listing brew anyway as a hint for macOS users.
+    { manager: "brew", command: "brew install --cask docker" },
+  ],
+};
+
+const MANUAL_URLS = {
+  semgrep: "https://semgrep.dev/docs/getting-started",
+  "osv-scanner": "https://google.github.io/osv-scanner/installation/",
+  lighthouse: "https://github.com/GoogleChrome/lighthouse#using-the-cli",
+  docker: "https://docs.docker.com/get-docker/",
+};
+
+/**
+ * Tools whose hint depends on the project stack. lighthouse is only
+ * relevant for frontend projects; suppressing the hint elsewhere keeps
+ * `kj doctor` output free of irrelevant noise.
+ *
+ * @param {string} tool
+ * @param {Object} stack — shape returned by detectProjectStack()
+ */
+export function appliesToStack(tool, stack) {
+  if (tool === "lighthouse") {
+    if (!stack) return false;
+    return Boolean(stack.isFrontend || stack.isFullstack);
+  }
+  // semgrep, osv-scanner, docker, sonar — always relevant.
+  return true;
+}