karajan-code 3.0.0 → 3.1.0

package/src/review/tdd-discipline.js

@@ -0,0 +1,90 @@
+// TDD discipline gate (KJC-TSK-0398 PR1).
+// PR1 ships the pure decision logic with injected runTests/stashFiles
+// helpers. PR2 ships the real surgical stash. PR3 wires the gate into
+// the pipeline behind `development.require_red_then_green`.
+
+const PARSERS = {
+  vitest: parseVitestFailures,
+  jest: parseVitestFailures,
+  pytest: parsePytestFailures,
+};
+
+function parseVitestFailures(output) {
+  const failures = new Set();
+  for (const line of String(output || "").split("\n")) {
+    const m = line.match(/^\s*(?:FAIL|×|✖)\s+(\S+)/);
+    if (m) failures.add(m[1].trim());
+  }
+  return failures;
+}
+
+function parsePytestFailures(output) {
+  const failures = new Set();
+  for (const line of String(output || "").split("\n")) {
+    const m = line.match(/^FAILED\s+(\S+)/);
+    if (m) failures.add(m[1].trim());
+  }
+  return failures;
+}
+
+function anyNewTestIn(failures, testFiles) {
+  return [...failures].some((f) => testFiles.some((t) => f.includes(t) || t.includes(f)));
+}
+
+export async function verifyTddDiscipline({
+  projectDir,
+  sourceFiles = [],
+  testFiles = [],
+  framework = null,
+  runTests,
+  stashFiles,
+  restoreFiles,
+} = {}) {
+  if (sourceFiles.length === 0) {
+    return { ok: true, reason: "no_source_changes", sourceFiles, testFiles };
+  }
+  if (testFiles.length === 0) {
+    return { ok: true, reason: "no_test_changes", sourceFiles, testFiles };
+  }
+
+  const parser = framework ? PARSERS[framework] : null;
+  if (!parser) {
+    return {
+      ok: true,
+      reason: "framework_unsupported",
+      sourceFiles,
+      testFiles,
+      warning: `tdd-discipline: framework "${framework || "unknown"}" has no failure parser; gate skipped`,
+    };
+  }
+
+  let stashToken = null;
+  try {
+    stashToken = await stashFiles(sourceFiles);
+    const before = await runTests(projectDir);
+    if (!anyNewTestIn(parser(before.output), testFiles)) {
+      return {
+        ok: false,
+        reason: "tests_pass_without_impl",
+        sourceFiles,
+        testFiles,
+        message:
+          "TDD discipline violation: new tests pass without the implementation. Tests must fail first (red), then pass (green).",
+      };
+    }
+  } finally {
+    if (stashToken) await restoreFiles(stashToken);
+  }
+
+  const after = await runTests(projectDir);
+  if (anyNewTestIn(parser(after.output), testFiles)) {
+    return {
+      ok: false,
+      reason: "tests_fail_with_impl",
+      sourceFiles,
+      testFiles,
+      message: "TDD discipline violation: new tests still fail with the implementation present.",
+    };
+  }
+  return { ok: true, reason: "red_then_green_verified", sourceFiles, testFiles };
+}

package/src/roles/tool-correctness-judge-role.js

