karajan-code 2.7.3 → 2.8.0

package/src/skills/semantic-detector.js

@@ -129,18 +129,23 @@ export async function refineSkillsSemantically({ task, alreadyDetected = [], con
 
 /**
  * Resolve the effective skills mode from config + flags.
- * Precedence: flags.skillsMode > config.skills.mode > globalThis default > "auto".
+ * Precedence: flags.skillsMode > config.skills.mode > config.testHarness.defaultSkillsMode > "auto".
  *
- * The global default lets the test harness opt out of semantic detection
- * without each orchestrator test having to mock this module (tests/setup.js
- * sets globalThis.__KJ_DEFAULT_SKILLS_MODE = "regex").
+ * The testHarness default lets the test harness opt out of semantic
+ * detection without each orchestrator test having to mock this module.
+ * Production code reads `config.testHarness.defaultSkillsMode` only;
+ * the legacy global override is documented and exclusively read in
+ * src/config/test-harness.js (ESLint rule #557 blocks any reintroduction
+ * of `globalThis.__KJ_*` outside that one file). Legacy callers without
+ * a fully-loaded config still work because `config.testHarness` is
+ * undefined → falls through to `"auto"`.
  *
  * @param {Object} config
  * @param {Object} [flags]
  * @returns {"auto"|"regex"|"semantic"|"none"}
  */
 export function resolveSkillsMode(config, flags = {}) {
-  const defaultMode = globalThis.__KJ_DEFAULT_SKILLS_MODE || "auto";
+  const defaultMode = config?.testHarness?.defaultSkillsMode || "auto";
   const candidate = flags.skillsMode ?? config?.skills?.mode ?? defaultMode;
   const valid = new Set(["auto", "regex", "semantic", "none"]);
   return valid.has(candidate) ? candidate : "auto";

package/src/skills/skill-detector.js

@@ -226,7 +226,7 @@ async function collectPythonDeps(projectDir, needed) {
     for (const line of raw.split("\n")) {
       const trimmed = line.trim().split("#")[0].trim();
       if (!trimmed) continue;
-      const name = trimmed.split(/[<>=!~\[\s]/)[0].toLowerCase();
+      const name = trimmed.split(/[<>=!~[\s]/)[0].toLowerCase();
       const skill = PYTHON_DEPS[name];
       if (skill) needed.add(skill);
     }

package/src/sonar/cloud-scanner.js

@@ -5,7 +5,6 @@ function buildCloudScannerArgs(projectKey, config) {
   const sc = config.sonarcloud || {};
   const scanner = sc.scanner || {};
   const host = sc.host || "https://sonarcloud.io";
-  const token = process.env.KJ_SONARCLOUD_TOKEN || sc.token;
   const organization = process.env.KJ_SONARCLOUD_ORG || sc.organization;
 
   const args = [

package/src/sonar/credentials.js

@@ -1,13 +1,20 @@
 /**
- * Load SonarQube admin credentials from ~/.karajan/sonar-credentials.json.
+ * Load SonarQube credentials from ~/.karajan/sonar-credentials.json.
  *
- * File format:
+ * File format (any subset):
  * {
  *   "user": "admin",
- *   "password": "your-password"
+ *   "password": "your-password",
+ *   "token": "squ_..."
  * }
  *
- * Returns { user, password } or { user: null, password: null } if file missing.
+ * Returns { user, password, token } with each field null when missing.
+ *
+ * The `token` field is consumed by resolveSonarTokenAsync as the
+ * lowest-priority fallback. Until v2.7.5 it was not extracted here, which
+ * meant a token persisted to the credentials file by `kj init` was never
+ * actually used at scan time — Karajan would silently fall back to the
+ * stale token in kj.config.yml or fail with a 401.
  */
 
 import fs from "node:fs/promises";
@@ -23,10 +30,11 @@ export async function loadSonarCredentials() {
     const data = JSON.parse(raw);
     return {
       user: data.user || null,
-      password: data.password || null
+      password: data.password || null,
+      token: data.token || null
     };
   } catch { /* credentials file may not exist */
-    return { user: null, password: null };
+    return { user: null, password: null, token: null };
   }
 }
 

package/src/sonar/discovery.js

@@ -0,0 +1,123 @@
+/**
+ * Discover running SonarQube containers regardless of the user's
+ * config. The point: never bother the user about port 9000 being
+ * "occupied by an unknown process" — if there's a Sonar already up
+ * somewhere, just point at it and move on.
+ *
+ * The previous preflight check insisted on owning port 9000 by name
+ * (`karajan-sonarqube`). If you happened to have a `sonarqube` from
+ * another project running on 9000 (or had pulled a different image
+ * tag), we'd error out asking the user to "stop the conflicting
+ * process". That's busywork — Sonar is Sonar; reuse what's there.
+ *
+ * The discovery strategy:
+ *   1. List Docker containers whose image looks like sonarqube
+ *      (image-name regex / ancestor filter — covers `sonarqube`,
+ *      `sonarqube:community`, `sonarqube:lts`, `sonarqube:9.9`, …).
+ *   2. Parse the published host port (`0.0.0.0:9001->9000/tcp`).
+ *   3. Optionally HTTP-probe to confirm it's actually serving
+ *      `/api/system/status` so a misnamed image can't hijack us.
+ */
+
+import { runCommand } from "../utils/process.js";
+import { isSonarReachable } from "./manager.js";
+
+/**
+ * @typedef {Object} DiscoveredSonar
+ * @property {boolean} found
+ * @property {string} [containerName]
+ * @property {string} [image]
+ * @property {number} [port]    - host port (what we connect to)
+ * @property {string} [host]    - http://localhost:<port>
+ * @property {boolean} [reachable] - true after a successful HTTP probe
+ */
+
+/**
+ * Parse the Ports column from `docker ps`. Looks for any host binding
+ * that maps to the container's `internalPort` (default 9000).
+ * Examples:
+ *   "0.0.0.0:9000->9000/tcp"        → 9000
+ *   "127.0.0.1:9001->9000/tcp"      → 9001
+ *   "9000/tcp"                      → null (no host binding)
+ *   "0.0.0.0:9000->9000/tcp, 9092/tcp" → 9000
+ *
+ * @param {string} portsStr
+ * @param {number} [internalPort=9000]
+ * @returns {number|null}
+ */
+export function extractHostPort(portsStr, internalPort = 9000) {
+  if (!portsStr) return null;
+  const re = new RegExp(
+    `(?:0\\.0\\.0\\.0|127\\.0\\.0\\.1|::|\\[::\\]):(\\d+)\\s*->\\s*${internalPort}\\/tcp`,
+    "g"
+  );
+  const matches = [...portsStr.matchAll(re)];
+  if (matches.length === 0) return null;
+  // Prefer the smallest port number (likeliest the "main" binding);
+  // arbitrary but deterministic.
+  return Math.min(...matches.map((m) => Number(m[1])));
+}
+
+/**
+ * Run `docker ps` with a list-of-images filter and parse the result.
+ * Returns the FIRST container with a usable host port, or null.
+ *
+ * @returns {Promise<DiscoveredSonar|null>}
+ */
+async function dockerPsForSonar() {
+  // List all running containers with their image so we can image-match
+  // ourselves. Cheap (single docker call) and tolerant of image tags.
+  const res = await runCommand("docker", [
+    "ps",
+    "--format", "{{.ID}}|{{.Names}}|{{.Image}}|{{.Ports}}",
+  ]);
+  if (res.exitCode !== 0 || !res.stdout?.trim()) return null;
+
+  const lines = res.stdout.trim().split("\n");
+  for (const line of lines) {
+    const [, name, image, ports] = line.split("|");
+    if (!image) continue;
+    if (!/sonarqube/i.test(image)) continue;
+    const port = extractHostPort(ports, 9000);
+    if (!port) continue;
+    return {
+      found: true,
+      containerName: name,
+      image,
+      port,
+      host: `http://localhost:${port}`,
+    };
+  }
+  return null;
+}
+
+/**
+ * Public entry point: find a usable, reachable Sonar.
+ *
+ * `probe`: when true (default) HTTP-pings `/api/system/status` to
+ * confirm the container is actually serving Sonar. Tests can disable
+ * the probe for hermetic mocking.
+ *
+ * @param {object} [opts]
+ * @param {boolean} [opts.probe=true]
+ * @param {number} [opts.healthcheckSeconds=5]
+ * @returns {Promise<DiscoveredSonar>}
+ */
+export async function discoverRunningSonar(opts = {}) {
+  const { probe = true, healthcheckSeconds = 5 } = opts;
+  let candidate;
+  try {
+    candidate = await dockerPsForSonar();
+  } catch {
+    candidate = null;
+  }
+  if (!candidate) return { found: false };
+  if (!probe) return { ...candidate, reachable: true };
+  let reachable;
+  try {
+    reachable = await isSonarReachable(candidate.host, healthcheckSeconds);
+  } catch {
+    reachable = false;
+  }
+  return { ...candidate, reachable };
+}

package/src/sonar/manager.js

@@ -87,6 +87,24 @@ export async function sonarUp(hostOverride = null) {
     };
   }
 
+  // Discover-before-spawn (v2.7.5): if there's already a SonarQube
+  // container running anywhere — even under a different name on a
+  // different port — reuse it instead of spinning up a second one.
+  // Avoids the user accidentally accumulating Sonar containers across
+  // projects, and matches what the port preflight check already does.
+  const { discoverRunningSonar } = await import("./discovery.js");
+  const discovered = await discoverRunningSonar({
+    healthcheckSeconds: sonarConfig.timeouts.healthcheckSeconds,
+  });
+  if (discovered.found && discovered.reachable) {
+    return {
+      exitCode: 0,
+      stdout: `Reusing existing SonarQube container "${discovered.containerName}" at ${discovered.host} (skipping container start).`,
+      stderr: "",
+      reusedHost: discovered.host,
+    };
+  }
+
   const compose = await ensureComposeFile(config.sonarqube);
   return runCommand("docker", ["compose", "-f", compose, "up", "-d"], { timeout: sonarConfig.timeouts.composeUpMs });
 }

package/src/sync/detect-drift.js

@@ -0,0 +1,113 @@
+/**
+ * kj sync — drift detection between code and the Canvas / plan
+ * (issue #540, MVP).
+ *
+ * Scope of THIS module: pure data transformation. Given a plan
+ * (with Operations and their file_hints) plus a list of currently
+ * tracked source files (mtime + path), classify each file:
+ *
+ *   - covered      — file IS referenced by some Operation's file_hint
+ *                    AND was modified since the plan was created.
+ *                    (Expected drift; plan still authoritative.)
+ *   - untracked    — file exists, modified, but no Operation references
+ *                    it. The user added it manually after the run; the
+ *                    Canvas needs a new Operation to reflect it.
+ *   - missing      — Operation references a file that no longer exists
+ *                    on disk. Either the file was deleted or the plan
+ *                    is wrong about its location.
+ *   - clean        — file is referenced by an Operation AND has not
+ *                    been modified since the plan. No action needed.
+ *
+ * The classifier is pure: caller does the I/O (walking the tree,
+ * stating files, parsing plan JSON). Easy to unit-test.
+ */
+
+/**
+ * @param {object} plan — plan JSON with `operations` (or `hus`) carrying
+ *                        optional `file_hint` strings, and `createdAt` ISO
+ * @param {Array<{path: string, mtime: Date}>} files — files in the project
+ * @returns {{ covered: object[], untracked: object[], missing: object[], clean: object[] }}
+ */
+export function classifyDrift(plan, files) {
+  const planMtime = new Date(plan?.createdAt || plan?.updatedAt || 0);
+
+  // Collect every file_hint declared by any operation/HU. Both keys
+  // are accepted for back-compat with v2 plans (HUs) and Canvas
+  // (Operations).
+  const ops = Array.isArray(plan?.operations) ? plan.operations
+    : Array.isArray(plan?.hus) ? plan.hus
+    : [];
+  const hinted = new Map(); // file → operation index
+  ops.forEach((op, idx) => {
+    const hint = op.file_hint || op.fileHint;
+    if (typeof hint === "string" && hint.length > 0) {
+      hinted.set(hint, idx);
+    }
+  });
+
+  const out = { covered: [], untracked: [], missing: [], clean: [] };
+  const seenInFs = new Set();
+
+  for (const f of files) {
+    if (!f?.path) continue;
+    seenInFs.add(f.path);
+    const opIdx = hinted.get(f.path);
+    const modified = f.mtime instanceof Date && f.mtime > planMtime;
+
+    if (opIdx === undefined) {
+      // Not referenced by any operation. Two sub-cases:
+      //  - modified: real drift, propose new operation.
+      //  - not modified: probably a pre-existing file from before the
+      //    plan; ignore (no action).
+      if (modified) {
+        out.untracked.push({ path: f.path, mtime: f.mtime, suggestion: "new operation" });
+      }
+      continue;
+    }
+    if (modified) {
+      out.covered.push({ path: f.path, mtime: f.mtime, operationIndex: opIdx });
+    } else {
+      out.clean.push({ path: f.path, operationIndex: opIdx });
+    }
+  }
+
+  // Missing: operation says a file should exist, but we never saw it.
+  for (const [hint, opIdx] of hinted.entries()) {
+    if (!seenInFs.has(hint)) {
+      out.missing.push({ path: hint, operationIndex: opIdx, suggestion: "remove operation OR fix the file_hint" });
+    }
+  }
+
+  return out;
+}
+
+/**
+ * Render a drift report as plain-text for the terminal.
+ */
+export function formatDriftReport(report, plan) {
+  const lines = [`Drift report — plan ${plan?.planId || "(unknown)"}`, ""];
+  if (report.untracked.length === 0 && report.missing.length === 0 && report.covered.length === 0) {
+    lines.push("  No drift detected.");
+    return lines.join("\n");
+  }
+  if (report.covered.length > 0) {
+    lines.push(`Covered (${report.covered.length}) — modified, an Operation references it; consider extending its Approach:`);
+    for (const c of report.covered) lines.push(`  ~ ${c.path}  [op #${c.operationIndex + 1}]`);
+    lines.push("");
+  }
+  if (report.untracked.length > 0) {
+    lines.push(`Untracked (${report.untracked.length}) — modified, NO Operation references it; propose new Operation:`);
+    for (const u of report.untracked) lines.push(`  + ${u.path}`);
+    lines.push("");
+  }
+  if (report.missing.length > 0) {
+    lines.push(`Missing (${report.missing.length}) — Operation file_hint points at a file that doesn't exist:`);
+    for (const m of report.missing) lines.push(`  ! ${m.path}  [op #${m.operationIndex + 1}] — ${m.suggestion}`);
+    lines.push("");
+  }
+  if (report.clean.length > 0) {
+    lines.push(`Clean (${report.clean.length}) — covered, unchanged.`);
+  }
+  lines.push("", "Run with --json for machine-readable output. Future: --apply to propose Canvas patches (issue #540 follow-ups).");
+  return lines.join("\n");
+}

package/src/tracker-bootstrap.js

@@ -0,0 +1,44 @@
+/**
+ * Tracker bootstrap — registers the configured task-tracker adapter into
+ * the orchestrator's integrations registry at runtime.
+ *
+ * This module exists so that `src/orchestrator/` never imports
+ * `src/planning-game/` (or any other tracker) directly — the architecture
+ * invariant `tests/architecture/tracker-coupling.test.js` enforces that.
+ * `runFlow` calls `ensureTrackerRegistered(config)` from here; this
+ * module owns the conditional import of each adapter.
+ *
+ * Adding a new tracker:
+ *   1. Write `src/adapters/<name>/adapter.js` with the hook surface
+ *      documented in `src/orchestrator/integrations.js`.
+ *   2. Add a branch below that imports and registers it when the relevant
+ *      config flag is true.
+ *
+ * The function is idempotent: once registered, subsequent calls are
+ * no-ops (the registry already has an entry for the slot).
+ */
+
+import { getIntegration, registerIntegration } from "./orchestrator/integrations.js";
+
+/**
+ * Ensure the tracker adapter configured by `config` is registered under
+ * the `"tracker"` slot. Safe to call on every `runFlow` invocation.
+ *
+ * @param {object|null} config
+ * @returns {Promise<void>}
+ */
+export async function ensureTrackerRegistered(config) {
+  if (getIntegration("tracker")) return; // Already registered.
+
+  if (config?.planning_game?.enabled) {
+    try {
+      const { planningGameAdapter } = await import("./planning-game/pipeline-adapter.js");
+      registerIntegration("tracker", planningGameAdapter);
+    } catch { /* registration failed — non-blocking, adapter stays absent */ }
+    return;
+  }
+
+  // No tracker enabled — the orchestrator's `getIntegration("tracker")`
+  // calls will return undefined and every hook becomes an optional-chain
+  // no-op. That's the intended behavior for "tracker disabled" runs.
+}

package/src/utils/agent-detect.js

@@ -18,17 +18,21 @@ export async function checkBinary(name, versionArg = "--version") {
 }
 
 export async function detectAvailableAgents() {
-  const results = [];
-  for (const agent of KNOWN_AGENTS) {
-    const check = await checkBinary(agent.name);
-    results.push({
-      name: agent.name,
-      available: check.ok,
-      version: check.ok ? check.version : null,
-      install: agent.install
-    });
-  }
-  return results;
+  // PR-J (audit quick win): probe the 5 agent binaries in parallel
+  // via Promise.all instead of awaiting in a for-of. checkBinary is
+  // a pure shell-out (no shared state), so serialising them was
+  // wasted latency. With 5 agents at ~80ms each: O(n) → O(1).
+  return Promise.all(
+    KNOWN_AGENTS.map(async (agent) => {
+      const check = await checkBinary(agent.name);
+      return {
+        name: agent.name,
+        available: check.ok,
+        version: check.ok ? check.version : null,
+        install: agent.install
+      };
+    })
+  );
 }
 
 /**

package/src/utils/board-prompt-bridge.js

@@ -0,0 +1,109 @@
+/**
+ * File-based RPC between a non-interactive Karajan run and the HU
+ * Board. When the runner needs an answer to a question (Solomon
+ * escalation, max-iterations resolution, anything wired to
+ * askQuestion) and stdin is unavailable (the board's ▶ Run plan
+ * spawns with stdio=ignore), it writes a prompt JSON to a known
+ * directory and polls for an "answer" sibling file. The board's
+ * chokidar watcher sees the prompt and surfaces it as a modal; the
+ * user's answer is POSTed back, written as the answer file, and the
+ * runner picks it up and resolves.
+ *
+ * Why files instead of a socket / SSE-back-channel:
+ *   - Zero new server in the runner. A detached child has no listening
+ *     port; opening one would mean discovery + auth + cleanup.
+ *   - Survives a runner restart: if the user kills + resumes, the
+ *     pending prompt is still on disk and the board can re-show it.
+ *   - The board already watches `~/.karajan/`; one more glob is cheap.
+ *
+ * Layout:
+ *   $KJ_HOME/prompts/<promptId>.json         - { sessionId, question, context, createdAt }
+ *   $KJ_HOME/prompts/<promptId>.answer.json  - { answer, answeredAt }    (written by board)
+ *
+ * The bridge owns the lifecycle: write the prompt, poll until the
+ * answer arrives, delete BOTH files, return the answer string (or
+ * null when the user picked "stop"). Aborts cleanly on signal or on
+ * a configurable timeout (default 30 min — long enough for a coffee).
+ */
+
+import { mkdir, writeFile, readFile, unlink, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { randomUUID } from "node:crypto";
+
+const POLL_INTERVAL_MS = 500;
+const DEFAULT_TIMEOUT_MS = 30 * 60 * 1000;          // 30 min
+
+function getPromptsDir() {
+  const home = process.env.KJ_HOME || join(homedir(), ".karajan");
+  return join(home, "prompts");
+}
+
+function exists(path) {
+  return stat(path).then(() => true, () => false);
+}
+
+/**
+ * Publish a prompt + wait for the answer. Returns the answer string,
+ * `null` when the user explicitly picked "stop", or rejects on
+ * timeout / abort.
+ *
+ * @param {object} args
+ * @param {string} args.sessionId
+ * @param {string} args.question
+ * @param {object} [args.context]   - serialised verbatim into the prompt JSON
+ * @param {number} [args.timeoutMs]
+ * @param {AbortSignal} [args.signal]
+ * @param {object} [args.logger]    - { info, warn } — optional, for breadcrumbs
+ * @returns {Promise<string|null>}
+ */
+export async function askThroughBoard({ sessionId, question, context = null, timeoutMs = DEFAULT_TIMEOUT_MS, signal = null, logger = null } = {}) {
+  if (!question) throw new Error("askThroughBoard: question is required");
+
+  const dir = getPromptsDir();
+  await mkdir(dir, { recursive: true });
+
+  const promptId = `prompt-${Date.now()}-${randomUUID().slice(0, 8)}`;
+  const promptPath = join(dir, `${promptId}.json`);
+  const answerPath = join(dir, `${promptId}.answer.json`);
+
+  const payload = {
+    promptId,
+    sessionId: sessionId || null,
+    question,
+    context: context || null,
+    createdAt: new Date().toISOString(),
+  };
+  await writeFile(promptPath, JSON.stringify(payload, null, 2), "utf-8");
+  logger?.info?.(`[prompt-bridge] published ${promptId} — waiting for answer via the board`);
+
+  const startedAt = Date.now();
+  try {
+    while (true) {
+      if (signal?.aborted) throw new Error("askThroughBoard: aborted");
+      if (Date.now() - startedAt > timeoutMs) {
+        throw new Error(`askThroughBoard: timed out after ${Math.round(timeoutMs / 1000)}s waiting for answer to ${promptId}`);
+      }
+      if (await exists(answerPath)) {
+        const raw = await readFile(answerPath, "utf-8");
+        let answer;
+        try { ({ answer } = JSON.parse(raw)); } catch { answer = null; }
+        await unlink(answerPath).catch(() => {});
+        await unlink(promptPath).catch(() => {});
+        if (typeof answer === "string" && answer.trim().toLowerCase() === "stop") return null;
+        return typeof answer === "string" ? answer.trim() : null;
+      }
+      await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+    }
+  } catch (err) {
+    // Best-effort cleanup of the prompt file on error so it doesn't
+    // get stuck pending on the board forever.
+    await unlink(promptPath).catch(() => {});
+    throw err;
+  }
+}
+
+/** Test seam — exposes the resolved prompts dir for assertions. */
+export function _getPromptsDirForTests() {
+  return getPromptsDir();
+}