karajan-code 4.38.0 → 4.40.0

package/src/rules/evaluate.js

@@ -0,0 +1,60 @@
+/**
+ * The deterministic evaluator of compiled rules (KJC-TSK-0944, MDR-B1, ADR 0016):
+ * one tool call against the rules parseRules accepted, with no model.
+ *
+ * A rule says when to deny. A condition over an argument the call does not
+ * carry, or cannot be read as the operator needs (a date, a number), does not
+ * hold: the rule states a fact about the call, and that fact is not there.
+ */
+import { isObject, toolsOf } from "./compiled.js";
+
+const DAY_MS = 86_400_000;
+
+/** A tool glob: `*` stands for any run of characters, the rest is literal. */
+const toolMatches = (glob, tool) => {
+  const literal = glob.split("*").map((part) => part.replaceAll(/[.+?^${}()|[\]\\]/g, String.raw`\$&`));
+  return new RegExp(`^${literal.join(".*")}$`).test(String(tool));
+};
+
+/** The value at a dotted path of the tool input, own properties only. */
+const at = (input, dotted) =>
+  dotted.split(".").reduce((node, key) => (isObject(node) && Object.hasOwn(node, key) ? node[key] : undefined), input);
+
+/** Calendar days (UTC) from one date to another: the same day is 0, whatever the hour. */
+const daysBetween = (from, to) => Math.floor(Date.parse(to) / DAY_MS) - Math.floor(Date.parse(from) / DAY_MS);
+
+function holds(cond, input) {
+  let value = at(input, cond.arg);
+  const present = value !== undefined && value !== null;
+  if ("exists" in cond) return present === cond.exists;
+  if (!present) return false;
+  if ("days_from" in cond) value = daysBetween(at(input, cond.days_from), value);
+  if ("equals" in cond) return value === cond.equals;
+  if ("in" in cond) return cond.in.includes(value);
+  if ("matches" in cond) return typeof value === "string" && new RegExp(cond.matches).test(value);
+  if (typeof value !== "number" || Number.isNaN(value)) return false;
+  return "gt" in cond ? value > cond.gt : value < cond.lt;
+}
+
+const applies = (rule, tool, input) =>
+  toolsOf(rule.when).some((glob) => toolMatches(glob, tool))
+  && (rule.when.all ?? []).every((cond) => holds(cond, input))
+  && (!rule.when.any?.length || rule.when.any.some((cond) => holds(cond, input)));
+
+/**
+ * @param {object[]} rules what parseRules returned
+ * @param {{tool: string, input?: object}} call
+ * @returns {{decision: "allow"} | {decision: "deny", rule_id: string, source: string|null, text: string|null, message: string}}
+ */
+export function evalRules(rules, { tool, input }) {
+  const args = isObject(input) ? input : {};
+  const hit = rules.find((rule) => rule.kind === "deterministic" && applies(rule, tool, args));
+  if (!hit) return { decision: "allow" };
+  return {
+    decision: "deny",
+    rule_id: hit.id,
+    source: hit.source ?? null,
+    text: hit.text ?? null,
+    message: hit.message ?? hit.text ?? `rule ${hit.id}`,
+  };
+}

package/src/rules/inventory.js

