karajan-code 3.4.0 → 3.4.2

package/README.md

@@ -23,7 +23,7 @@
 
 ---
 
-> **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).
+> **v3.4.2 released** — Hotfix: `npm install karajan-code@3.4.1` crashed at `kj --version` because the bundled `@karajan/core` dragged in `sqlite-vec` (which ships `files: []`) without its entry point. `@karajan/core`'s runtime deps are now `peerDependencies`, so they resolve complete from the consumer's top-level install. Clean install verified end-to-end. 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/package.json

@@ -27,11 +27,22 @@
   "scripts": {
     "test": "vitest run"
   },
-  "dependencies": {
+  "peerDependencies": {
     "better-sqlite3": "^12.10.0",
     "execa": "^9.6.0",
     "sqlite-vec": "^0.1.9"
   },
+  "peerDependenciesMeta": {
+    "better-sqlite3": {
+      "optional": true
+    },
+    "execa": {
+      "optional": true
+    },
+    "sqlite-vec": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "vitest": "^4.0.0"
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "3.4.0",
+  "version": "3.4.2",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",
@@ -71,7 +71,9 @@
     "typecheck": "npx -p typescript@5 tsc --noEmit -p tsconfig.json",
     "validate": "npm run lint && npm run lint:syntax && npm test",
     "mcp": "node src/mcp/server.js",
-    "audit:test-diet": "node scripts/audit-test-diet.mjs"
+    "audit:test-diet": "node scripts/audit-test-diet.mjs",
+    "verify-pack": "node scripts/verify-pack.mjs",
+    "prepublishOnly": "node scripts/verify-pack.mjs"
   },
   "simple-git-hooks": {
     "pre-commit": "npx lint-staged"

package/packages/hu-board/src/routes/api.js

@@ -1,5 +1,26 @@
 import { Router } from 'express';
 import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+
+/** Async existence probe (KJC-TSK-0539 — no sync fs in handlers). */
+const pathExists = (p) => fsp.access(p).then(() => true, () => false);
+
+/**
+ * mtime-keyed cache for parsed plan JSON (KJC-TSK-0539). The plan scans
+ * used to re-read and re-parse every plan file on EVERY request; with N
+ * plans and the board polling, that was O(N) parses per poll. The cache
+ * serves the parsed object while the file's mtime is unchanged and
+ * re-reads transparently when kj writes the plan.
+ */
+const planFileCache = new Map();
+export async function readPlanCached(p) {
+  const { mtimeMs } = await fsp.stat(p);
+  const hit = planFileCache.get(p);
+  if (hit && hit.mtimeMs === mtimeMs) return hit.plan;
+  const plan = JSON.parse(await fsp.readFile(p, 'utf8'));
+  planFileCache.set(p, { mtimeMs, plan });
+  return plan;
+}
 import os from 'node:os';
 import path from 'node:path';
 import { spawn as spawnChild } from 'node:child_process';
@@ -74,10 +95,10 @@ function huStoriesDir() {
 /**
  * Best-effort removal of the hu-stories/<id>/ directory.
  */
-function removeBatchDir(batchId) {
+async function removeBatchDir(batchId) {
   try {
     const dir = path.join(huStoriesDir(), batchId);
-    fs.rmSync(dir, { recursive: true, force: true });
+    await fsp.rm(dir, { recursive: true, force: true });
     return true;
   } catch {
     return false;
@@ -207,10 +228,10 @@ router.get('/projects/:id/preflight', async (req, res) => {
     try {
       outer: for (const root of getHuBoardPlansDirs()) {
         const plansDir = path.join(root, projectId);
-        if (!fs.existsSync(plansDir)) continue;
-        for (const f of fs.readdirSync(plansDir).filter((x) => x.endsWith('.json'))) {
+        if (!(await pathExists(plansDir))) continue;
+        for (const f of (await fsp.readdir(plansDir)).filter((x) => x.endsWith('.json'))) {
           try {
-            const plan = JSON.parse(fs.readFileSync(path.join(plansDir, f), 'utf8'));
+            const plan = await readPlanCached(path.join(plansDir, f));
             if (plan?.projectDir) { projectDir = plan.projectDir; break outer; }
           } catch { /* try next file */ }
         }
@@ -231,7 +252,7 @@ router.get('/projects/:id/preflight', async (req, res) => {
  * failed · 15 min" banner. Plans that haven't finished yet have a
  * null outcome — the front handles that by hiding the banner.
  */
-router.get('/projects/:id/plans-outcome', (req, res) => {
+router.get('/projects/:id/plans-outcome', async (req, res) => {
   try {
     const projectId = req.params.id;
     // KJC-BUG-0059 (v2.19.3): scan canonical + legacy roots so users
@@ -239,10 +260,10 @@ router.get('/projects/:id/plans-outcome', (req, res) => {
     const out = [];
     for (const root of getHuBoardPlansDirs()) {
       const plansDir = path.join(root, projectId);
-      if (!fs.existsSync(plansDir)) continue;
-      for (const f of fs.readdirSync(plansDir).filter(n => n.endsWith('.json'))) {
+      if (!(await pathExists(plansDir))) continue;
+      for (const f of (await fsp.readdir(plansDir)).filter(n => n.endsWith('.json'))) {
         try {
-          const plan = JSON.parse(fs.readFileSync(path.join(plansDir, f), 'utf8'));
+          const plan = await readPlanCached(path.join(plansDir, f));
           if (plan?.version !== 2) continue;
           out.push({
           planId: plan.planId,
@@ -363,7 +384,7 @@ router.get('/sessions', (_req, res) => {
  * Also removes the hu-stories/<id>/ directory from disk so the next sync
  * does not re-import it.
  */
-router.delete('/projects/:id', (req, res) => {
+router.delete('/projects/:id', async (req, res) => {
   try {
     const id = req.params.id;
     // Gather filesystem paths to remove BEFORE deleting DB rows so we
@@ -397,7 +418,7 @@ router.delete('/projects/:id', (req, res) => {
     // Best-effort fs cleanup; failure does NOT undo the tombstones.
     let pathsRemoved = 0;
     for (const p of fsPaths) {
-      try { fs.rmSync(p, { recursive: true, force: true }); pathsRemoved++; } catch { /* */ }
+      try { await fsp.rm(p, { recursive: true, force: true }); pathsRemoved++; } catch { /* */ }
     }
     res.json({ deleted: true, pathsRemoved, tombstoned: 1 + storyIds.length + sessionIds.length });
   } catch (err) {
@@ -411,7 +432,7 @@ router.delete('/projects/:id', (req, res) => {
  * prompt id so a stale chokidar event can't recreate it, and emits a
  * `prompt:resolved` event so all open boards close the modal.
  */
-router.delete('/prompts/:promptId', (req, res) => {
+router.delete('/prompts/:promptId', async (req, res) => {
   try {
     const promptId = req.params.promptId;
     const dir = promptsDir();
@@ -419,7 +440,7 @@ router.delete('/prompts/:promptId', (req, res) => {
     const answer = path.join(dir, `${promptId}.answer.json`);
     let removed = 0;
     for (const p of [main, answer]) {
-      try { fs.unlinkSync(p); removed++; } catch { /* missing is fine */ }
+      try { await fsp.unlink(p); removed++; } catch { /* missing is fine */ }
     }
     addTombstone('prompt', promptId, { source: 'api', fsPaths: [main, answer] });
     // Re-use the same event the runner emits when answered, so any open
@@ -439,7 +460,7 @@ router.delete('/prompts/:promptId', (req, res) => {
  * it. Pre-tombstones this endpoint was a DB-only soft hide that the next
  * chokidar event undid silently.
  */
-router.delete('/stories/:id', (req, res) => {
+router.delete('/stories/:id', async (req, res) => {
   try {
     const id = req.params.id;
     const dir = path.join(huStoriesDir(), id);
@@ -447,7 +468,7 @@ router.delete('/stories/:id', (req, res) => {
     if (!ok) return res.status(404).json({ error: 'Story not found' });
     addTombstone('story', id, { source: 'api', fsPaths: [dir] });
     let dirRemoved = false;
-    try { fs.rmSync(dir, { recursive: true, force: true }); dirRemoved = true; } catch { /* */ }
+    try { await fsp.rm(dir, { recursive: true, force: true }); dirRemoved = true; } catch { /* */ }
     res.json({ deleted: true, dirRemoved });
   } catch (err) {
     res.status(500).json({ error: err.message });
@@ -459,7 +480,7 @@ router.delete('/stories/:id', (req, res) => {
  *
  * Tombstones + removes `~/.karajan/sessions/<id>/` (KJC-TSK-0380).
  */
-router.delete('/sessions/:id', (req, res) => {
+router.delete('/sessions/:id', async (req, res) => {
   try {
     const id = req.params.id;
     const dir = path.join(getKjHome(), 'sessions', id);
@@ -467,7 +488,7 @@ router.delete('/sessions/:id', (req, res) => {
     if (!ok) return res.status(404).json({ error: 'Session not found' });
     addTombstone('session', id, { source: 'api', fsPaths: [dir] });
     let dirRemoved = false;
-    try { fs.rmSync(dir, { recursive: true, force: true }); dirRemoved = true; } catch { /* */ }
+    try { await fsp.rm(dir, { recursive: true, force: true }); dirRemoved = true; } catch { /* */ }
     res.json({ deleted: true, dirRemoved });
   } catch (err) {
     res.status(500).json({ error: err.message });
@@ -482,7 +503,7 @@ router.delete('/sessions/:id', (req, res) => {
  * delete the project: a project can have multiple plans, deleting one
  * plan only removes that plan's HUs from the board.
  */
-router.delete('/plans/:planId', (req, res) => {
+router.delete('/plans/:planId', async (req, res) => {
   try {
     const planId = req.params.planId;
     // Locate the plan file by scanning both canonical and legacy plans
@@ -492,15 +513,15 @@ router.delete('/plans/:planId', (req, res) => {
     let foundPath = null;
     try {
       outer: for (const plansRoot of getHuBoardPlansDirs()) {
-        if (!fs.existsSync(plansRoot)) continue;
-        for (const projSlug of fs.readdirSync(plansRoot)) {
+        if (!(await pathExists(plansRoot))) continue;
+        for (const projSlug of await fsp.readdir(plansRoot)) {
           const candidate = path.join(plansRoot, projSlug, `plan-${planId}.json`);
-          if (fs.existsSync(candidate)) { foundPath = candidate; break outer; }
+          if (await pathExists(candidate)) { foundPath = candidate; break outer; }
         }
       }
     } catch { /* plansRoot missing */ }
     addTombstone('plan', planId, { source: 'api', fsPaths: foundPath ? [foundPath] : [] });
-    if (foundPath) { try { fs.unlinkSync(foundPath); } catch { /* */ } }
+    if (foundPath) { try { await fsp.unlink(foundPath); } catch { /* */ } }
     res.json({ deleted: true, fileRemoved: !!foundPath });
   } catch (err) {
     res.status(500).json({ error: err.message });
@@ -770,11 +791,11 @@ function promptsDir() {
 // Solomon escalation; anything older is a crashed runner.
 const PROMPT_ZOMBIE_TTL_MS = 30 * 60 * 1000;
 
-router.get('/prompts', (_req, res) => {
+router.get('/prompts', async (_req, res) => {
   try {
     const dir = promptsDir();
-    if (!fs.existsSync(dir)) return res.json([]);
-    const entries = fs.readdirSync(dir);
+    if (!(await pathExists(dir))) return res.json([]);
+    const entries = await fsp.readdir(dir);
     const result = [];
     const now = Date.now();
     for (const name of entries) {
@@ -784,21 +805,21 @@ router.get('/prompts', (_req, res) => {
       const answerPath = path.join(dir, `${promptId}.answer.json`);
       // KJC-TSK-0380 — skip tombstoned prompts and clean their files.
       if (isTombstonedFn('prompt', promptId)) {
-        try { fs.unlinkSync(mainPath); } catch { /* */ }
-        try { fs.unlinkSync(answerPath); } catch { /* */ }
+        try { await fsp.unlink(mainPath); } catch { /* */ }
+        try { await fsp.unlink(answerPath); } catch { /* */ }
         continue;
       }
       let parsed;
       try {
-        parsed = JSON.parse(fs.readFileSync(mainPath, 'utf-8'));
+        parsed = JSON.parse(await fsp.readFile(mainPath, 'utf-8'));
       } catch { continue; /* malformed — skip */ }
       // KJC-BUG-0038: zombie detection. Prefer parsed.createdAt; fall back
       // to mtime if the runner skipped the timestamp (older formats).
       const createdMs = Date.parse(parsed?.createdAt || '');
-      const ageRef = Number.isFinite(createdMs) ? createdMs : safeMtime(mainPath);
+      const ageRef = Number.isFinite(createdMs) ? createdMs : await safeMtime(mainPath);
       if (ageRef && (now - ageRef) > PROMPT_ZOMBIE_TTL_MS) {
-        try { fs.unlinkSync(mainPath); } catch { /* */ }
-        try { fs.unlinkSync(answerPath); } catch { /* */ }
+        try { await fsp.unlink(mainPath); } catch { /* */ }
+        try { await fsp.unlink(answerPath); } catch { /* */ }
         addTombstone('prompt', promptId, { source: 'zombie-ttl', fsPaths: [mainPath, answerPath] });
         continue;
       }
@@ -811,8 +832,8 @@ router.get('/prompts', (_req, res) => {
   }
 });
 
-function safeMtime(p) {
-  try { return fs.statSync(p).mtimeMs; } catch { return 0; }
+async function safeMtime(p) {
+  try { return (await fsp.stat(p)).mtimeMs; } catch { return 0; }
 }
 
 /**
@@ -821,20 +842,20 @@ function safeMtime(p) {
  * it, deletes both files, and resolves askQuestion. An answer of
  * "stop" tells the runner to abort the session.
  */
-router.post('/prompts/:promptId/answer', (req, res) => {
+router.post('/prompts/:promptId/answer', async (req, res) => {
   try {
     const { answer } = req.body || {};
     if (typeof answer !== 'string') {
       return res.status(400).json({ error: 'Body must contain an "answer" string' });
     }
     const dir = promptsDir();
-    fs.mkdirSync(dir, { recursive: true });
+    await fsp.mkdir(dir, { recursive: true });
     const promptPath = path.join(dir, `${req.params.promptId}.json`);
-    if (!fs.existsSync(promptPath)) {
+    if (!(await pathExists(promptPath))) {
       return res.status(404).json({ error: `Prompt not found: ${req.params.promptId}` });
     }
     const answerPath = path.join(dir, `${req.params.promptId}.answer.json`);
-    fs.writeFileSync(
+    await fsp.writeFile(
       answerPath,
       JSON.stringify({ answer, answeredAt: new Date().toISOString() }, null, 2),
       'utf-8'
@@ -912,14 +933,14 @@ router.get('/events', (req, res) => {
  * Path is the same one that `runPlan` wrote to:
  *   ~/.karajan/hu-board-runs/<planId>.log (honours KJ_HOME in tests).
  */
-router.get('/plans/:planId/log', (req, res) => {
+router.get('/plans/:planId/log', async (req, res) => {
   try {
     const runsDir = getHuBoardRunsDir(); // KJC-TSK-0421
     const logPath = path.join(runsDir, `${req.params.planId}.log`);
-    if (!fs.existsSync(logPath)) {
+    if (!(await pathExists(logPath))) {
       return res.json({ exists: false, size: 0, content: '' });
     }
-    const stat = fs.statSync(logPath);
+    const stat = await fsp.stat(logPath);
     const offset = Math.max(0, Math.min(stat.size, Number(req.query.offset) || 0));
     // Cap per-request read to 1 MiB so a huge log can't blow up the
     // response. The client will keep polling and catch up.
@@ -927,13 +948,13 @@ router.get('/plans/:planId/log', (req, res) => {
     const length = Math.min(MAX_READ, stat.size - offset);
     let content = '';
     if (length > 0) {
-      const fd = fs.openSync(logPath, 'r');
+      const fh = await fsp.open(logPath, 'r');
       try {
         const buf = Buffer.alloc(length);
-        fs.readSync(fd, buf, 0, length, offset);
+        await fh.read(buf, 0, length, offset);
         content = buf.toString('utf-8');
       } finally {
-        fs.closeSync(fd);
+        await fh.close();
       }
     }
     res.json({ exists: true, size: stat.size, content });
@@ -1230,26 +1251,26 @@ router.post('/runs/:planId/stop', async (req, res) => {
   }
 });
 
-router.get('/runs/:commandId/log', (req, res) => {
+router.get('/runs/:commandId/log', async (req, res) => {
   try {
     const runsDir = getHuBoardRunsDir(); // KJC-TSK-0421
     const logPath = path.join(runsDir, `${req.params.commandId}.log`);
-    if (!fs.existsSync(logPath)) {
+    if (!(await pathExists(logPath))) {
       return res.json({ exists: false, size: 0, content: '' });
     }
-    const stat = fs.statSync(logPath);
+    const stat = await fsp.stat(logPath);
     const offset = Math.max(0, Math.min(stat.size, Number(req.query.offset) || 0));
     const MAX_READ = 1024 * 1024;
     const length = Math.min(MAX_READ, stat.size - offset);
     let content = '';
     if (length > 0) {
-      const fd = fs.openSync(logPath, 'r');
+      const fh = await fsp.open(logPath, 'r');
       try {
         const buf = Buffer.alloc(length);
-        fs.readSync(fd, buf, 0, length, offset);
+        await fh.read(buf, 0, length, offset);
         content = buf.toString('utf-8');
       } finally {
-        fs.closeSync(fd);
+        await fh.close();
       }
     }
     res.json({ exists: true, size: stat.size, content });

package/packages/hu-board/src/zombie-reaper.js

@@ -130,7 +130,7 @@ export function appendZombieCheckpoint(existingJson, reason, isoTimestamp) {
  * @returns {string}
  */
 import { getKjHome } from "./db.js";
-export function getSessionsDir() {
+function getSessionsDir() {
   return path.join(getKjHome(), "sessions");
 }
 

package/scripts/verify-pack.mjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+/**
+ * Pre-publish tarball smoke gate (KJC-TSK-0553).
+ *
+ * WHY: the test suite runs against the linked workspace, where
+ * `@karajan/core` and its deps resolve via symlink — so a broken
+ * PUBLISHED artifact (bundleDependencies dragging in sqlite-vec without
+ * its entry point, KJC-BUG-0082 / 0086) passed CI yet failed on every
+ * clean `npm install`. v3.2.0, v3.3.0 and v3.4.1 all shipped unable to
+ * run even `kj --version`.
+ *
+ * WHAT: pack the real tarball, install it into an isolated tmpdir
+ * (outside the repo, with CLAUDECODE stripped), and assert the binary
+ * actually starts and its native-ish deps resolve. Exit non-zero on any
+ * failure so `prepublishOnly` aborts the publish and CI blocks the PR.
+ *
+ * `npm pack` fires prepack/postpack, NOT prepublishOnly — so invoking
+ * this from prepublishOnly does not recurse.
+ */
+
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const pkg = JSON.parse(fs.readFileSync(path.join(repoRoot, "package.json"), "utf8"));
+const expectedVersion = pkg.version;
+
+// Subprocess env: strip CLAUDECODE (Claude Code blocks nested non-interactive
+// runs otherwise) and force a non-interactive, quiet npm.
+const { CLAUDECODE: _omit, ...cleanEnv } = process.env;
+const childEnv = { ...cleanEnv, npm_config_yes: "true", CI: "1" };
+
+function run(cmd, args, opts = {}) {
+  return execFileSync(cmd, args, {
+    encoding: "utf8",
+    env: childEnv,
+    stdio: ["ignore", "pipe", "pipe"],
+    ...opts,
+  });
+}
+
+function fail(msg, detail) {
+  console.error(`\n✗ verify-pack: ${msg}`);
+  if (detail) console.error(String(detail).split("\n").slice(0, 20).join("\n"));
+  process.exit(1);
+}
+
+let tgzPath = null;
+let tmpDir = null;
+try {
+  console.log(`verify-pack: packing karajan-code@${expectedVersion}…`);
+  // --json gives us the exact filename without parsing human output.
+  const packOut = run("npm", ["pack", "--json", "--silent"], { cwd: repoRoot });
+  const filename = JSON.parse(packOut)[0]?.filename;
+  if (!filename) fail("npm pack did not report a filename", packOut);
+  // npm normalizes scoped names in --json but karajan-code is unscoped;
+  // the file lands in cwd under the reported name.
+  tgzPath = path.join(repoRoot, filename);
+  if (!fs.existsSync(tgzPath)) fail(`packed tarball not found at ${tgzPath}`);
+
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "kj-verify-pack-"));
+  console.log(`verify-pack: installing the tarball into ${tmpDir} (clean, isolated)…`);
+  run("npm", ["install", tgzPath, "--no-audit", "--no-fund", "--silent", "--prefix", tmpDir], {
+    cwd: tmpDir,
+  });
+
+  const binPath = path.join(tmpDir, "node_modules", ".bin", "kj");
+  if (!fs.existsSync(binPath)) fail(`kj binary missing after install: ${binPath}`);
+
+  // 1. kj --version must start AND report the version we just packed.
+  let versionOut;
+  try {
+    versionOut = run(binPath, ["--version"]).trim();
+  } catch (err) {
+    fail("`kj --version` crashed on a clean install", err.stderr || err.message);
+  }
+  if (!versionOut.includes(expectedVersion)) {
+    fail(`kj --version returned "${versionOut}", expected ${expectedVersion}`);
+  }
+  console.log(`verify-pack: kj --version → ${versionOut} ✓`);
+
+  // 2. kj --help must exit 0 (exercises the command tree wiring).
+  try {
+    run(binPath, ["--help"]);
+  } catch (err) {
+    fail("`kj --help` failed on a clean install", err.stderr || err.message);
+  }
+  console.log("verify-pack: kj --help ✓");
+
+  // 3. The deps that broke before must resolve in the installed tree.
+  const installedRoot = path.join(tmpDir, "node_modules", "karajan-code");
+  const checks = [
+    path.join(tmpDir, "node_modules", "sqlite-vec", "index.mjs"),
+    path.join(installedRoot, "node_modules", "@karajan", "core", "src", "vec-store.js"),
+  ];
+  for (const p of checks) {
+    if (!fs.existsSync(p)) fail(`expected resolved path missing in install: ${p}`);
+  }
+  console.log("verify-pack: sqlite-vec + @karajan/core resolve ✓");
+
+  console.log(`\n✓ verify-pack: karajan-code@${expectedVersion} installs clean and runs.`);
+} finally {
+  if (tgzPath && fs.existsSync(tgzPath)) fs.rmSync(tgzPath, { force: true });
+  if (tmpDir && fs.existsSync(tmpDir)) fs.rmSync(tmpDir, { recursive: true, force: true });
+}

package/src/agents/aider-agent.js

@@ -12,7 +12,7 @@ import { resolveBin } from "./resolve-bin.js";
  * Returns `{tokens_in, tokens_out, cached_tokens}` or null when no usage
  * is found (= unmeasured; callers leave the fields undefined).
  */
-export function extractAiderUsage(text) {
+function extractAiderUsage(text) {
   if (!text) return null;
   for (const line of text.split("\n")) {
     const t = line.trim();

package/src/agents/gemini-agent.js

@@ -12,7 +12,7 @@ import { resolveBin } from "./resolve-bin.js";
  * so the caller leaves `cached_tokens` undefined (= unmeasured,
  * distinct from a measured 0).
  */
-export function extractGeminiUsage(text) {
+function extractGeminiUsage(text) {
   if (!text) return null;
   const candidates = [];
   for (const line of text.split("\n")) {

package/src/agents/opencode-agent.js

@@ -10,7 +10,7 @@ import { resolveBin } from "./resolve-bin.js";
  * nested `usage` object. Returns `{tokens_in, tokens_out, cached_tokens}`
  * or null (= unmeasured).
  */
-export function extractOpenCodeUsage(text) {
+function extractOpenCodeUsage(text) {
   if (!text) return null;
   const candidates = [text.trim()];
   for (const line of text.split("\n")) {

package/src/audit/agent-readiness.js

@@ -16,6 +16,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
+import { escapeRegExp } from "../utils/escape-regexp.js";
 
 const PAGE_BYTE_LIMIT = 32 * 1024; // ≈ 8K tokens, the typical agent budget per fetch
 
@@ -65,7 +66,7 @@ const CHECKS = [
       if (!found) return { ok: false, hint: "Add robots.txt with `User-agent: GPTBot|ClaudeBot|PerplexityBot\\nAllow: /` blocks.", details: {} };
       const text = safeRead(path.join(rootDir, found));
       const aiBots = ["GPTBot", "ClaudeBot", "PerplexityBot", "anthropic-ai", "Google-Extended"];
-      const allowed = aiBots.filter((bot) => new RegExp(`User-agent:\\s*${bot}[\\s\\S]*?Allow:\\s*/`, "i").test(text));
+      const allowed = aiBots.filter((bot) => new RegExp(`User-agent:\\s*${escapeRegExp(bot)}[\\s\\S]*?Allow:\\s*/`, "i").test(text));
       const ok = allowed.length > 0;
       return ok
         ? { ok: true, hint: null, details: { found, allowed } }

package/src/audit/deterministic-summary.js

@@ -71,7 +71,8 @@ function formatInjectionBlock(inj) {
       if (items.length === 0) continue;
       lines.push(`  - ${severity} (${items.length}):`);
       for (const f of items.slice(0, MAX_SAMPLE_INJECTION_PER_SEVERITY)) {
-        lines.push(`    - ${f.file || "(unknown)"}${f.line ? `:${f.line}` : ""} [${f.type}] ${f.pattern}`);
+        const lineSuffix = f.line ? `:${f.line}` : "";
+        lines.push(`    - ${f.file || "(unknown)"}${lineSuffix} [${f.type}] ${f.pattern}`);
       }
       if (items.length > MAX_SAMPLE_INJECTION_PER_SEVERITY) lines.push(`    - ... and ${items.length - MAX_SAMPLE_INJECTION_PER_SEVERITY} more in ${severity}`);
     }
@@ -85,7 +86,8 @@ function formatCircularDepsBlock(circularDeps) {
     return ["### Circular Dependencies (architecture)", `- Status: not available — ${circularDeps.reason || "madge not available"}`, ""];
   }
   const lines = ["### Circular Dependencies (architecture)"];
-  lines.push(`- Total cycles: ${circularDeps.total ?? 0}${circularDeps.suppressedCount ? ` (+${circularDeps.suppressedCount} suppressed)` : ""}`);
+  const suppressedSuffix = circularDeps.suppressedCount ? ` (+${circularDeps.suppressedCount} suppressed)` : "";
+  lines.push(`- Total cycles: ${circularDeps.total ?? 0}${suppressedSuffix}`);
   if ((circularDeps.total ?? 0) > 0) {
     const groups = groupCyclesBySeverity(circularDeps.cycles || []);
     for (const [severity, cycles] of Object.entries(groups)) {
@@ -118,7 +120,8 @@ function formatSemgrepBlock(semgrepFindings) {
       if (findings.length === 0) continue;
       lines.push(`  - ${severity} (${findings.length}):`);
       for (const f of findings.slice(0, MAX_SAMPLE_SEMGREP_PER_SEVERITY)) {
-        const loc = f.file ? `${f.file}${f.line ? `:${f.line}` : ""}` : "";
+        const lineSuffix = f.line ? `:${f.line}` : "";
+        const loc = f.file ? `${f.file}${lineSuffix}` : "";
         lines.push(`    - ${loc} [${f.rule}]`);
       }
       if (findings.length > MAX_SAMPLE_SEMGREP_PER_SEVERITY) {
@@ -172,7 +175,9 @@ function formatDeadExportsBlock(deadExports) {
       if (items.length === 0) continue;
       lines.push(`  - ${severity} (${items.length}):`);
       for (const item of items.slice(0, MAX_SAMPLE_KNIP_PER_SEVERITY)) {
-        lines.push(`    - ${item.path}${item.line ? `:${item.line}` : ""} [${item.rule}]${item.name ? ` \`${item.name}\`` : ""}`);
+        const lineSuffix = item.line ? `:${item.line}` : "";
+        const nameSuffix = item.name ? ` \`${item.name}\`` : "";
+        lines.push(`    - ${item.path}${lineSuffix} [${item.rule}]${nameSuffix}`);
       }
       if (items.length > MAX_SAMPLE_KNIP_PER_SEVERITY) {
         lines.push(`    - ... and ${items.length - MAX_SAMPLE_KNIP_PER_SEVERITY} more in ${severity}`);
@@ -246,7 +251,8 @@ function formatSonarBlock(sonarFindings) {
       if (issues.length === 0) continue;
       lines.push(`  - ${severity} (${issues.length}):`);
       for (const issue of issues.slice(0, MAX_SAMPLE_SONAR_PER_SEVERITY)) {
-        const loc = issue.component ? `${issue.component}${issue.line ? `:${issue.line}` : ""}` : "";
+        const lineSuffix = issue.line ? `:${issue.line}` : "";
+        const loc = issue.component ? `${issue.component}${lineSuffix}` : "";
         const rule = issue.rule ? ` [${issue.rule}]` : "";
         lines.push(`    - ${loc}${rule} ${issue.message || ""}`.trim());
       }

package/src/audit/issue-filter.js

@@ -16,6 +16,7 @@
 // metadata for auditability — no silent dropping.
 
 import fs from "node:fs";
+import { escapeRegExp } from "../utils/escape-regexp.js";
 
 export const DEFAULT_FALSE_POSITIVES = [
   {
@@ -59,8 +60,8 @@ export function hasInlineIgnore(filePath, line, ruleId, tool = "sonar") {
     const lines = fs.readFileSync(filePath, "utf8").split("\n");
     const idx = line - 1;
     const candidates = [lines[idx], lines[idx - 1]].filter(Boolean);
-    const escapedRule = escapeRegex(ruleId);
-    const escapedTool = escapeRegex(tool);
+    const escapedRule = escapeRegExp(ruleId);
+    const escapedTool = escapeRegExp(tool);
     // New generalised marker + legacy sonar-only marker.
     const reAudit = new RegExp(`karajan-audit-ignore\\s*:\\s*${escapedTool}:${escapedRule}\\b`);
     const reLegacy = tool === "sonar"
@@ -72,10 +73,6 @@ export function hasInlineIgnore(filePath, line, ruleId, tool = "sonar") {
   }
 }
 
-function escapeRegex(s) {
-  return String(s).replaceAll(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-
 /**
  * Filter a list of normalised audit findings into kept + suppressed.
  *

package/src/audit/plan-adherence.js

@@ -7,6 +7,8 @@
  * See docs/plan-adherence.md (PR-C) for the full spec.
  */
 
+import { escapeRegExp } from "../utils/escape-regexp.js";
+
 const WEIGHTS = {
   commit_attribution: 40,
   acceptance_tests: 30,
@@ -20,7 +22,7 @@ const WEIGHTS = {
  * appear inside HU ids so we anchor on whole-token rather than \b.
  */
 function huIdMatcher(huId) {
-  const escaped = String(huId).replace(/[-/\\^$*+?.()|[\]{}]/g, "\\$&");
+  const escaped = escapeRegExp(huId);
   return new RegExp(`(^|[^a-z0-9])${escaped}([^a-z0-9]|$)`, "i");
 }