karajan-code 1.57.0 → 1.58.1

package/src/domains/domain-loader.js

@@ -0,0 +1,164 @@
+/**
+ * Domain Knowledge loader.
+ * Scans .karajan/domains/ (project-local) and ~/.karajan/domains/ (user-global)
+ * for DOMAIN.md files with YAML frontmatter.
+ * Project-local domains override user-global domains by directory name.
+ */
+
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import yaml from "js-yaml";
+import { getKarajanHome } from "../utils/paths.js";
+
+const DOMAIN_FILE = "DOMAIN.md";
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+
+/**
+ * Parse a DOMAIN.md file into a structured DomainFile object.
+ * @param {string} filePath — absolute path to the DOMAIN.md file
+ * @returns {Promise<DomainFile|null>} parsed domain or null on error
+ *
+ * @typedef {Object} DomainSection
+ * @property {string} heading — section heading (e.g. "Core Concepts")
+ * @property {string} content — section body (markdown)
+ *
+ * @typedef {Object} DomainFile
+ * @property {string} name
+ * @property {string} description
+ * @property {string[]} tags
+ * @property {string} version
+ * @property {string} author
+ * @property {string} visibility — "private" | "public"
+ * @property {Array<{type: string, note?: string}>} sources
+ * @property {string} content — full markdown body (after frontmatter)
+ * @property {DomainSection[]} sections — parsed markdown sections
+ * @property {string} filePath — original file path
+ * @property {string} [origin] — "project" | "user" (set by loadDomains)
+ */
+export async function parseDomainFile(filePath) {
+  let raw;
+  try {
+    raw = await readFile(filePath, "utf-8");
+  } catch {
+    return null;
+  }
+
+  const match = raw.match(FRONTMATTER_RE);
+  if (!match) return null;
+
+  let meta;
+  try {
+    meta = yaml.load(match[1]);
+  } catch {
+    return null;
+  }
+
+  if (!meta || typeof meta !== "object" || !meta.name) return null;
+
+  const content = match[2].trim();
+  const sections = parseSections(content);
+
+  return {
+    name: meta.name,
+    description: meta.description || "",
+    tags: Array.isArray(meta.tags) ? meta.tags : [],
+    version: meta.version || "0.0.0",
+    author: meta.author || "",
+    visibility: meta.visibility || "private",
+    sources: Array.isArray(meta.sources) ? meta.sources : [],
+    content,
+    sections,
+    filePath
+  };
+}
+
+/**
+ * Split markdown content into sections by ## headings.
+ * @param {string} content
+ * @returns {DomainSection[]}
+ */
+function parseSections(content) {
+  const sections = [];
+  const lines = content.split("\n");
+  let current = null;
+
+  for (const line of lines) {
+    const headingMatch = line.match(/^##\s+(.+)/);
+    if (headingMatch) {
+      if (current) {
+        current.content = current.content.trim();
+        sections.push(current);
+      }
+      current = { heading: headingMatch[1].trim(), content: "" };
+    } else if (current) {
+      current.content += line + "\n";
+    }
+  }
+
+  if (current) {
+    current.content = current.content.trim();
+    sections.push(current);
+  }
+
+  return sections;
+}
+
+/**
+ * Load all domains from project-local and user-global directories.
+ * Project-local domains override user-global domains when directory names match.
+ *
+ * @param {string|null} projectDir — absolute path to project root (null = user-global only)
+ * @returns {Promise<DomainFile[]>}
+ */
+export async function loadDomains(projectDir) {
+  const userDir = join(getKarajanHome(), "domains");
+  const projectDomainDir = projectDir ? join(projectDir, ".karajan", "domains") : null;
+
+  // Load user-global first, then project-local overrides
+  const userDomains = await scanDomainDir(userDir, "user");
+  const projectDomains = projectDomainDir ? await scanDomainDir(projectDomainDir, "project") : [];
+
+  // Build a map keyed by directory name for merge.
+  // We track by directory name (not domain name) because the override is by directory.
+  const merged = new Map();
+
+  for (const { dirName, domain } of userDomains) {
+    merged.set(dirName, domain);
+  }
+  for (const { dirName, domain } of projectDomains) {
+    merged.set(dirName, domain); // project overrides user
+  }
+
+  return Array.from(merged.values());
+}
+
+/**
+ * Scan a single domains directory for DOMAIN.md files.
+ * @param {string} dir — absolute path to a domains/ directory
+ * @param {string} origin — "project" | "user"
+ * @returns {Promise<Array<{dirName: string, domain: DomainFile}>>}
+ */
+async function scanDomainDir(dir, origin) {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const results = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+
+    const domainPath = join(dir, entry.name, DOMAIN_FILE);
+    const domain = await parseDomainFile(domainPath);
+
+    if (domain) {
+      domain.origin = origin;
+      results.push({ dirName: entry.name, domain });
+    }
+  }
+
+  return results;
+}