@@ -0,0 +1,78 @@
+// KJC-TSK-0375 — ToolCorrectnessJudgeRole.
+// Post-iteration LLM judge scoring how well a coder picked its tool calls.
+// PR1 ships role + tests; wiring lives in PR3.
+
+import { AgentRole } from "./agent-role.js";
+import { buildToolCorrectnessJudgePrompt } from "../prompts/tool-correctness-judge.js";
+import { extractFirstJson } from "../utils/json-extract.js";
+
+const DEFAULT_THRESHOLD = 70;
+
+const clampScore = (n) => Number.isFinite(n) ? Math.max(0, Math.min(100, Math.round(n))) : null;
+
+const normalizeBreakdown = (b) => Array.isArray(b) ? b.map((x) => ({
+  tool: typeof x?.tool === "string" ? x.tool : "unknown",
+  args: x?.args && typeof x.args === "object" ? x.args : {},
+  correct: Boolean(x?.correct),
+  reason: typeof x?.reason === "string" ? x.reason.trim() : "",
+})) : [];
+
+export class ToolCorrectnessJudgeRole extends AgentRole {
+  constructor(opts) {
+    super({ ...opts, name: "tool-correctness-judge" });
+    this.threshold = opts?.threshold ?? this.config?.pipeline?.tool_judge?.threshold ?? DEFAULT_THRESHOLD;
+  }
+
+  resolveProvider() {
+    return this.config?.roles?.["tool-correctness-judge"]?.provider
+      || this.config?.roles?.reviewer?.provider
+      || this.config?.roles?.coder?.provider
+      || "claude";
+  }
+
+  extractInput(input) {
+    return { ...super.extractInput(input), toolCalls: Array.isArray(input?.toolCalls) ? input.toolCalls : [] };
+  }
+
+  async buildPrompt({ task, toolCalls }) {
+    return { prompt: buildToolCorrectnessJudgePrompt({ task, toolCalls, instructions: this.instructions }) };
+  }
+
+  parseOutput(raw) { return extractFirstJson(raw); }
+
+  buildSuccessResult(parsed, provider) {
+    const score = clampScore(parsed?.score);
+    return {
+      score,
+      summary: typeof parsed?.summary === "string" ? parsed.summary.trim() : "",
+      breakdown: normalizeBreakdown(parsed?.breakdown),
+      threshold: this.threshold,
+      lowQuality: score !== null && score < this.threshold,
+      provider,
+    };
+  }
+
+  buildSummary(parsed) {
+    const score = clampScore(parsed?.score);
+    if (score === null) return "Tool-judge: unparseable score";
+    return `Tool-judge: ${score}/100 (${score < this.threshold ? "LOW" : "OK"})`;
+  }
+
+  // Empty tool-call list = nothing to judge. Skip the LLM and report a
+  // neutral score so an absent transcript is never read as a failure.
+  async execute(input) {
+    const extracted = this.extractInput(input);
+    if (extracted.toolCalls.length === 0) {
+      return {
+        ok: true,
+        result: {
+          score: null, summary: "no tool calls captured (skipped)", breakdown: [],
+          threshold: this.threshold, lowQuality: false, provider: this.resolveProvider(), skipped: true,
+        },
+        summary: "Tool-judge: skipped (no calls)",
+        usage: null,
+      };
+    }
+    return super.execute(extracted);
+  }
+}

package/src/session/mutators.js

@@ -109,6 +109,10 @@ export function setSonarSummary(session, text) {
   session.last_sonar_summary = text;
 }
 
+export function setCoderTranscript(session, text) {
+  session.last_coder_transcript = text;
+}
+
 export function setSonarIssueSignature(session, sig) {
   session.last_sonar_issue_signature = sig;
 }

package/src/sync/apply-canvas-patch.js

