@cappa/cli 0.17.1 → 0.19.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.mjs CHANGED
@@ -1,7 +1,7 @@
1
1
  import { getLogger, initLogger } from "@cappa/logger";
2
2
  import { Command, InvalidArgumentError } from "commander";
3
3
  import { configToEngineOptions, defaultConfig, getConfig } from "@cappa/config";
4
- import { JUDGED_LABELS, JUDGE_MODES, LocalEngine, ScreenshotFileSystem, clearJudgment, collectScreenshots, groupScreenshots, isJudgedLabel, normalizeChangeType, readAgentReport, runAgentCheck, toSlimAgentReport, writeAgentVerdict } from "@cappa/core";
4
+ import { LocalEngine, ScreenshotFileSystem, VERDICT_LABELS, clearJudgment, collectScreenshots, groupScreenshots, isVerdictLabel, normalizeChangeType, removePlaywrightContainers, resolveContainerOptions, runAgentCheck, toSlimAgentReport, writeAgentVerdict } from "@cappa/core";
5
5
  import chalk from "chalk";
6
6
  import path from "node:path";
7
7
  import { fileURLToPath } from "node:url";
@@ -12,7 +12,7 @@ import { ProtocolMismatchError, createClient } from "@cappa/client";
12
12
  import { createServer, isLoopbackHost } from "@cappa/server";
13
13
  import { randomBytes } from "node:crypto";
14
14
  //#region package.json
15
- var version = "0.17.1";
15
+ var version = "0.19.0";
16
16
  //#endregion
17
17
  //#region ../../node_modules/.pnpm/tsdown@0.23.0_@arethetypeswrong+core@0.18.5_oxc-resolver@11.24.2_tsx@4.23.1_typescript@7.0.2/node_modules/tsdown/esm-shims.js
18
18
  const getFilename = () => fileURLToPath(import.meta.url);
