karajan-code 2.7.4 → 2.9.0

package/src/checks/dir-setup.js

@@ -15,6 +15,10 @@ const REQUIRED_DIRS = [
   "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",

package/src/checks/mcp-health.js

@@ -86,6 +86,9 @@ async function pingMcpStdio(command, args) {
 /**
  * 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 {
@@ -121,6 +124,9 @@ export function createKarajanMcpCheck() {
 /**
  * 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 {

package/src/checks/ports.js

@@ -12,6 +12,8 @@
 
 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;
@@ -23,62 +25,122 @@ function extractPortFromHost(host, fallback) {
 }
 
 /**
- * Whether the occupant looks like the Karajan-managed Sonar container.
- * Docker Desktop's proxy is typically `com.docker.backend` / `com.docker.vmnetd`
- * on macOS and `docker-proxy` on Linux. We treat those as OK.
+ * @internal Exported for dynamic import from tests/checks/ports.test.js
+ * and tests/checks/auto-remediation-e2e.test.js. Knip false positive.
  */
-function isKarajanSonarOccupant(occupant) {
-  if (!occupant?.command) return false;
-  const cmd = occupant.command.toLowerCase();
-  return cmd.includes("docker") || cmd.includes("sonar");
-}
-
 export function createSonarPortCheck() {
   return {
     name: "port:sonar",
     label: "SonarQube port",
-    strategy: STRATEGY.MANUAL,
-    // Since v2.7.4 Sonar is intrinsic to Karajan for code tasks, so the
-    // port check almost always applies. The only legitimate skip is when
-    // the user runs their own external Sonar instance (`external: true`),
-    // in which case the port is managed outside Karajan. The legacy
-    // `sonarqube.enabled` field is ignored (deprecation warning emitted
-    // at config load time — see emitConfigDeprecations in flow-runner.js).
+    // 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 port = extractPortFromHost(config?.sonarqube?.host, DEFAULT_SONAR_PORT);
-      const free = await isPortAvailable(port);
+      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 ${port} is free (Sonar container not yet running)` };
+        return {
+          ok: true,
+          severity: "info",
+          detail: `Port ${configuredPort} is free (Sonar container will be started on demand)`,
+        };
       }
-      // Busy — is it our container?
-      const occupant = await getPortOccupant(port);
-      if (occupant && isKarajanSonarOccupant(occupant)) {
+
+      // 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 ${port} held by Karajan-managed Sonar (${occupant.command} PID ${occupant.pid})`,
+          detail: `Port ${configuredPort} held by a Sonar instance (HTTP /api/system/status responds) — reusing it`,
         };
       }
-      const who = occupant
-        ? `${occupant.command || "unknown"} (PID ${occupant.pid ?? "?"})`
-        : "unknown process";
+
+      // 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 ${port} occupied by ${who}`,
-        fix: `Stop the process holding port ${port} or change sonarqube.host in kj.config.yml.`,
-        extra: { port, occupant },
+        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",

package/src/checks/rtk.js

@@ -8,7 +8,7 @@ import { getInstallCommand } from "../utils/os-detect.js";
 import { withDocLink } from "../utils/doc-links.js";
 import { STRATEGY } from "./types.js";
 
-export function createRtkCheck() {
+function createRtkCheck() {
   return {
     name: "rtk",
     label: "RTK (Rust Token Killer)",

package/src/checks/skills.js

@@ -8,10 +8,14 @@ import { isOpenSkillsAvailable } from "../skills/openskills-client.js";
 import { runCommand } from "../utils/process.js";
 import { STRATEGY } from "./types.js";
 
-export function skillsEnabled(config) {
+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",

package/src/checks/sonar.js

@@ -26,7 +26,7 @@ function sonarHost(config) {
  * Informative check: Sonar enabled/disabled status.
  * Produces an OK result with disabled description when Sonar is off.
  */
-export function createSonarStatusCheck() {
+function createSonarStatusCheck() {
   return {
     name: "sonarqube",
     label: "SonarQube",
@@ -36,7 +36,7 @@ export function createSonarStatusCheck() {
       if (!sonarEnabled(config)) {
         return { ok: true, severity: "info", detail: "Disabled in config" };
       }
-      let reachable = false;
+      let reachable;
       try {
         reachable = await isSonarReachable(host);
       } catch {

package/src/checks/system.js

@@ -14,7 +14,7 @@ function getPackageVersion() {
   return JSON.parse(readFileSync(pkgPath, "utf8")).version;
 }
 
-export function createKarajanVersionCheck() {
+function createKarajanVersionCheck() {
   return {
     name: "karajan",
     label: "Karajan Code",
@@ -26,13 +26,13 @@ export function createKarajanVersionCheck() {
   };
 }
 
-export function createGitRepoCheck() {
+function createGitRepoCheck() {
   return {
     name: "git",
     label: "Git repository",
     strategy: STRATEGY.MANUAL,
     async detect() {
-      let gitOk = false;
+      let gitOk;
       try {
         gitOk = await ensureGitRepo();
       } catch {

package/src/checks/tokens.js

@@ -146,4 +146,4 @@ export function getTokenChecks(config) {
 }
 
 // Re-export for tests that need to introspect the mapping.
-export { PROVIDER_TO_CLI, normalizeProvider };
+export { normalizeProvider };

package/src/checks/types.js

@@ -91,15 +91,3 @@ export const STRATEGY = Object.freeze({
   NONE: "none",
 });
 
-export const SEVERITY = Object.freeze({
-  FAIL: "fail",
-  WARN: "warn",
-  INFO: "info",
-});
-
-/**
- * Whether the final status blocks the pipeline (for preflight).
- */
-export function isBlocking(status) {
-  return status === STATUS.FAIL || status === STATUS.TIMEOUT;
-}

package/src/cli/_shared.js

@@ -0,0 +1,30 @@
+import { applyRunOverrides, loadConfig, validateConfig } from "../config.js";
+import { createLogger } from "../utils/logger.js";
+
+/**
+ * Wraps a CLI action so it loads + validates config, builds the logger,
+ * and fires the anonymous cli_command telemetry event before invoking
+ * the real command body. Shared across every register-*.js module so
+ * each one doesn't need to re-import the config plumbing.
+ *
+ * @param {string} pkgVersion       Current kj version (used for telemetry).
+ * @param {string} commandName      The CLI command name being executed.
+ * @param {object} flags            Flags parsed by Commander.
+ * @param {(ctx: { config: object, logger: object, flags: object }) => Promise<any>} fn
+ *                                  Body of the command — receives the merged config + logger.
+ */
+export async function withConfig(pkgVersion, commandName, flags, fn) {
+  const { config } = await loadConfig();
+  const merged = applyRunOverrides(config, flags || {});
+  validateConfig(merged, commandName);
+  const logger = createLogger(merged.output.log_level);
+
+  // Telemetry: anonymous cli_command event (non-blocking).
+  import("../utils/telemetry.js")
+    .then(({ sendTelemetryEvent }) =>
+      sendTelemetryEvent("cli_command", { command: commandName, version: pkgVersion }, merged)
+    )
+    .catch(() => {});
+
+  return fn({ config: merged, logger, flags });
+}

package/src/cli/register-meta.js

@@ -0,0 +1,218 @@
+import { discoverCommand } from "../commands/discover.js";
+import { triageCommand } from "../commands/triage.js";
+import { researcherCommand } from "../commands/researcher.js";
+import { architectCommand } from "../commands/architect.js";
+import { auditCommand } from "../commands/audit.js";
+import { resumeCommand } from "../commands/resume.js";
+import { boardCommand } from "../commands/board.js";
+import { undoCommand } from "../commands/undo.js";
+import { syncCommand } from "../commands/sync.js";
+import { cleanCommand } from "../commands/clean.js";
+import { withConfig } from "./_shared.js";
+
+/**
+ * Register the "meta" / single-role / housekeeping commands: pre-pipeline
+ * analysis (discover, triage, researcher, architect, audit), session
+ * management (resume, board, undo) and maintenance (update, sync, clean).
+ *
+ * Note: `triage` lives here (not in pipeline) because it's a single-role
+ * analysis command in the same family as discover / researcher /
+ * architect / audit, none of which run the full agent loop.
+ */
+export function registerMeta(program, { pkgVersion }) {
+  program
+    .command("discover")
+    .description("Analyze task for gaps, ambiguities and missing info")
+    .argument("[task]", "Task description (or use --task-file)")
+    .option("--task-file <path>", "Read the task from a file (e.g. .md)")
+    .option("--mode <name>", "Discovery mode: gaps|momtest|wendel|classify|jtbd", "gaps")
+    .option("--discover <name>", "Override discover agent")
+    .option("--discover-model <name>", "Override discover model")
+    .option("--json", "Output raw JSON")
+    .action(async (task, flags) => {
+      await withConfig(pkgVersion, "discover", flags, async ({ config, logger }) => {
+        const { resolveTaskInput } = await import("../utils/task-file.js");
+        const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+        await discoverCommand({ task: resolvedTask, config, logger, mode: flags.mode, json: flags.json });
+      });
+    });
+
+  program
+    .command("triage")
+    .description("Classify task complexity and recommend pipeline roles")
+    .argument("[task]", "Task description (or use --task-file)")
+    .option("--task-file <path>", "Read the task from a file (e.g. .md)")
+    .option("--triage <name>", "Override triage agent")
+    .option("--triage-model <name>", "Override triage model")
+    .option("--json", "Output raw JSON")
+    .action(async (task, flags) => {
+      await withConfig(pkgVersion, "triage", flags, async ({ config, logger }) => {
+        const { resolveTaskInput } = await import("../utils/task-file.js");
+        const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+        await triageCommand({ task: resolvedTask, config, logger, json: flags.json });
+      });
+    });
+
+  program
+    .command("researcher")
+    .description("Research codebase for a task (files, patterns, constraints)")
+    .argument("[task]", "Task description (or use --task-file)")
+    .option("--task-file <path>", "Read the task from a file (e.g. .md)")
+    .option("--researcher <name>", "Override researcher agent")
+    .option("--researcher-model <name>", "Override researcher model")
+    .action(async (task, flags) => {
+      await withConfig(pkgVersion, "researcher", flags, async ({ config, logger }) => {
+        const { resolveTaskInput } = await import("../utils/task-file.js");
+        const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+        await researcherCommand({ task: resolvedTask, config, logger });
+      });
+    });
+
+  program
+    .command("architect")
+    .description("Design solution architecture (layers, patterns, contracts)")
+    .argument("[task]", "Task description (or use --task-file)")
+    .option("--task-file <path>", "Read the task from a file (e.g. .md)")
+    .option("--architect <name>", "Override architect agent")
+    .option("--architect-model <name>", "Override architect model")
+    .option("--context <text>", "Additional context (e.g. researcher output)")
+    .option("--json", "Output raw JSON")
+    .action(async (task, flags) => {
+      await withConfig(pkgVersion, "architect", flags, async ({ config, logger }) => {
+        const { resolveTaskInput } = await import("../utils/task-file.js");
+        const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+        await architectCommand({ task: resolvedTask, config, logger, context: flags.context, json: flags.json });
+      });
+    });
+
+  program
+    .command("audit")
+    .description("Analyze codebase health (read-only)")
+    .argument("[task]", "Task description. If absent, defaults to a full-codebase analysis. Use --task-file to point at a .md.")
+    .option("--task-file <path>", "Read the task from a file (e.g. .md)")
+    .option("--dimensions <list>", "Comma-separated: security,quality,performance,architecture,testing,accessibility (default: all; accessibility auto-skipped on detected backend-only projects)", "all")
+    .option("--json", "Output raw JSON")
+    .option("--agent-readiness", "Score the repo for AI-agent readability (llms.txt, SKILL.md coverage, page token budgets, robots allowlist, heading hierarchy). LLM-free; uses [path] or cwd as the audit target. See issue #542.")
+    .option("--path <dir>", "Path to audit (used with --agent-readiness; defaults to cwd)")
+    .option("--no-sonar", "Skip the SonarQube findings collector (faster, less context). Sonar findings are also skipped automatically when SonarQube is unreachable.")
+    .option("--no-osv", "Skip the OSV-Scanner vulnerability collector. Findings are also skipped automatically when osv-scanner is not installed.")
+    .option("--no-semgrep", "Skip the Semgrep SAST collector. Findings are also skipped automatically when semgrep is not installed (install via 'pipx install semgrep' or 'brew install semgrep').")
+    .option("--report-file <path>", "Write the audit report to disk in addition to stdout. <path> may be a file (extension drives format: .md or .json) or a directory (creates audit-<ISO>.<md|json> inside). $KJ_AUDIT_REPORT_DIR env var is used as default directory if no --report-file is given.")
+    .option("--deterministic-only", "Skip the LLM analysis entirely. Print/persist only the deterministic findings (basalCost, sonar, stack, growth-delta, webperf). Zero tokens spent. Compatible with --report-file and --json.")
+    .option("-y, --yes", "Auto-confirm the 'Continue with LLM analysis?' prompt. Useful in scripts that want the full audit non-interactively. CI/non-TTY paths already auto-confirm without this flag.")
+    .action(async (task, flags) => {
+      await withConfig(pkgVersion, "audit", flags, async ({ config, logger }) => {
+        let resolvedTask = task;
+        if (flags.taskFile) {
+          const { readTaskFile } = await import("../utils/task-file.js");
+          resolvedTask = await readTaskFile(flags.taskFile, { projectDir: config.projectDir });
+        }
+        // commander resolves --no-sonar to flags.sonar=false (negation flag).
+        // We translate to the explicit `noSonar: true` shape AuditRole expects.
+        await auditCommand({
+          task: resolvedTask || "Analyze the full codebase",
+          config, logger,
+          dimensions: flags.dimensions, json: flags.json,
+          agentReadiness: Boolean(flags.agentReadiness),
+          path: flags.path,
+          noSonar: flags.sonar === false,
+          noOsv: flags.osv === false,
+          noSemgrep: flags.semgrep === false,
+          reportFile: flags.reportFile || null,
+          deterministicOnly: Boolean(flags.deterministicOnly),
+          yes: Boolean(flags.yes),
+        });
+      });
+    });
+
+  program
+    .command("resume")
+    .description("Resume a paused session")
+    .argument("<sessionId>")
+    .option("--answer <text>", "Answer to the question that caused the pause")
+    .option("--json", "Output JSON only")
+    .action(async (sessionId, flags) => {
+      await withConfig(pkgVersion, "resume", flags, async ({ config, logger }) => {
+        await resumeCommand({ sessionId, answer: flags.answer, config, logger, flags });
+      });
+    });
+
+  program
+    .command("update")
+    .description("Update karajan-code to the latest version from npm")
+    .action(async () => {
+      // Audit follow-up: was execaCommand (shell parsing). Inputs are
+      // constants today, but the project standard since #555 is execa
+      // with arg arrays (no shell). Migrated for consistency.
+      const { execa } = await import("execa");
+      console.log(`Current version: ${pkgVersion}`);
+      console.log("Checking for updates...");
+      try {
+        const { stdout } = await execa("npm", ["view", "karajan-code", "version"]);
+        const latest = stdout.trim();
+        if (latest === pkgVersion) {
+          console.log(`Already on the latest version (${pkgVersion}).`);
+          return;
+        }
+        console.log(`Updating ${pkgVersion} → ${latest}...`);
+        await execa("npm", ["install", "-g", "karajan-code@latest"], { stdio: "inherit" });
+        console.log(`Updated to ${latest}. Restart Claude to pick up the new MCP server.`);
+      } catch (err) {
+        console.error(`Update failed: ${err.message}`);
+        process.exit(1);
+      }
+    });
+
+  program
+    .command("board [action]")
+    .description("Manage HU Board (start|stop|status|open)")
+    .option("--port <number>", "Port (default: 4000)", "4000")
+    .action(async (action = "start", opts) => {
+      await withConfig(pkgVersion, "board", opts, async ({ config, logger }) => {
+        const port = Number(opts.port) || config.hu_board?.port || 4000;
+        await boardCommand({ action, port, logger });
+      });
+    });
+
+  program
+    .command("undo")
+    .description("Revert last pipeline run")
+    .option("--hard", "Discard all changes (default: soft reset, keeps changes staged)")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "undo", flags, async ({ logger }) => {
+        const result = await undoCommand({ hard: !!flags.hard, logger });
+        if (!result.ok) process.exit(1);
+      });
+    });
+
+  program
+    .command("sync")
+    .description("Detect drift between code and the latest plan. Read-only report (issue #540 MVP).")
+    .option("--plan <planId>", "Sync against a specific plan instead of the latest")
+    .option("--json", "Emit machine-readable JSON instead of human output")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "sync", flags, async ({ config, logger }) => {
+        await syncCommand({ config, logger, planId: flags.plan, json: flags.json });
+      });
+    });
+
+  program
+    .command("clean")
+    .description("Garbage-collect stale plans, sessions and HU batches (dry-run by default)")
+    .option("--yes", "Actually delete — without this flag, only prints what would be removed")
+    .option("--nuke", "Retention=0 everywhere + wipe HU board DB. \"I want it all gone\"")
+    .option("--plan-days <n>", "Keep finalised plans (approved/rejected/executed) for N days (default: 30)")
+    .option("--draft-days <n>", "Keep draft plans for N days (default: 60)")
+    .option("--session-days <n>", "Keep finalised sessions for N days (default: 7)")
+    .option("--hu-days <n>", "Keep HU story batches for N days (default: 14)")
+    .action(async (flags) => {
+      await cleanCommand({
+        yes: Boolean(flags.yes),
+        nuke: Boolean(flags.nuke),
+        planDays: flags.planDays ? Number(flags.planDays) : undefined,
+        draftDays: flags.draftDays ? Number(flags.draftDays) : undefined,
+        sessionDays: flags.sessionDays ? Number(flags.sessionDays) : undefined,
+        huDays: flags.huDays ? Number(flags.huDays) : undefined,
+      });
+    });
+}