@cappa/core 0.14.0 → 0.16.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.cjs CHANGED
@@ -47,6 +47,7 @@ let _blazediff_core_native = require("@blazediff/core-native");
47
47
  let _blazediff_interpret_native = require("@blazediff/interpret-native");
48
48
  let node_crypto = require("node:crypto");
49
49
  let playwright_core = require("playwright-core");
50
+ let node_child_process = require("node:child_process");
50
51
  //#region src/features/png/util.ts
51
52
  const pngSignature = Buffer.from([
52
53
  137,
@@ -844,6 +845,17 @@ var ScreenshotFileSystem = class {
844
845
  await node_fs_promises.default.writeFile(filepath, data);
845
846
  }
846
847
  /**
848
+ * Remove a screenshot's diff image and metadata sidecar, if any.
849
+ *
850
+ * A run that does not clear `diff/` — a filtered or single-screenshot
851
+ * re-capture — would otherwise leave the previous run's diff behind for a
852
+ * screenshot that now passes, and a screenshot with a diff is `changed`.
853
+ */
854
+ async removeDiffFiles(filename) {
855
+ const filepath = this.getDiffFilePath(filename);
856
+ await Promise.all([node_fs_promises.default.rm(filepath, { force: true }), node_fs_promises.default.rm(toDiffMetaPath(filepath), { force: true })]);
857
+ }
858
+ /**
847
859
  * Get the path to a diff metadata sidecar file (`<name>.json`)
848
860
  */
849
861
  getDiffMetaFilePath(filename) {
@@ -990,6 +1002,91 @@ const recordCaptureOrigins = async (outputDir, origins, knownNames) => {
990
1002
  }
991
1003
  };
992
1004
  //#endregion
1005
+ //#region src/webServer/unreachable.ts
1006
+ /** The advice for a refused connection when the config has no `webServer`. */
1007
+ const NO_WEB_SERVER_HINT = "Start it before capturing, or add a `webServer` entry to cappa.config.ts so cappa starts it for you.";
1008
+ /**
1009
+ * How a refused connection reads, across the places one surfaces: Node's
1010
+ * sockets and `fetch` (`ECONNREFUSED`), Chromium (`net::ERR_CONNECTION_REFUSED`),
1011
+ * Firefox (`NS_ERROR_CONNECTION_REFUSED`) and WebKit.
1012
+ */
1013
+ const REFUSED_PATTERN = /\bECONNREFUSED\b|\bERR_CONNECTION_REFUSED\b|\bNS_ERROR_CONNECTION_REFUSED\b|Could not connect to (?:the )?server|Connection refused/i;
1014
+ const URL_PATTERN = /\bhttps?:\/\/[^\s"'`<>)\]]+/i;
1015
+ const toOrigin = (url) => {
1016
+ try {
1017
+ return new URL(url.replace(/[.,;:!?]+$/, "")).origin;
1018
+ } catch {
1019
+ return;
1020
+ }
1021
+ };
1022
+ /**
1023
+ * Whether `error` — an `Error`, a plain object, or just a message string, as
1024
+ * plugins report task failures — is a refused connection.
1025
+ *
1026
+ * Walks `cause` and `AggregateError.errors`: Node's `fetch` says only
1027
+ * "fetch failed" and puts `ECONNREFUSED` on its cause, and a plugin that wraps
1028
+ * the error in a friendlier one keeps it there too.
1029
+ *
1030
+ * Works on any plugin's errors, third-party included, because it reads the
1031
+ * error rather than asking the plugin.
1032
+ */
1033
+ function findRefusedConnection(error) {
1034
+ let refused = false;
1035
+ let origin;
1036
+ let socketOrigin;
1037
+ const seen = /* @__PURE__ */ new Set();
1038
+ const visit = (value, depth) => {
1039
+ if (value === null || value === void 0 || depth > 8 || seen.has(value)) return;
1040
+ seen.add(value);
1041
+ if (typeof value === "string") {
1042
+ if (REFUSED_PATTERN.test(value)) refused = true;
1043
+ const url = value.match(URL_PATTERN)?.[0];
1044
+ origin ??= url ? toOrigin(url) : void 0;
1045
+ return;
1046
+ }
1047
+ if (typeof value !== "object") return;
1048
+ const record = value;
1049
+ if (record.code === "ECONNREFUSED") {
1050
+ refused = true;
1051
+ if (typeof record.address === "string" && record.port !== void 0) {
1052
+ const host = record.address.includes(":") ? `[${record.address}]` : record.address;
1053
+ socketOrigin ??= `http://${host}:${record.port}`;
1054
+ }
1055
+ }
1056
+ visit(record.message, depth + 1);
1057
+ visit(record.cause, depth + 1);
1058
+ if (Array.isArray(record.errors)) for (const inner of record.errors) visit(inner, depth + 1);
1059
+ };
1060
+ visit(error, 0);
1061
+ if (!refused) return;
1062
+ const resolved = origin ?? socketOrigin;
1063
+ return resolved ? { origin: resolved } : {};
1064
+ }
1065
+ const LOOPBACK_HOSTS = /* @__PURE__ */ new Set([
1066
+ "localhost",
1067
+ "127.0.0.1",
1068
+ "[::1]",
1069
+ "0.0.0.0"
1070
+ ]);
1071
+ /**
1072
+ * Whether two origins name the same server.
1073
+ *
1074
+ * Loopback spellings are interchangeable: a plugin configured with
1075
+ * `localhost:6006` and a socket error reporting `127.0.0.1:6006` are the same
1076
+ * Storybook.
1077
+ */
1078
+ function sameServer(a, b) {
1079
+ try {
1080
+ const left = new URL(a);
1081
+ const right = new URL(b);
1082
+ const port = (url) => url.port || (url.protocol === "https:" ? "443" : "80");
1083
+ if (port(left) !== port(right)) return false;
1084
+ return left.hostname === right.hostname || LOOPBACK_HOSTS.has(left.hostname) && LOOPBACK_HOSTS.has(right.hostname);
1085
+ } catch {
1086
+ return false;
1087
+ }
1088
+ }
1089
+ //#endregion
993
1090
  //#region src/runner/tasks.ts
994
1091
  const isObject = (value) => typeof value === "object" && value !== null;
995
1092
  /**
@@ -1081,6 +1178,8 @@ var CaptureRunner = class {
1081
1178
  outputDir;
1082
1179
  fileSystem;
1083
1180
  now;
1181
+ prepare;
1182
+ explainUnreachable;
1084
1183
  listeners = /* @__PURE__ */ new Set();
1085
1184
  controller = new AbortController();
1086
1185
  seq = 0;
@@ -1110,6 +1209,8 @@ var CaptureRunner = class {
1110
1209
  this.fileSystem = options.fileSystem ?? options.screenshotTool.filesystem ?? new ScreenshotFileSystem(this.outputDir);
1111
1210
  this.id = options.id ?? (0, node_crypto.randomUUID)();
1112
1211
  this.now = options.now ?? (() => Date.now());
1212
+ this.prepare = options.prepare;
1213
+ this.explainUnreachable = options.explainUnreachable ?? (() => "Start it before capturing, or add a `webServer` entry to cappa.config.ts so cappa starts it for you.");
1113
1214
  }
1114
1215
  /** Subscribe to run events. Returns an unsubscribe function. */
1115
1216
  on(listener) {
@@ -1198,6 +1299,10 @@ var CaptureRunner = class {
1198
1299
  this.attachToolCaptureSink();
1199
1300
  try {
1200
1301
  try {
1302
+ if (this.prepare) {
1303
+ this.state = "discovering";
1304
+ await this.prepare((level, message) => this.log(level, message));
1305
+ }
1201
1306
  if (request.clearActual ?? true) {
1202
1307
  this.log("debug", `Cleaning output directory: ${this.outputDir}`);
1203
1308
  this.fileSystem.clearActual();
@@ -1205,7 +1310,8 @@ var CaptureRunner = class {
1205
1310
  }
1206
1311
  const pluginTasks = await this.discover(request);
1207
1312
  if (!this.controller.signal.aborted) await this.execute(pluginTasks);
1208
- } catch (error) {
1313
+ } catch (thrown) {
1314
+ const error = this.toUnreachableError(thrown) ?? thrown;
1209
1315
  this.error = error;
1210
1316
  this.state = "failed";
1211
1317
  this.finishedAt = this.now();
@@ -1383,6 +1489,7 @@ var CaptureRunner = class {
1383
1489
  }
1384
1490
  const durationMs = this.now() - taskStart;
1385
1491
  completedTasks++;
1492
+ result = this.explainTaskError(result);
1386
1493
  const failed = didScreenshotFail(result);
1387
1494
  const status = toTaskStatus(result);
1388
1495
  const typedResult = result;
@@ -1421,6 +1528,36 @@ var CaptureRunner = class {
1421
1528
  });
1422
1529
  }
1423
1530
  }
1531
+ /**
1532
+ * The message for a refused connection: where, and what to do about it.
1533
+ *
1534
+ * Identical for every task that hit the same server — no task id, no path —
1535
+ * so a report can collapse 300 of them into one line.
1536
+ */
1537
+ unreachableMessage(origin) {
1538
+ return `Cannot reach ${origin ?? "the app under test"}: connection refused. ${this.explainUnreachable(origin)}`;
1539
+ }
1540
+ toUnreachableError(error) {
1541
+ const refused = findRefusedConnection(error);
1542
+ if (!refused) return;
1543
+ return new Error(this.unreachableMessage(refused.origin), { cause: error });
1544
+ }
1545
+ /**
1546
+ * Replace a plugin's refused-connection error with the explained one.
1547
+ *
1548
+ * Reads the result rather than asking the plugin, so third-party plugins get
1549
+ * the same message without an API change.
1550
+ */
1551
+ explainTaskError(result) {
1552
+ const error = result?.error;
1553
+ if (error === void 0 || error === null) return result;
1554
+ const refused = findRefusedConnection(error);
1555
+ if (!refused) return result;
1556
+ return {
1557
+ ...result,
1558
+ error: this.unreachableMessage(refused.origin)
1559
+ };
1560
+ }
1424
1561
  async collectDeleted() {
1425
1562
  if (!this.anyTasksRan) return;
1426
1563
  try {
@@ -1857,6 +1994,7 @@ var ScreenshotTool = class {
1857
1994
  const saveDiff = extras.saveDiffImage ?? false;
1858
1995
  const diffFilename = extras.diffImageFilename ?? filename;
1859
1996
  const diffOverride = extras.diff;
1997
+ await this.filesystem.removeDiffFiles(diffFilename);
1860
1998
  if (!await this.filesystem.hasExpectedFile(filename)) {
1861
1999
  this.logger.debug(`Expected image not found for ${filename}, taking screenshot`);
1862
2000
  result.filepath = await this.takeScreenshot(page, filename, options);
@@ -2056,6 +2194,204 @@ var ScreenshotTool = class {
2056
2194
  }
2057
2195
  };
2058
2196
  //#endregion
2197
+ //#region src/agent/paths.ts
2198
+ /**
2199
+ * Where agent review keeps its state, inside `outputDir`.
2200
+ *
2201
+ * Its own module so screenshot collection can read the report without
2202
+ * importing the review pipeline, which itself collects screenshots.
2203
+ */
2204
+ const AGENT_DIRNAME = ".cappa-agent";
2205
+ /** Bumped only if `request.json` or `report.json` change incompatibly. */
2206
+ const AGENT_REPORT_VERSION = 1;
2207
+ const agentDir = (outputDir) => node_path.default.resolve(outputDir, AGENT_DIRNAME);
2208
+ const judgmentsRoot = (outputDir) => node_path.default.join(agentDir(outputDir), "judgments");
2209
+ const agentReportPath = (outputDir) => node_path.default.join(agentDir(outputDir), "report.json");
2210
+ //#endregion
2211
+ //#region src/agent/verdict.ts
2212
+ /**
2213
+ * What a reviewer — heuristic or agent — believes a changed screenshot is.
2214
+ *
2215
+ * `ambiguous` is only ever produced by the heuristic: it is the signal that
2216
+ * the change has to be looked at, and an agent's verdict must resolve it into
2217
+ * one of the other three.
2218
+ */
2219
+ const VERDICT_LABELS = [
2220
+ "regression-likely",
2221
+ "intentional-likely",
2222
+ "noise-likely",
2223
+ "ambiguous"
2224
+ ];
2225
+ /** The labels a judge may hand back — everything but `ambiguous`. */
2226
+ const JUDGED_LABELS = [
2227
+ "regression-likely",
2228
+ "intentional-likely",
2229
+ "noise-likely"
2230
+ ];
2231
+ const ACTION_BY_LABEL = {
2232
+ "regression-likely": "investigate",
2233
+ "intentional-likely": "approve-if-intended",
2234
+ "noise-likely": "mask-or-approve",
2235
+ ambiguous: "investigate"
2236
+ };
2237
+ const isVerdictLabel = (value) => typeof value === "string" && VERDICT_LABELS.includes(value);
2238
+ const isJudgedLabel = (value) => typeof value === "string" && JUDGED_LABELS.includes(value);
2239
+ /**
2240
+ * Change types are normalised to kebab-case before they are compared.
2241
+ *
2242
+ * `@blazediff/interpret-native` reports `color-change` today but earlier
2243
+ * releases reported `ColorChange`; normalising keeps the heuristic working
2244
+ * across a diff-engine upgrade instead of silently degrading every screenshot
2245
+ * to `ambiguous`.
2246
+ */
2247
+ const normalizeChangeType = (changeType) => changeType.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/[\s_]+/g, "-").toLowerCase();
2248
+ const normalizeSeverity = (severity) => (severity ?? "").toLowerCase();
2249
+ /** Structural: something appeared, vanished or was replaced. */
2250
+ const REGRESSIVE_TYPES = /* @__PURE__ */ new Set([
2251
+ "content-change",
2252
+ "addition",
2253
+ "deletion"
2254
+ ]);
2255
+ /** Restyled or moved, with structure intact. */
2256
+ const RESTYLE_TYPES = /* @__PURE__ */ new Set(["color-change", "shift"]);
2257
+ const NOISE_TYPES = /* @__PURE__ */ new Set(["rendering-noise"]);
2258
+ const ELEVATED_SEVERITY = /* @__PURE__ */ new Set(["medium", "high"]);
2259
+ /** Below this share of the image, a low-severity change is not perceptible. */
2260
+ const SUB_PERCEPTUAL_PERCENT = .01;
2261
+ /** Mean region confidence above which a pure recolour is trusted. */
2262
+ const RECOLOR_CONFIDENCE = .7;
2263
+ const formatPercent = (percent) => {
2264
+ if (percent === void 0) return "?%";
2265
+ return percent >= .01 ? `${percent.toFixed(2)}%` : `${percent.toFixed(3)}%`;
2266
+ };
2267
+ const countByType = (regions) => {
2268
+ const counts = /* @__PURE__ */ new Map();
2269
+ for (const region of regions) {
2270
+ const type = normalizeChangeType(region.changeType);
2271
+ counts.set(type, (counts.get(type) ?? 0) + 1);
2272
+ }
2273
+ return counts;
2274
+ };
2275
+ const formatBreakdown = (counts) => [...counts].sort((a, b) => b[1] - a[1]).map(([type, count]) => `${count} ${type}`).join(", ");
2276
+ const largestRegion = (regions) => regions.reduce((best, region) => !best || region.pixelCount > best.pixelCount ? region : best, void 0);
2277
+ const meanConfidence = (regions) => regions.length === 0 ? 0 : regions.reduce((sum, region) => sum + (region.confidence ?? 0), 0) / regions.length;
2278
+ /**
2279
+ * A one-line description of a change, shaped so that the same kind of change
2280
+ * on different screenshots produces the same headline — which is what lets an
2281
+ * agent spot one shared cause (a footer timestamp, a theme toggle) across
2282
+ * dozens of screenshots without opening any of them.
2283
+ */
2284
+ const buildHeadline = (input) => {
2285
+ if (input.differentSizes) return "image dimensions changed";
2286
+ const interpretation = input.interpretation;
2287
+ const percent = input.percentDifference ?? interpretation?.diffPercentage;
2288
+ if (!interpretation || interpretation.regions.length === 0) return `${(input.numDiffPixels ?? interpretation?.diffCount)?.toLocaleString("en-US") ?? "?"} px (${formatPercent(percent)}) - no region analysis`;
2289
+ const regions = interpretation.regions;
2290
+ const counts = countByType(regions);
2291
+ const position = largestRegion(regions)?.position;
2292
+ const at = position ? ` @ ${position}` : "";
2293
+ const severity = normalizeSeverity(interpretation.severity) || "?";
2294
+ if (regions.length === 1) return `1 ${[...counts.keys()][0]}${at} (${formatPercent(percent)}, ${severity})`;
2295
+ return `${regions.length} regions: ${formatBreakdown(counts)}${at} (${formatPercent(percent)}, ${severity})`;
2296
+ };
2297
+ const verdict = (label, headline, rationale) => ({
2298
+ label,
2299
+ headline,
2300
+ rationale,
2301
+ action: ACTION_BY_LABEL[label]
2302
+ });
2303
+ /**
2304
+ * Classify a changed screenshot from its diff interpretation alone.
2305
+ *
2306
+ * Deliberately conservative: only the cases the signals settle are labelled,
2307
+ * and everything else is `ambiguous` so that it reaches a judge who can look
2308
+ * at the pixels. A wrong `noise-likely` hides a regression; a wrong
2309
+ * `ambiguous` costs one look.
2310
+ */
2311
+ const deriveVerdict = (input) => {
2312
+ const headline = buildHeadline(input);
2313
+ if (input.differentSizes) return verdict("ambiguous", headline, ["expected and actual have different dimensions — content likely grew or shrank", "could be an intended content change or a broken layout"]);
2314
+ const interpretation = input.interpretation;
2315
+ if (!interpretation || interpretation.regions.length === 0) return verdict("ambiguous", headline, ["pixels differ but no change regions were found"]);
2316
+ const regions = interpretation.regions;
2317
+ const types = regions.map((region) => normalizeChangeType(region.changeType));
2318
+ const severity = normalizeSeverity(interpretation.severity);
2319
+ const percent = input.percentDifference ?? interpretation.diffPercentage;
2320
+ const counts = countByType(regions);
2321
+ if (types.every((type) => NOISE_TYPES.has(type))) return verdict("noise-likely", headline, ["every region is classified as rendering noise"]);
2322
+ if (percent < .01 && severity === "low") return verdict("noise-likely", headline, [`less than ${SUB_PERCEPTUAL_PERCENT}% of the image differs (${formatPercent(percent)}) at low severity`, "sub-perceptual change"]);
2323
+ if (types.some((type) => REGRESSIVE_TYPES.has(type)) && ELEVATED_SEVERITY.has(severity)) {
2324
+ const structural = [...counts].filter(([type]) => REGRESSIVE_TYPES.has(type)).map(([type, count]) => `${count} ${type}`).join(", ");
2325
+ return verdict("regression-likely", headline, [`${severity} severity with structural changes (${structural})`, "content or layout changed, not just styling"]);
2326
+ }
2327
+ const allRecolor = types.every((type) => type === "color-change");
2328
+ if (allRecolor && meanConfidence(regions) > RECOLOR_CONFIDENCE) return verdict("intentional-likely", headline, [`${regions.length} confident color-change ${regions.length === 1 ? "region" : "regions"}`, "edge structure preserved — looks like a theming or palette change"]);
2329
+ if (!allRecolor && types.every((type) => RESTYLE_TYPES.has(type))) return verdict("intentional-likely", headline, ["every region is a shift or color change — content moved or was restyled, structure preserved"]);
2330
+ return verdict("ambiguous", headline, [`mix of change types (${formatBreakdown(counts)}) at ${severity || "unknown"} severity`, `${formatPercent(percent)} of the image differs`]);
2331
+ };
2332
+ //#endregion
2333
+ //#region src/agent/reviewIndex.ts
2334
+ /**
2335
+ * Read the review index, or nothing.
2336
+ *
2337
+ * Never throws: like the capture manifest, the report is an extra, and a
2338
+ * missing or hand-edited file must not break the screenshot listing.
2339
+ */
2340
+ const readAgentReviewIndex = async (outputDir) => {
2341
+ let raw;
2342
+ try {
2343
+ raw = JSON.parse(await node_fs_promises.default.readFile(agentReportPath(outputDir), "utf8"));
2344
+ } catch {
2345
+ return;
2346
+ }
2347
+ const createdAt = typeof raw?.createdAt === "string" ? Date.parse(raw.createdAt) : NaN;
2348
+ if (raw?.version !== 1 || Number.isNaN(createdAt) || !Array.isArray(raw.entries)) return;
2349
+ const reviews = /* @__PURE__ */ new Map();
2350
+ for (const entry of raw.entries) {
2351
+ if (typeof entry !== "object" || entry === null) continue;
2352
+ const { name, category, verdict, pending } = entry;
2353
+ if (typeof name !== "string" || category !== "changed") continue;
2354
+ if (typeof verdict !== "object" || verdict === null) continue;
2355
+ const v = verdict;
2356
+ if (!isVerdictLabel(v.label) || typeof v.headline !== "string") continue;
2357
+ reviews.set(name, {
2358
+ label: v.label,
2359
+ headline: v.headline,
2360
+ rationale: Array.isArray(v.rationale) ? v.rationale.filter((line) => typeof line === "string") : [],
2361
+ action: v.action,
2362
+ source: v.source === "agent" ? "agent" : "heuristic",
2363
+ ...typeof v.confidence === "number" ? { confidence: v.confidence } : {},
2364
+ pending: pending === true,
2365
+ reviewedAt: new Date(createdAt).toISOString()
2366
+ });
2367
+ }
2368
+ return {
2369
+ createdAt,
2370
+ reviews
2371
+ };
2372
+ };
2373
+ const modifiedAt = async (file) => {
2374
+ try {
2375
+ return (await node_fs_promises.default.stat(file)).mtimeMs;
2376
+ } catch {
2377
+ return Number.POSITIVE_INFINITY;
2378
+ }
2379
+ };
2380
+ /**
2381
+ * The review for a changed screenshot, if it is still about these images.
2382
+ *
2383
+ * A capture after the check rewrites `actual/`, an approval rewrites
2384
+ * `expected/`; either makes the verdict describe pixels that are gone. File
2385
+ * times are compared rather than content hashed because this runs on every
2386
+ * listing the review UI makes.
2387
+ */
2388
+ const freshAgentReview = async (index, outputDir, screenshot) => {
2389
+ const review = index?.reviews.get(screenshot.name);
2390
+ if (!index || !review) return void 0;
2391
+ const [actual, expected] = await Promise.all([modifiedAt(node_path.default.resolve(outputDir, screenshot.actualPath)), modifiedAt(node_path.default.resolve(outputDir, screenshot.expectedPath))]);
2392
+ return actual <= index.createdAt && expected <= index.createdAt ? review : void 0;
2393
+ };
2394
+ //#endregion
2059
2395
  //#region src/screenshots/groupScreenshots.ts
2060
2396
  const groupScreenshots = async (actualScreenshots, expectedScreenshots, diffScreenshots, outputDir) => {
2061
2397
  const screenshotRepresentations = [];
@@ -2125,23 +2461,431 @@ const listPngs = async (dir) => Array.fromAsync(await (0, node_fs_promises.glob)
2125
2461
  *
2126
2462
  * The capture manifest is folded in here so every consumer — the CLI, the
2127
2463
  * server, the review UI — sees the same `taskId`, and so a screenshot captured
2128
- * before manifests existed simply has none rather than a wrong one.
2464
+ * before manifests existed simply has none rather than a wrong one. The last
2465
+ * `cappa agent check` verdict is folded in the same way, as `review`, while it
2466
+ * still describes the images on disk.
2129
2467
  */
2130
2468
  const collectScreenshots = async (outputDir) => {
2131
- const [actualScreenshots, expectedScreenshots, diffScreenshots, manifest] = await Promise.all([
2469
+ const [actualScreenshots, expectedScreenshots, diffScreenshots, manifest, reviewIndex] = await Promise.all([
2132
2470
  listPngs(node_path.default.resolve(outputDir, "actual")),
2133
2471
  listPngs(node_path.default.resolve(outputDir, "expected")),
2134
2472
  listPngs(node_path.default.resolve(outputDir, "diff")),
2135
- readCaptureManifest(outputDir)
2473
+ readCaptureManifest(outputDir),
2474
+ readAgentReviewIndex(outputDir)
2136
2475
  ]);
2137
- return (await groupScreenshots(actualScreenshots, expectedScreenshots, diffScreenshots, outputDir)).map((screenshot) => {
2476
+ const screenshots = await groupScreenshots(actualScreenshots, expectedScreenshots, diffScreenshots, outputDir);
2477
+ return Promise.all(screenshots.map(async (screenshot) => {
2138
2478
  const origin = manifest.screenshots[screenshot.name];
2139
- return origin ? {
2479
+ const withOrigin = origin ? {
2140
2480
  ...screenshot,
2141
2481
  taskId: origin.taskId,
2142
2482
  plugin: origin.plugin
2143
2483
  } : screenshot;
2484
+ if (withOrigin.category !== "changed" || !reviewIndex) return withOrigin;
2485
+ const review = await freshAgentReview(reviewIndex, outputDir, withOrigin);
2486
+ return review ? {
2487
+ ...withOrigin,
2488
+ review
2489
+ } : withOrigin;
2490
+ }));
2491
+ };
2492
+ //#endregion
2493
+ //#region src/webServer/process.ts
2494
+ /** Grace period between SIGTERM and SIGKILL. */
2495
+ const DEFAULT_KILL_GRACE_MS = 5e3;
2496
+ /** How long to wait for the kernel to reap a SIGKILLed group. */
2497
+ const SIGKILL_WAIT_MS = 2e3;
2498
+ const isWindows = process.platform === "win32";
2499
+ /**
2500
+ * The last part of a process's output, kept in memory.
2501
+ *
2502
+ * Bounded by bytes rather than lines: a dev server that prints one enormous
2503
+ * line is no reason to hold on to all of it, and the tail exists to explain a
2504
+ * failure, not to be a log.
2505
+ */
2506
+ var OutputTail = class {
2507
+ maxBytes;
2508
+ chunks = [];
2509
+ size = 0;
2510
+ constructor(maxBytes = 65536) {
2511
+ this.maxBytes = maxBytes;
2512
+ }
2513
+ push(chunk) {
2514
+ this.chunks.push(chunk);
2515
+ this.size += chunk.length;
2516
+ while (this.size > this.maxBytes && this.chunks.length > 1) this.size -= this.chunks.shift()?.length ?? 0;
2517
+ }
2518
+ /** The last `maxLines` non-empty lines. */
2519
+ lines(maxLines = 30) {
2520
+ return this.chunks.join("").split(/\r?\n/).filter((line) => line.trim() !== "").slice(-maxLines);
2521
+ }
2522
+ };
2523
+ /**
2524
+ * Process groups this process started and has not stopped yet.
2525
+ *
2526
+ * Exists for the one exit no `close()` covers: the process leaving without
2527
+ * shutting down. A server left running holds its port, and the next run would
2528
+ * silently *reuse* it — a stale build answering for the current one.
2529
+ */
2530
+ const liveProcesses = /* @__PURE__ */ new Set();
2531
+ let exitHookInstalled = false;
2532
+ const installExitHook = () => {
2533
+ if (exitHookInstalled) return;
2534
+ exitHookInstalled = true;
2535
+ process.on("exit", () => {
2536
+ for (const child of liveProcesses) killTreeNow(child);
2537
+ liveProcesses.clear();
2538
+ });
2539
+ };
2540
+ const killTreeNow = (child) => {
2541
+ if (child.pid === void 0) return;
2542
+ try {
2543
+ if (isWindows) (0, node_child_process.execFileSync)("taskkill", [
2544
+ "/pid",
2545
+ String(child.pid),
2546
+ "/T",
2547
+ "/F"
2548
+ ], { stdio: "ignore" });
2549
+ else process.kill(-child.pid, "SIGKILL");
2550
+ } catch {}
2551
+ };
2552
+ /**
2553
+ * Start `command` through a shell, as the leader of its own process group.
2554
+ *
2555
+ * A group, because the command is rarely the server itself: `pnpm storybook`
2556
+ * is pnpm, running a shell, running storybook, running workers. Killing only
2557
+ * the direct child would leave the rest holding the port.
2558
+ *
2559
+ * Output is buffered, never written anywhere unless `onOutput` asks for it —
2560
+ * `cappa capture --json` must stay a single clean document on stdout.
2561
+ */
2562
+ function spawnServerProcess(command, options) {
2563
+ const child = (0, node_child_process.spawn)(command, {
2564
+ cwd: options.cwd,
2565
+ env: {
2566
+ ...process.env,
2567
+ ...options.env
2568
+ },
2569
+ shell: true,
2570
+ detached: !isWindows,
2571
+ stdio: [
2572
+ "ignore",
2573
+ "pipe",
2574
+ "pipe"
2575
+ ],
2576
+ windowsHide: true
2144
2577
  });
2578
+ const output = new OutputTail();
2579
+ const onData = (data) => {
2580
+ const chunk = data.toString();
2581
+ output.push(chunk);
2582
+ options.onOutput?.(chunk);
2583
+ };
2584
+ child.stdout?.on("data", onData);
2585
+ child.stderr?.on("data", onData);
2586
+ liveProcesses.add(child);
2587
+ installExitHook();
2588
+ let exit;
2589
+ const exited = new Promise((resolve) => {
2590
+ const settle = (value) => {
2591
+ if (exit) return;
2592
+ exit = value;
2593
+ resolve(value);
2594
+ };
2595
+ child.once("exit", (code, signal) => settle({
2596
+ code,
2597
+ signal
2598
+ }));
2599
+ child.once("error", (error) => {
2600
+ output.push(`${error.message}\n`);
2601
+ settle({
2602
+ code: null,
2603
+ signal: null
2604
+ });
2605
+ });
2606
+ });
2607
+ let killing;
2608
+ return {
2609
+ get pid() {
2610
+ return child.pid;
2611
+ },
2612
+ exited,
2613
+ get exit() {
2614
+ return exit;
2615
+ },
2616
+ output,
2617
+ kill(graceMs = DEFAULT_KILL_GRACE_MS) {
2618
+ killing ??= killProcessTree(child, exited, graceMs).finally(() => {
2619
+ liveProcesses.delete(child);
2620
+ });
2621
+ return killing;
2622
+ }
2623
+ };
2624
+ }
2625
+ /** True while any process in the group led by `pid` is alive. */
2626
+ const groupAlive = (pid) => {
2627
+ try {
2628
+ process.kill(-pid, 0);
2629
+ return true;
2630
+ } catch (error) {
2631
+ return error.code === "EPERM";
2632
+ }
2633
+ };
2634
+ const delay = (ms) => new Promise((resolve) => {
2635
+ setTimeout(resolve, ms);
2636
+ });
2637
+ /**
2638
+ * SIGTERM the whole group, then SIGKILL whatever is left after `graceMs`.
2639
+ *
2640
+ * Waits on the group, not the child: the shell can exit at once while the
2641
+ * server it started is still shutting down — and still holding the port.
2642
+ */
2643
+ async function killProcessTree(child, exited, graceMs) {
2644
+ const pid = child.pid;
2645
+ if (pid === void 0) return;
2646
+ if (isWindows) {
2647
+ await new Promise((resolve) => {
2648
+ (0, node_child_process.execFile)("taskkill", [
2649
+ "/pid",
2650
+ String(pid),
2651
+ "/T",
2652
+ "/F"
2653
+ ], () => resolve());
2654
+ });
2655
+ await exited;
2656
+ return;
2657
+ }
2658
+ if (!groupAlive(pid)) return;
2659
+ try {
2660
+ process.kill(-pid, "SIGTERM");
2661
+ } catch {
2662
+ return;
2663
+ }
2664
+ const deadline = Date.now() + graceMs;
2665
+ while (groupAlive(pid) && Date.now() < deadline) await delay(50);
2666
+ if (groupAlive(pid)) {
2667
+ try {
2668
+ process.kill(-pid, "SIGKILL");
2669
+ } catch {}
2670
+ const killDeadline = Date.now() + SIGKILL_WAIT_MS;
2671
+ while (groupAlive(pid) && Date.now() < killDeadline) await delay(20);
2672
+ }
2673
+ await exited;
2674
+ }
2675
+ //#endregion
2676
+ //#region src/webServer/readiness.ts
2677
+ const PROBE_TIMEOUT_MS = 5e3;
2678
+ /** Delays between probes; the last one repeats. */
2679
+ const POLL_DELAYS_MS = [
2680
+ 100,
2681
+ 250,
2682
+ 500,
2683
+ 1e3
2684
+ ];
2685
+ /**
2686
+ * Whether `url` answers with a 2xx or 3xx status.
2687
+ *
2688
+ * Redirects are not followed: a dev server that redirects `/` to `/login` is
2689
+ * up, and following it would make readiness depend on a page cappa never asked
2690
+ * about.
2691
+ */
2692
+ async function isUrlReady(url, timeoutMs = PROBE_TIMEOUT_MS) {
2693
+ try {
2694
+ const response = await fetch(url, {
2695
+ redirect: "manual",
2696
+ signal: AbortSignal.timeout(Math.max(1, timeoutMs))
2697
+ });
2698
+ await response.body?.cancel().catch(() => {});
2699
+ return response.status >= 200 && response.status < 400;
2700
+ } catch {
2701
+ return false;
2702
+ }
2703
+ }
2704
+ /** Poll `url` until it is ready, the deadline passes, or `abort` settles. */
2705
+ async function waitForUrl(url, options) {
2706
+ const probe = options.probe ?? isUrlReady;
2707
+ const deadline = Date.now() + options.timeoutMs;
2708
+ let aborted = false;
2709
+ const abort = (options.abort ?? new Promise(() => {})).then(() => {
2710
+ aborted = true;
2711
+ }, () => {
2712
+ aborted = true;
2713
+ });
2714
+ for (let attempt = 0;; attempt++) {
2715
+ const remaining = deadline - Date.now();
2716
+ if (aborted) return "aborted";
2717
+ if (remaining <= 0) return "timeout";
2718
+ if (await probe(url, Math.min(remaining, PROBE_TIMEOUT_MS))) return "ready";
2719
+ const wait = Math.min(POLL_DELAYS_MS[Math.min(attempt, POLL_DELAYS_MS.length - 1)] ?? 1e3, Math.max(0, deadline - Date.now()));
2720
+ let timer;
2721
+ await Promise.race([new Promise((resolve) => {
2722
+ timer = setTimeout(resolve, wait);
2723
+ }), abort]);
2724
+ clearTimeout(timer);
2725
+ }
2726
+ }
2727
+ //#endregion
2728
+ //#region src/webServer/WebServerPool.ts
2729
+ /** A web server could not be started, or would not become ready. */
2730
+ var WebServerError = class extends Error {
2731
+ constructor(message) {
2732
+ super(message);
2733
+ this.name = "WebServerError";
2734
+ }
2735
+ };
2736
+ const describeExit = (exit) => exit.signal ? `signal ${exit.signal}` : exit.code === null ? "an error" : `code ${exit.code}`;
2737
+ const formatTail = (command, lines) => lines.length === 0 ? `\`${command}\` printed nothing.` : `Last output of \`${command}\`:\n${lines.map((line) => ` ${line}`).join("\n")}`;
2738
+ const seconds = (ms) => `${Math.round(ms / 100) / 10}s`;
2739
+ /**
2740
+ * The servers a config's `webServer` describes, started on demand.
2741
+ *
2742
+ * Lazy and restartable rather than started once: the owning engine calls
2743
+ * `ensure` before every run and `stop` when the browser goes idle, so a review
2744
+ * session that sits unused gives the port back, and the next capture starts —
2745
+ * and rebuilds — the app again, picking up whatever changed in between.
2746
+ *
2747
+ * Every `ensure` says which way it went, because "reusing a server" and
2748
+ * "started one" look identical in screenshots, and a stale build, another
2749
+ * branch or another project on the same port is otherwise very hard to spot.
2750
+ */
2751
+ var WebServerPool = class {
2752
+ entries;
2753
+ options;
2754
+ probe;
2755
+ /** Bumped by `stop`, so a start in flight knows it was cancelled. */
2756
+ generation = 0;
2757
+ constructor(options) {
2758
+ this.options = options;
2759
+ this.probe = options.probe ?? isUrlReady;
2760
+ this.entries = options.servers.map((config) => ({
2761
+ config,
2762
+ state: { kind: "idle" },
2763
+ starting: null
2764
+ }));
2765
+ }
2766
+ /** Whether the config has any `webServer` entry at all. */
2767
+ get configured() {
2768
+ return this.entries.length > 0;
2769
+ }
2770
+ /** Number of processes cappa started that are still running. */
2771
+ get running() {
2772
+ return this.entries.filter((entry) => entry.state.kind === "running" && !entry.state.process.exit).length;
2773
+ }
2774
+ /**
2775
+ * Make every server ready, in parallel, starting the ones that are not.
2776
+ *
2777
+ * All of them, even for a run that only captures one plugin's tasks: nothing
2778
+ * maps a plugin to a server, and guessing would start the wrong one.
2779
+ */
2780
+ async ensure(log = this.defaultLog) {
2781
+ if (this.entries.length === 0) return;
2782
+ const errors = (await Promise.allSettled(this.entries.map((entry) => this.ensureEntry(entry, log)))).flatMap((result) => result.status === "rejected" ? [result.reason] : []);
2783
+ if (errors.length === 1) throw errors[0];
2784
+ if (errors.length > 1) throw new WebServerError(errors.map((error) => error instanceof Error ? error.message : error).join("\n\n"));
2785
+ }
2786
+ /**
2787
+ * Stop every server cappa started. A reused server is left alone — cappa did
2788
+ * not start it, so it is not cappa's to stop.
2789
+ */
2790
+ async stop() {
2791
+ this.generation += 1;
2792
+ await Promise.all(this.entries.map(async (entry) => {
2793
+ const state = entry.state;
2794
+ entry.state = { kind: "idle" };
2795
+ if (state.kind === "running") await state.process.kill(this.options.killGraceMs);
2796
+ }));
2797
+ }
2798
+ /**
2799
+ * What to tell the user about a connection refused at `origin`.
2800
+ *
2801
+ * Always an actionable sentence: the bare "ECONNREFUSED" it replaces is the
2802
+ * single most common capture failure, and says nothing about what to do.
2803
+ */
2804
+ explainUnreachable(origin) {
2805
+ if (this.entries.length === 0) return NO_WEB_SERVER_HINT;
2806
+ const matching = origin ? this.entries.find((entry) => sameServer(entry.config.url, origin)) : void 0;
2807
+ const crashed = matching?.state.kind === "exited" ? matching : this.entries.find((entry) => entry.state.kind === "exited");
2808
+ if (crashed && crashed.state.kind === "exited") return `The web server \`${crashed.config.command}\` exited with ${describeExit(crashed.state.exit)} during the run; it is started again on the next run.\n${formatTail(crashed.config.command, crashed.state.tail)}`;
2809
+ if (origin && !matching) return `No \`webServer\` entry serves ${origin} (configured: ${this.entries.map((entry) => entry.config.url).join(", ")}). Check that the plugin's URL matches \`webServer.url\`.`;
2810
+ return "The configured `webServer` was ready, but stopped accepting connections.";
2811
+ }
2812
+ defaultLog = (level, message) => {
2813
+ this.options.log?.(level, message);
2814
+ };
2815
+ ensureEntry(entry, log) {
2816
+ entry.starting ??= this.startEntry(entry, log).finally(() => {
2817
+ entry.starting = null;
2818
+ });
2819
+ return entry.starting;
2820
+ }
2821
+ async startEntry(entry, log) {
2822
+ const { command, url, timeout, cwd, env, reuseExistingServer } = entry.config;
2823
+ const previous = entry.state;
2824
+ if (previous.kind === "running" && !previous.process.exit) {
2825
+ log("info", `Using \`${command}\` at ${url}, started earlier by cappa`);
2826
+ return;
2827
+ }
2828
+ if (previous.kind === "exited") log("warn", `\`${command}\` exited with ${describeExit(previous.exit)} after the last run; starting it again`);
2829
+ if (await this.probe(url, Math.min(timeout, 5e3))) {
2830
+ if (reuseExistingServer) {
2831
+ entry.state = { kind: "reused" };
2832
+ log("info", `Reusing server at ${url} — \`${command}\` was not run`);
2833
+ return;
2834
+ }
2835
+ throw new WebServerError(`${url} is already in use, and \`webServer.reuseExistingServer\` is false. Stop whatever is serving it, or allow reusing it.`);
2836
+ }
2837
+ const generation = this.generation;
2838
+ const startedAt = Date.now();
2839
+ log("info", `Starting \`${command}\` — waiting up to ${seconds(timeout)} for ${url}`);
2840
+ const child = (this.options.spawn ?? spawnServerProcess)(command, {
2841
+ cwd,
2842
+ env,
2843
+ onOutput: this.options.onOutput ? (chunk) => this.options.onOutput?.(entry.config, chunk) : void 0
2844
+ });
2845
+ entry.state = {
2846
+ kind: "running",
2847
+ process: child
2848
+ };
2849
+ const result = await waitForUrl(url, {
2850
+ timeoutMs: timeout,
2851
+ abort: child.exited,
2852
+ probe: this.probe
2853
+ });
2854
+ if (generation !== this.generation) {
2855
+ await child.kill(this.options.killGraceMs);
2856
+ throw new WebServerError(`\`${command}\` was stopped before ${url} was ready.`);
2857
+ }
2858
+ if (result === "ready") {
2859
+ this.watchForCrash(entry, child);
2860
+ log("success", `Started \`${command}\` — ${url} ready in ${seconds(Date.now() - startedAt)}`);
2861
+ return;
2862
+ }
2863
+ entry.state = { kind: "idle" };
2864
+ if (result === "aborted") {
2865
+ const exit = await child.exited;
2866
+ throw new WebServerError(`\`${command}\` exited with ${describeExit(exit)} before ${url} was ready.\n${formatTail(command, child.output.lines())}`);
2867
+ }
2868
+ await child.kill(this.options.killGraceMs);
2869
+ throw new WebServerError(`Timed out after ${seconds(timeout)} waiting for \`${command}\` to serve ${url}. If it needs longer — a build step, say — raise \`webServer.timeout\`.\n${formatTail(command, child.output.lines())}`);
2870
+ }
2871
+ /**
2872
+ * Record a server that exits on its own, so the failures it causes can say
2873
+ * why and the next run starts it again. Deliberately no restart loop: a
2874
+ * server that keeps crashing should fail loudly, not flap.
2875
+ */
2876
+ watchForCrash(entry, child) {
2877
+ child.exited.then((exit) => {
2878
+ const state = entry.state;
2879
+ if (state.kind !== "running" || state.process !== child) return;
2880
+ entry.state = {
2881
+ kind: "exited",
2882
+ exit,
2883
+ tail: child.output.lines()
2884
+ };
2885
+ child.kill(this.options.killGraceMs);
2886
+ this.defaultLog("error", `\`${entry.config.command}\` exited with ${describeExit(exit)} while cappa was using it.`);
2887
+ });
2888
+ }
2145
2889
  };
2146
2890
  //#endregion
2147
2891
  //#region src/engine/RunStore.ts
@@ -2309,6 +3053,7 @@ const isWatchInProgressError = (error) => hasCode(error, ENGINE_ERROR_CODES.watc
2309
3053
  var WarmBrowser = class {
2310
3054
  createTool;
2311
3055
  idleTimeoutMs;
3056
+ onShutdown;
2312
3057
  tool = null;
2313
3058
  idleTimer = null;
2314
3059
  inUse = false;
@@ -2320,6 +3065,7 @@ var WarmBrowser = class {
2320
3065
  constructor(options) {
2321
3066
  this.createTool = options.create;
2322
3067
  this.idleTimeoutMs = options.idleTimeoutMs ?? 3e5;
3068
+ this.onShutdown = options.onShutdown;
2323
3069
  }
2324
3070
  /** True while a browser process is alive. */
2325
3071
  get isWarm() {
@@ -2391,7 +3137,11 @@ var WarmBrowser = class {
2391
3137
  const tool = this.tool;
2392
3138
  this.tool = null;
2393
3139
  this.inUse = false;
2394
- if (tool) await tool.close();
3140
+ try {
3141
+ if (tool) await tool.close();
3142
+ } finally {
3143
+ await this.onShutdown?.();
3144
+ }
2395
3145
  });
2396
3146
  }
2397
3147
  startIdleTimer() {
@@ -2416,7 +3166,11 @@ var WarmBrowser = class {
2416
3166
  if (this.inUse || this.closed || this.holds > 0) return;
2417
3167
  const tool = this.tool;
2418
3168
  this.tool = null;
2419
- if (tool) await tool.close();
3169
+ try {
3170
+ if (tool) await tool.close();
3171
+ } finally {
3172
+ await this.onShutdown?.();
3173
+ }
2420
3174
  });
2421
3175
  }
2422
3176
  serialize(work) {
@@ -2780,6 +3534,28 @@ const toRelative = (cwd, changedPath) => {
2780
3534
  };
2781
3535
  //#endregion
2782
3536
  //#region src/engine/LocalEngine.ts
3537
+ const defaultLog = (level, message) => {
3538
+ try {
3539
+ (0, _cappa_logger.getLogger)()[level](message);
3540
+ } catch {}
3541
+ };
3542
+ /**
3543
+ * Stream a web server's output live at debug level. Buffered regardless: the
3544
+ * tail is what explains a server that failed to start.
3545
+ *
3546
+ * To stderr, never stdout — `capture --json` owns stdout.
3547
+ */
3548
+ const streamOutputAtDebug = (server, chunk) => {
3549
+ let level = 0;
3550
+ try {
3551
+ level = (0, _cappa_logger.getLogger)().level;
3552
+ } catch {
3553
+ return;
3554
+ }
3555
+ if (level < 4) return;
3556
+ const prefix = `[webServer ${server.url}] `;
3557
+ process.stderr.write(chunk.split(/(?<=\n)/).map((line) => prefix + line).join(""));
3558
+ };
2783
3559
  /**
2784
3560
  * `CaptureEngine` backed by an in-process Playwright browser.
2785
3561
  *
@@ -2797,6 +3573,7 @@ var LocalEngine = class {
2797
3573
  fileSystem;
2798
3574
  browser;
2799
3575
  runs;
3576
+ webServers;
2800
3577
  /**
2801
3578
  * Set synchronously the moment a run is claimed, before any `await`, so two
2802
3579
  * concurrent `startRun` calls cannot both pass the check and then fight over
@@ -2824,9 +3601,16 @@ var LocalEngine = class {
2824
3601
  this.plugins = options.plugins;
2825
3602
  this.fileSystem = new ScreenshotFileSystem(options.outputDir);
2826
3603
  this.runs = new RunStore(options.runStore);
3604
+ this.webServers = new WebServerPool({
3605
+ servers: options.webServer ?? [],
3606
+ log: defaultLog,
3607
+ onOutput: streamOutputAtDebug,
3608
+ ...options.webServerPool
3609
+ });
2827
3610
  this.browser = new WarmBrowser({
2828
3611
  create: options.createScreenshotTool ?? (() => this.buildTool()),
2829
- idleTimeoutMs: options.browserIdleTimeoutMs
3612
+ idleTimeoutMs: options.browserIdleTimeoutMs,
3613
+ onShutdown: () => this.webServers.stop()
2830
3614
  });
2831
3615
  }
2832
3616
  buildTool() {
@@ -2876,7 +3660,9 @@ var LocalEngine = class {
2876
3660
  screenshotTool: await this.browser.acquire(),
2877
3661
  plugins: this.plugins,
2878
3662
  outputDir: this.options.outputDir,
2879
- fileSystem: this.fileSystem
3663
+ fileSystem: this.fileSystem,
3664
+ prepare: (log) => this.webServers.ensure(log),
3665
+ explainUnreachable: (origin) => this.webServers.explainUnreachable(origin)
2880
3666
  });
2881
3667
  const finish = () => {
2882
3668
  if (this.activeRunId !== runner.id) return;
@@ -3014,7 +3800,11 @@ var LocalEngine = class {
3014
3800
  this.closed = true;
3015
3801
  await this.endWatch("engine-closed");
3016
3802
  (this.activeRunId ? this.runs.getRunner(this.activeRunId) : void 0)?.abort();
3017
- await this.browser.close();
3803
+ try {
3804
+ await this.browser.close();
3805
+ } finally {
3806
+ await this.webServers.stop();
3807
+ }
3018
3808
  }
3019
3809
  async endWatch(reason) {
3020
3810
  const session = this.watchSession;
@@ -3087,6 +3877,7 @@ var LocalEngine = class {
3087
3877
  async discoverTargets() {
3088
3878
  const tool = await this.browser.acquire();
3089
3879
  try {
3880
+ await this.webServers.ensure();
3090
3881
  const discovered = await Promise.all(this.plugins.map(async (plugin) => {
3091
3882
  const tasks = await plugin.discover(tool);
3092
3883
  return {
@@ -3182,49 +3973,749 @@ var FsScreenshotStore = class {
3182
3973
  }
3183
3974
  };
3184
3975
  //#endregion
3976
+ //#region src/agent/tiles.ts
3977
+ const LOCATOR_MAX_WIDTH = 400;
3978
+ const LOCATOR_MAX_HEIGHT = 1200;
3979
+ const GUTTER = 12;
3980
+ const ROW_GUTTER = 16;
3981
+ const LABEL_HEIGHT = 18;
3982
+ const BACKGROUND = {
3983
+ r: 128,
3984
+ g: 128,
3985
+ b: 128
3986
+ };
3987
+ const escapeXml = (text) => text.replace(/[<>&"]/g, (c) => `&#${c.charCodeAt(0)};`);
3988
+ /** A caption strip, so a row reads as "#2 expected | #2 actual" at a glance. */
3989
+ const label = (text, width) => Buffer.from(`<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${LABEL_HEIGHT}"><rect width="100%" height="100%" fill="#222"/><text x="4" y="13" font-family="sans-serif" font-size="12" fill="#fff">${escapeXml(text)}</text></svg>`);
3990
+ const padAndClamp = (bbox, padding, width, height) => {
3991
+ const padX = typeof padding === "number" ? padding : padding.x;
3992
+ const padY = typeof padding === "number" ? padding : padding.y;
3993
+ const x = Math.max(0, Math.floor(bbox.x - padX));
3994
+ const y = Math.max(0, Math.floor(bbox.y - padY));
3995
+ const right = Math.min(width, Math.ceil(bbox.x + bbox.width + padX));
3996
+ const bottom = Math.min(height, Math.ceil(bbox.y + bbox.height + padY));
3997
+ return {
3998
+ x,
3999
+ y,
4000
+ width: Math.max(1, right - x),
4001
+ height: Math.max(1, bottom - y)
4002
+ };
4003
+ };
4004
+ const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
4005
+ /**
4006
+ * Context kept around a region: proportional to its size, within bounds.
4007
+ *
4008
+ * A fixed margin is too tight for small regions — a changed letter cropped
4009
+ * with 24px around it says nothing about whether a button label got
4010
+ * truncated — and wasteful for large ones.
4011
+ */
4012
+ const contextPadding = (bbox, minimum) => ({
4013
+ x: clamp(bbox.width, minimum * 2, 160),
4014
+ y: clamp(bbox.height, minimum, 96)
4015
+ });
4016
+ /** Scale that fits `width`x`height` into the bounds without upscaling. */
4017
+ const fitScale = (width, height, maxWidth, maxHeight) => Math.min(1, maxWidth / width, maxHeight / height);
4018
+ const readSize$1 = async (file) => {
4019
+ const { width, height } = await (0, sharp.default)(file).metadata();
4020
+ if (!width || !height) throw new Error(`Unable to read image dimensions: ${file}`);
4021
+ return {
4022
+ width,
4023
+ height
4024
+ };
4025
+ };
4026
+ const renderCrop = async (file, box, scale) => {
4027
+ const crop = (0, sharp.default)(file).extract({
4028
+ left: box.x,
4029
+ top: box.y,
4030
+ width: box.width,
4031
+ height: box.height
4032
+ });
4033
+ if (scale < 1) crop.resize(Math.max(1, Math.round(box.width * scale)), Math.max(1, Math.round(box.height * scale)));
4034
+ return crop.png().toBuffer();
4035
+ };
4036
+ const renderRegions = async (options, width, height) => {
4037
+ const padding = options.padding ?? 24;
4038
+ const maxCropWidth = options.maxCropWidth ?? 640;
4039
+ const regions = options.regions.slice(0, options.maxRegions ?? 8);
4040
+ if (regions.length === 0) return void 0;
4041
+ const rows = await Promise.all(regions.map(async (region) => {
4042
+ const box = padAndClamp(region, contextPadding(region, padding), width, height);
4043
+ const scale = Math.min(1, maxCropWidth / box.width);
4044
+ const [expected, actual] = await Promise.all([renderCrop(options.expectedPath, box, scale), renderCrop(options.actualPath, box, scale)]);
4045
+ return {
4046
+ expected,
4047
+ actual,
4048
+ width: Math.max(1, Math.round(box.width * scale)),
4049
+ height: Math.max(1, Math.round(box.height * scale))
4050
+ };
4051
+ }));
4052
+ const columnWidth = (row) => Math.max(row.width, 96);
4053
+ const canvasWidth = Math.max(...rows.map((row) => columnWidth(row) * 2 + GUTTER));
4054
+ const canvasHeight = rows.reduce((sum, row) => sum + LABEL_HEIGHT + row.height, 0) + ROW_GUTTER * (rows.length - 1);
4055
+ const composites = [];
4056
+ let top = 0;
4057
+ rows.forEach((row, index) => {
4058
+ const column = columnWidth(row);
4059
+ const right = column + GUTTER;
4060
+ composites.push({
4061
+ input: label(`#${index + 1} expected`, column),
4062
+ left: 0,
4063
+ top
4064
+ }, {
4065
+ input: label(`#${index + 1} actual`, column),
4066
+ left: right,
4067
+ top
4068
+ }, {
4069
+ input: row.expected,
4070
+ left: 0,
4071
+ top: top + LABEL_HEIGHT
4072
+ }, {
4073
+ input: row.actual,
4074
+ left: right,
4075
+ top: top + LABEL_HEIGHT
4076
+ });
4077
+ top += LABEL_HEIGHT + row.height + ROW_GUTTER;
4078
+ });
4079
+ const file = node_path.default.join(options.outDir, "regions.png");
4080
+ await (0, sharp.default)({ create: {
4081
+ width: canvasWidth,
4082
+ height: canvasHeight,
4083
+ channels: 3,
4084
+ background: BACKGROUND
4085
+ } }).composite(composites).png().toFile(file);
4086
+ return {
4087
+ file,
4088
+ count: rows.length
4089
+ };
4090
+ };
4091
+ const renderLocator = async (options, width, height) => {
4092
+ const scale = fitScale(width, height, LOCATOR_MAX_WIDTH, LOCATOR_MAX_HEIGHT);
4093
+ const locatorWidth = Math.max(1, Math.round(width * scale));
4094
+ const locatorHeight = Math.max(1, Math.round(height * scale));
4095
+ const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${locatorWidth}" height="${locatorHeight}">${options.regions.map((region, index) => {
4096
+ const x = Math.round(region.x * scale);
4097
+ const y = Math.round(region.y * scale);
4098
+ return `<rect x="${x}" y="${y}" width="${Math.max(2, Math.round(region.width * scale))}" height="${Math.max(2, Math.round(region.height * scale))}" fill="none" stroke="red" stroke-width="2"/><text x="${x + 2}" y="${Math.max(12, y - 3)}" font-family="sans-serif" font-size="12" font-weight="bold" fill="red" stroke="#fff" stroke-width="3" paint-order="stroke">${index + 1}</text>`;
4099
+ }).join("")}</svg>`;
4100
+ const file = node_path.default.join(options.outDir, "locator.png");
4101
+ await (0, sharp.default)(options.diffPath ?? options.actualPath).resize(locatorWidth, locatorHeight, { fit: "fill" }).composite([{
4102
+ input: Buffer.from(svg),
4103
+ left: 0,
4104
+ top: 0
4105
+ }]).png().toFile(file);
4106
+ return file;
4107
+ };
4108
+ /**
4109
+ * Write `locator.png` and `regions.png` into `outDir`.
4110
+ *
4111
+ * Expected and actual must have the same dimensions — region boxes are only
4112
+ * meaningful when both images share a coordinate space. Use
4113
+ * {@link renderOverview} when they do not.
4114
+ */
4115
+ const renderJudgmentTiles = async (options) => {
4116
+ const { width, height } = await readSize$1(options.actualPath);
4117
+ const [regions, locator] = await Promise.all([renderRegions(options, width, height), renderLocator(options, width, height)]);
4118
+ return {
4119
+ locator,
4120
+ regions: regions?.file,
4121
+ renderedRegions: regions?.count ?? 0
4122
+ };
4123
+ };
4124
+ /**
4125
+ * Write `overview.png`: expected and actual, scaled down side by side.
4126
+ *
4127
+ * For screenshots whose dimensions changed, where no region can be located,
4128
+ * this is what the judge looks at instead of two full-size images.
4129
+ */
4130
+ const renderOverview = async (options) => {
4131
+ const [expectedSize, actualSize] = await Promise.all([readSize$1(options.expectedPath), readSize$1(options.actualPath)]);
4132
+ const scale = Math.min(fitScale(expectedSize.width, expectedSize.height, LOCATOR_MAX_WIDTH, LOCATOR_MAX_HEIGHT), fitScale(actualSize.width, actualSize.height, LOCATOR_MAX_WIDTH, LOCATOR_MAX_HEIGHT));
4133
+ const scaled = (size) => ({
4134
+ width: Math.max(1, Math.round(size.width * scale)),
4135
+ height: Math.max(1, Math.round(size.height * scale))
4136
+ });
4137
+ const expected = scaled(expectedSize);
4138
+ const actual = scaled(actualSize);
4139
+ const [expectedBuffer, actualBuffer] = await Promise.all([(0, sharp.default)(options.expectedPath).resize(expected.width, expected.height, { fit: "fill" }).png().toBuffer(), (0, sharp.default)(options.actualPath).resize(actual.width, actual.height, { fit: "fill" }).png().toBuffer()]);
4140
+ const file = node_path.default.join(options.outDir, "overview.png");
4141
+ await (0, sharp.default)({ create: {
4142
+ width: expected.width + GUTTER + actual.width,
4143
+ height: LABEL_HEIGHT + Math.max(expected.height, actual.height),
4144
+ channels: 3,
4145
+ background: BACKGROUND
4146
+ } }).composite([
4147
+ {
4148
+ input: label(`expected ${expectedSize.width}x${expectedSize.height}`, expected.width),
4149
+ left: 0,
4150
+ top: 0
4151
+ },
4152
+ {
4153
+ input: label(`actual ${actualSize.width}x${actualSize.height}`, actual.width),
4154
+ left: expected.width + GUTTER,
4155
+ top: 0
4156
+ },
4157
+ {
4158
+ input: expectedBuffer,
4159
+ left: 0,
4160
+ top: LABEL_HEIGHT
4161
+ },
4162
+ {
4163
+ input: actualBuffer,
4164
+ left: expected.width + GUTTER,
4165
+ top: LABEL_HEIGHT
4166
+ }
4167
+ ]).png().toFile(file);
4168
+ return file;
4169
+ };
4170
+ //#endregion
4171
+ //#region src/agent/review.ts
4172
+ /**
4173
+ * Agent review: turn the screenshots on disk into something a coding agent
4174
+ * can judge cheaply, and fold its judgments back in.
4175
+ *
4176
+ * Nothing here captures. It reads `actual/`, `expected/` and `diff/` as the
4177
+ * last `cappa capture` left them, so it is safe to run repeatedly — a re-run
4178
+ * is how an agent's verdicts are applied, and a re-capture invalidates them
4179
+ * automatically because every judgment is tied to a fingerprint of the two
4180
+ * images it was made about.
4181
+ *
4182
+ * Layout, all inside `<outputDir>/.cappa-agent/` (dot-prefixed, so neither
4183
+ * screenshot collection nor the review server's static handler touch it):
4184
+ *
4185
+ * ```
4186
+ * report.json full report of the last check
4187
+ * judgments/<name>/request.json what to judge and where the evidence is
4188
+ * judgments/<name>/locator.png thumbnail with every region outlined
4189
+ * judgments/<name>/regions.png [expected | actual] crop per region
4190
+ * judgments/<name>/overview.png instead of the two above when sizes differ
4191
+ * judgments/<name>/verdict.json written by the judge
4192
+ * ```
4193
+ */
4194
+ const REQUEST_FILE = "request.json";
4195
+ const VERDICT_FILE = "verdict.json";
4196
+ const JUDGMENT_FILES = [
4197
+ REQUEST_FILE,
4198
+ VERDICT_FILE,
4199
+ "locator.png",
4200
+ "regions.png",
4201
+ "overview.png"
4202
+ ];
4203
+ const JUDGE_MODES = [
4204
+ "ambiguous",
4205
+ "all",
4206
+ "none"
4207
+ ];
4208
+ /**
4209
+ * The directory holding a screenshot's judgment.
4210
+ *
4211
+ * Screenshot names are relative paths (`example/button/primary`), so they map
4212
+ * onto nested directories directly; anything that would resolve outside the
4213
+ * judgments root is refused rather than written.
4214
+ */
4215
+ const judgmentDir = (outputDir, name) => {
4216
+ const root = judgmentsRoot(outputDir);
4217
+ const dir = node_path.default.resolve(root, name);
4218
+ const relative = node_path.default.relative(root, dir);
4219
+ if (!relative || relative.startsWith("..") || node_path.default.isAbsolute(relative)) throw new Error(`Invalid screenshot name for a judgment: ${name}`);
4220
+ return dir;
4221
+ };
4222
+ const exists = async (file) => {
4223
+ try {
4224
+ await node_fs_promises.default.access(file);
4225
+ return true;
4226
+ } catch {
4227
+ return false;
4228
+ }
4229
+ };
4230
+ const readJson = async (file) => {
4231
+ try {
4232
+ return JSON.parse(await node_fs_promises.default.readFile(file, "utf8"));
4233
+ } catch {
4234
+ return;
4235
+ }
4236
+ };
4237
+ const writeJson = async (file, value) => {
4238
+ await node_fs_promises.default.mkdir(node_path.default.dirname(file), { recursive: true });
4239
+ await node_fs_promises.default.writeFile(file, `${JSON.stringify(value, null, 2)}\n`, "utf8");
4240
+ };
4241
+ /** Ties a judgment to the exact pair of images it was made about. */
4242
+ const fingerprintImages = async (expectedPath, actualPath) => {
4243
+ const [expected, actual] = await Promise.all([node_fs_promises.default.readFile(expectedPath), node_fs_promises.default.readFile(actualPath)]);
4244
+ return (0, node_crypto.createHash)("sha256").update(expected).update("\0").update(actual).digest("hex");
4245
+ };
4246
+ /**
4247
+ * Read a judge's verdict, accepting both the nested shape blazediff uses
4248
+ * (`{ verdict: { label, headline, rationale }, confidence }`) and a flat one
4249
+ * (`{ label, headline, rationale, confidence }`) — a judge that writes either
4250
+ * should not have its work thrown away over nesting.
4251
+ */
4252
+ const parseAgentVerdict = (raw) => {
4253
+ if (typeof raw !== "object" || raw === null) return {
4254
+ ok: false,
4255
+ error: "verdict.json is not a JSON object"
4256
+ };
4257
+ const outer = raw;
4258
+ const inner = typeof outer.verdict === "object" && outer.verdict !== null ? outer.verdict : outer;
4259
+ const label = inner.label;
4260
+ if (!isJudgedLabel(label)) return {
4261
+ ok: false,
4262
+ error: `label must be one of regression-likely, intentional-likely, noise-likely (got ${JSON.stringify(label)})`
4263
+ };
4264
+ const headline = typeof inner.headline === "string" && inner.headline.trim() ? inner.headline.trim() : void 0;
4265
+ if (!headline) return {
4266
+ ok: false,
4267
+ error: "headline must be a non-empty string"
4268
+ };
4269
+ const toLines = (value) => Array.isArray(value) ? value.filter((line) => typeof line === "string") : typeof value === "string" && value.trim() ? [value.trim()] : [];
4270
+ const rationale = [...toLines(inner.rationale)];
4271
+ if (inner !== outer) rationale.push(...toLines(outer.rationale));
4272
+ const rawConfidence = outer.confidence ?? inner.confidence;
4273
+ const confidence = typeof rawConfidence === "number" && Number.isFinite(rawConfidence) ? Math.min(1, Math.max(0, rawConfidence)) : void 0;
4274
+ return {
4275
+ ok: true,
4276
+ label,
4277
+ headline,
4278
+ rationale,
4279
+ ...confidence !== void 0 ? { confidence } : {}
4280
+ };
4281
+ };
4282
+ const readSize = async (file) => {
4283
+ const { width = 0, height = 0 } = await (0, sharp.default)(file).metadata();
4284
+ return {
4285
+ width,
4286
+ height
4287
+ };
4288
+ };
4289
+ const toAgentRegions = (regions) => [...regions].sort((a, b) => b.pixelCount - a.pixelCount).map((region, index) => ({
4290
+ index: index + 1,
4291
+ bbox: {
4292
+ x: region.bbox.x,
4293
+ y: region.bbox.y,
4294
+ width: region.bbox.width,
4295
+ height: region.bbox.height
4296
+ },
4297
+ pixelCount: region.pixelCount,
4298
+ percentage: region.percentage,
4299
+ position: region.position,
4300
+ shape: region.shape,
4301
+ changeType: normalizeChangeType(region.changeType),
4302
+ confidence: region.confidence
4303
+ }));
4304
+ /**
4305
+ * The interpretation a capture already persisted, or a fresh one.
4306
+ *
4307
+ * `diff.interpret` is off by default, so most changed screenshots arrive
4308
+ * without one; computing it here means agent review works on any project
4309
+ * rather than only on those that opted into interpretation at capture time.
4310
+ */
4311
+ const interpretationFor = async (screenshot, expectedPath, actualPath, diff) => {
4312
+ if (screenshot.diffMeta?.interpretation) return screenshot.diffMeta.interpretation;
4313
+ const pixel = diff && diff.type !== "gmsd" ? diff : void 0;
4314
+ try {
4315
+ return await (0, _blazediff_interpret_native.interpret)(expectedPath, actualPath, void 0, {
4316
+ source: "pixel",
4317
+ threshold: pixel?.threshold,
4318
+ antialiasing: pixel?.includeAA ?? false
4319
+ });
4320
+ } catch {
4321
+ return;
4322
+ }
4323
+ };
4324
+ const JUDGE_INSTRUCTIONS = [
4325
+ "Read locator.png and regions.png together. locator.png outlines every region (numbered) on a thumbnail; regions.png stacks one [expected | actual] row per region, in `regions` order.",
4326
+ "Open overview.png when it exists instead — the image dimensions changed, so no regions could be located.",
4327
+ "Only open paths.expected / paths.actual / paths.diff (full size) when a change clearly continues outside its crop.",
4328
+ "Write verdict.json next to this file, or run `cappa agent judge <name> --label <label> --headline <text>`."
4329
+ ];
4330
+ const VERDICT_SCHEMA = {
4331
+ label: "regression-likely | intentional-likely | noise-likely",
4332
+ headline: "one line describing what changed",
4333
+ rationale: ["short reasons"],
4334
+ confidence: "0..1"
4335
+ };
4336
+ const analyseChanged = async (screenshot, options, createdAt) => {
4337
+ const { outputDir } = options;
4338
+ const expectedPath = node_path.default.resolve(outputDir, screenshot.expectedPath);
4339
+ const actualPath = node_path.default.resolve(outputDir, screenshot.actualPath);
4340
+ const diffPath = node_path.default.resolve(outputDir, screenshot.diffPath);
4341
+ const [expectedSize, actualSize, diffExists] = await Promise.all([
4342
+ readSize(expectedPath),
4343
+ readSize(actualPath),
4344
+ exists(diffPath)
4345
+ ]);
4346
+ const differentSizes = expectedSize.width !== actualSize.width || expectedSize.height !== actualSize.height;
4347
+ const interpretation = differentSizes ? void 0 : await interpretationFor(screenshot, expectedPath, actualPath, options.diff);
4348
+ const percentDifference = screenshot.diffMeta?.percentDifference ?? interpretation?.diffPercentage;
4349
+ const numDiffPixels = screenshot.diffMeta?.numDiffPixels ?? interpretation?.diffCount;
4350
+ const regions = toAgentRegions(interpretation?.regions ?? []);
4351
+ const heuristic = deriveVerdict({
4352
+ percentDifference,
4353
+ numDiffPixels,
4354
+ interpretation,
4355
+ differentSizes
4356
+ });
4357
+ const entry = {
4358
+ name: screenshot.name,
4359
+ category: "changed",
4360
+ ...screenshot.taskId ? {
4361
+ taskId: screenshot.taskId,
4362
+ plugin: screenshot.plugin
4363
+ } : {},
4364
+ paths: {
4365
+ expected: expectedPath,
4366
+ actual: actualPath,
4367
+ ...diffExists ? { diff: diffPath } : {}
4368
+ },
4369
+ percentDifference,
4370
+ numDiffPixels,
4371
+ dimensions: {
4372
+ expected: expectedSize,
4373
+ actual: actualSize
4374
+ },
4375
+ severity: interpretation?.severity?.toLowerCase(),
4376
+ summary: interpretation?.summary,
4377
+ regions,
4378
+ heuristic,
4379
+ verdict: {
4380
+ ...heuristic,
4381
+ source: "heuristic"
4382
+ },
4383
+ pending: false
4384
+ };
4385
+ const dir = judgmentDir(outputDir, screenshot.name);
4386
+ const requestPath = node_path.default.join(dir, REQUEST_FILE);
4387
+ const verdictPath = node_path.default.join(dir, VERDICT_FILE);
4388
+ if (!(options.judge === "all" || options.judge === "ambiguous" && heuristic.label === "ambiguous" || await exists(requestPath))) return entry;
4389
+ const fingerprint = await fingerprintImages(expectedPath, actualPath);
4390
+ const previous = await readJson(requestPath);
4391
+ if (previous && previous.fingerprint !== fingerprint) await clearJudgmentFiles(dir);
4392
+ await node_fs_promises.default.mkdir(dir, { recursive: true });
4393
+ const judgment = {
4394
+ dir,
4395
+ request: requestPath,
4396
+ verdict: verdictPath
4397
+ };
4398
+ if (differentSizes) judgment.overview = await renderOverview({
4399
+ expectedPath,
4400
+ actualPath,
4401
+ outDir: dir
4402
+ });
4403
+ else {
4404
+ const tiles = await renderJudgmentTiles({
4405
+ expectedPath,
4406
+ actualPath,
4407
+ diffPath: diffExists ? diffPath : void 0,
4408
+ regions: regions.map((region) => region.bbox),
4409
+ outDir: dir,
4410
+ maxRegions: options.maxTileRegions
4411
+ });
4412
+ if (tiles.locator) judgment.locator = tiles.locator;
4413
+ if (tiles.regions) judgment.regions = tiles.regions;
4414
+ }
4415
+ entry.judgment = judgment;
4416
+ await writeJson(requestPath, {
4417
+ version: 1,
4418
+ name: entry.name,
4419
+ taskId: entry.taskId,
4420
+ plugin: entry.plugin,
4421
+ fingerprint,
4422
+ createdAt,
4423
+ instructions: JUDGE_INSTRUCTIONS,
4424
+ verdictSchema: VERDICT_SCHEMA,
4425
+ heuristic,
4426
+ percentDifference,
4427
+ numDiffPixels,
4428
+ dimensions: entry.dimensions,
4429
+ severity: entry.severity,
4430
+ summary: entry.summary,
4431
+ regions,
4432
+ paths: {
4433
+ locator: judgment.locator,
4434
+ regions: judgment.regions,
4435
+ overview: judgment.overview,
4436
+ expected: expectedPath,
4437
+ actual: actualPath,
4438
+ diff: entry.paths.diff,
4439
+ verdict: verdictPath
4440
+ }
4441
+ });
4442
+ if (!await exists(verdictPath)) {
4443
+ entry.pending = true;
4444
+ return entry;
4445
+ }
4446
+ const parsed = parseAgentVerdict(await readJson(verdictPath));
4447
+ if (!parsed.ok) {
4448
+ entry.pending = true;
4449
+ entry.verdictError = parsed.error;
4450
+ return entry;
4451
+ }
4452
+ entry.verdict = {
4453
+ label: parsed.label,
4454
+ headline: parsed.headline,
4455
+ rationale: parsed.rationale,
4456
+ action: ACTION_BY_LABEL[parsed.label],
4457
+ source: "agent",
4458
+ ...parsed.confidence !== void 0 ? { confidence: parsed.confidence } : {}
4459
+ };
4460
+ return entry;
4461
+ };
4462
+ const clearJudgmentFiles = async (dir) => {
4463
+ await Promise.all(JUDGMENT_FILES.map((file) => node_fs_promises.default.rm(node_path.default.join(dir, file), { force: true })));
4464
+ };
4465
+ /**
4466
+ * Remove a screenshot's judgment — after it was approved, or because it is no
4467
+ * longer changed. Only the judgment's own files go: a directory can also be
4468
+ * the parent of another screenshot's judgment (`button` and `button/primary`).
4469
+ */
4470
+ const clearJudgment = async (outputDir, name) => {
4471
+ const dir = judgmentDir(outputDir, name);
4472
+ await clearJudgmentFiles(dir);
4473
+ await removeEmptyDirs(dir, judgmentsRoot(outputDir));
4474
+ };
4475
+ /** Remove `dir` and its parents up to (excluding) `root` while empty. */
4476
+ const removeEmptyDirs = async (dir, root) => {
4477
+ let current = dir;
4478
+ while (current !== root && current.startsWith(root)) {
4479
+ try {
4480
+ await node_fs_promises.default.rmdir(current);
4481
+ } catch {
4482
+ return;
4483
+ }
4484
+ current = node_path.default.dirname(current);
4485
+ }
4486
+ };
4487
+ const listRequestDirs = async (root) => {
4488
+ if (!await exists(root)) return [];
4489
+ return (await Array.fromAsync(node_fs_promises.default.glob(`**/${REQUEST_FILE}`, { cwd: root }))).map((file) => node_path.default.resolve(root, node_path.default.dirname(file)));
4490
+ };
4491
+ /** Drop judgments for screenshots that no longer need one. */
4492
+ const pruneJudgments = async (outputDir, keep) => {
4493
+ const root = judgmentsRoot(outputDir);
4494
+ for (const dir of await listRequestDirs(root)) {
4495
+ if (keep.has(dir)) continue;
4496
+ await clearJudgmentFiles(dir);
4497
+ await removeEmptyDirs(dir, root);
4498
+ }
4499
+ };
4500
+ /**
4501
+ * Analyse every non-passing screenshot, write judgment requests for the ones
4502
+ * that need a judge, apply any verdicts already written, and persist the
4503
+ * full report to `<outputDir>/.cappa-agent/report.json`.
4504
+ */
4505
+ const runAgentCheck = async (options) => {
4506
+ const outputDir = node_path.default.resolve(options.outputDir);
4507
+ const judge = options.judge ?? "ambiguous";
4508
+ const createdAt = (options.now?.() ?? /* @__PURE__ */ new Date()).toISOString();
4509
+ const screenshots = await collectScreenshots(outputDir);
4510
+ await node_fs_promises.default.mkdir(agentDir(outputDir), { recursive: true });
4511
+ await node_fs_promises.default.writeFile(node_path.default.join(agentDir(outputDir), ".gitignore"), "*\n");
4512
+ const changed = screenshots.filter((s) => s.category === "changed");
4513
+ const changedEntries = await mapWithConcurrency(options.concurrency ?? 4, changed, (screenshot) => analyseChanged(screenshot, {
4514
+ ...options,
4515
+ outputDir,
4516
+ judge
4517
+ }, createdAt));
4518
+ await pruneJudgments(outputDir, new Set(changedEntries.flatMap((entry) => entry.judgment ? [entry.judgment.dir] : [])));
4519
+ const otherEntries = screenshots.flatMap((s) => {
4520
+ if (s.category === "new") return [{
4521
+ name: s.name,
4522
+ category: "new",
4523
+ ...s.taskId ? {
4524
+ taskId: s.taskId,
4525
+ plugin: s.plugin
4526
+ } : {},
4527
+ paths: { actual: node_path.default.resolve(outputDir, s.actualPath) },
4528
+ pending: false
4529
+ }];
4530
+ if (s.category === "deleted") return [{
4531
+ name: s.name,
4532
+ category: "deleted",
4533
+ paths: { expected: node_path.default.resolve(outputDir, s.expectedPath) },
4534
+ pending: false
4535
+ }];
4536
+ return [];
4537
+ });
4538
+ const entries = [...changedEntries, ...otherEntries];
4539
+ const count = (category) => screenshots.filter((s) => s.category === category).length;
4540
+ const report = {
4541
+ version: 1,
4542
+ createdAt,
4543
+ outputDir,
4544
+ reportPath: agentReportPath(outputDir),
4545
+ judge,
4546
+ totals: {
4547
+ total: screenshots.length,
4548
+ passed: count("passed"),
4549
+ changed: count("changed"),
4550
+ new: count("new"),
4551
+ deleted: count("deleted"),
4552
+ pendingJudgments: entries.filter((entry) => entry.pending).length
4553
+ },
4554
+ entries
4555
+ };
4556
+ await writeJson(report.reportPath, report);
4557
+ return report;
4558
+ };
4559
+ /** Read the report the last {@link runAgentCheck} wrote, if any. */
4560
+ const readAgentReport = async (outputDir) => {
4561
+ const raw = await readJson(agentReportPath(outputDir));
4562
+ return raw?.version === 1 ? raw : void 0;
4563
+ };
4564
+ /**
4565
+ * The report as an agent should first see it: one line of state per
4566
+ * screenshot, with the detail left in `report.json` and the judgment
4567
+ * requests for when it is actually needed.
4568
+ */
4569
+ const toSlimAgentReport = (report) => ({
4570
+ reportPath: report.reportPath,
4571
+ ...report.totals,
4572
+ results: report.entries.map((entry) => ({
4573
+ name: entry.name,
4574
+ category: entry.category,
4575
+ ...entry.verdict ? { verdict: {
4576
+ label: entry.verdict.label,
4577
+ headline: entry.verdict.headline,
4578
+ action: entry.verdict.action,
4579
+ source: entry.verdict.source
4580
+ } } : {},
4581
+ ...entry.pending ? { pending: true } : {},
4582
+ ...entry.pending && entry.judgment ? { judgment: entry.judgment.dir } : {},
4583
+ ...entry.verdictError ? { verdictError: entry.verdictError } : {}
4584
+ }))
4585
+ });
4586
+ /**
4587
+ * Record a judge's verdict for a screenshot with a pending request — the
4588
+ * validated alternative to hand-writing `verdict.json`.
4589
+ */
4590
+ const writeAgentVerdict = async (outputDir, name, input) => {
4591
+ const dir = judgmentDir(outputDir, name);
4592
+ if (!await exists(node_path.default.join(dir, REQUEST_FILE))) throw new Error(`No judgment request for "${name}" — run \`cappa agent check\` first (use --judge all to request one for any changed screenshot).`);
4593
+ const parsed = parseAgentVerdict(input);
4594
+ if (!parsed.ok) throw new Error(parsed.error);
4595
+ const verdictPath = node_path.default.join(dir, VERDICT_FILE);
4596
+ await writeJson(verdictPath, {
4597
+ name,
4598
+ verdict: {
4599
+ label: parsed.label,
4600
+ headline: parsed.headline,
4601
+ rationale: parsed.rationale,
4602
+ action: ACTION_BY_LABEL[parsed.label]
4603
+ },
4604
+ ...parsed.confidence !== void 0 ? { confidence: parsed.confidence } : {}
4605
+ });
4606
+ return verdictPath;
4607
+ };
4608
+ //#endregion
4609
+ //#region src/webServer/resolve.ts
4610
+ const DEFAULT_WEB_SERVER_TIMEOUT_MS = 6e4;
4611
+ const isHttpUrl = (value) => URL.canParse(value) && ["http:", "https:"].includes(new URL(value).protocol);
4612
+ /**
4613
+ * Normalise `webServer` to a list with every default applied.
4614
+ *
4615
+ * A relative `cwd` resolves against `configDir` — the directory of
4616
+ * `cappa.config.ts` — not the process's working directory, so the same config
4617
+ * works whether cappa runs from the repository root or from inside the package
4618
+ * (`pnpm -F visual-tests cappa capture`).
4619
+ */
4620
+ function resolveWebServerConfig(webServer, configDir, env = process.env) {
4621
+ if (webServer === void 0) return [];
4622
+ return (Array.isArray(webServer) ? webServer : [webServer]).map((entry, index) => {
4623
+ const where = Array.isArray(webServer) ? `webServer[${index}]` : "webServer";
4624
+ if (typeof entry?.command !== "string" || entry.command.trim() === "") throw new Error(`Invalid configuration: ${where}.command is required.`);
4625
+ if (typeof entry.url !== "string" || !isHttpUrl(entry.url)) throw new Error(`Invalid configuration: ${where}.url must be an absolute URL, e.g. "http://localhost:6006".`);
4626
+ if (entry.timeout !== void 0 && !(Number.isFinite(entry.timeout) && entry.timeout > 0)) throw new Error(`Invalid configuration: ${where}.timeout must be a positive number of milliseconds.`);
4627
+ return {
4628
+ command: entry.command,
4629
+ url: entry.url,
4630
+ reuseExistingServer: entry.reuseExistingServer ?? !env.CI,
4631
+ timeout: entry.timeout ?? 6e4,
4632
+ cwd: node_path.default.resolve(configDir, entry.cwd ?? "."),
4633
+ env: entry.env ?? {}
4634
+ };
4635
+ });
4636
+ }
4637
+ //#endregion
4638
+ exports.ACTION_BY_LABEL = ACTION_BY_LABEL;
4639
+ exports.AGENT_DIRNAME = AGENT_DIRNAME;
4640
+ exports.AGENT_REPORT_VERSION = AGENT_REPORT_VERSION;
3185
4641
  exports.CONSOLE_LOG_LEVELS = CONSOLE_LOG_LEVELS;
3186
4642
  exports.CaptureRunner = CaptureRunner;
3187
4643
  exports.DEFAULT_DEBOUNCE_MS = DEFAULT_DEBOUNCE_MS;
3188
4644
  exports.DEFAULT_IGNORED_DIRS = DEFAULT_IGNORED_DIRS;
4645
+ exports.DEFAULT_KILL_GRACE_MS = DEFAULT_KILL_GRACE_MS;
3189
4646
  exports.DEFAULT_MAX_TASKS = DEFAULT_MAX_TASKS;
4647
+ exports.DEFAULT_WEB_SERVER_TIMEOUT_MS = DEFAULT_WEB_SERVER_TIMEOUT_MS;
3190
4648
  exports.ENGINE_ERROR_CODES = ENGINE_ERROR_CODES;
3191
4649
  exports.FsScreenshotStore = FsScreenshotStore;
4650
+ exports.JUDGED_LABELS = JUDGED_LABELS;
4651
+ exports.JUDGE_MODES = JUDGE_MODES;
3192
4652
  exports.LocalEngine = LocalEngine;
3193
4653
  exports.MANIFEST_FILENAME = MANIFEST_FILENAME;
3194
4654
  exports.MANIFEST_VERSION = MANIFEST_VERSION;
4655
+ exports.NO_WEB_SERVER_HINT = NO_WEB_SERVER_HINT;
4656
+ exports.OutputTail = OutputTail;
3195
4657
  exports.RunInProgressError = RunInProgressError;
3196
4658
  exports.RunStore = RunStore;
4659
+ exports.SUB_PERCEPTUAL_PERCENT = SUB_PERCEPTUAL_PERCENT;
3197
4660
  exports.ScreenshotFileSystem = ScreenshotFileSystem;
3198
4661
  exports.ScreenshotTool = ScreenshotTool;
3199
4662
  exports.UnknownTargetsError = UnknownTargetsError;
4663
+ exports.VERDICT_LABELS = VERDICT_LABELS;
3200
4664
  exports.WarmBrowser = WarmBrowser;
3201
4665
  exports.WatchInProgressError = WatchInProgressError;
3202
4666
  exports.WatchSession = WatchSession;
4667
+ exports.WebServerError = WebServerError;
4668
+ exports.WebServerPool = WebServerPool;
4669
+ exports.agentDir = agentDir;
4670
+ exports.agentReportPath = agentReportPath;
3203
4671
  exports.attachConsoleLogging = attachConsoleLogging;
4672
+ exports.buildHeadline = buildHeadline;
4673
+ exports.clearJudgment = clearJudgment;
3204
4674
  exports.collectScreenshots = collectScreenshots;
3205
4675
  exports.compareImages = compareImages;
3206
4676
  exports.compareImagesGMSD = compareImagesGMSD;
4677
+ exports.contextPadding = contextPadding;
3207
4678
  exports.defineConfig = defineConfig;
4679
+ exports.deriveVerdict = deriveVerdict;
3208
4680
  exports.didScreenshotFail = didScreenshotFail;
3209
4681
  exports.filterTasks = filterTasks;
4682
+ exports.findRefusedConnection = findRefusedConnection;
4683
+ exports.fingerprintImages = fingerprintImages;
3210
4684
  exports.getDeletedScreenshots = getDeletedScreenshots;
3211
4685
  exports.groupScreenshots = groupScreenshots;
3212
4686
  exports.imagesMatch = imagesMatch;
3213
4687
  exports.imagesMatchGMSD = imagesMatchGMSD;
4688
+ exports.isJudgedLabel = isJudgedLabel;
3214
4689
  exports.isRunInProgressError = isRunInProgressError;
3215
4690
  exports.isUnknownTargetsError = isUnknownTargetsError;
4691
+ exports.isUrlReady = isUrlReady;
4692
+ exports.isVerdictLabel = isVerdictLabel;
3216
4693
  exports.isWatchInProgressError = isWatchInProgressError;
4694
+ exports.judgmentDir = judgmentDir;
3217
4695
  exports.mapWithConcurrency = mapWithConcurrency;
3218
4696
  exports.mergeCaptureManifest = mergeCaptureManifest;
4697
+ exports.normalizeChangeType = normalizeChangeType;
4698
+ exports.padAndClamp = padAndClamp;
4699
+ exports.parseAgentVerdict = parseAgentVerdict;
4700
+ exports.readAgentReport = readAgentReport;
3219
4701
  exports.readCaptureManifest = readCaptureManifest;
3220
4702
  exports.readDiffMeta = readDiffMeta;
3221
4703
  exports.recordCaptureOrigins = recordCaptureOrigins;
4704
+ exports.renderJudgmentTiles = renderJudgmentTiles;
4705
+ exports.renderOverview = renderOverview;
4706
+ exports.resolveWebServerConfig = resolveWebServerConfig;
4707
+ exports.runAgentCheck = runAgentCheck;
4708
+ exports.sameServer = sameServer;
3222
4709
  exports.sanitizeScreenshotFilename = sanitizeScreenshotFilename;
3223
4710
  exports.selectTasks = selectTasks;
4711
+ exports.spawnServerProcess = spawnServerProcess;
3224
4712
  exports.toConsoleLogLevel = toConsoleLogLevel;
3225
4713
  exports.toDiffMetaPath = toDiffMetaPath;
3226
4714
  exports.toManifestKey = toManifestKey;
3227
4715
  exports.toSerializedError = toSerializedError;
4716
+ exports.toSlimAgentReport = toSlimAgentReport;
3228
4717
  exports.toTaskStatus = toTaskStatus;
4718
+ exports.waitForUrl = waitForUrl;
4719
+ exports.writeAgentVerdict = writeAgentVerdict;
3229
4720
 
3230
4721
  //# sourceMappingURL=index.cjs.map