karajan-code 4.1.0 → 4.1.2

package/package.json

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

package/scripts/install-binary.sh

@@ -1,31 +1,36 @@
 #!/bin/sh
-# Karajan Code — standalone binary installer (no Node required).
+# Karajan Code installer — guarantees a COMPLETE install (KJC-TSK-0658).
 #
 #   curl -fsSL https://karajancode.com/install.sh | sh
 #
-# Downloads the prebuilt `kj` binary for your OS/arch from the GitHub
-# release, verifies its SHA256 checksum, and installs it to ~/.local/bin.
-# Override with env vars: KJ_VERSION (e.g. v3.7.2), KJ_INSTALL_DIR.
+# Default route: npm — the full product (CLI + RAG + HU Board + MCP).
+#   1. Node >= 22.12 present  → npm install -g karajan-code
+#   2. No usable Node         → auto-provision official Node LTS into
+#      ~/.karajan/node (checksum-verified, nothing system-wide touched),
+#      install karajan-code with it, symlink kj into ~/.local/bin.
+# Standalone route (CLI only, no native-module features — RAG/board/MCP
+# unavailable): opt-in with `--standalone` or KJ_STANDALONE=1.
 #
-# POSIX sh only — no bashisms, no Node. KJC-TSK-0593.
+# POSIX sh only. Env overrides: KJ_VERSION, KJ_INSTALL_DIR.
 set -eu
 
 REPO="manufosela/karajan-code"
 VERSION="${KJ_VERSION:-latest}"
 INSTALL_DIR="${KJ_INSTALL_DIR:-$HOME/.local/bin}"
+NODE_MAJOR="22"
+NODE_MIN_MINOR="12"
+MODE="full"
+[ "${1:-}" = "--standalone" ] && MODE="standalone"
+[ "${KJ_STANDALONE:-0}" = "1" ] && MODE="standalone"
 
-die() {
-  echo "kj-install: $1" >&2
-  exit 1
-}
+die() { echo "kj-install: $1" >&2; exit 1; }
 
-# --- Detect OS/arch, map to the release asset names we actually build. ---
-os="$(uname -s)"
-arch="$(uname -m)"
+# --- Detect OS/arch (shared by both routes). ---
+os="$(uname -s)"; arch="$(uname -m)"
 case "$os" in
   Linux) os="linux" ;;
   Darwin) os="darwin" ;;
-  *) die "unsupported OS '$os'. Supported: Linux, macOS. Use npm instead: npm install -g karajan-code" ;;
+  *) die "unsupported OS '$os'. Supported: Linux, macOS." ;;
 esac
 case "$arch" in
   x86_64 | amd64) arch="x64" ;;
@@ -33,80 +38,122 @@ case "$arch" in
   *) die "unsupported architecture '$arch'" ;;
 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" ;;
-esac
+# --- Downloader + checksum tool. ---
+if command -v curl >/dev/null 2>&1; then fetch() { curl -fsSL "$1" -o "$2"; }
+elif command -v wget >/dev/null 2>&1; then fetch() { wget -qO "$2" "$1"; }
+else die "need curl or wget"; fi
+if command -v sha256sum >/dev/null 2>&1; then sha256() { sha256sum "$1" | cut -d' ' -f1; }
+elif command -v shasum >/dev/null 2>&1; then sha256() { shasum -a 256 "$1" | cut -d' ' -f1; }
+else die "need sha256sum or shasum to verify downloads"; fi
 
-# --- Resolve the download URL for the requested version (or latest). ---
-asset="kj-${target}"
-if [ "$VERSION" = "latest" ]; then
-  base="https://github.com/${REPO}/releases/latest/download"
-else
-  base="https://github.com/${REPO}/releases/download/${VERSION}"
-fi
+tmp="$(mktemp -d "${TMPDIR:-/tmp}/kj-install.XXXXXX")"
+trap 'rm -rf "$tmp"' EXIT INT TERM
 