@@ -0,0 +1,55 @@
+/**
+ * kj sync --apply — append a drift patch to the Canvas markdown.
+ *
+ * KJC-TSK-0348. Pure data + I/O: reads the Canvas at `canvasPath`, drops a
+ * `.bak` snapshot alongside it, appends an HTML-comment block describing
+ * untracked / missing / covered files, and atomically renames a `.tmp`
+ * over the target. Comments are inert for the Canvas parser, so the
+ * patched file stays structurally valid — the user converts the TODOs
+ * into Operations by hand.
+ */
+
+import { promises as fs } from "node:fs";
+
+function tempPath(target) {
+  return `${target}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}.tmp`;
+}
+
+export function renderDriftComment(report) {
+  const lines = ["", `<!-- kj sync --apply (${new Date().toISOString()}) — review and convert into Operations as needed. -->`];
+  let mutations = 0;
+  if (report.untracked?.length) {
+    lines.push("<!-- Untracked files (modified, no Operation references them — add one): -->");
+    for (const u of report.untracked) { lines.push(`<!-- + ${u.path} -->`); mutations += 1; }
+  }
+  if (report.missing?.length) {
+    lines.push("<!-- Missing files (Operation file_hint points at a file that does not exist): -->");
+    for (const m of report.missing) { lines.push(`<!-- ! ${m.path}  [op #${(m.operationIndex ?? 0) + 1}] -->`); mutations += 1; }
+  }
+  if (report.covered?.length) {
+    lines.push("<!-- Covered (referenced and modified — consider extending the Approach): -->");
+    for (const c of report.covered) lines.push(`<!-- ~ ${c.path}  [op #${(c.operationIndex ?? 0) + 1}] -->`);
+  }
+  lines.push("<!-- /kj sync -->", "");
+  return { block: lines.join("\n"), mutations };
+}
+
+export async function applyCanvasPatch({ canvasPath, report }) {
+  if (!canvasPath || typeof canvasPath !== "string") throw new Error("applyCanvasPatch: canvasPath is required");
+  if (!report || typeof report !== "object") throw new Error("applyCanvasPatch: report is required");
+  const hasDrift = (report.untracked?.length || 0) + (report.missing?.length || 0) > 0;
+  if (!hasDrift) return { patchedPath: canvasPath, backupPath: null, mutations: 0, skipped: true };
+
+  let original;
+  try { original = await fs.readFile(canvasPath, "utf-8"); }
+  catch (err) { throw new Error(`applyCanvasPatch: cannot read canvas ${canvasPath}: ${err.message}`, { cause: err }); }
+
+  const backupPath = `${canvasPath}.bak`;
+  await fs.writeFile(backupPath, original, "utf-8");
+  const { block, mutations } = renderDriftComment(report);
+  const trimmed = original.endsWith("\n") ? original : `${original}\n`;
+  const tmp = tempPath(canvasPath);
+  await fs.writeFile(tmp, `${trimmed}${block}\n`, "utf-8");
+  await fs.rename(tmp, canvasPath);
+  return { patchedPath: canvasPath, backupPath, mutations };
+}

package/src/utils/paths.js

@@ -1,3 +1,4 @@
+import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
@@ -12,6 +13,17 @@ function vitestRoot() {
     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;
 }
 

package/src/utils/repo-cleaner.js

