@cappa/cli 0.13.2 → 0.14.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,16 +1,336 @@
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 { LocalEngine, ScreenshotFileSystem, collectScreenshots, groupScreenshots } from "@cappa/core";
5
- import path from "node:path";
4
+ import { JUDGED_LABELS, JUDGE_MODES, LocalEngine, ScreenshotFileSystem, clearJudgment, collectScreenshots, groupScreenshots, isJudgedLabel, normalizeChangeType, readAgentReport, runAgentCheck, toSlimAgentReport, writeAgentVerdict } from "@cappa/core";
6
5
  import chalk from "chalk";
6
+ import path from "node:path";
7
+ import { fileURLToPath } from "node:url";
8
+ import fs from "node:fs";
9
+ import fsp from "node:fs/promises";
7
10
  import { z } from "zod";
8
11
  import { ProtocolMismatchError, createClient } from "@cappa/client";
9
12
  import { createServer, isLoopbackHost } from "@cappa/server";
10
- import fs from "node:fs";
11
13
  import { randomBytes } from "node:crypto";
12
14
  //#region package.json
13
- var version = "0.13.2";
15
+ var version = "0.14.0";
16
+ //#endregion
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
+ const getFilename = () => fileURLToPath(import.meta.url);
19
+ const getDirname = () => path.dirname(getFilename());
20
+ const __dirname = /* @__PURE__ */ getDirname();
21
+ //#endregion
22
+ //#region src/utils/agentSkills.ts
23
+ /**
24
+ * Agent integrations `cappa agent init` can install, and the files each one
25
+ * gets.
26
+ *
27
+ * - `claude` — Claude Code: the skill in `.claude/skills/cappa`.
28
+ * - `agents` — the vendor-neutral Agent Skills directory `.agents/skills`,
29
+ * read by Codex, OpenCode and other agents that adopted it.
30
+ * - `opencode` — OpenCode: the `.agents` skill plus slash commands that run
31
+ * the review flow and a sandboxed `cappa-judge` subagent that judges
32
+ * screenshots in its own context.
33
+ *
34
+ * Sources are relative to the package's `integrations/` directory; targets
35
+ * are relative to the project.
36
+ */
37
+ const SKILL = [
38
+ "skills/cappa/SKILL.md",
39
+ "skills/cappa/JUDGING.md",
40
+ "skills/cappa/MASKING.md"
41
+ ];
42
+ const skillInto = (dir) => SKILL.map((source) => ({
43
+ source,
44
+ target: path.join(dir, path.basename(source))
45
+ }));
46
+ const STACK_FILES = {
47
+ claude: skillInto(".claude/skills/cappa"),
48
+ agents: skillInto(".agents/skills/cappa"),
49
+ opencode: [...skillInto(".agents/skills/cappa"), ...[
50
+ "commands/cappa-review.md",
51
+ "commands/cappa-judge.md",
52
+ "commands/cappa-approve.md",
53
+ "agents/cappa-judge.md"
54
+ ].map((file) => ({
55
+ source: `opencode/${file}`,
56
+ target: path.join(".opencode", file)
57
+ }))]
58
+ };
59
+ const SKILL_STACK_NAMES = Object.keys(STACK_FILES);
60
+ /**
61
+ * Find the integration sources shipped with the package.
62
+ *
63
+ * They live in `integrations/` at the package root, which is one level above
64
+ * `dist/` when installed and two above `src/utils/` in development — so walk
65
+ * up instead of hard-coding either depth.
66
+ */
67
+ const findIntegrationsDir = (from = __dirname) => {
68
+ let current = from;
69
+ while (true) {
70
+ const candidate = path.join(current, "integrations");
71
+ if (fs.existsSync(path.join(candidate, "skills", "cappa", "SKILL.md"))) return candidate;
72
+ const parent = path.dirname(current);
73
+ if (parent === current) throw new Error("Could not locate the bundled cappa agent skill files");
74
+ current = parent;
75
+ }
76
+ };
77
+ /**
78
+ * Pick the stacks to install when none was named: whichever agents the
79
+ * project already shows signs of, falling back to Claude Code.
80
+ *
81
+ * OpenCode wins over plain `agents` — its stack already includes the
82
+ * `.agents` skill, and adds the commands on top.
83
+ */
84
+ const detectSkillStacks = (cwd) => {
85
+ const has = (entry) => fs.existsSync(path.join(cwd, entry));
86
+ const stacks = [];
87
+ if (has(".claude") || has("CLAUDE.md")) stacks.push("claude");
88
+ if (has(".opencode") || has("opencode.json") || has("opencode.jsonc")) stacks.push("opencode");
89
+ else if (has(".agents") || has("AGENTS.md")) stacks.push("agents");
90
+ return stacks.length > 0 ? stacks : ["claude"];
91
+ };
92
+ /**
93
+ * How the project runs its own `cappa` binary, from its lockfile.
94
+ *
95
+ * Written into the installed files because OpenCode commands run shell
96
+ * commands *before* the model sees anything, so a bare `cappa` that is not on
97
+ * `PATH` would inject an error instead of the review state; and agent
98
+ * permission rules match the command text literally.
99
+ */
100
+ const detectCappaRunner = (cwd) => {
101
+ const has = (entry) => fs.existsSync(path.join(cwd, entry));
102
+ if (has("pnpm-lock.yaml")) return "pnpm exec cappa";
103
+ if (has("yarn.lock")) return "yarn cappa";
104
+ if (has("bun.lock") || has("bun.lockb")) return "bunx cappa";
105
+ return "npx cappa";
106
+ };
107
+ /** Fill the `{{cappa}}` placeholder in a source file. */
108
+ const renderIntegrationFile = (source, runner) => source.replaceAll("{{cappa}}", runner);
109
+ /**
110
+ * Copy each stack's files into the project.
111
+ *
112
+ * A file that exists with different content is left alone unless `force` is
113
+ * set: users are expected to tailor these to their project, and an upgrade
114
+ * must not silently discard that. A target shared by two stacks (the
115
+ * `.agents` skill) is written once.
116
+ */
117
+ const installAgentSkills = async (options) => {
118
+ const sourceDir = options.sourceDir ?? findIntegrationsDir();
119
+ const runner = options.runner ?? detectCappaRunner(options.cwd);
120
+ const files = [];
121
+ const seen = /* @__PURE__ */ new Set();
122
+ for (const stack of options.stacks) for (const mapping of STACK_FILES[stack]) {
123
+ const target = path.resolve(options.cwd, mapping.target);
124
+ if (seen.has(target)) continue;
125
+ seen.add(target);
126
+ const source = renderIntegrationFile(await fsp.readFile(path.join(sourceDir, mapping.source), "utf8"), runner);
127
+ const existing = await fsp.readFile(target, "utf8").catch(() => void 0);
128
+ if (existing === source) {
129
+ files.push({
130
+ stack,
131
+ path: target,
132
+ status: "unchanged"
133
+ });
134
+ continue;
135
+ }
136
+ if (existing !== void 0 && !options.force) {
137
+ files.push({
138
+ stack,
139
+ path: target,
140
+ status: "skipped"
141
+ });
142
+ continue;
143
+ }
144
+ await fsp.mkdir(path.dirname(target), { recursive: true });
145
+ await fsp.writeFile(target, source, "utf8");
146
+ files.push({
147
+ stack,
148
+ path: target,
149
+ status: "written"
150
+ });
151
+ }
152
+ const warnings = [];
153
+ const claudeSkill = fs.existsSync(path.resolve(options.cwd, ".claude/skills/cappa/SKILL.md"));
154
+ if (options.stacks.includes("opencode") && claudeSkill) warnings.push("OpenCode reads .claude/skills too, and uses that copy of the cappa skill over the one in .agents/skills — keep the two in sync if you tailor them.");
155
+ return {
156
+ runner,
157
+ files,
158
+ warnings
159
+ };
160
+ };
161
+ //#endregion
162
+ //#region src/commands/agent.ts
163
+ const printJson = (value) => {
164
+ process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
165
+ };
166
+ /** `CI=true`/`CI=1` — but not `CI=false`, which some tools set explicitly. */
167
+ const isCi = (env = process.env) => {
168
+ const value = env.CI?.trim().toLowerCase();
169
+ return !!value && value !== "false" && value !== "0";
170
+ };
171
+ /**
172
+ * Run `action`, reporting a failure as `{ error }` under `--json` instead of
173
+ * a log line an agent would have to find.
174
+ */
175
+ const run$1 = async (options, action) => {
176
+ try {
177
+ await action();
178
+ } catch (error) {
179
+ const message = error instanceof Error ? error.message : String(error);
180
+ if (options.json) printJson({ error: message });
181
+ else getLogger().error(message);
182
+ process.exitCode = 1;
183
+ }
184
+ };
185
+ const LABEL_COLORS = {
186
+ "regression-likely": chalk.red,
187
+ "intentional-likely": chalk.green,
188
+ "noise-likely": chalk.gray,
189
+ ambiguous: chalk.yellow
190
+ };
191
+ /** Human-readable lines for a report — what `--json` prints, for people. */
192
+ const describeAgentReport = (report) => {
193
+ const { totals } = report;
194
+ const lines = [`${totals.passed}/${totals.total} passed · ${totals.changed} changed · ${totals.new} new · ${totals.deleted} deleted`];
195
+ if (totals.pendingJudgments > 0) lines.push(chalk.yellow(`${totals.pendingJudgments} awaiting judgment in ${report.outputDir}/.cappa-agent/judgments`));
196
+ for (const entry of report.entries) {
197
+ if (entry.category !== "changed" || !entry.verdict) {
198
+ lines.push(`${chalk.bold(entry.name)} ${chalk.dim(entry.category)}`);
199
+ continue;
200
+ }
201
+ const { label, headline, source } = entry.verdict;
202
+ const tags = [source === "agent" ? "judged" : void 0, entry.pending ? "pending" : void 0].filter(Boolean);
203
+ lines.push(`${chalk.bold(entry.name)} ${LABEL_COLORS[label](label)} — ${headline}${tags.length > 0 ? chalk.dim(` (${tags.join(", ")})`) : ""}`);
204
+ if (entry.verdictError) lines.push(chalk.red(` verdict.json ignored: ${entry.verdictError}`));
205
+ }
206
+ return lines;
207
+ };
208
+ const agentCheck = (options) => run$1(options, async () => {
209
+ const config = await getConfig();
210
+ const report = await runAgentCheck({
211
+ outputDir: config.outputDir,
212
+ diff: config.diff,
213
+ judge: options.judge,
214
+ maxTileRegions: options.maxTileRegions
215
+ });
216
+ if (options.json) printJson(toSlimAgentReport(report));
217
+ else getLogger().box({
218
+ title: "Agent Review",
219
+ message: describeAgentReport(report).join("\n")
220
+ });
221
+ if (report.entries.length > 0) process.exitCode = 1;
222
+ });
223
+ const agentJudge = (names, options) => run$1(options, async () => {
224
+ const config = await getConfig();
225
+ const written = [];
226
+ for (const name of names) {
227
+ const verdict = await writeAgentVerdict(config.outputDir, name, {
228
+ label: options.label,
229
+ headline: options.headline,
230
+ rationale: options.rationale,
231
+ confidence: options.confidence
232
+ });
233
+ written.push({
234
+ name,
235
+ verdict
236
+ });
237
+ }
238
+ if (options.json) printJson({ written });
239
+ else getLogger().success(`Recorded ${options.label} for ${written.length} screenshot(s) — run \`cappa agent check\` to apply`);
240
+ });
241
+ const agentApprove = (names, options) => run$1(options, async () => {
242
+ if (isCi()) throw new Error("Refusing to approve in CI — baselines are only changed on developer machines.");
243
+ if (names.length === 0 && !options.label?.length) throw new Error("Name the screenshots to approve, or pass --label.");
244
+ const config = await getConfig();
245
+ const screenshots = await collectScreenshots(config.outputDir);
246
+ const byName = new Map(screenshots.map((s) => [s.name, s]));
247
+ const wanted = new Set(names);
248
+ const unknown = names.filter((name) => {
249
+ const screenshot = byName.get(name);
250
+ return !screenshot || screenshot.category === "passed";
251
+ });
252
+ if (unknown.length > 0) throw new Error(`Nothing to approve for: ${unknown.join(", ")} — names must match exactly (see \`cappa agent check --json\`).`);
253
+ if (options.label?.length) {
254
+ const previous = await readAgentReport(config.outputDir);
255
+ const report = await runAgentCheck({
256
+ outputDir: config.outputDir,
257
+ diff: config.diff,
258
+ judge: previous?.judge ?? "ambiguous"
259
+ });
260
+ const labels = new Set(options.label);
261
+ for (const entry of report.entries) if (entry.category === "changed" && entry.verdict && labels.has(entry.verdict.label)) wanted.add(entry.name);
262
+ }
263
+ const toApprove = [...wanted].flatMap((name) => {
264
+ const screenshot = byName.get(name);
265
+ return screenshot && screenshot.category !== "passed" ? [screenshot] : [];
266
+ });
267
+ await new ScreenshotFileSystem(config.outputDir).approveScreenshots(toApprove, config.diff);
268
+ await Promise.all(toApprove.map((screenshot) => clearJudgment(config.outputDir, screenshot.name)));
269
+ const approved = toApprove.map((s) => ({
270
+ name: s.name,
271
+ category: s.category
272
+ }));
273
+ if (options.json) printJson({ approved });
274
+ else if (approved.length === 0) getLogger().warn("No screenshots matched");
275
+ else getLogger().success(`Approved ${approved.length} screenshot(s): ${approved.map((s) => s.name).join(", ")}`);
276
+ });
277
+ const agentInit = (options) => run$1(options, async () => {
278
+ const cwd = process.cwd();
279
+ const stacks = options.stack === "all" ? SKILL_STACK_NAMES : options.stack ? [options.stack] : detectSkillStacks(cwd);
280
+ const { runner, files, warnings } = await installAgentSkills({
281
+ cwd,
282
+ stacks,
283
+ force: options.force,
284
+ runner: options.runner
285
+ });
286
+ if (options.json) {
287
+ printJson({
288
+ stacks,
289
+ runner,
290
+ files,
291
+ warnings
292
+ });
293
+ return;
294
+ }
295
+ const logger = getLogger();
296
+ for (const file of files) {
297
+ const verb = {
298
+ written: chalk.green("wrote"),
299
+ unchanged: chalk.dim("unchanged"),
300
+ skipped: chalk.yellow("skipped (modified — use --force)")
301
+ }[file.status];
302
+ logger.log(`${verb} ${file.path}`);
303
+ }
304
+ logger.log(chalk.dim(`commands run as \`${runner}\` (--runner to change)`));
305
+ for (const warning of warnings) logger.warn(warning);
306
+ logger.success(stacks.includes("opencode") ? "Agent integration installed — run /cappa-review in OpenCode, or /cappa in Claude Code" : "Agent skill installed — ask your agent to run a visual review, or use /cappa in Claude Code");
307
+ });
308
+ const parseChoice = (choices, what) => (value) => {
309
+ if (!choices.includes(value)) throw new InvalidArgumentError(`${what} must be one of: ${choices.join(", ")}`);
310
+ return value;
311
+ };
312
+ const parseLabel = (value) => {
313
+ if (!isJudgedLabel(value)) throw new InvalidArgumentError(`label must be one of: ${JUDGED_LABELS.join(", ")}`);
314
+ return value;
315
+ };
316
+ const collectLabel = (value, previous = []) => [...previous, parseLabel(value)];
317
+ const parseConfidence = (value) => {
318
+ const parsed = Number(value);
319
+ if (!Number.isFinite(parsed) || parsed < 0 || parsed > 1) throw new InvalidArgumentError("confidence must be a number from 0 to 1");
320
+ return parsed;
321
+ };
322
+ const parsePositiveInt = (value) => {
323
+ const parsed = Number(value);
324
+ if (!Number.isInteger(parsed) || parsed < 1) throw new InvalidArgumentError("must be a positive integer");
325
+ return parsed;
326
+ };
327
+ const registerAgentCommand = (program) => {
328
+ const agent = program.command("agent").description("Visual review for coding agents: label changes, hand ambiguous ones to an agent, approve");
329
+ 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);
330
+ 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);
331
+ 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("--json", "print a JSON summary to stdout").action(agentApprove);
332
+ 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("--json", "print a JSON summary to stdout").action(agentInit);
333
+ };
14
334
  //#endregion
