@karajan-family/code 4.21.0

package/src/commands/sync.js

@@ -0,0 +1,103 @@
+/**
+ * `kj sync` — closed-loop drift detection between code and Canvas/plan.
+ * Issue #540 MVP: detection + report.
+ * KJC-TSK-0348: `--apply` writes drift notes back into the source Canvas
+ * markdown (with `.bak` backup) so the user can review + commit.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { listPlans, loadPlan } from "../plan/plan-store.js";
+import { classifyDrift, formatDriftReport } from "../sync/detect-drift.js";
+import { applyCanvasPatch } from "../sync/apply-canvas-patch.js";
+
+const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", "coverage", ".karajan", ".kj", "tmp", ".cache", ".astro", ".next"]);
+
+function listSourceFiles(rootDir, out = []) {
+  for (const e of fs.readdirSync(rootDir, { withFileTypes: true })) {
+    if (e.name.startsWith(".") && !["src", "tests"].includes(e.name)) continue;
+    if (SKIP_DIRS.has(e.name)) continue;
+    const p = path.join(rootDir, e.name);
+    if (e.isDirectory()) {
+      listSourceFiles(p, out);
+    } else if (e.isFile()) {
+      try {
+        const s = fs.statSync(p);
+        out.push({
+          path: path.relative(rootDir, p),
+          mtime: s.mtime,
+        });
+      } catch { /* ignore stat errors */ }
+    }
+  }
+  return out;
+}
+
+/**
+ * @param {object} args
+ * @param {object} args.config
+ * @param {object} args.logger
+ * @param {string} [args.planId] — when set, sync against this plan; else use the latest
+ * @param {boolean} [args.json]
+ * @param {boolean} [args.apply] — when true, write a drift patch back into
+ *                                 the Canvas markdown the plan came from
+ *                                 (with `.bak` backup).
+ */
+export async function syncCommand({ config, logger, planId, json, apply }) {
+  const projectDir = config?.projectDir || process.cwd();
+
+  // Resolve which plan to sync against.
+  let plan;
+  if (planId) {
+    plan = await loadPlan(projectDir, planId);
+    if (!plan) throw new Error(`kj sync: plan not found: ${planId}`);
+  } else {
+    const all = await listPlans(projectDir);
+    if (!all || all.length === 0) {
+      throw new Error("kj sync: no plans found for this project. Generate one with `kj plan generate --task-file SPEC.md` (or `--canvas SPEC.canvas.md` for the structured form).");
+    }
+    // Pick the most recent plan by createdAt.
+    plan = await loadPlan(projectDir, all.sort((a, b) =>
+      new Date(b.createdAt || 0) - new Date(a.createdAt || 0))[0].planId);
+  }
+
+  logger.info(`kj sync: comparing ${projectDir} against plan ${plan.planId}`);
+
+  const files = listSourceFiles(projectDir);
+  const report = classifyDrift(plan, files);
+
+  let applyResult = null;
+  if (apply) {
+    if (!plan.sourceCanvasPath) {
+      throw new Error(
+        "kj sync --apply: this plan has no sourceCanvasPath — it was not generated from a SPEC.canvas.md. "
+        + "Re-run `kj plan generate --task-file SPEC.canvas.md` so the plan remembers the Canvas it came from."
+      );
+    }
+    applyResult = await applyCanvasPatch({ canvasPath: plan.sourceCanvasPath, report });
+  }
+
+  if (json) {
+    console.log(JSON.stringify({
+      planId: plan.planId,
+      projectDir,
+      ...report,
+      apply: applyResult,
+    }, null, 2));
+  } else {
+    console.log(formatDriftReport(report, plan));
+    if (applyResult) {
+      if (applyResult.skipped) {
+        console.log("\nkj sync --apply: no actionable drift, Canvas left untouched.");
+      } else {
+        console.log(
+          `\nkj sync --apply: wrote ${applyResult.mutations} drift note(s) to ${applyResult.patchedPath} `
+          + `(backup at ${applyResult.backupPath}).`
+        );
+      }
+    }
+  }
+
+  // Exit 0 always — drift is informational, not an error. CI users
+  // can opt-in to "exit non-zero on drift" later via a flag.
+}

