karajan-code 3.3.0 → 3.4.0

package/README.md

@@ -23,7 +23,7 @@
 
 ---
 
-> **v3.3.0 released** — Cross-provider cache observability (epic KJC-PCS-0056 / Phase 0 closed). Every `kj run` now measures provider-level prompt-cache hits end-to-end across Anthropic, OpenAI/Codex, Gemini, aider and opencode — same `cached_tokens` field flows from agent → BudgetTracker → `summary.md` → `board.db` → HU Board badge `🎯 N%` → telemetry `pipeline_complete`. Real data: Claude cold→hot 47.2% → 94.3% cache_pct (**76.4% cost savings on a single HU**), Gemini 87.9% → 96.8%. Null-safe: badge hides when unmeasured. Drop-in upgrade from v3.2.0. Full notes in [CHANGELOG.md](CHANGELOG.md).
+> **v3.4.0 released** — Cache-friendly prompts (epic KJC-PCS-0057 / Phase 1 closed). Every Karajan prompt is now split into a stable block (identical across iterations and HUs, rendered first so automatic prefix caching hits on it) and a volatile tail; on Claude the stable block ships via `--append-system-prompt` so the CLI's cache breakpoints serve it from cache on every call. Real data: cold-run cache_pct jumps **47.2% → 99.6%** and coder cost drops **76%** ($0.61 → $0.14 per HU). A prefix-stability regression suite freezes the contract in CI. Drop-in upgrade from v3.3.0. Full notes in [CHANGELOG.md](CHANGELOG.md).
 
 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.
 

package/node_modules/@karajan/core/README.md

@@ -0,0 +1,42 @@
+# @karajan/core
+
+Shared modules for the Karajan Code CLI and `@karajan/hu-board`. Private
+workspace package — not published to npm.
+
+## Scope
+
+`@karajan/core` is the extraction destination for code that both the CLI
+package (`karajan-code`) and the HU Board package (`@karajan/hu-board`)
+need. Today it ships the atomic JSON writer; subsequent commits of
+KJC-TSK-0511 will land the shared paths, port-check, run-registry,
+process runner, plan validation, vector store, and plan/HU ops modules
+here.
+
+## Exports
+
+| Subpath | Module |
+| --- | --- |
+| `@karajan/core/atomic-write` | `writeJsonAtomic`, `writeJsonAtomicSync` |
+| `@karajan/core/shared-paths` | `SHARED_DIR_NAME`, `getSharedRoot`, `getSharedPlansDir`, `getSharedHuStoriesDir`, `isSharedPath` |
+| `@karajan/core/port-check` | `isPortAvailable`, `findAvailablePort` |
+| `@karajan/core/paths` | `resolveHome`, `getKarajanHome`, `getSessionRoot`, `getSonarComposePath`, `getOllamaComposePath`, `getWebperfDir`, `getRunsDir`, `getPromptsDir`, `__resetKjHomeWarningForTests` |
+| `@karajan/core/run-registry` | `runsDir`, `registerRun`, `unregisterRun`, `listActiveRuns` |
+| `@karajan/core/vec-store` | `dbPath`, `openVecStore`, `insertChunk`, `searchSimilar`, `searchBM25`, `projectSlug`, `deleteChunksBySource`, `findChunkByHash`, `getEmbeddingsByIds`, `getLastIndexedCommit`, `setLastIndexedCommit`, `countChunks` |
+| `@karajan/core/plan-id` | `generatePlanId`, `generateHuId`, `normaliseAlias` |
+| `@karajan/core/plan-hu-ops` | `addHu`, `removeHu`, `updateHu`, `updateHuStatus`, `setHuOutcome`, `setPlanOutcome`, `autoCertifyPendingHus`, `assertPlanRunnable`, `computePlanOutcome`, `certifyAllHus`, `reorderHus` |
+| `@karajan/core/plan-validation` | `validateBlockedByChange` |
+| `@karajan/core/process` | `runCommand` (execa wrapper with output streaming, silence/total timeouts, ENOENT enrichment) |
+| `@karajan/core/hu-snapshot` | `snapshotRefForHu`, `createHuSnapshot`, `hasHuSnapshot`, `restoreHuSnapshot`, `removeHuSnapshot` |
+| `@karajan/core/standby-store` | `persistStandby`, `loadStandby`, `listPendingStandby`, `markStandbyDone`, `acquireStandbyLock`, `buildStandbyState`, `standbyDir`, `standbyDoneDir` |
+| `@karajan/core/standby-scheduler` | `scheduleResume`, `cancelScheduled`, `reconcileAll`, `acquireStandbyLock`, `markStandbyDone`, `_resetScheduledForTests` |
+
+The root export (`@karajan/core`) re-exports everything via the barrel
+in `src/index.js`, but prefer the subpath form so the bundler can
+tree-shake unused modules.
+
+## Status
+
+KJC-TSK-0511 PR8 — `standby-store` + `standby-scheduler` extracted.
+With this PR `@karajan/hu-board` no longer reaches into `../../../src`
+from any static **or dynamic** import. PR9 will re-add
+`packages/hu-board` to the root `workspaces` array.

