@karajan-family/code 4.21.0

package/src/utils/display/session-summary.js

@@ -0,0 +1,118 @@
+import { ANSI } from "./formatters.js";
+
+export function printSessionStages(stages) {
+  if (!stages) return;
+  if (stages.researcher?.summary) {
+    console.log(`  ${ANSI.dim}\ud83d\udd2c Research: ${stages.researcher.summary}${ANSI.reset}`);
+  }
+  printSessionPlanner(stages.planner);
+  if (stages.tester?.summary) {
+    console.log(`  ${ANSI.dim}\ud83e\uddea Tester: ${stages.tester.summary}${ANSI.reset}`);
+  }
+  if (stages.security?.summary) {
+    console.log(`  ${ANSI.dim}\ud83d\udd12 Security: ${stages.security.summary}${ANSI.reset}`);
+  }
+  printSessionSonar(stages.sonar);
+}
+
+function printSessionPlanner(planner) {
+  if (!planner?.title && !planner?.approach && !planner?.completedSteps?.length) return;
+  const planParts = [];
+  if (planner.title) planParts.push(planner.title);
+  if (planner.approach) planParts.push(`approach: ${planner.approach}`);
+  console.log(`  ${ANSI.dim}\ud83d\uddfa Plan: ${planParts.join(" | ")}${ANSI.reset}`);
+  for (const step of planner.completedSteps || []) {
+    console.log(`  ${ANSI.dim}   \u2713 ${step}${ANSI.reset}`);
+  }
+}
+
+export function printSessionSonar(sonar) {
+  if (!sonar) return;
+  // Three buckets so the banner reads correctly:
+  //   - OK                                 \u2192 green (real pass).
+  //   - SKIPPED / PENDING                  \u2192 gray (informational; sonar
+  //     wasn't gated against, this is NOT a fail). Pre-2026-05-07 N4
+  //     dogfooding these were rendered red, which made a clean run
+  //     look like a sonar failure during the live demo.
+  //   - everything else (ERROR, WARN, ...) \u2192 red (real fail).
+  let gateLabel;
+  if (sonar.gateStatus === "OK") gateLabel = ANSI.green;
+  else if (sonar.gateStatus === "SKIPPED" || sonar.gateStatus === "PENDING") gateLabel = ANSI.gray;
+  else gateLabel = ANSI.red;
+  console.log(`  ${ANSI.dim}\ud83d\udd0d Sonar: ${gateLabel}${sonar.gateStatus}${ANSI.reset}${ANSI.dim} (${sonar.openIssues ?? 0} issues)${ANSI.reset}`);
+  if (typeof sonar.issuesInitial === "number" || typeof sonar.issuesResolved === "number") {
+    const issuesInitial = sonar.issuesInitial ?? sonar.openIssues ?? 0;
+    const issuesFinal = sonar.issuesFinal ?? sonar.openIssues ?? 0;
+    const issuesResolved = sonar.issuesResolved ?? Math.max(issuesInitial - issuesFinal, 0);
+    console.log(`  ${ANSI.dim}\ud83d\udee0 Issues: ${issuesInitial} detected, ${issuesFinal} open, ${issuesResolved} resolved${ANSI.reset}`);
+  }
+}
+
+export function printSessionGit(git) {
+  if (!git?.branch) return;
+  const parts = [`branch: ${git.branch}`];
+  if (git.committed) parts.push("committed");
+  if (git.pushed) parts.push("pushed");
+  if (git.pr || git.prUrl) parts.push(`PR: ${git.pr || git.prUrl}`);
+  console.log(`  ${ANSI.dim}\ud83d\udcce Git: ${parts.join(", ")}${ANSI.reset}`);
+  if (Array.isArray(git.commits) && git.commits.length > 0) {
+    console.log(`  ${ANSI.dim}\ud83e\uddfe Commits:${ANSI.reset}`);
+    for (const commit of git.commits) {
+      const shortHash = (commit.hash || "").slice(0, 7) || "unknown";
+      const message = commit.message || "";
+      console.log(`  ${ANSI.dim}   - ${shortHash} ${message}${ANSI.reset}`);
+    }
+  }
+}
+
+function isBudgetUnavailable(budget) {
+  return budget.usage_available === false ||
+    (budget.total_tokens === 0 && budget.total_cost_usd === 0 && Object.keys(budget.breakdown_by_role || {}).length > 0);
+}
+
+export function printSessionRtkSavings(rtkSavings) {
+  if (!rtkSavings || !rtkSavings.callCount) return;
+  const tokens = rtkSavings.estimatedTokensSaved ?? 0;
+  const ratio = rtkSavings.savedPct ?? 0;
+  const commands = rtkSavings.callCount ?? 0;
+  const original = rtkSavings.originalBytes ?? 0;
+  const compressed = rtkSavings.rtkBytes ?? 0;
+
+  if (tokens === 0 || ratio === 0) {
+    console.log(`  ${ANSI.dim}⚡ RTK: ${commands} commands wrapped, 0% savings — output was already minimal (${original} bytes in, ${compressed} bytes out)${ANSI.reset}`);
+  } else {
+    console.log(`  ${ANSI.dim}⚡ RTK: saved ~${tokens.toLocaleString()} tokens (${ratio}% compression, ${commands} commands, ${original.toLocaleString()} → ${compressed.toLocaleString()} bytes)${ANSI.reset}`);
+  }
+}
+
+export function printSessionBudget(budget) {
+  if (!budget) return;
+  if (isBudgetUnavailable(budget)) {
+    console.log(`  ${ANSI.dim}\ud83d\udcb0 Budget: N/A (provider does not report usage)${ANSI.reset}`);
+    return;
+  }
+  const estPrefix = budget.includes_estimates ? "~" : "";
+  const estNote = budget.includes_estimates ? " (includes estimates)" : "";
+  const fmtTokens = (n) => Number(n || 0).toLocaleString("en-US");
+  console.log(`  ${ANSI.dim}\ud83d\udcb0 Total tokens: ${estPrefix}${fmtTokens(budget.total_tokens)}${estNote}${ANSI.reset}`);
+  console.log(`  ${ANSI.dim}\ud83d\udcb0 Total cost: ${estPrefix}$${Number(budget.total_cost_usd || 0).toFixed(2)}${ANSI.reset}`);
+  // KJC-TSK-0274: KJ-vs-non-KJ comparison line when compression data exists.
+  const cmp = budget.kj_comparison;
+  if (cmp?.hasCompression) {
+    const wkCost = `$${Number(cmp.withKj?.cost || 0).toFixed(2)}`;
+    const wkTok = fmtTokens(Number(cmp.withKj?.tokens || 0));
+    const wnCost = `$${Number(cmp.withoutKj?.cost || 0).toFixed(2)}`;
+    const wnTok = fmtTokens(Number(cmp.withoutKj?.tokens || 0));
+    const pct = Math.round(Number(cmp.savedPct || 0));
+    console.log(`  ${ANSI.dim}   \u2937 With KJ: ${wkCost} / ${wkTok} tokens${ANSI.reset}`);
+    console.log(`  ${ANSI.dim}   \u2937 Without KJ: ~${wnCost} / ~${wnTok} tokens (-${pct}%)${ANSI.reset}`);
+  }
+  for (const [role, metrics] of Object.entries(budget.breakdown_by_role || {})) {
+    const tokens = Number(metrics.total_tokens || 0);
+    const cost = Number(metrics.total_cost_usd || 0);
+    if (tokens === 0 && cost === 0) continue; // skip roles with no usage
+    console.log(
+      `  ${ANSI.dim}   - ${role}: ${estPrefix}${fmtTokens(tokens)} tokens, ${estPrefix}$${cost.toFixed(2)}${ANSI.reset}`
+    );
+  }
+}

