karajan-code 3.0.0 → 3.2.0

package/src/utils/qmd-install.js

@@ -0,0 +1,37 @@
+import { runCommand } from "./process.js";
+import { getInstallCommand } from "./os-detect.js";
+import { detectQmd } from "./qmd-detect.js";
+
+/**
+ * Install QMD using the OS-appropriate command.
+ * @param {object} logger - Logger with info/warn methods
+ * @returns {Promise<{ ok: boolean, version: string|null, error: string|null }>}
+ */
+export async function installQmd(logger) {
+  const command = getInstallCommand("qmd");
+
+  logger.info("Installing QMD...");
+
+  try {
+    const result = await runCommand("sh", ["-c", command], { timeout: 120_000 });
+
+    if (result.exitCode !== 0) {
+      const error = (result.stderr || "").trim() || `exit code ${result.exitCode}`;
+      logger.warn(`QMD install failed: ${error}`);
+      return { ok: false, version: null, error };
+    }
+
+    const check = await detectQmd();
+    if (check.available) {
+      logger.info(`QMD ${check.version || ""} installed successfully.`);
+      return { ok: true, version: check.version, error: null };
+    }
+
+    logger.warn("QMD install command succeeded but qmd binary not found in PATH.");
+    return { ok: false, version: null, error: "Binary not found after install" };
+  } catch (err) {
+    const error = err.message || String(err);
+    logger.warn(`QMD install failed: ${error}`);
+    return { ok: false, version: null, error };
+  }
+}

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/run-registry.js

