@karajan-family/code 4.21.0

package/scripts/install.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT_DIR"
+
+node scripts/install.js "$@"

package/scripts/postinstall.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+/**
+ * postinstall hook – registers karajan-mcp in Claude Code and Codex
+ * automatically after `npm install`.
+ *
+ * - Non-interactive, silent on success.
+ * - Idempotent: safe to run many times.
+ * - Never fails hard (exits 0 even on error) so `npm install` is not blocked.
+ */
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT_DIR = path.resolve(__dirname, "..");
+const REGISTRY_PATH = path.join(os.homedir(), ".karajan", "instances.json");
+
+async function readJson(file) {
+  const raw = await fs.readFile(file, "utf8");
+  return JSON.parse(raw);
+}
+
+async function writeJson(file, obj) {
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  await fs.writeFile(file, `${JSON.stringify(obj, null, 2)}\n`, "utf8");
+}
+
+function resolveKjHome() {
+  if (process.env.KJ_HOME) return process.env.KJ_HOME;
+  return path.join(ROOT_DIR, ".karajan");
+}
+
+async function resolveKjHomeFromRegistry() {
+  try {
+    const registry = await readJson(REGISTRY_PATH);
+    const names = Object.keys(registry.instances || {});
+    if (names.length > 0) {
+      const first = registry.instances[names.includes("default") ? "default" : names[0]];
+      if (first?.kjHome) return first.kjHome;
+    }
+  } catch {
+    // No registry yet — use default
+  }
+  return resolveKjHome();
+}
+
+async function setupClaudeMcp(kjHome) {
+  const claudeJsonPath = path.join(os.homedir(), ".claude.json");
+  let config = {};
+  try {
+    config = await readJson(claudeJsonPath);
+  } catch {
+    config = {};
+  }
+
+  config.mcpServers = config.mcpServers || {};
+  config.mcpServers["karajan-mcp"] = {
+    type: "stdio",
+    command: "node",
+    args: [path.join(ROOT_DIR, "src", "mcp", "server.js")],
+    cwd: ROOT_DIR,
+    env: { KJ_HOME: kjHome }
+  };
+
+  await writeJson(claudeJsonPath, config);
+}
+
+function upsertCodexMcpBlock(toml, block) {
+  const begin = "# BEGIN karajan-mcp";
+  const end = "# END karajan-mcp";
+  const startIdx = toml.indexOf(begin);
+  const endIdx = toml.indexOf(end);
+  let base = toml;
+
+  if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+    base = `${toml.slice(0, startIdx).trimEnd()}\n\n${toml.slice(endIdx + end.length).trimStart()}`;
+  }
+
+  return `${base.trimEnd()}\n\n${begin}\n${block}\n${end}\n`;
+}
+
+async function setupCodexMcp(kjHome) {
+  const configPath = path.join(os.homedir(), ".codex", "config.toml");
+  let toml = "";
+  try {
+    toml = await fs.readFile(configPath, "utf8");
+  } catch {
+    toml = "";
+  }
+
+  const block = [
+    '[mcp_servers."karajan-mcp"]',
+    'command = "node"',
+    `args = ["${path.join(ROOT_DIR, "src", "mcp", "server.js")}"]`,
+    `cwd = "${ROOT_DIR}"`,
+    '[mcp_servers."karajan-mcp".env]',
+    `KJ_HOME = "${kjHome}"`
+  ].join("\n");
+
+  const updated = upsertCodexMcpBlock(toml, block);
+  await fs.mkdir(path.dirname(configPath), { recursive: true });
+  await fs.writeFile(configPath, updated, "utf8");
+}
+
+async function main() {
+  const kjHome = await resolveKjHomeFromRegistry();
+
+  await setupClaudeMcp(kjHome);
+  await setupCodexMcp(kjHome);
+
+  console.log("karajan-mcp registered in Claude Code and Codex.");
+}
+
+main().catch(() => {
+  // Silent failure — never block npm install
+});

