karajan-code 4.70.0 → 4.70.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "4.70.0",
+  "version": "4.70.2",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

package/src/checks/native-build.js

@@ -9,8 +9,43 @@
  * WARN in `kj doctor` with the exact remedy instead of a cryptic runtime crash.
  */
 
+import { execFileSync } from "node:child_process";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
 import { STRATEGY } from "./types.js";
 
+// kj's own package root: where npm keeps its dependencies' approvals and builds.
+const OWN_PKG_DIR = resolve(fileURLToPath(new URL("../..", import.meta.url)));
+
+/** npm's major version, or null when npm is not there to ask. */
+function defaultNpmMajor() {
+  try {
+    return Number.parseInt(execFileSync("npm", ["--version"], { encoding: "utf8", timeout: 10_000 }), 10) || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * KJC-BUG-0426 (issue #2670): npm 12 runs a dependency's install script only when
+ * allowScripts covers it; reinstalling blocks it again. Approve, then rebuild, in kj's dir.
+ */
+export const npmAllowScriptsRemedy = (pkgDir = OWN_PKG_DIR) =>
+  `cd "${pkgDir}" && npm install-scripts approve better-sqlite3 && npm install-scripts approve node-pty && npm rebuild better-sqlite3 node-pty`;
+
+// The addon is installed but its native build is missing (a missing package needs a reinstall, not this).
+const UNBUILT_ADDON = /bindings file|better_sqlite3\.node/;
+
+/** A missing better-sqlite3 addon becomes an error that says how to build it; any other error passes as it is. */
+export function explainNativeLoadError(err, { npmMajor = defaultNpmMajor, pkgDir = OWN_PKG_DIR } = {}) {
+  if (!UNBUILT_ADDON.test(String(err?.message ?? err))) return err;
+  const remedy = (npmMajor() ?? 0) >= 12
+    ? `npm 12 skipped its install script (allowScripts); build it with: ${npmAllowScriptsRemedy(pkgDir)}`
+    : "run kj doctor for the exact fix on this install";
+  return new Error(`better-sqlite3 native addon is not built, so the RAG cannot open its index — ${remedy}`, { cause: err });
+}
+
 /** pnpm lays packages out under a `.pnpm` virtual store and symlinks them in. */
 function isPnpmInstall() {
   return (
@@ -25,7 +60,7 @@ async function defaultLoadDb() {
   new Database(":memory:").close();
 }
 
-export function createNativeBuildCheck({ loadDb = defaultLoadDb, isPnpm = isPnpmInstall } = {}) {
+export function createNativeBuildCheck({ loadDb = defaultLoadDb, isPnpm = isPnpmInstall, npmMajor = defaultNpmMajor, pkgDir = OWN_PKG_DIR } = {}) {
   return {
     name: "native-build",
     label: "native modules (better-sqlite3)",
@@ -48,6 +83,14 @@ export function createNativeBuildCheck({ loadDb = defaultLoadDb, isPnpm = isPnpm
             fix: "Approve the build then reinstall: `pnpm approve-builds better-sqlite3` — or install with npm: `npm i -g @karajan-family/code`",
           };
         }
+        if ((npmMajor() ?? 0) >= 12) {
+          return {
+            ok: false,
+            severity: "warn",
+            detail: `better-sqlite3 failed to load: ${firstLine} — npm 12 skips dependency install scripts that allowScripts does not cover, so the native build never ran`,
+            fix: npmAllowScriptsRemedy(pkgDir),
+          };
+        }
         return {
           ok: false,
           severity: "warn",

package/src/commands/harden.js

@@ -219,7 +219,10 @@ export async function hardenCommand({
     const note = c.note ? ` (${c.note})` : "";
     logger.info?.(`  • ${c.file}: ${c.action}${note}`);
   }
-  for (const w of out.workflows) logger.info?.(`  • ${w.file}: ${w.action}`);
+  for (const w of out.workflows) {
+    logger.info?.(`  • ${w.file}: ${w.action}`);
+    if (w.note) logger.warn?.(`⚠ ${w.note}`);
+  }
   for (const g of out.guidelines) {
     logger.info?.(`  • ${g.file}: ${g.action}`);
     // KJC-BUG-0206: quitar reglas no puede leerse como "updated" y nada más.

package/src/config/loader.js

@@ -119,7 +119,9 @@ export async function loadConfig(projectDir) {
   // a .karajan dir from another repo, edited the wrong file, etc.) and
   // would silently behave like a global config without the defaults
   // people expect. Refuse with an actionable message.
-  if (projectConfig && !globalExists) {
+  // KJC-BUG-0428 (issue #2694): a CI runner never has a global config; there the
+  // team's committed project config sits on the defaults instead.
+  if (projectConfig && !globalExists && !process.env.CI) {
     throw new Error(
       `Local config found at ${getProjectConfigPath(projectDir)} but no global config exists.\n` +
       "Local configs are merged ON TOP of the global one — run `kj init --global` first to create the base."

package/src/harden/sentinel/pretooluse-sentinel.mjs

@@ -84,8 +84,9 @@ process.stdin.on("end", () => {
     // substitution) cannot be resolved from command text: that vector is
     // caught by the Stop gate's checksum verification, which blocks the turn.
     // KJC-TSK-1114: where the host sandbox denies writing them, the sandbox guards them instead.
+    // KJC-BUG-0425 (ADR 0036): text a command only publishes or stores (a PR description) is not a write.
     const SUPERVISOR_PATHS = [".claude/settings.json", ".karajan/hooks", ".karajan/harness"];
-    if (tool === "Bash" && PROTECTED.test(String(input.command || "").replaceAll("\\", "/")) && !sandboxCovers(ROOT, SUPERVISOR_PATHS)) {
+    if (tool === "Bash" && PROTECTED.test(stripTextOnlyCommandValues(String(input.command || "")).replaceAll("\\", "/")) && !sandboxCovers(ROOT, SUPERVISOR_PATHS)) {
       console.error("karajan sentinel: los ficheros del supervisor no se tocan desde Bash — consultalos con la tool Read/Grep; solo el humano los modifica, fuera de la sesion." + doc("supervisor"));
       process.exit(2);
     }

package/src/harden/sentinel/sentinel-shell.mjs

@@ -174,7 +174,22 @@ const isGitCommit = (words) => {
   return words[0] === "git" && words[i] === "commit";
 };
 
-const isTextOnlyHead = (seg) => /^kj\s+(?:hu|adr|handoff)\s+add\b/.test(seg) || isGitCommit(seg.split(/\s+/));
+// KJC-BUG-0425: gh pr/issue/release commands only publish their text to GitHub.
+const isTextOnlyHead = (seg) => /^kj\s+(?:hu|adr|handoff)\s+add\b/.test(seg) || /^gh\s+(?:pr|issue|release)\s+(?:create|edit|comment|review)\b/.test(seg) || isGitCommit(seg.split(/\s+/));
+
+// KJC-BUG-0425: a heredoc whose delimiter is quoted expands nothing; read from stdin
+// by a text-only command, it is the text stored or published. The FIRST line equal to
+// the delimiter must be the last one, or the shell would run what follows it.
+const HEREDOC_HEAD = /^([^\n]*?)[ \t]*<<(-?)[ \t]*(['"])([A-Za-z_]\w*)\3[ \t]*$/;
+const READS_STDIN = /(^|\s)(?:--body-file|--notes-file|--file|-F)(?:=|\s+)-(?=\s|$)/;
+const quotedHeredocHead = (cmd) => {
+  const lines = cmd.replace(/\n$/, "").split("\n");
+  const m = lines.length > 1 ? HEREDOC_HEAD.exec(lines[0]) : null;
+  if (!m) return null;
+  const [, head, dash, , delim] = m;
+  const end = lines.findIndex((l, i) => i > 0 && (dash ? l.replace(/^\t+/, "") : l) === delim);
+  return end === lines.length - 1 && READS_STDIN.test(head) ? head : null;
+};
 
 /**
  * KJC-BUG-0354: blank the quoted text values (stripTextOptionValues) only when the
@@ -185,9 +200,10 @@ const isTextOnlyHead = (seg) => /^kj\s+(?:hu|adr|handoff)\s+add\b/.test(seg) ||
 export const stripTextOnlyCommandValues = (cmd) => {
   // Only a whole input that is ONE simple text-storage command: a chained
   // segment could follow a shell function that turns the stored text into code.
-  const bare = stripInertQuotes(cmd);
-  if (splitOutsideQuotes(cmd).length !== 1 || /[(){}<>`$\n]/.test(bare) || !isTextOnlyHead(cmd.trim())) return cmd;
-  return stripTextOptionValues(cmd);
+  const line = quotedHeredocHead(cmd) ?? cmd;
+  const bare = stripInertQuotes(line);
+  if (splitOutsideQuotes(line).length !== 1 || /[(){}<>`$\n]/.test(bare) || !isTextOnlyHead(line.trim())) return cmd;
+  return stripTextOptionValues(line);
 };
 
 /** Segments and the ; && || | between them, cut only outside quotes (the pieces join back to cmd). */

package/src/harden/workflow-engine.js

@@ -16,6 +16,13 @@ import { parse as parseYaml } from "yaml";
 import { upsertManagedBlock } from "../utils/managed-markers.js";
 import { extraWorkflowsFor, mutationWorkflowFor, qualityWorkflowFor, policyWorkflowFor, stewardWorkflowFor, WORKFLOWS } from "./workflow-templates.js";
 
+// KJC-BUG-0424: on the PR that brings this change GitHub runs neither YAML (the base's
+// listens to pull_request, the new one to pull_request_target), so policy-check never reports.
+export const POLICY_TRIGGER_MOVE_NOTE =
+  "kj-policy.yml moves from pull_request to pull_request_target (judged from the base branch). " +
+  "The PR that brings this change gets no policy-check run: if policy-check is a required check, " +
+  "merge that one PR as an admin after the other checks pass; from then on the base runs the judge.";
+
 // La versión del kj que corre harden — es la que se pinea en el fallback
 // npx del workflow de policy (jamás @latest en CI). Lectura LAZY: en el
 // bundle SEA no hay package.json junto al módulo y una lectura eager a
@@ -125,7 +132,9 @@ export function installWorkflows({
       // pre-commit rechaza el fichero recién generado.
       writeFileSync(target, content.endsWith("\n") ? content : `${content}\n`);
     }
-    results.push({ file: label, action });
+    // KJC-BUG-0424: the PR that moves the trigger cannot report policy-check.
+    const movesTrigger = wf.blockId === "wf-policy" && action !== "unchanged" && /^\s*pull_request:\s*$/m.test(source);
+    results.push({ file: label, action, ...(movesTrigger ? { note: POLICY_TRIGGER_MOVE_NOTE } : {}) });
   }
   return { dryRun, workflows: results };
 }

package/src/harden/workflow-templates.js

@@ -69,10 +69,13 @@ export const WORKFLOWS = [
 // npx PINEADO a la versión del kj que corrió harden — jamás @latest en CI.
 // KJC-BUG-0399: the judge is never the PR's code. A repo that ships kj itself
 // judges with the kj of the BASE branch, checked out apart; the PR is only data.
+// KJC-BUG-0419: on `pull_request` GitHub runs the PR's own copy of this YAML, so a
+// PR could rewrite its judge. `pull_request_target` runs the base's YAML; the PR
+// is fetched into its own worktree, read by kj and never installed nor executed.
 export const policyWorkflowFor = (kjVersion, kjName = "karajan-code") => [
   "name: Policy",
   "on:",
-  "  pull_request:",
+  "  pull_request_target:",
   "permissions:",
   "  contents: read",
   "jobs:",
@@ -88,16 +91,23 @@ export const policyWorkflowFor = (kjVersion, kjName = "karajan-code") => [
   "      - name: kj policy check (strict) on the PR diff",
   "        env:",
   "          BASE_REF: ${{ github.base_ref }}",
+  "          PR_NUMBER: ${{ github.event.pull_request.number }}",
   "        run: |",
   '          JUDGE="$RUNNER_TEMP/kj-judge"',
+  '          PR_TREE="$RUNNER_TEMP/kj-pr"',
   '          git fetch --no-tags origin "${BASE_REF}:refs/remotes/origin/${BASE_REF}"',
+  '          git fetch --no-tags origin "+refs/pull/${PR_NUMBER}/head:refs/remotes/origin/kj-pr-head"',
   '          if git cat-file -e "origin/${BASE_REF}:bin/kj.js" 2>/dev/null; then',
   '            git worktree add --detach "$JUDGE" "origin/${BASE_REF}"',
   '            (cd "$JUDGE" && npm ci --ignore-scripts)',
   '            KJ="node $JUDGE/bin/kj.js"',
   "          else",
-  `            KJ="npx --yes ${kjName}@${kjVersion}"`,
+  '            mkdir -p "$JUDGE"',
+  `            (cd "$JUDGE" && echo '{"private":true}' > package.json && npm install --no-save --ignore-scripts --no-audit --no-fund ${kjName}@${kjVersion})`,
+  `            KJ="node $JUDGE/node_modules/${kjName}/bin/kj.js"`,
   "          fi",
+  '          git worktree add --detach "$PR_TREE" origin/kj-pr-head',
+  '          cd "$PR_TREE"',
   '          $KJ policy check --range "origin/${BASE_REF}...HEAD" --strict',
 ].join("\n");
 

package/src/policy/add.js

@@ -11,6 +11,7 @@ import yaml from "js-yaml";
 import { parsePolicy } from "@karajan-family/governance";
 import { createAgent } from "../agents/index.js";
 import { resolveRole } from "../config/role-resolver.js";
+import { agentAnswerText } from "../review/parser.js";
 
 const PROMPT = (text) => `Traduce esta regla de proyecto hablada a un FRAGMENTO YAML del vocabulario
 cerrado v1 de policy de Karajan. Vocabulario COMPLETO (nada fuera de esto):
@@ -27,7 +28,8 @@ async function defaultTranslate({ text, config, logger }) {
   const role = resolveRole(config, "reviewer");
   const res = await createAgent(role.provider, config, logger).reviewTask({ prompt: PROMPT(text), role: "reviewer" });
   if (!res?.ok) throw new Error(`el agente traductor (${role.provider}) falló: ${res?.error || "sin salida"}`);
-  return String(res.output || "").replace(/^```[a-z]*\n?|```\s*$/g, "").trim();
+  // KJC-BUG-0430 (issue #2695): claude answers with its stream-json; the answer is its final result.
+  return String(agentAnswerText(res.output) || "").replace(/^```[a-z]*\n?|```\s*$/g, "").trim();
 }
 
 // Merge conservador: las listas se CONCATENAN (añadir jamás borra), los

package/src/rag/migrate.js

@@ -9,7 +9,8 @@
 import { existsSync } from "node:fs";
 import { sep } from "node:path";
 
-import { openVecStore, insertChunk, getLastIndexedCommit, setLastIndexedCommit } from "./vec-store.js";
+import { insertChunk, getLastIndexedCommit, setLastIndexedCommit } from "./vec-store.js";
+import { openVecStoreExplained as openVecStore } from "./project-store.js";
 
 export const countProjectChunks = (db, slug) => db.prepare("SELECT COUNT(*) AS n FROM chunks WHERE project_slug = ?").get(slug).n;
 

package/src/rag/project-store.js

@@ -17,6 +17,7 @@ import { execFileSync } from "node:child_process";
 import path from "node:path";
 
 import { openVecStore } from "./vec-store.js";
+import { explainNativeLoadError } from "../checks/native-build.js";
 import { getKarajanHome } from "../utils/paths.js";
 
 function projectRoot(dir) {
@@ -39,10 +40,20 @@ export function libraryDbPath() {
   return process.env.KJ_LIBRARY_DB || path.join(getKarajanHome(), "library.db");
 }
 
+// KJC-BUG-0426: an unbuilt better-sqlite3 addon says how to build it, not "bindings file".
+// Every opening of a RAG store goes through here.
+export function openVecStoreExplained(opts) {
+  try {
+    return openVecStore(opts);
+  } catch (err) {
+    throw explainNativeLoadError(err);
+  }
+}
+
 export function openLibraryStore({ dim = 768 } = {}) {
-  return openVecStore({ dim, path: libraryDbPath() });
+  return openVecStoreExplained({ dim, path: libraryDbPath() });
 }
 
 export function openProjectStore({ projectDir = process.cwd(), dim = 768 } = {}) {
-  return openVecStore({ dim, path: projectDbPath(projectDir) });
+  return openVecStoreExplained({ dim, path: projectDbPath(projectDir) });
 }