@karajan-family/code 4.21.0

package/src/utils/install-hints.js

@@ -0,0 +1,180 @@
+// Platform-aware install hints for external tools that `kj audit` /
+// `kj webperf` use (semgrep, osv-scanner, lighthouse).
+//
+// `kj doctor` calls these to render hint strings ("Install with:
+// pipx install semgrep") that match what's actually available on the
+// user's machine, rather than a generic "see docs" message. The same
+// metadata drives `kj install-tools` (HU2) — it decides which package
+// manager to invoke per tool.
+//
+// We probe each package manager once with `which`/`where`-style checks
+// and cache the result for the lifetime of the process.
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * @typedef {"pipx"|"brew"|"go"|"npm"|"pip"|"apt"|"dnf"|"choco"|"scoop"|"docker"} PackageManager
+ */
+
+/** @type {Record<PackageManager, boolean>|null} */
+let cachedAvailability = null;
+
+const PROBES = [
+  ["pipx", ["--version"]],
+  ["brew", ["--version"]],
+  ["go", ["version"]],
+  ["npm", ["--version"]],
+  ["pip", ["--version"]],
+  ["apt", ["--version"]],
+  ["dnf", ["--version"]],
+  ["choco", ["--version"]],
+  ["scoop", ["--version"]],
+  ["docker", ["--version"]],
+];
+
+async function probeOne(bin, args) {
+  try {
+    await execFileAsync(bin, args, { timeout: 3000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Detect which package managers are reachable on PATH. Cached on first
+ * call. Exported for tests; production callers go through getInstallHint.
+ */
+export async function detectPackageManagers() {
+  if (cachedAvailability) return cachedAvailability;
+  const entries = await Promise.all(
+    PROBES.map(async ([bin, args]) => [bin, await probeOne(bin, args)]),
+  );
+  cachedAvailability = Object.fromEntries(entries);
+  return cachedAvailability;
+}
+
+/** Test helper — reset the cache between unit cases. */
+export function resetPackageManagerCache() {
+  cachedAvailability = null;
+}
+
+/**
+ * Returns the install command for a tool, preferring the highest-priority
+ * package manager available on the current system.
+ *
+ * The order encodes our recommendation when multiple managers can install
+ * the same tool. We prefer isolated installs (pipx, brew) over global
+ * `pip install` so we don't pollute the user's site-packages.
+ *
+ * @param {"semgrep"|"osv-scanner"|"lighthouse"|"docker"} tool
+ * @param {Record<PackageManager, boolean>} [available] — pre-computed availability; if omitted, detects.
+ * @returns {Promise<{ command: string|null, manager: PackageManager|null, manualUrl: string }>}
+ */
+export async function getInstallHint(tool, available = null) {
+  const avail = available || (await detectPackageManagers());
+  const candidates = INSTALL_CANDIDATES[tool] || [];
+  for (const { manager, command } of candidates) {
+    if (avail[manager]) return { command, manager, manualUrl: MANUAL_URLS[tool] };
+  }
+  // Nothing matched — suggest a recipe that actually works on this system.
+  // KJC-BUG-0120 (issue #1256): distro-aware fallbacks first (PEP 668 makes
+  // the generic pip bootstrap fail on Debian/Ubuntu); these are display-only
+  // (manager: null), never auto-run — sudo stays in the user's hands.
+  for (const { when, command } of DISTRO_FALLBACKS[tool] || []) {
+    if (avail[when]) return { command, manager: null, manualUrl: MANUAL_URLS[tool] };
+  }
+  const first = candidates[0];
+  return {
+    command: first ? first.command : null,
+    manager: null,
+    manualUrl: MANUAL_URLS[tool],
+  };
+}
+
+const DISTRO_FALLBACKS = {
+  semgrep: [
+    { when: "apt", command: "sudo apt update && sudo apt install -y pipx && pipx install semgrep" },
+    { when: "dnf", command: "sudo dnf install -y pipx && pipx install semgrep" },
+  ],
+};
+
+const INSTALL_CANDIDATES = {
+  semgrep: [
+    { manager: "pipx", command: "pipx install semgrep" },
+    { manager: "brew", command: "brew install semgrep" },
+    { manager: "pip", command: "pip install semgrep" },
+  ],
+  "osv-scanner": [
+    // The module root has no main package — the binary lives in the cmd/
+    // subpackage, and since v2 the module path carries the /v2 suffix.
+    // `go install github.com/google/osv-scanner@latest` resolves the module
+    // (v1.x) but fails with "does not contain package" (KJC-BUG-0105).
+    { manager: "go", command: "go install github.com/google/osv-scanner/v2/cmd/osv-scanner@latest" },
+    { manager: "brew", command: "brew install osv-scanner" },
+  ],
+  lighthouse: [
+    { manager: "npm", command: "npm install -g lighthouse" },
+  ],
+  docker: [
+    // Docker Desktop / Engine cannot be installed by a package manager
+    // reliably across platforms — always point users to the official docs.
+    // Listing brew anyway as a hint for macOS users.
+    { manager: "brew", command: "brew install --cask docker" },
+  ],
+};
+
+const MANUAL_URLS = {
+  semgrep: "https://semgrep.dev/docs/getting-started",
+  "osv-scanner": "https://google.github.io/osv-scanner/installation/",
+  lighthouse: "https://github.com/GoogleChrome/lighthouse#using-the-cli",
+  docker: "https://docs.docker.com/get-docker/",
+  git: "https://git-scm.com/downloads",
+};
+
+// git is a `kj doctor` *required* tool. Unlike the audit tools it is installed
+// through the OS package manager, and on Linux that needs root — so the plan
+// carries a `needsSudo` flag and the caller runs those through the interactive
+// (tty-inherited) path, where sudo prompts the user directly and kj never sees
+// the password. brew/scoop/choco install at user scope, no sudo.
+const GIT_CANDIDATES = [
+  { manager: "brew", command: "brew install git", needsSudo: false },
+  { manager: "apt", command: "sudo apt-get install -y git", needsSudo: true },
+  { manager: "dnf", command: "sudo dnf install -y git", needsSudo: true },
+  { manager: "choco", command: "choco install git -y", needsSudo: false },
+  { manager: "scoop", command: "scoop install git", needsSudo: false },
+];
+
+/**
+ * Pick a git install plan for the current machine. Returns a manual plan
+ * (command null + URL) when no supported package manager is present.
+ *
+ * @param {Record<PackageManager, boolean>} available
+ * @returns {{ command: string|null, manager: PackageManager|null, needsSudo: boolean, manualUrl: string }}
+ */
+export function gitInstallPlan(available = {}) {
+  for (const { manager, command, needsSudo } of GIT_CANDIDATES) {
+    if (available[manager]) return { command, manager, needsSudo, manualUrl: MANUAL_URLS.git };
+  }
+  return { command: null, manager: null, needsSudo: false, manualUrl: MANUAL_URLS.git };
+}
+
+/**
+ * Tools whose hint depends on the project stack. lighthouse is only
+ * relevant for frontend projects; suppressing the hint elsewhere keeps
+ * `kj doctor` output free of irrelevant noise.
+ *
+ * @param {string} tool
+ * @param {Object} stack — shape returned by detectProjectStack()
+ */
+export function appliesToStack(tool, stack) {
+  if (tool === "lighthouse") {
+    if (!stack) return false;
+    return Boolean(stack.isFrontend || stack.isFullstack);
+  }
+  // semgrep, osv-scanner, docker, sonar — always relevant.
+  return true;
+}

package/src/utils/json-extract.js

@@ -0,0 +1,64 @@
+/**
+ * Robust JSON extraction from agent output.
+ * Extracts the first complete JSON object from a string,
+ * ignoring any trailing text that would cause parse errors.
+ */
+
+/**
+ * Extract the first valid JSON object from a raw string.
+ * Handles cases where agents output valid JSON followed by extra text.
+ * @param {string} raw - Raw agent output.
+ * @returns {object|null} Parsed JSON object, or null if no valid JSON found.
+ */
+export function extractFirstJson(raw) {
+  if (!raw) return null;
+  const str = typeof raw === "string" ? raw.trim() : String(raw).trim();
+  if (!str) return null;
+
+  // Fast path: try parsing the whole string first
+  try {
+    return JSON.parse(str);
+  } catch { /* fall through to extraction */ }
+
+  // Find the first '{' and match to its closing '}'
+  const start = str.indexOf("{");
+  if (start === -1) return null;
+
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+
+  for (let i = start; i < str.length; i++) {
+    const ch = str[i];
+
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+
+    if (ch === "\\") {
+      escaped = true;
+      continue;
+    }
+
+    if (ch === '"') {
+      inString = !inString;
+      continue;
+    }
+
+    if (inString) continue;
+
+    if (ch === "{") depth++;
+    if (ch === "}") depth--;
+
+    if (depth === 0) {
+      try {
+        return JSON.parse(str.substring(start, i + 1));
+      } catch { /* matched braces but not valid JSON */
+        return null;
+      }
+    }
+  }
+
+  return null;
+}

package/src/utils/locale.js

@@ -0,0 +1,59 @@
+/**
+ * OS locale detection and language instruction generation for i18n support.
+ */
+
+export const SUPPORTED_LANGUAGES = {
+  en: "English",
+  es: "Español"
+};
+
+const LANG_ENV_VARS = ["LANG", "LANGUAGE", "LC_ALL", "LC_MESSAGES"];
+
+/**
+ * Detect the 2-letter language code from OS environment variables.
+ * Checks LANG, LANGUAGE, LC_ALL, LC_MESSAGES in order.
+ * @returns {string} 2-letter language code (e.g. "en", "es")
+ */
+export function detectOsLocale() {
+  for (const envVar of LANG_ENV_VARS) {
+    const value = process.env[envVar];
+    if (value) {
+      const code = extractLangCode(value);
+      if (code) return code;
+    }
+  }
+  return "en";
+}
+
+/**
+ * Extract a 2-letter language code from a locale string.
+ * Handles formats like "es_ES.UTF-8", "en_US", "es", "C.UTF-8".
+ * @param {string} locale
+ * @returns {string|null}
+ */
+function extractLangCode(locale) {
+  const trimmed = locale.trim();
+  if (!trimmed || trimmed === "C" || trimmed === "POSIX") return null;
+  // Match first 2 lowercase letters before _, ., or end
+  const match = /^([a-z]{2})(?:[_.-]|$)/i.exec(trimmed);
+  if (match) return match[1].toLowerCase();
+  return null;
+}
+
+/**
+ * Get a prompt instruction string for the given language.
+ * Returns empty string for English (agents default to English).
+ * @param {string} lang - 2-letter language code
+ * @returns {string}
+ */
+export function getLanguageInstruction(lang) {
+  if (!lang || lang === "en") return "";
+  const languageName = SUPPORTED_LANGUAGES[lang];
+  if (lang === "es") {
+    return "IMPORTANT: Respond in Spanish. All output, explanations, and feedback must be in Spanish.";
+  }
+  if (languageName) {
+    return `IMPORTANT: Respond in ${languageName}. All output must be in ${languageName}.`;
+  }
+  return `IMPORTANT: Respond in ${lang}. All output must be in ${lang}.`;
+}

package/src/utils/logger.js

@@ -0,0 +1,96 @@
+import { EventEmitter } from "node:events";
+
+const LEVELS = ["debug", "info", "warn", "error"];
+
+const ANSI = {
+  reset: "\x1b[0m",
+  dim: "\x1b[2m",
+  cyan: "\x1b[36m",
+  yellow: "\x1b[33m",
+  red: "\x1b[31m",
+  gray: "\x1b[90m"
+};
+
+const LEVEL_COLORS = {
+  debug: ANSI.gray,
+  info: ANSI.cyan,
+  warn: ANSI.yellow,
+  error: ANSI.red
+};
+
+function timestamp() {
+  const now = new Date();
+  const h = String(now.getHours()).padStart(2, "0");
+  const m = String(now.getMinutes()).padStart(2, "0");
+  const s = String(now.getSeconds()).padStart(2, "0");
+  const ms = String(now.getMilliseconds()).padStart(3, "0");
+  return `${h}:${m}:${s}.${ms}`;
+}
+
+function formatContext(ctx) {
+  const parts = [];
+  if (ctx.iteration !== undefined) parts.push(`iter=${ctx.iteration}`);
+  if (ctx.stage) parts.push(`stage=${ctx.stage}`);
+  return parts.length ? `[${parts.join(" ")}] ` : "";
+}
+
+export function createLogger(level = "info", mode = "cli") {
+  const min = LEVELS.indexOf(level);
+  const minIdx = min === -1 ? 1 : min;
+  const emitter = new EventEmitter();
+  let context = {};
+
+  function canLog(target) {
+    return LEVELS.indexOf(target) >= minIdx;
+  }
+
+  function emit(lvl, args) {
+    const entry = {
+      level: lvl,
+      timestamp: new Date().toISOString(),
+      context: { ...context },
+      message: args.map((a) => (typeof a === "string" ? a : JSON.stringify(a))).join(" ")
+    };
+    emitter.emit("log", entry);
+  }
+
+  function log(lvl, ...args) {
+    if (!canLog(lvl)) return;
+    emit(lvl, args);
+    if (mode === "silent") return;
+    if (mode === "mcp") return;
+    const color = LEVEL_COLORS[lvl] || "";
+    const ts = `${ANSI.dim}${timestamp()}${ANSI.reset}`;
+    const prefix = `${color}[${lvl}]${ANSI.reset}`;
+    const ctx = formatContext(context);
+    let stream = console.log;
+    if (lvl === "error") {
+      stream = console.error;
+    } else if (lvl === "warn") {
+      stream = console.warn;
+    }
+    stream(`${ts} ${prefix} ${ctx}${args.map((a) => (typeof a === "string" ? a : JSON.stringify(a))).join(" ")}`);
+  }
+
+  return {
+    debug: (...args) => log("debug", ...args),
+    info: (...args) => log("info", ...args),
+    warn: (...args) => log("warn", ...args),
+    error: (...args) => log("error", ...args),
+    setContext(ctx) {
+      context = { ...context, ...ctx };
+    },
+    resetContext() {
+      context = {};
+    },
+    onLog(callback) {
+      emitter.on("log", callback);
+    },
+    offLog(callback) {
+      emitter.off("log", callback);
+    },
+    get mode() {
+      return mode;
+    }
+  };
+}

package/src/utils/managed-markers.js

@@ -0,0 +1,93 @@
+/**
+ * Managed-markers — idempotent file-block scaffolding for `kj harden`
+ * (KJC-TSK-0555, design in docs/specs/quality-harness.md §4).
+ *
+ * harden owns ONLY the content between a pair of markers; everything else in
+ * the file is preserved verbatim. Re-running with the same input is a no-op.
+ * Generalises the `KJC-TSK-0455` marker already used by the post-merge hook
+ * installer, and honours the project rule "never overwrite existing files".
+ *
+ * Block shape (comment syntax varies by file type):
+ *   # >>> kj:managed:<id> v<N> >>> (do not edit: regenerated by kj harden)
+ *   …managed body…
+ *   # <<< kj:managed:<id> <<<
+ */
+
+const DEFAULT_NOTE = "do not edit: regenerated by kj harden";
+
+/** Wrap marker payload text in the comment syntax for a given style. */
+const COMMENT = {
+  hash: (text) => `# ${text}`,
+  slash: (text) => `// ${text}`,
+  html: (text) => `<!-- ${text} -->`,
+};
+
+/** Pick a comment style from a file path. Defaults to hash (shell/yaml/conf). */
+export function commentStyleFor(filePath = "") {
+  if (/\.(md|markdown|mdx)$/i.test(filePath)) return "html";
+  if (/\.(m?[jt]sx?|c[jt]s)$/i.test(filePath)) return "slash";
+  return "hash";
+}
+
+const openPayload = (blockId, version) => `>>> kj:managed:${blockId} v${version} >>>`;
+const closePayload = (blockId) => `<<< kj:managed:${blockId} <<<`;
+
+/** Render the full managed block (open marker + body + close marker). */
+export function buildManagedBlock({ blockId, version, body, style = "hash", note = DEFAULT_NOTE }) {
+  const comment = COMMENT[style] ?? COMMENT.hash;
+  const open = comment(`${openPayload(blockId, version)} (${note})`);
+  const close = comment(closePayload(blockId));
+  return `${open}\n${body}\n${close}`;
+}
+
+/**
+ * Locate a managed block by id in `source`, regardless of comment style or
+ * version. Returns line indices and the detected version, or { found:false }.
+ */
+export function findManagedBlock(source = "", blockId) {
+  const lines = source.split("\n");
+  const openTag = `>>> kj:managed:${blockId} v`;
+  const closeTag = `<<< kj:managed:${blockId} <<<`;
+  let startLine = -1;
+  let version = null;
+  for (let i = 0; i < lines.length; i += 1) {
+    const at = lines[i].indexOf(openTag);
+    if (at === -1) continue;
+    const rest = lines[i].slice(at + openTag.length);
+    const end = rest.indexOf(" >>>");
+    const digits = end === -1 ? "" : rest.slice(0, end);
+    if (/^\d+$/.test(digits)) {
+      startLine = i;
+      version = Number(digits);
+      break;
+    }
+  }
+  if (startLine === -1) return { found: false };
+  for (let i = startLine + 1; i < lines.length; i += 1) {
+    if (lines[i].includes(closeTag)) return { found: true, startLine, endLine: i, version };
+  }
+  return { found: false, malformed: true, startLine };
+}
+
+/**
+ * Insert or update the managed block for `blockId` in `source`, preserving all
+ * content outside the markers. Idempotent: identical input → action "unchanged".
+ *
+ * @returns {{content: string, action: "inserted"|"updated"|"unchanged", previousVersion: number|null}}
+ */
+export function upsertManagedBlock({ source = "", blockId, version, body, style = "hash", note }) {
+  const block = buildManagedBlock({ blockId, version, body, style, note });
+  const existing = findManagedBlock(source, blockId);
+
+  if (!existing.found) {
+    const base = source === "" ? "" : source.replace(/\n*$/, "\n");
+    return { content: `${base}${block}\n`, action: "inserted", previousVersion: null };
+  }
+
+  const lines = source.split("\n");
+  const before = lines.slice(0, existing.startLine);
+  const after = lines.slice(existing.endLine + 1);
+  const content = [...before, ...block.split("\n"), ...after].join("\n");
+  if (content === source) return { content, action: "unchanged", previousVersion: existing.version };
+  return { content, action: "updated", previousVersion: existing.version };
+}

package/src/utils/manifest-sniff.js

@@ -0,0 +1,82 @@
+// KJC-TSK-0476 — Multi-stack manifest sniffer. Sin libs externas: JSON.parse
+// para package.json, regex para TOML y go.mod. Lo consumen audit (basal-cost)
+// y, vía PR-D, el onboarder.
+import fs from "node:fs/promises";
+import path from "node:path";
+
+async function readMaybe(file) {
+  try { return await fs.readFile(file, "utf8"); } catch { return null; }
+}
+
+async function sniffNode(dir) {
+  const raw = await readMaybe(path.join(dir, "package.json"));
+  if (!raw) return null;
+  try {
+    const pkg = JSON.parse(raw);
+    return { stack: "node", manifest: "package.json", name: pkg.name || null,
+      deps: Object.keys(pkg.dependencies || {}).length,
+      devDeps: Object.keys(pkg.devDependencies || {}).length };
+  } catch {
+    return { stack: "node", manifest: "package.json", name: null, deps: 0, devDeps: 0, malformed: true };
+  }
+}
+
+// Cuerpo TOML de `[section]` hasta el siguiente `\n[` o EOF. Lookahead con `/m`
+// cambia el significado de `$` y producía capturas vacías.
+function tomlSection(toml, section) {
+  const i = toml.indexOf(`[${section}]`);
+  if (i === -1) return "";
+  const rest = toml.slice(i + section.length + 2);
+  const n = rest.search(/\n\[/);
+  return n === -1 ? rest : rest.slice(0, n);
+}
+
+const DEP_LINE_RE = /^\s*[A-Za-z0-9_-]+\s*=/;
+const countDepLines = (block, excludePython) => block.split("\n")
+  .filter((l) => DEP_LINE_RE.test(l) && !(excludePython && /^\s*python\s*=/.test(l))).length;
+
+async function sniffPython(dir) {
+  const py = await readMaybe(path.join(dir, "pyproject.toml"));
+  if (py) {
+    const name = /^name\s*=\s*["']([^"']+)["']/m.exec(py)?.[1] || null;
+    const projectDeps = /\[project\][\s\S]*?dependencies\s*=\s*\[([^\]]*)\]/m.exec(py)?.[1] || "";
+    const projectCount = projectDeps.split(",").map((s) => s.trim()).filter(Boolean).length;
+    const poetryCount = countDepLines(tomlSection(py, "tool.poetry.dependencies"), true);
+    return { stack: "python", manifest: "pyproject.toml", name, deps: projectCount + poetryCount, devDeps: 0 };
+  }
+  const req = await readMaybe(path.join(dir, "requirements.txt"));
+  if (!req) return null;
+  const lines = req.split("\n").map((l) => l.replace(/#.*$/, "").trim()).filter(Boolean);
+  return { stack: "python", manifest: "requirements.txt", name: null, deps: lines.length, devDeps: 0 };
+}
+
+async function sniffRust(dir) {
+  const toml = await readMaybe(path.join(dir, "Cargo.toml"));
+  if (!toml) return null;
+  return { stack: "rust", manifest: "Cargo.toml",
+    name: /^name\s*=\s*["']([^"']+)["']/m.exec(toml)?.[1] || null,
+    deps: countDepLines(tomlSection(toml, "dependencies")),
+    devDeps: countDepLines(tomlSection(toml, "dev-dependencies")) };
+}
+
+async function sniffGo(dir) {
+  const mod = await readMaybe(path.join(dir, "go.mod"));
+  if (!mod) return null;
+  const block = /require\s*\(([\s\S]*?)\)/m.exec(mod)?.[1] || "";
+  const blockCount = block.split("\n").filter((l) => /\S/.test(l) && !l.trim().startsWith("//")).length;
+  const singleCount = mod.split("\n").filter((l) => /^require\s+\S+\s+\S+/.test(l)).length;
+  return { stack: "go", manifest: "go.mod",
+    name: /^module\s+(\S+)/m.exec(mod)?.[1] || null,
+    deps: blockCount + singleCount, devDeps: 0 };
+}
+
+export async function sniffManifests(dir) {
+  const r = await Promise.all([sniffNode(dir), sniffPython(dir), sniffRust(dir), sniffGo(dir)]);
+  return r.filter(Boolean);
+}
+
+export function summariseStack(manifests) {
+  if (!manifests.length) return { primary: null, multi: false, manifests: [] };
+  const ranked = [...manifests].sort((a, b) => (b.deps + b.devDeps) - (a.deps + a.devDeps));
+  return { primary: ranked[0].stack, multi: manifests.length > 1, manifests };
+}

package/src/utils/messages.js

@@ -0,0 +1,61 @@
+/**
+ * Centralized message catalog for pipeline UI strings.
+ * Supports i18n by resolving messages for the configured language.
+ * Falls back to English when a key or language is missing.
+ */
+
+const MESSAGES = {
+  en: {
+    triage_decompose: "Triage recommends decomposing this task into {count} subtasks:",
+    triage_create_cards: "Create these as linked cards in Planning Game (parent: {cardId})?",
+    triage_sequential: "Each subtask will block the next one (sequential chain).",
+    triage_reply: "Reply: yes / no",
+    solomon_conflict: "--- Conflict: {stage} ---",
+    solomon_feedback: "Reviewer feedback:",
+    solomon_reason: "Solomon could not resolve the conflict:",
+    solomon_options: "Options:\n  1. Accept coder's work as-is\n  2. Retry with reviewer's feedback\n  3. Stop the session",
+    solomon_proceed: "How should we proceed?",
+    checkpoint_continue: "Continue for {minutes} more minutes?",
+    checkpoint_options: "1. Continue 5 more minutes\n2. Continue until done (no more checkpoints)\n3. Continue for N minutes (reply with the number)\n4. Stop now",
+    preflight_passed: "Preflight passed — all checks OK",
+    pipeline_iteration: "Iteration {current}/{max}",
+  },
+  es: {
+    triage_decompose: "Triage recomienda descomponer esta tarea en {count} subtareas:",
+    triage_create_cards: "¿Crear estas como cards vinculadas en Planning Game (padre: {cardId})?",
+    triage_sequential: "Cada subtarea bloqueará la siguiente (cadena secuencial).",
+    triage_reply: "Responde: sí / no",
+    solomon_conflict: "--- Conflicto: {stage} ---",
+    solomon_feedback: "Feedback del reviewer:",
+    solomon_reason: "Solomon no pudo resolver el conflicto:",
+    solomon_options: "Opciones:\n  1. Aceptar el trabajo del coder tal cual\n  2. Reintentar con el feedback del reviewer\n  3. Parar la sesión",
+    solomon_proceed: "¿Cómo procedemos?",
+    checkpoint_continue: "¿Continuar {minutes} minutos más?",
+    checkpoint_options: "1. Continuar (5 min)\n2. Continuar hasta terminar\n3. Tiempo personalizado\n4. Parar",
+    preflight_passed: "Preflight superado — todas las comprobaciones OK",
+    pipeline_iteration: "Iteración {current}/{max}",
+  }
+};
+
+/**
+ * Resolve a message template by key and language, interpolating parameters.
+ * Falls back to English, then to the raw key if not found.
+ *
+ * @param {string} key - Message key (e.g. "solomon_conflict")
+ * @param {string} [lang="en"] - 2-letter language code
+ * @param {object} [params={}] - Interpolation values (e.g. {stage: "reviewer"})
+ * @returns {string}
+ */
+export function msg(key, lang = "en", params = {}) {
+  const template = MESSAGES[lang]?.[key] || MESSAGES.en[key] || key;
+  return template.replaceAll(/\{(\w+)\}/g, (_, k) => params[k] ?? `{${k}}`);
+}
+
+/**
+ * Extract the language code from a Karajan config object.
+ * @param {object} [config] - Karajan config
+ * @returns {string} 2-letter language code
+ */
+export function getLang(config) {
+  return config?.language || "en";
+}