package/src/domains/domain-registry.js

@@ -0,0 +1,140 @@
+/**
+ * Local domain registry.
+ * Tracks installed domains in ~/.karajan/domain-registry.json.
+ * Provides search and filtering by tags/hints.
+ * Interface prepared for future remote registry extension.
+ */
+
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { getKarajanHome } from "../utils/paths.js";
+
+const REGISTRY_FILE = "domain-registry.json";
+const SCHEMA_VERSION = 1;
+
+/**
+ * @typedef {Object} RegistryEntry
+ * @property {string} name
+ * @property {string} [description]
+ * @property {string} version
+ * @property {string} source — "local" (future: "remote")
+ * @property {string} installedAt — ISO timestamp
+ * @property {string} filePath — absolute path to DOMAIN.md
+ * @property {string[]} tags
+ */
+
+export class DomainRegistry {
+  /**
+   * @param {Record<string, RegistryEntry>} domains
+   */
+  constructor(domains = {}) {
+    this._domains = domains;
+  }
+
+  /**
+   * Load registry from disk. Creates empty registry if file is missing or corrupt.
+   * @returns {Promise<DomainRegistry>}
+   */
+  static async load() {
+    const filePath = join(getKarajanHome(), REGISTRY_FILE);
+    try {
+      const raw = await readFile(filePath, "utf-8");
+      const data = JSON.parse(raw);
+      if (data?.schemaVersion === SCHEMA_VERSION && data.domains) {
+        return new DomainRegistry(data.domains);
+      }
+    } catch { /* file missing, corrupt, or wrong schema */ }
+    return new DomainRegistry();
+  }
+
+  /**
+   * Persist registry to disk.
+   */
+  async save() {
+    const home = getKarajanHome();
+    await mkdir(home, { recursive: true });
+    const filePath = join(home, REGISTRY_FILE);
+    const data = {
+      schemaVersion: SCHEMA_VERSION,
+      domains: this._domains
+    };
+    await writeFile(filePath, JSON.stringify(data, null, 2), "utf-8");
+  }
+
+  /**
+   * Register or update a domain in the registry.
+   * @param {{name: string, version?: string, tags?: string[], filePath?: string, description?: string}} domainFile
+   */
+  register(domainFile) {
+    this._domains[domainFile.name] = {
+      name: domainFile.name,
+      description: domainFile.description || "",
+      version: domainFile.version || "0.0.0",
+      source: "local",
+      installedAt: new Date().toISOString(),
+      filePath: domainFile.filePath || "",
+      tags: domainFile.tags || []
+    };
+  }
+
+  /**
+   * List domains, optionally filtered by tags and/or free-text query.
+   * @param {{tags?: string[], query?: string}} [filters]
+   * @returns {RegistryEntry[]}
+   */
+  list(filters = {}) {
+    let entries = Object.values(this._domains);
+
+    if (filters.tags?.length) {
+      const tagSet = new Set(filters.tags.map(t => t.toLowerCase()));
+      entries = entries.filter(e =>
+        e.tags?.some(t => tagSet.has(t.toLowerCase()))
+      );
+    }
+
+    if (filters.query) {
+      const q = filters.query.toLowerCase();
+      entries = entries.filter(e =>
+        (e.name || "").toLowerCase().includes(q) ||
+        (e.description || "").toLowerCase().includes(q)
+      );
+    }
+
+    return entries;
+  }
+
+  /**
+   * Search domains by triage hints.
+   * Matches hints against tags, name and description.
+   * Returns results ranked by number of matching hints.
+   * @param {string[]} hints — keywords from triage domainHints
+   * @returns {RegistryEntry[]}
+   */
+  search(hints) {
+    if (!hints?.length) return [];
+
+    const lowerHints = hints.map(h => h.toLowerCase());
+    const entries = Object.values(this._domains);
+    const scored = [];
+
+    for (const entry of entries) {
+      const searchable = [
+        entry.name || "",
+        entry.description || "",
+        ...(entry.tags || [])
+      ].join(" ").toLowerCase();
+
+      let score = 0;
+      for (const hint of lowerHints) {
+        if (searchable.includes(hint)) score++;
+      }
+
+      if (score > 0) {
+        scored.push({ entry, score });
+      }
+    }
+
+    scored.sort((a, b) => b.score - a.score);
+    return scored.map(s => s.entry);
+  }
+}

