karajan-code 3.12.3 → 3.13.1

package/package.json

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

package/src/config/defaults.js

@@ -55,7 +55,10 @@ const DEFAULTS = {
   review_mode: "standard",
   max_iterations: 5,
   hu_max_iterations: 3,
-  max_budget_usd: null,
+  // Hard per-run spend ceiling, ON by default (KJC-TSK-0621): a stuck or
+  // runaway run must never drain a subscription quota unattended. Explicit
+  // null in the user's config opts out (no cap).
+  max_budget_usd: 5,
   review_rules: "./.karajan/review-rules.md",
   coder_rules: "./.karajan/coder-rules.md",
   base_branch: "main",

package/src/config/overrides.js

@@ -172,8 +172,14 @@ export function applyRunOverrides(config, flags) {
   out.git = out.git || {};
   out.development = out.development || {};
   out.sonarqube = out.sonarqube || {};
-  if (out.max_budget_usd === undefined || out.max_budget_usd === null) {
-    out.max_budget_usd = out.session.max_budget_usd ?? null;
+  // Precedence: explicit top-level value (including null = opt-out) wins;
+  // the legacy session.max_budget_usd location next; the shipped default
+  // (KJC-TSK-0621: 5) last. When top-level still carries the default, a
+  // session-level value — including an explicit null — takes over.
+  if (out.max_budget_usd === undefined) {
+    out.max_budget_usd = out.session.max_budget_usd !== undefined ? out.session.max_budget_usd : DEFAULTS.max_budget_usd;
+  } else if (out.max_budget_usd === DEFAULTS.max_budget_usd && out.session.max_budget_usd !== undefined) {
+    out.max_budget_usd = out.session.max_budget_usd;
   }
   out.budget = mergeDeep(DEFAULTS.budget, out.budget || {});
   out.roles = mergeDeep(DEFAULTS.roles, out.roles || {});

package/src/harden/advisory.js

@@ -12,6 +12,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
 import { findManagedBlock } from "../utils/managed-markers.js";
+import { findAlternative } from "./alternatives.js";
 import { CONFIGS_BY_LANGUAGE, UNIVERSAL_CONFIGS } from "./config-templates.js";
 import { detectStackRoots } from "./stack-roots.js";
 
@@ -98,6 +99,13 @@ function readArtifactContent(searchDir, foundAt) {
 
 /** Map a classified state to a recommendation + human rationale. */
 function recommend(state) {
+  if (state.status === "SATISFIED_BY_ALTERNATIVE") {
+    return {
+      recommendation: "keep",
+      rationale: `covered by ${state.foundAt} (${state.alternativeTool}) — kj won't add a second linter/formatter`,
+      mergeable: false,
+    };
+  }
   if (state.status === "MISSING") return { recommendation: "install", rationale: `kj would add ${state.file}`, mergeable: true };
   if (state.status === "USER_OWNED") {
     const n = state.improvements?.length ?? 0;
@@ -109,11 +117,20 @@ function recommend(state) {
   return { recommendation: "update", rationale: `kj v${state.currentVersion} available (you have v${state.managedVersion})`, mergeable: true };
 }
 
-/** Classify a single artifact found (or not) under `searchDir`. */
-export function classifyArtifact(searchDir, artifact) {
+/**
+ * Classify a single artifact found (or not) under `searchDir`. `altDirs`
+ * widens the cross-tool alternative lookup (a root-level biome.json covers a
+ * monorepo's language roots); the user's OWN config of the same tool still
+ * wins over an alternative.
+ */
+export function classifyArtifact(searchDir, artifact, altDirs = [searchDir]) {
   const foundAt = findArtifactFile(searchDir, artifact);
   const base = { foundAt, managedVersion: null, upToDate: null, improvements: [] };
   let state = { ...base, status: "MISSING" };
+  if (!foundAt) {
+    const alt = findAlternative(altDirs, artifact.id);
+    if (alt) state = { ...base, status: "SATISFIED_BY_ALTERNATIVE", foundAt: alt.foundAt, alternativeTool: alt.tool };
+  }
   if (foundAt) {
     const content = readArtifactContent(searchDir, foundAt);
     if (artifact.blockId && content.includes(`kj:managed:${artifact.blockId}`)) {
@@ -139,8 +156,10 @@ export function compareHarden({ projectDir = process.cwd(), profile = "standard"
   for (const { dir, language } of detectStackRoots(projectDir, { only, exclude })) {
     const searchDir = dir === "." ? projectDir : join(projectDir, dir);
     for (const cfg of CONFIGS_BY_LANGUAGE[language] ?? []) {
-      const res = classifyArtifact(searchDir, toArtifact(cfg));
-      artifacts.push({ dir, ...res, foundAt: res.foundAt && dir !== "." ? join(dir, res.foundAt) : res.foundAt });
+      const res = classifyArtifact(searchDir, toArtifact(cfg), [searchDir, projectDir]);
+      // Alternative matches may live at the repo root — keep their path unprefixed.
+      const prefix = res.foundAt && dir !== "." && res.status !== "SATISFIED_BY_ALTERNATIVE";
+      artifacts.push({ dir, ...res, foundAt: prefix ? join(dir, res.foundAt) : res.foundAt });
     }
   }
   return { artifacts };

package/src/harden/alternatives.js

@@ -0,0 +1,50 @@
+/**
+ * Cross-tool alternatives for `kj harden` (KJC-TSK-0614).
+ *
+ * A user's Biome config replaces BOTH eslint and prettier — seeding kj's
+ * configs next to biome.json installs a second, conflicting linter/formatter
+ * that fights the user's own hooks. The advisory's EQUIVALENTS map only
+ * covers same-tool filename variants; this map covers whole-tool
+ * substitutions, and the three surfaces (advisory, config-engine, check)
+ * consult it before treating an artifact as missing.
+ *
+ * Detection is config-file based on purpose: deterministic, and a false
+ * negative just means kj proposes its default (the pre-0614 behaviour),
+ * never that it overwrites the user's tool.
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+const ALTERNATIVES = {
+  eslint: [{ tool: "biome", files: ["biome.json", "biome.jsonc"] }],
+  prettier: [{ tool: "biome", files: ["biome.json", "biome.jsonc"] }],
+};
+
+/**
+ * First alternative tool that satisfies `artifactId`, searching each dir in
+ * order (a language root first, then the repo root — a root-level biome.json
+ * covers the whole monorepo). Null when none applies.
+ *
+ * @param {string[]} searchDirs
+ * @param {string} artifactId - "eslint" | "prettier" | ...
+ * @returns {{ tool: string, foundAt: string }|null}
+ */
+export function findAlternative(searchDirs, artifactId) {
+  for (const alt of ALTERNATIVES[artifactId] ?? []) {
+    for (const dir of searchDirs) {
+      for (const rel of alt.files) {
+        if (existsSync(join(dir, rel))) return { tool: alt.tool, foundAt: rel };
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Artifact id for a config-template entry — same convention as the
+ * advisory's toArtifact: prettier is the only marker-less JSON config.
+ */
+export function artifactIdForConfig(cfg) {
+  return cfg.blockId ?? "prettier";
+}

package/src/harden/check.js

@@ -11,6 +11,7 @@ import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 
 import { runCommand } from "../utils/process.js";
+import { artifactIdForConfig, findAlternative } from "./alternatives.js";
 import { CONFIGS_BY_LANGUAGE, UNIVERSAL_CONFIGS } from "./config-templates.js";
 import { PROFILE_HOOKS } from "./hook-templates.js";
 import { detectStackRoots } from "./stack-roots.js";
@@ -53,8 +54,18 @@ export async function checkHarden({ projectDir = process.cwd(), profile = "stand
       checks.push(presence(projectDir, cfg.file, `config:${cfg.file}`, "missing — run kj harden"));
     }
     for (const { dir, language } of roots) {
+      const rootDir = dir === "." ? projectDir : join(projectDir, dir);
       for (const cfg of CONFIGS_BY_LANGUAGE[language] ?? []) {
         const rel = dir === "." ? cfg.file : join(dir, cfg.file);
+        // A config covered by the user's own tool (biome.json ⇒ eslint+prettier)
+        // is not drift — kj must not demand a second linter/formatter (KJC-TSK-0614).
+        if (!existsSync(join(projectDir, rel))) {
+          const alt = findAlternative([rootDir, projectDir], artifactIdForConfig(cfg));
+          if (alt) {
+            checks.push({ id: `config:${rel}`, ok: true, detail: `covered by ${alt.foundAt} (${alt.tool})` });
+            continue;
+          }
+        }
         checks.push(presence(projectDir, rel, `config:${rel}`, `missing for ${language} — run kj harden`));
       }
     }

package/src/harden/config-engine.js

@@ -9,6 +9,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 
 import { upsertManagedBlock } from "../utils/managed-markers.js";
+import { artifactIdForConfig, findAlternative } from "./alternatives.js";
 import { CONFIGS_BY_LANGUAGE, UNIVERSAL_CONFIGS } from "./config-templates.js";
 
 const BLOCK_VERSION = 1;
@@ -18,13 +19,26 @@ function writeFile(target, content) {
   writeFileSync(target, content);
 }
 
-/** Seed a list of config entries into `targetDir`, labelling each by `prefix`. */
-function seedInto(targetDir, configs, dryRun, prefix, results) {
+/**
+ * Seed a list of config entries into `targetDir`, labelling each by `prefix`.
+ * `altDirs` widens the cross-tool alternative lookup (KJC-TSK-0614): a config
+ * covered by the user's own tool (biome.json ⇒ eslint+prettier) is never
+ * seeded — kj must not install a second, conflicting linter/formatter.
+ */
+function seedInto(targetDir, configs, dryRun, prefix, results, altDirs = [targetDir]) {
   for (const cfg of configs) {
     const target = join(targetDir, cfg.file);
     const exists = existsSync(target);
     const file = prefix === "." ? cfg.file : join(prefix, cfg.file);
 
+    if (!exists) {
+      const alt = findAlternative(altDirs, artifactIdForConfig(cfg));
+      if (alt) {
+        results.push({ file, action: "covered", by: alt.foundAt });
+        continue;
+      }
+    }
+
     if (cfg.json) {
       const action = exists ? "skipped" : "inserted";
       if (!dryRun && !exists) writeFile(target, `${cfg.body}\n`);
@@ -69,7 +83,9 @@ export function installConfigsForRoots({ projectDir = process.cwd(), roots = [],
   const results = [];
   seedInto(projectDir, UNIVERSAL_CONFIGS, dryRun, ".", results);
   for (const { dir, language } of roots) {
-    seedInto(join(projectDir, dir), CONFIGS_BY_LANGUAGE[language] ?? [], dryRun, dir, results);
+    const rootDir = join(projectDir, dir);
+    // A root-level biome.json covers every language root of the monorepo.
+    seedInto(rootDir, CONFIGS_BY_LANGUAGE[language] ?? [], dryRun, dir, results, [rootDir, projectDir]);
   }
   return { dryRun, configs: results };
 }

package/src/orchestrator/flow-control.js

@@ -153,7 +153,11 @@ export async function checkBudgetExceeded({ budgetTracker, config, session, emit
 
   await markSessionStatus(session, "failed");
   const totalCost = budgetTracker.total().cost_usd;
-  const message = `Budget exceeded: $${totalCost.toFixed(2)} > $${budgetLimit.toFixed(2)}`;
+  const limit = Number(budgetLimit ?? config?.max_budget_usd);
+  const message =
+    `Budget exceeded: $${totalCost.toFixed(2)} > $${limit.toFixed(2)}. ` +
+    `Continue consciously with \`kj resume ${session.id}\`, or raise the cap ` +
+    `(max_budget_usd in .karajan/kj.config.yml; null removes it).`;
   emitProgress(
     emitter,
     makeEvent("session:end", { ...eventBase, iteration: i, stage: "budget" }, {

package/templates/kj.config.yml

@@ -114,5 +114,7 @@ output:
 session:
   max_iteration_minutes: 15
   max_total_minutes: 120
-  max_budget_usd: null
+  # Hard per-run spend ceiling (USD-equivalent). The run stops with a summary
+  # when exceeded; resume with `kj resume`. Set to null to remove the cap.
+  max_budget_usd: 5
   fail_fast_repeats: 2