karajan-code 2.5.0 → 2.6.0

package/src/utils/display/solomon.js

@@ -0,0 +1,42 @@
+import { ANSI } from "./formatters.js";
+
+export 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/port-check.js

@@ -0,0 +1,45 @@
+/**
+ * TCP port availability helpers.
+ *
+ * Originally lived in packages/hu-board/src/server.js. Moved here so the
+ * doctor/preflight subsystem (src/checks/) and hu-board share a single
+ * implementation.
+ */
+
+import { createServer } from "node:net";
+
+/**
+ * Check whether a TCP port is available to bind on localhost.
+ *
+ * @param {number} port
+ * @returns {Promise<boolean>}
+ */
+export function isPortAvailable(port) {
+  return new Promise((resolve) => {
+    const server = createServer();
+    server.once("error", () => resolve(false));
+    server.once("listening", () => {
+      server.close();
+      resolve(true);
+    });
+    server.listen(port);
+  });
+}
+
+/**
+ * Find the first available port starting from `startPort`.
+ *
+ * @param {number} startPort       - first port to try
+ * @param {number} [maxAttempts=11] - how many consecutive ports to probe
+ * @param {(port: number) => void} [onBusy] - called for each busy port seen
+ * @returns {Promise<number>}      - resolves with the first free port found
+ * @throws {Error} if no port is free within the range
+ */
+export async function findAvailablePort(startPort, maxAttempts = 11, onBusy) {
+  for (let i = 0; i < maxAttempts; i++) {
+    const port = startPort + i;
+    if (await isPortAvailable(port)) return port;
+    if (onBusy) onBusy(port);
+  }
+  throw new Error(`No available port found between ${startPort} and ${startPort + maxAttempts - 1}`);
+}

package/src/utils/port-occupant.js

@@ -0,0 +1,95 @@
+/**
+ * Detect which process is holding a TCP port. Cross-platform best-effort:
+ *   - Linux/macOS: try `lsof -iTCP:PORT -sTCP:LISTEN -n -P -Fpcn` (parsable),
+ *     fall back to `ss -tlnp` for Linux-only pid detection.
+ *   - Windows: `netstat -ano` + `tasklist` to resolve image name.
+ *
+ * Returns null if the port is free or we cannot determine the occupant.
+ * Never throws — designed to enrich diagnostic messages, not to gate logic.
+ */
+
+import { runCommand } from "./process.js";
+
+/**
+ * @typedef {Object} PortOccupant
+ * @property {number} port
+ * @property {number|null} pid
+ * @property {string|null} command      - process name ("karajan-sonarqube", "node", etc.)
+ * @property {string} raw               - raw tool output for debugging
+ */
+
+/**
+ * @param {number} port
+ * @returns {Promise<PortOccupant|null>}
+ */
+export async function getPortOccupant(port) {
+  if (process.platform === "win32") {
+    return detectWindows(port);
+  }
+  const byLsof = await detectLsof(port);
+  if (byLsof) return byLsof;
+  return detectSs(port);
+}
+
+async function detectLsof(port) {
+  try {
+    const res = await runCommand("lsof", [
+      `-iTCP:${port}`,
+      "-sTCP:LISTEN",
+      "-n",
+      "-P",
+      "-Fpcn",
+    ]);
+    if (res.exitCode !== 0 || !res.stdout.trim()) return null;
+    // Format: lines starting with p<pid>, c<command>, n<name>
+    const lines = res.stdout.split("\n").filter(Boolean);
+    let pid = null;
+    let command = null;
+    for (const line of lines) {
+      if (line.startsWith("p")) pid = Number(line.slice(1)) || null;
+      else if (line.startsWith("c")) command = line.slice(1) || null;
+    }
+    return { port, pid, command, raw: res.stdout };
+  } catch {
+    return null;
+  }
+}
+
+async function detectSs(port) {
+  try {
+    const res = await runCommand("ss", ["-tlnpH", `sport = :${port}`]);
+    if (res.exitCode !== 0 || !res.stdout.trim()) return null;
+    // Example line: LISTEN 0 511 0.0.0.0:4000 0.0.0.0:* users:(("node",pid=12345,fd=20))
+    const match = res.stdout.match(/users:\(\("([^"]+)",pid=(\d+)/);
+    if (!match) return null;
+    return { port, pid: Number(match[2]), command: match[1], raw: res.stdout };
+  } catch {
+    return null;
+  }
+}
+
+async function detectWindows(port) {
+  try {
+    const netstat = await runCommand("netstat", ["-ano"]);
+    if (netstat.exitCode !== 0) return null;
+    const line = netstat.stdout
+      .split(/\r?\n/)
+      .find((l) => l.match(new RegExp(`:${port}\\s+.*LISTENING`)));
+    if (!line) return null;
+    const parts = line.trim().split(/\s+/);
+    const pid = Number(parts[parts.length - 1]) || null;
+    if (!pid) return { port, pid: null, command: null, raw: line };
+    const tasklist = await runCommand("tasklist", ["/FI", `PID eq ${pid}`, "/FO", "CSV", "/NH"]);
+    const command = parseTasklist(tasklist.stdout);
+    return { port, pid, command, raw: `${line}\n${tasklist.stdout}` };
+  } catch {
+    return null;
+  }
+}
+
+function parseTasklist(stdout) {
+  const line = stdout.split(/\r?\n/).find(Boolean);
+  if (!line) return null;
+  const match = line.match(/^"([^"]+)"/);
+  return match ? match[1] : null;
+}