package/src/utils/display/solomon.js

@@ -0,0 +1,42 @@
+import { ANSI } from "./formatters.js";
+
+const SOLOMON_RULING_HANDLERS = {
+  approve(detail, elapsed) {
+    const dismissedCount = detail?.dismissed?.length || 0;
+    const dismissedSuffix = dismissedCount > 0 ? ` (${dismissedCount} dismissed)` : "";
+    console.log(`  \u251c\u2500 ${ANSI.green}\u2696\ufe0f Solomon: APPROVE${dismissedSuffix}${ANSI.reset}  ${elapsed}`);
+  },
+  approve_with_conditions(detail, elapsed) {
+    const condCount = detail?.conditions?.length || 0;
+    console.log(`  \u251c\u2500 ${ANSI.yellow}\u2696\ufe0f Solomon: ${condCount} condition${condCount === 1 ? "" : "s"}${ANSI.reset}  ${elapsed}`);
+    if (detail?.conditions) {
+      for (const cond of detail.conditions) {
+        console.log(`  \u2502   ${ANSI.dim}${cond}${ANSI.reset}`);
+      }
+    }
+  },
+  escalate_human(detail, elapsed) {
+    const reason = detail?.escalate_reason || "unknown reason";
+    console.log(`  \u251c\u2500 ${ANSI.red}\u2696\ufe0f Solomon: ESCALATE \u2014 ${reason}${ANSI.reset}  ${elapsed}`);
+  },
+  create_subtask(detail, elapsed) {
+    const subtaskTitle = detail?.subtask?.title || "untitled";
+    console.log(`  \u251c\u2500 ${ANSI.magenta}\u2696\ufe0f Solomon: SUBTASK \u2014 ${subtaskTitle}${ANSI.reset}  ${elapsed}`);
+  }
+};
+
+/**
+ * Print Solomon ruling details
+ * @param {Object} detail 
+ * @param {string} elapsed 
+ */
+export function printSolomonRuling(detail, elapsed) {
+  const ruling = detail?.ruling || "unknown";
+  const handler = SOLOMON_RULING_HANDLERS[ruling];
+  if (handler) {
+    handler(detail, elapsed);
+  } else {
+    const rulingUpper = ruling.toUpperCase().replaceAll("_", " ");
+    console.log(`  \u251c\u2500 \u2696\ufe0f Solomon: ${rulingUpper}  ${elapsed}`);
+  }
+}