package/src/commands/telemetry.js

@@ -0,0 +1,70 @@
+import { TELEMETRY_ENDPOINT, buildTelemetryPayload, isTelemetryEnabled } from "../utils/telemetry.js";
+
+/**
+ * Render the exact payload that would be POSTed for every event type.
+ *
+ * Read-only by design: this never opens a socket. It exists so users
+ * can inspect what telemetry sends before (or after) opting in,
+ * without grepping the source. The contract here MUST stay in sync
+ * with the producers in src/cli/_shared.js and the pipeline emitter
+ * in src/orchestrator/flow-runner.js — if a new field appears there,
+ * mirror it in the example below.
+ */
+function buildPreview(version) {
+  const v = version || "x.y.z";
+  return {
+    endpoint: TELEMETRY_ENDPOINT,
+    events: [
+      buildTelemetryPayload("install", { version: v }),
+      buildTelemetryPayload("cli_command", { version: v, command: "run" }),
+      buildTelemetryPayload("pipeline_complete", {
+        version: v,
+        mode: "standard",
+        agent: "claude",
+        duration_s: 42,
+        success: true,
+        taskType: "feature"
+      })
+    ]
+  };
+}
+
+export async function telemetryPreviewCommand({ config, logger, version, json }) {
+  const preview = buildPreview(version);
+  if (json) {
+    logger.info(JSON.stringify(preview, null, 2));
+    return preview;
+  }
+  const enabled = isTelemetryEnabled(config);
+  logger.info(`Telemetry endpoint: ${preview.endpoint}`);
+  logger.info(`Telemetry enabled:  ${enabled ? "yes" : "no"}`);
+  logger.info("");
+  logger.info("Exact payloads that would be POSTed (one per event type):");
+  logger.info("");
+  for (const payload of preview.events) {
+    logger.info(`  [${payload.event}]`);
+    logger.info(`    ${JSON.stringify(payload)}`);
+    logger.info("");
+  }
+  logger.info("No data was sent — `kj telemetry preview` never opens a socket.");
+  return preview;
+}
+
+export async function telemetryStatusCommand({ config, logger, json }) {
+  const enabled = isTelemetryEnabled(config);
+  const report = {
+    enabled,
+    endpoint: TELEMETRY_ENDPOINT,
+    flipHint: enabled
+      ? "Set `telemetry: false` in ~/.karajan/kj.config.yml (or re-run `kj init`) to turn it off."
+      : "Set `telemetry: true` in ~/.karajan/kj.config.yml (or re-run `kj init`) to turn it on."
+  };
+  if (json) {
+    logger.info(JSON.stringify(report, null, 2));
+    return report;
+  }
+  logger.info(`Telemetry: ${enabled ? "enabled" : "disabled"}`);
+  logger.info(`Endpoint:  ${report.endpoint}`);
+  logger.info(report.flipHint);
+  return report;
+}

package/src/commands/tournament.js

