karajan-code 3.9.0 → 3.10.2

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "karajan-code",
-  "version": "3.9.0",
+  "version": "3.10.2",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",
-  "author": "Manu Fosela <mjfosela@gmail.com>",
+  "author": "manufosela (https://github.com/manufosela)",
   "homepage": "https://github.com/manufosela/karajan-code#readme",
   "repository": {
     "type": "git",

package/scripts/build-sea.mjs

@@ -85,10 +85,16 @@ async function main() {
 
     // ── Step 4: Inject blob with postject ───────────────────────────
     console.log("[4/5] Injecting SEA blob with postject...");
+    // On macOS the blob MUST land as section NODE_SEA_BLOB inside a segment
+    // named NODE_SEA. Without --macho-segment-name postject writes it to a
+    // default segment the SEA loader never inspects, so the binary segfaults
+    // on startup (KJC-BUG-0096, nodejs/postject#76). The flag is Mach-O only —
+    // ELF (Linux) and PE (Windows) don't take it — so add it only on macOS.
     const postjectCmd = [
       `npx postject ${binaryPath}`,
       "NODE_SEA_BLOB dist/sea-prep.blob",
       "--sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2",
+      ...(isMac ? ["--macho-segment-name NODE_SEA"] : []),
     ].join(" ");
     run(postjectCmd);
     console.log("      -> Blob injected.\n");

package/scripts/esbuild-sea.config.mjs

@@ -183,6 +183,15 @@ const ragStubPlugin = {
           parseWhere: notAvailable, buildWhereSql: notAvailable,
           // KJC-TSK-0449 — RAG cross-encoder rerank.
           rerank: notAvailable, RerankError: notAvailable, _resetPipeline: notAvailable,
+          // KJC-BUG-0097 — src/rag/auto-update.js lives under src/rag/ so it is
+          // caught by this stub, but its exports are called on the hot path.
+          // maybeAutoUpdate() runs on EVERY \`kj run\` (run.js): it must be a
+          // silent no-op here (RAG index is unavailable in SEA anyway), NOT an
+          // absent symbol — otherwise the whole command crashes with
+          // "maybeAutoUpdate is not a function". installPostMergeHook() is only
+          // reached from \`kj rag install-hooks\`, so it degrades like the rest.
+          maybeAutoUpdate: async () => ({ skipped: true }),
+          installPostMergeHook: notAvailable,
           default: notAvailable,
         };
       `,

package/scripts/install-binary.ps1

@@ -77,6 +77,13 @@ try {
   } else {
     Write-Host "kj-install: '$installDir' is already on your user PATH — run 'kj --help' to get started."
   }
+
+  # The binary bundles no toolchain. kj orchestrates external tools, so name
+  # the hard requirements and let `kj doctor` check them for this machine.
+  Write-Host ""
+  Write-Host "kj-install: next step — run 'kj doctor' to check prerequisites."
+  Write-Host "  Required: git, plus at least one agent CLI (Claude Code, Codex or Gemini)."
+  Write-Host "  Optional: Docker (local models, SonarQube) and Node/npm (helper tools: Squeezr, qmd)."
 } finally {
   Remove-Item -Path $tmp -Recurse -Force -ErrorAction SilentlyContinue
 }

package/scripts/install-binary.sh

@@ -35,8 +35,18 @@ esac
 
 target="${os}-${arch}"
 case "$target" in
-  linux-x64 | darwin-arm64) ;;
-  *) die "no prebuilt binary for '$target'. Available: linux-x64, darwin-arm64. Use npm instead: npm install -g karajan-code" ;;
+  linux-x64) ;;
+  darwin-arm64)
+    # The macOS standalone binary is not published yet (tracked in
+    # KJC-BUG-0096: the darwin-arm64 SEA build crashes under smoke-test).
+    # Degrade gracefully to the npm install path instead of trying to
+    # download an asset that does not exist.
+    echo "kj-install: the macOS standalone binary is not available yet." >&2
+    echo "kj-install: install with npm instead (requires Node 18+):" >&2
+    echo "  npm install -g karajan-code" >&2
+    exit 0
+    ;;
+  *) die "no prebuilt binary for '$target'. Available: linux-x64. On macOS use npm instead: npm install -g karajan-code" ;;
 esac
 
 # --- Resolve the download URL for the requested version (or latest). ---
@@ -101,3 +111,11 @@ case ":${PATH}:" in
     echo "  (add that line to ~/.bashrc, ~/.zshrc or ~/.profile to make it permanent)"
     ;;
 esac
+
+# --- Prerequisites: the binary bundles no toolchain. kj orchestrates ---
+# --- external tools, so name the hard requirements and let `kj doctor` ---
+# --- check them precisely for this machine.
+echo ""
+echo "kj-install: next step — run 'kj doctor' to check prerequisites."
+echo "  Required: git, plus at least one agent CLI (Claude Code, Codex or Gemini)."
+echo "  Optional: Docker (local models, SonarQube) and Node/npm (helper tools: Squeezr, qmd)."

package/src/commands/doctor.js

@@ -160,6 +160,28 @@ function statusIcon(status) {
   }
 }
 
+// The `kj` binary bundles no toolchain: it orchestrates external tools. So
+// beyond the per-check wall, spell out what is *required* to run kj at all
+// (git + at least one agent CLI) versus what is *optional* (enables extra
+// features). We derive the verdict from the checks already collected rather
+// than re-probing, so it always agrees with the lines printed above.
+function printPrerequisites(report) {
+  const git = report.checks.find((c) => c.name === "git");
+  const agents = report.checks.filter((c) => c.name?.startsWith("agent:"));
+  const okAgent = agents.find((c) => c.status === STATUS.OK);
+  const mark = (ok) => (ok ? "OK" : "MISSING");
+
+  const gitOk = git?.status === STATUS.OK;
+  const agentLabel = okAgent
+    ? `OK (${okAgent.label.replace(/^Agent:\s*/, "")})`
+    : "MISSING — install Claude Code, Codex or Gemini";
+
+  console.log();
+  console.log("Prerequisites (kj orchestrates external tools, it bundles none):");
+  console.log(`  Required: git ${mark(gitOk)}; agent CLI ${agentLabel}`);
+  console.log("  Optional: Docker (local models, SonarQube); Node/npm (helper tools: Squeezr, qmd)");
+}
+
 function printHuman(report, { verbose }) {
   for (const check of report.checks) {
     console.log(`${statusIcon(check.status)} ${check.label}: ${check.detail}`);
@@ -186,6 +208,8 @@ function printHuman(report, { verbose }) {
     console.log(`Runtime overrides applied: ${JSON.stringify(report.overrides)}`);
   }
 
+  printPrerequisites(report);
+
   // KJC-TSK v2.18 — if any external audit tool (semgrep, osv-scanner,
   // lighthouse) reported missing, surface the one-line remediation so
   // the user doesn't have to dig the fix lines out of the wall of
@@ -202,4 +226,4 @@ function printHuman(report, { verbose }) {
   }
 }
 
-export const __test = { printHuman };
+export const __test = { printHuman, printPrerequisites };

package/src/orchestrator/direct-actions.js

@@ -26,6 +26,18 @@ const ALLOWED_COMMANDS = [
   "bundle install", "composer install", "dotnet restore"
 ];
 
+/**
+ * True when `target` resolves to a path inside `base` (or is `base` itself).
+ * Uses path.relative instead of a string prefix check: a naive
+ * `resolved.startsWith(base)` lets a sibling with a shared prefix slip through
+ * (base `/repo/app` would accept `/repo/app2`). Also rejects absolute paths
+ * pointing outside the project.
+ */
+function isInsideBase(target, base) {
+  const rel = path.relative(base, target);
+  return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+
 /**
  * Validate that a shell command is in the allow-list.
  * Prevents arbitrary command execution.
@@ -74,7 +86,7 @@ async function createFile({ filePath, content, cwd, overwrite = false }) {
     // Path traversal guard
     const resolved = path.resolve(fullPath);
     const base = path.resolve(cwd || process.cwd());
-    if (!resolved.startsWith(base)) {
+    if (!isInsideBase(resolved, base)) {
       return { ok: false, error: "Path traversal denied", action: "create_file" };
     }
 
@@ -130,9 +142,10 @@ async function gitAdd({ files, cwd }) {
   }
 
   try {
-    // Only allow relative paths (no absolute paths, no shell metacharacters)
+    // Reject shell metacharacters and anything that resolves outside the project.
+    const base = path.resolve(cwd || process.cwd());
     for (const f of files) {
-      if (typeof f !== "string" || f.includes("..") || /[;&|`$]/.test(f)) {
+      if (typeof f !== "string" || /[;&|`$]/.test(f) || !isInsideBase(path.resolve(base, f), base)) {
         return { ok: false, error: `Invalid file path: ${f}`, action: "git_add" };
       }
     }

package/src/orchestrator/stages/triage-stage.js

@@ -11,6 +11,20 @@ import { createStallDetector } from "../../utils/stall-detector.js";
 
 const ROLE_NAMES = ["planner", "researcher", "architect", "refactorer", "reviewer", "tester", "security", "impeccable"];
 
+// What each role is for. Used to explain — deterministically — why triage would
+// or would not turn a role on. These describe the role's trigger, never a claim
+// about the current task, so the rationale is never invented per run.
+const ROLE_PURPOSE = {
+  planner: "planificación multi-fichero",
+  researcher: "investigación de contexto externo",
+  architect: "decisiones de arquitectura",
+  refactorer: "refactor de código existente",
+  reviewer: "revisión de cambios",
+  tester: "cobertura de tests dedicada",
+  security: "auditoría de seguridad",
+  impeccable: "auditoría de diseño"
+};
+
 function buildRoleOverrides(recommendedRoles, pipelineConfig) {
   const overrides = {};
   for (const role of ROLE_NAMES) {
@@ -19,6 +33,28 @@ function buildRoleOverrides(recommendedRoles, pipelineConfig) {
   return overrides;
 }
 
+// Per-role explanation of the activate/skip decision, mirroring buildRoleOverrides.
+// When triage failed, recommendations are unavailable: roles resolve from config
+// alone and skipped ones get a neutral "sin datos de triage" reason.
+function buildRoleRationale(recommendedRoles, pipelineConfig, triageOk) {
+  return ROLE_NAMES.map((role) => {
+    const forced = Boolean(pipelineConfig[role]?.enabled);
+    const recommended = triageOk && recommendedRoles.has(role);
+    const purpose = ROLE_PURPOSE[role];
+
+    if (recommended) {
+      return { role, enabled: true, source: "triage", reason: `recomendado por triage — ${purpose}` };
+    }
+    if (forced) {
+      return { role, enabled: true, source: "config", reason: `forzado por configuración — ${purpose}` };
+    }
+    const reason = triageOk
+      ? `no recomendado — ${purpose} sin aplicar`
+      : `sin datos de triage — ${purpose} sin evaluar`;
+    return { role, enabled: false, source: "none", reason };
+  });
+}
+
 function applyModelSelection(triageOutput, config, emitter, eventBase) {
   if (!triageOutput.ok || !config?.model_selection?.enabled) return null;
   const level = triageOutput.result?.level;
@@ -104,7 +140,8 @@ export async function runTriageStage({ config, logger, emitter, eventBase, sessi
     taskType: triageOutput.result?.taskType || "sw",
     shouldDecompose,
     subtasks,
-    domainHints
+    domainHints,
+    roleRationale: buildRoleRationale(recommendedRoles, config.pipeline || {}, triageOutput.ok)
   };
 
   const modelSelection = applyModelSelection(triageOutput, config, emitter, eventBase);

package/src/utils/display/event-handlers.js

@@ -69,6 +69,20 @@ export const EVENT_HANDLERS = {
     console.log(`  \u251c\u2500 ${icon} TDD policy: ${label}${files}${executor}`);
   },
 
+  "triage:end": (event, icon, elapsed, status) => {
+    const detail = event.detail || {};
+    const level = detail.level ? ` ${detail.level}` : "";
+    const onCount = detail.roles?.length || 0;
+    console.log(
+      `  \u251c\u2500 ${icon} ${status} Triage${level}${ANSI.dim} \u2014 ${onCount} role(s) on${ANSI.reset}  ${elapsed}`
+    );
+    // Per-role rationale: why each role was activated or skipped (KJC-TSK-0601).
+    for (const entry of detail.roleRationale || []) {
+      const mark = entry.enabled ? `${ANSI.green}\u2713${ANSI.reset}` : `${ANSI.dim}\u2717${ANSI.reset}`;
+      console.log(`  \u2502    ${mark} ${ANSI.dim}${entry.role}: ${entry.reason}${ANSI.reset}`);
+    }
+  },
+
   "researcher:start": (event, icon) => {
     console.log(`  \u251c\u2500 ${icon} Researcher (${event.detail?.researcher || "?"}) investigating...`);
   },