@@ -0,0 +1,118 @@
+/**
+ * Rule inventory (KJC-TSK-0937, MDR-A, ADR 0016). Every rule written in the MD
+ * files that govern a session, with a stable id, its literal text and where it
+ * lives, so each one can get a gate and a deny can cite it.
+ *
+ * A rule is a markdown block (a list item with the lines that continue it, or a
+ * paragraph), outside code blocks, that carries a normative marker. The id hashes
+ * the normalized text, so a rule keeps its id when it moves or is wrapped anew.
+ */
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const NORMATIVE = /\b(nunca|siempre|prohibido|obligatorio|jam[aá]s|never|always|must|forbidden|required|do not|don't)\b/i;
+
+// Emphasis delimiters only: a marker opens after a blank and closes before one (or
+// punctuation), so snake_case names and globs (docs/**/*.md) keep their characters.
+const stripEmphasis = (text) => text
+  .replaceAll(/(^|[\s(])\*\*(\S[^*]*)\*\*(?=[\s).,;:!?]|$)/g, "$1$2")
+  .replaceAll(/(^|[\s(])__(\S[^_]*)__(?=[\s).,;:!?]|$)/g, "$1$2")
+  .replaceAll(/(^|[\s(])\*(\S[^*]*)\*(?=[\s).,;:!?]|$)/g, "$1$2")
+  .replaceAll(/(^|[\s(])_(\S[^_]*)_(?=[\s).,;:!?]|$)/g, "$1$2");
+
+const LIST_ITEM = /^\s*(?:[-*+]|\d+[.)])\s+/;
+
+const HELD =""; // private-use char: stands in for a code span while emphasis is stripped
+
+/**
+ * The text of a markdown line without its list marker, emphasis or code ticks.
+ * What sits inside a code span is kept as written, whatever characters it holds.
+ */
+const plain = (line) => {
+  const spans = [];
+  const held = line
+    .replace(LIST_ITEM, "")
+    .replaceAll(/`([^`]*)`/g, (_m, code) => `${HELD}${spans.push(code) - 1}${HELD}`);
+  return stripEmphasis(held)
+    .replaceAll(new RegExp(`${HELD}(\\d+)${HELD}`, "g"), (_m, n) => spans[Number(n)])
+    .replaceAll(/\s+/g, " ")
+    .trim();
+};
+
+const ruleId = (text) => "R-" + createHash("sha256").update(text.toLowerCase()).digest("hex").slice(0, 10);
+
+/**
+ * @param {string} markdown
+ * @param {string} file
+ * @returns {{id: string, text: string, file: string, line: number}[]}
+ */
+export function extractRules(markdown, file) {
+  const rules = [];
+  let fence = null; // the open code fence (``` or ~~~, any length), closed by one as long
+  let comment = false; // inside an HTML comment that has not closed yet
+  let block = null; // the list item or paragraph being read: { line, parts }
+  const flush = () => {
+    const text = block ? plain(block.parts.join(" ")) : "";
+    if (text && NORMATIVE.test(text)) rules.push({ id: ruleId(text), text, file, line: block.line });
+    block = null;
+  };
+  const lines = markdown.split("\n");
+  // A memory file's YAML frontmatter is metadata, not rules.
+  const frontmatterEnd = lines[0]?.trim() === "---" ? lines.indexOf("---", 1) : -1;
+  lines.forEach((raw, i) => {
+    if (i <= frontmatterEnd) return;
+    const mark = /^\s*(`{3,}|~{3,})/.exec(raw)?.[1];
+    if (mark && !fence) { flush(); fence = mark; return; }
+    if (mark && mark[0] === fence[0] && mark.length >= fence.length && raw.trim() === mark) { fence = null; return; }
+    if (fence) return;
+    if (comment || /^\s*<!--/.test(raw)) { flush(); comment = !raw.includes("-->"); return; }
+    if (!raw.trim() || /^\s*#/.test(raw) || /^\s*\|/.test(raw)) { flush(); return; }
+    // KJC-BUG-0271: the unit is the markdown block. A list marker opens a new
+    // one; any other line continues the block it follows (a wrapped rule).
+    if (LIST_ITEM.test(raw)) flush();
+    block ??= { line: i + 1, parts: [] };
+    block.parts.push(raw.trim());
+  });
+  flush();
+  return rules;
+}
+
+/**
+ * The MD files that govern a session in projectDir (KJC-TSK-0942): its CLAUDE.md
+ * and AGENTS.md, the global ~/.claude/CLAUDE.md and the project's feedback memories.
+ * @param {string} projectDir
+ * @param {{home?: string}} [opts]
+ */
+export function ruleSources(projectDir, { home = os.homedir() } = {}) {
+  // Claude Code names a project's folder after its path, every non-alphanumeric char as "-".
+  const memory = path.join(home, ".claude", "projects", path.resolve(projectDir).replaceAll(/[^A-Za-z0-9]/g, "-"), "memory");
+  let feedback = [];
+  try {
+    feedback = fs.readdirSync(memory).filter((f) => /^feedback_.*\.md$/.test(f)).sort().map((f) => path.join(memory, f));
+  } catch { /* no memories for this project */ }
+  return [
+    path.join(projectDir, "CLAUDE.md"),
+    path.join(projectDir, "AGENTS.md"),
+    path.join(home, ".claude", "CLAUDE.md"),
+    ...feedback,
+  ].filter((f) => fs.existsSync(f));
+}
+
+/** Whether an MD file is part of the project, and so as public as the repo is. */
+export const inProject = (file, projectDir) => {
+  const rel = path.relative(projectDir, file);
+  return !rel.startsWith("..") && !path.isAbsolute(rel);
+};
+
+/** A source as a rules file can carry it: from the project's root, or from `~`. */
+export const shownSource = (file, projectDir, home = os.homedir()) => {
+  if (inProject(file, projectDir)) return path.relative(projectDir, file);
+  return inProject(file, home) ? path.join("~", path.relative(home, file)) : file;
+};
+
+/** Every rule of every governing MD file, in source order. */
+export function listRules(projectDir, opts = {}) {
+  return ruleSources(projectDir, opts).flatMap((file) => extractRules(fs.readFileSync(file, "utf8"), file));
+}

package/src/sonar/api.js

@@ -82,6 +82,27 @@ async function sonarFetch(config, urlPath) {
   );
 }
 
+const CE_FINAL = new Set(["SUCCESS", "FAILED", "CANCELED"]);
+const sleepMs = (ms) => new Promise((done) => setTimeout(done, ms));
+
+/**
+ * KJC-BUG-0263 — the scanner uploads the analysis and returns; the server
+ * processes it in the background, and issues read before that task ends are
+ * the PREVIOUS analysis. Polls /api/ce/task until it reaches a final status.
+ * @returns {Promise<{ok: boolean, status: string, timedOut?: boolean}>}
+ */
+export async function waitForAnalysis(config, taskId, { timeoutMs = 120_000, intervalMs = 1000, sleep = sleepMs } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  let status = "UNKNOWN";
+  while (Date.now() < deadline) {
+    const body = await sonarFetch(config, `/api/ce/task?id=${encodeURIComponent(taskId)}`);
+    try { status = JSON.parse(body).task?.status || "UNKNOWN"; } catch { status = "UNKNOWN"; }
+    if (CE_FINAL.has(status)) return { ok: status === "SUCCESS", status };
+    await sleep(intervalMs);
+  }
+  return { ok: false, status, timedOut: true };
+}
+
 /**
  * KJC-BUG-0226 (issue #1838) — de donde sale la clave que se CONSULTA. El
  * scanner sube el analisis con la que el repo declara en su

package/src/sonar/config-resolver.js

@@ -5,7 +5,14 @@
  * Consumers: scanner.js, preflight-checks.js, api.js.
  */
 
+import fs from "node:fs";
+import path from "node:path";
 import { loadSonarCredentials } from "./credentials.js";
+import { getKarajanHome } from "../utils/paths.js";
+
+/** KJC-BUG-0266: the places a token is looked for, named in every "no token" message. */
+export const sonarTokenSources = () =>
+  `KJ_SONAR_TOKEN, sonarqube.token in kj.config.yml, SONAR_TOKEN, ${path.join(getKarajanHome(), "sonar-credentials.json")} or ${sonarTokenFilePath()}`;
 
 const DEFAULT_HOST = "http://localhost:9000";
 
@@ -54,7 +61,18 @@ export async function resolveSonarTokenAsync(config = {}) {
 
   // Check credentials file for persisted token
   const fileCreds = (await loadSonarCredentials()) || {};
-  return fileCreds.token || null;
+  return fileCreds.token || readSonarTokenFile() || null;
+}
+
+/** Where the token bootstrap saves the token (mode 0600), in the active Karajan home. */
+export const sonarTokenFilePath = () => path.join(getKarajanHome(), "sonar.token");
+
+/**
+ * KJC-BUG-0266: the token bootstrap persisted the token to <karajan home>/sonar.token
+ * and no resolver read it back, so a home with only that file looked tokenless.
+ */
+export function readSonarTokenFile() {
+  try { return fs.readFileSync(sonarTokenFilePath(), "utf8").trim() || null; } catch { return null; }
 }
 
 /**

package/src/sonar/scanner.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import os from "node:os";
 import { runCommand } from "../utils/process.js";
 import { sonarUp } from "./manager.js";
+import { waitForAnalysis } from "./api.js";
 import { resolveSonarProjectKey } from "./project-key.js";
 import {
   resolveSonarHost,
@@ -380,14 +381,32 @@ export async function runSonarScan(config, projectKey = null, { verbose = false,
   }
 
   const result = await runCommand(cmd, args, { timeout: scannerTimeout, env, cwd: scanCwd });
+  // KJC-BUG-0263: the scan is done when the server has processed it; whoever reads
+  // the issues next would otherwise get the previous analysis. Said out loud when
+  // the log names no task to wait for.
+  let ok = result.exitCode === 0;
+  let analysisNote = null;
+  if (ok) {
+    const taskId = /api\/ce\/task\?id=([\w-]+)/.exec(String(result.stdout || ""))?.[1];
+    if (taskId) {
+      const done = await waitForAnalysis({ ...config, sonarqube: { ...sonarConfig, host: apiHost } }, taskId);
+      if (!done.ok) {
+        ok = false;
+        analysisNote = `sonar: the server did not finish analysis ${taskId} (${done.status}${done.timedOut ? ", timed out" : ""}) — its issues would be the previous analysis`;
+      }
+    } else {
+      analysisNote = "sonar: the scanner log names no analysis task, so kj could not wait for the server — issues may belong to the previous analysis";
+    }
+  }
   return {
-    ok: result.exitCode === 0,
+    ok,
     projectKey: effectiveProjectKey,
     cwd: scanCwd,
     scanner: pick.type,
-    note,
+    note: [note, analysisNote].filter(Boolean).join("; ") || null,
     stdout: result.stdout,
-    stderr: result.stderr,
+    // A scan that failed on the server's side says so, not with the scanner's own log.
+    stderr: !ok && result.exitCode === 0 ? analysisNote : result.stderr,
     exitCode: result.exitCode
   };
 }

package/src/utils/run-log.js

@@ -8,10 +8,12 @@
  * Log location: <projectDir>/.kj/run.log  (overwritten each run)
  */
 
+import { randomUUID } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 
 const LOG_FILENAME = "run.log";
+const LOCK_FILENAME = "run.lock";
 
 function resolveLogDir(baseDir) {
   return path.join(baseDir || process.cwd(), ".kj");
@@ -54,8 +56,15 @@ export function createRunLog(projectDir) {
   const logDir = resolveLogDir(projectDir);
   ensureDir(logDir);
 
-  // Truncate/create the log file
-  fs.writeFileSync(logPath, `--- Karajan run started at ${new Date().toISOString()} ---\n`);
+  // KJC-BUG-0250: the run lock, taken atomically and owned by this run's token.
+  // close() releases it only while it is still ours (every caller closes in a
+  // finally); a lock whose process is gone is stale and taken over.
+  const startedAt = new Date().toISOString();
+  const lockPath = path.join(logDir, LOCK_FILENAME);
+  const token = randomUUID();
+  const owned = acquireLock(lockPath, { pid: process.pid, startedAt, token });
+  // Truncate/create the log file, unless another live run owns it.
+  if (owned) fs.writeFileSync(logPath, `--- Karajan run started at ${startedAt} ---\n`);
 
   // Audit recommendation (perf-LOW): suggested createWriteStream + queue.
   // Tried it; broke the contract. `readRunLog` (used by `kj_status`,
@@ -102,16 +111,79 @@ export function createRunLog(projectDir) {
         fd = null;
       }
     } catch { /* best-effort */ }
+    if (owned && readLock(lockPath)?.token === token) {
+      try { fs.rmSync(lockPath, { force: true }); } catch { /* best-effort */ }
+    }
   }
 
   return {
     logEvent,
     logText,
     close,
+    /** false when another live run already held the project */
+    owned,
     get path() { return logPath; }
   };
 }
 
+const readLock = (lockPath) => {
+  try { return JSON.parse(fs.readFileSync(lockPath, "utf8")); } catch { return null; }
+};
+
+export const isPidAlive = (pid) => {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; } catch (err) { return err.code === "EPERM"; }
+};
+
+const createExclusive = (file, body) => {
+  try { fs.writeFileSync(file, body, { flag: "wx" }); return true; } catch { return false; }
+};
+
+// The lock appears with its whole content or not at all: written to a private
+// file first, then hard-linked into place (link fails if the path exists), so
+// nobody can read a half-written lock and take it for stale.
+function linkLock(lockPath, body, token) {
+  const tmp = `${lockPath}.${token}.tmp`;
+  try {
+    fs.writeFileSync(tmp, body);
+    fs.linkSync(tmp, lockPath);
+    return true;
+  } catch {
+    return false;
+  } finally {
+    try { fs.rmSync(tmp, { force: true }); } catch { /* leftover, harmless */ }
+  }
+}
+
+function acquireLock(lockPath, holder) {
+  const body = JSON.stringify(holder);
+  if (linkLock(lockPath, body, holder.token)) return true;
+  if (isPidAlive(readLock(lockPath)?.pid)) return false;
+  // Stale (its process is gone, or unreadable). Only one racer at a time may take
+  // it over: the takeover mutex is itself an exclusive create. Inside it the lock
+  // is read again and replaced only if it is still stale; nobody else removes it,
+  // and the exclusive create that follows loses to anyone who got there first.
+  const mutex = `${lockPath}.takeover`;
+  clearStaleMutex(mutex);
+  if (!createExclusive(mutex, holder.token)) return false;
+  try {
+    if (isPidAlive(readLock(lockPath)?.pid)) return false;
+    try { fs.rmSync(lockPath, { force: true }); } catch { return false; }
+    return linkLock(lockPath, body, holder.token);
+  } finally {
+    try { fs.rmSync(mutex, { force: true }); } catch { /* leftover, cleared when stale */ }
+  }
+}
+
+// A takeover takes milliseconds; a mutex older than this was left by a process
+// that died inside one.
+const TAKEOVER_STALE_MS = 10_000;
+function clearStaleMutex(mutex) {
+  try {
+    if (Date.now() - fs.statSync(mutex).mtimeMs > TAKEOVER_STALE_MS) fs.rmSync(mutex, { force: true });
+  } catch { /* none */ }
+}
+
 const KJ_TOOLS = ["kj_run", "kj_code", "kj_plan"];
 
 function detectRunStart(line, status) {

package/src/utils/stack-detect.js

@@ -46,6 +46,9 @@ const LANGUAGE_FILE_MARKERS = [
   { file: "Package.swift", language: "swift", type: "backend" },
 ];
 
+/** A page served as it is: where a static site (or the static half of an app) keeps it. */
+const STATIC_SITE_MARKERS = ["index.html", path.join("public", "index.html"), path.join("src", "index.html")];
+
 /**
  * Maps framework names to skill names for auto-install suggestions.
  */
@@ -109,6 +112,15 @@ export async function detectProjectStack(projectDir) {
     } catch { /* file not found */ }
   }
 
+  // 3. KJC-BUG-0267: a static site has a frontend with no framework to show for it.
+  for (const page of STATIC_SITE_MARKERS) {
+    try {
+      await fs.access(path.join(projectDir, page));
+      hasFrontend = true;
+      break;
+    } catch { /* file not found */ }
+  }
+
   const frameworkList = Array.from(frameworks);
   const isFullstack = hasFrontend && hasBackend;