karajan-code 2.8.0 → 2.10.0

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,136 @@
+/**
+ * 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. Three
+ *     possible sources, in priority order:
+ *       1. `config.webperf.lastResult` — inline {metrics, thresholds, ...}
+ *          (rare; legacy / programmatic injection)
+ *       2. `config.webperf.lastResultPath` — file path written by
+ *          `kj webperf` (KJC-TSK-0149). This is the standard wiring.
+ *       3. `~/.karajan/webperf/<projectSlug>/last.json` — fallback
+ *          discovery when the user ran `kj webperf` but didn't patch
+ *          their kj.config.yml.
+ *     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 wrong layer. `kj webperf` does
+ * the measurement; `kj audit` consumes the persisted result.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { evaluateCwv, CWV_THRESHOLDS } from "../webperf/cwv-gate.js";
+
+// Resolve per call — `os.homedir()` reads $HOME each time, so test
+// suites that override $HOME for hermetic tmp dirs work without
+// special re-imports.
+function webperfHome() {
+  return path.join(os.homedir(), ".karajan", "webperf");
+}
+
+function projectSlug(projectDir) {
+  return path.basename(projectDir || process.cwd()).replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+
+/**
+ * Try the three discovery paths in priority order. Returns the parsed
+ * scan object (shape produced by src/webperf/scanner.js) or null.
+ */
+function loadPersistedScan(webperfConfig, projectDir) {
+  // 1. Inline result on the config (back-compat)
+  if (webperfConfig.lastResult && typeof webperfConfig.lastResult === "object" && webperfConfig.lastResult.metrics) {
+    return webperfConfig.lastResult;
+  }
+  // 2. Explicit file path on the config
+  const candidates = [];
+  if (webperfConfig.lastResultPath) candidates.push(webperfConfig.lastResultPath);
+  // 3. Fallback: ~/.karajan/webperf/<slug>/last.json
+  if (projectDir) {
+    candidates.push(path.join(webperfHome(), projectSlug(projectDir), "last.json"));
+  }
+  for (const candidate of candidates) {
+    try {
+      const raw = fs.readFileSync(candidate, "utf8");
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed === "object" && parsed.metrics) return parsed;
+    } catch { /* missing file or unparseable — try next */ }
+  }
+  return null;
+}
+
+/**
+ * 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 projectDir = config?.projectDir;
+  const persisted = loadPersistedScan(webperfConfig, projectDir);
+
+  if (persisted) {
+    const verdict = persisted.cwv || evaluateCwv(persisted.metrics, persisted.thresholds || webperfConfig.thresholds);
+    return {
+      available: true,
+      mode: "cwv-result",
+      url: persisted.url || webperfConfig.url || null,
+      capturedAt: persisted.capturedAt || null,
+      cwv: verdict,
+      thresholds: persisted.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/canvas/schema.js

@@ -51,7 +51,7 @@ const Operation = v.looseObject({
   acceptance: v.pipe(v.array(AcceptanceTest), v.minLength(1)),
 });
 
-export const CanvasSchema = v.looseObject({
+const CanvasSchema = v.looseObject({
   // Title is the project / feature name. The planner uses it as the
   // plan name unless the user overrides on prompt.
   title: NonEmptyString,

package/src/checks/binaries.js

@@ -60,7 +60,7 @@ function createCoreBinaryCheck(bin) {
 /**
  * Docker check. Manual strategy (platform-dependent install).
  */
