@cappa/cli 0.16.0 → 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 +199 -18
- package/dist/index.cjs.map +1 -1
- package/dist/index.mjs +199 -18
- 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 +4 -6
- package/package.json +2 -2
package/dist/index.cjs
CHANGED
|
@@ -38,7 +38,7 @@ let _cappa_client = require("@cappa/client");
|
|
|
38
38
|
let _cappa_server = require("@cappa/server");
|
|
39
39
|
let node_crypto = require("node:crypto");
|
|
40
40
|
//#region package.json
|
|
41
|
-
var version = "0.
|
|
41
|
+
var version = "0.17.0";
|
|
42
42
|
//#endregion
|
|
43
43
|
//#region src/utils/agentSkills.ts
|
|
44
44
|
/**
|
|
@@ -61,6 +61,16 @@ const SKILL = [
|
|
|
61
61
|
"skills/cappa/JUDGING.md",
|
|
62
62
|
"skills/cappa/MASKING.md"
|
|
63
63
|
];
|
|
64
|
+
/**
|
|
65
|
+
* Both judges share one body; their own source files are only the
|
|
66
|
+
* frontmatter each agent needs. The body points at the copy of `JUDGING.md`
|
|
67
|
+
* the agent's caller reads — for OpenCode that is the `.claude` copy when
|
|
68
|
+
* there is one, since OpenCode prefers it over `.agents` (see the warning in
|
|
69
|
+
* `installAgentSkills`), and judge and caller must not follow two copies.
|
|
70
|
+
*/
|
|
71
|
+
const JUDGE_BODY = "judge/cappa-judge.md";
|
|
72
|
+
const CLAUDE_JUDGING = ".claude/skills/cappa/JUDGING.md";
|
|
73
|
+
const AGENTS_JUDGING = ".agents/skills/cappa/JUDGING.md";
|
|
64
74
|
const skillInto = (dir) => SKILL.map((source) => ({
|
|
65
75
|
source,
|
|
66
76
|
target: node_path.default.join(dir, node_path.default.basename(source))
|
|
@@ -68,18 +78,26 @@ const skillInto = (dir) => SKILL.map((source) => ({
|
|
|
68
78
|
const STACK_FILES = {
|
|
69
79
|
claude: [...skillInto(".claude/skills/cappa"), {
|
|
70
80
|
source: "claude/agents/cappa-judge.md",
|
|
71
|
-
target: node_path.default.join(".claude", "agents", "cappa-judge.md")
|
|
81
|
+
target: node_path.default.join(".claude", "agents", "cappa-judge.md"),
|
|
82
|
+
judge: "claude"
|
|
72
83
|
}],
|
|
73
84
|
agents: skillInto(".agents/skills/cappa"),
|
|
74
|
-
opencode: [
|
|
75
|
-
"
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
85
|
+
opencode: [
|
|
86
|
+
...skillInto(".agents/skills/cappa"),
|
|
87
|
+
...[
|
|
88
|
+
"commands/cappa-review.md",
|
|
89
|
+
"commands/cappa-judge.md",
|
|
90
|
+
"commands/cappa-approve.md"
|
|
91
|
+
].map((file) => ({
|
|
92
|
+
source: `opencode/${file}`,
|
|
93
|
+
target: node_path.default.join(".opencode", file)
|
|
94
|
+
})),
|
|
95
|
+
{
|
|
96
|
+
source: "opencode/agents/cappa-judge.md",
|
|
97
|
+
target: node_path.default.join(".opencode", "agents", "cappa-judge.md"),
|
|
98
|
+
judge: "opencode"
|
|
99
|
+
}
|
|
100
|
+
]
|
|
83
101
|
};
|
|
84
102
|
const SKILL_STACK_NAMES = Object.keys(STACK_FILES);
|
|
85
103
|
/**
|
|
@@ -185,25 +203,64 @@ const detectCappaRunner = (root, cwd = root) => {
|
|
|
185
203
|
/** Fill the `{{cappa}}` placeholder in a source file. */
|
|
186
204
|
const renderIntegrationFile = (source, runner) => source.replaceAll("{{cappa}}", runner);
|
|
187
205
|
/**
|
|
206
|
+
* Which judge a model id is for: OpenCode names models `provider/model`,
|
|
207
|
+
* Claude Code takes an alias (`sonnet`) or a model id, neither with a slash.
|
|
208
|
+
*/
|
|
209
|
+
const judgeFormatOf = (model) => model.includes("/") ? "opencode" : "claude";
|
|
210
|
+
/** Pin a judge's model: a `model:` line at the top of its frontmatter. */
|
|
211
|
+
const withJudgeModel = (source, model) => source.replace(/^---\n/, `---\nmodel: ${model}\n`);
|
|
212
|
+
/** The model pinned in an installed judge, if any. */
|
|
213
|
+
const readJudgeModel = (source) => /^---\nmodel: (.*)\n/.exec(source)?.[1]?.trim() || void 0;
|
|
214
|
+
/** A judge file without its `model:` line, to tell a re-pin from an edit. */
|
|
215
|
+
const withoutJudgeModel = (source) => source.replace(/^(---\n)model: .*\n/, "$1");
|
|
216
|
+
/**
|
|
188
217
|
* Copy each stack's files into the project root (see `findProjectRoot`).
|
|
189
218
|
*
|
|
190
219
|
* A file that exists with different content is left alone unless `force` is
|
|
191
220
|
* set: users are expected to tailor these to their project, and an upgrade
|
|
192
221
|
* must not silently discard that. A target shared by two stacks (the
|
|
193
222
|
* `.agents` skill) is written once.
|
|
223
|
+
*
|
|
224
|
+
* `judgeModel` goes into the judge whose format it matches (see
|
|
225
|
+
* `judgeFormatOf`). Without it, a judge keeps the model it was pinned to.
|
|
226
|
+
* Changing only that model is not a modification: an installed judge that
|
|
227
|
+
* differs from the new one by its `model:` line alone is rewritten without
|
|
228
|
+
* `force`.
|
|
194
229
|
*/
|
|
195
230
|
const installAgentSkills = async (options) => {
|
|
196
231
|
const sourceDir = options.sourceDir ?? findIntegrationsDir();
|
|
197
232
|
const root = options.root ?? findProjectRoot(options.cwd);
|
|
198
233
|
const runner = options.runner ?? detectCappaRunner(root, options.cwd);
|
|
234
|
+
const judgeModel = options.judgeModel?.trim() || void 0;
|
|
235
|
+
const judgeFormats = options.stacks.flatMap((stack) => STACK_FILES[stack].flatMap((mapping) => mapping.judge ? [mapping.judge] : []));
|
|
236
|
+
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`);
|
|
237
|
+
const judgeModels = {};
|
|
238
|
+
if (judgeModel) judgeModels[judgeFormatOf(judgeModel)] = judgeModel;
|
|
239
|
+
const claudeSkillDir = node_path.default.resolve(root, ".claude/skills/cappa");
|
|
240
|
+
const hasClaudeSkill = options.stacks.includes("claude") || node_fs.default.existsSync(node_path.default.join(claudeSkillDir, "SKILL.md"));
|
|
241
|
+
const judgingFor = {
|
|
242
|
+
claude: CLAUDE_JUDGING,
|
|
243
|
+
opencode: hasClaudeSkill ? CLAUDE_JUDGING : AGENTS_JUDGING
|
|
244
|
+
};
|
|
199
245
|
const files = [];
|
|
200
246
|
const seen = /* @__PURE__ */ new Set();
|
|
201
247
|
for (const stack of options.stacks) for (const mapping of STACK_FILES[stack]) {
|
|
202
248
|
const target = node_path.default.resolve(root, mapping.target);
|
|
203
249
|
if (seen.has(target)) continue;
|
|
204
250
|
seen.add(target);
|
|
205
|
-
const
|
|
251
|
+
const read = (file) => node_fs_promises.default.readFile(node_path.default.join(sourceDir, file), "utf8");
|
|
252
|
+
let template = await read(mapping.source);
|
|
253
|
+
if (mapping.judge) template = `${template}\n${await read(JUDGE_BODY)}`.replaceAll("{{judging}}", judgingFor[mapping.judge]);
|
|
254
|
+
const rendered = renderIntegrationFile(template, runner);
|
|
206
255
|
const existing = await node_fs_promises.default.readFile(target, "utf8").catch(() => void 0);
|
|
256
|
+
let source = rendered;
|
|
257
|
+
if (mapping.judge) {
|
|
258
|
+
const model = judgeModels[mapping.judge] ?? (existing === void 0 ? void 0 : readJudgeModel(existing));
|
|
259
|
+
if (model) {
|
|
260
|
+
judgeModels[mapping.judge] = model;
|
|
261
|
+
source = withJudgeModel(rendered, model);
|
|
262
|
+
}
|
|
263
|
+
}
|
|
207
264
|
if (existing === source) {
|
|
208
265
|
files.push({
|
|
209
266
|
stack,
|
|
@@ -212,7 +269,8 @@ const installAgentSkills = async (options) => {
|
|
|
212
269
|
});
|
|
213
270
|
continue;
|
|
214
271
|
}
|
|
215
|
-
|
|
272
|
+
const repinned = mapping.judge !== void 0 && existing !== void 0 && withoutJudgeModel(existing) === rendered;
|
|
273
|
+
if (existing !== void 0 && !options.force && !repinned) {
|
|
216
274
|
files.push({
|
|
217
275
|
stack,
|
|
218
276
|
path: target,
|
|
@@ -229,16 +287,106 @@ const installAgentSkills = async (options) => {
|
|
|
229
287
|
});
|
|
230
288
|
}
|
|
231
289
|
const warnings = [];
|
|
232
|
-
|
|
233
|
-
if (
|
|
290
|
+
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.");
|
|
291
|
+
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>");
|
|
234
292
|
return {
|
|
235
293
|
root,
|
|
236
294
|
runner,
|
|
295
|
+
judgeModels,
|
|
237
296
|
files,
|
|
238
297
|
warnings
|
|
239
298
|
};
|
|
240
299
|
};
|
|
241
300
|
//#endregion
|
|
301
|
+
//#region src/utils/judgeGuard.ts
|
|
302
|
+
/**
|
|
303
|
+
* The shell commands the `cappa-judge` subagent may run.
|
|
304
|
+
*
|
|
305
|
+
* OpenCode enforces this with the judge's `permission.bash` patterns. Claude
|
|
306
|
+
* Code agent frontmatter cannot narrow Bash to commands, only run a
|
|
307
|
+
* `PreToolUse` hook — which calls `cappa agent guard`, and that calls this.
|
|
308
|
+
*/
|
|
309
|
+
const GIT_READ_ONLY = [
|
|
310
|
+
"diff",
|
|
311
|
+
"log",
|
|
312
|
+
"show",
|
|
313
|
+
"status"
|
|
314
|
+
];
|
|
315
|
+
const CAPPA_ALLOWED = ["check", "judge"];
|
|
316
|
+
/**
|
|
317
|
+
* Split a command the way a shell would, as far as the guard needs: words,
|
|
318
|
+
* with quotes removed. Returns a reason instead when the command does
|
|
319
|
+
* anything but run one program — chaining, pipes, redirects, substitution —
|
|
320
|
+
* since a prefix check alone would let `git diff; rm -rf .` through.
|
|
321
|
+
*
|
|
322
|
+
* Quoted text is literal, so a headline like "Price | Total misaligned"
|
|
323
|
+
* stays one argument; only `$(` and backticks are refused inside double
|
|
324
|
+
* quotes, because the shell still expands those.
|
|
325
|
+
*/
|
|
326
|
+
const splitCommand = (command) => {
|
|
327
|
+
const words = [];
|
|
328
|
+
let word;
|
|
329
|
+
let quote;
|
|
330
|
+
for (let i = 0; i < command.length; i++) {
|
|
331
|
+
const char = command[i];
|
|
332
|
+
const next = command[i + 1];
|
|
333
|
+
if (quote === "'") {
|
|
334
|
+
if (char === "'") quote = void 0;
|
|
335
|
+
else word += char;
|
|
336
|
+
continue;
|
|
337
|
+
}
|
|
338
|
+
if (quote === "\"") {
|
|
339
|
+
if (char === "\"") quote = void 0;
|
|
340
|
+
else if (char === "`" || char === "$" && next === "(") return { reason: "command substitution is not allowed" };
|
|
341
|
+
else if (char === "\\" && next !== void 0) {
|
|
342
|
+
word += next;
|
|
343
|
+
i++;
|
|
344
|
+
} else word += char;
|
|
345
|
+
continue;
|
|
346
|
+
}
|
|
347
|
+
if (char === "'" || char === "\"") {
|
|
348
|
+
quote = char;
|
|
349
|
+
word ??= "";
|
|
350
|
+
} else if (char === "\\" && next === "\n") i++;
|
|
351
|
+
else if (char === "\\" && next !== void 0) {
|
|
352
|
+
word = (word ?? "") + next;
|
|
353
|
+
i++;
|
|
354
|
+
} else if (char === " " || char === " ") {
|
|
355
|
+
if (word !== void 0) words.push(word);
|
|
356
|
+
word = void 0;
|
|
357
|
+
} else if (";&|<>`\n".includes(char) || char === "$" && next === "(") return { reason: "run one command at a time — no chaining, pipes, redirects or substitution" };
|
|
358
|
+
else word = (word ?? "") + char;
|
|
359
|
+
}
|
|
360
|
+
if (quote) return { reason: "unterminated quote" };
|
|
361
|
+
if (word !== void 0) words.push(word);
|
|
362
|
+
return { words };
|
|
363
|
+
};
|
|
364
|
+
/**
|
|
365
|
+
* Why the judge may not run `command`, or `undefined` when it may.
|
|
366
|
+
*
|
|
367
|
+
* `runner` is how the project runs cappa (`pnpm exec cappa`); the judge's
|
|
368
|
+
* cappa calls must start with exactly those words.
|
|
369
|
+
*/
|
|
370
|
+
const judgeCommandRefusal = (command, runner) => {
|
|
371
|
+
const split = splitCommand(command.trim());
|
|
372
|
+
if ("reason" in split) return split.reason;
|
|
373
|
+
const { words } = split;
|
|
374
|
+
const prefix = runner.trim().split(/\s+/);
|
|
375
|
+
const allowed = `only \`${runner} agent ${CAPPA_ALLOWED.join("|")}\` and \`git ${GIT_READ_ONLY.join("|")}\``;
|
|
376
|
+
if (words[0] === "git") {
|
|
377
|
+
const sub = words[1] === "--no-pager" ? words[2] : words[1];
|
|
378
|
+
if (GIT_READ_ONLY.includes(sub ?? "")) {
|
|
379
|
+
if (words.some((w) => w === "--output" || w.startsWith("--output="))) return "`--output` writes a file";
|
|
380
|
+
return;
|
|
381
|
+
}
|
|
382
|
+
return `the judge may run ${allowed}`;
|
|
383
|
+
}
|
|
384
|
+
const isCappa = prefix.every((w, i) => words[i] === w);
|
|
385
|
+
const [agent, sub] = words.slice(prefix.length);
|
|
386
|
+
if (isCappa && agent === "agent" && CAPPA_ALLOWED.includes(sub ?? "")) return;
|
|
387
|
+
return `the judge may run ${allowed}`;
|
|
388
|
+
};
|
|
389
|
+
//#endregion
|
|
242
390
|
//#region src/commands/agent.ts
|
|
243
391
|
const printJson = (value) => {
|
|
244
392
|
process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
|
|
@@ -383,12 +531,13 @@ const agentInit = (options) => run$1(options, async () => {
|
|
|
383
531
|
const cwd = process.cwd();
|
|
384
532
|
const root = findProjectRoot(cwd);
|
|
385
533
|
const stacks = options.stack === "all" ? SKILL_STACK_NAMES : options.stack ? [options.stack] : detectSkillStacks(root);
|
|
386
|
-
const { runner, files, warnings } = await installAgentSkills({
|
|
534
|
+
const { runner, judgeModels, files, warnings } = await installAgentSkills({
|
|
387
535
|
cwd,
|
|
388
536
|
root,
|
|
389
537
|
stacks,
|
|
390
538
|
force: options.force,
|
|
391
|
-
runner: options.runner
|
|
539
|
+
runner: options.runner,
|
|
540
|
+
judgeModel: options.judgeModel
|
|
392
541
|
});
|
|
393
542
|
const hints = await webServerHints(cwd);
|
|
394
543
|
if (options.json) {
|
|
@@ -396,6 +545,7 @@ const agentInit = (options) => run$1(options, async () => {
|
|
|
396
545
|
root,
|
|
397
546
|
stacks,
|
|
398
547
|
runner,
|
|
548
|
+
judgeModels,
|
|
399
549
|
files,
|
|
400
550
|
warnings,
|
|
401
551
|
hints
|
|
@@ -412,10 +562,40 @@ const agentInit = (options) => run$1(options, async () => {
|
|
|
412
562
|
logger.log(`${verb} ${file.path}`);
|
|
413
563
|
}
|
|
414
564
|
logger.log(chalk.default.dim(`commands run as \`${runner}\` (--runner to change)`));
|
|
565
|
+
for (const [stack, model] of Object.entries(judgeModels)) logger.log(chalk.default.dim(`${stack} cappa-judge runs on \`${model}\``));
|
|
415
566
|
for (const warning of warnings) logger.warn(warning);
|
|
416
567
|
for (const hint of hints) logger.info(hint);
|
|
417
568
|
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");
|
|
418
569
|
});
|
|
570
|
+
const readStdin = async (stream = process.stdin) => {
|
|
571
|
+
const chunks = [];
|
|
572
|
+
for await (const chunk of stream) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
|
|
573
|
+
return Buffer.concat(chunks).toString("utf8");
|
|
574
|
+
};
|
|
575
|
+
/**
|
|
576
|
+
* Decide a Claude Code `PreToolUse` hook call for the `cappa-judge`
|
|
577
|
+
* subagent: `undefined` lets the Bash command run, a message blocks it.
|
|
578
|
+
* Anything it cannot read is blocked too — a guard that fails open is no
|
|
579
|
+
* guard.
|
|
580
|
+
*/
|
|
581
|
+
const judgeGuardVerdict = (input, runner) => {
|
|
582
|
+
let command;
|
|
583
|
+
try {
|
|
584
|
+
command = JSON.parse(input)?.tool_input?.command;
|
|
585
|
+
} catch {
|
|
586
|
+
return "cappa-judge: could not read the hook input";
|
|
587
|
+
}
|
|
588
|
+
if (typeof command !== "string") return "cappa-judge: could not read the hook input";
|
|
589
|
+
const refusal = judgeCommandRefusal(command, runner);
|
|
590
|
+
return refusal ? `cappa-judge: ${refusal}` : void 0;
|
|
591
|
+
};
|
|
592
|
+
const agentGuard = async (options) => {
|
|
593
|
+
const message = judgeGuardVerdict(await readStdin(), options.runner);
|
|
594
|
+
if (message) {
|
|
595
|
+
process.stderr.write(`${message}\n`);
|
|
596
|
+
process.exitCode = 2;
|
|
597
|
+
}
|
|
598
|
+
};
|
|
419
599
|
const parseChoice = (choices, what) => (value) => {
|
|
420
600
|
if (!choices.includes(value)) throw new commander.InvalidArgumentError(`${what} must be one of: ${choices.join(", ")}`);
|
|
421
601
|
return value;
|
|
@@ -440,7 +620,8 @@ const registerAgentCommand = (program) => {
|
|
|
440
620
|
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: ${_cappa_core.JUDGE_MODES.join(", ")}`, parseChoice(_cappa_core.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);
|
|
441
621
|
agent.command("judge").description("Record a verdict for screenshots with a judgment request").argument("<names...>", "screenshot names, exactly as reported").requiredOption("--label <label>", _cappa_core.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);
|
|
442
622
|
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);
|
|
443
|
-
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);
|
|
623
|
+
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);
|
|
624
|
+
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);
|
|
444
625
|
};
|
|
445
626
|
//#endregion
|
|
446
627
|
//#region src/commands/approve.ts
|