karajan-code 3.8.0 → 3.10.1

package/README.md

@@ -112,6 +112,16 @@ brew install manufosela/tap/karajan-code
 
 > **Installing with pnpm?** pnpm blocks dependency build scripts by default, so `better-sqlite3`'s native addon won't compile on install and DB-backed commands (`board`, `rag`, cost tracking) will fail. After installing, run `pnpm approve-builds better-sqlite3` — or just use npm. `kj doctor` flags this if it happens.
 
+> **On a bare Linux box, install `curl` first.** The binary and script installers
+> below download with `curl` (or `wget`). macOS already ships `curl` and Windows
+> PowerShell has `irm` built in, but a minimal server or container image often has
+> neither — install it with your package manager, then run the one-liner:
+> - **Debian/Ubuntu**: `sudo apt update && sudo apt install -y curl`
+> - **Fedora/RHEL/CentOS**: `sudo dnf install -y curl`
+> - **Arch**: `sudo pacman -S --noconfirm curl`
+> - **Alpine**: `sudo apk add curl`
+> - **openSUSE**: `sudo zypper install -y curl`
+
 **Standalone binary** (no Node.js needed):
 ```bash
 # macOS (Apple Silicon)
@@ -124,7 +134,28 @@ curl -L https://github.com/manufosela/karajan-code/releases/latest/download/kj-l
 curl -L https://github.com/manufosela/karajan-code/releases/latest/download/kj-win-x64.exe -o kj.exe
 ```
 
-**One-liner** (detects OS, installs via npm):
+**One-liner, binary** (no Node — detects OS/arch, verifies the checksum, installs to `~/.local/bin`):
+```bash
+curl -fsSL https://raw.githubusercontent.com/manufosela/karajan-code/main/scripts/install-binary.sh | sh
+```
+Pin a version or install dir with env vars: `KJ_VERSION=v3.7.2 KJ_INSTALL_DIR=/usr/local/bin`.
+
+**One-liner, binary — Windows** (no Node — verifies the checksum, installs to `%LOCALAPPDATA%\Karajan` and adds it to your user PATH):
+```powershell
+irm https://raw.githubusercontent.com/manufosela/karajan-code/main/scripts/install-binary.ps1 | iex
+```
+
+> **If your OS blocks the binary.** The macOS build is ad-hoc signed and the
+> Windows build is unsigned — neither carries a paid certificate, so a manually
+> downloaded binary may be blocked on first run. The install scripts above clear
+> the flag for you. If you download the binary by hand instead:
+> - **macOS** — Gatekeeper says the binary "cannot be opened": `xattr -d com.apple.quarantine ./kj`, or Control-click the file → **Open**.
+> - **Windows** — SmartScreen shows "Windows protected your PC": click **More info → Run anyway**, or run `Unblock-File .\kj.exe`.
+>
+> Paid notarization (Apple) and Authenticode signing (Windows) are optional and
+> not enabled by default — this is a deliberate cost decision, not an oversight.
+
+**One-liner, npm** (detects OS, installs via npm — needs Node ≥ 18):
 ```bash
 curl -fsSL https://raw.githubusercontent.com/manufosela/karajan-code/main/scripts/install-kj.sh | sh
 ```

package/package.json

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

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