-export function createDockerCheck() {
+function createDockerCheck() {
   return {
     name: "docker",
     label: "Docker",
@@ -80,7 +80,7 @@ export function createDockerCheck() {
 /**
  * Serena MCP (optional). Prompt strategy: we know how to install it.
  */
-export function createSerenaCheck() {
+function createSerenaCheck() {
   return {
     name: "serena",
     label: "Serena MCP",

package/src/checks/ci.js

@@ -37,7 +37,7 @@ function createWorkflowCheck(workflow) {
   };
 }
 
-export function createGhCliCheck() {
+function createGhCliCheck() {
   return {
     name: "ci:gh",
     label: "CI: gh CLI",
@@ -55,7 +55,7 @@ export function createGhCliCheck() {
   };
 }
 
-export function createGhSecretsCheck() {
+function createGhSecretsCheck() {
   return {
     name: "ci:secrets",
     label: "CI: GitHub secrets",

package/src/checks/config-files.js

@@ -20,7 +20,7 @@ import { STRATEGY } from "./types.js";
 /**
  * kj.config.yml presence check.
  */
-export function createConfigFileCheck() {
+function createConfigFileCheck() {
   return {
     name: "config",
     label: "Config file",
@@ -42,7 +42,7 @@ export function createConfigFileCheck() {
 /**
  * Review rules (.md) informational check.
  */
-export function createReviewRulesCheck() {
+function createReviewRulesCheck() {
   return {
     name: "review-rules",
     label: "Reviewer rules (.md)",
@@ -63,7 +63,7 @@ export function createReviewRulesCheck() {
 /**
  * Coder rules (.md) informational check.
  */
-export function createCoderRulesCheck() {
+function createCoderRulesCheck() {
   return {
     name: "coder-rules",
     label: "Coder rules (.md)",
@@ -104,7 +104,7 @@ function findDuplicateTomlKeys(content) {
 /**
  * Claude config (~/.claude.json) validity.
  */
-export function createClaudeConfigCheck() {
+function createClaudeConfigCheck() {
   return {
     name: "agent-config:claude",
     label: "Agent config: claude (~/.claude.json)",
@@ -135,7 +135,7 @@ export function createClaudeConfigCheck() {
 /**
  * Codex config (~/.codex/config.toml) validity.
  */
-export function createCodexConfigCheck() {
+function createCodexConfigCheck() {
   return {
     name: "agent-config:codex",
     label: "Agent config: codex (~/.codex/config.toml)",
@@ -173,7 +173,7 @@ export function createCodexConfigCheck() {
 /**
  * KJ config (~/.karajan/kj.config.yml) YAML validity (separate from existence).
  */
-export function createKjConfigYamlCheck() {
+function createKjConfigYamlCheck() {
   return {
     name: "agent-config:karajan",
     label: "Agent config: karajan (kj.config.yml)",

package/src/checks/dir-setup.js

@@ -15,6 +15,10 @@ const REQUIRED_DIRS = [
   "logs",
 ];
 
+/**
+ * @internal Exported for dynamic import from tests/checks/dir-setup.test.js
+ * and tests/checks/auto-remediation-e2e.test.js. Knip false positive.
+ */
 export function createKarajanDirsCheck() {
   return {
     name: "karajan-dirs",

package/src/checks/mcp-health.js

@@ -86,6 +86,9 @@ async function pingMcpStdio(command, args) {
 /**
  * karajan-mcp health — stdio server bundled with this package.
  * Strategy: auto (we can re-spawn it ourselves).
+ *
+ * @internal Exported for dynamic import from tests/checks/mcp-health.test.js.
+ * Knip false positive.
  */
 export function createKarajanMcpCheck() {
   return {
@@ -121,6 +124,9 @@ export function createKarajanMcpCheck() {
 /**
  * Serena MCP — external tool the user installs themselves. Warn only when
  * enabled in config. Strategy: manual (we don't manage its lifecycle).
+ *
+ * @internal Exported for dynamic import from tests/checks/mcp-health.test.js.
+ * Knip false positive.
  */
 export function createSerenaMcpCheck() {
   return {

package/src/checks/ports.js

@@ -24,6 +24,10 @@ function extractPortFromHost(host, fallback) {
   return m ? Number(m[1]) : fallback;
 }
 
+/**
+ * @internal Exported for dynamic import from tests/checks/ports.test.js
+ * and tests/checks/auto-remediation-e2e.test.js. Knip false positive.
+ */
 export function createSonarPortCheck() {
   return {
     name: "port:sonar",
@@ -133,6 +137,10 @@ export function createSonarPortCheck() {
   };
 }
 
+/**
+ * @internal Exported for dynamic import from tests/checks/ports.test.js
+ * and tests/checks/auto-remediation-e2e.test.js. Knip false positive.
+ */
 export function createHuBoardPortCheck() {
   return {
     name: "port:hu-board",

package/src/checks/rtk.js

@@ -8,7 +8,7 @@ import { getInstallCommand } from "../utils/os-detect.js";
 import { withDocLink } from "../utils/doc-links.js";
 import { STRATEGY } from "./types.js";
 
-export function createRtkCheck() {
+function createRtkCheck() {
   return {
     name: "rtk",
     label: "RTK (Rust Token Killer)",

package/src/checks/skills.js

@@ -8,10 +8,14 @@ import { isOpenSkillsAvailable } from "../skills/openskills-client.js";
 import { runCommand } from "../utils/process.js";
 import { STRATEGY } from "./types.js";
 
-export function skillsEnabled(config) {
+function skillsEnabled(config) {
   return config?.skills?.enabled !== false;
 }
 
+/**
+ * @internal Exported for dynamic import from tests/checks/skills.test.js
+ * and tests/checks/auto-remediation-e2e.test.js. Knip false positive.
+ */
 export function createOpenSkillsCheck() {
   return {
     name: "openskills",

package/src/checks/sonar.js

@@ -26,7 +26,7 @@ function sonarHost(config) {
  * Informative check: Sonar enabled/disabled status.
  * Produces an OK result with disabled description when Sonar is off.
  */
-export function createSonarStatusCheck() {
+function createSonarStatusCheck() {
   return {
     name: "sonarqube",
     label: "SonarQube",

package/src/checks/system.js

@@ -14,7 +14,7 @@ function getPackageVersion() {
   return JSON.parse(readFileSync(pkgPath, "utf8")).version;
 }
 
-export function createKarajanVersionCheck() {
+function createKarajanVersionCheck() {
   return {
     name: "karajan",
     label: "Karajan Code",
@@ -26,7 +26,7 @@ export function createKarajanVersionCheck() {
   };
 }
 
-export function createGitRepoCheck() {
+function createGitRepoCheck() {
   return {
     name: "git",
     label: "Git repository",

package/src/checks/tokens.js

@@ -146,4 +146,4 @@ export function getTokenChecks(config) {
 }
 
 // Re-export for tests that need to introspect the mapping.
-export { PROVIDER_TO_CLI, normalizeProvider };
+export { normalizeProvider };

package/src/checks/types.js

@@ -91,15 +91,3 @@ export const STRATEGY = Object.freeze({
   NONE: "none",
 });
 
-export const SEVERITY = Object.freeze({
-  FAIL: "fail",
-  WARN: "warn",
-  INFO: "info",
-});
-
-/**
- * Whether the final status blocks the pipeline (for preflight).
- */
-export function isBlocking(status) {
-  return status === STATUS.FAIL || status === STATUS.TIMEOUT;
-}

package/src/cli/register-meta.js

@@ -5,6 +5,7 @@ import { architectCommand } from "../commands/architect.js";
 import { auditCommand } from "../commands/audit.js";
 import { resumeCommand } from "../commands/resume.js";
 import { boardCommand } from "../commands/board.js";
+import { webperfCommand } from "../commands/webperf.js";
 import { undoCommand } from "../commands/undo.js";
 import { syncCommand } from "../commands/sync.js";
 import { cleanCommand } from "../commands/clean.js";
@@ -90,10 +91,16 @@ export function registerMeta(program, { pkgVersion }) {
     .description("Analyze codebase health (read-only)")
     .argument("[task]", "Task description. If absent, defaults to a full-codebase analysis. Use --task-file to point at a .md.")
     .option("--task-file <path>", "Read the task from a file (e.g. .md)")
-    .option("--dimensions <list>", "Comma-separated: security,quality,performance,architecture,testing", "all")
+    .option("--dimensions <list>", "Comma-separated: security,quality,performance,architecture,testing,accessibility (default: all; accessibility auto-skipped on detected backend-only projects)", "all")
     .option("--json", "Output raw JSON")
     .option("--agent-readiness", "Score the repo for AI-agent readability (llms.txt, SKILL.md coverage, page token budgets, robots allowlist, heading hierarchy). LLM-free; uses [path] or cwd as the audit target. See issue #542.")
     .option("--path <dir>", "Path to audit (used with --agent-readiness; defaults to cwd)")
+    .option("--no-sonar", "Skip the SonarQube findings collector (faster, less context). Sonar findings are also skipped automatically when SonarQube is unreachable.")
+    .option("--no-osv", "Skip the OSV-Scanner vulnerability collector. Findings are also skipped automatically when osv-scanner is not installed.")
+    .option("--no-semgrep", "Skip the Semgrep SAST collector. Findings are also skipped automatically when semgrep is not installed (install via 'pipx install semgrep' or 'brew install semgrep').")
+    .option("--report-file <path>", "Write the audit report to disk in addition to stdout. <path> may be a file (extension drives format: .md or .json) or a directory (creates audit-<ISO>.<md|json> inside). $KJ_AUDIT_REPORT_DIR env var is used as default directory if no --report-file is given.")
+    .option("--deterministic-only", "Skip the LLM analysis entirely. Print/persist only the deterministic findings (basalCost, sonar, stack, growth-delta, webperf). Zero tokens spent. Compatible with --report-file and --json.")
+    .option("-y, --yes", "Auto-confirm the 'Continue with LLM analysis?' prompt. Useful in scripts that want the full audit non-interactively. CI/non-TTY paths already auto-confirm without this flag.")
     .action(async (task, flags) => {
       await withConfig(pkgVersion, "audit", flags, async ({ config, logger }) => {
         let resolvedTask = task;
@@ -101,16 +108,45 @@ export function registerMeta(program, { pkgVersion }) {
           const { readTaskFile } = await import("../utils/task-file.js");
           resolvedTask = await readTaskFile(flags.taskFile, { projectDir: config.projectDir });
         }
+        // commander resolves --no-sonar to flags.sonar=false (negation flag).
+        // We translate to the explicit `noSonar: true` shape AuditRole expects.
         await auditCommand({
           task: resolvedTask || "Analyze the full codebase",
           config, logger,
           dimensions: flags.dimensions, json: flags.json,
           agentReadiness: Boolean(flags.agentReadiness),
           path: flags.path,
+          noSonar: flags.sonar === false,
+          noOsv: flags.osv === false,
+          noSemgrep: flags.semgrep === false,
+          reportFile: flags.reportFile || null,
+          deterministicOnly: Boolean(flags.deterministicOnly),
+          yes: Boolean(flags.yes),
         });
       });
     });
 
+  program
+    .command("webperf")
+    .description("Run a Lighthouse web-perf scan against a URL — Core Web Vitals + opportunities")
+    .argument("<url>", "Target URL (e.g. http://localhost:3000)")
+    .option("--mobile", "Use the Lighthouse mobile preset (default: desktop)")
+    .option("--json", "Output raw JSON")
+    .option("--no-persist", "Don't write the result into ~/.karajan/webperf/<slug>/last.json (kj audit reads it from there)")
+    .action(async (url, flags) => {
+      await withConfig(pkgVersion, "webperf", flags, async ({ config, logger }) => {
+        const result = await webperfCommand({
+          url,
+          config, logger,
+          mobile: Boolean(flags.mobile),
+          json: Boolean(flags.json),
+          persist: flags.persist !== false,
+        });
+        // Exit with non-zero when the verdict is FAIL so CI can gate.
+        if (result && result.ok === false) process.exitCode = 1;
+      });
+    });
+
   program
     .command("resume")
     .description("Resume a paused session")
@@ -153,10 +189,12 @@ export function registerMeta(program, { pkgVersion }) {
     .command("board [action]")
     .description("Manage HU Board (start|stop|status|open)")
     .option("--port <number>", "Port (default: 4000)", "4000")
+    .option("--bind <host>", "Bind host (default: 127.0.0.1; use 0.0.0.0 to expose on LAN — token auth auto-enforced)")
     .action(async (action = "start", opts) => {
       await withConfig(pkgVersion, "board", opts, async ({ config, logger }) => {
         const port = Number(opts.port) || config.hu_board?.port || 4000;
-        await boardCommand({ action, port, logger });
+        const bind = opts.bind || config.hu_board?.bind || "127.0.0.1";
+        await boardCommand({ action, port, bind, logger });
       });
     });
 

package/src/cli/register-pipeline.js

@@ -58,6 +58,7 @@ export function registerPipeline(program, { pkgVersion }) {
     .option("--enable-tester")
     .option("--enable-security")
     .option("--enable-impeccable")
+    .option("--enable-perf")
     .option("--enable-triage")
     .option("--enable-discover")
     .option("--enable-architect")