Skip to content

Commit 2d3033c

Browse files
jrusso1020claude
andauthored
fix(cli): exit 2 for remaining flag validation errors (#6639)
* fix(cli): exit 2 for remaining flag validation errors Flag and argument checks that commands make themselves still exited 1 and reported runtime_error under --json. They now take the existing usage-error path (failUsage / CliUsageError): exit 2 and a usage_error envelope. This covers lambda and cloudrun render/render-batch (--width/--height, --fps, positive-number, enum and --output-resolution flags, unknown subcommands), capture, feedback, benchmark --runs, tts, init, snapshot, compare, grade-compare, check, normalize-audio, media-treatment, play/present --port, models, docs, browser and telemetry unknown subcommands, cloud render conflicting inputs, cloud delete without --no-confirm, and inline --variables. A few checks now run before project or stack lookup so a bad flag is reported first. Runtime failures (missing files, network, render errors) still exit 1. An unattended spinner now writes its start and progress text as plain stderr lines, not only the outcome, so tools watching init can see "Transcoding". Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * fix(cli): reject a bad snapshot --frames, quiet spinner progress, drop added comments - `snapshot --frames abc` (or 0, -3, 2.5) is now a usage error: exit 2, and a usage_error envelope under --json. It used to fall back to 5 frames silently. - An unattended spinner prints its start line once and its outcome, but no longer one line per progress update, which flooded stderr during remove-background and the Chrome download. - Removes the comment lines this branch added, so the comment ratchet passes. - The render --json test now expects exit 2 and usage_error for bad inline --variables. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> --------- Co-authored-by: Claude Opus 5.5 (1M context) <[email protected]>
1 parent b847622 commit 2d3033c

36 files changed

Lines changed: 284 additions & 157 deletions

‎packages/cli/src/cli.agentMode.test.ts‎

Lines changed: 75 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -190,6 +190,79 @@ describe("agent-mode contract", () => {
190190
expect(run.code, run.stderr).toBe(2);
191191
});
192192

193+
// A bad flag value or flag combination a command checks itself is a usage error like any other:
194+
// exit 2, and under --json a usage_error envelope that names the problem.
195+
describe.concurrent("flag checks a command makes itself", () => {
196+
it.each([
197+
["lambda render proj", "--width and --height are required"],
198+
["lambda render proj --width 1920 --height 1080 --fps 7", "--fps must be one of"],
199+
["lambda render proj --width 0 --height 1080", "--width must be a positive integer"],
200+
["lambda render proj --width 1920 --height 1080 --chunk-size 0", "--chunk-size must be"],
201+
["lambda render proj --width 1920 --height 1080 --format avi", "--format must be"],
202+
["lambda render proj --width 1920 --height 1080 --output-resolution 8k", "8k"],
203+
["lambda render-batch proj --batch b.jsonl", "--width and --height are required"],
204+
["lambda render-batch proj --batch b.jsonl --width 1920 --height 1080 --fps 7", "--fps"],
205+
["lambda deploy --concurrency 0", "--concurrency must be"],
206+
["lambda sites bogus", 'unknown verb "bogus"'],
207+
["lambda bogus", "Unknown subcommand"],
208+
["cloudrun render proj", "--width and --height are required"],
209+
["cloudrun render proj --width 1920 --height 1080 --fps 7", "--fps must be one of"],
210+
["cloudrun render proj --width 1920 --height 1080 --chunk-size 0", "--chunk-size must be"],
211+
["cloudrun render proj --width 1920 --height 1080 --wait-interval-ms 0", "--wait-interval"],
212+
["cloudrun render proj --width 1920 --height 1080 --variables {bad", "--variables"],
213+
["cloudrun render-batch proj --batch b.jsonl", "--width and --height are required"],
214+
["cloudrun render-batch proj --batch b.jsonl --width 1920 --height 1080 --fps 7", "--fps"],
215+
["cloudrun render-batch proj --batch b.jsonl --width 640 --height 360 --format avi", "avi"],
216+
["cloudrun sites bogus", 'unknown verb "bogus"'],
217+
["cloudrun bogus", "Unknown subcommand"],
218+
["capture https://example.com --max-screenshots 0", "--max-screenshots must be"],
219+
["capture https://example.com --capture-budget 0", "--capture-budget must be"],
220+
["capture https://example.com --local-file page.html", "not both"],
221+
["capture not-a-url", "Invalid URL"],
222+
["benchmark --runs 0", "Invalid runs"],
223+
["models bogus", "Unknown: models bogus"],
224+
["tts", "Provide text to speak"],
225+
["tts hello --speed 9", "Speed must be"],
226+
["cloud render --asset-id a --url https://example.com/p.zip", "Conflicting inputs"],
227+
["cloud delete render_1", "Confirmation required"],
228+
["snapshot --at 1 --range 0,1", "Use only one of"],
229+
["snapshot --at x", "--at must be"],
230+
["snapshot --frames abc", "--frames must be a positive integer"],
231+
["snapshot --frames -3", "--frames must be a positive integer"],
232+
["compare a.html", "need 2+ paths"],
233+
["compare a.html b.html --cols 0", "--cols must be"],
234+
["grade-compare --for frame.png", "Exactly one of --grades or --luts"],
235+
["check --range 5,1", "Invalid --range"],
236+
["normalize-audio --target music --tolerance=-1", "--tolerance must be"],
237+
["media-treatment --capabilities --all --capability x", "--all or --capability"],
238+
])("`%s` exits 2 with a usage_error envelope", async (args, message) => {
239+
const run = await runAsAgent([...args.split(" "), "--json"]);
240+
expectQuiet(run);
241+
expect(run.code, run.stderr).toBe(2);
242+
expectJsonFailure(run, "usage_error");
243+
expect(JSON.parse(run.stdout).error.message).toContain(message);
244+
});
245+
246+
it.each([
247+
["feedback --rating 99", "Rating must be an integer between 0 and 10"],
248+
["feedback", "Give a --rating"],
249+
["feedback --comment x --file-issue", "--file-issue needs a --rating"],
250+
["feedback --rating 5 --source bot", "Source must be"],
251+
["browser bogus", "Unknown subcommand"],
252+
["telemetry bogus", "Unknown subcommand"],
253+
["docs bogus", "Unknown topic"],
254+
["init demo --template x --non-interactive", "renamed to --example"],
255+
["init demo --video a.mp4 --audio b.mp3 --non-interactive", "--video and --audio"],
256+
["play --port 0", "--port must be"],
257+
["present --port 0", "--port must be"],
258+
])("`%s` has no JSON output and exits 2 naming the problem", async (args, message) => {
259+
const run = await runAsAgent(args.split(" "));
260+
expect(run.signal, "finished before the timeout").toBeNull();
261+
expect(run.code, run.stderr).toBe(2);
262+
expect(run.stdout + run.stderr).toContain(message);
263+
});
264+
});
265+
193266
it.each([
194267
["help", "Usage:"],
195268
["help render", "USAGE hyperframes render"],
@@ -256,9 +329,9 @@ describe("agent-mode contract", () => {
256329
writeFileSync(join(project, "index.html"), "<!doctype html><html><body></body></html>");
257330
const run = await runAsAgent(["render", project, "--variables", "{bad", "--json"]);
258331
expectQuiet(run);
259-
expect(run.code, run.stderr).toBe(1);
332+
expect(run.code, run.stderr).toBe(2);
260333
expect(run.stdout.trim().split("\n")).toHaveLength(1);
261-
expectJsonFailure(run, "runtime_error");
334+
expectJsonFailure(run, "usage_error");
262335
expect(JSON.parse(run.stdout).error.message).toBe("Invalid JSON in --variables");
263336
});
264337

‎packages/cli/src/commands/benchmark.ts‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import { failCommand, setCommandExitCode } from "../utils/commandResult.js";
1+
import { failCommand, failUsage, setCommandExitCode } from "../utils/commandResult.js";
22
import { defineCommand } from "../utils/defineCommand.js";
33
import type { Example } from "./_examples.js";
44
import { existsSync, mkdtempSync, rmSync, statSync } from "node:fs";
@@ -59,16 +59,16 @@ export default defineCommand({
5959
json: { type: "boolean", description: "Output results as JSON", default: false },
6060
},
6161
async run({ args }) {
62-
// ── Resolve project ──────────────────────────────────────────────────
63-
const project = resolveProject(args.dir);
64-
6562
// ── Parse runs ───────────────────────────────────────────────────────
6663
const runsPerConfig = parseInt(args.runs ?? "3", 10);
6764
if (isNaN(runsPerConfig) || runsPerConfig < 1 || runsPerConfig > 20) {
6865
errorBox("Invalid runs", `Got "${args.runs ?? "3"}". Must be between 1 and 20.`);
69-
failCommand();
66+
failUsage();
7067
}
7168

69+
// ── Resolve project ──────────────────────────────────────────────────
70+
const project = resolveProject(args.dir);
71+
7272
const jsonOutput = args.json ?? false;
7373

7474
// ── Temp output for benchmark renders ────────────────────────────────

‎packages/cli/src/commands/browser.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import { failCommand } from "../utils/commandResult.js";
1+
import { failCommand, failUsage } from "../utils/commandResult.js";
22
import { defineCommand } from "../utils/defineCommand.js";
33
import type { Example } from "./_examples.js";
44
import * as clack from "../ui/prompts.js";
@@ -182,7 +182,7 @@ ${c.bold("EXAMPLES:")}
182182
console.error(
183183
`${c.error("Unknown subcommand:")} ${subcommand}\n\nRun ${c.accent("hyperframes browser --help")} for usage.`,
184184
);
185-
failCommand(1, `Unknown subcommand: ${subcommand}`);
185+
failUsage();
186186
}
187187
},
188188
});

‎packages/cli/src/commands/capture.test.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -169,7 +169,7 @@ describe("capture command — vision control", () => {
169169
json: true,
170170
},
171171
} as never),
172-
).rejects.toBeInstanceOf(CliRuntimeError);
172+
).rejects.toBeInstanceOf(CliUsageError);
173173

