karajan-code 3.1.0 → 3.3.0

package/src/commands/init.js

@@ -15,6 +15,12 @@ import { detectOsLocale, SUPPORTED_LANGUAGES } from "../utils/locale.js";
 import { buildTelemetryPayload, sendTelemetryEvent } from "../utils/telemetry.js";
 import { detectRtk } from "../utils/rtk-detect.js";
 import { installRtk } from "../utils/rtk-install.js";
+import { detectSqueezr } from "../utils/squeezr-detect.js";
+import { installSqueezr } from "../utils/squeezr-install.js";
+import { detectAiTrash, installAiTrashHook } from "../utils/ai-trash.js";
+import { detectQmd } from "../utils/qmd-detect.js";
+import { installQmd } from "../utils/qmd-install.js";
+import { registerQmdCollections } from "../utils/qmd-collection.js";
 import { detectProjectStack } from "../utils/stack-detect.js";
 import { bootstrapSonarToken } from "../sonar/token-bootstrap.js";
 
@@ -754,15 +760,74 @@ export async function initCommand({ logger, flags = {} }) {
     logger.info("No project stack detected — using default configuration.");
   }
 
-  // Check RTK availability — auto-install if missing
-  const rtk = await detectRtk();
-  if (rtk.available) {
-    logger.info(`RTK ${rtk.version || ""} detected.`);
+  // Check RTK availability — auto-install if missing (opt-out: --no-rtk)
+  const skipRtk = flags?.noRtk === true || flags?.rtk === false;
+  if (skipRtk) {
+    logger.info("RTK setup skipped (--no-rtk). Bash outputs will not be token-optimized.");
   } else {
-    const installResult = await installRtk(logger);
-    if (!installResult.ok) {
-      logger.warn("RTK is optional but recommended for 60-90% token savings.");
-      logger.warn(`  Manual install: ${getInstallCommand("rtk")}`);
+    const rtk = await detectRtk();
+    if (rtk.available) {
+      logger.info(`RTK ${rtk.version || ""} detected.`);
+    } else {
+      const installResult = await installRtk(logger);
+      if (!installResult.ok) {
+        logger.warn("RTK install failed — Bash outputs will not be token-optimized.");
+        logger.warn(`  Manual install: ${getInstallCommand("rtk")}`);
+      }
+    }
+  }
+
+  // Check Squeezr availability — auto-install if missing (opt-out: --no-squeezr)
+  const skipSqueezr = flags?.noSqueezr === true || flags?.squeezr === false;
+  if (skipSqueezr) {
+    logger.info("Squeezr setup skipped (--no-squeezr). Tool outputs will not be compressed.");
+  } else {
+    const squeezr = await detectSqueezr();
+    if (squeezr.available) {
+      logger.info(`Squeezr ${squeezr.version || ""} detected.`);
+    } else {
+      const installResult = await installSqueezr(logger);
+      if (!installResult.ok) {
+        logger.warn("Squeezr install failed — tool outputs will not be compressed.");
+        logger.warn(`  Manual install: ${getInstallCommand("squeezr")}`);
+      }
+    }
+  }
+
+  // Check ai-trash availability — register PreToolUse hook if binary present
+  // (opt-out: --no-ai-trash). The binary itself ships with karajan-code.
+  const skipAiTrash = flags?.noAiTrash === true || flags?.aiTrash === false;
+  if (skipAiTrash) {
+    logger.info("ai-trash setup skipped (--no-ai-trash). Destructive ops will run unprotected.");
+  } else {
+    const aiTrash = await detectAiTrash();
+    if (aiTrash.available) {
+      await installAiTrashHook(logger);
+    } else {
+      logger.warn("ai-trash kj-trash binary not found — destructive ops unprotected.");
+      logger.warn("  Reinstall karajan-code so kj-trash is on PATH.");
+    }
+  }
+
+  // Check QMD availability — auto-install if missing and register project
+  // collections (docs/, .reviews/, .karajan/plans/). Opt-out: --no-qmd.
+  const skipQmd = flags?.noQmd === true || flags?.qmd === false;
+  if (skipQmd) {
+    logger.info("QMD setup skipped (--no-qmd). Semantic wiki indexing disabled.");
+  } else {
+    const qmd = await detectQmd();
+    if (qmd.available) {
+      logger.info(`QMD ${qmd.version || ""} detected.`);
+    } else {
+      const installResult = await installQmd(logger);
+      if (!installResult.ok) {
+        logger.warn("QMD install failed — semantic wiki unavailable.");
+        logger.warn(`  Manual install: ${getInstallCommand("qmd")}`);
+      }
+    }
+    const recheck = await detectQmd();
+    if (recheck.available) {
+      await registerQmdCollections(process.cwd(), logger);
     }
   }
 

package/src/commands/qmd.js

@@ -0,0 +1,86 @@
+// KJC-TSK-0509 — `kj qmd query` CLI wrapper. Auto-resolves the project's QMD
+// collection (`<projectSlug>-<suffix>`) so users do not have to remember it.
+// Mirrors `kj rag query`'s friendly-error shape on missing binary/collection.
+// Distinction: rag = agent context (code+plans); qmd = human wiki (docs/*.md).
+import { runCommand } from "../utils/process.js";
+import { projectSlug } from "../utils/qmd-collection.js";
+
+const QMD_NOT_INSTALLED = /command not found|ENOENT|not recognized as/i;
+const COLLECTION_MISSING = /no such collection|collection .* not found|unknown collection/i;
+const INSTALL_HINT = "qmd not installed. Install it with: npm install -g @tobilu/qmd";
+const INIT_HINT = "Collection not registered for this project. Run `kj init` to register the wiki collection.";
+
+function suffixFor(scope) {
+  if (!scope || scope === "docs") return "docs";
+  if (scope === "reviews" || scope === ".reviews") return "reviews";
+  if (scope === "plans" || scope === ".karajan/plans" || scope === "karajan-plans") return "karajan-plans";
+  return scope;
+}
+
+function resolveCollection({ flags, projectDir }) {
+  if (flags.collection) return String(flags.collection).trim();
+  return `${projectSlug(projectDir)}-${suffixFor(flags.scope)}`;
+}
+
+function notInstalled(logger) {
+  logger.error?.(`[qmd] ${INSTALL_HINT}`);
+  process.exitCode = 127;
+  return { ok: false, error: "qmd not installed", installable: true };
+}
+
+export async function qmdQueryCommand({ text, config, logger, flags = {} }) {
+  if (!text || !String(text).trim()) throw new Error("kj qmd query: text argument required");
+  const projectDir = config?.projectDir || process.cwd();
+  const collection = resolveCollection({ flags, projectDir });
+  const limit = Math.min(Math.max(Number(flags.topK) || 10, 1), 50);
+  const args = ["query", String(text), "--format", "json", "-c", collection, "-n", String(limit)];
+  if (flags.fast) args.push("--no-rerank");
+
+  let out;
+  try {
+    out = await runCommand("qmd", args, { timeout: 120_000 });
+  } catch (err) {
+    if (err?.code === "ENOENT") return notInstalled(logger);
+    throw err;
+  }
+
+  const stderr = out.stderr || "";
+  if (out.exitCode === 127 || QMD_NOT_INSTALLED.test(stderr)) return notInstalled(logger);
+  if (COLLECTION_MISSING.test(stderr)) {
+    logger.error?.(`[qmd] ${INIT_HINT}`);
+    process.exitCode = 1;
+    return { ok: false, error: "collection not registered", collection };
+  }
+  if (out.exitCode !== 0) {
+    const msg = (stderr || out.stdout || `qmd exit ${out.exitCode}`).trim();
+    logger.error?.(`[qmd] ${msg}`);
+    process.exitCode = out.exitCode || 1;
+    return { ok: false, error: msg };
+  }
+
+  let results;
+  try { results = JSON.parse(out.stdout || "[]"); }
+  catch {
+    logger.error?.("[qmd] qmd output is not valid JSON");
+    process.exitCode = 1;
+    return { ok: false, error: "qmd output is not valid JSON" };
+  }
+
+  if (flags.json) {
+    process.stdout.write(`${JSON.stringify(results)}\n`);
+    return { ok: true, results };
+  }
+  if (!Array.isArray(results) || results.length === 0) {
+    logger.info(`[qmd] no hits for "${text}" in collection ${collection}`);
+    return { ok: true, results: [] };
+  }
+  logger.info(`[qmd] ${results.length} hit(s) in ${collection}:`);
+  for (const h of results) {
+    const src = h.source || h.path || h.file || "?";
+    const score = typeof h.score === "number" ? ` · score=${h.score.toFixed(4)}` : "";
+    const snippet = h.snippet || h.text || h.body || "";
+    logger.info(`  - ${src}${score}`);
+    if (snippet) logger.info(`    ${snippet.length > 200 ? `${snippet.slice(0, 200)}…` : snippet}`);
+  }
+  return { ok: true, results };
+}

package/src/commands/resume.js

@@ -1,53 +1,10 @@
 import { EventEmitter } from "node:events";
-import readline from "node:readline";
 import { resumeFlow } from "../orchestrator.js";
 import { createActivityLog } from "../activity-log.js";
 import { printEvent } from "../utils/display/event-handlers.js";
 import { withCliRunLog } from "../utils/cli-run-log.js";
 import { registerRun, unregisterRun } from "../utils/run-registry.js";
-
-function createCliAskQuestion(opts = {}) {
-  const { sessionId = null } = opts;
-  return async (question, context) => {
-    // Mirror the run.js logic: route to the board via the file-based
-    // bridge when there's no TTY; otherwise prompt the local terminal.
-    const stdinReadable = process.stdin && process.stdin.readable !== false;
-    const isInteractive = Boolean(process.stdin?.isTTY) && stdinReadable;
-    if (!isInteractive) {
-      const { askThroughBoard } = await import("../utils/board-prompt-bridge.js");
-      console.log(`\n\u2753 ${question}`);
-      if (context?.detail) {
-        console.log(`   Context: ${JSON.stringify(context.detail, null, 2)}`);
-      }
-      console.log(
-        "\n[non-interactive] Routing the prompt to the HU Board.\n"
-        + "  Open http://localhost:4000 \u2014 a modal will appear asking for your answer."
-      );
-      try {
-        return await askThroughBoard({ sessionId, question, context });
-      } catch (err) {
-        console.log(`\n[prompt-bridge] ${err.message} \u2014 stopping the session.`);
-        return null;
-      }
-    }
-
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-    return new Promise((resolve) => {
-      console.log(`\n\u2753 ${question}`);
-      if (context?.detail) {
-        console.log(`   Context: ${JSON.stringify(context.detail, null, 2)}`);
-      }
-      rl.question("\n> Your response (or 'stop' to exit): ", (answer) => {
-        rl.close();
-        if (answer.trim().toLowerCase() === "stop") {
-          resolve(null);
-        } else {
-          resolve(answer.trim());
-        }
-      });
-    });
-  };
-}
+import { createCliAskQuestion } from "../utils/cli-ask-question.js";
 
 export async function resumeCommand({ sessionId, answer, config, logger, flags }) {
   const jsonMode = flags?.json;
@@ -88,7 +45,11 @@ export async function resumeCommand({ sessionId, answer, config, logger, flags }
       }
     });
 
-    const askQuestion = createCliAskQuestion();
+    // KJC-BUG-0081 round 2 — propagate `flags` so the helper honours
+    // `--yes` here too. Before this fix, `kj resume <id> --yes` in
+    // non-TTY mode still routed every prompt to the HU Board bridge
+    // and hung, exactly the bug the original PR #995 fixed for `kj run`.
+    const askQuestion = createCliAskQuestion({ sessionId, flags });
     const result = await resumeFlow({
       sessionId,
       answer: answer || null,

package/src/commands/run.js

@@ -1,5 +1,4 @@
 import { EventEmitter } from "node:events";
-import readline from "node:readline";
 import { runFlow } from "../orchestrator.js";
 import { assertAgentsAvailable } from "../agents/availability.js";
 import { createActivityLog } from "../activity-log.js";
@@ -14,54 +13,11 @@ import { confirmCwd } from "../utils/cwd-confirm.js";
 import { runSpecReview } from "../spec-review/run-spec-review.js";
 import { maybeAutoUpdate } from "../rag/auto-update.js";
 
-function createCliAskQuestion(opts = {}) {
-  const { sessionId = null } = opts;
-  return async (question, context) => {
-    // Two paths:
-    //   - Interactive TTY: prompt via readline (the developer's terminal).
-    //   - No TTY (board's \u25b6 Run plan with stdio=ignore, CI, etc.): publish
-    //     the prompt through the file-based bridge so the HU Board can
-    //     surface it as a modal. The runner blocks on the bridge until
-    //     the user answers (or times out / kills the run). Pre-v2.7.5
-    //     this path just bailed; now the question actually gets answered.
-    const stdinReadable = process.stdin && process.stdin.readable !== false;
-    const isInteractive = Boolean(process.stdin?.isTTY) && stdinReadable;
-    if (!isInteractive) {
-      const { askThroughBoard } = await import("../utils/board-prompt-bridge.js");
-      console.log(`\n\u2753 ${question}`);
-      if (context?.detail) {
-        console.log(`   Context: ${JSON.stringify(context.detail, null, 2)}`);
-      }
-      console.log(
-        "\n[non-interactive] Routing the prompt to the HU Board.\n"
-        + "  Open http://localhost:4000 \u2014 a modal will appear asking for your answer.\n"
-        + "  This process is now waiting; closing the board does NOT cancel the run."
-      );
-      try {
-        return await askThroughBoard({ sessionId, question, context });
-      } catch (err) {
-        console.log(`\n[prompt-bridge] ${err.message} \u2014 stopping the session.`);
-        return null;
-      }
-    }
-
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-    return new Promise((resolve) => {
-      console.log(`\n\u2753 ${question}`);
-      if (context?.detail) {
-        console.log(`   Context: ${JSON.stringify(context.detail, null, 2)}`);
-      }
-      rl.question("\n> Your response (or 'stop' to exit): ", (answer) => {
-        rl.close();
-        if (answer.trim().toLowerCase() === "stop") {
-          resolve(null);
-        } else {
-          resolve(answer.trim());
-        }
-      });
-    });
-  };
-}
+// Re-export the shared helper so existing imports (tests, MCP wrappers)
+// keep working. KJC-BUG-0081 round 2 split the body into utils/ because
+// resume.js also needs the same contract.
+import { createCliAskQuestion } from "../utils/cli-ask-question.js";
+export { createCliAskQuestion };
 
 export async function runCommandHandler({ task, config, logger, flags }) {
   // PR-F (cwd confirmation): when launching from an interactive
@@ -171,7 +127,7 @@ export async function runCommandHandler({ task, config, logger, flags }) {
       printHeader({ task: task, config });
     }
 
-    const askQuestion = createCliAskQuestion();
+    const askQuestion = createCliAskQuestion({ flags });
 
     // Spec-reviewer pre-pipeline audit (KJC-PCS-0048). Runs BEFORE
     // anything else — surfaces ambiguity / missing scope / missing AC

package/src/git/hu-snapshot.js

@@ -1,105 +1,10 @@
-// KJC-TSK-0408: snapshots de ficheros por HU para soportar Undo.
-//
-// Antes de ejecutar una HU, guardamos un ref git apuntando al HEAD
-// actual (`refs/kj-snapshots/<huId>`). Si el usuario hace Undo después,
-// hacemos `git reset --hard <ref>` para volver al estado pre-run.
-//
-// Por qué refs en lugar de stash/tarball:
-//   - Refs son objetos git nativos. No mueven blobs (todos compartidos
-//     con HEAD), así que crear el snapshot es O(1).
-//   - El snapshot persiste a través de checkouts y rebases.
-//   - Si el ref ya apunta al SHA correcto, restore es no-op.
-//
-// El runner es inyectable para que los tests no necesiten un repo git real.
-
-import { runCommand } from "../utils/process.js";
-
-const REF_PREFIX = "refs/kj-snapshots/";
-
-/**
- * Sanitiza un huId para uso como nombre de ref. Git rechaza:
- *   - `..`, `:`, `~`, `^`, `?`, `*`, `[`, `\`, espacios, control chars
- *   - segmentos que empiecen por `.` o terminen en `.lock`
- * Reemplazamos cualquier no [a-zA-Z0-9_-] por `_`.
- */
-export function snapshotRefForHu(huId) {
-  if (!huId) throw new Error("huId requerido");
-  const safe = String(huId).replaceAll(/[^a-zA-Z0-9_-]/g, "_").slice(0, 80);
-  return REF_PREFIX + safe;
-}
-
-async function defaultRunner(args, opts = {}) {
-  return runCommand("git", args, opts);
-}
-
-/**
- * Crea (o actualiza) el ref del snapshot apuntando al HEAD actual.
- *
- * @param {object} args
- * @param {string} args.projectDir
- * @param {string} args.huId
- * @param {Function} [args.runner] - sustituye git CLI en tests
- * @returns {Promise<{ ok: boolean, ref?: string, sha?: string, error?: string }>}
- */
-export async function createHuSnapshot({ projectDir, huId, runner }) {
-  const run = runner || defaultRunner;
-  const ref = snapshotRefForHu(huId);
-  const head = await run(["rev-parse", "HEAD"], { cwd: projectDir });
-  if (head.exitCode !== 0) {
-    return { ok: false, error: `rev-parse HEAD failed: ${(head.stderr || "").trim()}` };
-  }
-  const sha = (head.stdout || "").trim();
-  if (!sha) return { ok: false, error: "HEAD vacío" };
-  const update = await run(["update-ref", ref, sha], { cwd: projectDir });
-  if (update.exitCode !== 0) {
-    return { ok: false, error: `update-ref falló: ${(update.stderr || "").trim()}` };
-  }
-  return { ok: true, ref, sha };
-}
-
-/**
- * @param {object} args
- * @param {string} args.projectDir
- * @param {string} args.huId
- * @param {Function} [args.runner]
- * @returns {Promise<{ ok: boolean, sha?: string }>}
- */
-export async function hasHuSnapshot({ projectDir, huId, runner }) {
-  const run = runner || defaultRunner;
-  const ref = snapshotRefForHu(huId);
-  const r = await run(["rev-parse", "--verify", "--quiet", ref], { cwd: projectDir });
-  if (r.exitCode !== 0) return { ok: false };
-  return { ok: true, sha: (r.stdout || "").trim() };
-}
-
-/**
- * Restaura el workspace al snapshot. DESTRUCTIVO: hace `git reset --hard`,
- * lo que descarta cambios no committeados. Caller debe avisar al usuario.
- *
- * @returns {Promise<{ ok: boolean, sha?: string, error?: string }>}
- */
-export async function restoreHuSnapshot({ projectDir, huId, runner }) {
-  const run = runner || defaultRunner;
-  const ref = snapshotRefForHu(huId);
-  const has = await hasHuSnapshot({ projectDir, huId, runner: run });
-  if (!has.ok) return { ok: false, error: `snapshot no encontrado para HU ${huId}` };
-  const r = await run(["reset", "--hard", ref], { cwd: projectDir });
-  if (r.exitCode !== 0) {
-    return { ok: false, error: `reset --hard falló: ${(r.stderr || "").trim()}` };
-  }
-  return { ok: true, sha: has.sha };
-}
-
-/**
- * Borra el ref del snapshot. Idempotente: si no existe, devuelve ok:true.
- */
-export async function removeHuSnapshot({ projectDir, huId, runner }) {
-  const run = runner || defaultRunner;
-  const ref = snapshotRefForHu(huId);
-  const r = await run(["update-ref", "-d", ref], { cwd: projectDir });
-  // git update-ref -d devuelve 0 incluso si el ref no existía.
-  if (r.exitCode !== 0) {
-    return { ok: false, error: `update-ref -d falló: ${(r.stderr || "").trim()}` };
-  }
-  return { ok: true };
-}
+// Shim de compatibilidad: hu-snapshot vive ahora en @karajan/core.
+// Mantenemos esta ruta para que callers internos del CLI (orchestrator,
+// runners) sigan funcionando sin tocar imports.
+export {
+  snapshotRefForHu,
+  createHuSnapshot,
+  hasHuSnapshot,
+  restoreHuSnapshot,
+  removeHuSnapshot,
+} from "@karajan/core/hu-snapshot";

package/src/orchestrator/drivers/pre-loop-phases/inject-loaded-plan.js

@@ -302,10 +302,37 @@ function wirePlanCallbacks({ session, loadedPlan, projectDir, syncResultsToPlan,
   // PR3: per-HU outcome. Stamped once per HU at runSingleHu's exit
   // so the board can show the 📄 indicator as soon as each HU
   // finishes (iterations / duration / commits / blockers / summary).
+  //
+  // Cost D (KJC-TSK-0515): the outcome may carry `cost_usd` (USD
+  // spent on this HU). When present and finite, also persist it to
+  // board.db so the per-card badge (Cost F) and the project total
+  // chip (Cost G) have data to show — without this write, the
+  // `cost_usd` column would always stay NULL and the UI would render
+  // nothing. Lazy-import to keep the pre-loop phase free of board
+  // deps until we actually need them.
   setLiveOutcomeUpdater(session, async (huId, outcome) => {
     try {
       if (!setHuOutcomeFn(loadedPlan, huId, outcome)) return;
       await savePlanToDisk(projectDir, loadedPlan);
+      if (outcome && Number.isFinite(outcome.cost_usd)) {
+        try {
+          const { setStoryCost, setStoryCachedTokens } = await import("../../../../packages/hu-board/src/db.js");
+          setStoryCost(huId, outcome.cost_usd);
+          // Φ0-G (KJC-TSK-0525): cached/in tokens travel in the same
+          // outcome blob as cost. Write them together so the board
+          // can render the "🎯 N% cached" badge on the same render.
+          // Either may be null (older runs, no cache) — setter handles it.
+          if (Number.isFinite(outcome.cached_tokens) || Number.isFinite(outcome.tokens_in)) {
+            setStoryCachedTokens(
+              huId,
+              Number.isFinite(outcome.cached_tokens) ? outcome.cached_tokens : null,
+              Number.isFinite(outcome.tokens_in) ? outcome.tokens_in : null,
+            );
+          }
+        } catch (err) {
+          logger?.warn?.(`Cost write failed for ${huId}: ${err.message}`);
+        }
+      }
     } catch (err) {
       logger?.warn?.(`Live outcome update failed for ${huId}: ${err.message}`);
     }

package/src/orchestrator/drivers/run-hu-batch.js

@@ -360,7 +360,11 @@ export async function runHuBatch({ ctx, task, askQuestion, emitter, logger }) {
     onStatusChange: ctx.session?._liveStatusUpdater || null,
     // PR3 (per-HU outcome): same pattern, but for the rich
     // outcome blob written ONCE per HU at the end of runSingleHu.
-    onOutcome: ctx.session?._liveOutcomeUpdater || null
+    onOutcome: ctx.session?._liveOutcomeUpdater || null,
+    // Cost D (KJC-TSK-0515): the sub-pipeline slices BudgetTracker
+    // entries per HU and stamps `outcome.cost_usd` so the board can
+    // show per-HU spend. Without this the tracker is invisible to it.
+    budgetTracker: ctx.budgetTracker || null
   });
 
   emitProgress(emitter, makeEvent("hu:sub-pipeline:end", { ...ctx.eventBase, stage: "hu-sub-pipeline" }, {

package/src/orchestrator/flow-runner.js

@@ -263,15 +263,23 @@ async function _runFlowInner({ task, config, logger, flags = {}, emitter = null,
 
     // --- Telemetry: anonymous pipeline_complete event (non-blocking) ---
     try {
-      const { sendTelemetryEvent } = await import("../utils/telemetry.js");
+      const { sendTelemetryEvent, computeCachedPct } = await import("../utils/telemetry.js");
       const durationS = Math.round((Date.now() - ctx.startedAt) / 1000);
       const sessionStatus = ctx.session?.status || "unknown";
+      // Φ0-H (KJC-TSK-0526): aggregate cache-hit ratios per role so we
+      // can see on the fleet how much each provider's cache is buying.
+      let cachedPct = { cached_pct_coder: null, cached_pct_reviewer: null, cached_pct_total: null };
+      try {
+        const budgetSummary = ctx.budgetTracker?.summary?.();
+        if (budgetSummary) cachedPct = computeCachedPct(budgetSummary);
+      } catch { /* non-blocking — telemetry must never break runs */ }
       sendTelemetryEvent("pipeline_complete", {
         mode: config.review_mode,
         agent: ctx.coderRole?.provider || config.coder,
         duration_s: durationS,
         success: sessionStatus === "approved",
-        taskType: ctx.session?.resolved_policies?.taskType || null
+        taskType: ctx.session?.resolved_policies?.taskType || null,
+        ...cachedPct
       }, config).catch(() => {});
     } catch { /* non-blocking */ }
   }