karajan-code 2.7.3 → 2.7.4

package/README.md

@@ -23,7 +23,7 @@
 
 ---
 
-> **v2.7.3 released** — Three dogfooding fixes: (1) task can now come from a `.md` file — `kj run --task-file spec.md` or MCP `kj_run({ taskFile: "spec.md" })`, same for `kj plan/audit/code/review/discover/triage/researcher/architect`; (2) CLI commands finally write `.kj/run.log` like MCP does, so `kj-tail` works whether Claude Code launches `kj` via Bash or the MCP tool; (3) Node 18 LTS is really supported now (preflight no longer refuses 18 with a bogus "needs Node 20" message), and `kj-tail` v1.38.0 waits for the log file to appear instead of exiting. Carries the full v2.7 skills story: [`addyosmani/agent-skills`](https://github.com/addyosmani/agent-skills) as Karajan's first-source process catalog (20+ lifecycle workflows) injected per role **before** OpenSkills stack skills, `summary.md` now surfaces which slugs shaped each role's prompt. See [CHANGELOG.md](./CHANGELOG.md) for full history and [MIGRATION-v2.md](./MIGRATION-v2.md) for v1→v2 breaking changes.
+> **v2.7.4 released** — Three contract fixes: (1) **Sonar is now intrinsic** to Karajan for code tasks (`sw`/`refactor`/`add-tests`) — `sonarqube.enabled` config and `--no-sonar` flag are ignored with a deprecation warning; a code task without a quality gate is not a job Karajan calls complete, like TDD; Solomon still may skip an iteration at runtime via rules. (2) **Preflight no longer demands API keys Karajan doesn't use** — the bogus `ANTHROPIC_API_KEY not set` check was blocking every Claude Code MCP run; replaced with a real CLI availability check (`claude`, `codex`, `gemini` on PATH). (3) **Orchestrator no longer crashes** with `Cannot read properties of undefined (reading 'push')` on the Solomon init-error path. Adds two architectural invariants (`no-provider-apis`, `sonar-intrinsic`) to CI so the contracts can't silently drift back. New `docs/TESTS.md` test-suite guide with diagrams. See [CHANGELOG.md](./CHANGELOG.md) for full history and [MIGRATION-v2.md](./MIGRATION-v2.md) for v1→v2 breaking changes.
 
 You describe what you want to build. Karajan orchestrates multiple AI agents to plan it, implement it, test it, review it with SonarQube, and iterate. No babysitting required.
 
@@ -297,9 +297,9 @@ Not nostalgia, not stubbornness. I've been using JavaScript since 1997, when Bre
 | Tool | Why |
 |------|-----|
 | [**RTK**](https://github.com/rtk-ai/rtk) | Reduces token consumption by 60-90% on Bash command outputs |
-| [**Planning Game MCP**](https://github.com/AgenteIA-Geniova/planning-game-mcp) | Agile project management (tasks, sprints, estimation), XP-native |
-| [**GitHub MCP**](https://github.com/modelcontextprotocol/servers/tree/main/src/github) | Create PRs, manage issues directly from the agent |
-| [**Chrome DevTools MCP**](https://github.com/anthropics/anthropic-quickstarts/tree/main/chrome-devtools-mcp) | Verify UI changes visually after frontend modifications |
+| [**Planning Game MCP**](https://github.com/manufosela/planning-game-xp-mcp) | Agile project management (tasks, sprints, estimation), XP-native |
+| [**GitHub MCP**](https://github.com/github/github-mcp-server) | Create PRs, manage issues directly from the agent |
+| [**Chrome DevTools MCP**](https://github.com/ChromeDevTools/chrome-devtools-mcp) | Verify UI changes visually after frontend modifications |
 
 ## Contributing
 

package/package.json

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

package/src/checks/ports.js

@@ -38,7 +38,18 @@ export function createSonarPortCheck() {
     name: "port:sonar",
     label: "SonarQube port",
     strategy: STRATEGY.MANUAL,
-    applies: (config) => config?.sonarqube?.enabled !== false,
+    // 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).
+    applies: (config) => {
+      if (config?.sonarqube?.external === true) {
+        return { applies: false, reason: "sonarqube.external is true — port managed outside Karajan" };
+      }
+      return true;
+    },
     async detect({ config }) {
       const port = extractPortFromHost(config?.sonarqube?.host, DEFAULT_SONAR_PORT);
       const free = await isPortAvailable(port);
@@ -73,7 +84,12 @@ export function createHuBoardPortCheck() {
     name: "port:hu-board",
     label: "HU Board port",
     strategy: STRATEGY.AUTO,
-    applies: (config) => config?.hu_board?.enabled !== false,
+    applies: (config) => {
+      if (config?.hu_board?.enabled === false) {
+        return { applies: false, reason: "hu_board.enabled is false in kj.config.yml — HU Board dashboard skipped" };
+      }
+      return true;
+    },
     describe: "Rebind HU Board to the next free port",
     async detect({ config }) {
       const port = config?.hu_board?.port || DEFAULT_HU_BOARD_PORT;

package/src/checks/runner.js

@@ -55,19 +55,35 @@ export async function runChecks(checks, ctx, options = {}) {
   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" && !check.applies(config)) {
-      entries.push({
-        check,
-        status: STATUS.SKIPPED,
-        detail: "Not applicable for current configuration",
-        runMs: 0,
-        detectResult: null,
-        remediated: false,
-      });
-    } else {
+    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.

package/src/checks/tokens.js

@@ -1,41 +1,83 @@
 /**
- * API token availability checks.
+ * Provider CLI availability checks (preflight).
  *
- * Provider tokens (ANTHROPIC_API_KEY / OPENAI_API_KEY / ...) are LAZY:
- * we only check them for providers that are actually used by at least one
- * active role in the current config.
+ * IMPORTANT — Karajan does NOT call provider APIs directly. There is no
+ * `@anthropic-ai/sdk`, no `openai`, no `@google/generative-ai` in
+ * package.json. Every active role spawns its agent CLI as a subprocess
+ * (`claude`, `codex`, `gemini`, `opencode`, `aider`). The CLI handles its
+ * own auth, typically via OAuth + on-disk token (Claude Code, Codex CLI,
+ * Gemini CLI). The user does NOT need to set ANTHROPIC_API_KEY etc. for
+ * Karajan to work.
  *
- * Strategy:
- *   - Required providers with no key → FAIL, strategy manual (we can't
- *     fetch an API key for the user). Fix hint includes the how-to URL.
- *   - Optional providers (opencode, aider) without key → WARN.
- *   - GH_TOKEN is checked when git.auto_pr=true, strategy prompt (we can
- *     launch `gh auth login` with user approval).
+ * Pre-v2.7.4 this module checked for ANTHROPIC_API_KEY / OPENAI_API_KEY /
+ * GEMINI_API_KEY env vars and FAILed preflight when missing — a false
+ * positive that blocked every user running Karajan as an MCP child of
+ * Claude Code (where `apiKeySource: "none"` is the norm). Replaced with a
+ * CLI-availability check that mirrors what the orchestrator actually does.
+ *
+ * GH_TOKEN is still checked when `git.auto_pr=true`, because that flow uses
+ * `git push` directly with the env var.
  */
 
 import { checkBinary } from "../utils/agent-detect.js";
-import { getRequiredProviderEnvs, hasEnvVar } from "../utils/provider-env.js";
+import { getRequiredProviderEnvs, normalizeProvider } from "../utils/provider-env.js";
 import { STRATEGY } from "./types.js";
 
 /**
- * A single provider env check. One is created per active provider.
+ * Map canonical provider name → the CLI binary Karajan actually spawns.
+ * Keep in sync with src/agents/index.js.
  */
-function createProviderTokenCheck(entry) {
+const PROVIDER_TO_CLI = Object.freeze({
+  anthropic: "claude",
+  openai: "codex",
+  google: "gemini",
+  opencode: "opencode",
+  aider: "aider",
+});
+
+/**
+ * Build a CLI-availability check for one provider.
+ *
+ * The check runs `<cli> --version`. If the binary is on PATH and exits 0,
+ * preflight passes — Karajan can spawn it. If the CLI is missing, preflight
+ * fails with the install URL we already track in PROVIDER_ENV.
+ *
+ * Note: we do NOT verify that the CLI is *authenticated*. Doing so would
+ * require provider-specific introspection (`claude doctor`, `codex login
+ * status`, ...), each with its own quirks and exit codes. If the CLI is
+ * present but not logged in, the agent will fail at the first request with
+ * a clear error — and the orchestrator surfaces that error already.
+ */
+function createProviderCliCheck(entry) {
+  const cli = PROVIDER_TO_CLI[entry.provider];
   return {
-    name: `token:${entry.provider}`,
-    label: `API token: ${entry.provider}`,
+    name: `cli:${entry.provider}`,
+    label: `${entry.provider} CLI (${cli})`,
     strategy: STRATEGY.MANUAL,
     async detect() {
-      const ok = hasEnvVar(entry);
-      if (ok) {
-        return { ok: true, severity: "info", detail: `${entry.envVars[0]} is set` };
+      if (!cli) {
+        return {
+          ok: false,
+          severity: "warn",
+          detail: `Unknown CLI for provider ${entry.provider}`,
+          extra: { provider: entry.provider },
+        };
+      }
+      const result = await checkBinary(cli);
+      if (result.ok) {
+        return {
+          ok: true,
+          severity: "info",
+          detail: `${cli} on PATH (${result.version || "version unknown"})`,
+          extra: { provider: entry.provider, cli, version: result.version, path: result.path },
+        };
       }
       return {
         ok: false,
         severity: entry.optional ? "warn" : "fail",
-        detail: `${entry.envVars.join(" / ")} not set`,
-        fix: `Get an API key at ${entry.howToGetUrl} and export ${entry.envVars[0]}=...`,
-        extra: { provider: entry.provider, envVars: entry.envVars, howToGetUrl: entry.howToGetUrl },
+        detail: `${cli} not found on PATH`,
+        fix: `Install the ${cli} CLI: see ${entry.howToGetUrl}`,
+        extra: { provider: entry.provider, cli, howToGetUrl: entry.howToGetUrl },
       };
     },
   };
@@ -43,6 +85,8 @@ function createProviderTokenCheck(entry) {
 
 /**
  * GH token check + auto-remediation via `gh auth login` when it's installed.
+ * Kept from the previous version: this one IS legitimate because Karajan
+ * uses `gh` (or raw `git push`) directly when auto_pr is on.
  */
 function createGhTokenCheck() {
   return {
@@ -82,15 +126,24 @@ function createGhTokenCheck() {
 }
 
 /**
- * Build the list of token checks for the active config. Each active provider
- * gets one, plus conditional GH token when auto_pr is on.
+ * Build the list of CLI/token checks for the active config.
+ * - One CLI availability check per active provider (claude / codex / gemini / ...).
+ * - One GH token check, conditional on git.auto_pr.
+ *
+ * Function name kept as `getTokenChecks` for backward compat with
+ * preflight-checks.js, even though the bulk of the checks no longer touch
+ * tokens at all. Tracked: rename to `getProviderChecks` in a follow-up
+ * once consumers are updated.
  *
  * @param {Object} config
  * @returns {import("./types.js").Check[]}
  */
 export function getTokenChecks(config) {
   const required = getRequiredProviderEnvs(config);
-  const checks = required.map(createProviderTokenCheck);
+  const checks = required.map(createProviderCliCheck);
   checks.push(createGhTokenCheck());
   return checks;
 }
+
+// Re-export for tests that need to introspect the mapping.
+export { PROVIDER_TO_CLI, normalizeProvider };

package/src/config.js

@@ -290,6 +290,20 @@ export async function loadConfig(projectDir) {
     throw new Error(`Invalid Karajan config:\n${formatConfigIssues(validation.issues)}`);
   }
 
+  // Deprecation tracking — `sonarqube.enabled` was a footgun: users would
+  // set it to `false` in their global ~/.karajan/kj.config.yml and then
+  // wonder why Sonar didn't run on a code task. Since v2.7.4 Sonar is
+  // intrinsic to Karajan for code tasks; the field is ignored. We surface
+  // a warning at run start (see emitConfigDeprecations in flow-runner.js)
+  // so users notice and clean up their config. Don't throw — keep
+  // back-compat so existing scripts keep working.
+  const userSetSonarEnabled = (globalConfig?.sonarqube?.enabled !== undefined)
+    || (projectConfig?.sonarqube?.enabled !== undefined);
+  if (userSetSonarEnabled) {
+    merged._deprecated = merged._deprecated || {};
+    merged._deprecated.sonarqubeEnabledKey = true;
+  }
+
   return { config: merged, path: configPath, exists: globalExists, hasProjectConfig: !!projectConfig };
 }
 
@@ -423,7 +437,16 @@ function applyOutputModeOverrides(out, flags) {
 
 function applyMiscOverrides(out, flags) {
   if (flags[AUTO_SIMPLIFY_FLAG] !== undefined) out.pipeline.auto_simplify = Boolean(flags[AUTO_SIMPLIFY_FLAG]);
-  if (flags.noSonar || flags.sonar === false) out.sonarqube.enabled = false;
+  // `--no-sonar` and `sonarqube.enabled: false` are deprecated since v2.7.4.
+  // Sonar is intrinsic to Karajan for code tasks (sw/refactor/add-tests) and
+  // skipped for non-code tasks (audit/doc/infra/analysis/no-code) by policy.
+  // The flag is still accepted to avoid breaking scripts; it now emits a
+  // warning at run start and is otherwise ignored. See preflight-checks.js
+  // and flow-runner.js for the actual gate (resolvedPolicies.sonar).
+  if (flags.noSonar || flags.sonar === false) {
+    out._deprecated = out._deprecated || {};
+    out._deprecated.noSonarFlag = true;
+  }
   out.sonarcloud = out.sonarcloud || {};
   if (flags.enableSonarcloud === true) out.sonarcloud.enabled = true;
   if (flags.noSonarcloud === true || flags.sonarcloud === false) out.sonarcloud.enabled = false;

package/src/orchestrator/flow-runner.js

@@ -726,6 +726,12 @@ async function runPreLoopStages({ config, logger, emitter, eventBase, session, f
 
   let updatedConfig = resolvePipelinePolicies({ flags, config, stageResults, emitter, eventBase, session, pipelineFlags });
 
+  // Deprecation warnings recorded at config load time. Done here, after
+  // policies are resolved, so the message lands in context: if the user's
+  // legacy `sonarqube.enabled: false` is being ignored, this is the right
+  // moment for them to see it.
+  emitConfigDeprecations(updatedConfig, logger, emitter, eventBase);
+
   // --- Preflight environment checks ---
   const preflightResult = await runPreflightChecks({
     config: updatedConfig, logger, emitter, eventBase,
@@ -920,6 +926,46 @@ async function runPreLoopStages({ config, logger, emitter, eventBase, session, f
  * Setting skills.addyosmani.enabled = false, or removing "addyosmani" from
  * skills.sources, disables this step entirely (reverts to OpenSkills-only).
  */
+/**
+ * Print one-time deprecation warnings for config keys / CLI flags that
+ * Karajan no longer honours. Called once per run, after policy resolution
+ * so the message lands in context (the user sees what's being ignored
+ * RIGHT before the preflight that would have been affected).
+ *
+ * Currently surfaces:
+ *   - `sonarqube.enabled` set in user config → ignored since v2.7.4
+ *   - `--no-sonar` CLI flag → ignored since v2.7.4
+ */
+function emitConfigDeprecations(config, logger, emitter, eventBase) {
+  const dep = config?._deprecated;
+  if (!dep) return;
+
+  if (dep.sonarqubeEnabledKey) {
+    const m =
+      "DEPRECATED: `sonarqube.enabled` in kj.config.yml is ignored since v2.7.4. " +
+      "Sonar is intrinsic to Karajan for code tasks (sw/refactor/add-tests) and " +
+      "skipped for non-code tasks (audit/doc/infra/analysis/no-code) by policy. " +
+      "Remove the key from your config to silence this warning.";
+    logger.warn(m);
+    emitProgress(emitter, makeEvent("config:deprecated", { ...eventBase, stage: "config" }, {
+      message: m,
+      detail: { key: "sonarqube.enabled", since: "v2.7.4" },
+    }));
+  }
+
+  if (dep.noSonarFlag) {
+    const m =
+      "DEPRECATED: `--no-sonar` flag is ignored since v2.7.4. Sonar runs for code " +
+      "tasks by policy. To skip Sonar on a one-off run, use a non-code task type " +
+      "(e.g. `--task-type doc`) or rely on Solomon's runtime override.";
+    logger.warn(m);
+    emitProgress(emitter, makeEvent("config:deprecated", { ...eventBase, stage: "config" }, {
+      message: m,
+      detail: { flag: "--no-sonar", since: "v2.7.4" },
+    }));
+  }
+}
+
 async function ensureAddyosmaniSkills({ task, config, logger, session, emitter, eventBase }) {
   const skillsConfig = config?.skills || {};
   const sources = Array.isArray(skillsConfig.sources) ? skillsConfig.sources : ["addyosmani", "openskills", "local"];
@@ -1173,9 +1219,17 @@ async function runQualityGateStages({ config, logger, emitter, eventBase, sessio
   if (tddResult.action === "pause") return { action: "return", result: tddResult.result };
   if (tddResult.action === "continue") return { action: "continue" };
 
-  const skipSonarForTaskType = new Set(["infra", "doc", "no-code"]);
-  const effectiveTaskType = session.resolved_policies?.taskType || null;
-  if (config.sonarqube.enabled && !skipSonarForTaskType.has(effectiveTaskType)) {
+  // Sonar runs for code tasks per policy. Since v2.7.4 it is NOT
+  // toggleable via config — that's intrinsic to Karajan. The taskType
+  // policy (resolved_policies.sonar) is the single source of truth.
+  // Solomon may skip a single iteration via rule alerts; that's a
+  // runtime decision, not a config option.
+  //
+  // Test-only escape hatch: globalThis.__KJ_DISABLE_SONAR_STAGE forces
+  // the sonar stage off so tests don't have to spin up Docker. Set in
+  // tests/setup.js by default; production code never sees it.
+  const sonarStageDisabledForTest = globalThis.__KJ_DISABLE_SONAR_STAGE === true;
+  if (!sonarStageDisabledForTest && session.resolved_policies?.sonar !== false) {
     const sonarResult = await runSonarStage({
       config, logger, emitter, eventBase, session, trackBudget, iteration: i,
       repeatDetector, budgetSummary, sonarState, askQuestion, task, brainCtx
@@ -1864,7 +1918,11 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
   } catch (initError) {
     // Pre-loop stage failure → Solomon decides
     logger.warn(`Init/pre-loop error — escalating to Solomon: ${initError.message}`);
-    const tempSession = { id: "init-error", task, status: "failed" };
+    // tempSession needs `checkpoints` because invokeSolomon → addCheckpoint
+    // pushes into it. Pre-v2.7.4 this lacked the array and crashed with
+    // "Cannot read properties of undefined (reading 'push')" the moment
+    // Solomon was consulted on a preflight failure.
+    const tempSession = { id: "init-error", task, status: "failed", checkpoints: [] };
     const solomonResult = await invokeSolomon({
       config, logger, emitter, eventBase: { sessionId: "init-error", iteration: 0, stage: "init", startedAt: Date.now() },
       stage: "init_error", askQuestion, session: tempSession, iteration: 0,

package/src/orchestrator/preflight-checks.js

@@ -168,7 +168,21 @@ async function checkSecurityAgent(config) {
  * @returns {{ ok: boolean, checks: object[], remediations: string[], configOverrides: object, warnings: string[], errors: object[] }}
  */
 export async function runPreflightChecks({ config, logger, emitter, eventBase, resolvedPolicies, securityEnabled }) {
-  const sonarEnabled = Boolean(config.sonarqube?.enabled) && resolvedPolicies.sonar !== false;
+  // Sonar is intrinsic to Karajan for code tasks (sw/refactor/add-tests).
+  // Since v2.7.4 it is NOT toggleable via `config.sonarqube.enabled` —
+  // that field is ignored (deprecation warning emitted at config load).
+  // The taskType policy (resolved_policies.sonar from DEFAULT_POLICIES in
+  // src/guards/policy-resolver.js) is the single source of truth: sw /
+  // refactor / add-tests run Sonar, audit / doc / infra / analysis /
+  // no-code skip it. Solomon may decide to skip a single iteration via
+  // rule alerts — that's a runtime decision, not a config option.
+  //
+  // Test-only escape hatch: globalThis.__KJ_DISABLE_SONAR_STAGE === true
+  // forces sonar OFF in preflight too, so tests that don't want sonar
+  // events in their expected sequence don't have to set up Docker mocks.
+  // Set in tests/setup.js by default; production code never sees it.
+  const sonarStageDisabledForTest = globalThis.__KJ_DISABLE_SONAR_STAGE === true;
+  const sonarEnabled = !sonarStageDisabledForTest && resolvedPolicies.sonar !== false;
   const isExternalSonar = Boolean(config.sonarqube?.external);
   const sonarHost = resolveSonarHost(config.sonarqube?.host);
 

package/src/session-store.js

@@ -44,6 +44,12 @@ export async function loadSession(sessionId) {
 }
 
 export async function addCheckpoint(session, checkpoint) {
+  // Defensive: any caller that builds a stub session (e.g. the init-error
+  // path in flow-runner.js, where `tempSession = { id, task, status }` has
+  // no checkpoints array) would otherwise crash with
+  // "Cannot read properties of undefined (reading 'push')". Guard once here
+  // so the bug class is gone instead of fixing every call site.
+  if (!Array.isArray(session.checkpoints)) session.checkpoints = [];
   session.checkpoints.push({ at: new Date().toISOString(), ...checkpoint });
   await saveSession(session);
 }