package/node_modules/@karajan/core/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@karajan/core",
+  "version": "0.1.0",
+  "description": "Shared modules for Karajan Code CLI and @karajan/hu-board (atomic-write, paths, RAG store, plan ops, process runner).",
+  "type": "module",
+  "private": true,
+  "engines": {
+    "node": ">=22.22.1"
+  },
+  "exports": {
+    "./atomic-write": "./src/atomic-write.js",
+    "./shared-paths": "./src/shared-paths.js",
+    "./port-check": "./src/port-check.js",
+    "./paths": "./src/paths.js",
+    "./run-registry": "./src/run-registry.js",
+    "./vec-store": "./src/vec-store.js",
+    "./plan-id": "./src/plan-id.js",
+    "./plan-hu-ops": "./src/plan-hu-ops.js",
+    "./plan-validation": "./src/plan-validation.js",
+    "./process": "./src/process.js",
+    "./hu-snapshot": "./src/hu-snapshot.js",
+    "./standby-store": "./src/standby-store.js",
+    "./standby-scheduler": "./src/standby-scheduler.js",
+    "./pricing": "./src/pricing/index.js",
+    "./cost": "./src/cost/index.js"
+  },
+  "scripts": {
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "better-sqlite3": "^12.10.0",
+    "execa": "^9.6.0",
+    "sqlite-vec": "^0.1.9"
+  },
+  "devDependencies": {
+    "vitest": "^4.0.0"
+  }
+}

package/node_modules/@karajan/core/src/atomic-write.js

@@ -0,0 +1,43 @@
+// Atomic JSON writes for persistent state (resilience audit, Phase 2).
+//
+// A plain `writeFile(path, JSON.stringify(...))` truncates the live file
+// before the new content lands. If the process is killed mid-write
+// (SIGKILL, crash, power loss) the file is left truncated and the only
+// good copy is already gone — the plan / session / standby JSON
+// silently corrupts.
+//
+// write-temp + rename fixes it: `rename` is atomic on the same
+// filesystem, so a reader sees either the old file or the complete new
+// one, never a half-written one. The temp file sits next to the target
+// (same dir → same FS) and is uniquely named so concurrent writers do
+// not clobber each other's temp. A crash before the rename leaves an
+// orphan `.tmp` but never a corrupt target.
+
+import { writeFileSync, renameSync } from "node:fs";
+import { writeFile, rename } from "node:fs/promises";
+
+function tempPath(target) {
+  return `${target}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}.tmp`;
+}
+
+/**
+ * Atomically write `obj` as pretty JSON to `target` (synchronous).
+ * @param {string} target - destination path; its directory must exist
+ * @param {unknown} obj
+ */
+export function writeJsonAtomicSync(target, obj) {
+  const tmp = tempPath(target);
+  writeFileSync(tmp, JSON.stringify(obj, null, 2), "utf-8");
+  renameSync(tmp, target);
+}
+
+/**
+ * Atomically write `obj` as pretty JSON to `target` (async).
+ * @param {string} target - destination path; its directory must exist
+ * @param {unknown} obj
+ */
+export async function writeJsonAtomic(target, obj) {
+  const tmp = tempPath(target);
+  await writeFile(tmp, JSON.stringify(obj, null, 2), "utf-8");
+  await rename(tmp, target);
+}

package/node_modules/@karajan/core/src/cost/index.js