-# --- Pick a downloader. ---
-if command -v curl >/dev/null 2>&1; then
-  fetch() { curl -fsSL "$1" -o "$2"; }
-elif command -v wget >/dev/null 2>&1; then
-  fetch() { wget -qO "$2" "$1"; }
-else
-  die "need curl or wget to download the binary"
-fi
+path_hint() {
+  case ":${PATH}:" in
+    *":$1:"*) ;;
+    *) echo "kj-install: add '$1' to your PATH:  export PATH=\"$1:\$PATH\"  (persist it in ~/.bashrc / ~/.zshrc)" ;;
+  esac
+}
+
+# --- Is there a usable Node (>= NODE_MAJOR.NODE_MIN_MINOR)? ---
+node_ok() {
+  command -v node >/dev/null 2>&1 || return 1
+  v="$(node --version 2>/dev/null | sed 's/^v//')"
+  major="${v%%.*}"; rest="${v#*.}"; minor="${rest%%.*}"
+  [ "$major" -gt "$NODE_MAJOR" ] 2>/dev/null && return 0
+  [ "$major" -eq "$NODE_MAJOR" ] 2>/dev/null && [ "$minor" -ge "$NODE_MIN_MINOR" ] 2>/dev/null
+}
+
+npm_pkg() { if [ "$VERSION" = "latest" ]; then echo "karajan-code"; else echo "karajan-code@${VERSION#v}"; fi; }
+
+if [ "$MODE" = "full" ]; then
+  if node_ok; then
+    echo "kj-install: Node $(node --version) found — installing via npm (full product)..."
+    npm install -g "$(npm_pkg)" || die "npm install failed. If it was a permissions error, set a user prefix (npm config set prefix ~/.local) and re-run."
+    echo "kj-install: installed $(kj --version 2>/dev/null || echo karajan-code). Run 'kj doctor' next."
+    exit 0
+  fi
 
-# --- Pick a checksum tool. ---
-if command -v sha256sum >/dev/null 2>&1; then
-  sha256() { sha256sum "$1" | cut -d' ' -f1; }
-elif command -v shasum >/dev/null 2>&1; then
-  sha256() { shasum -a 256 "$1" | cut -d' ' -f1; }
-else
-  die "need sha256sum or shasum to verify the download"
+  echo "kj-install: no usable Node (need >= ${NODE_MAJOR}.${NODE_MIN_MINOR}) — provisioning official Node LTS into ~/.karajan/node (nothing system-wide)..."
+  dist="https://nodejs.org/dist/latest-v${NODE_MAJOR}.x"
+  fetch "${dist}/SHASUMS256.txt" "${tmp}/SHASUMS256.txt" || die "could not fetch the Node checksum list"
+  node_asset="$(grep -o "node-v[0-9.]*-${os}-${arch}\.tar\.gz" "${tmp}/SHASUMS256.txt" | head -1)"
+  [ -n "$node_asset" ] || die "no official Node build for ${os}-${arch}"
+  echo "kj-install: downloading ${node_asset}..."
+  fetch "${dist}/${node_asset}" "${tmp}/${node_asset}" || die "could not download Node"
+  expected="$(grep "${node_asset}\$" "${tmp}/SHASUMS256.txt" | head -1 | cut -d' ' -f1)"
+  actual="$(sha256 "${tmp}/${node_asset}")"
+  [ "$expected" = "$actual" ] || die "Node checksum mismatch — aborting, nothing installed"
+
+  # Stage the whole install (extract + npm install) in a sibling dir and only
+  # swap it into place once EVERYTHING succeeded — a failed download/extract/
+  # install must never destroy a previous working ~/.karajan/node.
+  node_home="$HOME/.karajan/node"
+  staging="${node_home}.staging.$$"
+  rm -rf "$staging"; mkdir -p "$staging"
+  trap 'rm -rf "$tmp" "$staging"' EXIT INT TERM
+  tar -xzf "${tmp}/${node_asset}" -C "$staging" --strip-components=1 || die "could not extract Node"
+
+  echo "kj-install: installing karajan-code with the provisioned Node..."
+  PATH="${staging}/bin:$PATH" "${staging}/bin/npm" install -g "$(npm_pkg)" || die "npm install failed with the provisioned Node"
+
+  # Swap keeping the previous install recoverable at EVERY instant: park it
+  # as a backup, arm a trap that restores it on any exit (signal included),
+  # move the staged one in, and only then disarm the trap and drop the
+  # backup — the user can never end up without a working install.
+  backup="${node_home}.old.$$"
+  if [ -e "$node_home" ]; then
+    mv "$node_home" "$backup" || die "could not park the previous install"
+    trap '[ -e "$node_home" ] || mv "$backup" "$node_home" 2>/dev/null; rm -rf "$tmp" "$staging"' EXIT INT TERM
+  fi
+  mv "$staging" "$node_home" || die "could not move the staged install into place (previous install restored)"
+  trap 'rm -rf "$tmp"' EXIT INT TERM
+  rm -rf "$backup"
+  mkdir -p "$INSTALL_DIR"
+  # Wrappers, not symlinks: the shebang (#!/usr/bin/env node) must find the
+  # provisioned Node even though it is not on the user's PATH.
+  for bin in kj karajan-mcp; do
+    [ -e "${node_home}/bin/${bin}" ] || continue
+    {
+      echo '#!/bin/sh'
+      echo "export PATH=\"${node_home}/bin:\$PATH\""
+      echo "exec \"${node_home}/bin/${bin}\" \"\$@\""
+    } >"${INSTALL_DIR}/${bin}"
+    chmod +x "${INSTALL_DIR}/${bin}"
+  done
+  installed="$("${INSTALL_DIR}/kj" --version 2>/dev/null || echo '?')"
+  echo "kj-install: installed kj ${installed} (full product) — kj at ${INSTALL_DIR}/kj"
+  path_hint "$INSTALL_DIR"
+  echo "kj-install: next — run 'kj doctor', then 'kj install-tools' to complete the whole stack."
+  exit 0
 fi
 