@@ -0,0 +1,85 @@
+/**
+ * `kj tournament` (KJC-TSK-0723, TOR-A) — fan the SAME task out to N coders
+ * in N isolated worktree lanes and collect the evidence. The deterministic
+ * scoreboard (TOR-B) and the governed judgement/merge (TOR-C) build on the
+ * artifacts this command leaves under .kj/tournaments/<id>/.
+ */
+import path from "node:path";
+import { runTournament } from "../tournament/run.js";
+import { scoreTournament } from "../tournament/scoreboard.js";
+import { judgeTournament } from "../tournament/judge.js";
+import { crownWinner } from "../tournament/crown.js";
+
+// The id feeds a path — same traversal class codex caught in TOR-A's coder
+// names: strict slug, no separators, before any filesystem use.
+function tournamentDirFor(config, rawId) {
+  const id = String(rawId);
+  if (!/^[a-z0-9][a-z0-9-]{0,63}$/i.test(id)) {
+    throw new Error(`tournament: id inválido "${id}" — usa el id que imprimió el torneo (p. ej. tor-abc123)`);
+  }
+  return path.join(config?.projectDir || process.cwd(), ".kj", "tournaments", id);
+}
+
+export async function tournamentCommand({
+  task, config, logger = console, flags = {},
+  runTournamentFn = runTournament, scoreTournamentFn = scoreTournament,
+  judgeTournamentFn = judgeTournament, crownWinnerFn = crownWinner,
+}) {
+  // TOR-C: `--judge <id>` ranks the finalists; `--crown <id>` commits the
+  // winner through the real gate in its lane.
+  if (flags.judge) {
+    const judgement = await judgeTournamentFn({ tournamentDir: tournamentDirFor(config, flags.judge), config, logger });
+    if (flags.json) logger?.info?.(JSON.stringify(judgement));
+    else logger?.info?.(`  siguiente: kj tournament --crown ${flags.judge}${judgement.escalated ? " (ganador vía solomon)" : ""}`);
+    return judgement;
+  }
+  if (flags.crown) {
+    const crown = await crownWinnerFn({
+      tournamentDir: tournamentDirFor(config, flags.crown), config, logger, cardRef: flags.card || null,
+    });
+    if (flags.json) logger?.info?.(JSON.stringify(crown));
+    return crown;
+  }
+
+  // TOR-B: `--score <id>` scores an EXISTING tournament from its artifacts.
+  if (flags.score) {
+    const tournamentDir = tournamentDirFor(config, flags.score);
+    const board = await scoreTournamentFn({ tournamentDir });
+    if (flags.json) {
+      logger?.info?.(JSON.stringify(board));
+      return board;
+    }
+    logger?.info?.(`scoreboard ${board.id} — regla: ${board.rule}`);
+    for (const r of board.rows) {
+      if (!r.finalist) {
+        logger?.info?.(`  ${r.coder.padEnd(10)} eliminado (${r.eliminated_by})`);
+        continue;
+      }
+      const mut = typeof r.mutation?.score === "number" ? `${r.mutation.score}%` : "n/a";
+      logger?.info?.(`  ${r.coder.padEnd(10)} FINALISTA  loc:${String(r.loc.net).padStart(5)}  tests:${r.loc.testsTouched}  mutation:${mut}`);
+    }
+    logger?.info?.(`  ranking: ${board.ranking.join(" > ") || "(sin finalistas)"}`);
+    return board;
+  }
+
+  if (!task || !String(task).trim()) {
+    throw new Error("tournament: falta la tarea — kj tournament \"<tarea>\" --coders claude,codex");
+  }
+  const coders = String(flags.coders || "")
+    .split(",")
+    .map((c) => c.trim())
+    .filter(Boolean);
+  if (coders.length < 2) {
+    throw new Error("tournament: hacen falta al menos 2 en --coders — p. ej. --coders claude,codex,agy (con uno no hay torneo)");
+  }
+
+  const res = await runTournamentFn({ task, coders, config, logger });
+
+  const completed = res.lanes.filter((l) => l.status === "completed");
+  const green = completed.filter((l) => l.suite?.ok);
+  logger?.info?.("");
+  logger?.info?.(`torneo ${res.id}: ${completed.length}/${res.lanes.length} carriles completados, ${green.length} con suite verde`);
+  logger?.info?.(`  evidencia: ${res.dir}`);
+  logger?.info?.("  siguiente: el scoreboard determinista (TOR-B) puntuará los carriles; de momento compara los diff.patch a mano.");
+  return res;
+}

package/src/commands/triage.js