package/src/domains/domain-synthesizer.js

@@ -0,0 +1,129 @@
+/**
+ * Domain context synthesizer.
+ * Filters relevant sections from domain files based on task + hints,
+ * and compacts the output to stay within a token budget.
+ */
+
+const DEFAULT_MAX_TOKENS = 4000;
+const CHARS_PER_TOKEN = 4;
+
+/**
+ * Synthesize a domain context string from selected domains,
+ * filtered by relevance to the task and domain hints.
+ *
+ * @param {Object} params
+ * @param {string} params.task — task description
+ * @param {string[]} params.domainHints — keywords from triage
+ * @param {import('./domain-loader.js').DomainFile[]|null} params.selectedDomains
+ * @param {number} [params.maxTokens=4000] — token budget (0 = unlimited)
+ * @returns {string} synthesized markdown context or empty string
+ */
+export function synthesizeDomainContext({ task, domainHints = [], selectedDomains, maxTokens = DEFAULT_MAX_TOKENS }) {
+  if (!selectedDomains?.length) return "";
+
+  const keywords = buildKeywords(task, domainHints);
+  const domainBlocks = [];
+
+  for (const domain of selectedDomains) {
+    const sections = domain.sections || [];
+    if (!sections.length) continue;
+
+    // Score all sections but include them all (domain was explicitly selected).
+    // Sort by relevance so highest-scoring sections survive token truncation.
+    const scored = sections
+      .map(section => ({
+        section,
+        score: scoreSection(section, keywords)
+      }))
+      .sort((a, b) => b.score - a.score);
+
+    const selected = scored.map(s => s.section);
+
+    const sectionMd = selected
+      .map(s => `#### ${s.heading}\n${s.content}`)
+      .join("\n\n");
+
+    domainBlocks.push(`### ${domain.name}\n\n${sectionMd}`);
+  }
+
+  if (!domainBlocks.length) return "";
+
+  let result = domainBlocks.join("\n\n---\n\n");
+
+  // Truncate by token budget if needed
+  if (maxTokens > 0) {
+    const maxChars = maxTokens * CHARS_PER_TOKEN;
+    if (result.length > maxChars) {
+      result = truncateBySection(result, maxChars);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Build a set of lowercase keywords from task text and domain hints.
+ * @param {string} task
+ * @param {string[]} hints
+ * @returns {string[]}
+ */
+function buildKeywords(task, hints) {
+  const words = new Set();
+
+  // Add domain hints
+  for (const h of hints) {
+    words.add(h.toLowerCase());
+  }
+
+  // Extract meaningful words from task (>3 chars, skip stop words)
+  const stopWords = new Set(["the", "this", "that", "with", "from", "have", "will", "should", "could", "would", "been", "being", "their", "there", "where", "when", "what", "which", "about", "into", "some", "than", "then", "them", "they", "also", "each", "more", "most", "other"]);
+
+  const taskWords = task
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, " ")
+    .split(/\s+/)
+    .filter(w => w.length > 3 && !stopWords.has(w));
+
+  for (const w of taskWords) {
+    words.add(w);
+  }
+
+  return Array.from(words);
+}
+
+/**
+ * Score a section by keyword overlap.
+ * @param {import('./domain-loader.js').DomainSection} section
+ * @param {string[]} keywords
+ * @returns {number}
+ */
+function scoreSection(section, keywords) {
+  const text = `${section.heading} ${section.content}`.toLowerCase();
+  let score = 0;
+  for (const kw of keywords) {
+    if (text.includes(kw)) score++;
+  }
+  return score;
+}
+
+/**
+ * Truncate result by dropping trailing sections to fit within maxChars.
+ * Preserves complete sections rather than cutting mid-sentence.
+ * @param {string} text
+ * @param {number} maxChars
+ * @returns {string}
+ */
+function truncateBySection(text, maxChars) {
+  // Split by section markers (#### or ###)
+  const parts = text.split(/(?=^#{3,4}\s)/m);
+  let result = "";
+
+  for (const part of parts) {
+    if (result.length + part.length > maxChars && result.length > 0) {
+      break;
+    }
+    result += part;
+  }
+
+  return result.trim();
+}

package/src/mcp/shared-helpers.js

@@ -104,11 +104,125 @@ export async function buildConfig(options, commandName = "run") {
   return merged;
 }
 
+/**
+ * Parse a structured response from free-text input.
+ * Exported for testing.
+ * @param {string} raw — user's raw text answer
+ * @param {string} type — question type: "multi-select" | "select" | "confirm" | "text"
+ * @param {Array<{id: string, label: string}>} [options] — available options (for select types)
+ * @returns {string[]|string|boolean|null} parsed response
+ */
+export function parseStructuredResponse(raw, type, options = []) {
+  const trimmed = (raw || "").trim();
+  const lower = trimmed.toLowerCase();
+
+  if (type === "confirm") {
+    return ["yes", "y", "si", "sí", "1", "true"].includes(lower) ? true : false;
+  }
+
+  if (type === "text") {
+    return trimmed;
+  }
+
+  if (type === "select") {
+    const num = parseInt(trimmed, 10);
+    if (!isNaN(num) && num >= 1 && num <= options.length) {
+      return options[num - 1].id;
+    }
+    // Try matching by id directly
+    const match = options.find(o => o.id.toLowerCase() === lower);
+    return match ? match.id : (options[0]?.id || null);
+  }
+
+  if (type === "multi-select") {
+    if (lower === "all") return options.map(o => o.id);
+    if (lower === "none" || lower === "0") return [];
+
+    // Parse comma-separated numbers or ids
+    const parts = trimmed.split(/[,;\s]+/).map(p => p.trim()).filter(Boolean);
+    const selected = [];
+
+    for (const part of parts) {
+      const num = parseInt(part, 10);
+      if (!isNaN(num) && num >= 1 && num <= options.length) {
+        selected.push(options[num - 1].id);
+      } else {
+        const match = options.find(o => o.id.toLowerCase() === part.toLowerCase());
+        if (match) selected.push(match.id);
+      }
+    }
+
+    return selected;
+  }
+
+  return trimmed || null;
+}
+
+/**
+ * Format a structured question into a text message for elicitInput.
+ * @param {Object} question
+ * @returns {string}
+ */
+function formatStructuredQuestion(question) {
+  const lines = [question.message, ""];
+
+  if (question.options?.length) {
+    for (let i = 0; i < question.options.length; i++) {
+      const opt = question.options[i];
+      const marker = opt.default ? "*" : " ";
+      lines.push(`  ${i + 1}.${marker} ${opt.label}`);
+    }
+    lines.push("");
+  }
+
+  if (question.type === "multi-select") {
+    lines.push("(Enter numbers separated by commas, 'all', or 'none')");
+  } else if (question.type === "select") {
+    lines.push("(Enter a number)");
+  } else if (question.type === "confirm") {
+    lines.push("(yes/no)");
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Build an askQuestion function from an MCP server.
+ * Detects host capabilities and adapts behavior accordingly.
+ *
+ * The returned function has an `.interactive` boolean property indicating
+ * whether the host supports elicitation.
+ *
+ * Accepts both plain string questions (backward compatible) and structured
+ * question objects ({message, type, options, defaults}).
+ *
+ * @param {Object} server — MCP server instance
+ * @returns {Function & {interactive: boolean}}
+ */
 export function buildAskQuestion(server) {
-  return async (question) => {
+  const canElicit = Boolean(server.getClientCapabilities?.()?.elicitation);
+
+  const askQuestion = async (question) => {
+    const isStructured = question && typeof question === "object" && question.message;
+
+    // Non-interactive: return defaults or null
+    if (!canElicit) {
+      if (!isStructured) return null;
+      if (question.defaults) return question.defaults;
+      if (question.type === "confirm") return false;
+      return null;
+    }
+
+    // Build the message text
+    const message = isStructured
+      ? formatStructuredQuestion(question)
+      : question;
+
+    // Call elicitInput
+    let rawAnswer;
     try {
       const result = await server.elicitInput({
-        message: question,
+        message,
         requestedSchema: {
           type: "object",
           properties: {
@@ -117,11 +231,25 @@ export function buildAskQuestion(server) {
           required: ["answer"]
         }
       });
-      return result.action === "accept" ? result.content?.answer || null : null;
+      rawAnswer = result.action === "accept" ? result.content?.answer || null : null;
     } catch {
-      return null;
+      return isStructured && question.defaults ? question.defaults : null;
     }
+
+    if (rawAnswer === null) {
+      return isStructured && question.defaults ? question.defaults : null;
+    }
+
+    // Parse structured response
+    if (isStructured && question.type) {
+      return parseStructuredResponse(rawAnswer, question.type, question.options);
+    }
+
+    return rawAnswer;
   };
+
+  askQuestion.interactive = canElicit;
+  return askQuestion;
 }
 
 const EVENT_LOG_LEVELS = {

package/src/orchestrator/pipeline-context.js

@@ -40,6 +40,9 @@ export class PipelineContext {
     // Product context (loaded from .karajan/context.md or product-vision.md)
     this.productContext = null;
 
+    // Domain context (synthesized by Domain Curator from ~/.karajan/domains/ and .karajan/domains/)
+    this.domainContext = null;
+
     // Planned task (may differ from original task after planner)
     this.plannedTask = null;
 

package/src/orchestrator/preflight-checks.js

@@ -38,19 +38,30 @@ async function checkDocker() {
   };
 }
 
+const SONAR_STARTUP_POLL_MS = 5000;
+const SONAR_STARTUP_MAX_WAIT_MS = 60000;
+
+async function waitForSonar(host, maxWaitMs = SONAR_STARTUP_MAX_WAIT_MS) {
+  const deadline = Date.now() + maxWaitMs;
+  while (Date.now() < deadline) {
+    if (await isSonarReachable(host)) return true;
+    await new Promise(r => setTimeout(r, SONAR_STARTUP_POLL_MS));
+  }
+  return false;
+}
+
 async function checkSonarReachable(host) {
   const reachable = await isSonarReachable(host);
   if (reachable) {
     return { name: "sonar-reachable", ok: true, detail: `SonarQube reachable at ${host}`, remediated: false };
   }
 
-  // Auto-remediation: try to start SonarQube
+  // Auto-remediation: start SonarQube and wait for it to be ready
   try {
     const upResult = await sonarUp(host);
     if (upResult.exitCode === 0) {
-      // Verify it's actually reachable now
-      const reachableAfter = await isSonarReachable(host);
-      if (reachableAfter) {
+      // SonarQube needs 20-40s to start. Poll until ready.
+      if (await waitForSonar(host)) {
         return { name: "sonar-reachable", ok: true, detail: `SonarQube started and reachable at ${host}`, remediated: true };
       }
     }
@@ -58,7 +69,7 @@ async function checkSonarReachable(host) {
     // sonarUp failed, fall through
   }
 
-  return { name: "sonar-reachable", ok: false, detail: `SonarQube not reachable at ${host} (auto-start failed)` };
+  return { name: "sonar-reachable", ok: false, detail: `SonarQube not reachable at ${host} (auto-start failed after ${SONAR_STARTUP_MAX_WAIT_MS / 1000}s)` };
 }
 
 async function checkSonarAuth(config) {