package/src/utils/provider-env.js

@@ -0,0 +1,116 @@
+/**
+ * Mapping of AI provider → required environment variable(s), plus helpers to
+ * determine which ones are actually needed by the current active config.
+ *
+ * The Check subsystem uses this to validate tokens LAZILY: we only demand an
+ * API key when a role is configured to use the provider behind it. Providers
+ * that run fully locally (e.g. opencode via a self-hosted proxy) are marked
+ * `optional: true` and only warn if their key is missing.
+ */
+
+/**
+ * @typedef {Object} ProviderEnv
+ * @property {string} provider
+ * @property {string[]} envVars     - env var names that would satisfy the check (first match wins)
+ * @property {string} howToGetUrl   - user-facing URL to obtain a key
+ * @property {boolean} optional     - warn vs fail when missing
+ */
+
+/** @type {Record<string, ProviderEnv>} */
+export const PROVIDER_ENV = Object.freeze({
+  anthropic: {
+    provider: "anthropic",
+    envVars: ["ANTHROPIC_API_KEY"],
+    howToGetUrl: "https://console.anthropic.com/settings/keys",
+    optional: false,
+  },
+  openai: {
+    provider: "openai",
+    envVars: ["OPENAI_API_KEY"],
+    howToGetUrl: "https://platform.openai.com/api-keys",
+    optional: false,
+  },
+  google: {
+    provider: "google",
+    envVars: ["GEMINI_API_KEY", "GOOGLE_API_KEY"],
+    howToGetUrl: "https://aistudio.google.com/app/apikey",
+    optional: false,
+  },
+  opencode: {
+    provider: "opencode",
+    envVars: ["OPENCODE_API_KEY"],
+    howToGetUrl: "https://opencode.ai/docs",
+    optional: true, // local/self-hosted — may not need an API key
+  },
+  aider: {
+    provider: "aider",
+    envVars: ["AIDER_API_KEY"],
+    howToGetUrl: "https://aider.chat/docs/usage.html",
+    optional: true,
+  },
+});
+
+/**
+ * Returns true if any of the env vars for a provider is set non-empty.
+ * @param {ProviderEnv} entry
+ */
+export function hasEnvVar(entry) {
+  return entry.envVars.some((name) => {
+    const v = process.env[name];
+    return typeof v === "string" && v.trim().length > 0;
+  });
+}
+
+/**
+ * Walk the active config and collect the set of providers currently in use
+ * by at least one role.
+ *
+ * @param {Object} config - Karajan config (loaded)
+ * @returns {Set<string>} - set of provider slugs (e.g. "anthropic", "openai")
+ */
+export function collectActiveProviders(config) {
+  const providers = new Set();
+  const roles = config?.roles || {};
+  for (const [, roleCfg] of Object.entries(roles)) {
+    const provider = roleCfg?.provider;
+    if (typeof provider === "string" && provider.trim().length > 0) {
+      providers.add(provider);
+    }
+  }
+  // Also include top-level default coder/reviewer if set (legacy shape).
+  if (config?.coder) providers.add(config.coder);
+  if (config?.reviewer) providers.add(config.reviewer);
+  return providers;
+}
+
+/**
+ * Map active providers to the env vars we must validate.
+ *
+ * @param {Object} config
+ * @returns {ProviderEnv[]}
+ */
+export function getRequiredProviderEnvs(config) {
+  const active = collectActiveProviders(config);
+  const required = [];
+  for (const providerSlug of active) {
+    // Some configs store agent names (claude, codex, gemini) rather than
+    // canonical provider names. Map them.
+    const canonical = normalizeProvider(providerSlug);
+    const entry = PROVIDER_ENV[canonical];
+    if (entry) required.push(entry);
+  }
+  return required;
+}
+
+/**
+ * Normalize CLI/agent name to canonical provider slug.
+ */
+export function normalizeProvider(name) {
+  const lc = String(name || "").toLowerCase();
+  if (lc === "claude" || lc === "anthropic") return "anthropic";
+  if (lc === "codex" || lc === "openai") return "openai";
+  if (lc === "gemini" || lc === "google") return "google";
+  if (lc === "opencode") return "opencode";
+  if (lc === "aider") return "aider";
+  return lc;
+}