15
335
  //#region src/commands/approve.ts
16
336
  const approve = async (options) => {
@@ -47,6 +367,75 @@ const filterScreenshots = (screenshots, filters) => {
47
367
  });
48
368
  };
49
369
  //#endregion
370
+ //#region src/utils/captureReport.ts
371
+ const errorMessage = (error) => {
372
+ if (typeof error === "string") return error;
373
+ if (error instanceof Error) return error.message;
374
+ if (typeof error === "object" && error !== null && typeof error.message === "string") return error.message;
375
+ return String(error);
376
+ };
377
+ /**
378
+ * A task failure that is a broken capture rather than a visual difference.
379
+ *
380
+ * A changed or new screenshot is reported as a failed task too; those are
381
+ * already in `results` with their category, so only the failures that never
382
+ * produced a comparable image belong here.
383
+ */
384
+ const toCaptureError = (failure) => {
385
+ const { result } = failure;
386
+ if (result.error !== void 0 && result.error !== null) return {
387
+ taskId: failure.taskId,
388
+ plugin: failure.pluginName,
389
+ error: errorMessage(result.error)
390
+ };
391
+ if (!result.filepath && result.skipped !== true) return {
392
+ taskId: failure.taskId,
393
+ plugin: failure.pluginName,
394
+ error: "no screenshot was produced"
395
+ };
396
+ };
397
+ const buildCaptureJsonReport = ({ detail, screenshots, durationMs }) => {
398
+ const failures = detail?.failures ?? [];
399
+ const deleted = detail?.deletedScreenshots ?? [];
400
+ const count = (category) => screenshots.filter((s) => s.category === category).length;
401
+ const results = screenshots.filter((s) => s.category !== "passed").map((s) => {
402
+ const origin = s;
403
+ return {
404
+ name: s.name,
405
+ category: s.category,
406
+ ...origin.taskId ? {
407
+ taskId: origin.taskId,
408
+ plugin: origin.plugin
409
+ } : {},
410
+ ...s.diffMeta?.percentDifference !== void 0 ? { percentDifference: s.diffMeta.percentDifference } : {}
411
+ };
412
+ });
413
+ const errors = failures.flatMap((failure) => {
414
+ const error = toCaptureError(failure);
415
+ return error ? [error] : [];
416
+ });
417
+ return {
418
+ ok: failures.length === 0 && deleted.length === 0,
419
+ ...detail ? { runId: detail.id } : {},
420
+ durationMs: Math.round(durationMs),
421
+ tasks: {
422
+ total: detail?.totalTasks ?? 0,
423
+ completed: detail?.completedTasks ?? 0,
424
+ failed: detail?.failedTasks ?? 0
425
+ },
426
+ screenshots: {
427
+ total: screenshots.length,
428
+ passed: count("passed"),
429
+ changed: count("changed"),
430
+ new: count("new"),
431
+ deleted: count("deleted")
432
+ },
433
+ errors,
434
+ results,
435
+ ...results.length > 0 ? { next: "cappa agent check --json" } : {}
436
+ };
437
+ };
438
+ //#endregion
50
439
  //#region src/utils/describeChanges.ts
