@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.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.16.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: [...skillInto(".agents/skills/cappa"), ...[
54
- "commands/cappa-review.md",
55
- "commands/cappa-judge.md",
56
- "commands/cappa-approve.md",
57
- "agents/cappa-judge.md"
58
- ].map((file) => ({
59
- source: `opencode/${file}`,
60
- target: path.join(".opencode", file)
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 source = renderIntegrationFile(await fsp.readFile(path.join(sourceDir, mapping.source), "utf8"), runner);
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
- if (existing !== void 0 && !options.force) {
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
- const claudeSkill = fs.existsSync(path.resolve(root, ".claude/skills/cappa/SKILL.md"));
212
- if (options.stacks.includes("opencode") && claudeSkill) warnings.push("OpenCode reads .claude/skills too, and uses that copy of the cappa skill over the one in .agents/skills — keep the two in sync if you tailor them.");
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`);
@@ -362,12 +510,13 @@ const agentInit = (options) => run$1(options, async () => {
362
510
  const cwd = process.cwd();
363
511
  const root = findProjectRoot(cwd);
364
512
  const stacks = options.stack === "all" ? SKILL_STACK_NAMES : options.stack ? [options.stack] : detectSkillStacks(root);
365
- const { runner, files, warnings } = await installAgentSkills({
513
+ const { runner, judgeModels, files, warnings } = await installAgentSkills({
366
514
  cwd,
367
515
  root,
368
516
  stacks,
369
517
  force: options.force,
370
- runner: options.runner
518
+ runner: options.runner,
519
+ judgeModel: options.judgeModel
371
520
  });
372
521
  const hints = await webServerHints(cwd);
373
522
  if (options.json) {
@@ -375,6 +524,7 @@ const agentInit = (options) => run$1(options, async () => {
375
524
  root,
376
525
  stacks,
377
526
  runner,
527
+ judgeModels,
378
528
  files,
379
529
  warnings,
380
530
  hints
@@ -391,10 +541,40 @@ const agentInit = (options) => run$1(options, async () => {
391
541
  logger.log(`${verb} ${file.path}`);
392
542
  }
393
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}\``));
394
545
  for (const warning of warnings) logger.warn(warning);
395
546
  for (const hint of hints) logger.info(hint);
396
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");
397
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
+ };
398
578
  const parseChoice = (choices, what) => (value) => {
399
579
  if (!choices.includes(value)) throw new InvalidArgumentError(`${what} must be one of: ${choices.join(", ")}`);
400
580
  return value;
@@ -419,7 +599,8 @@ const registerAgentCommand = (program) => {
419
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);
420
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);
421
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);
422
- 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);
423
604
  };
424
605
  //#endregion
425
606
  //#region src/commands/approve.ts