@@ -0,0 +1,78 @@
+import { createAgent } from "../agents/index.js";
+import { assertAgentsAvailable } from "../agents/availability.js";
+import { resolveRole } from "../config.js";
+import { createCliProgressReporter } from "../utils/cli-progress.js";
+import { buildTriagePrompt } from "../prompts/triage.js";
+import { parseMaybeJsonString } from "../review/parser.js";
+import { withBrainRecovery } from "../brain/with-brain-recovery.js";
+
+function formatTriage(result) {
+  const lines = [];
+  lines.push(`## Triage Result`);
+  lines.push(`- **Level:** ${result.level || "unknown"}`);
+  if (result.taskType) lines.push(`- **Task type:** ${result.taskType}`);
+  if (result.reasoning) lines.push(`- **Reasoning:** ${result.reasoning}`);
+  lines.push("");
+
+  if (result.roles?.length) {
+    lines.push("### Recommended Roles");
+    for (const r of result.roles) {
+      lines.push(`- ${r}`);
+    }
+    lines.push("");
+  }
+
+  if (result.shouldDecompose) {
+    lines.push("### Decomposition Suggested");
+    if (result.subtasks?.length) {
+      for (const s of result.subtasks) {
+        lines.push(`- ${typeof s === "string" ? s : s.title || s}`);
+      }
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+export async function triageCommand({ task, config, logger, json }) {
+  const { withCliRunLog } = await import("../utils/cli-run-log.js");
+  return withCliRunLog("triage", { projectDir: config?.projectDir, logger }, async ({ runLog }) => {
+    const triageRole = resolveRole(config, "triage");
+    await assertAgentsAvailable([triageRole.provider]);
+    logger.info(`Triage (${triageRole.provider}) starting...`);
+    runLog.logText(`[triage] provider=${triageRole.provider}`);
+
+    const agent = createAgent(triageRole.provider, config, logger);
+    const prompt = buildTriagePrompt({ task });
+    const progress = createCliProgressReporter({ role: "triage" });
+    let result;
+    try {
+      result = await withBrainRecovery({
+        agent, taskArgs: { prompt, onOutput: progress.onOutput, role: "triage" },
+        role: "triage", provider: triageRole.provider, logger,
+      });
+      progress.finish(result.ok ? "done" : (result.action || "failed"));
+    } catch (err) { progress.finish("failed"); throw err; }
+
+    if (!result.ok) {
+      throw new Error(result.error || result.output || "Triage failed");
+    }
+
+    const parsed = parseMaybeJsonString(result.output);
+    if (parsed?.level) runLog.logText(`[triage] level=${parsed.level} roles=${(parsed.roles || []).join(",")}`);
+
+    if (json) {
+      console.log(JSON.stringify(parsed || result.output, null, 2));
+      return { ok: true };
+    }
+
+    if (parsed?.level) {
+      console.log(formatTriage(parsed));
+    } else {
+      console.log(result.output);
+    }
+    logger.info("Triage completed.");
+    return { ok: true };
+  });
+}

package/src/commands/undo.js

@@ -0,0 +1,62 @@
+import { loadMostRecentSession } from "../session/store.js";
+import { runCommand } from "../utils/process.js";
+
+/**
+ * Revert the last pipeline run by resetting to the pre-pipeline commit.
+ * Default: soft reset (keeps changes staged). With --hard: discards all changes.
+ */
+export async function undoCommand({ hard = false, logger } = {}) {
+  const session = await loadMostRecentSession();
+  if (!session) {
+    const msg = "No session to undo. No sessions found in the sessions directory.";
+    if (logger) logger.error(msg);
+    return { ok: false, error: msg };
+  }
+
+  const sha = session.session_start_sha;
+  if (!sha) {
+    const msg = `Session ${session.id} has no session_start_sha. Cannot determine the pre-pipeline commit.`;
+    if (logger) logger.error(msg);
+    return { ok: false, error: msg };
+  }
+
+  // Verify the SHA exists in git history
+  const verifyRes = await runCommand("git", ["cat-file", "-t", sha]);
+  if (verifyRes.exitCode !== 0 || verifyRes.stdout.trim() !== "commit") {
+    const msg = `Commit ${sha} not found in git history. It may have been garbage-collected or belong to a different repository.`;
+    if (logger) logger.error(msg);
+    return { ok: false, error: msg };
+  }
+
+  // Check there are commits after the SHA (HEAD is ahead)
+  const logRes = await runCommand("git", ["log", "--oneline", `${sha}..HEAD`]);
+  if (logRes.exitCode !== 0 || !logRes.stdout.trim()) {
+    const msg = `No commits to undo. HEAD is already at or before ${sha.slice(0, 8)}.`;
+    if (logger) logger.warn(msg);
+    return { ok: false, error: msg };
+  }
+
+  const mode = hard ? "--hard" : "--soft";
+  const resetRes = await runCommand("git", ["reset", mode, sha]);
+  if (resetRes.exitCode !== 0) {
+    const msg = `git reset ${mode} ${sha} failed: ${resetRes.stderr || resetRes.stdout}`;
+    if (logger) logger.error(msg);
+    return { ok: false, error: msg };
+  }
+
+  const shortSha = sha.slice(0, 8);
+  const message = hard
+    ? `Reverted to pre-pipeline state (commit ${shortSha}). All changes discarded.`
+    : `Reverted to pre-pipeline state (commit ${shortSha}). Changes are staged. Use \`git diff --cached\` to review.`;
+
+  if (logger) logger.info(message);
+  console.log(message);
+
+  return {
+    ok: true,
+    message,
+    sessionId: session.id,
+    sha,
+    mode: hard ? "hard" : "soft"
+  };
+}

package/src/commands/watch.js

@@ -0,0 +1,46 @@
+// KJC-TSK-0441 — `kj watch [start|stop|status]`. Thin wrappers.
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { startWatcher, readPidFile, clearPidFile, isPidAlive, writePidFile } from "../rag/watcher.js";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+export async function watchStartCommand({ config, logger, flags = {} }) {
+  const projectDir = config?.projectDir || process.cwd();
+  const existing = readPidFile();
+  if (existing && isPidAlive(existing)) { logger.info(`Watcher already running (pid ${existing}).`); return { pid: existing, started: false }; }
+  if (existing) clearPidFile();
+  if (flags.foreground) {
+    writePidFile();
+    const stop = startWatcher({ projectDir, config, logger, withSources: !!flags.withSources });
+    const shutdown = async () => { await stop(); clearPidFile(); process.exit(0); };
+    process.on("SIGINT", shutdown).on("SIGTERM", shutdown);
+    logger.info(`Watcher started in foreground (pid ${process.pid}). Ctrl+C to stop.`);
+    return { pid: process.pid, started: true };
+  }
+  const args = [join(HERE, "..", "cli.js"), "watch", "start", "--foreground", ...(flags.withSources ? ["--with-sources"] : [])];
+  const child = spawn(process.execPath, args, { detached: true, stdio: "ignore", env: { ...process.env, KJ_WATCHER_DAEMON: "1" } });
+  child.unref();
+  logger.info(`Watcher started in background (pid ${child.pid}).`);
+  return { pid: child.pid, started: true };
+}
+
+export async function watchStopCommand({ logger }) {
+  const pid = readPidFile();
+  if (!pid) { logger.info("No watcher running."); return { stopped: false }; }
+  if (!isPidAlive(pid)) { clearPidFile(); logger.info(`Stale PID file removed (process ${pid} was not alive).`); return { stopped: false, stale: true }; }
+  try { process.kill(pid, "SIGTERM"); } catch (err) { logger.warn(`Could not signal pid ${pid}: ${err.message}`); }
+  clearPidFile();
+  logger.info(`Watcher (pid ${pid}) stopped.`);
+  return { stopped: true, pid };
+}
+
+export async function watchStatusCommand({ logger }) {
+  const pid = readPidFile();
+  const alive = pid && isPidAlive(pid);
+  if (alive) logger.info(`Watcher running (pid ${pid}).`);
+  else if (pid) logger.warn(`Stale PID file (process ${pid} not alive). Run \`kj watch stop\` to clean up.`);
+  else logger.info("Watcher is NOT running.");
+  return { pid, alive };
+}

package/src/commands/webperf.js

@@ -0,0 +1,162 @@
+/**
+ * `kj webperf <url>` — KJC-TSK-0149.
+ *
+ * Headless Lighthouse wrapper. Produces structured CWV + opportunities
+ * JSON. Writes the result into `~/.karajan/webperf/<projectSlug>/last.json`
+ * so future `kj audit` runs can surface the verdict via the existing
+ * WebPerf section (KJC-TSK-0360 cwv-result mode).
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import yaml from "js-yaml";
+import { runWebperfScan } from "../webperf/scanner.js";
+import { withCliRunLog } from "../utils/cli-run-log.js";
+
+// Delegated to src/utils/paths.js (KJC-TSK-0420) — respects
+// KARAJAN_HOME / KJ_HOME / VITEST tmp / default.
+import { getWebperfDir } from "../utils/paths.js";
+function defaultReportDir() { return getWebperfDir(); }
+
+/**
+ * Slug a project directory the same way audit/basal-cost.js and
+ * plan/plan-store.js do, so the per-project webperf history aligns
+ * with audit history under ~/.karajan/.
+ */
+function projectSlug(projectDir) {
+  return path.basename(projectDir || process.cwd()).replaceAll(/[^a-zA-Z0-9_-]/g, "_");
+}
+
+function formatHumanReport(result) {
+  if (!result.ok) {
+    return `WebPerf scan FAILED — ${result.reason}`;
+  }
+  const lines = ["## WebPerf Scan", ""];
+  lines.push(`- URL: ${result.url}`);
+  lines.push(`- Preset: ${result.preset}`);
+  lines.push(`- Captured: ${result.capturedAt}`);
+  if (result.lighthouseVersion) lines.push(`- Lighthouse: v${result.lighthouseVersion}`);
+  if (typeof result.performanceScore === "number") {
+    lines.push(`- Performance score: ${result.performanceScore}/100`);
+  }
+  lines.push("");
+  lines.push(`### Verdict: ${result.cwv.pass ? "PASS" : "FAIL"}`);
+  lines.push("");
+  lines.push("### Core Web Vitals");
+  for (const [metric, score] of Object.entries(result.cwv.scores || {})) {
+    const value = formatMetricValue(metric, score.value);
+    lines.push(`- ${metric.toUpperCase()}: ${value} (${score.rating})`);
+  }
+  if (result.cwv.blocking?.length) {
+    lines.push("");
+    lines.push("### Blocking metrics (above poor threshold)");
+    for (const b of result.cwv.blocking) {
+      lines.push(`- ${b.metric.toUpperCase()}: ${formatMetricValue(b.metric, b.value)} > ${formatMetricValue(b.metric, b.threshold)}`);
+    }
+  }
+  if (result.issues?.length) {
+    lines.push("");
+    lines.push(`### Top opportunities (${result.issues.length})`);
+    for (const issue of result.issues.slice(0, 10)) {
+      const savings = issue.savingsMs ? ` (saves ~${Math.round(issue.savingsMs)}ms)` : "";
+      lines.push(`- [${issue.severity.toUpperCase()}] ${issue.id}${savings}: ${issue.title}`);
+    }
+    if (result.issues.length > 10) {
+      lines.push(`- ... and ${result.issues.length - 10} more`);
+    }
+  }
+  return lines.join("\n");
+}
+
+function formatMetricValue(metric, value) {
+  if (typeof value !== "number") return "n/a";
+  if (metric === "cls") return value.toFixed(3);
+  return `${Math.round(value)}ms`;
+}
+
+/**
+ * Persist the scan result into ~/.karajan/webperf/<slug>/last.json so
+ * `kj audit` can read it via collectWebPerfInput (KJC-TSK-0360).
+ */
+async function persistResult(result, projectDir) {
+  if (!result.ok) return null;
+  const dir = path.join(defaultReportDir(), projectSlug(projectDir));
+  await fs.mkdir(dir, { recursive: true });
+  const filePath = path.join(dir, "last.json");
+  await fs.writeFile(filePath, JSON.stringify(result, null, 2), "utf8");
+  return filePath;
+}
+
+/**
+ * Optionally update kj.config.yml so `kj audit` finds the result by
+ * default (mirrors how sonar config is wired). Best-effort: never
+ * fails the command; absence of config file or write error is logged.
+ */
+async function patchConfigLastResult(configPath, lastResultPath, logger) {
+  if (!configPath || !lastResultPath) return false;
+  let raw;
+  try { raw = await fs.readFile(configPath, "utf8"); } catch { return false; }
+  let parsed;
+  try { parsed = yaml.load(raw) || {}; } catch (err) {
+    if (logger?.warn) logger.warn(`webperf: cannot parse ${configPath}: ${err.message}`);
+    return false;
+  }
+  parsed.webperf = parsed.webperf || {};
+  parsed.webperf.lastResultPath = lastResultPath;
+  try {
+    await fs.writeFile(configPath, yaml.dump(parsed), "utf8");
+    return true;
+  } catch (err) {
+    if (logger?.warn) logger.warn(`webperf: cannot write ${configPath}: ${err.message}`);
+    return false;
+  }
+}
+
+export async function webperfCommand({ url, config, logger, json = false, mobile = false, persist = true, thresholds = null }) {
+  if (!url) {
+    throw new Error("kj webperf: <url> is required (e.g. http://localhost:3000)");
+  }
+  return withCliRunLog("webperf", { projectDir: config?.projectDir, logger }, async ({ runLog }) => {
+    logger.info(`Running webperf scan against ${url} (preset: ${mobile ? "mobile" : "desktop"})`);
+    runLog.logText(`[webperf] scan url=${url} preset=${mobile ? "mobile" : "desktop"}`);
+
+    const scanThresholds = thresholds || config?.webperf?.thresholds || null;
+    const result = await runWebperfScan(url, {
+      preset: mobile ? "mobile" : "desktop",
+      thresholds: scanThresholds,
+      logger,
+    });
+
+    if (json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(formatHumanReport(result));
+    }
+
+    if (!result.ok) {
+      runLog.logText(`[webperf] failed reason=${result.reason}`);
+      return { ok: false, reason: result.reason };
+    }
+
+    runLog.logText(`[webperf] verdict=${result.cwv.pass ? "PASS" : "FAIL"} score=${result.performanceScore}`);
+
+    let savedPath = null;
+    if (persist) {
+      try {
+        savedPath = await persistResult(result, config?.projectDir);
+        if (savedPath) {
+          logger.info(`WebPerf result saved: ${savedPath}`);
+          // Wire into kj.config.yml so `kj audit` picks it up automatically.
+          const configPath = config?.configFilePath
+            || path.join(config?.projectDir || process.cwd(), ".karajan", "kj.config.yml");
+          await patchConfigLastResult(configPath, savedPath, logger);
+        }
+      } catch (err) {
+        logger.warn(`webperf: persist failed (non-blocking): ${err.message}`);
+      }
+    }
+
+    // Exit code: 0 for PASS, 1 for FAIL. Lets CI gate on it.
+    return { ok: result.cwv.pass, result, savedPath };
+  });
+}