@cappa/cli 0.14.0 → 0.15.1
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 +84 -18
- package/dist/index.cjs.map +1 -1
- package/dist/index.mjs +84 -18
- package/dist/index.mjs.map +1 -1
- package/integrations/claude/agents/cappa-judge.md +54 -0
- package/integrations/opencode/agents/cappa-judge.md +5 -2
- package/integrations/opencode/commands/cappa-approve.md +2 -0
- package/integrations/opencode/commands/cappa-review.md +7 -4
- package/integrations/skills/cappa/JUDGING.md +15 -2
- package/integrations/skills/cappa/SKILL.md +35 -11
- package/package.json +1 -1
package/dist/index.cjs
CHANGED
|
@@ -38,14 +38,15 @@ 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.15.1";
|
|
42
42
|
//#endregion
|
|
43
43
|
//#region src/utils/agentSkills.ts
|
|
44
44
|
/**
|
|
45
45
|
* Agent integrations `cappa agent init` can install, and the files each one
|
|
46
46
|
* gets.
|
|
47
47
|
*
|
|
48
|
-
* - `claude` — Claude Code: the skill in `.claude/skills/cappa
|
|
48
|
+
* - `claude` — Claude Code: the skill in `.claude/skills/cappa` plus a
|
|
49
|
+
* `cappa-judge` subagent that judges screenshots in its own context.
|
|
49
50
|
* - `agents` — the vendor-neutral Agent Skills directory `.agents/skills`,
|
|
50
51
|
* read by Codex, OpenCode and other agents that adopted it.
|
|
51
52
|
* - `opencode` — OpenCode: the `.agents` skill plus slash commands that run
|
|
@@ -65,7 +66,10 @@ const skillInto = (dir) => SKILL.map((source) => ({
|
|
|
65
66
|
target: node_path.default.join(dir, node_path.default.basename(source))
|
|
66
67
|
}));
|
|
67
68
|
const STACK_FILES = {
|
|
68
|
-
claude: skillInto(".claude/skills/cappa"),
|
|
69
|
+
claude: [...skillInto(".claude/skills/cappa"), {
|
|
70
|
+
source: "claude/agents/cappa-judge.md",
|
|
71
|
+
target: node_path.default.join(".claude", "agents", "cappa-judge.md")
|
|
72
|
+
}],
|
|
69
73
|
agents: skillInto(".agents/skills/cappa"),
|
|
70
74
|
opencode: [...skillInto(".agents/skills/cappa"), ...[
|
|
71
75
|
"commands/cappa-review.md",
|
|
@@ -110,6 +114,43 @@ const detectSkillStacks = (cwd) => {
|
|
|
110
114
|
else if (has(".agents") || has("AGENTS.md")) stacks.push("agents");
|
|
111
115
|
return stacks.length > 0 ? stacks : ["claude"];
|
|
112
116
|
};
|
|
117
|
+
const LOCKFILES = {
|
|
118
|
+
"pnpm-lock.yaml": "pnpm",
|
|
119
|
+
"yarn.lock": "yarn",
|
|
120
|
+
"bun.lock": "bun",
|
|
121
|
+
"bun.lockb": "bun",
|
|
122
|
+
"package-lock.json": "npm"
|
|
123
|
+
};
|
|
124
|
+
const detectPackageManager = (dir) => {
|
|
125
|
+
for (const [lockfile, manager] of Object.entries(LOCKFILES)) if (node_fs.default.existsSync(node_path.default.join(dir, lockfile))) return manager;
|
|
126
|
+
};
|
|
127
|
+
/**
|
|
128
|
+
* The directory agents work from: the workspace root holding the lockfile.
|
|
129
|
+
*
|
|
130
|
+
* `cappa` is often installed in a single workspace package and run with
|
|
131
|
+
* `pnpm -F <pkg> exec cappa`, which puts `cwd` inside that package — but
|
|
132
|
+
* agents only read `.claude/` and `.agents/` from the root they were started
|
|
133
|
+
* in. Walk up to the nearest lockfile or `pnpm-workspace.yaml`, without
|
|
134
|
+
* leaving the git repository; `cwd` itself when there is neither.
|
|
135
|
+
*/
|
|
136
|
+
const findProjectRoot = (cwd) => {
|
|
137
|
+
let current = node_path.default.resolve(cwd);
|
|
138
|
+
while (true) {
|
|
139
|
+
const has = (entry) => node_fs.default.existsSync(node_path.default.join(current, entry));
|
|
140
|
+
if (detectPackageManager(current) || has("pnpm-workspace.yaml")) return current;
|
|
141
|
+
const parent = node_path.default.dirname(current);
|
|
142
|
+
if (has(".git") || parent === current) return node_path.default.resolve(cwd);
|
|
143
|
+
current = parent;
|
|
144
|
+
}
|
|
145
|
+
};
|
|
146
|
+
const readPackageName = (dir) => {
|
|
147
|
+
try {
|
|
148
|
+
const { name } = JSON.parse(node_fs.default.readFileSync(node_path.default.join(dir, "package.json"), "utf8"));
|
|
149
|
+
return typeof name === "string" ? name : void 0;
|
|
150
|
+
} catch {
|
|
151
|
+
return;
|
|
152
|
+
}
|
|
153
|
+
};
|
|
113
154
|
/**
|
|
114
155
|
* How the project runs its own `cappa` binary, from its lockfile.
|
|
115
156
|
*
|
|
@@ -117,18 +158,34 @@ const detectSkillStacks = (cwd) => {
|
|
|
117
158
|
* commands *before* the model sees anything, so a bare `cappa` that is not on
|
|
118
159
|
* `PATH` would inject an error instead of the review state; and agent
|
|
119
160
|
* permission rules match the command text literally.
|
|
161
|
+
*
|
|
162
|
+
* When `cwd` is a package below `root`, the command switches into it: that is
|
|
163
|
+
* where `cappa` is installed and where `cappa.config.ts` lives, while agents
|
|
164
|
+
* run commands from the root.
|
|
120
165
|
*/
|
|
121
|
-
const detectCappaRunner = (cwd) => {
|
|
122
|
-
const
|
|
123
|
-
|
|
124
|
-
if (
|
|
125
|
-
|
|
126
|
-
|
|
166
|
+
const detectCappaRunner = (root, cwd = root) => {
|
|
167
|
+
const manager = detectPackageManager(root);
|
|
168
|
+
const dir = node_path.default.relative(root, cwd).split(node_path.default.sep).join("/");
|
|
169
|
+
if (!dir) return {
|
|
170
|
+
pnpm: "pnpm exec cappa",
|
|
171
|
+
yarn: "yarn cappa",
|
|
172
|
+
bun: "bunx cappa",
|
|
173
|
+
npm: "npx cappa"
|
|
174
|
+
}[manager ?? "npm"];
|
|
175
|
+
switch (manager) {
|
|
176
|
+
case "pnpm": return `pnpm -C ${dir} exec cappa`;
|
|
177
|
+
case "yarn": {
|
|
178
|
+
const name = readPackageName(cwd);
|
|
179
|
+
return name ? `yarn workspace ${name} cappa` : `yarn --cwd ${dir} cappa`;
|
|
180
|
+
}
|
|
181
|
+
case "bun": return `bun --cwd ${dir} x cappa`;
|
|
182
|
+
default: return `npm exec -w ${dir} -- cappa`;
|
|
183
|
+
}
|
|
127
184
|
};
|
|
128
185
|
/** Fill the `{{cappa}}` placeholder in a source file. */
|
|
129
186
|
const renderIntegrationFile = (source, runner) => source.replaceAll("{{cappa}}", runner);
|
|
130
187
|
/**
|
|
131
|
-
* Copy each stack's files into the project.
|
|
188
|
+
* Copy each stack's files into the project root (see `findProjectRoot`).
|
|
132
189
|
*
|
|
133
190
|
* A file that exists with different content is left alone unless `force` is
|
|
134
191
|
* set: users are expected to tailor these to their project, and an upgrade
|
|
@@ -137,11 +194,12 @@ const renderIntegrationFile = (source, runner) => source.replaceAll("{{cappa}}",
|
|
|
137
194
|
*/
|
|
138
195
|
const installAgentSkills = async (options) => {
|
|
139
196
|
const sourceDir = options.sourceDir ?? findIntegrationsDir();
|
|
140
|
-
const
|
|
197
|
+
const root = options.root ?? findProjectRoot(options.cwd);
|
|
198
|
+
const runner = options.runner ?? detectCappaRunner(root, options.cwd);
|
|
141
199
|
const files = [];
|
|
142
200
|
const seen = /* @__PURE__ */ new Set();
|
|
143
201
|
for (const stack of options.stacks) for (const mapping of STACK_FILES[stack]) {
|
|
144
|
-
const target = node_path.default.resolve(
|
|
202
|
+
const target = node_path.default.resolve(root, mapping.target);
|
|
145
203
|
if (seen.has(target)) continue;
|
|
146
204
|
seen.add(target);
|
|
147
205
|
const source = renderIntegrationFile(await node_fs_promises.default.readFile(node_path.default.join(sourceDir, mapping.source), "utf8"), runner);
|
|
@@ -171,9 +229,10 @@ const installAgentSkills = async (options) => {
|
|
|
171
229
|
});
|
|
172
230
|
}
|
|
173
231
|
const warnings = [];
|
|
174
|
-
const claudeSkill = node_fs.default.existsSync(node_path.default.resolve(
|
|
232
|
+
const claudeSkill = node_fs.default.existsSync(node_path.default.resolve(root, ".claude/skills/cappa/SKILL.md"));
|
|
175
233
|
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.");
|
|
176
234
|
return {
|
|
235
|
+
root,
|
|
177
236
|
runner,
|
|
178
237
|
files,
|
|
179
238
|
warnings
|
|
@@ -271,20 +330,24 @@ const agentApprove = (names, options) => run$1(options, async () => {
|
|
|
271
330
|
return !screenshot || screenshot.category === "passed";
|
|
272
331
|
});
|
|
273
332
|
if (unknown.length > 0) throw new Error(`Nothing to approve for: ${unknown.join(", ")} — names must match exactly (see \`cappa agent check --json\`).`);
|
|
274
|
-
|
|
333
|
+
const verdicts = /* @__PURE__ */ new Map();
|
|
334
|
+
if (!!options.label?.length || names.some((name) => byName.get(name)?.category === "changed")) {
|
|
275
335
|
const previous = await (0, _cappa_core.readAgentReport)(config.outputDir);
|
|
276
336
|
const report = await (0, _cappa_core.runAgentCheck)({
|
|
277
337
|
outputDir: config.outputDir,
|
|
278
338
|
diff: config.diff,
|
|
279
339
|
judge: previous?.judge ?? "ambiguous"
|
|
280
340
|
});
|
|
281
|
-
const
|
|
282
|
-
for (const entry of report.entries) if (entry.category === "changed" && entry.verdict && labels.has(entry.verdict.label)) wanted.add(entry.name);
|
|
341
|
+
for (const entry of report.entries) if (entry.category === "changed" && entry.verdict) verdicts.set(entry.name, entry.verdict.label);
|
|
283
342
|
}
|
|
343
|
+
const labels = new Set(options.label);
|
|
344
|
+
for (const [name, label] of verdicts) if (labels.has(label)) wanted.add(name);
|
|
284
345
|
const toApprove = [...wanted].flatMap((name) => {
|
|
285
346
|
const screenshot = byName.get(name);
|
|
286
347
|
return screenshot && screenshot.category !== "passed" ? [screenshot] : [];
|
|
287
348
|
});
|
|
349
|
+
const regressions = toApprove.filter((s) => verdicts.get(s.name) === "regression-likely").map((s) => s.name);
|
|
350
|
+
if (regressions.length > 0 && !options.allowRegression) throw new Error(`Refusing to approve regression-likely: ${regressions.join(", ")} — if the change is intended, judge it (\`cappa agent check --judge all\`, then \`cappa agent judge <name> --label intentional-likely\`), or pass --allow-regression.`);
|
|
288
351
|
await new _cappa_core.ScreenshotFileSystem(config.outputDir).approveScreenshots(toApprove, config.diff);
|
|
289
352
|
await Promise.all(toApprove.map((screenshot) => (0, _cappa_core.clearJudgment)(config.outputDir, screenshot.name)));
|
|
290
353
|
const approved = toApprove.map((s) => ({
|
|
@@ -297,15 +360,18 @@ const agentApprove = (names, options) => run$1(options, async () => {
|
|
|
297
360
|
});
|
|
298
361
|
const agentInit = (options) => run$1(options, async () => {
|
|
299
362
|
const cwd = process.cwd();
|
|
300
|
-
const
|
|
363
|
+
const root = findProjectRoot(cwd);
|
|
364
|
+
const stacks = options.stack === "all" ? SKILL_STACK_NAMES : options.stack ? [options.stack] : detectSkillStacks(root);
|
|
301
365
|
const { runner, files, warnings } = await installAgentSkills({
|
|
302
366
|
cwd,
|
|
367
|
+
root,
|
|
303
368
|
stacks,
|
|
304
369
|
force: options.force,
|
|
305
370
|
runner: options.runner
|
|
306
371
|
});
|
|
307
372
|
if (options.json) {
|
|
308
373
|
printJson({
|
|
374
|
+
root,
|
|
309
375
|
stacks,
|
|
310
376
|
runner,
|
|
311
377
|
files,
|
|
@@ -349,7 +415,7 @@ const registerAgentCommand = (program) => {
|
|
|
349
415
|
const agent = program.command("agent").description("Visual review for coding agents: label changes, hand ambiguous ones to an agent, approve");
|
|
350
416
|
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);
|
|
351
417
|
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);
|
|
352
|
-
agent.command("approve").description("Approve screenshots by exact name or by verdict label (refused in CI)").argument("[names...]", "screenshot names, exactly as reported").option("--label <label>", "also approve every changed screenshot with this verdict label (repeatable)", collectLabel).option("--json", "print a JSON summary to stdout").action(agentApprove);
|
|
418
|
+
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);
|
|
353
419
|
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);
|
|
354
420
|
};
|
|
355
421
|
//#endregion
|