package/src/utils/with-timeout.js

@@ -0,0 +1,42 @@
+/**
+ * Timeout wrapper for arbitrary promises.
+ *
+ * Produces a new Promise that resolves with the original value if the
+ * underlying promise settles within `ms`, or rejects with a TimeoutError if
+ * it doesn't. Intended for wrapping individual checks in the doctor/preflight
+ * runner so a slow HTTP probe cannot hang the whole pipeline.
+ *
+ * The original promise keeps running after timeout (we cannot cancel it
+ * without cooperation). Callers should avoid calling `withTimeout` on
+ * side-effectful operations they need to be sure completed.
+ */
+
+export class TimeoutError extends Error {
+  constructor(label, ms) {
+    super(`Timeout after ${ms}ms${label ? ` (${label})` : ""}`);
+    this.name = "TimeoutError";
+    this.timeoutMs = ms;
+    this.label = label;
+  }
+}
+
+/**
+ * @template T
+ * @param {Promise<T>} promise
+ * @param {number} ms
+ * @param {string} [label] - for error messages / logs
+ * @returns {Promise<T>}
+ */
+export function withTimeout(promise, ms, label) {
+  if (!Number.isFinite(ms) || ms <= 0) return promise;
+
+  let timerId;
+  const timeout = new Promise((_resolve, reject) => {
+    timerId = setTimeout(() => reject(new TimeoutError(label, ms)), ms);
+    if (timerId && typeof timerId.unref === "function") timerId.unref();
+  });
+
+  return Promise.race([promise, timeout]).finally(() => {
+    if (timerId) clearTimeout(timerId);
+  });
+}

package/templates/roles/architect/anthropic.md

@@ -0,0 +1,65 @@
+# Architect Role (Claude-optimized)
+
+<role>
+You are the Architect in a multi-role AI pipeline. Design the technical architecture for a task BEFORE implementation. Leverage Claude's strengths: reason carefully about tradeoffs, surface hidden coupling, challenge unstated assumptions.
+</role>
+
+<responsibilities>
+- Define architecture type (layered, microservices, event-driven, monolith, ...).
+- Identify layers and their responsibilities.
+- Select design patterns with clear rationale.
+- Define the data model (entities + relationships).
+- Specify API contracts (REST, events, interfaces).
+- List internal and external dependencies.
+- Document tradeoffs with pros/cons.
+- Flag questions that MUST be answered before implementation.
+- Evaluate containerization (Docker / Docker Compose) and recommend when it aids dev consistency or deployment.
+</responsibilities>
+
+<verdict>
+- **ready** — architecture fully defined, implementation can proceed.
+- **needs_clarification** — critical decisions blocked on missing info. Put every blocker in `questions`.
+</verdict>
+
+<design_guidelines>
+1. **Type** — choose the minimum style that solves the problem.
+2. **Layers** — explicit boundaries (presentation / business / data / ...).
+3. **Patterns** — pick each one to solve a named problem; document the WHY.
+4. **Data Model** — entities + key attributes.
+5. **API Contracts** — endpoints, request/response schemas, or event contracts.
+6. **Dependencies** — packages, services, infra.
+7. **Tradeoffs** — every significant decision documented with pros/cons.
+</design_guidelines>
+
+<rules>
+- Respect existing codebase patterns and conventions.
+- Prefer simplicity. Minimum architecture that solves the problem.
+- Document WHY each pattern was chosen, not just WHAT.
+- Use research context when provided.
+- NEVER invent requirements — add uncertainty to `questions`.
+</rules>
+
+<output_format>
+Return a single valid JSON object and nothing else.
+
+```json
+{
+  "verdict": "ready|needs_clarification",
+  "architecture": {
+    "type": "layered|microservices|event-driven|monolith|etc.",
+    "layers": ["presentation", "business", "data"],
+    "patterns": ["repository", "factory", "observer"],
+    "dataModel": {
+      "entities": ["User", "Session", "Token"]
+    },
+    "apiContracts": ["POST /auth/login", "GET /auth/me"],
+    "dependencies": ["bcrypt", "jsonwebtoken"],
+    "tradeoffs": ["JWT allows stateless auth but cannot be revoked without a blacklist"]
+  },
+  "questions": ["Which database engine should be used?"],
+  "summary": "Brief human-readable summary of the architecture"
+}
+```
+
+If the architecture is fully defined, `verdict: "ready"` and `questions: []`.
+</output_format>

