karajan-code 1.6.2 → 1.8.0

package/README.md

@@ -42,6 +42,7 @@ Instead of running one AI agent and manually reviewing its output, `kj` chains a
 - **Interactive checkpoints** — instead of killing long-running tasks, pauses every 5 minutes with a progress report and lets you decide: continue, stop, or adjust the time
 - **Task decomposition** — triage detects when tasks should be split and recommends subtasks; with Planning Game integration, creates linked cards with sequential blocking
 - **Retry with backoff** — automatic recovery from transient API errors (429, 5xx) with exponential backoff and jitter
+- **Pipeline stage tracker** — cumulative progress view during `kj_run` showing which stages are done, running, or pending — both in CLI and via MCP events for real-time host rendering
 - **Planning Game integration** — optionally pair with [Planning Game](https://github.com/AgenteIA-Geniova/planning-game) for agile project management (tasks, sprints, estimation) — like Jira, but open-source and XP-native
 
 > **Best with MCP** — Karajan Code is designed to be used as an MCP server inside your AI agent (Claude, Codex, etc.). The agent sends tasks to `kj_run`, gets real-time progress notifications, and receives structured results — no copy-pasting needed.
@@ -447,7 +448,7 @@ Use `kj roles show <role>` to inspect any template. Create a project override to
 git clone https://github.com/manufosela/karajan-code.git
 cd karajan-code
 npm install
-npm test              # Run 1025+ tests with Vitest
+npm test              # Run 1040+ tests with Vitest
 npm run test:watch    # Watch mode
 npm run validate      # Lint + test
 ```

package/docs/README.es.md

@@ -41,6 +41,7 @@ En lugar de ejecutar un agente de IA y revisar manualmente su output, `kj` encad
 - **Checkpoints interactivos** — en lugar de matar tareas largas, pausa cada 5 minutos con un informe de progreso y te deja decidir: continuar, parar o ajustar el tiempo
 - **Descomposicion de tareas** — triage detecta cuando una tarea debe dividirse y recomienda subtareas; con integracion Planning Game, crea cards vinculadas con bloqueo secuencial
 - **Retry con backoff** — recuperacion automatica ante errores transitorios de API (429, 5xx) con backoff exponencial y jitter
+- **Pipeline stage tracker** — vista de progreso acumulativo durante `kj_run` mostrando que stages estan completadas, en ejecucion o pendientes — tanto en CLI como via eventos MCP para renderizado en tiempo real en el host
 - **Integracion con Planning Game** — combina opcionalmente con [Planning Game](https://github.com/AgenteIA-Geniova/planning-game) para gestion agil de proyectos (tareas, sprints, estimacion) — como Jira, pero open-source y nativo XP
 
 > **Mejor con MCP** — Karajan Code esta disenado para usarse como servidor MCP dentro de tu agente de IA (Claude, Codex, etc.). El agente envia tareas a `kj_run`, recibe notificaciones de progreso en tiempo real, y obtiene resultados estructurados — sin copiar y pegar.
@@ -231,7 +232,7 @@ Usa `kj roles show <rol>` para inspeccionar cualquier template. Crea un override
 git clone https://github.com/manufosela/karajan-code.git
 cd karajan-code
 npm install
-npm test              # Ejecutar 899+ tests con Vitest
+npm test              # Ejecutar 1040+ tests con Vitest
 npm run test:watch    # Modo watch
 npm run validate      # Lint + test
 ```

package/package.json

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

package/src/cli.js

@@ -1,4 +1,7 @@
 #!/usr/bin/env node
+import path from "node:path";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 import { Command } from "commander";
 import { applyRunOverrides, loadConfig, validateConfig } from "./config.js";
 import { createLogger } from "./utils/logger.js";
@@ -15,6 +18,9 @@ import { resumeCommand } from "./commands/resume.js";
 import { sonarCommand, sonarOpenCommand } from "./commands/sonar.js";
 import { rolesCommand } from "./commands/roles.js";
 
+const PKG_PATH = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../package.json");
+const PKG_VERSION = JSON.parse(readFileSync(PKG_PATH, "utf8")).version;
+
 async function withConfig(commandName, flags, fn) {
   const { config } = await loadConfig();
   const merged = applyRunOverrides(config, flags || {});
@@ -24,7 +30,7 @@ async function withConfig(commandName, flags, fn) {
 }
 
 const program = new Command();
-program.name("kj").description("Karajan Code CLI").version("1.6.2");
+program.name("kj").description("Karajan Code CLI").version(PKG_VERSION);
 
 program
   .command("init")

package/src/mcp/orphan-guard.js

@@ -1,3 +1,6 @@
+import { readFileSync } from "node:fs";
+import { watch } from "node:fs";
+
 const DEFAULT_INTERVAL_MS = 5000;
 
 export function setupOrphanGuard({ intervalMs = DEFAULT_INTERVAL_MS, exitFn = () => process.exit(0) } = {}) {
@@ -19,3 +22,27 @@ export function setupOrphanGuard({ intervalMs = DEFAULT_INTERVAL_MS, exitFn = ()
 
   return { timer, parentPid };
 }
+
+export function setupVersionWatcher({ pkgPath, currentVersion, exitFn = () => process.exit(0) } = {}) {
+  if (!pkgPath) return null;
+
+  function checkVersion() {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+      if (pkg.version !== currentVersion) {
+        exitFn();
+        return true;
+      }
+    } catch { /* ignore read errors */ }
+    return false;
+  }
+
+  let watcher = null;
+  try {
+    watcher = watch(pkgPath, { persistent: false }, () => {
+      checkVersion();
+    });
+  } catch { /* ignore watch errors */ }
+
+  return { watcher, checkVersion };
+}

package/src/mcp/progress.js

@@ -21,9 +21,74 @@ export const PROGRESS_STAGES = [
   "solomon:escalate",
   "question",
   "session:end",
-  "dry-run:summary"
+  "dry-run:summary",
+  "pipeline:tracker"
 ];
 
+const PIPELINE_ORDER = [
+  "triage", "researcher", "planner", "coder", "refactorer", "sonar", "reviewer", "tester", "security", "commiter"
+];
+
+export function buildPipelineTracker(config, emitter) {
+  const pipeline = config.pipeline || {};
+
+  const stages = PIPELINE_ORDER
+    .filter(name => {
+      if (name === "coder") return true;
+      if (name === "reviewer") return pipeline.reviewer?.enabled !== false;
+      if (name === "sonar") return pipeline.sonar?.enabled || config.sonarqube?.enabled;
+      return pipeline[name]?.enabled;
+    })
+    .map(name => ({ name, status: "pending", summary: undefined }));
+
+  const findStage = (name) => stages.find(s => s.name === name);
+
+  const emitTracker = () => {
+    emitter.emit("progress", {
+      type: "pipeline:tracker",
+      detail: { stages: stages.map(s => ({ ...s })) }
+    });
+  };
+
+  emitter.on("progress", (event) => {
+    const match = event.type?.match(/^(\w+):(start|end)$/);
+    if (!match) return;
+
+    const [, name, phase] = match;
+    const stage = findStage(name);
+    if (!stage) return;
+
+    if (phase === "start") {
+      stage.status = "running";
+      stage.summary = event.detail?.[name] || stage.summary;
+    } else {
+      stage.status = event.status === "fail" ? "failed" : "done";
+      stage.summary = event.detail?.summary || event.detail?.gateStatus || stage.summary;
+    }
+
+    emitTracker();
+  });
+
+  return { stages };
+}
+
+export function sendTrackerLog(server, stageName, status, summary) {
+  try {
+    server.sendLoggingMessage({
+      level: "info",
+      logger: "karajan",
+      data: {
+        type: "pipeline:tracker",
+        detail: {
+          stages: [{ name: stageName, status, summary: summary || undefined }]
+        }
+      }
+    });
+  } catch {
+    // best-effort
+  }
+}
+
 export function buildProgressHandler(server) {
   return (event) => {
     try {

package/src/mcp/server-handlers.js

@@ -4,13 +4,21 @@
  */
 
 import { EventEmitter } from "node:events";
+import fs from "node:fs/promises";
 import { runKjCommand } from "./run-kj.js";
 import { normalizePlanArgs } from "./tool-arg-normalizers.js";
-import { buildProgressHandler, buildProgressNotifier } from "./progress.js";
+import { buildProgressHandler, buildProgressNotifier, buildPipelineTracker, sendTrackerLog } from "./progress.js";
 import { runFlow, resumeFlow } from "../orchestrator.js";
 import { loadConfig, applyRunOverrides, validateConfig, resolveRole } from "../config.js";
 import { createLogger } from "../utils/logger.js";
 import { assertAgentsAvailable } from "../agents/availability.js";
+import { createAgent } from "../agents/index.js";
+import { buildPlannerPrompt } from "../prompts/planner.js";
+import { buildCoderPrompt } from "../prompts/coder.js";
+import { buildReviewerPrompt } from "../prompts/reviewer.js";
+import { parseMaybeJsonString } from "../review/parser.js";
+import { computeBaseRef, generateDiff } from "../review/diff-generator.js";
+import { resolveReviewProfile } from "../review/profiles.js";
 
 export function asObject(value) {
   if (value && typeof value === "object") return value;
@@ -93,10 +101,10 @@ export function enrichedFailPayload(error, toolName) {
   return payload;
 }
 
-export async function buildConfig(options) {
+export async function buildConfig(options, commandName = "run") {
   const { config } = await loadConfig();
   const merged = applyRunOverrides(config, options || {});
-  validateConfig(merged, "run");
+  validateConfig(merged, commandName);
   return merged;
 }
 
@@ -143,6 +151,7 @@ export async function handleRunDirect(a, server, extra) {
   emitter.on("progress", buildProgressHandler(server));
   const progressNotifier = buildProgressNotifier(extra);
   if (progressNotifier) emitter.on("progress", progressNotifier);
+  buildPipelineTracker(config, emitter);
 
   const askQuestion = buildAskQuestion(server);
   const pgTaskId = a.pgTask || null;
@@ -173,6 +182,82 @@ export async function handleResumeDirect(a, server, extra) {
   return { ok: true, ...result };
 }
 
+export async function handlePlanDirect(a, server, extra) {
+  const options = normalizePlanArgs(a);
+  const config = await buildConfig(options, "plan");
+  const logger = createLogger(config.output.log_level, "mcp");
+
+  const plannerRole = resolveRole(config, "planner");
+  await assertAgentsAvailable([plannerRole.provider]);
+
+  const planner = createAgent(plannerRole.provider, config, logger);
+  const prompt = buildPlannerPrompt({ task: a.task, context: a.context });
+  sendTrackerLog(server, "planner", "running", plannerRole.provider);
+  const result = await planner.runTask({ prompt, role: "planner" });
+
+  if (!result.ok) {
+    sendTrackerLog(server, "planner", "failed");
+    throw new Error(result.error || result.output || "Planner failed");
+  }
+
+  sendTrackerLog(server, "planner", "done");
+  const parsed = parseMaybeJsonString(result.output);
+  return { ok: true, plan: parsed || result.output, raw: result.output };
+}
+
+export async function handleCodeDirect(a, server, extra) {
+  const config = await buildConfig(a, "code");
+  const logger = createLogger(config.output.log_level, "mcp");
+
+  const coderRole = resolveRole(config, "coder");
+  await assertAgentsAvailable([coderRole.provider]);
+
+  const coder = createAgent(coderRole.provider, config, logger);
+  let coderRules = null;
+  if (config.coder_rules) {
+    try {
+      coderRules = await fs.readFile(config.coder_rules, "utf8");
+    } catch { /* no coder rules file */ }
+  }
+  const prompt = buildCoderPrompt({ task: a.task, coderRules, methodology: config.development?.methodology || "tdd" });
+  sendTrackerLog(server, "coder", "running", coderRole.provider);
+  const result = await coder.runTask({ prompt, role: "coder" });
+
+  if (!result.ok) {
+    sendTrackerLog(server, "coder", "failed");
+    throw new Error(result.error || result.output || `Coder failed (exit ${result.exitCode})`);
+  }
+
+  sendTrackerLog(server, "coder", "done");
+  return { ok: true, output: result.output, exitCode: result.exitCode };
+}
+
+export async function handleReviewDirect(a, server, extra) {
+  const config = await buildConfig(a, "review");
+  const logger = createLogger(config.output.log_level, "mcp");
+
+  const reviewerRole = resolveRole(config, "reviewer");
+  await assertAgentsAvailable([reviewerRole.provider, config.reviewer_options?.fallback_reviewer]);
+
+  const reviewer = createAgent(reviewerRole.provider, config, logger);
+  const resolvedBase = await computeBaseRef({ baseBranch: config.base_branch, baseRef: a.baseRef });
+  const diff = await generateDiff({ baseRef: resolvedBase });
+  const { rules } = await resolveReviewProfile({ mode: config.review_mode, projectDir: process.cwd() });
+
+  const prompt = buildReviewerPrompt({ task: a.task, diff, reviewRules: rules, mode: config.review_mode });
+  sendTrackerLog(server, "reviewer", "running", reviewerRole.provider);
+  const result = await reviewer.reviewTask({ prompt, role: "reviewer" });
+
+  if (!result.ok) {
+    sendTrackerLog(server, "reviewer", "failed");
+    throw new Error(result.error || result.output || `Reviewer failed (exit ${result.exitCode})`);
+  }
+
+  sendTrackerLog(server, "reviewer", "done");
+  const parsed = parseMaybeJsonString(result.output);
+  return { ok: true, review: parsed || result.output, raw: result.output };
+}
+
 export async function handleToolCall(name, args, server, extra) {
   const a = asObject(args);
 
@@ -240,22 +325,21 @@ export async function handleToolCall(name, args, server, extra) {
     if (!a.task) {
       return failPayload("Missing required field: task");
     }
-    return runKjCommand({ command: "code", commandArgs: [a.task], options: a });
+    return handleCodeDirect(a, server, extra);
   }
 
   if (name === "kj_review") {
     if (!a.task) {
       return failPayload("Missing required field: task");
     }
-    return runKjCommand({ command: "review", commandArgs: [a.task], options: a });
+    return handleReviewDirect(a, server, extra);
   }
 
   if (name === "kj_plan") {
     if (!a.task) {
       return failPayload("Missing required field: task");
     }
-    const options = normalizePlanArgs(a);
-    return runKjCommand({ command: "plan", commandArgs: [a.task], options });
+    return handlePlanDirect(a, server, extra);
   }
 
   return failPayload(`Unknown tool: ${name}`);

package/src/mcp/server.js

@@ -1,14 +1,26 @@
 #!/usr/bin/env node
+import path from "node:path";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { tools } from "./tools.js";
 import { handleToolCall, responseText, enrichedFailPayload } from "./server-handlers.js";
 
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const PKG_PATH = path.resolve(MODULE_DIR, "../../package.json");
+
+function readVersion() {
+  return JSON.parse(readFileSync(PKG_PATH, "utf8")).version;
+}
+
+const LOADED_VERSION = readVersion();
+
 const server = new Server(
   {
     name: "karajan-mcp",
-    version: "1.0.0"
+    version: LOADED_VERSION
   },
   {
     capabilities: {
@@ -22,6 +34,9 @@ const server = new Server(
 server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
 
 server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+  // Auto-exit if package version changed (stale process)
+  if (readVersion() !== LOADED_VERSION) process.exit(0);
+
   const name = request.params?.name;
   const args = request.params?.arguments || {};
 
@@ -33,9 +48,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
   }
 });
 
-// --- Orphan process protection ---
-import { setupOrphanGuard } from "./orphan-guard.js";
+// --- Orphan process protection + version watcher ---
+import { setupOrphanGuard, setupVersionWatcher } from "./orphan-guard.js";
 setupOrphanGuard();
+setupVersionWatcher({ pkgPath: PKG_PATH, currentVersion: LOADED_VERSION });
 
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/src/mcp/tools.js

@@ -146,8 +146,7 @@ export const tools = [
         task: { type: "string" },
         coder: { type: "string" },
         coderModel: { type: "string" },
-        kjHome: { type: "string" },
-        timeoutMs: { type: "number" }
+        kjHome: { type: "string" }
       }
     }
   },
@@ -162,8 +161,7 @@ export const tools = [
         reviewer: { type: "string" },
         reviewerModel: { type: "string" },
         baseRef: { type: "string" },
-        kjHome: { type: "string" },
-        timeoutMs: { type: "number" }
+        kjHome: { type: "string" }
       }
     }
   },
@@ -179,8 +177,7 @@ export const tools = [
         plannerModel: { type: "string" },
         coder: { type: "string", description: "Legacy alias for planner" },
         coderModel: { type: "string", description: "Legacy alias for plannerModel" },
-        kjHome: { type: "string" },
-        timeoutMs: { type: "number" }
+        kjHome: { type: "string" }
       }
     }
   }

package/src/utils/display.js

@@ -1,3 +1,10 @@
+import path from "node:path";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+const DISPLAY_PKG_PATH = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../package.json");
+const DISPLAY_VERSION = JSON.parse(readFileSync(DISPLAY_PKG_PATH, "utf8")).version;
+
 const ANSI = {
   reset: "\x1b[0m",
   bold: "\x1b[1m",
@@ -57,7 +64,7 @@ export function formatElapsed(ms) {
 const BAR = `${ANSI.dim}\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500${ANSI.reset}`;
 
 export function printHeader({ task, config }) {
-  const version = "0.1.0";
+  const version = DISPLAY_VERSION;
   console.log(BAR);
   console.log(`${ANSI.bold}${ANSI.cyan}\u25b6 Karajan Code v${version}${ANSI.reset}`);
   console.log(BAR);
@@ -336,6 +343,26 @@ export function printEvent(event) {
       console.log(`${ANSI.dim}Resume with: kj resume ${event.sessionId} --answer "<response>"${ANSI.reset}`);
       break;
 
+    case "pipeline:tracker": {
+      const trackerStages = event.detail?.stages || [];
+      console.log(`  ${ANSI.dim}\u250c Pipeline${ANSI.reset}`);
+      for (const stage of trackerStages) {
+        let stIcon, stColor;
+        switch (stage.status) {
+          case "done": stIcon = "\u2713"; stColor = ANSI.green; break;
+          case "running": stIcon = "\u25b6"; stColor = ANSI.cyan; break;
+          case "failed": stIcon = "\u2717"; stColor = ANSI.red; break;
+          default: stIcon = "\u00b7"; stColor = ANSI.dim; break;
+        }
+        const suffix = stage.summary
+          ? stage.status === "running" ? ` (${stage.summary})` : ` \u2192 ${stage.summary}`
+          : "";
+        console.log(`  ${ANSI.dim}\u2502${ANSI.reset} ${stColor}${stIcon} ${stage.name}${suffix}${ANSI.reset}`);
+      }
+      console.log(`  ${ANSI.dim}\u2514${ANSI.reset}`);
+      break;
+    }
+
     case "agent:output":
       console.log(`  \u2502 ${ANSI.dim}${event.message}${ANSI.reset}`);
       break;