package/scripts/protect-all-repos.sh

@@ -0,0 +1,88 @@
+#!/bin/bash
+#
+# Configures branch protection on all repos of a GitHub user.
+# Requires: gh CLI authenticated with admin permissions.
+#
+# Usage:
+#   ./scripts/protect-all-repos.sh              # dry-run (shows what it would do)
+#   ./scripts/protect-all-repos.sh --apply      # apply protection rules
+#
+# What it does:
+#   - Require PRs before merging (no direct push to default branch)
+#   - Block force push
+#   - Block branch deletion
+#
+# Skips repos where branch protection is already configured.
+
+set -euo pipefail
+
+OWNER="${GH_OWNER:-manufosela}"
+APPLY=false
+
+if [[ "${1:-}" == "--apply" ]]; then
+  APPLY=true
+fi
+
+echo "=== Branch Protection for all repos of $OWNER ==="
+echo ""
+
+if [[ "$APPLY" == false ]]; then
+  echo "  DRY RUN mode. Use --apply to actually configure."
+  echo ""
+fi
+
+REPOS=$(gh repo list "$OWNER" --limit 500 --json name,defaultBranchRef,isArchived \
+  --jq '.[] | select(.isArchived == false) | "\(.name)\t\(.defaultBranchRef.name // "main")"')
+
+TOTAL=0
+PROTECTED=0
+SKIPPED=0
+FAILED=0
+
+while IFS=$'\t' read -r REPO BRANCH; do
+  TOTAL=$((TOTAL + 1))
+
+  # Check if already protected
+  STATUS=$(gh api "repos/$OWNER/$REPO/branches/$BRANCH/protection" --jq '.required_pull_request_reviews.required_approving_review_count // 0' 2>/dev/null || echo "none")
+
+  if [[ "$STATUS" != "none" ]]; then
+    echo "  SKIP  $REPO ($BRANCH) — already protected"
+    SKIPPED=$((SKIPPED + 1))
+    continue
+  fi
+
+  if [[ "$APPLY" == false ]]; then
+    echo "  WOULD $REPO ($BRANCH)"
+    continue
+  fi
+
+  # Apply protection
+  if gh api "repos/$OWNER/$REPO/branches/$BRANCH/protection" -X PUT \
+    --input - <<EOF 2>/dev/null; then
+{
+  "required_pull_request_reviews": {
+    "required_approving_review_count": 0,
+    "dismiss_stale_reviews": false
+  },
+  "enforce_admins": false,
+  "required_status_checks": null,
+  "restrictions": null,
+  "allow_force_pushes": false,
+  "allow_deletions": false
+}
+EOF
+    echo "  OK    $REPO ($BRANCH)"
+    PROTECTED=$((PROTECTED + 1))
+  else
+    echo "  FAIL  $REPO ($BRANCH) — check permissions"
+    FAILED=$((FAILED + 1))
+  fi
+
+done <<< "$REPOS"
+
+echo ""
+echo "=== Summary ==="
+echo "  Total:     $TOTAL"
+echo "  Protected: $PROTECTED"
+echo "  Skipped:   $SKIPPED"
+echo "  Failed:    $FAILED"