@@ -1,116 +1,9 @@
-/**
- * Run registry — registro persistente de `kj run` activos.
- *
- * KJC-TSK-0396 (extensión): el HU Board necesita ver runs lanzados desde
- * la terminal externa (no solo los lanzados desde el propio board). Para
- * eso, cada `kj run` escribe su PID + planId + huIds + projectDir a un
- * archivo en `~/.karajan/runs/<runId>.json` al arrancar, y lo borra al
- * terminar (success o crash con cleanup vía finally).
- *
- * El board lee ese directorio en startup + cada vez que sirve el endpoint
- * `/api/runs/:planId/active`, descartando los registros con PID muerto
- * (filtrado con `process.kill(pid, 0)`). Resultado: bidireccionalidad
- * total terminal ↔ board.
- *
- * Compartido entre el CLI (src/commands/run.js) y el board
- * (packages/hu-board/src/run-tracker.js). Vive en src/utils/ porque
- * el board ya importa cosas de src/ sin problema.
- */
-
-import fs from "node:fs";
-import path from "node:path";
-import { writeJsonAtomicSync } from "./atomic-write.js";
-import { getRunsDir } from "./paths.js";
-
-/**
- * Directorio raíz donde viven los registros de run.
- * Delega en `getRunsDir()` (KJC-TSK-0420) — respeta KARAJAN_HOME,
- * KJ_HOME (con warning de deprecación), VITEST tmp y default.
- */
-export function runsDir() {
-  return getRunsDir();
-}
-
-/**
- * Registra un nuevo run en disco. El runId es derivado del PID + timestamp
- * para ser único por proceso.
- *
- * @param {{ pid: number, planId?: string|null, huIds?: string[]|null, projectDir?: string|null, source?: string }} info
- * @returns {string|null} runId o null si la escritura falló (no bloquea al caller).
- */
-export function registerRun(info = {}) {
-  if (!info?.pid) return null;
-  try {
-    fs.mkdirSync(runsDir(), { recursive: true });
-    // Sufijo random para evitar colisiones cuando 2 runs del mismo PID
-    // se registran en el mismo ms (raro en CLI, posible en tests).
-    const runId = `run-${Date.now()}-${info.pid}-${Math.random().toString(36).slice(2, 8)}`;
-    const filePath = path.join(runsDir(), `${runId}.json`);
-    const entry = {
-      runId,
-      pid: info.pid,
-      planId: info.planId || null,
-      huIds: Array.isArray(info.huIds) ? info.huIds : null,
-      projectDir: info.projectDir || null,
-      source: info.source || "cli",
-      startedAt: new Date().toISOString(),
-    };
-    writeJsonAtomicSync(filePath, entry);
-    return runId;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Borra el registro de un run. Idempotente — silencia ENOENT.
- *
- * @param {string} runId
- */
-export function unregisterRun(runId) {
-  if (!runId) return;
-  try {
-    fs.unlinkSync(path.join(runsDir(), `${runId}.json`));
-  } catch {
-    // Idempotente
-  }
-}
-
-/**
- * Lista todos los runs activos en disco, filtrando los con PID muerto.
- * Los muertos se borran del FS (auto-cleanup defensivo).
- *
- * @param {{ planId?: string }} [filter] - si se pasa planId, devuelve solo los runs de ese plan.
- * @returns {Array<{runId, pid, planId, huIds, projectDir, source, startedAt}>}
- */
-export function listActiveRuns(filter = {}) {
-  const dir = runsDir();
-  if (!fs.existsSync(dir)) return [];
-  const out = [];
-  let files;
-  try { files = fs.readdirSync(dir); } catch { return []; }
-  for (const f of files) {
-    if (!f.endsWith(".json")) continue;
-    const filePath = path.join(dir, f);
-    let entry;
-    try { entry = JSON.parse(fs.readFileSync(filePath, "utf8")); }
-    catch { try { fs.unlinkSync(filePath); } catch { /* swallow */ } continue; }
-    if (!isAlive(entry.pid)) {
-      try { fs.unlinkSync(filePath); } catch { /* swallow */ }
-      continue;
-    }
-    if (filter.planId && entry.planId !== filter.planId) continue;
-    out.push(entry);
-  }
-  return out;
-}
-
-/**
- * Verifica si un PID sigue vivo. `process.kill(pid, 0)` NO envía
- * señal — solo lanza ESRCH si el proceso no existe.
- */
-function isAlive(pid) {
-  if (!pid) return false;
-  try { process.kill(pid, 0); return true; }
-  catch (err) { return err.code === "EPERM"; }
-}
+// Shim: run-registry now lives in @karajan/core/run-registry so the
+// hu-board workspace can consume it without a relative dep on the CLI
+// src tree. KJC-TSK-0511 PR3.
+export {
+  runsDir,
+  registerRun,
+  unregisterRun,
+  listActiveRuns,
+} from "@karajan/core/run-registry";

package/src/utils/shared-paths.js

@@ -1,41 +1,12 @@
-/**
- * Team-shared HU Board paths — KJC-PRP-0002 / v2.31.0 PR1.
- *
- * The shared root lives INSIDE the project, not in `~/.karajan/`, so a team
- * can commit it to git (or sync via Drive/SyncThing) and share plans + HU
- * stories without each member regenerating them locally.
- *
- *   <projectDir>/.karajan-shared/
- *     plans/<planId>.json     ← `kj plan share <planId>` copies here
- *     hu-stories/<huId>.md    ← reserved for PR2+ (board reads it)
- *
- * Keep the dir name in lockstep with the HU Board sync layer
- * (`packages/hu-board/src/sync.js`) — diverging the constant breaks the
- * watcher silently. One source of truth lives here.
- */
-
-import path from "node:path";
-
-export const SHARED_DIR_NAME = ".karajan-shared";
-
-export function getSharedRoot(projectDir) {
-  return path.join(projectDir, SHARED_DIR_NAME);
-}
-
-export function getSharedPlansDir(projectDir) {
-  return path.join(getSharedRoot(projectDir), "plans");
-}
-
-export function getSharedHuStoriesDir(projectDir) {
-  return path.join(getSharedRoot(projectDir), "hu-stories");
-}
-
-/**
- * Quick check used by callers that decide whether a plan came from local
- * (`~/.karajan/plans/`) or from the shared dir. The HU Board uses this to
- * stamp a `source` column on each record so the UI can render a 🌐 badge.
- */
-export function isSharedPath(p) {
-  if (!p) return false;
-  return p.split(path.sep).includes(SHARED_DIR_NAME);
-}
+// Shim — the real implementation now lives in @karajan/core/shared-paths.
+// Kept here so CLI callers (src/**/*.js) keep importing
+// "../utils/shared-paths.js" without churn during KJC-TSK-0511 (decouple
+// @karajan/hu-board). Will be retired once every consumer migrates to
+// the @karajan/core import.
+export {
+  SHARED_DIR_NAME,
+  getSharedRoot,
+  getSharedPlansDir,
+  getSharedHuStoriesDir,
+  isSharedPath,
+} from "@karajan/core/shared-paths";

package/src/utils/squeezr-detect.js

@@ -0,0 +1,18 @@
+import { runCommand } from "./process.js";
+
+/**
+ * Detect whether Squeezr is installed and available.
+ * @returns {Promise<{ available: boolean, version: string|null }>}
+ */
+export async function detectSqueezr() {
+  try {
+    const result = await runCommand("squeezr", ["--version"]);
+    if (result.exitCode === 0) {
+      const version = (result.stdout || "").trim() || null;
+      return { available: true, version };
+    }
+    return { available: false, version: null };
+  } catch { /* squeezr binary not found */
+    return { available: false, version: null };
+  }
+}

package/src/utils/squeezr-install.js

@@ -0,0 +1,37 @@
+import { runCommand } from "./process.js";
+import { getInstallCommand } from "./os-detect.js";
+import { detectSqueezr } from "./squeezr-detect.js";
+
+/**
+ * Install Squeezr using the OS-appropriate command.
+ * @param {object} logger - Logger with info/warn methods
+ * @returns {Promise<{ ok: boolean, version: string|null, error: string|null }>}
+ */
+export async function installSqueezr(logger) {
+  const command = getInstallCommand("squeezr");
+
+  logger.info("Installing Squeezr...");
+
+  try {
+    const result = await runCommand("sh", ["-c", command], { timeout: 120_000 });
+
+    if (result.exitCode !== 0) {
+      const error = (result.stderr || "").trim() || `exit code ${result.exitCode}`;
+      logger.warn(`Squeezr install failed: ${error}`);
+      return { ok: false, version: null, error };
+    }
+
+    const check = await detectSqueezr();
+    if (check.available) {
+      logger.info(`Squeezr ${check.version || ""} installed successfully.`);
+      return { ok: true, version: check.version, error: null };
+    }
+
+    logger.warn("Squeezr install command succeeded but squeezr binary not found in PATH.");
+    return { ok: false, version: null, error: "Binary not found after install" };
+  } catch (err) {
+    const error = err.message || String(err);
+    logger.warn(`Squeezr install failed: ${error}`);
+    return { ok: false, version: null, error };
+  }
+}

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 };
+}