package/src/utils/display/spec-findings.js

@@ -0,0 +1,44 @@
+// Pretty-printer for SpecReviewerRole findings (KJC-PCS-0048 PR 2).
+// Grouped by category, colours by severity, every finding gets its
+// `suggestion` printed below as the actionable fix-it line.
+
+const COLOURS = {
+  reset: "\x1b[0m", bold: "\x1b[1m", dim: "\x1b[2m",
+  cyan: "\x1b[36m", yellow: "\x1b[33m", red: "\x1b[31m", gray: "\x1b[90m",
+};
+
+const SEV_COLOUR = { info: COLOURS.cyan, warn: COLOURS.yellow, fail: COLOURS.red };
+const SEV_LABEL = { info: "INFO", warn: "WARN", fail: "FAIL" };
+
+function colour(severity, text) {
+  const c = SEV_COLOUR[severity] || COLOURS.gray;
+  return `${c}${text}${COLOURS.reset}`;
+}
+
+/**
+ * @param {Array<{id,severity,category,message,suggestion?}>} findings
+ * @param {"ok"|"info"|"warn"|"fail"} severity
+ * @param {object} [opts]
+ * @param {(line:string)=>void} [opts.write]  Defaults to `console.warn` (stderr).
+ */
+export function printFindings(findings, severity, opts = {}) {
+  const write = opts.write || ((line) => process.stderr.write(`${line}\n`));
+  if (!Array.isArray(findings) || findings.length === 0) return;
+
+  write("");
+  write(`${COLOURS.bold}Spec review — ${colour(severity, SEV_LABEL[severity] || severity.toUpperCase())}${COLOURS.reset} (${findings.length} finding${findings.length === 1 ? "" : "s"})`);
+
+  const byCat = new Map();
+  for (const f of findings) {
+    if (!byCat.has(f.category)) byCat.set(f.category, []);
+    byCat.get(f.category).push(f);
+  }
+  for (const [cat, items] of byCat) {
+    write(`${COLOURS.dim}── ${cat}${COLOURS.reset}`);
+    for (const f of items) {
+      write(`  ${colour(f.severity, "●")} ${COLOURS.bold}${f.id}${COLOURS.reset} ${f.message}`);
+      if (f.suggestion) write(`    ${COLOURS.dim}→${COLOURS.reset} ${f.suggestion}`);
+    }
+  }
+  write("");
+}

package/src/utils/doc-links.js

@@ -0,0 +1,29 @@
+/**
+ * Documentation links for error messages.
+ *
+ * Maps error types to their relevant documentation page so that
+ * every actionable error includes a "See: <url>" pointer.
+ */
+
+const BASE_URL = "https://karajancode.com/docs";
+
+const ERROR_DOCS = {
+  sonar_token: `${BASE_URL}/guides/configuration/#sonarqube`,
+  sonar_docker: `${BASE_URL}/getting-started/installation/#docker`,
+  agent_not_found: `${BASE_URL}/getting-started/installation/#agents`,
+  bootstrap_failed: `${BASE_URL}/guides/troubleshooting/`,
+  config_missing: `${BASE_URL}/getting-started/quick-start/`,
+  branch_error: `${BASE_URL}/guides/pipeline/#git-workflow`,
+  rtk_install: `${BASE_URL}/guides/configuration/#rtk`,
+  squeezr_install: `${BASE_URL}/guides/configuration/#squeezr`,
+  qmd_install: `${BASE_URL}/guides/configuration/#qmd`,
+};
+
+export function docLink(errorType) {
+  return ERROR_DOCS[errorType] || `${BASE_URL}/guides/troubleshooting/`;
+}
+
+export function withDocLink(message, errorType) {
+  const link = docLink(errorType);
+  return `${message}\n  See: ${link}`;
+}