package/scripts/quickstart-gate.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+/**
+ * Quickstart gate (KJC-TSK-0635) — the landing's Quick Start, end to end,
+ * against the PACKED tarball, with a REAL coder run.
+ *
+ * Run manually before a release (`npm run verify-quickstart`). Opt-in
+ * because the coder run spends real subscription quota (~$0.5-1.5, 5-8
+ * minutes). What it catches that unit tests and verify-pack cannot:
+ * the exact first-contact sequence a new user follows — install → init →
+ * `kj run` on a no-remote repo → playable artifact (2026-07-19: that
+ * sequence surfaced KJC-BUG-0111/0112/0113 in one afternoon).
+ *
+ * Asserts: run exits 0 · report says approved · index.html exists with
+ * game markers · "skipping push/PR" logged · ZERO Solomon escalations.
+ */
+import { execFileSync, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const repoRoot = path.resolve(path.dirname(new URL(import.meta.url).pathname), "..");
+const TASK = "Create a tic-tac-toe game in a single self-contained index.html — vanilla HTML, CSS and JavaScript, no server and no build step. The human plays X, the bot plays O and blocks or takes a winning move when it can. Detect wins and draws, and add a New Game button. Opening index.html in a browser must be enough to play.";
+
+function fail(msg, detail) {
+  console.error(`\n✗ quickstart-gate: ${msg}`);
+  if (detail) console.error(String(detail).slice(-1200));
+  process.exitCode = 1;
+  throw new Error(msg);
+}
+
+let work = null;
+try {
+  console.log("quickstart-gate: packing…");
+  const packOut = execFileSync("npm", ["pack", "--json", "--silent"], { cwd: repoRoot, encoding: "utf8" });
+  const tgz = path.join(repoRoot, JSON.parse(packOut)[0].filename);
+
+  work = fs.mkdtempSync(path.join(os.tmpdir(), "kj-qs-gate-"));
+  const prefix = path.join(work, "npm");
+  const project = path.join(work, "project");
+  fs.mkdirSync(project, { recursive: true });
+
+  console.log("quickstart-gate: installing the tarball (isolated prefix)…");
+  execFileSync("npm", ["install", "-g", tgz, "--no-audit", "--no-fund", "--silent", "--prefix", prefix], { encoding: "utf8" });
+  const kj = path.join(prefix, "bin", "kj");
+  fs.rmSync(tgz, { force: true });
+
+  // Isolated KARAJAN_HOME: faithful to a brand-new user (no global
+  // config) and never touches the maintainer's real ~/.karajan.
+  const env = { ...process.env, KARAJAN_HOME: path.join(work, "karajan-home") };
+  delete env.CLAUDECODE;
+  // If the maintainer's machine has a SonarQube server running, preflight
+  // (correctly) demands a token the isolated home doesn't have. Forward the
+  // maintainer's token so the gate exercises the sonar stage instead of
+  // dying in preflight. A machine with no sonar server is unaffected.
+  if (!env.KJ_SONAR_TOKEN) {
+    try {
+      const cfg = fs.readFileSync(path.join(os.homedir(), ".karajan", "kj.config.yml"), "utf8");
+      const m = cfg.match(/^\s*token:\s*(sqa_[A-Za-z0-9]+|squ_[A-Za-z0-9]+)\s*$/m);
+      if (m) env.KJ_SONAR_TOKEN = m[1];
+    } catch { /* no global config — brand-new machine, nothing to forward */ }
+  }
+
+  console.log("quickstart-gate: git init + kj init (unattended)…");
+  execFileSync("git", ["init", "-q", "-b", "main"], { cwd: project });
+  const init = spawnSync(kj, ["init", "--no-interactive", "--no-ollama", "--no-rtk", "--no-squeezr", "--no-qmd"], {
+    cwd: project, env, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 300000,
+  });
+  if (init.status !== 0) fail("kj init failed", init.stderr || init.stdout);
+
+  console.log("quickstart-gate: kj run (REAL coder — this spends quota, ~5-8 min)…");
+  const runRes = spawnSync(kj, ["run", "-y", TASK], {
+    cwd: project, env, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 20 * 60 * 1000,
+  });
+  const runOut = `${runRes.stdout || ""}${runRes.stderr || ""}`;
+  fs.writeFileSync(path.join(work, "run.log"), runOut);
+
+  if (runRes.status !== 0) fail(`kj run exited ${runRes.status} (log: ${work}/run.log)`, runOut);
+  if (/escalating to Solomon/i.test(runOut)) fail(`Solomon escalation detected — the happy path must not consult Solomon (log: ${work}/run.log)`);
+  // KJC-BUG-0112 regression: a remote-less repo must never attempt (and
+  // fail) push/fetch automation. With init's defaults (auto_push: false)
+  // the "skipping push/PR" line is legitimately absent, so assert the
+  // absence of failure symptoms rather than the presence of the skip line.
+  if (/failed to push|fatal: .*origin|couldn't find remote/i.test(runOut)) fail(`push/fetch against a missing remote detected (log: ${work}/run.log)`);
+
+  const html = path.join(project, "index.html");
+  if (!fs.existsSync(html)) fail("index.html was not created");
+  const htmlText = fs.readFileSync(html, "utf8");
+  if (!/new game/i.test(htmlText)) fail("index.html has no New Game control — not the requested game");
+
+  const report = spawnSync(kj, ["report"], { cwd: project, env, encoding: "utf8", timeout: 60000 });
+  if (!/approved/i.test(`${report.stdout || ""}`)) fail("kj report does not say approved", report.stdout);
+
+  console.log("\n✓ quickstart-gate: install → init → run → playable index.html → approved. Ship it.");
+} finally {
+  if (work && process.exitCode !== 1 && fs.existsSync(work)) fs.rmSync(work, { recursive: true, force: true });
+  if (work && process.exitCode === 1) console.error(`quickstart-gate: workdir kept for inspection: ${work}`);
+}

package/scripts/regen-arch-stats.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+# Regenerate the numeric stats in docs/ARCHITECTURE.md from the current tree.
+#
+# Motivation: docs/ARCHITECTURE.md accumulates staleness. The v2.7.4 audit
+# found it claimed "28k LOC, 234 files" when reality was 35.9k LOC / 260
+# files (+28% LOC, +11% files), and pointed at `src/orchestrator.js` as the
+# main pipeline (~1400 LOC) when the real orchestrator is
+# `src/orchestrator/flow-runner.js` (2241 LOC) and `src/orchestrator.js` is
+# a 22-line barrel.
+#
+# This script rewrites the specific lines that contain numeric stats
+# in-place; narrative paragraphs are left alone.
+#
+# Usage:
+#   scripts/regen-arch-stats.sh          # rewrite and exit 0
+#   scripts/regen-arch-stats.sh --check  # exit 1 if the file would change
+#
+# Add to the release checklist: run without --check, commit any diff.
+set -euo pipefail
+
+MODE="${1:-}"
+DOC="docs/ARCHITECTURE.md"
+
+if [[ ! -f "$DOC" ]]; then
+  echo "ARCHITECTURE.md not found at $DOC — run from the repo root." >&2
+  exit 2
+fi
+
+# ── Compute current stats ──────────────────────────────────────────────
+
+SRC_LOC=$(find src -name "*.js" -not -path "*/node_modules/*" | xargs wc -l 2>/dev/null | tail -1 | awk '{print $1}')
+SRC_FILES=$(find src -name "*.js" -not -path "*/node_modules/*" | wc -l)
+TEST_COUNT=$(find tests -name "*.test.js" -not -path "*/worktrees/*" -not -path "*/.kj/*" | wc -l)
+
+# Format LOC with thousands separator ("36038" → "36k" for narrative, raw for table)
+SRC_LOC_SHORT=$(awk -v n="$SRC_LOC" 'BEGIN{ printf "%dk", int(n/1000) }')
+
+# Orchestrator pipeline stats
+FLOW_RUNNER_LOC=$(wc -l < src/orchestrator/flow-runner.js 2>/dev/null | awk '{print $1}')
+BARREL_LOC=$(wc -l < src/orchestrator.js 2>/dev/null | awk '{print $1}')
+
+# ── Build a sed program ────────────────────────────────────────────────
+# Each line targets a specific claim. Patterns are narrow enough to miss
+# unrelated mentions but wide enough to absorb small formatting drifts.
+
+SED_SCRIPT=$(cat <<EOF
+s|Source code ([0-9kKmM.]\\+ LOC, [0-9]\\+ files)|Source code (${SRC_LOC_SHORT} LOC, ${SRC_FILES} files)|g
+s|Test suite ([0-9]\\+ tests)|Test suite (${TEST_COUNT} test files)|g
+s|\`src/orchestrator.js\` (~[0-9]\\+ LOC)|\`src/orchestrator.js\` (${BARREL_LOC}-line barrel) → delegates to \`src/orchestrator/flow-runner.js\` (${FLOW_RUNNER_LOC} LOC)|g
+EOF
+)
+
+if [[ "$MODE" == "--check" ]]; then
+  if sed "$SED_SCRIPT" "$DOC" | diff -q "$DOC" - >/dev/null; then
+    echo "docs/ARCHITECTURE.md stats are up to date."
+    exit 0
+  fi
+  echo "docs/ARCHITECTURE.md stats are STALE. Run scripts/regen-arch-stats.sh to rewrite." >&2
+  sed "$SED_SCRIPT" "$DOC" | diff -u "$DOC" - || true
+  exit 1
+fi
+
+# Real rewrite, in place, with backup we immediately delete to keep the
+# working tree clean.
+sed -i.bak "$SED_SCRIPT" "$DOC"
+rm -f "${DOC}.bak"
+
+echo "docs/ARCHITECTURE.md updated with:"
+echo "  Source code: ${SRC_LOC_SHORT} LOC, ${SRC_FILES} files"
+echo "  Tests:       ${TEST_COUNT} test files"
+echo "  Orchestrator: src/orchestrator.js ${BARREL_LOC}-line barrel → flow-runner.js ${FLOW_RUNNER_LOC} LOC"

package/scripts/setup-multi-instance.sh

@@ -0,0 +1,150 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+INSTALLER="$ROOT_DIR/scripts/install.sh"
+
+if [[ ! -x "$INSTALLER" ]]; then
+  echo "Installer not found: $INSTALLER"
+  exit 1
+fi
+
+echo "Karajan multi-instance setup (personal + pro)"
+echo
+
+read -r -p "Sonar host [http://localhost:9000]: " SONAR_HOST
+SONAR_HOST="${SONAR_HOST:-http://localhost:9000}"
+
+read -r -p "Personal KJ_HOME [$HOME/.karajan-personal]: " PERSONAL_HOME
+PERSONAL_HOME="${PERSONAL_HOME:-$HOME/.karajan-personal}"
+
+read -r -p "Pro KJ_HOME [$HOME/.karajan-pro]: " PRO_HOME
+PRO_HOME="${PRO_HOME:-$HOME/.karajan-pro}"
+
+echo
+read -r -p "Personal Sonar token (KJ_SONAR_TOKEN): " PERSONAL_TOKEN
+read -r -p "Pro Sonar token (KJ_SONAR_TOKEN): " PRO_TOKEN
+
+read -r -p "Coder default [codex]: " CODER
+CODER="${CODER:-codex}"
+
+read -r -p "Reviewer default [claude]: " REVIEWER
+REVIEWER="${REVIEWER:-claude}"
+
+read -r -p "Reviewer fallback [codex]: " REVIEWER_FALLBACK
+REVIEWER_FALLBACK="${REVIEWER_FALLBACK:-codex}"
+
+echo
+echo "Setting up PERSONAL instance..."
+"$INSTALLER" \
+  --non-interactive \
+  --link-global false \
+  --kj-home "$PERSONAL_HOME" \
+  --sonar-host "$SONAR_HOST" \
+  --sonar-token "$PERSONAL_TOKEN" \
+  --coder "$CODER" \
+  --reviewer "$REVIEWER" \
+  --reviewer-fallback "$REVIEWER_FALLBACK" \
+  --setup-mcp-claude false \
+  --setup-mcp-codex false \
+  --run-doctor true
+
+echo
+echo "Setting up PRO instance..."
+"$INSTALLER" \
+  --non-interactive \
+  --link-global false \
+  --kj-home "$PRO_HOME" \
+  --sonar-host "$SONAR_HOST" \
+  --sonar-token "$PRO_TOKEN" \
+  --coder "$CODER" \
+  --reviewer "$REVIEWER" \
+  --reviewer-fallback "$REVIEWER_FALLBACK" \
+  --setup-mcp-claude false \
+  --setup-mcp-codex false \
+  --run-doctor true
+
+CLAUDE_SETTINGS="$HOME/.claude/settings.json"
+CODEX_CONFIG="$HOME/.codex/config.toml"
+SERVER_PATH="$ROOT_DIR/src/mcp/server.js"
+
+mkdir -p "$HOME/.claude" "$HOME/.codex"
+
+if [[ ! -f "$CLAUDE_SETTINGS" ]]; then
+  cat > "$CLAUDE_SETTINGS" <<JSON
+{
+  "mcpServers": {}
+}
+JSON
+fi
+
+node - <<NODE
+const fs = require('fs');
+const p = "$CLAUDE_SETTINGS";
+const serverPath = "$SERVER_PATH";
+const rootDir = "$ROOT_DIR";
+const personalHome = "$PERSONAL_HOME";
+const proHome = "$PRO_HOME";
+const personalToken = "$PERSONAL_TOKEN";
+const proToken = "$PRO_TOKEN";
+let settings = {};
+try { settings = JSON.parse(fs.readFileSync(p, 'utf8')); } catch { settings = {}; }
+settings.mcpServers = settings.mcpServers || {};
+settings.mcpServers['karajan-personal'] = {
+  command: 'node',
+  args: [serverPath],
+  cwd: rootDir,
+  env: { KJ_HOME: personalHome, KJ_SONAR_TOKEN: personalToken }
+};
+settings.mcpServers['karajan-pro'] = {
+  command: 'node',
+  args: [serverPath],
+  cwd: rootDir,
+  env: { KJ_HOME: proHome, KJ_SONAR_TOKEN: proToken }
+};
+fs.writeFileSync(p, JSON.stringify(settings, null, 2) + '\\n');
+NODE
+
+if [[ ! -f "$CODEX_CONFIG" ]]; then
+  touch "$CODEX_CONFIG"
+fi
+
+TMP_CODEX="$(mktemp)"
+cp "$CODEX_CONFIG" "$TMP_CODEX"
+
+sed -i '/# BEGIN karajan-multi/,/# END karajan-multi/d' "$TMP_CODEX"
+cat >> "$TMP_CODEX" <<TOML
+
+# BEGIN karajan-multi
+[mcp_servers."karajan-personal"]
+command = "node"
+args = ["$SERVER_PATH"]
+cwd = "$ROOT_DIR"
+
+[mcp_servers."karajan-personal".env]
+KJ_HOME = "$PERSONAL_HOME"
+KJ_SONAR_TOKEN = "$PERSONAL_TOKEN"
+
+[mcp_servers."karajan-pro"]
+command = "node"
+args = ["$SERVER_PATH"]
+cwd = "$ROOT_DIR"
+
+[mcp_servers."karajan-pro".env]
+KJ_HOME = "$PRO_HOME"
+KJ_SONAR_TOKEN = "$PRO_TOKEN"
+# END karajan-multi
+TOML
+
+mv "$TMP_CODEX" "$CODEX_CONFIG"
+
+echo
+echo "Multi-instance setup completed."
+echo "- Personal KJ_HOME: $PERSONAL_HOME"
+echo "- Pro KJ_HOME: $PRO_HOME"
+echo "- Claude MCP updated: $CLAUDE_SETTINGS"
+echo "- Codex MCP updated: $CODEX_CONFIG"
+echo
+echo "Next steps:"
+echo "1) Restart Claude and Codex."
+echo "2) In each client, use MCP server karajan-personal or karajan-pro."