@karajan-family/code 4.21.0

package/src/lang/chunk-rust.js

@@ -0,0 +1,102 @@
+// KJC-PCS-0052 PR-B.2.2 — Rust source chunker (tree-sitter + regex fallback).
+// Mismo contrato síncrono que chunk-python: AST si el caller awaited
+// `prepareRust()` antes, regex si no. Top-level items (fn / struct / enum /
+// trait / impl / mod) son la frontera de chunk.
+//
+// El nodo `impl_item` no tiene field `name`; usamos el campo `type` para
+// que metadata.symbol apunte al tipo implementado (útil para grep en RAG).
+
+import { getLoaded, loadLanguage } from "./tree-sitter-loader.js";
+
+const DEFAULT_LIMIT = 800;
+const DEFAULT_OVERLAP = 100;
+const NAMED_KINDS = new Set([
+  "function_item",
+  "struct_item",
+  "enum_item",
+  "trait_item",
+  "mod_item",
+  "type_item",
+  "union_item",
+]);
+const TOP_RE = /^(?:pub(?:\([^)]*\))?\s+)?(?:async\s+|unsafe\s+|extern\s+(?:"[^"]+"\s+)?)*(?:fn|struct|enum|trait|mod|type|union|impl)(?:\s+(?:<[^>]+>\s+)?)?([A-Za-z_][\w]*)/gm;
+
+export async function prepareRust() {
+  return loadLanguage("rust");
+}
+
+function windowText(text, limit, overlap) {
+  if (text.length <= limit) return [text];
+  const step = Math.max(1, limit - overlap);
+  const out = [];
+  for (let i = 0; i < text.length; i += step) {
+    out.push(text.slice(i, i + limit));
+    if (i + limit >= text.length) break;
+  }
+  return out;
+}
+
+function symbolForImpl(node) {
+  const typeNode = node.childForFieldName("type");
+  return typeNode ? typeNode.text : null;
+}
+
+function marksViaAST(text) {
+  const entry = getLoaded("rust");
+  if (!entry) return null;
+  let tree;
+  try {
+    tree = entry.parser.parse(text);
+  } catch {
+    return null;
+  }
+  const marks = [];
+  let pendingAttrStart = null;
+  for (const child of tree.rootNode.namedChildren) {
+    if (child.type === "attribute_item" || child.type === "inner_attribute_item") {
+      if (pendingAttrStart === null) pendingAttrStart = child.startIndex;
+      continue;
+    }
+    let symbol = null;
+    if (NAMED_KINDS.has(child.type)) {
+      const nameNode = child.childForFieldName("name");
+      if (nameNode) symbol = nameNode.text;
+    } else if (child.type === "impl_item") {
+      symbol = symbolForImpl(child);
+    }
+    if (symbol) {
+      const idx = pendingAttrStart ?? child.startIndex;
+      marks.push({ idx, symbol });
+    }
+    pendingAttrStart = null;
+  }
+  return marks;
+}
+
+function marksViaRegex(text) {
+  const marks = [];
+  TOP_RE.lastIndex = 0;
+  let m;
+  while ((m = TOP_RE.exec(text)) !== null) marks.push({ idx: m.index, symbol: m[1] });
+  return marks;
+}
+
+export function chunkRust(text, { path = "<src>", limit = DEFAULT_LIMIT, overlap = DEFAULT_OVERLAP } = {}) {
+  const marks = marksViaAST(text) ?? marksViaRegex(text);
+  if (marks.length === 0) {
+    return windowText(text, limit, overlap).map((piece) => ({
+      text: piece,
+      metadata: { source: path, kind: "code", symbol: null, language: "rust" },
+    }));
+  }
+  const out = [];
+  for (let i = 0; i < marks.length; i += 1) {
+    const start = marks[i].idx;
+    const end = i + 1 < marks.length ? marks[i + 1].idx : text.length;
+    const body = text.slice(start, end);
+    for (const piece of windowText(body, limit, overlap)) {
+      out.push({ text: piece, metadata: { source: path, kind: "code", symbol: marks[i].symbol, language: "rust" } });
+    }
+  }
+  return out;
+}

package/src/lang/go.js

@@ -0,0 +1,14 @@
+// KJC-PCS-0052 PR-B.2.3 — Go adapter. Detección por go.mod/go.sum; vendor/
+// y bin/ no se recorren (vendor lo usa `go mod vendor`, bin son builds).
+// chunk-go usa AST (tree-sitter) cuando el caller hizo `await prepareGo()`
+// y cae a regex en otro caso (mismo patrón que PYTHON_ADAPTER / RUST_ADAPTER).
+import { chunkGo, prepareGo } from "./chunk-go.js";
+
+export const GO_ADAPTER = {
+  id: "go",
+  extensions: [".go"],
+  skipSegments: ["vendor", "bin"],
+  manifests: ["go.mod", "go.sum"],
+  chunkSource: chunkGo,
+  prepare: prepareGo,
+};

package/src/lang/java.js

@@ -0,0 +1,16 @@
+// KJC-PCS-0052 PR-B.2.5 — Java adapter. Detección por pom.xml / build.gradle
+// (Maven, Gradle Groovy y Kotlin DSL). target/ y build/ son outputs estándar
+// de ambos sistemas; .gradle/ es el cache del wrapper; out/ lo usan IDEs
+// (IntelliJ/Eclipse) para classes. chunk-java usa AST (tree-sitter) cuando
+// el caller hizo `await prepareJava()` y cae a regex en otro caso (mismo
+// patrón que GO_ADAPTER / RUST_ADAPTER / PYTHON_ADAPTER).
+import { chunkJava, prepareJava } from "./chunk-java.js";
+
+export const JAVA_ADAPTER = {
+  id: "java",
+  extensions: [".java"],
+  skipSegments: ["target", "build", ".gradle", "out"],
+  manifests: ["pom.xml", "build.gradle", "build.gradle.kts"],
+  chunkSource: chunkJava,
+  prepare: prepareJava,
+};

package/src/lang/js.js

@@ -0,0 +1,8 @@
+// KJC-PCS-0052 PR-A — JS/TS adapter. Codifica las constantes que vivían
+// hard-coded en src/rag/indexer.js antes del registry.
+export const JS_ADAPTER = {
+  id: "js",
+  extensions: [".js", ".mjs", ".cjs", ".ts", ".tsx", ".jsx"],
+  skipSegments: ["node_modules", ".next", ".nuxt", ".svelte-kit"],
+  manifests: ["package.json"],
+};

package/src/lang/python.js

@@ -0,0 +1,14 @@
+// KJC-PCS-0052 PR-A/PR-B — Python adapter. Detección por manifest activa
+// el adapter; virtualenvs y caches se excluyen del walk. PR-B añade
+// `chunkSource` regex top-level (def/async def/class) — tree-sitter real
+// queda para PR-B.2 (decisión WASM vs native).
+import { chunkPython, preparePython } from "./chunk-python.js";
+
+export const PYTHON_ADAPTER = {
+  id: "python",
+  extensions: [".py"],
+  skipSegments: ["__pycache__", ".venv", "venv", ".tox", ".pytest_cache", ".mypy_cache", ".ruff_cache"],
+  manifests: ["pyproject.toml", "setup.py", "setup.cfg", "requirements.txt", "Pipfile"],
+  chunkSource: chunkPython,
+  prepare: preparePython,
+};

package/src/lang/registry.js

@@ -0,0 +1,79 @@
+// KJC-PCS-0052 PR-A — Language adapter registry. Antes vivían CODE_EXT_RE
+// y SKIP_SEGMENTS hardcoded en indexer.js (solo JS/TS); ahora cada adapter
+// declara extensiones, skipSegments y manifests. PR-B añadirá AST chunkers
+// (tree-sitter); PR-C/D usan el mismo registry para audit y onboarder.
+import { existsSync } from "node:fs";
+import { extname, join } from "node:path";
+
+import { GO_ADAPTER } from "./go.js";
+import { JAVA_ADAPTER } from "./java.js";
+import { JS_ADAPTER } from "./js.js";
+import { PYTHON_ADAPTER } from "./python.js";
+import { RUST_ADAPTER } from "./rust.js";
+
+// Segmentos siempre excluidos del walk, independientes de stack: VCS,
+// outputs de build, scratch de Karajan, sandbox del audit. Lo que viva
+// aquí jamás se indexa.
+const COMMON_SKIP_SEGMENTS = [".git", "dist", "build", "coverage", ".karajan", ".kj", "_diet"];
+
+const REGISTRY = [JS_ADAPTER, PYTHON_ADAPTER, RUST_ADAPTER, GO_ADAPTER, JAVA_ADAPTER];
+
+export function getAdapters() {
+  return REGISTRY.slice();
+}
+
+/**
+ * Detecta qué adapters aplican a un projectDir mirando los manifests
+ * declarados. Si ningún adapter coincide (proyecto sin manifest), cae
+ * a JS para no romper repos legacy o sandboxes de tests.
+ */
+export function detectAdaptersForProject(projectDir) {
+  if (!projectDir) return [JS_ADAPTER];
+  const matched = REGISTRY.filter((a) => a.manifests.some((m) => existsSync(join(projectDir, m))));
+  return matched.length ? matched : [JS_ADAPTER];
+}
+
+/**
+ * Construye los matchers que usa el indexer al recorrer el árbol:
+ * `isCodeFile(path)` decide si la extensión cuadra con algún adapter
+ * activo; `shouldSkip(path)` aplica la unión de skipSegments comunes +
+ * los del adapter. Devuelve también `extensions` por si el caller quiere
+ * inspeccionarlas (p.ej. tests).
+ */
+export function buildMatchers(adapters) {
+  const extSet = new Set();
+  const skipSet = new Set(COMMON_SKIP_SEGMENTS);
+  for (const a of adapters) {
+    for (const e of a.extensions) extSet.add(e.toLowerCase());
+    for (const s of a.skipSegments || []) skipSet.add(s);
+  }
+  return {
+    isCodeFile: (p) => extSet.has(extname(p).toLowerCase()),
+    shouldSkip: (p) => p.split("/").some((seg) => skipSet.has(seg)),
+    extensions: [...extSet],
+  };
+}
+
+/**
+ * Unión de extensiones de TODOS los adapters registrados. Útil para
+ * `detectKind` en el indexer, que recibe un path suelto sin saber el
+ * projectDir y necesita reconocer una extensión de código aunque venga
+ * de un adapter no detectado en el proyecto actual.
+ */
+export function getAllCodeExtensions() {
+  const out = new Set();
+  for (const a of REGISTRY) for (const e of a.extensions) out.add(e.toLowerCase());
+  return [...out];
+}
+
+/**
+ * KJC-PCS-0052 PR-B — devuelve el adapter cuya `extensions` cubre el
+ * path, o `null` si ninguno matchea. Lo consume el chunker para delegar
+ * a un chunker específico por lenguaje (p.ej. Python).
+ */
+export function adapterForPath(path) {
+  if (!path) return null;
+  const ext = extname(path).toLowerCase();
+  for (const a of REGISTRY) if (a.extensions.includes(ext)) return a;
+  return null;
+}

package/src/lang/rust.js

@@ -0,0 +1,14 @@
+// KJC-PCS-0052 PR-B.2.2 — Rust adapter. Detección por Cargo.toml; target/
+// y skip segments evitan que el indexer recorra builds. chunk-rust usa
+// AST (tree-sitter) cuando el caller hizo `await prepareRust()` y cae a
+// regex en otro caso (mismo patrón que PYTHON_ADAPTER).
+import { chunkRust, prepareRust } from "./chunk-rust.js";
+
+export const RUST_ADAPTER = {
+  id: "rust",
+  extensions: [".rs"],
+  skipSegments: ["target", ".cargo"],
+  manifests: ["Cargo.toml", "Cargo.lock"],
+  chunkSource: chunkRust,
+  prepare: prepareRust,
+};

package/src/lang/tree-sitter-loader.js

@@ -0,0 +1,45 @@
+// KJC-PCS-0052 PR-B.2.1 — Lazy loader for web-tree-sitter parsers.
+// Async init (Parser.init + Language.load) is paid once per language id
+// and cached. Callers that want AST chunking must `await loadLanguage(...)`
+// during pre-loop; the per-file chunker then reads the cached entry
+// synchronously via `getLoaded(id)` and falls back to regex if not ready.
+//
+// Pure WASM (web-tree-sitter) over native bindings: no node-gyp build, no
+// per-platform .node files — works inside the SEA binary because the
+// grammar `.wasm` files travel with the npm package under
+// `vendor/tree-sitter-grammars/` (see ../../vendor/.../README.md).
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+
+import { Language, Parser } from "web-tree-sitter";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const GRAMMAR_DIR = resolve(HERE, "../../vendor/tree-sitter-grammars");
+
+const cache = new Map();
+let runtimePromise = null;
+
+async function initRuntime() {
+  if (!runtimePromise) runtimePromise = Parser.init();
+  return runtimePromise;
+}
+
+function grammarPath(id) {
+  return resolve(GRAMMAR_DIR, `${id}.wasm`);
+}
+
+export async function loadLanguage(id, wasmPath = grammarPath(id)) {
+  if (cache.has(id)) return cache.get(id);
+  await initRuntime();
+  const language = await Language.load(wasmPath);
+  const parser = new Parser();
+  parser.setLanguage(language);
+  const entry = { parser, language };
+  cache.set(id, entry);
+  return entry;
+}
+
+export function getLoaded(id) {
+  return cache.get(id) || null;
+}
+

package/src/mcp/direct-role-runner.js

@@ -0,0 +1,112 @@
+/**
+ * Shared runner for direct role execution (discover, triage, researcher, architect, audit).
+ * Extracts the repeated boilerplate from server-handlers.js handleXxxDirect functions.
+ */
+
+import { createStallDetector } from "../utils/stall-detector.js";
+import { resolveRole } from "../config.js";
+import { createLogger } from "../utils/logger.js";
+import { assertAgentsAvailable } from "../agents/availability.js";
+import { createRunLog } from "../utils/run-log.js";
+import { sendTrackerLog } from "./progress.js";
+
+/**
+ * Run a role-based tool directly (not through the orchestrator pipeline).
+ *
+ * @param {object} opts
+ * @param {string} opts.roleName     - Config role key (e.g. "discover", "triage")
+ * @param {string} [opts.stage]      - Stage label for events/logs (defaults to roleName)
+ * @param {Function} opts.importRole - Async fn returning { RoleClass } (dynamic import wrapper)
+ * @param {object} opts.initContext  - Object passed to role.init()
+ * @param {object} opts.runInput     - Object passed to role.run() (onOutput is injected automatically)
+ * @param {string} [opts.logStartMsg] - Custom "[kj_xxx] started" suffix (optional)
+ * @param {object} opts.args         - Raw tool arguments (for buildConfig overrides)
+ * @param {string} [opts.commandName] - Config command name (defaults to roleName)
+ * @param {object} opts.server       - MCP server instance
+ * @param {object} opts.extra        - MCP extra context (for progress notifier)
+ * @param {Function} opts.resolveProjectDir - Async fn(server, explicitDir) => projectDir
+ * @param {Function} opts.buildConfig       - Async fn(args, commandName) => config
+ * @param {Function} opts.buildDirectEmitter - fn(server, runLog, extra) => emitter
+ */
+export async function runDirectRole({
+  roleName,
+  stage,
+  importRole,
+  initContext,
+  runInput,
+  logStartMsg,
+  args,
+  commandName,
+  server,
+  extra,
+  resolveProjectDir,
+  buildConfig,
+  buildDirectEmitter
+}) {
+  const effectiveStage = stage || roleName;
+  const effectiveCommand = commandName || roleName;
+
+  const config = await buildConfig(args, effectiveCommand);
+  const logger = createLogger(config.output.log_level, "mcp");
+
+  const role = resolveRole(config, roleName);
+  await assertAgentsAvailable([role.provider]);
+
+  const projectDir = await resolveProjectDir(server, args.projectDir);
+
+  // Allow taskFile as alternative to inline task — works for every direct
+  // role (discover/triage/researcher/architect/audit/impeccable/...) without
+  // per-handler wiring. The mutation is in-place on the role's runInput /
+  // initContext since they are already built with `task: a.task`.
+  if ((!runInput?.task || runInput.task === undefined) && args.taskFile) {
+    const { readTaskFile } = await import("../utils/task-file.js");
+    const loaded = await readTaskFile(args.taskFile, { projectDir });
+    if (runInput) runInput.task = loaded;
+    if (initContext) initContext.task = loaded;
+    args.task = loaded;
+  }
+  const runLog = createRunLog(projectDir);
+  const startMsg = logStartMsg || `[kj_${effectiveStage}] started`;
+  runLog.logText(startMsg);
+
+  const emitter = buildDirectEmitter(server, runLog, extra);
+  const eventBase = { sessionId: null, iteration: 0, startedAt: Date.now() };
+  const onOutput = ({ stream, line }) => {
+    emitter.emit("progress", {
+      type: "agent:output",
+      stage: effectiveStage,
+      message: line,
+      detail: { stream, agent: role.provider }
+    });
+  };
+  const stallDetector = createStallDetector({
+    onOutput, emitter, eventBase, stage: effectiveStage, provider: role.provider
+  });
+
+  const { RoleClass } = await importRole();
+  const roleInstance = new RoleClass({ config, logger, emitter });
+  await roleInstance.init(initContext);
+
+  sendTrackerLog(server, effectiveStage, "running", role.provider);
+  runLog.logText(`[${effectiveStage}] agent launched, waiting for response...`);
+
+  let result;
+  try {
+    result = await roleInstance.run({ ...runInput, onOutput: stallDetector.onOutput });
+  } finally {
+    stallDetector.stop();
+    const stats = stallDetector.stats();
+    runLog.logText(
+      `[${effectiveStage}] finished — lines=${stats.lineCount}, bytes=${stats.bytesReceived}, elapsed=${Math.round(stats.elapsedMs / 1000)}s`
+    );
+    runLog.close();
+  }
+
+  if (!result.ok) {
+    sendTrackerLog(server, effectiveStage, "failed");
+    throw new Error(result.result?.error || result.summary || `${effectiveStage} failed`);
+  }
+
+  sendTrackerLog(server, effectiveStage, "done");
+  return { ok: true, ...result.result, summary: result.summary };
+}

package/src/mcp/error-classifiers.js

@@ -0,0 +1,66 @@
+/**
+ * Error classification for MCP tool responses.
+ * Extracted to its own module to avoid circular import TDZ issues
+ * (server-handlers.js ↔ handlers/*.js circular chain).
+ */
+
+import { withDocLink } from "../utils/doc-links.js";
+
+const ERROR_CLASSIFIERS = [
+  {
+    test: (lower) => lower.includes("without output") || lower.includes("silent for") || lower.includes("unresponsive") || lower.includes("exceeded max silence"),
+    category: "agent_stall",
+    suggestion: "Agent output stalled. Check live details with kj_status, then retry with a smaller prompt or increase session.max_agent_silence_minutes if needed."
+  },
+  {
+    test: (lower) => lower.includes("sonar") && (lower.includes("connect") || lower.includes("econnrefused") || lower.includes("not available") || lower.includes("not running")),
+    category: "sonar_unavailable",
+    suggestion: withDocLink("SonarQube is not reachable. Try: kj_init to set up SonarQube, or run 'docker start sonarqube' if already installed. Use --no-sonar to skip SonarQube.", "sonar_docker")
+  },
+  {
+    test: (lower) => lower.includes("401") || lower.includes("unauthorized") || lower.includes("invalid token"),
+    category: "auth_error",
+    suggestion: withDocLink("Authentication failed. Regenerate the SonarQube token and update it via kj_init or in ~/.karajan/kj.config.yml under sonarqube.token.", "sonar_token")
+  },
+  {
+    test: (lower) => lower.includes("config") && (lower.includes("missing") || lower.includes("not found") || lower.includes("invalid")),
+    category: "config_error",
+    suggestion: withDocLink("Configuration issue detected. Run kj_doctor to diagnose, or kj_init to create a fresh config.", "config_missing")
+  },
+  {
+    test: (lower) => lower.includes("missing provider") || lower.includes("not found") && (lower.includes("claude") || lower.includes("codex") || lower.includes("gemini") || lower.includes("aider")),
+    category: "agent_missing",
+    suggestion: withDocLink("Required agent CLI not found. Run kj_doctor to check which agents are installed and get installation instructions.", "agent_not_found")
+  },
+  {
+    test: (lower) => lower.includes("timed out") || lower.includes("timeout"),
+    category: "timeout",
+    suggestion: "The agent did not complete in time. Try: (1) increase --max-iteration-minutes (default: 5), (2) split the task into smaller pieces, (3) use kj_code for single-agent tasks. If a SonarQube scan timed out, check Docker health."
+  },
+  {
+    test: (lower) => lower.includes("you are on the base branch"),
+    category: "branch_error",
+    suggestion: withDocLink("Create a feature branch before running Karajan. Use 'git checkout -b feat/<task-description>' and then retry. Do NOT run kj_code directly on the base branch.", "branch_error")
+  },
+  {
+    test: (lower) => lower.includes("not a git repository"),
+    category: "git_error",
+    suggestion: "Current directory is not a git repository. Navigate to your project root or initialize git with 'git init'."
+  },
+  {
+    test: (lower) => lower.includes("bootstrap failed"),
+    category: "bootstrap_error",
+    suggestion: withDocLink("Environment prerequisites not met. Run kj_doctor for diagnostics, then fix the issues listed. Do NOT work around these — fix them properly.", "bootstrap_failed")
+  }
+];
+
+export function classifyError(error) {
+  const msg = error?.message || String(error);
+  const lower = msg.toLowerCase();
+
+  const match = ERROR_CLASSIFIERS.find(c => c.test(lower));
+  if (match) {
+    return { category: match.category, suggestion: match.suggestion };
+  }
+  return { category: "unknown", suggestion: null };
+}