package/src/utils/docker-install.js

@@ -0,0 +1,34 @@
+// How `kj install-tools` installs Docker, resolved per platform (KJC-TSK-0609,
+// absorbing the sudo+apt/dnf primitive of KJC-TSK-0608).
+//
+//  · Linux: prefer the distro package manager (apt → docker.io, dnf → docker)
+//    run through `sudo` on the user's own tty — kj never sees the password.
+//    When neither is present, fall back to Docker's official convenience
+//    script, which the caller downloads to a file and runs (never `curl | sh`).
+//  · macOS / Windows: never auto-install (platform-specific, invasive) — point
+//    at the official docs, suggesting the brew cask on macOS.
+
+const GET_DOCKER_URL = "https://get.docker.com";
+const DOCKER_DOCS_URL = "https://docs.docker.com/get-docker/";
+
+/**
+ * Resolve the Docker install plan for a platform + available managers.
+ *
+ * @param {string} platform - process.platform value (linux/darwin/win32).
+ * @param {Record<string, boolean>} available - detected package managers.
+ * @returns {{ kind: "package", manager: string, command: string }
+ *          | { kind: "script", url: string }
+ *          | { kind: "manual", manualUrl: string, suggested: string|null }}
+ */
+export function dockerInstallPlan(platform = process.platform, available = {}) {
+  if (platform !== "linux") {
+    return {
+      kind: "manual",
+      manualUrl: DOCKER_DOCS_URL,
+      suggested: available.brew ? "brew install --cask docker" : null,
+    };
+  }
+  if (available.apt) return { kind: "package", manager: "apt", command: "sudo apt-get install -y docker.io" };
+  if (available.dnf) return { kind: "package", manager: "dnf", command: "sudo dnf install -y docker" };
+  return { kind: "script", url: GET_DOCKER_URL };
+}

package/src/utils/escape-regexp.js

@@ -0,0 +1,15 @@
+/**
+ * Escape regex metacharacters so a value can be interpolated into a
+ * RegExp literally (KJC-TSK-0536 — closes Semgrep's
+ * detect-non-literal-regexp findings in one move).
+ *
+ * Use this EVERY time a variable lands inside `new RegExp(...)`. It is
+ * NOT for config-provided patterns (output-guard/perf-guard policies),
+ * which are regexes by design.
+ *
+ * @param {unknown} value - coerced to string
+ * @returns {string}
+ */
+export function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/src/utils/events.js

@@ -0,0 +1,35 @@
+/**
+ * Pipeline event helpers.
+ * Extracted from orchestrator.js for reuse across modules.
+ */
+
+export function emitProgress(emitter, data) {
+  if (!emitter) return;
+  emitter.emit("progress", data);
+}
+
+export function makeEvent(type, base, extra = {}) {
+  return {
+    type,
+    sessionId: base.sessionId,
+    iteration: base.iteration,
+    stage: base.stage,
+    status: extra.status || "ok",
+    message: extra.message || type,
+    detail: extra.detail || {},
+    elapsed: base.startedAt ? Date.now() - base.startedAt : 0,
+    timestamp: new Date().toISOString()
+  };
+}
+
+/**
+ * Standard agent output emitter. Routes tool invocations to agent:action
+ * (visible in quiet mode) and everything else to agent:output (verbose only).
+ */
+export function emitAgentOutput(emitter, eventBase, stage, provider, { stream, line, kind }) {
+  const eventType = kind === "tool" ? "agent:action" : "agent:output";
+  emitProgress(emitter, makeEvent(eventType, { ...eventBase, stage }, {
+    message: line,
+    detail: { stream, agent: provider, kind }
+  }));
+}

package/src/utils/fs.js

@@ -0,0 +1,19 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export async function ensureDir(dir) {
+  await fs.mkdir(dir, { recursive: true });
+}
+
+export async function exists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch { /* file does not exist */
+    return false;
+  }
+}
+
+export function resolveFromCwd(...parts) {
+  return path.resolve(process.cwd(), ...parts);
+}