-# --- Download to a temp dir; only install after the checksum matches. ---
-tmp="$(mktemp -d "${TMPDIR:-/tmp}/kj-install.XXXXXX")"
-trap 'rm -rf "$tmp"' EXIT INT TERM
+# --- Standalone route: prebuilt single binary (CLI only). ---
+echo "kj-install: standalone mode — single binary, NO native-module features (RAG, HU Board and MCP need the npm install)."
+target="${os}-${arch}"
+case "$target" in
+  linux-x64 | darwin-arm64) ;;
+  *) die "no prebuilt binary for '$target' (available: linux-x64, darwin-arm64) — run without --standalone for the npm route" ;;
+esac
+asset="kj-${target}"
+if [ "$VERSION" = "latest" ]; then base="https://github.com/${REPO}/releases/latest/download"
+else base="https://github.com/${REPO}/releases/download/${VERSION}"; fi
 
 echo "kj-install: downloading ${asset} (${VERSION})..."
-fetch "${base}/${asset}" "${tmp}/kj" || die "could not download ${base}/${asset} — does that version/asset exist?"
+fetch "${base}/${asset}" "${tmp}/kj" || die "could not download ${base}/${asset}"
 fetch "${base}/${asset}.sha256" "${tmp}/kj.sha256" || die "could not download the checksum for ${asset}"
-
 expected="$(cut -d' ' -f1 <"${tmp}/kj.sha256")"
 actual="$(sha256 "${tmp}/kj")"
-[ "$expected" = "$actual" ] || die "checksum mismatch (expected ${expected}, got ${actual}). Aborting, nothing installed."
+[ "$expected" = "$actual" ] || die "checksum mismatch — aborting, nothing installed"
 
-# --- Install atomically: chmod on the temp file, then move into place. ---
 chmod +x "${tmp}/kj"
 mkdir -p "$INSTALL_DIR"
 mv -f "${tmp}/kj" "${INSTALL_DIR}/kj"
-
-# On macOS the binary is ad-hoc signed, not notarized with a paid Apple
-# certificate, so Gatekeeper can quarantine it. Clear the flag on the copy
-# we just checksummed ourselves (no-op on Linux / if the flag is absent).
 if [ "$os" = "darwin" ] && command -v xattr >/dev/null 2>&1; then
   xattr -d com.apple.quarantine "${INSTALL_DIR}/kj" 2>/dev/null || true
 fi
-
 installed="$("${INSTALL_DIR}/kj" --version 2>/dev/null || echo '?')"
-echo "kj-install: installed kj ${installed} to ${INSTALL_DIR}/kj"
-
-# --- Tell the user how to reach it if the dir is not on PATH. ---
-case ":${PATH}:" in
-  *":${INSTALL_DIR}:"*) echo "kj-install: '${INSTALL_DIR}' is on your PATH — run 'kj --help' to get started." ;;
-  *)
-    echo "kj-install: '${INSTALL_DIR}' is not on your PATH. Add it with:"
-    echo "  export PATH=\"${INSTALL_DIR}:\$PATH\""
-    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)."
+echo "kj-install: installed standalone kj ${installed} to ${INSTALL_DIR}/kj"
+path_hint "$INSTALL_DIR"
+echo "kj-install: next — run 'kj doctor'. For the full product later: re-run this installer without --standalone."