@@ -392,8 +392,7 @@ const run$1 = async (options, action) => {
392
392
  const LABEL_COLORS = {
393
393
  "regression-likely": chalk.red,
394
394
  "intentional-likely": chalk.green,
395
- "noise-likely": chalk.gray,
396
- ambiguous: chalk.yellow
395
+ "noise-likely": chalk.gray
397
396
  };
398
397
  /** Human-readable lines for a report — what `--json` prints, for people. */
399
398
  const describeAgentReport = (report) => {
@@ -401,13 +400,14 @@ const describeAgentReport = (report) => {
401
400
  const lines = [`${totals.passed}/${totals.total} passed · ${totals.changed} changed · ${totals.new} new · ${totals.deleted} deleted`];
402
401
  if (totals.pendingJudgments > 0) lines.push(chalk.yellow(`${totals.pendingJudgments} awaiting judgment in ${report.outputDir}/.cappa-agent/judgments`));
403
402
  for (const entry of report.entries) {
404
- if (entry.category !== "changed" || !entry.verdict) {
403
+ if (entry.category !== "changed") {
405
404
  lines.push(`${chalk.bold(entry.name)} ${chalk.dim(entry.category)}`);
406
405
  continue;
407
406
  }
408
- const { label, headline, source } = entry.verdict;
409
- const tags = [source === "agent" ? "judged" : void 0, entry.pending ? "pending" : void 0].filter(Boolean);
410
- lines.push(`${chalk.bold(entry.name)} ${LABEL_COLORS[label](label)} — ${headline}${tags.length > 0 ? chalk.dim(` (${tags.join(", ")})`) : ""}`);
407
+ if (entry.verdict) {
408
+ const { label, headline } = entry.verdict;
409
+ lines.push(`${chalk.bold(entry.name)} ${LABEL_COLORS[label](label)} — ${headline}`);
410
+ } else lines.push(`${chalk.bold(entry.name)} ${chalk.yellow("awaiting judgment")} — ${entry.change ?? "changed"}`);
411
411
  if (entry.verdictError) lines.push(chalk.red(` verdict.json ignored: ${entry.verdictError}`));
412
412
  }
413
413
  return lines;
@@ -417,7 +417,6 @@ const agentCheck = (options) => run$1(options, async () => {
417
417
  const report = await runAgentCheck({
418
418
  outputDir: config.outputDir,
419
419
  diff: config.diff,
420
- judge: options.judge,
421
420
  maxTileRegions: options.maxTileRegions
422
421
  });
423
422
  if (options.json) printJson(toSlimAgentReport(report));
@@ -459,11 +458,9 @@ const agentApprove = (names, options) => run$1(options, async () => {
459
458
  if (unknown.length > 0) throw new Error(`Nothing to approve for: ${unknown.join(", ")} — names must match exactly (see \`cappa agent check --json\`).`);
460
459
  const verdicts = /* @__PURE__ */ new Map();
461
460
  if (!!options.label?.length || names.some((name) => byName.get(name)?.category === "changed")) {
462
- const previous = await readAgentReport(config.outputDir);
463
461
  const report = await runAgentCheck({
464
462
  outputDir: config.outputDir,
465
- diff: config.diff,
466
- judge: previous?.judge ?? "ambiguous"
463
+ diff: config.diff
467
464
  });
468
465
  for (const entry of report.entries) if (entry.category === "changed" && entry.verdict) verdicts.set(entry.name, entry.verdict.label);
469
466
  }
@@ -474,7 +471,7 @@ const agentApprove = (names, options) => run$1(options, async () => {
474
471
  return screenshot && screenshot.category !== "passed" ? [screenshot] : [];
475
472
  });
476
473
  const regressions = toApprove.filter((s) => verdicts.get(s.name) === "regression-likely").map((s) => s.name);
477
- if (regressions.length > 0 && !options.allowRegression) throw new Error(`Refusing to approve regression-likely: ${regressions.join(", ")} — if the change is intended, judge it (\`cappa agent check --judge all\`, then \`cappa agent judge <name> --label intentional-likely\`), or pass --allow-regression.`);
474
+ if (regressions.length > 0 && !options.allowRegression) throw new Error(`Refusing to approve regression-likely: ${regressions.join(", ")} — if the change is intended, judge it again (\`cappa agent judge <name> --label intentional-likely\`), or pass --allow-regression.`);
478
475
  await new ScreenshotFileSystem(config.outputDir).approveScreenshots(toApprove, config.diff);
479
476
  await Promise.all(toApprove.map((screenshot) => clearJudgment(config.outputDir, screenshot.name)));
480
477
  const approved = toApprove.map((s) => ({
@@ -580,7 +577,7 @@ const parseChoice = (choices, what) => (value) => {
580
577
  return value;
581
578
  };
582
579
  const parseLabel = (value) => {
583
- if (!isJudgedLabel(value)) throw new InvalidArgumentError(`label must be one of: ${JUDGED_LABELS.join(", ")}`);
580
+ if (!isVerdictLabel(value)) throw new InvalidArgumentError(`label must be one of: ${VERDICT_LABELS.join(", ")}`);
584
581
  return value;
585
582
  };
586
583
  const collectLabel = (value, previous = []) => [...previous, parseLabel(value)];
@@ -595,9 +592,9 @@ const parsePositiveInt = (value) => {
595
592
  return parsed;
596
593
  };
597
594
  const registerAgentCommand = (program) => {
598
- const agent = program.command("agent").description("Visual review for coding agents: label changes, hand ambiguous ones to an agent, approve");
599
- agent.command("check").description("Label every changed screenshot and write judgment requests for an agent (does not capture)").option("--judge <mode>", `which changes get a judgment request: ${JUDGE_MODES.join(", ")}`, parseChoice(JUDGE_MODES, "--judge"), "ambiguous").option("--max-tile-regions <count>", "regions rendered into each regions.png", parsePositiveInt).option("--json", "print a JSON summary to stdout").action(agentCheck);
600
- agent.command("judge").description("Record a verdict for screenshots with a judgment request").argument("<names...>", "screenshot names, exactly as reported").requiredOption("--label <label>", JUDGED_LABELS.join(" | "), parseLabel).requiredOption("--headline <text>", "one line describing the change").option("--rationale <text...>", "reasons for the verdict").option("--confidence <number>", "0 to 1", parseConfidence).option("--json", "print a JSON summary to stdout").action(agentJudge);
595
+ const agent = program.command("agent").description("Visual review for coding agents: hand every change to a judge, record verdicts, approve");
596
+ agent.command("check").description("Write a judgment request for every changed screenshot and apply verdicts already recorded (does not capture)").option("--max-tile-regions <count>", "regions rendered into each regions.png", parsePositiveInt).option("--json", "print a JSON summary to stdout").action(agentCheck);
597
+ agent.command("judge").description("Record a verdict for screenshots with a judgment request").argument("<names...>", "screenshot names, exactly as reported").requiredOption("--label <label>", VERDICT_LABELS.join(" | "), parseLabel).requiredOption("--headline <text>", "one line describing the change").option("--rationale <text...>", "reasons for the verdict").option("--confidence <number>", "0 to 1", parseConfidence).option("--json", "print a JSON summary to stdout").action(agentJudge);
601
598
  agent.command("approve").description("Approve screenshots by exact name or by verdict label (refused in CI)").argument("[names...]", "screenshot names, exactly as reported").option("--label <label>", "also approve every changed screenshot with this verdict label (repeatable)", collectLabel).option("--allow-regression", "approve screenshots whose current verdict is regression-likely").option("--json", "print a JSON summary to stdout").action(agentApprove);
602
599
  agent.command("init").description("Install the cappa skill for coding agents in this project").option("--stack <stack>", `${SKILL_STACK_NAMES.join(", ")} or all (default: detected)`, parseChoice([...SKILL_STACK_NAMES, "all"], "--stack")).option("--force", "overwrite skill files that were modified").option("--runner <command>", "how the project runs cappa, e.g. `pnpm exec cappa` (default: from the lockfile)").option("--judge-model <model>", "pin the cappa-judge subagent to a model that can read images: provider/model for OpenCode, an alias or model id for Claude Code (default: the calling model)").option("--json", "print a JSON summary to stdout").action(agentInit);
603
600
  agent.command("guard", { hidden: true }).description("Allow or block a cappa-judge Bash call (Claude Code hook)").requiredOption("--runner <command>", "how the project runs cappa").action(agentGuard);
@@ -638,6 +635,37 @@ const filterScreenshots = (screenshots, filters) => {
638
635
  });
639
636
  };
640
637
  //#endregion
638
+ //#region src/commands/browser.ts
639
+ /**
640
+ * The container CLI to use: `--cli`, else the config's
641
+ * `playwright({ container: { cli } })`, else `CAPPA_CONTAINER_CLI`, else
642
+ * docker. A config that fails to load must not block cleanup.
643
+ */
644
+ const resolveCli = async (cli) => {
645
+ if (cli) return cli;
646
+ let container;
647
+ try {
648
+ container = (await getConfig()).browser?.provider?.options?.container;
649
+ } catch (error) {
650
+ getLogger().debug("Could not load the config:", error);
651
+ }
652
+ return resolveContainerOptions(container && container !== true ? container : true)?.cli ?? "docker";
653
+ };
654
+ /** `cappa browser down` — remove every Playwright container cappa started. */
655
+ const browserDown = async (options = {}) => {
656
+ const logger = getLogger();
657
+ const cli = await resolveCli(options.cli);
658
+ const removed = await removePlaywrightContainers({ cli });
659
+ if (removed.length === 0) {
660
+ logger.info("No Playwright containers to remove.");
661
+ return;
662
+ }
663
+ for (const name of removed) logger.success(`Removed ${name}`);
664
+ };
665
+ const registerBrowserCommand = (program) => {
666
+ program.command("browser").description("Manage the Playwright container (browser.provider container)").command("down").description("Remove every Playwright container cappa started").option("--cli <cli>", "container CLI to use (docker, podman, nerdctl)").action(browserDown);
667
+ };
668
+ //#endregion
641
669
  //#region src/utils/captureReport.ts
642
670
  const errorMessage = (error) => {
643
671
  if (typeof error === "string") return error;
@@ -1589,6 +1617,7 @@ program.command("serve").description("Host a capture engine for a remote `cappa
1589
1617
  program.command("approve").description("Approve screenshots").option("-f, --filter <filter...>", "only approve screenshots whose name includes the provided filter value(s)").action(approve);
1590
1618
  program.command("status").description("Get status of screenshots").option("--max-regions <count>", "maximum number of interpreted diff regions listed per changed screenshot (0 to disable)", parseMaxRegions, 5).action(status);
1591
1619
  registerAgentCommand(program);
1620
+ registerBrowserCommand(program);
1592
1621
  program.command("init").description("Initialize Cappa in the current directory").action(init);
1593
1622
  async function run() {
1594
1623
  await program.parseAsync();