karajan-code 1.57.2 → 1.58.1

package/README.md

@@ -63,12 +63,24 @@ npm install -g karajan-code
 brew install manufosela/tap/karajan-code
 ```
 
+**Standalone binary** (no Node.js needed):
+```bash
+# macOS (Apple Silicon)
+curl -L https://github.com/manufosela/karajan-code/releases/latest/download/kj-darwin-arm64 -o kj && chmod +x kj
+
+# Linux x64
+curl -L https://github.com/manufosela/karajan-code/releases/latest/download/kj-linux-x64 -o kj && chmod +x kj
+
+# Windows
+curl -L https://github.com/manufosela/karajan-code/releases/latest/download/kj-win-x64.exe -o kj.exe
+```
+
 **One-liner** (detects OS, installs via npm):
 ```bash
 curl -fsSL https://raw.githubusercontent.com/manufosela/karajan-code/main/scripts/install-kj.sh | sh
 ```
 
-**Docker** (no Node.js needed):
+**Docker**:
 ```bash
 docker run --rm -v $(pwd):/workspace karajan-code kj --version
 ```
@@ -156,15 +168,16 @@ $ claude                         $ kj-tail
 ## The pipeline
 
 ```
-hu-reviewer? → triage → discover? → architect? → planner? → coder → sonar? → impeccable? → reviewer → tester? → security? → solomon → commiter?
+hu-reviewer? → triage → domain-curator? → discover? → architect? → planner? → coder → sonar? → impeccable? → reviewer → tester? → security? → solomon → commiter?
 ```
 
-**15 roles**, each executed by the AI agent you choose:
+**16 roles**, each executed by the AI agent you choose:
 
 | Role | What it does | Default |
 |------|-------------|---------|
 | **hu-reviewer** | Certifies user stories before coding (6 dimensions, 7 antipatterns) | Auto (medium/complex) |
-| **triage** | Classifies complexity, activates roles, auto-simplifies for trivial tasks | **On** |
+| **triage** | Classifies complexity, activates roles, detects domain hints | **On** |
+| **domain-curator** | Discovers, proposes and synthesizes business-domain knowledge for the pipeline | Auto (when domains exist) |
 | **discover** | Detects gaps in requirements (Mom Test, Wendel, JTBD) | Off |
 | **architect** | Designs solution architecture before planning | Off |
 | **planner** | Generates structured implementation plans | Off |
@@ -228,7 +241,7 @@ Karajan auto-detects and auto-configures everything it can:
 - **TDD**: Detects test framework for 12 languages (vitest, jest, JUnit, pytest, go test, cargo test, and more). Auto-enables TDD for code tasks, skips for doc/infra
 - **Bootstrap gate**: Validates all prerequisites (git repo, remote, config, agents, SonarQube) before any tool runs. Fails hard with actionable fix instructions, never silently degrades
 - **Injection guard**: Scans diffs for prompt injection before AI review. Detects directive overrides, invisible Unicode, oversized comment payloads. Also runs as a GitHub Action on every PR
-- **SonarQube**: Auto-starts Docker container, generates config if missing
+- **SonarQube**: Auto-starts Docker container, waits up to 60s for startup, generates config if missing
 - **Pipeline complexity**: Triage classifies task → trivial tasks skip reviewer loop
 - **Provider outages**: Retries on 500/502/503/504 with backoff (same as rate limits)
 - **Coverage**: Coverage-only quality gate failures treated as advisory

package/docs/README.es.md

@@ -63,12 +63,24 @@ npm install -g karajan-code
 brew install manufosela/tap/karajan-code
 ```
 
+**Binario standalone** (sin Node.js):
+```bash
+# macOS (Apple Silicon)
+curl -L https://github.com/manufosela/karajan-code/releases/latest/download/kj-darwin-arm64 -o kj && chmod +x kj
+
+# Linux x64
+curl -L https://github.com/manufosela/karajan-code/releases/latest/download/kj-linux-x64 -o kj && chmod +x kj
+
+# Windows
+curl -L https://github.com/manufosela/karajan-code/releases/latest/download/kj-win-x64.exe -o kj.exe
+```
+
 **One-liner** (detecta SO, instala via npm):
 ```bash
 curl -fsSL https://raw.githubusercontent.com/manufosela/karajan-code/main/scripts/install-kj.sh | sh
 ```
 