@@ -0,0 +1,79 @@
+/**
+ * Repo-level cleaner — KJC-TSK-0499 PR1. Read-only collector that
+ * surfaces stale local artifacts so the user can decide what to drop.
+ * Detects: branches merged into a base ref, branches with `[gone]`
+ * upstream, top-level `dist/` `coverage/` `logs/` older than N days,
+ * `*.tmp` / `*.bak` older than N days. Never spawns destructive ops.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { execa } from "execa";
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const STALE_DIRS = ["dist", "coverage", "logs"];
+const STALE_FILE_RX = /\.(tmp|bak)$/;
+
+async function safeGit(cwd, args) {
+  try {
+    const { stdout, exitCode } = await execa("git", args, { cwd, reject: false });
+    return exitCode === 0 ? stdout : "";
+  } catch { return ""; }
+}
+
+async function collectBranches(cwd, baseRef) {
+  const items = [];
+  const baseShort = baseRef.replace(/^origin\//, "");
+  const current = (await safeGit(cwd, ["symbolic-ref", "--short", "HEAD"])).trim();
+  const merged = await safeGit(cwd, ["branch", "--merged", baseRef, "--format=%(refname:short)"]);
+  for (const raw of merged.split("\n")) {
+    const name = raw.trim();
+    if (!name || name === current || name === baseShort) continue;
+    items.push({ kind: "branch", target: name, reason: `merged into ${baseRef}`, command: `git branch -d ${name}` });
+  }
+  for (const line of (await safeGit(cwd, ["branch", "-vv"])).split("\n")) {
+    const m = line.match(/^[\s*]+(\S+)\s+\S+\s+\[[^:]+: gone\]/);
+    if (m && m[1] !== current) items.push({ kind: "branch-gone", target: m[1], reason: "upstream gone", command: `git branch -D ${m[1]}` });
+  }
+  return items;
+}
+
+async function ageMs(p) {
+  try { return Date.now() - (await fs.stat(p)).mtimeMs; } catch { return -1; }
+}
+
+async function collectStale(cwd, maxAgeDays) {
+  const cutoff = maxAgeDays * DAY_MS;
+  const items = [];
+  for (const name of STALE_DIRS) {
+    const full = path.join(cwd, name);
+    if (await ageMs(full) > cutoff) {
+      items.push({ kind: "dir", target: full, reason: `${name}/ older than ${maxAgeDays}d`, command: `rm -rf ${full}` });
+    }
+  }
+  let entries = [];
+  try { entries = await fs.readdir(cwd, { withFileTypes: true }); } catch { /* cwd unreadable */ }
+  for (const e of entries) {
+    if (!e.isFile() || !STALE_FILE_RX.test(e.name)) continue;
+    const full = path.join(cwd, e.name);
+    if (await ageMs(full) > cutoff) {
+      items.push({ kind: "file", target: full, reason: `${path.extname(e.name)} older than ${maxAgeDays}d`, command: `rm -f ${full}` });
+    }
+  }
+  return items;
+}
+
+/**
+ * Discover repo-level cleanup candidates.
+ * @param {object} opts
+ * @param {string} [opts.cwd=process.cwd()]
+ * @param {number} [opts.maxAgeDays=7]
+ * @param {string} [opts.mergedTo="origin/main"]
+ * @returns {Promise<{candidates: Array, errors: Array}>}
+ */
+export async function collectRepoCandidates({ cwd = process.cwd(), maxAgeDays = 7, mergedTo = "origin/main" } = {}) {
+  const candidates = [];
+  const errors = [];
+  try { candidates.push(...await collectBranches(cwd, mergedTo)); } catch (e) { errors.push({ stage: "branches", error: String(e?.message ?? e) }); }
+  try { candidates.push(...await collectStale(cwd, maxAgeDays)); } catch (e) { errors.push({ stage: "stale", error: String(e?.message ?? e) }); }
+  return { candidates, errors };
+}

package/src/utils/tool-call-extractor.js

@@ -0,0 +1,56 @@
+// KJC-TSK-0375 PR2 — Extract structured tool calls from an agent transcript.
+//
+// The ToolCorrectnessJudgeRole (PR1) consumes a list of `{tool, args}`
+// objects. The coder writes a raw transcript (provider-dependent format) to
+// disk per iteration. This module bridges the two: parse the transcript,
+// return the ordered list of tool invocations.
+//
+// Provider-agnostic interface; Claude stream-json is the only format
+// implemented today. New providers add a branch below — keep parsers
+// pure (no I/O), so the role tests can mock transcripts trivially.
+
+const PROVIDER_PARSERS = {
+  claude: parseClaudeStreamJson,
+};
+
+/**
+ * Extract tool calls from a transcript string.
+ *
+ * @param {object} args
+ * @param {string} args.transcript - raw agent output (stdout/stderr buffer).
+ * @param {string} [args.provider] - "claude" (default). Unknown returns [].
+ * @returns {Array<{tool:string, args:object}>}
+ */
+export function extractToolCalls({ transcript, provider = "claude" } = {}) {
+  if (typeof transcript !== "string" || transcript.length === 0) return [];
+  const parser = PROVIDER_PARSERS[provider];
+  if (!parser) return [];
+  return parser(transcript);
+}
+
+// Claude emits one JSON event per line. We care about `assistant` events
+// whose `message.content` is an array containing `tool_use` blocks with
+// `{type:"tool_use", name, input}`. Lines that fail to parse, that are
+// not `assistant`, or whose content is not an array are silently skipped:
+// the transcript also carries `system`, `result`, `rate_limit_event`, etc.
+function parseClaudeStreamJson(transcript) {
+  const out = [];
+  for (const raw of transcript.split("\n")) {
+    const line = raw.trim();
+    if (!line || line[0] !== "{") continue;
+    let obj;
+    try { obj = JSON.parse(line); } catch { continue; }
+    if (obj?.type !== "assistant") continue;
+    const content = obj?.message?.content;
+    if (!Array.isArray(content)) continue;
+    for (const block of content) {
+      if (block?.type === "tool_use" && typeof block.name === "string") {
+        out.push({
+          tool: block.name,
+          args: block.input && typeof block.input === "object" ? block.input : {},
+        });
+      }
+    }
+  }
+  return out;
+}