package/src/checks/mcp-health.js

@@ -102,8 +102,14 @@ export function createKarajanMcpCheck() {
       return {
         ok: result.ok,
         severity: result.ok ? "info" : "warn",
-        detail: result.ok ? result.detail : `karajan-mcp did not respond: ${result.detail}`,
-        fix: result.ok ? undefined : "Re-run karajan-mcp via `node bin/karajan-mcp.js`",
+        // KJC-BUG-0118: the MCP is OPTIONAL in the v4 environment (the host
+        // agent drives kj via CLI) — a dead MCP must read as a degraded
+        // optional, never as a broken install. The standalone (curl) binary
+        // cannot run it at all (no bundled native modules).
+        detail: result.ok
+          ? result.detail
+          : `karajan-mcp did not respond: ${result.detail} — OPTIONAL in v4: your agent runs kj directly; only shell-less hosts need MCP`,
+        fix: result.ok ? undefined : "Only if you need MCP: install via npm (`npm i -g karajan-code`) — the standalone binary does not bundle it",
         extra: { binPath },
       };
     },

package/src/checks/native-build.js

@@ -51,7 +51,10 @@ export function createNativeBuildCheck({ loadDb = defaultLoadDb, isPnpm = isPnpm
         return {
           ok: false,
           severity: "warn",
-          detail: `better-sqlite3 failed to load: ${firstLine}`,
+          // KJC-BUG-0118: the standalone (curl) binary ships without native
+          // modules by design — name the consequence (RAG/board/MCP need the
+          // npm install) instead of implying the install is broken.
+          detail: `better-sqlite3 failed to load: ${firstLine} — DB-backed features (RAG, board, MCP) unavailable; the standalone binary does not bundle native modules`,
           fix: "Reinstall to rebuild native modules: `npm i -g karajan-code`",
         };
       }

package/src/commands/harden.js

@@ -10,6 +10,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
 import { loadConfig } from "../config.js";
+import { resolveTestOnPush } from "../harden/test-on-push.js";
 import { compareHarden, formatAdvisoryReport } from "../harden/advisory.js";
 import { interactiveHarden } from "../harden/interactive.js";
 import { createWizard, isTTY } from "../utils/wizard.js";
@@ -121,6 +122,14 @@ export async function hardenCommand({
 
   const roots = detectStackRoots(projectDir, { only: onlyDirs, exclude: excludeDirs });
   const cmds = await resolveCmds(projectDir, roots[0]?.language ?? null);
+  // KJC-TSK-0647: CI already running the suite per PR ⇒ pre-push drops its
+  // test command (false-red source under local parallelism); opt back in
+  // via package.json kj.harden.test_on_push.
+  const top = resolveTestOnPush({ projectDir, repoCfg, testCmd: cmds.test });
+  if (top.reason) {
+    logger.info?.(`kj harden: ${top.reason}`);
+    cmds.test = undefined;
+  }
   // KJC-TSK-0648: branch-first guard — the base branch only moves via PR.
   // Resolved from the project's kj config (default "main"); best-effort so
   // harden keeps working on repos that never ran kj init.

package/src/commands/install-tools.js

@@ -28,7 +28,17 @@ const execFileAsync = promisify(execFile);
 
 // git and the agent CLI lead the list: both are `kj doctor` *required* tools,
 // so a blank machine wants them before the optional audit tools.
-const ALL_TOOLS = ["git", "agent-cli", "semgrep", "osv-scanner", "lighthouse", "docker", "sonar"];
+// KJC-TSK-0657: rtk/squeezr/qmd (token+context optimizers, previously
+// init-only) complete the list — one pass leaves the machine 100%
+// operational, per the quality-default-on product rule.
+const ALL_TOOLS = ["git", "agent-cli", "semgrep", "osv-scanner", "lighthouse", "docker", "sonar", "rtk", "squeezr", "qmd"];
+
+// Optimizer tools reuse the init installers (same {ok, version, error} contract).
+const OPTIMIZER_INSTALLERS = {
+  rtk: () => import("../utils/rtk-install.js").then((m) => m.installRtk),
+  squeezr: () => import("../utils/squeezr-install.js").then((m) => m.installSqueezr),
+  qmd: () => import("../utils/qmd-install.js").then((m) => m.installQmd),
+};
 
 // The default pipeline is coder=claude, reviewer=codex, so `agent-cli` installs
 // exactly those two. gemini stays out of the default: it is a supported
@@ -335,6 +345,22 @@ export async function installToolsCommand(opts = {}) {
       continue;
     }
 
+    if (OPTIMIZER_INSTALLERS[tool]) {
+      if (dryRun) {
+        results.push({ tool, action: "planned", command: `kj install-tools --only ${tool}` });
+        logger.info?.(`▸ ${tool}: would install (init installer)`);
+        continue;
+      }
+      const proceed = yes || await promptYesNo(`Install ${tool}?`);
+      if (!proceed) { results.push({ tool, action: "declined" }); continue; }
+      const install = await OPTIMIZER_INSTALLERS[tool]();
+      const r = await install(logger);
+      results.push(r.ok
+        ? { tool, action: "installed", version: r.version }
+        : { tool, action: "failed", error: r.error });
+      continue;
+    }
+
     if (tool === "git") {
       const result = await handleGit({ available, dryRun, yes, logger });
       results.push(result);

package/src/commands/review-gate.js

@@ -9,6 +9,7 @@ import { runCommand } from "../utils/process.js";
 import { checkVerdict } from "../review/verdict-store.js";
 import { runOneShotReview } from "../review/one-shot-review.js";
 import { runSolomonArbitration } from "../review/solomon-arbitration.js";
+import { ensureGateTrackable } from "../review/gate-gitignore.js";
 
 // Raw git always — never a wrapped/compressing runner (KJC-BUG-0115).
 async function rawDiff(range) {
@@ -64,6 +65,12 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
     await fs.mkdir(path.dirname(marker), { recursive: true });
     await fs.writeFile(marker, "# Cross-AI review gate enabled (ENV-C1). Commit this file so the whole team inherits the gate.\n");
     console.log("✓ review gate enabled — commits now require an approved cross-AI verdict (kj review --staged)");
+    // KJC-TSK-0646: a `.karajan/` dir-exclude would silently keep the
+    // contract out of git — rewrite it so the team actually inherits it.
+    const gi = await ensureGateTrackable(projectDir);
+    if (gi.changed) {
+      console.log("✓ .gitignore adjusted: the gate contract (.karajan/review-gate, hooks) is now trackable — commit it");
+    }
     const hookProbe = await runCommand("git", ["config", "core.hooksPath"]);
     if (!hookProbe.stdout?.trim()) {
       console.log("⚠ no core.hooksPath configured — run `kj harden` so the pre-commit hook enforces the gate");

package/src/harden/test-on-push.js

@@ -0,0 +1,38 @@
+/**
+ * Test-on-push policy (KJC-TSK-0647) — the full suite on every push is
+ * redundant when CI already runs it per PR, and a source of false reds
+ * (suites unstable under local parallelism). Field-reproduced.
+ *
+ * Policy: a CI workflow that runs tests ⇒ pre-push drops its test command
+ * (identity guard and chaining stay). Repos can force it back with
+ * `"kj": { "harden": { "test_on_push": true } }` in package.json. Repos
+ * without CI keep tests on push — there it IS the last safety net.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const TEST_STEP = /\b(npm (run )?test|vitest|jest|pytest|go test|phpunit|cargo test)\b/;
+
+export function ciRunsTests(projectDir) {
+  const dir = join(projectDir, ".github", "workflows");
+  if (!existsSync(dir)) return false;
+  try {
+    return readdirSync(dir)
+      .filter((f) => /\.ya?ml$/.test(f))
+      .some((f) => TEST_STEP.test(readFileSync(join(dir, f), "utf8")));
+  } catch {
+    return false;
+  }
+}
+
+export function resolveTestOnPush({ projectDir, repoCfg = {}, testCmd = null }) {
+  if (!testCmd) return { testCmd: null, reason: null };
+  if (repoCfg.test_on_push === true) return { testCmd, reason: null };
+  if (ciRunsTests(projectDir)) {
+    return {
+      testCmd: null,
+      reason: "CI already runs the suite per PR — pre-push keeps only the identity guard (opt back in with kj.harden.test_on_push: true in package.json)",
+    };
+  }
+  return { testCmd, reason: null };
+}