51
440
  /**
52
441
  * The interpretation fields this reporter actually reads.
@@ -78,23 +467,27 @@ const interpretationSchema = z.object({
78
467
  regions: z.array(regionSchema).catch([]).optional()
79
468
  });
80
469
  const severityColor = (severity) => {
81
- switch (severity) {
82
- case "High": return chalk.red;
83
- case "Medium": return chalk.yellow;
84
- case "Low": return chalk.green;
470
+ switch (severity.toLowerCase()) {
471
+ case "high": return chalk.red;
472
+ case "medium": return chalk.yellow;
473
+ case "low": return chalk.green;
85
474
  default: return chalk.gray;
86
475
  }
87
476
  };
88
- /** Human-readable labels for the `changeType` values reported by blazediff. */
477
+ /**
478
+ * Human-readable labels for the `changeType` values reported by blazediff,
479
+ * keyed by their normalised (kebab-case) form so both `color-change` and the
480
+ * older `ColorChange` resolve.
481
+ */
89
482
  const CHANGE_TYPE_LABELS = {
90
- Addition: "added",
91
- Deletion: "removed",
92
- ColorChange: "color",
93
- ContentChange: "content",
94
- Shift: "shifted",
95
- RenderingNoise: "noise"
96
- };
97
- const changeTypeLabel = (changeType) => CHANGE_TYPE_LABELS[changeType] ?? changeType;
483
+ addition: "added",
484
+ deletion: "removed",
485
+ "color-change": "color",
486
+ "content-change": "content",
487
+ shift: "shifted",
488
+ "rendering-noise": "noise"
489
+ };
490
+ const changeTypeLabel = (changeType) => CHANGE_TYPE_LABELS[normalizeChangeType(changeType)] ?? changeType;
98
491
  /** `content at center · 0.90% · 360x200 at (420, 300)` */