package/templates/roles/architect/default.md

@@ -0,0 +1,63 @@
+# Architect Role
+
+You are the **Architect** in a multi-role AI pipeline. Your job is to design the technical architecture for a task before implementation begins.
+
+## Responsibilities
+
+- Define the architecture type and structure (layered, microservices, event-driven, etc.)
+- Identify layers and their responsibilities
+- Select appropriate design patterns
+- Define the data model with entities and relationships
+- Specify API contracts (REST endpoints, events, interfaces)
+- List internal and external dependencies
+- Document tradeoffs and their rationale
+- Flag areas where clarification is needed before implementation
+- Evaluate if the project benefits from containerization (Docker/Docker Compose) for development consistency and deployment, and recommend it in the architecture output if appropriate
+
+## Verdict
+
+- **ready**: The architecture is well-defined and implementation can proceed
+- **needs_clarification**: Critical architectural decisions cannot be made without additional information
+
+## Architecture Design Guidelines
+
+1. **Type** — Choose the most appropriate architecture style for the task
+2. **Layers** — Define clear boundaries between layers (presentation, business logic, data access, etc.)
+3. **Patterns** — Select patterns that solve specific problems (repository, factory, observer, strategy, etc.)
+4. **Data Model** — List entities and their key attributes
+5. **API Contracts** — Define endpoints, request/response formats, or event schemas
+6. **Dependencies** — List required packages, services, or infrastructure
+7. **Tradeoffs** — Document every significant decision with pros/cons
+
+## Output format
+
+Return a single valid JSON object and nothing else.
+
+```json
+{
+  "verdict": "ready|needs_clarification",
+  "architecture": {
+    "type": "layered|microservices|event-driven|monolith|etc.",
+    "layers": ["presentation", "business", "data"],
+    "patterns": ["repository", "factory", "observer"],
+    "dataModel": {
+      "entities": ["User", "Session", "Token"]
+    },
+    "apiContracts": ["POST /auth/login", "GET /auth/me"],
+    "dependencies": ["bcrypt", "jsonwebtoken"],
+    "tradeoffs": ["JWT allows stateless auth but cannot be revoked without a blacklist"]
+  },
+  "questions": ["Which database engine should be used?"],
+  "summary": "Brief human-readable summary of the architecture"
+}
+```
+
+If the architecture is fully defined with no open questions, return `verdict: "ready"` with an empty `questions` array.
+
+## Rules
+
+- Always consider the existing codebase patterns and conventions
+- Prefer simplicity over complexity — choose the minimum architecture that solves the problem
+- Document WHY each pattern was chosen, not just WHAT
+- If research context is provided, use it to inform architectural decisions
+- Never invent requirements — if something is unclear, add it to questions

package/templates/roles/architect/google.md