-**Docker** (sin Node.js):
+**Docker**:
 ```bash
 docker run --rm -v $(pwd):/workspace karajan-code kj --version
 ```
@@ -129,15 +141,16 @@ kj-tail --help           # Todas las opciones
 ## El pipeline
 
 ```
-hu-reviewer? → triage → discover? → architect? → planner? → coder → sonar? → impeccable? → reviewer → tester? → security? → solomon → commiter?
+hu-reviewer? → triage → domain-curator? → discover? → architect? → planner? → coder → sonar? → impeccable? → reviewer → tester? → security? → solomon → commiter?
 ```
 
-**15 roles**, cada uno ejecutado por el agente de IA que elijas:
+**16 roles**, cada uno ejecutado por el agente de IA que elijas:
 
 | Rol | Que hace | Por defecto |
 |-----|----------|-------------|
 | **hu-reviewer** | Certifica historias de usuario antes de codificar (6 dimensiones, 7 antipatrones) | Auto (media/compleja) |
-| **triage** | Clasifica complejidad, activa roles, auto-simplifica para tareas triviales | **On** |
+| **triage** | Clasifica complejidad, activa roles, detecta domain hints | **On** |
+| **domain-curator** | Descubre, propone y sintetiza conocimiento de dominio de negocio para el pipeline | Auto (cuando existen dominios) |
 | **discover** | Detecta huecos en requisitos (Mom Test, Wendel, JTBD) | Off |
 | **architect** | Diseña la arquitectura de la solucion antes de planificar | Off |
 | **planner** | Genera planes de implementacion estructurados | Off |
@@ -201,7 +214,7 @@ Karajan auto-detecta y auto-configura todo lo que puede:
 - **TDD**: Detecta framework de tests para 12 lenguajes (vitest, jest, JUnit, pytest, go test, cargo test, y mas). Auto-activa TDD para tareas de codigo, lo salta para doc/infra
 - **Bootstrap gate**: Valida todos los prerequisitos (repo git, remote, config, agentes, SonarQube) antes de ejecutar. Falla con instrucciones claras, nunca degrada silenciosamente
 - **Injection guard**: Escanea diffs en busca de prompt injection antes del review de IA. Detecta directivas de override, Unicode invisible, payloads en comentarios sobredimensionados. Tambien como GitHub Action en cada PR
-- **SonarQube**: Auto-arranca contenedor Docker, genera config si falta
+- **SonarQube**: Auto-arranca contenedor Docker, espera hasta 60s al arranque, genera config si falta
 - **Complejidad del pipeline**: Triage clasifica la tarea, las triviales saltan el loop del reviewer
 - **Caidas de proveedor**: Reintentos en 500/502/503/504 con backoff (igual que rate limits)
 - **Cobertura**: Fallos de quality gate solo por cobertura se tratan como advisory

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "1.57.2",
+  "version": "1.58.1",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

package/src/cli.js

@@ -28,6 +28,7 @@ import { undoCommand } from "./commands/undo.js";
 import { statusCommand } from "./commands/status.js";
 
 import { printUpdateNotice } from "./utils/update-check.js";
+import { printWelcomeScreen } from "./utils/welcome.js";
 
 const PKG_PATH = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../package.json");
 const PKG_VERSION = JSON.parse(readFileSync(PKG_PATH, "utf8")).version;
@@ -369,6 +370,12 @@ sonar
     console.log(`Opened ${result.url}`);
   });
 
+// Show welcome screen when invoked with no subcommand
+program.action(async () => {
+  const { config } = await loadConfig().catch(() => ({ config: null }));
+  printWelcomeScreen({ version: PKG_VERSION, config });
+});
+
 try {
   await program.parseAsync();
 } catch (error) {

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();
+}