karajan-code 2.7.4 → 2.9.0

package/src/audit/osv-findings.js

@@ -0,0 +1,162 @@
+/**
+ * OSV-Scanner findings collector for `kj audit` (KJC-TSK-0365).
+ *
+ * Wraps Google's `osv-scanner` CLI and feeds its results into the audit
+ * prompt as a deterministic vulnerability section. OSV.dev's database
+ * pulls from GitHub Advisory Database, GLSA, PyPI advisories, Go vuln
+ * DB and others — broader coverage than `npm audit` alone, with no
+ * account, token, or upload (the scanner runs locally and only the
+ * advisory data is fetched on demand).
+ *
+ * This module follows the same pattern as src/audit/sonar-findings.js:
+ *   - Best-effort: missing binary or scan errors return
+ *     {available: false, reason} and the audit continues without the
+ *     section.
+ *   - Severity-grouped: helps the LLM (and the deterministic summary)
+ *     prioritise the worst issues without scrolling.
+ *   - Capped: only the first MAX_OSV_VULNS_IN_PROMPT entries land in
+ *     the prompt, with overflow markers per severity, so an
+ *     out-of-control result list cannot blow the token budget.
+ */
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+const SCAN_TIMEOUT_MS = 60_000;
+const SEVERITY_ORDER = ["CRITICAL", "HIGH", "MEDIUM", "LOW", "MODERATE"];
+
+/**
+ * Run osv-scanner on the project and return a structured result.
+ *
+ * @param {string} projectDir - absolute path to the project root
+ * @param {object} [logger]
+ * @returns {Promise<{available: boolean, reason?: string, total?: number, vulnerabilities?: object[]}>}
+ */
+export async function collectOsvFindings(projectDir, logger = null) {
+  let stdout;
+  try {
+    const { stdout: out } = await execFileAsync(
+      "osv-scanner",
+      ["--format=json", "--recursive", projectDir || "."],
+      { cwd: projectDir, timeout: SCAN_TIMEOUT_MS, maxBuffer: 16 * 1024 * 1024 }
+    );
+    stdout = out;
+  } catch (err) {
+    // osv-scanner exits with non-zero when vulnerabilities are found, so
+    // err.code 1 is NORMAL — we still want the stdout. Real failures are
+    // ENOENT (binary missing) or stdout empty.
+    if (err.code === "ENOENT") {
+      if (logger?.warn) logger.warn("osv-scanner not found in PATH — install via 'go install github.com/google/osv-scanner@latest'");
+      return { available: false, reason: "osv-scanner not installed" };
+    }
+    if (err.killed) {
+      if (logger?.warn) logger.warn(`osv-scanner timed out after ${SCAN_TIMEOUT_MS}ms`);
+      return { available: false, reason: `osv-scanner timed out after ${SCAN_TIMEOUT_MS}ms` };
+    }
+    if (typeof err.stdout === "string" && err.stdout.trim().length > 0) {
+      stdout = err.stdout;
+    } else {
+      if (logger?.warn) logger.warn(`osv-scanner failed: ${err.message}`);
+      return { available: false, reason: `osv-scanner failed: ${err.message}` };
+    }
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch (err) {
+    if (logger?.warn) logger.warn(`osv-scanner output not parseable: ${err.message}`);
+    return { available: false, reason: "osv-scanner output not parseable as JSON" };
+  }
+
+  return { available: true, ...parseOsvOutput(parsed) };
+}
+
+/**
+ * Flatten the osv-scanner JSON shape into a flat list of vulnerabilities.
+ * The scanner emits results[].packages[].vulnerabilities[].
+ *
+ * @param {object} raw - parsed osv-scanner JSON
+ * @returns {{total: number, vulnerabilities: object[]}}
+ */
+export function parseOsvOutput(raw) {
+  const flat = [];
+  const results = Array.isArray(raw?.results) ? raw.results : [];
+  for (const result of results) {
+    const source = result.source?.path || result.source || "";
+    const packages = Array.isArray(result.packages) ? result.packages : [];
+    for (const pkg of packages) {
+      const name = pkg.package?.name || "";
+      const version = pkg.package?.version || "";
+      const ecosystem = pkg.package?.ecosystem || "";
+      const vulns = Array.isArray(pkg.vulnerabilities) ? pkg.vulnerabilities : [];
+      const groups = Array.isArray(pkg.groups) ? pkg.groups : [];
+      for (const vuln of vulns) {
+        flat.push({
+          id: vuln.id || vuln.aliases?.[0] || "UNKNOWN",
+          aliases: vuln.aliases || [],
+          severity: extractSeverity(vuln, groups),
+          summary: vuln.summary || vuln.details?.split("\n")[0] || "",
+          package: name,
+          version,
+          ecosystem,
+          source,
+          fixed: extractFixedVersion(vuln),
+        });
+      }
+    }
+  }
+  return { total: flat.length, vulnerabilities: flat };
+}
+
+/**
+ * Resolve a vulnerability's effective severity. osv-scanner reports
+ * CVSS (per-vuln) and a separate `groups[].severity` (per scanner run).
+ * Group severity wins when present because it reflects scanner policy.
+ */
+function extractSeverity(vuln, groups) {
+  // Group-level severity (scanner-resolved, includes ecosystem context)
+  for (const group of groups) {
+    if (group.ids?.includes(vuln.id) && group.severity) {
+      return String(group.severity).toUpperCase();
+    }
+  }
+  // Per-vuln CVSS — pick the highest score
+  const severities = Array.isArray(vuln.severity) ? vuln.severity : [];
+  for (const sev of severities) {
+    if (sev?.severity) return String(sev.severity).toUpperCase();
+  }
+  // database_specific severity (GHSA-style)
+  if (vuln.database_specific?.severity) {
+    return String(vuln.database_specific.severity).toUpperCase();
+  }
+  return "UNKNOWN";
+}
+
+function extractFixedVersion(vuln) {
+  const ranges = vuln.affected?.[0]?.ranges || [];
+  for (const range of ranges) {
+    const events = range.events || [];
+    for (const event of events) {
+      if (event.fixed) return event.fixed;
+    }
+  }
+  return null;
+}
+
+/**
+ * Group vulnerabilities by severity, preserving canonical ordering
+ * (CRITICAL → HIGH → MEDIUM/MODERATE → LOW → UNKNOWN).
+ */
+export function groupVulnerabilitiesBySeverity(vulnerabilities) {
+  const groups = Object.fromEntries(SEVERITY_ORDER.map(s => [s, []]));
+  groups.UNKNOWN = [];
+  for (const vuln of vulnerabilities || []) {
+    const sev = (vuln.severity || "UNKNOWN").toUpperCase();
+    if (groups[sev]) groups[sev].push(vuln);
+    else groups.UNKNOWN.push(vuln);
+  }
+  return groups;
+}

package/src/audit/semgrep-findings.js

@@ -0,0 +1,117 @@
+/**
+ * Semgrep SAST collector for `kj audit` (KJC-TSK-0366).
+ *
+ * Wraps `semgrep --config auto --json` and feeds structured static-
+ * analysis findings into the audit prompt. Equivalent to the SAST half
+ * of `snyk code` but free for OSS, no account, runs locally. Semgrep
+ * has 2000+ built-in rules across JS/TS/Python/Go/etc. covering OWASP
+ * Top 10, taint analysis, hardcoded secrets, regex misuse and language-
+ * specific anti-patterns.
+ *
+ * Same best-effort pattern as sonar-findings.js and osv-findings.js:
+ *   - Missing binary or timeout returns {available: false, reason}.
+ *   - 120s timeout (semgrep can be slow on large repos with --config auto).
+ *   - Severity-grouped (ERROR / WARNING / INFO) and capped at
+ *     MAX_SEMGREP_FINDINGS_IN_PROMPT (50) total entries with overflow
+ *     markers.
+ *   - The LLM is told these are deterministic and asked to fold them
+ *     into the `security` dimension using the rule ID as the rule field.
+ */
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+const SCAN_TIMEOUT_MS = 120_000;
+const SEVERITY_ORDER = ["ERROR", "WARNING", "INFO"];
+
+/**
+ * Run semgrep on the project and return a structured result.
+ *
+ * @param {string} projectDir - absolute path to the project root
+ * @param {object} [logger]
+ * @returns {Promise<{available: boolean, reason?: string, total?: number, findings?: object[]}>}
+ */
+export async function collectSemgrepFindings(projectDir, logger = null) {
+  let stdout;
+  try {
+    const { stdout: out } = await execFileAsync(
+      "semgrep",
+      ["--config", "auto", "--json", "--quiet", `--timeout=${Math.floor(SCAN_TIMEOUT_MS / 1000)}`, projectDir || "."],
+      { cwd: projectDir, timeout: SCAN_TIMEOUT_MS + 5000, maxBuffer: 32 * 1024 * 1024 }
+    );
+    stdout = out;
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      if (logger?.warn) logger.warn("semgrep not found in PATH — install via 'pipx install semgrep' or 'brew install semgrep'");
+      return { available: false, reason: "semgrep not installed" };
+    }
+    if (err.killed) {
+      if (logger?.warn) logger.warn(`semgrep timed out after ${SCAN_TIMEOUT_MS}ms`);
+      return { available: false, reason: `semgrep timed out after ${SCAN_TIMEOUT_MS}ms` };
+    }
+    // semgrep exits 1 when it finds blocking rules (ERROR severity), but
+    // still emits a valid JSON report on stdout. Rescue that case.
+    if (typeof err.stdout === "string" && err.stdout.trim().length > 0) {
+      stdout = err.stdout;
+    } else {
+      if (logger?.warn) logger.warn(`semgrep failed: ${err.message}`);
+      return { available: false, reason: `semgrep failed: ${err.message}` };
+    }
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch (err) {
+    if (logger?.warn) logger.warn(`semgrep output not parseable: ${err.message}`);
+    return { available: false, reason: "semgrep output not parseable as JSON" };
+  }
+
+  return { available: true, ...parseSemgrepOutput(parsed, projectDir) };
+}
+
+/**
+ * Convert semgrep's JSON shape into the flat findings list the prompt
+ * builder consumes. Semgrep emits results[] with rule id, severity,
+ * path, start/end line, message, fix hints.
+ *
+ * @param {object} raw - parsed semgrep --json output
+ * @param {string} [projectDir] - used to make paths repo-relative
+ * @returns {{total: number, findings: object[]}}
+ */
+export function parseSemgrepOutput(raw, projectDir = "") {
+  const results = Array.isArray(raw?.results) ? raw.results : [];
+  const findings = [];
+  for (const r of results) {
+    const file = r.path && projectDir
+      ? r.path.startsWith(projectDir + "/") ? r.path.slice(projectDir.length + 1) : r.path
+      : r.path || "";
+    findings.push({
+      rule: r.check_id || "(unknown)",
+      severity: String(r.extra?.severity || "INFO").toUpperCase(),
+      file,
+      line: r.start?.line ?? 0,
+      endLine: r.end?.line ?? 0,
+      message: r.extra?.message || "",
+      fix: r.extra?.fix || r.extra?.fix_regex || null,
+      cwe: r.extra?.metadata?.cwe || null,
+      owasp: r.extra?.metadata?.owasp || null,
+    });
+  }
+  return { total: findings.length, findings };
+}
+
+/**
+ * Group findings by severity in canonical order (ERROR → WARNING → INFO).
+ */
+export function groupFindingsBySeverity(findings) {
+  const groups = Object.fromEntries(SEVERITY_ORDER.map(s => [s, []]));
+  for (const f of findings || []) {
+    const sev = (f.severity || "INFO").toUpperCase();
+    if (groups[sev]) groups[sev].push(f);
+    else groups.INFO.push(f);
+  }
+  return groups;
+}

package/src/audit/sonar-findings.js

@@ -0,0 +1,81 @@
+/**
+ * Sonar findings collector for `kj audit` (KJC-TSK-0361).
+ *
+ * The audit pipeline already pays for SonarQube to exist (kj run + the
+ * SonarStage drive a full scan and gate the pipeline on its result). When
+ * the user runs `kj audit`, we don't want to pay for *another* full scan
+ * (~1-3 min) — we want to read whatever Sonar already knows. This module
+ * does exactly that: ping the configured Sonar host, and if it's
+ * reachable, fetch the current open-issue list + quality-gate status via
+ * the existing sonar/api.js helpers. Both results are best-effort: a
+ * sonar-down host or a never-scanned project quietly returns
+ * `{available: false, reason: "..."}` and the audit continues without
+ * the section.
+ *
+ * Why this matters: the LLM auditor was previously asked to find issues
+ * by reading source code, but Sonar already produces them with rule IDs
+ * (squid:S1234), severity, and line precision. Feeding those in lets the
+ * LLM cross-reference its own findings (high-confidence overlap) and
+ * focus its tokens on patterns Sonar can't see (architecture, naming,
+ * API design).
+ */
+
+import { isSonarReachable } from "../sonar/manager.js";
+import { getOpenIssues, getQualityGateStatus } from "../sonar/api.js";
+
+/**
+ * Collect deterministic Sonar findings for the audit prompt.
+ *
+ * @param {object} config - resolved Karajan config (must have config.sonarqube.host)
+ * @param {object} [logger] - optional logger for warn-level traces
+ * @returns {Promise<{available: boolean, reason?: string, issues?: object[], total?: number, qualityGate?: object}>}
+ */
+export async function collectSonarFindings(config, logger = null) {
+  const sonarConfig = config?.sonarqube || {};
+  const host = sonarConfig.host || "http://localhost:9000";
+  const healthcheckSeconds = sonarConfig.timeouts?.healthcheckSeconds ?? 5;
+
+  // Ping first — avoids surfacing a 30-second timeout into audit runtime
+  // when Docker is simply down or the user opted out of Sonar.
+  const reachable = await isSonarReachable(host, healthcheckSeconds).catch(() => false);
+  if (!reachable) {
+    if (logger?.warn) logger.warn(`sonar audit input skipped: host ${host} not reachable`);
+    return { available: false, reason: `sonar host ${host} not reachable` };
+  }
+
+  let issuesResult;
+  try {
+    issuesResult = await getOpenIssues(config);
+  } catch (err) {
+    if (logger?.warn) logger.warn(`sonar audit input: getOpenIssues failed: ${err?.message || err}`);
+    return { available: false, reason: `getOpenIssues failed: ${err?.message || err}` };
+  }
+
+  let qualityGate = null;
+  try {
+    const qg = await getQualityGateStatus(config);
+    if (qg?.ok) qualityGate = { status: qg.status, conditions: qg.conditions };
+  } catch { /* gate is optional context */ }
+
+  return {
+    available: true,
+    issues: issuesResult.issues || [],
+    total: issuesResult.total || 0,
+    qualityGate,
+  };
+}
+
+/**
+ * Group Sonar issues by severity, preserving Sonar's canonical ordering.
+ * Used by the prompt builder to render the findings section.
+ */
+export function groupIssuesBySeverity(issues) {
+  const order = ["BLOCKER", "CRITICAL", "MAJOR", "MINOR", "INFO"];
+  const groups = Object.fromEntries(order.map(s => [s, []]));
+  for (const issue of issues || []) {
+    const sev = issue.severity || "INFO";
+    if (groups[sev]) groups[sev].push(issue);
+    else groups.INFO.push(issue);
+  }
+  return groups;
+}

package/src/audit/webperf-input.js

@@ -0,0 +1,90 @@
+/**
+ * WebPerf input collector for `kj audit` (KJC-TSK-0360).
+ *
+ * Two modes:
+ *   - "static-hints": no live measurement available, but the project is
+ *     frontend so the LLM should look for frontend-perf patterns in the
+ *     source (bundle bloat, render-blocking, image opt, lazy loading).
+ *     This is the common path because `kj audit` runs against a code
+ *     tree, not a live preview server.
+ *   - "cwv-result": a Core Web Vitals measurement was supplied (either
+ *     via config.webperf.lastResult, or in the future via a `kj webperf`
+ *     command that drives Chrome DevTools MCP). evaluateCwv from
+ *     src/webperf/cwv-gate.js produces a structured verdict the prompt
+ *     renders verbatim.
+ *
+ * The "live measurement" path is intentionally NOT wired here: the
+ * audit's LLM sub-agent is forbidden from MCP tool use (SUBAGENT_PREAMBLE
+ * in src/prompts/audit.js), and spawning Chrome / launching a preview
+ * server during a read-only audit is out of scope. When a future
+ * `kj webperf` command exists, it can write the result into
+ * `config.webperf.lastResult` and this collector will surface it.
+ */
+
+import { evaluateCwv, CWV_THRESHOLDS } from "../webperf/cwv-gate.js";
+
+/**
+ * Decide what (if anything) to feed the audit prompt about web perf.
+ *
+ * @param {object|null} stack - detectProjectStack output (null when unknown)
+ * @param {object} [config] - resolved Karajan config (config.webperf may carry a stale CWV result)
+ * @returns {{available: boolean, mode?: 'static-hints'|'cwv-result', cwv?: object, reason?: string}}
+ */
+export function collectWebPerfInput(stack, config = {}) {
+  const webperfConfig = config?.webperf || {};
+  const lastResult = webperfConfig.lastResult || null;
+
+  if (lastResult && typeof lastResult === "object" && lastResult.metrics) {
+    const verdict = evaluateCwv(lastResult.metrics, lastResult.thresholds || webperfConfig.thresholds);
+    return {
+      available: true,
+      mode: "cwv-result",
+      url: lastResult.url || webperfConfig.url || null,
+      capturedAt: lastResult.capturedAt || null,
+      cwv: verdict,
+      thresholds: lastResult.thresholds || webperfConfig.thresholds || CWV_THRESHOLDS,
+    };
+  }
+
+  // No live measurement → static hints only when the project actually has
+  // a frontend layer to audit. Backend-only projects get nothing.
+  const isFrontendish = !stack || stack.isFrontend === true || stack.isFullstack === true;
+  if (!isFrontendish) {
+    return { available: false, reason: "project is backend-only — no frontend-perf hints to give" };
+  }
+
+  return { available: true, mode: "static-hints" };
+}
+
+/**
+ * Render a CWV verdict (from collectWebPerfInput's cwv-result mode) as
+ * concise prompt-friendly markdown. Kept independent from the prompt
+ * builder so it stays unit-testable in isolation.
+ */
+export function formatCwvVerdict(input) {
+  if (!input || input.mode !== "cwv-result" || !input.cwv) return null;
+  const { cwv, url, capturedAt } = input;
+  const lines = [];
+  if (url) lines.push(`- Target URL: ${url}`);
+  if (capturedAt) lines.push(`- Captured: ${capturedAt}`);
+  lines.push(`- Verdict: ${cwv.pass ? "PASS" : "FAIL"}`);
+  if (Object.keys(cwv.scores || {}).length) {
+    lines.push("- Scores:");
+    for (const [metric, score] of Object.entries(cwv.scores)) {
+      lines.push(`  - ${metric.toUpperCase()}: ${score.value} (${score.rating})`);
+    }
+  }
+  if (cwv.blocking?.length) {
+    lines.push("- Blocking metrics (above poor threshold):");
+    for (const b of cwv.blocking) {
+      lines.push(`  - ${b.metric.toUpperCase()} ${b.value} > ${b.threshold}`);
+    }
+  }
+  if (cwv.advisory?.length) {
+    lines.push("- Advisory metrics (between good and poor):");
+    for (const a of cwv.advisory) {
+      lines.push(`  - ${a.metric.toUpperCase()} ${a.value} > good=${a.threshold}`);
+    }
+  }
+  return lines.join("\n");
+}

package/src/bootstrap.js

@@ -36,7 +36,7 @@ function getPackageVersion() {
 // ── Individual checks ────────────────────────────────────────────────
 
 async function checkGitRepo() {
-  let ok = false;
+  let ok;
   try {
     ok = await ensureGitRepo();
   } catch { /* git may not be installed */
@@ -219,6 +219,31 @@ function formatBootstrapFailure(failures) {
  * Throws Error with actionable message if any prerequisite fails.
  */
 export async function ensureBootstrap(projectDir, config) {
+  // Plugin discovery runs unconditionally on every bootstrap, regardless
+  // of whether the bootstrap cache says environment is valid. A user
+  // dropping a new file into `.karajan/plugins/` expects it to be picked
+  // up without running `kj init` again.
+  //
+  // Pre-v2.7.5 this was never called — `loadPlugins()` was exported but
+  // never imported from production code, so any plugin the user added
+  // was silently ignored. Fixed in TSK-0329.
+  try {
+    const { loadPlugins } = await import("./plugins/loader.js");
+    await loadPlugins({ projectDir });
+  } catch { /* plugin system failed — non-blocking, continue bootstrap */ }
+
+  // TSK-0339: register the Planning Game adapter in the integrations registry
+  // when enabled. The orchestrator no longer imports `src/planning-game/*`
+  // directly — it calls `getIntegration("tracker")?.hookName(...)` instead.
+  // Other trackers (GitHub Projects, Jira, Linear, …) drop in by writing
+  // a sibling adapter that calls `registerIntegration("tracker", …)`.
+  if (config?.planning_game?.enabled) {
+    try {
+      const { registerPgAdapter } = await import("./planning-game/pipeline-adapter.js");
+      await registerPgAdapter();
+    } catch { /* PG registration failed — non-blocking, continue bootstrap */ }
+  }
+
   const cached = await readBootstrapFile(projectDir);
   if (isBootstrapValid(cached, projectDir)) {
     return; // Environment already validated

package/src/brain/decision-tracker.js

@@ -11,6 +11,8 @@
  * the session for human input.
  */
 
+import { setBrainDecisions } from "../session/mutators.js";
+
 export const DEFAULT_MAX_DECISIONS = 20;
 export const INDECISION_REPEAT_THRESHOLD = 3; // 3 identical classifications in a row
 
@@ -42,7 +44,7 @@ export const INDECISION_REPEAT_THRESHOLD = 3; // 3 identical classifications in
  */
 export function createTracker(session, { max = DEFAULT_MAX_DECISIONS } = {}) {
   if (!Array.isArray(session.brainDecisions)) {
-    session.brainDecisions = [];
+    setBrainDecisions(session, []);
   }
   return { session, max };
 }

package/src/brain/decisor.js

@@ -125,7 +125,7 @@ function applyOverrides(roles, overrides) {
  * @param {{ forceRoles?: string[], skipRoles?: string[] }} [args.overrides]
  * @returns {Decision}
  */
-export function buildDecision({ triage, task, config = {}, overrides = {} } = {}) {
+export function buildDecision({ triage, task: _task, config = {}, overrides = {} } = {}) {
   const level = triage?.level || "simple";
   const taskType = triage?.taskType || "sw";