package/src/utils/vector-store-orphans.js

@@ -0,0 +1,89 @@
+/**
+ * RAG vector-store orphan collector — KJC-TSK-0499 PR2.
+ *
+ * Enumerates distinct `project_slug` rows in `~/.karajan/rag.db`,
+ * augments each with chunk count + last_indexed_{at,commit}, and
+ * marks as orphan the slugs whose basename does not resolve to a
+ * directory in any of the configured `projectRoots`.
+ *
+ * Read-only. Returns rows + a copy-paste sqlite3 command per orphan.
+ * Deliberate inverse of the RAG indexer: never opens the DB for write.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import { dbPath, openVecStore, projectSlug } from "../rag/vec-store.js";
+
+const DEFAULT_ROOTS = [
+  path.join(os.homedir(), "ws_npm-packages"),
+  path.join(os.homedir(), "ws_firebase"),
+  path.join(os.homedir(), "projects"),
+  path.join(os.homedir(), "code"),
+];
+
+async function listDirs(root) {
+  try {
+    const entries = await fs.readdir(root, { withFileTypes: true });
+    return entries.filter((e) => e.isDirectory()).map((e) => path.join(root, e.name));
+  } catch {
+    return [];
+  }
+}
+
+async function buildSlugIndex(roots) {
+  const index = new Map();
+  for (const root of roots) {
+    for (const dir of await listDirs(root)) {
+      const slug = projectSlug(dir);
+      if (slug && !index.has(slug)) index.set(slug, dir);
+    }
+  }
+  return index;
+}
+
+function purgeCommand(slug) {
+  const slugSafe = slug.replace(/'/g, "''");
+  return `sqlite3 ${dbPath()} "DELETE FROM chunks WHERE project_slug='${slugSafe}'; DELETE FROM vec_store_meta WHERE project_slug='${slugSafe}';"`;
+}
+
+/**
+ * Collect RAG vector-store orphans.
+ * @param {object} [opts]
+ * @param {string[]} [opts.projectRoots] — directories to look for live
+ *   projects whose basename matches each slug. Defaults to the usual
+ *   `~/ws_*`, `~/projects`, `~/code` set.
+ * @returns {Promise<{rows: Array, orphans: Array, errors: Array}>}
+ */
+export async function collectVectorStoreOrphans({ projectRoots = DEFAULT_ROOTS } = {}) {
+  const rows = [];
+  const errors = [];
+  let db;
+  try { db = openVecStore(); } catch (e) {
+    return { rows, orphans: [], errors: [{ stage: "open", error: String(e?.message ?? e) }] };
+  }
+  try {
+    const stats = db.prepare(`
+      SELECT COALESCE(c.project_slug, '<null>') AS slug,
+             COUNT(c.id) AS chunkCount,
+             COALESCE(m.last_indexed_commit, '') AS lastCommit,
+             COALESCE(m.last_indexed_at, '') AS lastAt
+      FROM chunks c
+      LEFT JOIN vec_store_meta m ON m.project_slug = c.project_slug
+      GROUP BY c.project_slug
+      ORDER BY chunkCount DESC
+    `).all();
+    const slugIndex = await buildSlugIndex(projectRoots);
+    for (const r of stats) {
+      const resolved = slugIndex.get(r.slug) || null;
+      rows.push({ ...r, resolvedDir: resolved, orphan: !resolved && r.slug !== "<null>" });
+    }
+  } catch (e) {
+    errors.push({ stage: "query", error: String(e?.message ?? e) });
+  } finally {
+    try { db.close(); } catch { /* close errors are non-fatal */ }
+  }
+  const orphans = rows
+    .filter((r) => r.orphan)
+    .map((r) => ({ ...r, command: purgeCommand(r.slug) }));
+  return { rows, orphans, errors };
+}