@@ -0,0 +1,102 @@
+/**
+ * Cost aggregator (Cost B — KJC-TSK-0513).
+ *
+ * Turns a list of token-usage events emitted by the orchestrator into
+ * a USD breakdown for a single run / HU. The pipeline calls this once
+ * when a HU finishes; the result is what Cost C will persist in
+ * board.db and Cost E will expose as `/api/projects/:id/cost`.
+ *
+ * Inputs are deliberately permissive: any extra field on an event is
+ * ignored. We only require `role`, `model`, `tokensIn`, `tokensOut`.
+ *
+ * Unknown models do NOT throw. Their token counts accumulate into
+ * `unknownModelTokens` and the function returns a flag so the caller
+ * can surface it in the UI (orange badge instead of `$X.XXXX`).
+ */
+
+import { getModelPricing } from "../pricing/index.js";
+
+const DEFAULT_ROUND_DECIMALS = 4;
+
+function round(n, decimals = DEFAULT_ROUND_DECIMALS) {
+  const f = 10 ** decimals;
+  return Math.round(n * f) / f;
+}
+
+function priceTokens(pricing, tokensIn, tokensOut) {
+  const inUsd = (tokensIn / 1_000_000) * pricing.inputPerMTok;
+  const outUsd = (tokensOut / 1_000_000) * pricing.outputPerMTok;
+  return inUsd + outUsd;
+}
+
+/**
+ * Aggregate cost of a run.
+ *
+ * @param {object} args
+ * @param {Array<{role:string, model:string, tokensIn:number, tokensOut:number}>} args.events
+ * @param {(level:"warn"|"info", msg:string, ctx?:object)=>void} [args.logger]
+ *        Optional structured logger. When a model is unknown we call
+ *        logger("warn", ...) so the user sees it once per run.
+ * @returns {{
+ *   totalUsd:number,
+ *   byRole:Record<string,number>,
+ *   byModel:Record<string,number>,
+ *   unknownModelTokens:{ tokensIn:number, tokensOut:number, models:string[] },
+ *   hasUnknown:boolean,
+ *   currency:string
+ * }}
+ */
+export function aggregateRunCost({ events, logger } = {}) {
+  const safeEvents = Array.isArray(events) ? events : [];
+  const byRole = {};
+  const byModel = {};
+  const unknownModels = new Set();
+  let totalUsd = 0;
+  let unknownIn = 0;
+  let unknownOut = 0;
+
+  for (const ev of safeEvents) {
+    if (!ev || typeof ev !== "object") continue;
+    const role = typeof ev.role === "string" && ev.role.length > 0 ? ev.role : "unknown";
+    const model = typeof ev.model === "string" ? ev.model : "";
+    const tokensIn = Number.isFinite(ev.tokensIn) ? ev.tokensIn : 0;
+    const tokensOut = Number.isFinite(ev.tokensOut) ? ev.tokensOut : 0;
+    if (tokensIn === 0 && tokensOut === 0) continue;
+
+    const pricing = getModelPricing(model);
+    if (!pricing) {
+      unknownIn += tokensIn;
+      unknownOut += tokensOut;
+      if (model.length > 0) unknownModels.add(model);
+      if (typeof logger === "function") {
+        logger("warn", "cost-aggregator: unknown model pricing", { model, role, tokensIn, tokensOut });
+      }
+      continue;
+    }
+
+    const cost = priceTokens(pricing, tokensIn, tokensOut);
+    totalUsd += cost;
+    byRole[role] = (byRole[role] || 0) + cost;
+    byModel[model] = (byModel[model] || 0) + cost;
+  }
+
+  const roundedByRole = Object.fromEntries(
+    Object.entries(byRole).map(([k, v]) => [k, round(v)])
+  );
+  const roundedByModel = Object.fromEntries(
+    Object.entries(byModel).map(([k, v]) => [k, round(v)])
+  );
+
+  return {
+    totalUsd: round(totalUsd),
+    byRole: roundedByRole,
+    byModel: roundedByModel,
+    unknownModelTokens: {
+      tokensIn: unknownIn,
+      tokensOut: unknownOut,
+      models: Array.from(unknownModels).sort(),
+    },
+    hasUnknown: unknownIn > 0 || unknownOut > 0,
+    currency: "USD",
+  };
+}

package/node_modules/@karajan/core/src/hu-snapshot.js

@@ -0,0 +1,105 @@
+// 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 "./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 };
+}

package/node_modules/@karajan/core/src/index.js

@@ -0,0 +1,18 @@
+// Barrel export for @karajan/core. Subpath imports
+// (e.g. `@karajan/core/atomic-write`) are the preferred shape — this
+// barrel only exists so a single `import { writeJsonAtomic } from
+// "@karajan/core"` keeps working for callers that want the whole API.
+
+export * from "./atomic-write.js";
+export * from "./shared-paths.js";
+export * from "./port-check.js";
+export * from "./paths.js";
+export * from "./run-registry.js";
+export * from "./vec-store.js";
+export * from "./plan-id.js";
+export * from "./plan-hu-ops.js";
+export * from "./plan-validation.js";
+export * from "./process.js";
+export * from "./hu-snapshot.js";
+export * from "./standby-store.js";
+export * from "./standby-scheduler.js";

package/node_modules/@karajan/core/src/paths.js

