karajan-code 1.44.0 → 1.45.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "1.44.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/config.js

@@ -166,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/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/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
+  };
+}