@@ -0,0 +1,89 @@
+<#
+.SYNOPSIS
+  Karajan Code — standalone binary installer for Windows (no Node required).
+
+.DESCRIPTION
+  Downloads the prebuilt kj.exe for Windows x64 from the GitHub release,
+  verifies its SHA256 checksum, installs it to %LOCALAPPDATA%\Karajan, and
+  adds that folder to the user PATH (idempotently). Re-running updates the
+  binary in place without duplicating PATH entries.
+
+  Run it with:
+    irm https://karajancode.com/install.ps1 | iex
+
+  Override with env vars: $env:KJ_VERSION (e.g. v3.7.2), $env:KJ_INSTALL_DIR.
+
+  KJC-TSK-0594.
+#>
+$ErrorActionPreference = "Stop"
+
+$repo = "manufosela/karajan-code"
+$version = if ($env:KJ_VERSION) { $env:KJ_VERSION } else { "latest" }
+$installDir = if ($env:KJ_INSTALL_DIR) { $env:KJ_INSTALL_DIR } else { Join-Path $env:LOCALAPPDATA "Karajan" }
+$asset = "kj-win-x64.exe"
+
+if ($version -eq "latest") {
+  $base = "https://github.com/$repo/releases/latest/download"
+} else {
+  $base = "https://github.com/$repo/releases/download/$version"
+}
+
+# Download to a temp folder; only install once the checksum matches, so a
+# failure never leaves a half-installed binary behind.
+$tmp = Join-Path ([System.IO.Path]::GetTempPath()) ("kj-install-" + [System.Guid]::NewGuid().ToString("N"))
+New-Item -ItemType Directory -Path $tmp -Force | Out-Null
+try {
+  $binTmp = Join-Path $tmp "kj.exe"
+  $shaTmp = Join-Path $tmp "kj.exe.sha256"
+
+  Write-Host "kj-install: downloading $asset ($version)..."
+  try {
+    Invoke-WebRequest -Uri "$base/$asset" -OutFile $binTmp -UseBasicParsing
+    Invoke-WebRequest -Uri "$base/$asset.sha256" -OutFile $shaTmp -UseBasicParsing
+  } catch {
+    throw "could not download $base/$asset — does that version/asset exist, and is the network reachable? ($_)"
+  }
+
+  # certutil writes a multi-line file; keep only the hex of the hash line.
+  $shaLine = (Get-Content $shaTmp | Where-Object { $_ -notmatch "SHA256|CertUtil" } | Select-Object -First 1)
+  $expected = ($shaLine -replace "[^0-9A-Fa-f]", "").ToLower()
+  $actual = (Get-FileHash -Algorithm SHA256 -Path $binTmp).Hash.ToLower()
+  if ($expected.Length -ne 64 -or $expected -ne $actual) {
+    throw "checksum mismatch (expected '$expected', got '$actual'). Aborting, nothing installed."
+  }
+
+  # Install: move into place, replacing any previous install (idempotent).
+  New-Item -ItemType Directory -Path $installDir -Force | Out-Null
+  $dest = Join-Path $installDir "kj.exe"
+  Move-Item -Path $binTmp -Destination $dest -Force
+
+  # The download carries a "mark of the web" (Zone.Identifier) that makes
+  # SmartScreen warn on first run. The binary is not code-signed with a paid
+  # certificate, so clear the mark on the copy we just verified ourselves.
+  Unblock-File -Path $dest -ErrorAction SilentlyContinue
+
+  $installed = (& $dest --version) 2>$null
+  Write-Host "kj-install: installed kj $installed to $dest"
+
+  # Add to the user PATH only if it is not already there (no duplicates).
+  $userPath = [Environment]::GetEnvironmentVariable("Path", "User")
+  $parts = @()
+  if ($userPath) { $parts = $userPath.Split(";") | Where-Object { $_ -ne "" } }
+  $already = $parts | Where-Object { $_.TrimEnd("\") -ieq $installDir.TrimEnd("\") }
+  if (-not $already) {
+    $newPath = if ($userPath) { "$userPath;$installDir" } else { $installDir }
+    [Environment]::SetEnvironmentVariable("Path", $newPath, "User")
+    Write-Host "kj-install: added '$installDir' to your user PATH. Open a new terminal to use 'kj'."
+  } 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

@@ -0,0 +1,121 @@
+#!/bin/sh
+# Karajan Code — standalone binary installer (no Node required).
+#
+#   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.
+#
+# POSIX sh only — no bashisms, no Node. KJC-TSK-0593.
+set -eu
+
+REPO="manufosela/karajan-code"
+VERSION="${KJ_VERSION:-latest}"
+INSTALL_DIR="${KJ_INSTALL_DIR:-$HOME/.local/bin}"
+
+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)"
+case "$os" in
+  Linux) os="linux" ;;
+  Darwin) os="darwin" ;;
+  *) die "unsupported OS '$os'. Supported: Linux, macOS. Use npm instead: npm install -g karajan-code" ;;
+esac
+case "$arch" in
+  x86_64 | amd64) arch="x64" ;;
+  arm64 | aarch64) arch="arm64" ;;
+  *) die "unsupported architecture '$arch'" ;;
+esac
+
+target="${os}-${arch}"
+case "$target" in
+  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). ---
+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
+
+# --- 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
+
+# --- 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"
+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
+
+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}.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."
+
+# --- 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)."

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/utils/update-check.js

@@ -1,11 +1,47 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import { isSea } from "node:sea";
 import { getKarajanHome } from "./paths.js";
 
 const CACHE_FILE = "update-check.json";
 const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
 const PACKAGE_NAME = "karajan-code";
 
+const RAW_BASE = "https://raw.githubusercontent.com/manufosela/karajan-code/main/scripts";
+export const INSTALL_SH_URL = `${RAW_BASE}/install-binary.sh`;
+export const INSTALL_PS1_URL = `${RAW_BASE}/install-binary.ps1`;
+
+/**
+ * Build the "how to update" line for the detected install channel.
+ * Pure and testable — no I/O.
+ * @param {{channel: "sea"|"npm"|"unknown", platform?: string}} opts
+ */
+export function updateInstruction({ channel, platform = process.platform }) {
+  if (channel === "sea") {
+    return platform === "win32"
+      ? `Re-run the installer: irm ${INSTALL_PS1_URL} | iex`
+      : `Re-run the installer: curl -fsSL ${INSTALL_SH_URL} | sh`;
+  }
+  if (channel === "npm") {
+    return `Run: npm install -g ${PACKAGE_NAME}`;
+  }
+  // Channel unknown — offer both paths, never silently pick a wrong one.
+  return `Update: npm install -g ${PACKAGE_NAME}  (or re-run the binary installer — see README)`;
+}
+
+/**
+ * Detect how this kj was installed: "sea" (standalone binary) or "npm"
+ * (global install / source tree). Falls back to "npm" if isSea() throws.
+ */
+export function detectInstallChannel() {
+  try {
+    return isSea() ? "sea" : "npm";
+  } catch {
+    // isSea() unexpectedly threw ⇒ treat as npm / source tree, never block.
+    return "npm";
+  }
+}
+
 /**
  * Check npm for a newer version. Non-blocking, cached for 24h.
  * Returns { updateAvailable, latest, current } or null if check fails/cached.
@@ -61,8 +97,9 @@ export async function checkForUpdate(currentVersion) {
 export async function printUpdateNotice(currentVersion) {
   const result = await checkForUpdate(currentVersion);
   if (result?.updateAvailable) {
+    const channel = detectInstallChannel();
     console.log(`\n  Update available: v${result.current} → v${result.latest}`);
-    console.log(`  Run: npm install -g ${PACKAGE_NAME}\n`);
+    console.log(`  ${updateInstruction({ channel })}\n`);
   }
 }