@@ -0,0 +1,123 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+// Per-process vitest root. We memoise the *root* (not the suffixed
+// `.karajan` / `.kj` path) so callers with different legacy defaults
+// — plan-store wants `.kj`, db.js wants `.karajan` — can share one
+// random tmp prefix per test run without colliding.
+let _vitestRoot = null;
+function vitestRoot() {
+  if (_vitestRoot) return _vitestRoot;
+  _vitestRoot = path.join(
+    os.tmpdir(),
+    `karajan-vitest-${process.pid}-${Math.random().toString(36).slice(2, 10)}`
+  );
+  // KJC-BUG-0075: clean up on clean exit so /tmp doesn't accumulate one
+  // dir per fork × run. `process.on('exit')` runs synchronously and only
+  // for graceful exits — SIGKILL leaks survive but are caught by the
+  // global-setup mtime purge at the start of the next run.
+  process.on("exit", () => {
+    try {
+      fs.rmSync(_vitestRoot, { recursive: true, force: true });
+    } catch {
+      // best-effort: never crash a test process on cleanup failure
+    }
+  });
+  return _vitestRoot;
+}
+
+function vitestTmpHome(defaultSegment) {
+  return path.join(vitestRoot(), defaultSegment);
+}
+
+// One-shot warning so users with KJ_HOME set in their shell rcfile do
+// not get spammed once per `kj` invocation. Reset across processes,
+// which is the granularity that matters for a humans-reading-stderr
+// audience.
+let _kjHomeWarned = false;
+function emitKjHomeDeprecationWarning() {
+  if (_kjHomeWarned) return;
+  _kjHomeWarned = true;
+  // eslint-disable-next-line no-console
+  console.warn(
+    "\x1b[33m[warn]\x1b[0m KJ_HOME is deprecated, rename to KARAJAN_HOME (KJ_HOME will be removed in a future release)"
+  );
+}
+
+/**
+ * Unified resolver for Karajan's HOME-level storage root. Used by every
+ * helper that previously rolled its own `getKjHome()` with subtly
+ * different defaults and VITEST handling.
+ *
+ * Precedence (highest first):
+ *   1. KARAJAN_HOME env var — explicit, no warning
+ *   2. KJ_HOME env var      — explicit, prints deprecation warning once
+ *   3. VITEST tmp dir       — auto-isolation under `os.tmpdir()/karajan-vitest-<pid>-<rand>/<defaultSegment>`
+ *   4. `~/<defaultSegment>` — production default
+ *
+ * Callers pass `defaultSegment` so we can preserve `.kj` for legacy
+ * paths (plan-store, standby-store) and `.karajan` for the canonical
+ * root, until PR 3 unifies the defaults too.
+ *
+ * @param {object} [options]
+ * @param {string} [options.defaultSegment=".karajan"]  HOME subdir name
+ * @returns {string} absolute path
+ */
+export function resolveHome({ defaultSegment = ".karajan" } = {}) {
+  if (process.env.KARAJAN_HOME) {
+    return path.resolve(process.env.KARAJAN_HOME);
+  }
+  if (process.env.KJ_HOME) {
+    emitKjHomeDeprecationWarning();
+    return path.resolve(process.env.KJ_HOME);
+  }
+  if (process.env.VITEST) {
+    return vitestTmpHome(defaultSegment);
+  }
+  return path.join(os.homedir(), defaultSegment);
+}
+
+/**
+ * Canonical Karajan home (`~/.karajan` by default). Every helper that
+ * used to roll its own `getKjHome()` now goes through this one — see
+ * KJC-PCS-0047 PR 3 for the consolidation.
+ */
+export function getKarajanHome() {
+  return resolveHome({ defaultSegment: ".karajan" });
+}
+
+// Test-only export. Tests that depend on observing the deprecation
+// warning being emitted exactly once need to reset the latch between
+// cases.
+export function __resetKjHomeWarningForTests() {
+  _kjHomeWarned = false;
+}
+
+export function getSessionRoot() {
+  return path.join(getKarajanHome(), "sessions");
+}
+
+export function getSonarComposePath() {
+  return path.join(getKarajanHome(), "docker-compose.sonar.yml");
+}
+
+/** Ollama RAG embedder compose: `<karajan-home>/docker-compose.ollama.yml` — KJC-TSK-0435. */
+export function getOllamaComposePath() {
+  return path.join(getKarajanHome(), "docker-compose.ollama.yml");
+}
+
+/** Webperf cache: `<karajan-home>/webperf/` — KJC-TSK-0420. */
+export function getWebperfDir() {
+  return path.join(getKarajanHome(), "webperf");
+}
+
+/** Run-registry: `<karajan-home>/runs/` — KJC-TSK-0420. */
+export function getRunsDir() {
+  return path.join(getKarajanHome(), "runs");
+}
+
+/** Board prompt bridge: `<karajan-home>/prompts/` — KJC-TSK-0420. */
+export function getPromptsDir() {
+  return path.join(getKarajanHome(), "prompts");
+}