karajan-code 1.43.0 → 1.45.0

package/package.json

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

package/src/commands/init.js

@@ -9,6 +9,7 @@ import { detectAvailableAgents } from "../utils/agent-detect.js";
 import { createWizard, isTTY } from "../utils/wizard.js";
 import { runCommand } from "../utils/process.js";
 import { getInstallCommand } from "../utils/os-detect.js";
+import { detectOsLocale, SUPPORTED_LANGUAGES } from "../utils/locale.js";
 
 async function runWizard(config, logger) {
   const agents = await detectAvailableAgents();
@@ -88,6 +89,31 @@ async function runWizard(config, logger) {
     config.development.require_test_changes = methodology === "tdd";
     logger.info(`  -> Methodology: ${methodology}`);
 
+    const detectedLocale = detectOsLocale();
+    const allLangEntries = Object.entries(SUPPORTED_LANGUAGES).map(([code, name]) => ({
+      label: `${name} (${code})`,
+      value: code,
+      available: true
+    }));
+    // Put detected locale first so it becomes the default selection
+    const languageOptions = [
+      ...allLangEntries.filter((o) => o.value === detectedLocale),
+      ...allLangEntries.filter((o) => o.value !== detectedLocale)
+    ];
+
+    const pipelineLang = await wizard.select("Pipeline language:", languageOptions);
+    config.language = pipelineLang;
+    logger.info(`  -> Pipeline language: ${pipelineLang}`);
+
+    // Reorder for HU language with pipeline language as default
+    const huLangOptions = [
+      ...allLangEntries.filter((o) => o.value === pipelineLang),
+      ...allLangEntries.filter((o) => o.value !== pipelineLang)
+    ];
+    const huLang = await wizard.select("HU language (for user stories):", huLangOptions);
+    config.hu_language = huLang;
+    logger.info(`  -> HU language: ${huLang}`);
+
     logger.info("");
   } finally {
     wizard.close();
@@ -290,6 +316,13 @@ export async function initCommand({ logger, flags = {} }) {
   const { config, exists: configExists } = await loadConfig();
   const interactive = flags.noInteractive !== true && isTTY();
 
+  // Auto-detect language from OS locale for non-interactive mode
+  if (!interactive && !configExists) {
+    const detectedLocale = detectOsLocale();
+    config.language = detectedLocale;
+    config.hu_language = detectedLocale;
+  }
+
   await handleConfigSetup({ config, configExists, interactive, configPath, logger });
   await ensureReviewRules(reviewRulesPath, logger);
   await ensureCoderRules(coderRulesPath, logger);

package/src/config.js

@@ -123,6 +123,8 @@ const DEFAULTS = {
     port: 4000,
     auto_start: false
   },
+  language: "en",
+  hu_language: "en",
   policies: {},
   serena: { enabled: false },
   planning_game: { enabled: false, project_id: null, codeveloper: null },
@@ -164,6 +166,11 @@ const DEFAULTS = {
     backoff_multiplier: 2,
     jitter_factor: 0.1
   },
+  webperf: {
+    enabled: true,
+    devtools_mcp: false,
+    thresholds: { lcp: 2500, cls: 0.1, inp: 200 }
+  },
   guards: {
     output: {
       enabled: true,

package/src/prompts/architect.js

@@ -1,4 +1,5 @@
 import { loadAvailableSkills, buildSkillSection } from "../skills/skill-loader.js";
+import { getLanguageInstruction } from "../utils/locale.js";
 
 const SUBAGENT_PREAMBLE = [
   "IMPORTANT: You are running as a Karajan sub-agent.",
@@ -8,8 +9,9 @@ const SUBAGENT_PREAMBLE = [
 
 export const VALID_VERDICTS = new Set(["ready", "needs_clarification"]);
 
-export async function buildArchitectPrompt({ task, instructions, researchContext = null, productContext = null, projectDir = null }) {
-  const sections = [SUBAGENT_PREAMBLE];
+export async function buildArchitectPrompt({ task, instructions, researchContext = null, productContext = null, projectDir = null, language = "en" }) {
+  const langInstruction = getLanguageInstruction(language);
+  const sections = [SUBAGENT_PREAMBLE, ...(langInstruction ? [langInstruction] : [])];
 
   if (instructions) {
     sections.push(instructions);

package/src/prompts/coder.js

@@ -1,5 +1,6 @@
 import { RTK_INSTRUCTIONS } from "./rtk-snippet.js";
 import { loadAvailableSkills, buildSkillSection } from "../skills/skill-loader.js";
+import { getLanguageInstruction } from "../utils/locale.js";
 
 const SUBAGENT_PREAMBLE = [
   "IMPORTANT: You are running as a Karajan sub-agent.",
@@ -32,9 +33,11 @@ const SERENA_INSTRUCTIONS = [
   "Fall back to reading files only when Serena tools are not sufficient."
 ].join("\n");
 
-export async function buildCoderPrompt({ task, reviewerFeedback = null, sonarSummary = null, coderRules = null, methodology = "tdd", serenaEnabled = false, rtkAvailable = false, deferredContext = null, productContext = null, plan = null, projectDir = null }) {
+export async function buildCoderPrompt({ task, reviewerFeedback = null, sonarSummary = null, coderRules = null, methodology = "tdd", serenaEnabled = false, rtkAvailable = false, deferredContext = null, productContext = null, plan = null, projectDir = null, language = "en" }) {
+  const langInstruction = getLanguageInstruction(language);
   const sections = [
     serenaEnabled ? SUBAGENT_PREAMBLE_SERENA : SUBAGENT_PREAMBLE,
+    ...(langInstruction ? [langInstruction] : []),
     `Task:\n${task}`,
     "Implement directly in the repository.",
     "Keep changes minimal and production-ready.",

package/src/prompts/hu-reviewer.js

@@ -1,4 +1,5 @@
 import { extractFirstJson } from "../utils/json-extract.js";
+import { getLanguageInstruction } from "../utils/locale.js";
 
 const SUBAGENT_PREAMBLE = [
   "IMPORTANT: You are running as a Karajan sub-agent.",
@@ -21,8 +22,9 @@ const DIMENSION_KEYS = [
  * @param {{stories: Array<{id: string, text: string}>, instructions: string|null, context?: string|null}} params
  * @returns {string} The assembled prompt.
  */
-export function buildHuReviewerPrompt({ stories, instructions, context = null, productContext = null }) {
-  const sections = [SUBAGENT_PREAMBLE];
+export function buildHuReviewerPrompt({ stories, instructions, context = null, productContext = null, hu_language = "en" }) {
+  const langInstruction = getLanguageInstruction(hu_language);
+  const sections = [SUBAGENT_PREAMBLE, ...(langInstruction ? [langInstruction] : [])];
 
   if (instructions) {
     sections.push(instructions);

package/src/prompts/reviewer.js

@@ -1,5 +1,6 @@
 import { RTK_INSTRUCTIONS } from "./rtk-snippet.js";
 import { loadAvailableSkills, buildSkillSection } from "../skills/skill-loader.js";
+import { getLanguageInstruction } from "../utils/locale.js";
 
 const SUBAGENT_PREAMBLE = [
   "IMPORTANT: You are running as a Karajan sub-agent.",
@@ -23,11 +24,13 @@ const SERENA_INSTRUCTIONS = [
   "Fall back to reading files only when Serena tools are not sufficient."
 ].join("\n");
 
-export async function buildReviewerPrompt({ task, diff, reviewRules, mode, serenaEnabled = false, rtkAvailable = false, productContext = null, projectDir = null }) {
+export async function buildReviewerPrompt({ task, diff, reviewRules, mode, serenaEnabled = false, rtkAvailable = false, productContext = null, projectDir = null, language = "en" }) {
   const truncatedDiff = diff.length > 12000 ? `${diff.slice(0, 12000)}\n\n[TRUNCATED]` : diff;
 
+  const langInstruction = getLanguageInstruction(language);
   const sections = [
     serenaEnabled ? SUBAGENT_PREAMBLE_SERENA : SUBAGENT_PREAMBLE,
+    ...(langInstruction ? [langInstruction] : []),
     `You are a code reviewer in ${mode} mode.`,
     "CRITICAL SCOPE RULE: Only review changes that are part of the diff below. Do NOT flag issues in unchanged code, missing features planned for future tasks, or improvements outside the scope of this task. If the diff is correct for what the task asks, approve it — even if the broader codebase has other issues.",
     "Only block approval for issues IN THE DIFF that are bugs, security vulnerabilities, or clear violations of the review rules.",

package/src/roles/impeccable-role.js

@@ -1,5 +1,6 @@
 import { BaseRole } from "./base-role.js";
 import { createAgent as defaultCreateAgent } from "../agents/index.js";
+import { isDevToolsMcpAvailable, ensureWebPerfSkills } from "../webperf/devtools-detect.js";
 
 const SUBAGENT_PREAMBLE = [
   "IMPORTANT: You are running as a Karajan sub-agent.",
@@ -64,14 +65,32 @@ export class ImpeccableRole extends BaseRole {
   }
 
   async execute(input) {
-    const { task, diff } = typeof input === "string"
-      ? { task: input, diff: null }
-      : { task: input?.task || this.context?.task || "", diff: input?.diff || null };
+    const { task, diff, projectDir } = typeof input === "string"
+      ? { task: input, diff: null, projectDir: null }
+      : { task: input?.task || this.context?.task || "", diff: input?.diff || null, projectDir: input?.projectDir || null };
+
+    // Auto-install WebPerf skills when DevTools MCP is configured
+    if (isDevToolsMcpAvailable(this.config)) {
+      const dir = projectDir || process.cwd();
+      try {
+        const webperfResult = await ensureWebPerfSkills(dir, this.logger);
+        if (webperfResult.installed.length > 0) {
+          this.logger?.info?.(`WebPerf skills installed: ${webperfResult.installed.join(", ")}`);
+        }
+      } catch (err) {
+        this.logger?.warn?.(`WebPerf skill installation failed: ${err.message}`);
+      }
+    } else {
+      this.logger?.info?.("Chrome DevTools MCP not configured — skipping WebPerf skills");
+    }
 
     const provider = resolveProvider(this.config);
     const agent = this._createAgent(provider, this.config, this.logger);
 
-    const prompt = buildPrompt({ task, diff, instructions: this.instructions });
+    const webperfNote = isDevToolsMcpAvailable(this.config)
+      ? "\n\nNote: WebPerf domain skills are available. Use them for Core Web Vitals analysis if the audit involves frontend performance."
+      : "";
+    const prompt = buildPrompt({ task, diff, instructions: this.instructions }) + webperfNote;
     const result = await agent.runTask({ prompt, role: "impeccable" });
 
     if (!result.ok) {

package/src/utils/display.js

@@ -2,6 +2,7 @@ import path from "node:path";
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 
+// TODO: i18n display messages
 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;
 

package/src/utils/locale.js

@@ -0,0 +1,59 @@
+/**
+ * OS locale detection and language instruction generation for i18n support.
+ */
+
+export const SUPPORTED_LANGUAGES = {
+  en: "English",
+  es: "Español"
+};
+
+const LANG_ENV_VARS = ["LANG", "LANGUAGE", "LC_ALL", "LC_MESSAGES"];
+
+/**
+ * Detect the 2-letter language code from OS environment variables.
+ * Checks LANG, LANGUAGE, LC_ALL, LC_MESSAGES in order.
+ * @returns {string} 2-letter language code (e.g. "en", "es")
+ */
+export function detectOsLocale() {
+  for (const envVar of LANG_ENV_VARS) {
+    const value = process.env[envVar];
+    if (value) {
+      const code = extractLangCode(value);
+      if (code) return code;
+    }
+  }
+  return "en";
+}
+
+/**
+ * Extract a 2-letter language code from a locale string.
+ * Handles formats like "es_ES.UTF-8", "en_US", "es", "C.UTF-8".
+ * @param {string} locale
+ * @returns {string|null}
+ */
+function extractLangCode(locale) {
+  const trimmed = locale.trim();
+  if (!trimmed || trimmed === "C" || trimmed === "POSIX") return null;
+  // Match first 2 lowercase letters before _, ., or end
+  const match = /^([a-z]{2})(?:[_.\-]|$)/i.exec(trimmed);
+  if (match) return match[1].toLowerCase();
+  return null;
+}
+
+/**
+ * Get a prompt instruction string for the given language.
+ * Returns empty string for English (agents default to English).
+ * @param {string} lang - 2-letter language code
+ * @returns {string}
+ */
+export function getLanguageInstruction(lang) {
+  if (!lang || lang === "en") return "";
+  const languageName = SUPPORTED_LANGUAGES[lang];
+  if (lang === "es") {
+    return "IMPORTANT: Respond in Spanish. All output, explanations, and feedback must be in Spanish.";
+  }
+  if (languageName) {
+    return `IMPORTANT: Respond in ${languageName}. All output must be in ${languageName}.`;
+  }
+  return `IMPORTANT: Respond in ${lang}. All output must be in ${lang}.`;
+}

package/src/webperf/cwv-gate.js

@@ -0,0 +1,94 @@
+/**
+ * Core Web Vitals quality gate.
+ *
+ * Evaluates LCP, CLS and INP against Google's recommended thresholds
+ * and returns a structured verdict usable by the pipeline.
+ */
+
+export const CWV_THRESHOLDS = {
+  lcp: { good: 2500, poor: 4000 },
+  cls: { good: 0.1, poor: 0.25 },
+  inp: { good: 200, poor: 500 }
+};
+
+/**
+ * Deep-merge custom thresholds on top of the defaults.
+ * Only overrides metrics/boundaries that the caller provides.
+ *
+ * @param {object} defaults - Base thresholds (e.g. CWV_THRESHOLDS)
+ * @param {object} [custom]  - Partial overrides
+ * @returns {object} Merged thresholds
+ */
+export function mergeThresholds(defaults, custom) {
+  if (!custom || typeof custom !== "object") return { ...defaults };
+
+  const merged = {};
+  for (const metric of Object.keys(defaults)) {
+    const base = defaults[metric];
+    const over = custom[metric];
+    if (over && typeof over === "object") {
+      merged[metric] = {
+        good: over.good !== undefined ? over.good : base.good,
+        poor: over.poor !== undefined ? over.poor : base.poor
+      };
+    } else {
+      merged[metric] = { ...base };
+    }
+  }
+
+  // Include any extra metrics the caller added that are not in defaults
+  for (const metric of Object.keys(custom)) {
+    if (!merged[metric] && typeof custom[metric] === "object") {
+      merged[metric] = { ...custom[metric] };
+    }
+  }
+
+  return merged;
+}
+
+function rateMetric(value, good, poor) {
+  if (value <= good) return "good";
+  if (value >= poor) return "poor";
+  return "needs-improvement";
+}
+
+/**
+ * Evaluate Core Web Vitals metrics against thresholds.
+ *
+ * @param {{ lcp?: number, cls?: number, inp?: number }} metrics
+ * @param {object} [customThresholds] - Optional per-metric overrides
+ * @returns {{
+ *   pass: boolean,
+ *   scores: Record<string, { value: number, rating: string }>,
+ *   blocking: Array<{ metric: string, value: number, threshold: number, rating: string }>,
+ *   advisory: Array<{ metric: string, value: number, threshold: number, rating: string }>
+ * }}
+ */
+export function evaluateCwv(metrics, customThresholds) {
+  const thresholds = mergeThresholds(CWV_THRESHOLDS, customThresholds);
+
+  const scores = {};
+  const blocking = [];
+  const advisory = [];
+
+  for (const [metric, bounds] of Object.entries(thresholds)) {
+    const value = metrics[metric];
+    if (value === undefined || value === null) continue;
+
+    const rating = rateMetric(value, bounds.good, bounds.poor);
+    scores[metric] = { value, rating };
+
+    if (rating === "poor") {
+      blocking.push({ metric, value, threshold: bounds.poor, rating });
+    } else if (rating === "needs-improvement") {
+      advisory.push({ metric, value, threshold: bounds.good, rating });
+    }
+  }
+
+  return {
+    pass: blocking.length === 0,
+    scores,
+    blocking,
+    advisory
+  };
+}

package/src/webperf/devtools-detect.js

@@ -0,0 +1,65 @@
+/**
+ * Chrome DevTools MCP detection and WebPerf skill auto-installation.
+ */
+
+import { isOpenSkillsAvailable, installSkill, listSkills } from "../skills/openskills-client.js";
+
+/** Skill names to auto-install when WebPerf is enabled. */
+export const WEBPERF_SKILLS = [
+  "webperf",
+  "webperf-core-web-vitals",
+  "webperf-loading"
+];
+
+/**
+ * Check whether Chrome DevTools MCP is configured and available.
+ * Since Karajan runs as an MCP server itself, it cannot directly call other MCPs.
+ * Instead, we check the config flag `webperf.devtools_mcp`.
+ * @param {object} config — merged Karajan config
+ * @returns {boolean}
+ */
+export function isDevToolsMcpAvailable(config) {
+  return Boolean(config?.webperf?.devtools_mcp);
+}
+
+/**
+ * Ensure WebPerf skills are installed via OpenSkills.
+ * Installs any missing skills from WEBPERF_SKILLS.
+ * @param {string} projectDir — absolute path to the project root
+ * @param {object} [logger] — optional logger ({ info, warn })
+ * @returns {Promise<{ installed: string[], alreadyInstalled: string[], skipped: string[] }>}
+ */
+export async function ensureWebPerfSkills(projectDir, logger) {
+  const result = { installed: [], alreadyInstalled: [], skipped: [] };
+
+  const available = await isOpenSkillsAvailable();
+  if (!available) {
+    logger?.warn?.("OpenSkills CLI not available — skipping WebPerf skill installation");
+    result.skipped = [...WEBPERF_SKILLS];
+    return result;
+  }
+
+  // Get currently installed skills
+  const listResult = await listSkills({ projectDir });
+  const installedNames = new Set(
+    (listResult.ok ? listResult.skills : []).map(s => s.name)
+  );
+
+  for (const skill of WEBPERF_SKILLS) {
+    if (installedNames.has(skill)) {
+      result.alreadyInstalled.push(skill);
+      continue;
+    }
+
+    const installResult = await installSkill(skill, { projectDir });
+    if (installResult.ok) {
+      result.installed.push(skill);
+      logger?.info?.(`Installed WebPerf skill: ${skill}`);
+    } else {
+      result.skipped.push(skill);
+      logger?.warn?.(`Failed to install WebPerf skill "${skill}": ${installResult.error}`);
+    }
+  }
+
+  return result;
+}

package/src/webperf/webperf-role-integration.js

@@ -0,0 +1,66 @@
+/**
+ * Integration helpers that format CWV gate results for the
+ * impeccable prompt and for pipeline progress events.
+ */
+
+const RATING_ICONS = { good: "PASS", "needs-improvement": "WARN", poor: "FAIL" };
+
+/**
+ * Build a human-readable section for the impeccable prompt.
+ *
+ * @param {{ pass: boolean, scores: object, blocking: Array, advisory: Array }} cwvResult
+ * @returns {string}
+ */
+export function buildWebPerfSection(cwvResult) {
+  const lines = [];
+  const verdict = cwvResult.pass ? "PASSED" : "FAILED";
+  lines.push(`## WebPerf — Core Web Vitals (${verdict})`);
+  lines.push("");
+
+  for (const [metric, { value, rating }] of Object.entries(cwvResult.scores)) {
+    const icon = RATING_ICONS[rating] || rating;
+    const unit = metric === "cls" ? "" : "ms";
+    lines.push(`- **${metric.toUpperCase()}**: ${value}${unit} [${icon}]`);
+  }
+
+  if (cwvResult.blocking.length > 0) {
+    lines.push("");
+    lines.push("### Blocking issues");
+    for (const b of cwvResult.blocking) {
+      const unit = b.metric === "cls" ? "" : "ms";
+      lines.push(`- ${b.metric.toUpperCase()}: ${b.value}${unit} exceeds poor threshold (${b.threshold}${unit})`);
+    }
+  }
+
+  if (cwvResult.advisory.length > 0) {
+    lines.push("");
+    lines.push("### Advisory (needs improvement)");
+    for (const a of cwvResult.advisory) {
+      const unit = a.metric === "cls" ? "" : "ms";
+      lines.push(`- ${a.metric.toUpperCase()}: ${a.value}${unit} exceeds good threshold (${a.threshold}${unit})`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Format CWV result for a pipeline progress event payload.
+ *
+ * @param {{ pass: boolean, scores: object, blocking: Array, advisory: Array }} cwvResult
+ * @returns {{ type: string, pass: boolean, metrics: object, blockingCount: number, advisoryCount: number }}
+ */
+export function formatCwvForEvent(cwvResult) {
+  const metrics = {};
+  for (const [metric, { value, rating }] of Object.entries(cwvResult.scores)) {
+    metrics[metric] = { value, rating };
+  }
+
+  return {
+    type: "webperf-cwv",
+    pass: cwvResult.pass,
+    metrics,
+    blockingCount: cwvResult.blocking.length,
+    advisoryCount: cwvResult.advisory.length
+  };
+}