174174
expect(captureWebsiteMock).not.toHaveBeenCalled();
175175
},
@@ -189,7 +189,7 @@ describe("capture command — vision control", () => {
189189
json: true,
190190
},
191191
} as never),
192-
).rejects.toBeInstanceOf(CliRuntimeError);
192+
).rejects.toBeInstanceOf(CliUsageError);
193193
expect(error).toHaveBeenCalledWith("--max-screenshots must be a positive integer.");
194194
expect(captureWebsiteMock).not.toHaveBeenCalled();
195195
},
@@ -232,7 +232,7 @@ describe("capture command — vision control", () => {
232232
captureCommand.run!({
233233
args: { ...target, output: "/tmp/hf-local-refused", json: true },
234234
} as never),
235-
).rejects.toThrow("local-root" in target ? CliUsageError : CliRuntimeError);
235+
).rejects.toThrow("url" in target ? CliUsageError : CliRuntimeError);
236236
expect(error.mock.calls.flat().join("\n")).toContain(message);
237237
expect(captureWebsiteMock).not.toHaveBeenCalled();
238238
});

‎packages/cli/src/commands/capture.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ function parsePositiveInteger(
2424
const parsed = Number(raw);
2525
if (!Number.isInteger(parsed) || parsed <= 0) {
2626
console.error(`${flag} must be a positive integer${unit}.`);
27-
failCommand();
27+
failUsage();
2828
}
2929
return parsed;
3030
}
@@ -152,7 +152,7 @@ export default defineCommand({
152152
if (localFile !== undefined) {
153153
if (url) {
154154
console.error("Pass either a URL or --local-file, not both.");
155-
failCommand();
155+
failUsage();
156156
}
157157
const { resolveLocalCaptureTarget } = await import("../capture/localPage.js");
158158
try {
@@ -176,7 +176,7 @@ export default defineCommand({
176176
new URL(url);
177177
} catch {
178178
console.error(`Invalid URL: ${url}`);
179-
failCommand();
179+
failUsage();
180180
}
181181
}
182182

‎packages/cli/src/commands/check.test.ts‎

Lines changed: 17 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,11 @@ import {
4848
type MotionSpecResolution,
4949
} from "../utils/checkPipeline.js";
5050
import { resolveCompositionViewportFromHtml } from "../utils/compositionViewport.js";
51-
import { consumeCommandResult, registerRootExitRequester } from "../utils/commandResult.js";
51+
import {
52+
CliUsageError,
53+
consumeCommandResult,
54+
registerRootExitRequester,
55+
} from "../utils/commandResult.js";
5256
import { ambiguousIssue } from "../utils/motionAudit.js";
5357
import type { ProjectLintResult } from "../utils/lintProject.js";
5458
import type {
@@ -654,7 +658,9 @@ it("prints a dash-prefixed --frame-check value's parse failure exactly once, not
654658
withMeta: (value) => value,
655659
});
656660

657-
await runViaCli(command, { rawArgs: ["--frame-check=--json"] });
661+
await expect(runViaCli(command, { rawArgs: ["--frame-check=--json"] })).rejects.toBeInstanceOf(
662+
CliUsageError,
663+
);
658664

659665
expect(runPipeline).not.toHaveBeenCalled();
660666
const matching = errorLog.mock.calls.filter(
@@ -841,16 +847,20 @@ it("rejects malformed caption-zone specs instead of silently disabling the gate"
841847
withMeta: (value) => ({ ...value, _meta: { version: "test" } }),
842848
});
843849

844-
await runCommand(command, {
845-
rawArgs: ["--json", "--caption-zone", "x0=0;y0=.8;x1=1;y1=1.2"],
846-
});
850+
await expect(
851+
runCommand(command, {
852+
rawArgs: ["--json", "--caption-zone", "x0=0;y0=.8;x1=1;y1=1.2"],
853+
}),
854+
).rejects.toMatchObject({ result: { exitCode: 2, kind: "usage_error" } });
847855

848856
expect(runPipeline).not.toHaveBeenCalled();
849-
expect(consumeCommandResult().exitCode).toBe(1);
850857
expect(log).toHaveBeenCalledTimes(1);
851858
expect(JSON.parse(String(log.mock.calls[0]?.[0]))).toEqual({
852859
ok: false,
853-
error: expect.objectContaining({ message: expect.stringContaining("Invalid --caption-zone") }),
860+
error: expect.objectContaining({
861+
code: "usage_error",
862+
message: expect.stringContaining("Invalid --caption-zone"),
863+
}),
854864
_meta: { version: "test" },
855865
});
856866
});

‎packages/cli/src/commands/check.ts‎

Lines changed: 24 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ import { parseAt } from "./layout.js";
2020
import { c } from "../ui/colors.js";
2121
import { registerBrowserSessionCleanup } from "../browser/launch.js";
2222
import { normalizeErrorMessage } from "../utils/errorMessage.js";
23-
import { setCommandExitCode } from "../utils/commandResult.js";
23+
import { CliUsageError, failUsage, setCommandExitCode } from "../utils/commandResult.js";
2424
import { swallowedFlagUsageError } from "../utils/reject-unknown-flags.js";
2525
import { formatLayoutIssue } from "../utils/layoutAudit.js";
2626
import { resolveProject, type ProjectDir } from "../utils/project.js";
@@ -278,8 +278,8 @@ export function createCheckCommand(
278278

279279
const reported = untilReported();
280280
try {
281-
const project = dependencies.resolveProject(args.dir);
282281
const options = parseCheckOptions(args);
282+
const project = dependencies.resolveProject(args.dir);
283283
if (!asJson) {
284284
console.log(`${c.accent("◆")} Checking ${c.accent(project.name)}`);
285285
}
@@ -303,22 +303,31 @@ export function createCheckCommand(
303303
}
304304
setCommandExitCode(checkExitCode(report));
305305
} catch (error) {
306-
const message = failureMessage(error);
307-
if (asJson) {
308-
console.log(
309-
JSON.stringify(dependencies.withMeta(jsonFailure("runtime_error", message)), null, 2),
310-
);
311-
} else {
312-
console.error(`${c.error("✗")} Check failed: ${message}`);
313-
}
314-
setCommandExitCode(1);
306+
reportCheckFailure(error, asJson, (value) => dependencies.withMeta(value));
315307
} finally {
316308
reported.done();
317309
}
318310
},
319311
});
320312
}
321313

