karajan-code 2.14.3 → 2.16.0

package/src/sonar/issue-filter.js

@@ -0,0 +1,110 @@
+// KJC-TSK-0416: pre-filtro determinístico de falsos positivos Sonar.
+//
+// Antes de que los issues Sonar lleguen al coder como feedback (sonar-role)
+// o al auditor (audit), filtramos los que sabemos que son falsos positivos
+// por reglas conocidas. Sin esto el coder quemaba tokens intentando
+// "arreglar" cosas que no están rotas.
+//
+// Dos mecanismos complementarios:
+//   1. Rules estáticas: { rule, filePattern, reason } — match por reglaId
+//      + patrón de path. Cargadas por defecto del catálogo de FALSE_POSITIVES
+//      abajo + extensibles via config.sonar.false_positives.
+//   2. Inline ignore: `// karajan-sonar-ignore: <ruleId>` en la línea del
+//      issue (o la anterior) → suprime ese hit exacto.
+
+import fs from "node:fs";
+
+// Catálogo built-in de patrones conocidos. Cada entrada:
+//   { rule: "javascript:S2699", filePattern: RegExp, reason: "..." }
+// Ampliable via config.sonar.false_positives.
+export const DEFAULT_FALSE_POSITIVES = [
+  {
+    rule: "javascript:S2699",
+    filePattern: /tests\/architecture\//,
+    reason: "Tests structurales fallan vía expect(offenders, msg).toEqual([]) — Sonar no detecta el assert con mensaje custom",
+  },
+];
+
+/**
+ * Comprueba si una línea del file contiene `// karajan-sonar-ignore: <ruleId>`.
+ * Acepta la línea exacta del issue o la inmediatamente anterior.
+ *
+ * @param {string} filePath
+ * @param {number} line - 1-indexed
+ * @param {string} ruleId
+ * @returns {boolean}
+ */
+export function hasInlineIgnore(filePath, line, ruleId) {
+  if (!filePath || !line || !ruleId) return false;
+  if (!fs.existsSync(filePath)) return false;
+  try {
+    const lines = fs.readFileSync(filePath, "utf8").split("\n");
+    const idx = line - 1;
+    const candidates = [lines[idx], lines[idx - 1]].filter(Boolean);
+    const re = new RegExp(`karajan-sonar-ignore\\s*:\\s*${escapeRegex(ruleId)}\\b`);
+    return candidates.some((l) => re.test(l));
+  } catch {
+    return false;
+  }
+}
+
+function escapeRegex(s) {
+  return String(s).replaceAll(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Filtra issues de Sonar separando los reales de los falsos positivos.
+ *
+ * @param {object[]} issues - array de Sonar issues (shape: { rule, component, line, message, severity, ... })
+ * @param {object} [opts]
+ * @param {object[]} [opts.extraRules] - rules adicionales del config
+ * @param {string} [opts.projectRoot] - para resolver component → ruta absoluta
+ * @returns {{ kept: object[], suppressed: object[] }}
+ */
+export function filterFalsePositives(issues, opts = {}) {
+  if (!Array.isArray(issues)) return { kept: [], suppressed: [] };
+  const rules = [...DEFAULT_FALSE_POSITIVES, ...(opts.extraRules || [])].map((r) => ({
+    ...r,
+    filePattern: r.filePattern instanceof RegExp ? r.filePattern : new RegExp(String(r.filePattern || ".*")),
+  }));
+  const projectRoot = opts.projectRoot || process.cwd();
+  const kept = [];
+  const suppressed = [];
+
+  for (const issue of issues) {
+    const path = componentToPath(issue.component);
+    let matched = null;
+
+    // 1. Rules estáticas.
+    for (const rule of rules) {
+      if (issue.rule === rule.rule && rule.filePattern.test(path)) {
+        matched = { rule: rule.rule, path, reason: rule.reason };
+        break;
+      }
+    }
+
+    // 2. Inline ignore (más caro — solo si la regla estática no matchea).
+    if (!matched && issue.rule && issue.line && path) {
+      const absPath = path.startsWith("/") ? path : `${projectRoot}/${path}`;
+      if (hasInlineIgnore(absPath, issue.line, issue.rule)) {
+        matched = { rule: issue.rule, path, reason: "inline `// karajan-sonar-ignore`" };
+      }
+    }
+
+    if (matched) {
+      suppressed.push({ ...issue, _suppressedBy: matched });
+    } else {
+      kept.push(issue);
+    }
+  }
+  return { kept, suppressed };
+}
+
+/**
+ * Sonar reporta component como `<projectKey>:<relativePath>`. Extrae el path.
+ */
+function componentToPath(component) {
+  if (typeof component !== "string") return "";
+  const colonIdx = component.indexOf(":");
+  return colonIdx >= 0 ? component.slice(colonIdx + 1) : component;
+}

package/src/sonar/scanner.js

@@ -164,7 +164,7 @@ async function ensureSonarProjectProperties(cwd = process.cwd()) {
     } catch {
       // no package.json or invalid JSON — use defaults
     }
-    const projectKey = (pkg.name || path.basename(cwd)).replace(/[^a-zA-Z0-9_.-]/g, "_");
+    const projectKey = (pkg.name || path.basename(cwd)).replaceAll(/[^a-zA-Z0-9_.-]/g, "_");
     const props = [
       `sonar.projectKey=${projectKey}`,
       `sonar.projectName=${pkg.name || path.basename(cwd)}`,

package/src/utils/cli-progress.js

@@ -132,14 +132,71 @@ export function createCliProgressReporter(opts = {}) {
     if (typeof heartbeatTimer.unref === "function") heartbeatTimer.unref();
   }
 
+  // JSON suppression — cuando el agente emite estructura JSON, la
+  // suprimimos por completo SIN marker ("<json suprimido>" confundía
+  // tanto como el propio JSON). Si no hay nada útil que decirle al
+  // usuario, mejor silencio.
+  //
+  // Capturamos 4 patrones:
+  //   1. Fence multilínea ``` json ... ``` (state in fence hasta cierre).
+  //   2. Brace block standalone { ... } o [ ... ] (state hasta brace=0).
+  //   3. Línea suelta con ``` o ```json EN CUALQUIER PARTE (incluso
+  //      "done: ```json" embedded en texto): suprimida + abre fence
+  //      si no estaba abierto.
+  //   4. Línea suelta con shape de propiedad JSON (`  "key": ...`,
+  //      `  },`, `  ],`, `  {`) cuando NO estamos en bloque: heurística
+  //      de "trozo de JSON suelto" — se suprime, no entra al stderr.
+  let inJsonBlock = false;
+  let fenceMode = false;
+  let braceDepth = 0;
+  const FULL_FENCE_RE = /^\s*```(?:json)?\s*$/;
+  const HAS_FENCE_RE = /```/;
+  const STANDALONE_BRACE_OPEN = /^[\s]*[{[]\s*$/;
+  // Trozo de línea que es CLARAMENTE sintaxis JSON aislada:
+  //   - `  "foo": "bar",`        propiedad
+  //   - `  "foo": 123`           propiedad numérica
+  //   - `  "foo": {`             apertura de objeto en valor
+  //   - `  },` / `  ],` / `  }` / `  ]`  cierre con o sin coma
+  const JSON_SCRAP_RE =
+    /^\s*(?:"[^"\\]*(?:\\.[^"\\]*)*"\s*:\s*.+|[}\]][,]?)\s*$/;
   const onOutput = (event) => {
     if (!event || typeof event !== "object") return;
     const raw = typeof event.line === "string" ? event.line : "";
     if (!raw) return;
-    // Strip trailing newline — we re-add our own.
     const line = raw.replace(/\s+$/, "");
     if (!line) return;
     lastActivityAt = Date.now();
+    // Estado: dentro de bloque ya marcado.
+    if (inJsonBlock) {
+      if (fenceMode) {
+        if (HAS_FENCE_RE.test(line)) { inJsonBlock = false; fenceMode = false; }
+        return;
+      }
+      braceDepth += (line.match(/[{[]/g) || []).length - (line.match(/[}\]]/g) || []).length;
+      if (braceDepth <= 0) { inJsonBlock = false; braceDepth = 0; }
+      return;
+    }
+    // Apertura de bloque por fence (línea es SOLO ``` o ```json).
+    if (FULL_FENCE_RE.test(line)) {
+      inJsonBlock = true; fenceMode = true; braceDepth = 0;
+      return;
+    }
+    // Apertura de bloque por brace standalone.
+    if (STANDALONE_BRACE_OPEN.test(line)) {
+      inJsonBlock = true; fenceMode = false; braceDepth = 1;
+      return;
+    }
+    // Fence embedded en texto (línea tipo `done: ```json` o `texto ```).
+    // Si la fence está sin cerrar en la misma línea → entra al modo.
+    if (HAS_FENCE_RE.test(line)) {
+      const fences = (line.match(/```/g) || []).length;
+      if (fences % 2 === 1) {           // impar → queda fence abierto
+        inJsonBlock = true; fenceMode = true; braceDepth = 0;
+      }
+      return;                            // suprimida en cualquier caso
+    }
+    // Trozo de JSON suelto sin fence: suprimir silenciosamente.
+    if (JSON_SCRAP_RE.test(line)) return;
     const icon = ICONS[event.kind] || ICONS.text;
     stream.write(`  ${icon} ${line}\n`);
   };

package/src/utils/derive-project-name-from-cwd.js

@@ -40,9 +40,9 @@ function prettifyName(raw) {
   if (!trimmed) return null;
   // Insert space at camelCase boundaries, then split on -/_/whitespace.
   const spaced = trimmed
-    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
-    .replace(/[-_]+/g, " ")
-    .replace(/\s+/g, " ")
+    .replaceAll(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replaceAll(/[-_]+/g, " ")
+    .replaceAll(/\s+/g, " ")
     .trim();
   if (!spaced) return null;
   return spaced

package/src/utils/garbage-collector.js

@@ -274,6 +274,82 @@ async function gcHuStories(opts) {
   return result;
 }
 
+// KJC-TSK-0414 PR3: limpia ~/.kj/standby/done/<id>-<ts>.json finalizadas
+// hace > N días. Las pendientes en ~/.kj/standby/<id>.json NUNCA se tocan
+// — son las que esperan resume.
+async function gcStandbyDone(opts) {
+  const result = { removed: [], bytesFreed: 0, errors: [] };
+  const now = opts.now || new Date();
+  const doneDir = path.join(getKjHome(), "standby", "done");
+  if (!(await exists(doneDir))) return result;
+
+  const entries = (await listDir(doneDir)).filter((e) => e.isFile());
+  for (const entry of entries) {
+    const file = path.join(doneDir, entry.name);
+    const stat = await tryStat(file);
+    if (!stat) continue;
+    const days = ageInDays(stat, now);
+    if (days <= opts.standbyDoneRetentionDays) continue;
+    try {
+      await unlinkOrRm(file, opts.dryRun);
+      result.removed.push({ path: file, reason: `standby done > ${opts.standbyDoneRetentionDays}d (${Math.round(days)}d)`, kind: "standby-done" });
+    } catch (err) {
+      result.errors.push({ path: file, error: err.message });
+    }
+  }
+  return result;
+}
+
+// KJC-TSK-0414 PR3: limpia ~/.karajan/audits/<project>/ con last mtime > N días.
+// El usuario reportó decenas de carpetas kj-test-* huérfanas — son audits de
+// runs antiguos cuyo project ya no existe o que llevan meses sin actividad.
+async function gcAudits(opts) {
+  const result = { removed: [], bytesFreed: 0, errors: [] };
+  const now = opts.now || new Date();
+  const auditRoot = path.join(getKarajanHome(), "audits");
+  if (!(await exists(auditRoot))) return result;
+
+  const entries = (await listDir(auditRoot)).filter((e) => e.isDirectory());
+  for (const entry of entries) {
+    const dir = path.join(auditRoot, entry.name);
+    const stat = await tryStat(dir);
+    if (!stat) continue;
+    const days = ageInDays(stat, now);
+    if (days <= opts.auditsRetentionDays) continue;
+    try {
+      await unlinkOrRm(dir, opts.dryRun);
+      result.removed.push({ path: dir, reason: `audit > ${opts.auditsRetentionDays}d sin actividad (${Math.round(days)}d)`, kind: "audit" });
+    } catch (err) {
+      result.errors.push({ path: dir, error: err.message });
+    }
+  }
+  return result;
+}
+
+// KJC-TSK-0414 PR3: ~/.karajan/hu-board-runs/<runId>/ con mtime > N días.
+async function gcHuBoardRuns(opts) {
+  const result = { removed: [], bytesFreed: 0, errors: [] };
+  const now = opts.now || new Date();
+  const root = path.join(getKarajanHome(), "hu-board-runs");
+  if (!(await exists(root))) return result;
+
+  const entries = (await listDir(root)).filter((e) => e.isDirectory());
+  for (const entry of entries) {
+    const dir = path.join(root, entry.name);
+    const stat = await tryStat(dir);
+    if (!stat) continue;
+    const days = ageInDays(stat, now);
+    if (days <= opts.huBoardRunsRetentionDays) continue;
+    try {
+      await unlinkOrRm(dir, opts.dryRun);
+      result.removed.push({ path: dir, reason: `hu-board-run > ${opts.huBoardRunsRetentionDays}d (${Math.round(days)}d)`, kind: "hu-board-run" });
+    } catch (err) {
+      result.errors.push({ path: dir, error: err.message });
+    }
+  }
+  return result;
+}
+
 function mergeResults(...parts) {
   const out = { removed: [], bytesFreed: 0, errors: [] };
   for (const r of parts) {
@@ -290,6 +366,10 @@ function defaultOpts(opts = {}) {
     draftRetentionDays: opts.draftRetentionDays ?? 60,
     sessionRetentionDays: opts.sessionRetentionDays ?? 7,
     huRetentionDays: opts.huRetentionDays ?? 14,
+    // KJC-TSK-0414 PR3
+    standbyDoneRetentionDays: opts.standbyDoneRetentionDays ?? 7,
+    auditsRetentionDays: opts.auditsRetentionDays ?? 30,
+    huBoardRunsRetentionDays: opts.huBoardRunsRetentionDays ?? 30,
     dryRun: Boolean(opts.dryRun),
     now: opts.now || new Date(),
   };
@@ -307,12 +387,15 @@ export async function runManualGC(opts = {}) {
   // stories live in different directory subtrees and don't share state,
   // so Promise.all is safe and roughly halves end-to-end GC latency on
   // a populated KJ_HOME.
-  const [plans, sessions, huStories] = await Promise.all([
+  const [plans, sessions, huStories, standbyDone, audits, huBoardRuns] = await Promise.all([
     gcPlans(o),
     gcSessions(o),
     gcHuStories(o),
+    gcStandbyDone(o),
+    gcAudits(o),
+    gcHuBoardRuns(o),
   ]);
-  return mergeResults(plans, sessions, huStories);
+  return mergeResults(plans, sessions, huStories, standbyDone, audits, huBoardRuns);
 }
 
 /**

package/src/utils/injection-guard.js

@@ -178,7 +178,7 @@ export function scanDiff(diff, opts = {}) {
 function excerpt(text, index) {
   const start = Math.max(0, index - 20);
   const end = Math.min(text.length, index + 100);
-  return text.slice(start, end).replace(/\n/g, "\\n").slice(0, 120);
+  return text.slice(start, end).replaceAll(/\n/g, "\\n").slice(0, 120);
 }
 
 function lineAt(text, index) {

package/src/utils/messages.js

@@ -48,7 +48,7 @@ const MESSAGES = {
  */
 export function msg(key, lang = "en", params = {}) {
   const template = MESSAGES[lang]?.[key] || MESSAGES.en[key] || key;
-  return template.replace(/\{(\w+)\}/g, (_, k) => params[k] ?? `{${k}}`);
+  return template.replaceAll(/\{(\w+)\}/g, (_, k) => params[k] ?? `{${k}}`);
 }
 
 /**

package/src/utils/run-registry.js

@@ -0,0 +1,115 @@
+/**
+ * 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 os from "node:os";
+
+/**
+ * Directorio raíz donde viven los registros de run.
+ * Honra `KJ_HOME` para tests y setups custom.
+ */
+export function runsDir() {
+  const home = process.env.KJ_HOME || path.join(os.homedir(), ".karajan");
+  return path.join(home, "runs");
+}
+
+/**
+ * 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(),
+    };
+    fs.writeFileSync(filePath, JSON.stringify(entry, null, 2), "utf8");
+    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"; }
+}