@@ -0,0 +1,52 @@
+# Architect Role (Gemini-optimized)
+
+You are the Architect. Design the technical architecture BEFORE implementation.
+
+## Responsibilities
+
+- Architecture type, layers, patterns, data model, API contracts, dependencies, tradeoffs, open questions, and containerization recommendation when relevant.
+
+## Verdict
+
+- `ready` — implementation can proceed with the provided architecture.
+- `needs_clarification` — at least one critical decision is blocked.
+
+## Examples
+
+### Example 1 — simple task (verdict: ready)
+
+Task: "Add caching to the /search endpoint (TTL 60s, key = query string)."
+
+```json
+{
+  "verdict": "ready",
+  "architecture": {
+    "type": "layered",
+    "layers": ["route", "cache", "search-service"],
+    "patterns": ["cache-aside"],
+    "dataModel": { "entities": ["SearchResult"] },
+    "apiContracts": ["GET /search?q=..."],
+    "dependencies": ["lru-cache"],
+    "tradeoffs": ["lru-cache chosen over redis for zero infra cost; loses cross-instance coherence"]
+  },
+  "questions": [],
+  "summary": "Cache-aside with lru-cache, TTL 60s, keyed by query string."
+}
+```
+
+### Example 2 — ambiguous task (verdict: needs_clarification)
+
+Task: "Add multi-tenant support."
+
+Questions MUST include which isolation level (shared DB + tenant_id column vs schema-per-tenant vs DB-per-tenant), auth strategy, billing model.
+
+## Rules
+
+- Minimum architecture that solves the problem.
+- Document WHY each pattern was chosen, not just WHAT.
+- Respect existing codebase patterns.
+- NEVER invent requirements — add uncertainty to `questions`.
+
+## Output (strict JSON)
+
+Same shape as Example 1. Exactly one top-level object. No prose around it.

package/templates/roles/architect/openai.md

@@ -0,0 +1,51 @@
+# Architect Role
+
+You are the Architect. Design the technical architecture BEFORE implementation.
+
+## RESPONSIBILITIES
+
+- Define architecture type (layered / microservices / event-driven / monolith / ...).
+- Identify layers + responsibilities.
+- Select design patterns with rationale.
+- Define data model (entities + relationships).
+- Specify API contracts (REST, events, interfaces).
+- List internal/external dependencies.
+- Document tradeoffs with pros/cons.
+- Flag blocking questions.
+- Recommend containerization when it aids dev consistency or deployment.
+
+## VERDICT
+
+- `ready` — implementation can proceed.
+- `needs_clarification` — critical decisions missing. List every blocker in `questions`.
+
+## RULES
+
+- Respect existing codebase patterns.
+- Minimum architecture that solves the problem.
+- Document WHY each pattern was chosen.
+- Use research context when provided.
+- NEVER invent requirements — add uncertainty to `questions`.
+
+## OUTPUT (strict JSON)
+
+```json
+{
+  "verdict": "ready|needs_clarification",
+  "architecture": {
+    "type": "layered|microservices|event-driven|monolith|etc.",
+    "layers": ["presentation", "business", "data"],
+    "patterns": ["repository", "factory", "observer"],
+    "dataModel": {
+      "entities": ["User", "Session", "Token"]
+    },
+    "apiContracts": ["POST /auth/login", "GET /auth/me"],
+    "dependencies": ["bcrypt", "jsonwebtoken"],
+    "tradeoffs": ["JWT allows stateless auth but cannot be revoked without a blacklist"]
+  },
+  "questions": ["Which database engine should be used?"],
+  "summary": "Brief human-readable summary of the architecture"
+}
+```
+
+If fully defined → `verdict: "ready"` and `questions: []`.

package/templates/roles/architect/opencode.md

@@ -0,0 +1,50 @@
+# Architect
+
+Role: design the technical architecture for the task before implementation.
+
+## Required fields
+
+- verdict: "ready" or "needs_clarification"
+- architecture.type: one of layered, microservices, event-driven, monolith, hybrid
+- architecture.layers: array of strings
+- architecture.patterns: array of strings (each must solve a named problem)
+- architecture.dataModel.entities: array of strings
+- architecture.apiContracts: array of strings
+- architecture.dependencies: array of strings
+- architecture.tradeoffs: array of strings (each must state pros AND cons)
+- questions: array of strings (blocking decisions; empty if verdict is "ready")
+- summary: one short sentence
+
+## Rules
+
+- Choose the smallest architecture that solves the problem.
+- Never invent requirements. Unknowns go to `questions`.
+- Document WHY each pattern was chosen.
+- Respect existing codebase patterns and conventions.
+- Recommend Docker/Docker Compose only when it materially improves dev consistency or deployment.
+
+## Output
+
+Return exactly this JSON shape. Nothing before. Nothing after.
+
+```json
+{
+  "verdict": "ready",
+  "architecture": {
+    "type": "layered",
+    "layers": [],
+    "patterns": [],
+    "dataModel": { "entities": [] },
+    "apiContracts": [],
+    "dependencies": [],
+    "tradeoffs": []
+  },
+  "questions": [],
+  "summary": "short sentence"
+}
+```
+
+Rules for the JSON:
+- Exact keys only. No extras.
+- All arrays may be empty but never null.
+- If `verdict` is "needs_clarification", `questions` must be non-empty.