@cappa/cli 0.15.1 → 0.17.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 +260 -25
- package/dist/index.cjs.map +1 -1
- package/dist/index.mjs +260 -25
- package/dist/index.mjs.map +1 -1
- package/integrations/claude/agents/cappa-judge.md +7 -50
- package/integrations/judge/cappa-judge.md +33 -0
- package/integrations/opencode/agents/cappa-judge.md +1 -55
- package/integrations/opencode/commands/cappa-review.md +2 -0
- package/integrations/skills/cappa/JUDGING.md +20 -12
- package/integrations/skills/cappa/SKILL.md +7 -10
- package/package.json +5 -5
package/dist/index.mjs
CHANGED
|
@@ -12,7 +12,7 @@ import { ProtocolMismatchError, createClient } from "@cappa/client";
|
|
|
12
12
|
import { createServer, isLoopbackHost } from "@cappa/server";
|
|
13
13
|
import { randomBytes } from "node:crypto";
|
|
14
14
|
//#region package.json
|
|
15
|
-
var version = "0.
|
|
15
|
+
var version = "0.17.0";
|
|
16
16
|
//#endregion
|
|
17
17
|
//#region ../../node_modules/.pnpm/tsdown@0.23.0_@arethetypeswrong+core@0.18.5_oxc-resolver@11.24.2_tsx@4.23.1_typescript@7.0.2/node_modules/tsdown/esm-shims.js
|
|
18
18
|
const getFilename = () => fileURLToPath(import.meta.url);
|
|
@@ -40,6 +40,16 @@ const SKILL = [
|
|
|
40
40
|
"skills/cappa/JUDGING.md",
|
|
41
41
|
"skills/cappa/MASKING.md"
|
|
42
42
|
];
|
|
43
|
+
/**
|
|
44
|
+
* Both judges share one body; their own source files are only the
|
|
45
|
+
* frontmatter each agent needs. The body points at the copy of `JUDGING.md`
|
|
46
|
+
* the agent's caller reads — for OpenCode that is the `.claude` copy when
|
|
47
|
+
* there is one, since OpenCode prefers it over `.agents` (see the warning in
|
|
48
|
+
* `installAgentSkills`), and judge and caller must not follow two copies.
|
|
49
|
+
*/
|
|
50
|
+
const JUDGE_BODY = "judge/cappa-judge.md";
|
|
51
|
+
const CLAUDE_JUDGING = ".claude/skills/cappa/JUDGING.md";
|
|
52
|
+
const AGENTS_JUDGING = ".agents/skills/cappa/JUDGING.md";
|
|
43
53
|
const skillInto = (dir) => SKILL.map((source) => ({
|
|
44
54
|
source,
|
|
45
55
|
target: path.join(dir, path.basename(source))
|
|
@@ -47,18 +57,26 @@ const skillInto = (dir) => SKILL.map((source) => ({
|
|
|
47
57
|
const STACK_FILES = {
|
|
48
58
|
claude: [...skillInto(".claude/skills/cappa"), {
|
|
49
59
|
source: "claude/agents/cappa-judge.md",
|
|
50
|
-
target: path.join(".claude", "agents", "cappa-judge.md")
|
|
60
|
+
target: path.join(".claude", "agents", "cappa-judge.md"),
|
|
61
|
+
judge: "claude"
|
|
51
62
|
}],
|
|
52
63
|
agents: skillInto(".agents/skills/cappa"),
|
|
53
|
-
opencode: [
|
|
54
|
-
"
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
64
|
+
opencode: [
|
|
65
|
+
...skillInto(".agents/skills/cappa"),
|
|
66
|
+
...[
|
|
67
|
+
"commands/cappa-review.md",
|
|
68
|
+
"commands/cappa-judge.md",
|
|
69
|
+
"commands/cappa-approve.md"
|
|
70
|
+
].map((file) => ({
|
|
71
|
+
source: `opencode/${file}`,
|
|
72
|
+
target: path.join(".opencode", file)
|
|
73
|
+
})),
|
|
74
|
+
{
|
|
75
|
+
source: "opencode/agents/cappa-judge.md",
|
|
76
|
+
target: path.join(".opencode", "agents", "cappa-judge.md"),
|
|
77
|
+
judge: "opencode"
|
|
78
|
+
}
|
|
79
|
+
]
|
|
62
80
|
};
|
|
63
81
|
const SKILL_STACK_NAMES = Object.keys(STACK_FILES);
|
|
64
82
|
/**
|
|
@@ -164,25 +182,64 @@ const detectCappaRunner = (root, cwd = root) => {
|
|
|
164
182
|
/** Fill the `{{cappa}}` placeholder in a source file. */
|
|
165
183
|
const renderIntegrationFile = (source, runner) => source.replaceAll("{{cappa}}", runner);
|
|
166
184
|
/**
|
|
185
|
+
* Which judge a model id is for: OpenCode names models `provider/model`,
|
|
186
|
+
* Claude Code takes an alias (`sonnet`) or a model id, neither with a slash.
|
|
187
|
+
*/
|
|
188
|
+
const judgeFormatOf = (model) => model.includes("/") ? "opencode" : "claude";
|
|
189
|
+
/** Pin a judge's model: a `model:` line at the top of its frontmatter. */
|
|
190
|
+
const withJudgeModel = (source, model) => source.replace(/^---\n/, `---\nmodel: ${model}\n`);
|
|
191
|
+
/** The model pinned in an installed judge, if any. */
|
|
192
|
+
const readJudgeModel = (source) => /^---\nmodel: (.*)\n/.exec(source)?.[1]?.trim() || void 0;
|
|
193
|
+
/** A judge file without its `model:` line, to tell a re-pin from an edit. */
|
|
194
|
+
const withoutJudgeModel = (source) => source.replace(/^(---\n)model: .*\n/, "$1");
|
|
195
|
+
/**
|
|
167
196
|
* Copy each stack's files into the project root (see `findProjectRoot`).
|
|
168
197
|
*
|
|
169
198
|
* A file that exists with different content is left alone unless `force` is
|
|
170
199
|
* set: users are expected to tailor these to their project, and an upgrade
|
|
171
200
|
* must not silently discard that. A target shared by two stacks (the
|
|
172
201
|
* `.agents` skill) is written once.
|
|
202
|
+
*
|
|
203
|
+
* `judgeModel` goes into the judge whose format it matches (see
|
|
204
|
+
* `judgeFormatOf`). Without it, a judge keeps the model it was pinned to.
|
|
205
|
+
* Changing only that model is not a modification: an installed judge that
|
|
206
|
+
* differs from the new one by its `model:` line alone is rewritten without
|
|
207
|
+
* `force`.
|
|
173
208
|
*/
|
|
174
209
|
const installAgentSkills = async (options) => {
|
|
175
210
|
const sourceDir = options.sourceDir ?? findIntegrationsDir();
|
|
176
211
|
const root = options.root ?? findProjectRoot(options.cwd);
|
|
177
212
|
const runner = options.runner ?? detectCappaRunner(root, options.cwd);
|
|
213
|
+
const judgeModel = options.judgeModel?.trim() || void 0;
|
|
214
|
+
const judgeFormats = options.stacks.flatMap((stack) => STACK_FILES[stack].flatMap((mapping) => mapping.judge ? [mapping.judge] : []));
|
|
215
|
+
if (judgeModel && !judgeFormats.includes(judgeFormatOf(judgeModel))) throw new Error(judgeFormatOf(judgeModel) === "opencode" ? `--judge-model "${judgeModel}" is an OpenCode model (provider/model), but no OpenCode judge is being installed — add --stack opencode` : `--judge-model "${judgeModel}" is a Claude Code model, but no Claude Code judge is being installed — OpenCode models are written provider/model, e.g. anthropic/claude-sonnet-5-5`);
|
|
216
|
+
const judgeModels = {};
|
|
217
|
+
if (judgeModel) judgeModels[judgeFormatOf(judgeModel)] = judgeModel;
|
|
218
|
+
const claudeSkillDir = path.resolve(root, ".claude/skills/cappa");
|
|
219
|
+
const hasClaudeSkill = options.stacks.includes("claude") || fs.existsSync(path.join(claudeSkillDir, "SKILL.md"));
|
|
220
|
+
const judgingFor = {
|
|
221
|
+
claude: CLAUDE_JUDGING,
|
|
222
|
+
opencode: hasClaudeSkill ? CLAUDE_JUDGING : AGENTS_JUDGING
|
|
223
|
+
};
|
|
178
224
|
const files = [];
|
|
179
225
|
const seen = /* @__PURE__ */ new Set();
|
|
180
226
|
for (const stack of options.stacks) for (const mapping of STACK_FILES[stack]) {
|
|
181
227
|
const target = path.resolve(root, mapping.target);
|
|
182
228
|
if (seen.has(target)) continue;
|
|
183
229
|
seen.add(target);
|
|
184
|
-
const
|
|
230
|
+
const read = (file) => fsp.readFile(path.join(sourceDir, file), "utf8");
|
|
231
|
+
let template = await read(mapping.source);
|
|
232
|
+
if (mapping.judge) template = `${template}\n${await read(JUDGE_BODY)}`.replaceAll("{{judging}}", judgingFor[mapping.judge]);
|
|
233
|
+
const rendered = renderIntegrationFile(template, runner);
|
|
185
234
|
const existing = await fsp.readFile(target, "utf8").catch(() => void 0);
|
|
235
|
+
let source = rendered;
|
|
236
|
+
if (mapping.judge) {
|
|
237
|
+
const model = judgeModels[mapping.judge] ?? (existing === void 0 ? void 0 : readJudgeModel(existing));
|
|
238
|
+
if (model) {
|
|
239
|
+
judgeModels[mapping.judge] = model;
|
|
240
|
+
source = withJudgeModel(rendered, model);
|
|
241
|
+
}
|
|
242
|
+
}
|
|
186
243
|
if (existing === source) {
|
|
187
244
|
files.push({
|
|
188
245
|
stack,
|
|
@@ -191,7 +248,8 @@ const installAgentSkills = async (options) => {
|
|
|
191
248
|
});
|
|
192
249
|
continue;
|
|
193
250
|
}
|
|
194
|
-
|
|
251
|
+
const repinned = mapping.judge !== void 0 && existing !== void 0 && withoutJudgeModel(existing) === rendered;
|
|
252
|
+
if (existing !== void 0 && !options.force && !repinned) {
|
|
195
253
|
files.push({
|
|
196
254
|
stack,
|
|
197
255
|
path: target,
|
|
@@ -208,16 +266,106 @@ const installAgentSkills = async (options) => {
|
|
|
208
266
|
});
|
|
209
267
|
}
|
|
210
268
|
const warnings = [];
|
|
211
|
-
|
|
212
|
-
if (
|
|
269
|
+
if (options.stacks.includes("opencode") && hasClaudeSkill) warnings.push("OpenCode reads .claude/skills too, and uses that copy of the cappa skill over the one in .agents/skills — so its cappa-judge follows .claude/skills/cappa/JUDGING.md. Tailor that copy; keep .agents/skills in sync for other agents.");
|
|
270
|
+
if (judgeFormats.includes("opencode") && !judgeModels.opencode) warnings.push("The OpenCode cappa-judge runs on the calling model, so it cannot judge if that model cannot read images. Pin a vision model: --judge-model <provider/model>");
|
|
213
271
|
return {
|
|
214
272
|
root,
|
|
215
273
|
runner,
|
|
274
|
+
judgeModels,
|
|
216
275
|
files,
|
|
217
276
|
warnings
|
|
218
277
|
};
|
|
219
278
|
};
|
|
220
279
|
//#endregion
|
|
280
|
+
//#region src/utils/judgeGuard.ts
|
|
281
|
+
/**
|
|
282
|
+
* The shell commands the `cappa-judge` subagent may run.
|
|
283
|
+
*
|
|
284
|
+
* OpenCode enforces this with the judge's `permission.bash` patterns. Claude
|
|
285
|
+
* Code agent frontmatter cannot narrow Bash to commands, only run a
|
|
286
|
+
* `PreToolUse` hook — which calls `cappa agent guard`, and that calls this.
|
|
287
|
+
*/
|
|
288
|
+
const GIT_READ_ONLY = [
|
|
289
|
+
"diff",
|
|
290
|
+
"log",
|
|
291
|
+
"show",
|
|
292
|
+
"status"
|
|
293
|
+
];
|
|
294
|
+
const CAPPA_ALLOWED = ["check", "judge"];
|
|
295
|
+
/**
|
|
296
|
+
* Split a command the way a shell would, as far as the guard needs: words,
|
|
297
|
+
* with quotes removed. Returns a reason instead when the command does
|
|
298
|
+
* anything but run one program — chaining, pipes, redirects, substitution —
|
|
299
|
+
* since a prefix check alone would let `git diff; rm -rf .` through.
|
|
300
|
+
*
|
|
301
|
+
* Quoted text is literal, so a headline like "Price | Total misaligned"
|
|
302
|
+
* stays one argument; only `$(` and backticks are refused inside double
|
|
303
|
+
* quotes, because the shell still expands those.
|
|
304
|
+
*/
|
|
305
|
+
const splitCommand = (command) => {
|
|
306
|
+
const words = [];
|
|
307
|
+
let word;
|
|
308
|
+
let quote;
|
|
309
|
+
for (let i = 0; i < command.length; i++) {
|
|
310
|
+
const char = command[i];
|
|
311
|
+
const next = command[i + 1];
|
|
312
|
+
if (quote === "'") {
|
|
313
|
+
if (char === "'") quote = void 0;
|
|
314
|
+
else word += char;
|
|
315
|
+
continue;
|
|
316
|
+
}
|
|
317
|
+
if (quote === "\"") {
|
|
318
|
+
if (char === "\"") quote = void 0;
|
|
319
|
+
else if (char === "`" || char === "$" && next === "(") return { reason: "command substitution is not allowed" };
|
|
320
|
+
else if (char === "\\" && next !== void 0) {
|
|
321
|
+
word += next;
|
|
322
|
+
i++;
|
|
323
|
+
} else word += char;
|
|
324
|
+
continue;
|
|
325
|
+
}
|
|
326
|
+
if (char === "'" || char === "\"") {
|
|
327
|
+
quote = char;
|
|
328
|
+
word ??= "";
|
|
329
|
+
} else if (char === "\\" && next === "\n") i++;
|
|
330
|
+
else if (char === "\\" && next !== void 0) {
|
|
331
|
+
word = (word ?? "") + next;
|
|
332
|
+
i++;
|
|
333
|
+
} else if (char === " " || char === " ") {
|
|
334
|
+
if (word !== void 0) words.push(word);
|
|
335
|
+
word = void 0;
|
|
336
|
+
} else if (";&|<>`\n".includes(char) || char === "$" && next === "(") return { reason: "run one command at a time — no chaining, pipes, redirects or substitution" };
|
|
337
|
+
else word = (word ?? "") + char;
|
|
338
|
+
}
|
|
339
|
+
if (quote) return { reason: "unterminated quote" };
|
|
340
|
+
if (word !== void 0) words.push(word);
|
|
341
|
+
return { words };
|
|
342
|
+
};
|
|
343
|
+
/**
|
|
344
|
+
* Why the judge may not run `command`, or `undefined` when it may.
|
|
345
|
+
*
|
|
346
|
+
* `runner` is how the project runs cappa (`pnpm exec cappa`); the judge's
|
|
347
|
+
* cappa calls must start with exactly those words.
|
|
348
|
+
*/
|
|
349
|
+
const judgeCommandRefusal = (command, runner) => {
|
|
350
|
+
const split = splitCommand(command.trim());
|
|
351
|
+
if ("reason" in split) return split.reason;
|
|
352
|
+
const { words } = split;
|
|
353
|
+
const prefix = runner.trim().split(/\s+/);
|
|
354
|
+
const allowed = `only \`${runner} agent ${CAPPA_ALLOWED.join("|")}\` and \`git ${GIT_READ_ONLY.join("|")}\``;
|
|
355
|
+
if (words[0] === "git") {
|
|
356
|
+
const sub = words[1] === "--no-pager" ? words[2] : words[1];
|
|
357
|
+
if (GIT_READ_ONLY.includes(sub ?? "")) {
|
|
358
|
+
if (words.some((w) => w === "--output" || w.startsWith("--output="))) return "`--output` writes a file";
|
|
359
|
+
return;
|
|
360
|
+
}
|
|
361
|
+
return `the judge may run ${allowed}`;
|
|
362
|
+
}
|
|
363
|
+
const isCappa = prefix.every((w, i) => words[i] === w);
|
|
364
|
+
const [agent, sub] = words.slice(prefix.length);
|
|
365
|
+
if (isCappa && agent === "agent" && CAPPA_ALLOWED.includes(sub ?? "")) return;
|
|
366
|
+
return `the judge may run ${allowed}`;
|
|
367
|
+
};
|
|
368
|
+
//#endregion
|
|
221
369
|
//#region src/commands/agent.ts
|
|
222
370
|
const printJson = (value) => {
|
|
223
371
|
process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
|
|
@@ -337,24 +485,49 @@ const agentApprove = (names, options) => run$1(options, async () => {
|
|
|
337
485
|
else if (approved.length === 0) getLogger().warn("No screenshots matched");
|
|
338
486
|
else getLogger().success(`Approved ${approved.length} screenshot(s): ${approved.map((s) => s.name).join(", ")}`);
|
|
339
487
|
});
|
|
488
|
+
/**
|
|
489
|
+
* Advice about the config the skill will run against. Read-only: `agent init`
|
|
490
|
+
* installs skill files and never edits `cappa.config.ts`.
|
|
491
|
+
*
|
|
492
|
+
* Without a `webServer` the skill still works, but the agent has to get the
|
|
493
|
+
* app under test running by itself — which is exactly the project-specific
|
|
494
|
+
* guesswork `webServer` exists to remove.
|
|
495
|
+
*/
|
|
496
|
+
const webServerHints = async (cwd) => {
|
|
497
|
+
let config;
|
|
498
|
+
try {
|
|
499
|
+
config = await getConfig(void 0, {
|
|
500
|
+
cwd,
|
|
501
|
+
command: "agent"
|
|
502
|
+
});
|
|
503
|
+
} catch {
|
|
504
|
+
return [];
|
|
505
|
+
}
|
|
506
|
+
if (config.webServer.length > 0) return [];
|
|
507
|
+
return ["cappa.config.ts has no `webServer`, so the agent has to start whatever the plugins point at itself. Add one and `cappa capture` starts and stops it: webServer: { command: \"pnpm storybook --ci\", url: \"http://localhost:6006\" }"];
|
|
508
|
+
};
|
|
340
509
|
const agentInit = (options) => run$1(options, async () => {
|
|
341
510
|
const cwd = process.cwd();
|
|
342
511
|
const root = findProjectRoot(cwd);
|
|
343
512
|
const stacks = options.stack === "all" ? SKILL_STACK_NAMES : options.stack ? [options.stack] : detectSkillStacks(root);
|
|
344
|
-
const { runner, files, warnings } = await installAgentSkills({
|
|
513
|
+
const { runner, judgeModels, files, warnings } = await installAgentSkills({
|
|
345
514
|
cwd,
|
|
346
515
|
root,
|
|
347
516
|
stacks,
|
|
348
517
|
force: options.force,
|
|
349
|
-
runner: options.runner
|
|
518
|
+
runner: options.runner,
|
|
519
|
+
judgeModel: options.judgeModel
|
|
350
520
|
});
|
|
521
|
+
const hints = await webServerHints(cwd);
|
|
351
522
|
if (options.json) {
|
|
352
523
|
printJson({
|
|
353
524
|
root,
|
|
354
525
|
stacks,
|
|
355
526
|
runner,
|
|
527
|
+
judgeModels,
|
|
356
528
|
files,
|
|
357
|
-
warnings
|
|
529
|
+
warnings,
|
|
530
|
+
hints
|
|
358
531
|
});
|
|
359
532
|
return;
|
|
360
533
|
}
|
|
@@ -368,9 +541,40 @@ const agentInit = (options) => run$1(options, async () => {
|
|
|
368
541
|
logger.log(`${verb} ${file.path}`);
|
|
369
542
|
}
|
|
370
543
|
logger.log(chalk.dim(`commands run as \`${runner}\` (--runner to change)`));
|
|
544
|
+
for (const [stack, model] of Object.entries(judgeModels)) logger.log(chalk.dim(`${stack} cappa-judge runs on \`${model}\``));
|
|
371
545
|
for (const warning of warnings) logger.warn(warning);
|
|
546
|
+
for (const hint of hints) logger.info(hint);
|
|
372
547
|
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");
|
|
373
548
|
});
|
|
549
|
+
const readStdin = async (stream = process.stdin) => {
|
|
550
|
+
const chunks = [];
|
|
551
|
+
for await (const chunk of stream) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
|
|
552
|
+
return Buffer.concat(chunks).toString("utf8");
|
|
553
|
+
};
|
|
554
|
+
/**
|
|
555
|
+
* Decide a Claude Code `PreToolUse` hook call for the `cappa-judge`
|
|
556
|
+
* subagent: `undefined` lets the Bash command run, a message blocks it.
|
|
557
|
+
* Anything it cannot read is blocked too — a guard that fails open is no
|
|
558
|
+
* guard.
|
|
559
|
+
*/
|
|
560
|
+
const judgeGuardVerdict = (input, runner) => {
|
|
561
|
+
let command;
|
|
562
|
+
try {
|
|
563
|
+
command = JSON.parse(input)?.tool_input?.command;
|
|
564
|
+
} catch {
|
|
565
|
+
return "cappa-judge: could not read the hook input";
|
|
566
|
+
}
|
|
567
|
+
if (typeof command !== "string") return "cappa-judge: could not read the hook input";
|
|
568
|
+
const refusal = judgeCommandRefusal(command, runner);
|
|
569
|
+
return refusal ? `cappa-judge: ${refusal}` : void 0;
|
|
570
|
+
};
|
|
571
|
+
const agentGuard = async (options) => {
|
|
572
|
+
const message = judgeGuardVerdict(await readStdin(), options.runner);
|
|
573
|
+
if (message) {
|
|
574
|
+
process.stderr.write(`${message}\n`);
|
|
575
|
+
process.exitCode = 2;
|
|
576
|
+
}
|
|
577
|
+
};
|
|
374
578
|
const parseChoice = (choices, what) => (value) => {
|
|
375
579
|
if (!choices.includes(value)) throw new InvalidArgumentError(`${what} must be one of: ${choices.join(", ")}`);
|
|
376
580
|
return value;
|
|
@@ -395,7 +599,8 @@ const registerAgentCommand = (program) => {
|
|
|
395
599
|
agent.command("check").description("Label every changed screenshot and write judgment requests for an agent (does not capture)").option("--judge <mode>", `which changes get a judgment request: ${JUDGE_MODES.join(", ")}`, parseChoice(JUDGE_MODES, "--judge"), "ambiguous").option("--max-tile-regions <count>", "regions rendered into each regions.png", parsePositiveInt).option("--json", "print a JSON summary to stdout").action(agentCheck);
|
|
396
600
|
agent.command("judge").description("Record a verdict for screenshots with a judgment request").argument("<names...>", "screenshot names, exactly as reported").requiredOption("--label <label>", JUDGED_LABELS.join(" | "), parseLabel).requiredOption("--headline <text>", "one line describing the change").option("--rationale <text...>", "reasons for the verdict").option("--confidence <number>", "0 to 1", parseConfidence).option("--json", "print a JSON summary to stdout").action(agentJudge);
|
|
397
601
|
agent.command("approve").description("Approve screenshots by exact name or by verdict label (refused in CI)").argument("[names...]", "screenshot names, exactly as reported").option("--label <label>", "also approve every changed screenshot with this verdict label (repeatable)", collectLabel).option("--allow-regression", "approve screenshots whose current verdict is regression-likely").option("--json", "print a JSON summary to stdout").action(agentApprove);
|
|
398
|
-
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);
|
|
602
|
+
agent.command("init").description("Install the cappa skill for coding agents in this project").option("--stack <stack>", `${SKILL_STACK_NAMES.join(", ")} or all (default: detected)`, parseChoice([...SKILL_STACK_NAMES, "all"], "--stack")).option("--force", "overwrite skill files that were modified").option("--runner <command>", "how the project runs cappa, e.g. `pnpm exec cappa` (default: from the lockfile)").option("--judge-model <model>", "pin the cappa-judge subagent to a model that can read images: provider/model for OpenCode, an alias or model id for Claude Code (default: the calling model)").option("--json", "print a JSON summary to stdout").action(agentInit);
|
|
603
|
+
agent.command("guard", { hidden: true }).description("Allow or block a cappa-judge Bash call (Claude Code hook)").requiredOption("--runner <command>", "how the project runs cappa").action(agentGuard);
|
|
399
604
|
};
|
|
400
605
|
//#endregion
|
|
401
606
|
//#region src/commands/approve.ts
|
|
@@ -460,6 +665,20 @@ const toCaptureError = (failure) => {
|
|
|
460
665
|
error: "no screenshot was produced"
|
|
461
666
|
};
|
|
462
667
|
};
|
|
668
|
+
/**
|
|
669
|
+
* Fold errors with the same plugin and message into one, keeping the first
|
|
670
|
+
* task and counting the rest. Order follows each message's first occurrence.
|
|
671
|
+
*/
|
|
672
|
+
const collapseIdenticalErrors = (errors) => {
|
|
673
|
+
const collapsed = /* @__PURE__ */ new Map();
|
|
674
|
+
for (const error of errors) {
|
|
675
|
+
const key = `${error.plugin}\u0000${error.error}`;
|
|
676
|
+
const existing = collapsed.get(key);
|
|
677
|
+
if (existing) existing.count = (existing.count ?? 1) + 1;
|
|
678
|
+
else collapsed.set(key, { ...error });
|
|
679
|
+
}
|
|
680
|
+
return [...collapsed.values()];
|
|
681
|
+
};
|
|
463
682
|
const buildCaptureJsonReport = ({ detail, screenshots, durationMs }) => {
|
|
464
683
|
const failures = detail?.failures ?? [];
|
|
465
684
|
const deleted = detail?.deletedScreenshots ?? [];
|
|
@@ -476,10 +695,10 @@ const buildCaptureJsonReport = ({ detail, screenshots, durationMs }) => {
|
|
|
476
695
|
...s.diffMeta?.percentDifference !== void 0 ? { percentDifference: s.diffMeta.percentDifference } : {}
|
|
477
696
|
};
|
|
478
697
|
});
|
|
479
|
-
const errors = failures.flatMap((failure) => {
|
|
698
|
+
const errors = collapseIdenticalErrors(failures.flatMap((failure) => {
|
|
480
699
|
const error = toCaptureError(failure);
|
|
481
700
|
return error ? [error] : [];
|
|
482
|
-
});
|
|
701
|
+
}));
|
|
483
702
|
return {
|
|
484
703
|
ok: failures.length === 0 && deleted.length === 0,
|
|
485
704
|
...detail ? { runId: detail.id } : {},
|
|
@@ -798,6 +1017,11 @@ function formatDuration(ms) {
|
|
|
798
1017
|
if (minutes > 0) return `${minutes}m ${remainingSeconds}s`;
|
|
799
1018
|
return `${(ms / 1e3).toFixed(2)}s`;
|
|
800
1019
|
}
|
|
1020
|
+
const errorMessageOf = (error) => {
|
|
1021
|
+
if (!error) return;
|
|
1022
|
+
if (typeof error === "string") return error;
|
|
1023
|
+
return error instanceof Error ? error.message : String(error);
|
|
1024
|
+
};
|
|
801
1025
|
function generateFailureReportMessage(failedScreenshots, deletedScreenshots) {
|
|
802
1026
|
const total = failedScreenshots.length + deletedScreenshots.length;
|
|
803
1027
|
if (total === 0) return "";
|
|
@@ -811,14 +1035,25 @@ function generateFailureReportMessage(failedScreenshots, deletedScreenshots) {
|
|
|
811
1035
|
}
|
|
812
1036
|
for (const [pluginName, failures] of byPlugin.entries()) {
|
|
813
1037
|
lines.push(`\n${chalk.bold(`Plugin: ${pluginName}`)}`);
|
|
1038
|
+
const byError = /* @__PURE__ */ new Map();
|
|
814
1039
|
for (const failed of failures) {
|
|
1040
|
+
const message = errorMessageOf(failed.result.error);
|
|
1041
|
+
if (message !== void 0) byError.set(message, [...byError.get(message) ?? [], failed]);
|
|
1042
|
+
}
|
|
1043
|
+
for (const [message, shared] of byError) {
|
|
1044
|
+
if (shared.length < 2) continue;
|
|
1045
|
+
const shown = shared.slice(0, 3).map((failed) => failed.taskId);
|
|
1046
|
+
const more = shared.length - shown.length;
|
|
1047
|
+
lines.push(`\n ${chalk.dim("Tasks:")} ${shown.join(", ")}${more > 0 ? ` and ${more} more` : ""}`);
|
|
1048
|
+
lines.push(` ${chalk.red("Error:")} ${message}`);
|
|
1049
|
+
}
|
|
1050
|
+
for (const failed of failures) {
|
|
1051
|
+
const errorMsg = errorMessageOf(failed.result.error);
|
|
1052
|
+
if (errorMsg !== void 0 && (byError.get(errorMsg)?.length ?? 0) > 1) continue;
|
|
815
1053
|
lines.push(`\n ${chalk.dim("Task ID:")} ${failed.taskId}`);
|
|
816
1054
|
const result = failed.result;
|
|
817
1055
|
if (result.storyName) lines.push(` ${chalk.dim("Story:")} ${result.storyName}`);
|
|
818
|
-
if (
|
|
819
|
-
const errorMsg = typeof result.error === "string" ? result.error : result.error instanceof Error ? result.error.message : String(result.error);
|
|
820
|
-
lines.push(` ${chalk.red("Error:")} ${errorMsg}`);
|
|
821
|
-
}
|
|
1056
|
+
if (errorMsg !== void 0) lines.push(` ${chalk.red("Error:")} ${errorMsg}`);
|
|
822
1057
|
if (result.success === false) {
|
|
823
1058
|
if (result.isNew) lines.push(` ${chalk.yellow("Status:")} New screenshot (no baseline — run 'cappa approve' to accept)`);
|
|
824
1059
|
else lines.push(` ${chalk.red("Status:")} Failed (comparison failed)`);
|