314+
function reportCheckFailure(
315+
error: unknown,
316+
asJson: boolean,
317+
addMeta: (value: object) => object,
318+
): void {
319+
const message = failureMessage(error);
320+
const usage = error instanceof CliUsageError;
321+
if (asJson) {
322+
const code = usage ? error.code : "runtime_error";
323+
console.log(JSON.stringify(addMeta(jsonFailure(code, message)), null, 2));
324+
} else {
325+
console.error(`${c.error("✗")} Check failed: ${message}`);
326+
}
327+
if (usage) failUsage();
328+
setCommandExitCode(1);
329+
}
330+
322331
const REPORT_GRACE_MS = 5_000;
323332

324333
function untilReported(): { done: () => void } {
@@ -427,7 +436,7 @@ export function parseCheckRange(value: unknown): [number, number] | undefined {
427436
start < 0 ||
428437
end <= start
429438
)
430-
throw new Error("Invalid --range: use non-negative start,end with end > start");
439+
throw new CliUsageError("Invalid --range: use non-negative start,end with end > start");
431440
return [start, end];
432441
}
433442

@@ -474,7 +483,7 @@ function parseFrameCheckTolerance(raw: string | undefined): number | undefined {
474483
}
475484

476485
function frameCheckError(): Error {
477-
return new Error(
486+
return new CliUsageError(
478487
'Invalid --frame-check: use bare --frame-check or "severity=warning|error;seek=.25,.75;tol=4" (all fields optional)',
479488
);
480489
}
@@ -513,7 +522,7 @@ function parseProseCoverageFloor(raw: string | undefined): number | undefined {
513522
}
514523

515524
function layoutError(): Error {
516-
return new Error(
525+
return new CliUsageError(
517526
'Invalid --layout: use "proseCoverageFloor=0.05" with a fraction from 0 to 1 (inclusive)',
518527
);
519528
}
@@ -615,7 +624,7 @@ function captionSeeks(
615624
}
616625

617626
function captionZoneError(): Error {
618-
return new Error(
627+
return new CliUsageError(
619628
'Invalid --caption-zone; use "x0=0;y0=.82;x1=1;y1=1[;severity=warning|error][;seek=.5,1]" with fractions from 0 to 1.',
620629
);
621630
}

‎packages/cli/src/commands/cloud/delete.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import { failCommand } from "../../utils/commandResult.js";
1+
import { failCommand, failUsage } from "../../utils/commandResult.js";
22
/**
33
* `hyperframes cloud delete <render_id>` — soft-delete a cloud render.
44
*
@@ -55,7 +55,7 @@ export default defineCommand({
5555
"delete cannot prompt for confirmation here: this run cannot answer a prompt, or --json was passed.",
5656
"Re-run with --no-confirm to acknowledge the irreversible delete.",
5757
);
58-
failCommand();
58+
failUsage();
5959
}
6060
const ok = await confirmDelete(args.id);
6161
if (!ok) {

‎packages/cli/src/commands/cloud/render.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -425,7 +425,7 @@ function resolveProjectInput(opts: {
425425
const count = Number(explicit.dir) + Number(explicit.assetId) + Number(explicit.url);
426426
if (count > 1) {
427427
errorBox("Conflicting inputs", "Pass only one of: project dir, --asset-id, --url.");
428-
failCommand();
428+
failUsage();
429429
}
430430
if (explicit.assetId) return { kind: "asset_id", assetId: opts.assetId };
431431
if (explicit.url) return { kind: "url", url: opts.url };

0 commit comments

Comments
 (0)