99
492
  const describeRegion = (region) => {
100
493
  const { bbox } = region;
@@ -607,11 +1000,24 @@ async function renderRunToCompletion(engine, runId, onEvent) {
607
1000
  unsubscribe?.();
608
1001
  }
609
1002
  }
1003
+ /**
1004
+ * Print a JSON document and wait until it is flushed: `process.exit` right
1005
+ * after a plain `write` can cut off output that is still queued for a pipe.
1006
+ */
1007
+ const writeJson = (value) => new Promise((resolve) => {
1008
+ process.stdout.write(`${JSON.stringify(value, null, 2)}\n`, () => resolve());
1009
+ });
610
1010
  /** How long a `SIGINT` waits for a remote host to acknowledge cancellation. */
611
1011
  const REMOTE_CANCEL_TIMEOUT_MS = 5e3;
612
1012
  const runCapture = async (options = {}) => {
613
1013
  const logger = getLogger();
614
1014
  const captureStart = performance.now();
1015
+ if (options.json && options.watch) {
1016
+ logger.error("--json cannot be combined with --watch: watch never ends.");
1017
+ process.exit(1);
1018
+ return;
1019
+ }
1020
+ if (options.json) logger.level = Math.min(logger.level, 1);
615
1021
  if (options.watch && options.server) {
616
1022
  logger.error("--watch cannot be combined with --server: a remote host cannot see the files on this machine.");
617
1023
  process.exit(1);
@@ -672,7 +1078,7 @@ const runCapture = async (options = {}) => {
672
1078
  try {
673
1079
  run = await engine.startRun({
674
1080
  filter: options.filter,
675
- clearActual: true
1081
+ clearActual: !options.filter
676
1082
  });
677
1083
  } catch (error) {
678
1084
  if (isRunInProgress(error)) {
@@ -689,7 +1095,7 @@ const runCapture = async (options = {}) => {
689
1095
  detail = await engine.getRun(run.id);
690
1096
  const failedDuringRun = detail?.error !== void 0;
691
1097
  const hasFailure = (detail?.failures.length ?? 0) > 0 || (detail?.deletedScreenshots.length ?? 0) > 0;
692
- if (!failedDuringRun && (isCi || hasFailure)) try {
1098
+ if (!failedDuringRun && (isCi || hasFailure || options.json)) try {
693
1099
  groupedScreenshots = await engine.listScreenshots();
694
1100
  } catch (err) {
695
1101
  logger.warn("Could not collect screenshot results:", err);
@@ -698,11 +1104,32 @@ const runCapture = async (options = {}) => {
698
1104
  unregisterSignalHandlers();
699
1105
  if (!options.watch) await engine.close();
700
1106
  }
701
- if (detail?.error) throw toThrowable(detail.error);
1107
+ if (detail?.error) {
1108
+ if (options.json) {
1109
+ await writeJson({
1110
+ ok: false,
1111
+ runId: detail.id,
1112
+ error: detail.error.message
1113
+ });
1114
+ process.exit(1);
1115
+ return;
1116
+ }
1117
+ throw toThrowable(detail.error);
1118
+ }
702
1119
  const failures = detail?.failures ?? [];
703
1120
  const deletedScreenshots = detail?.deletedScreenshots ?? [];
704
1121
  const hasScreenshotFailure = failures.length > 0 || deletedScreenshots.length > 0;
705
1122
  if (isCi) await executeOnFailCallback(config, groupedScreenshots, { remote });
1123
+ if (options.json) {
1124
+ const report = buildCaptureJsonReport({
1125
+ detail,
1126
+ screenshots: groupedScreenshots,
1127
+ durationMs: performance.now() - captureStart
1128
+ });
1129
+ await writeJson(report);
1130
+ if (!report.ok) process.exit(1);
1131
+ return;
1132
+ }
706
1133
  const duration = formatDuration(performance.now() - captureStart);
707
1134
  if (hasScreenshotFailure) {
708
1135
  const reportMessage = generateFailureReportMessage(failures, deletedScreenshots);
@@ -732,7 +1159,7 @@ const runCapture = async (options = {}) => {
732
1159
  }
733
1160
  };
734
1161
  const registerCaptureCommand = (program) => {
735
- program.command("capture").description("Capture screenshots").option("--ci", "run capture in CI mode and execute onFail callback").option("-f, --filter <pattern>", "only capture tasks whose id matches the given glob pattern").option("--max-regions <count>", "maximum number of interpreted diff regions listed per changed screenshot (0 to disable)", parseMaxRegions, 5).option("--server <url>", "capture against a `cappa serve` host instead of a local browser").option("--token <token>", "access token for --server (falls back to CAPPA_TOKEN)").option("-w, --watch", "capture once, then re-capture affected tasks whenever files change").action(async (options) => {
1162
+ program.command("capture").description("Capture screenshots").option("--ci", "run capture in CI mode and execute onFail callback").option("--json", "print a JSON summary to stdout instead of progress and reports").option("-f, --filter <pattern>", "only capture tasks whose id matches the given glob pattern").option("--max-regions <count>", "maximum number of interpreted diff regions listed per changed screenshot (0 to disable)", parseMaxRegions, 5).option("--server <url>", "capture against a `cappa serve` host instead of a local browser").option("--token <token>", "access token for --server (falls back to CAPPA_TOKEN)").option("-w, --watch", "capture once, then re-capture affected tasks whenever files change").action(async (options) => {
736
1163
  await runCapture(options);
737
1164
  });
738
1165
  };
@@ -860,6 +1287,7 @@ program.command("review").description("Open the review and capture UI").option("
860
1287
  program.command("serve").description("Host a capture engine for a remote `cappa capture --server`").option("-p, --port <port>", "port to listen on", (v) => Number.parseInt(v, 10)).option("--host <host>", "host to bind to (a non-loopback host requires an access token)").option("--read-only", "serve without capture, approval or any other mutation").option("--token <token>", "require this access token on every API request (falls back to CAPPA_TOKEN)").option("--no-ui", "serve the API only, without the review UI").action(serve);
861
1288
  program.command("approve").description("Approve screenshots").option("-f, --filter <filter...>", "only approve screenshots whose name includes the provided filter value(s)").action(approve);
862
1289
  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);
1290
+ registerAgentCommand(program);
863
1291
  program.command("init").description("Initialize Cappa in the current directory").action(init);
864
1292
  async function run() {
865
1293
  await program.parseAsync();