Skip to content

Commit 25132f4

Browse files
jrusso1020claude
andcommitted
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]>
1 parent edc4df1 commit 25132f4

35 files changed

Lines changed: 278 additions & 155 deletions

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

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -190,6 +190,77 @@ 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+
["compare a.html", "need 2+ paths"],
231+
["compare a.html b.html --cols 0", "--cols must be"],
232+
["grade-compare --for frame.png", "Exactly one of --grades or --luts"],
233+
["check --range 5,1", "Invalid --range"],
234+
["normalize-audio --target music --tolerance=-1", "--tolerance must be"],
235+
["media-treatment --capabilities --all --capability x", "--all or --capability"],
236+
])("`%s` exits 2 with a usage_error envelope", async (args, message) => {
237+
const run = await runAsAgent([...args.split(" "), "--json"]);
238+
expectQuiet(run);
239+
expect(run.code, run.stderr).toBe(2);
240+
expectJsonFailure(run, "usage_error");
241+
expect(JSON.parse(run.stdout).error.message).toContain(message);
242+
});
243+
244+
it.each([
245+
["feedback --rating 99", "Rating must be an integer between 0 and 10"],
246+
["feedback", "Give a --rating"],
247+
["feedback --comment x --file-issue", "--file-issue needs a --rating"],
248+
["feedback --rating 5 --source bot", "Source must be"],
249+
["browser bogus", "Unknown subcommand"],
250+
["telemetry bogus", "Unknown subcommand"],
251+
["docs bogus", "Unknown topic"],
252+
["init demo --template x --non-interactive", "renamed to --example"],
253+
["init demo --video a.mp4 --audio b.mp3 --non-interactive", "--video and --audio"],
254+
["play --port 0", "--port must be"],
255+
["present --port 0", "--port must be"],
256+
])("`%s` has no JSON output and exits 2 naming the problem", async (args, message) => {
257+
const run = await runAsAgent(args.split(" "));
258+
expect(run.signal, "finished before the timeout").toBeNull();
259+
expect(run.code, run.stderr).toBe(2);
260+
expect(run.stdout + run.stderr).toContain(message);
261+
});
262+
});
263+
193264
it.each([
194265
["help", "Usage:"],
195266
["help render", "USAGE hyperframes render"],

‎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: 25 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,32 @@ 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+
/** A bad flag is a usage error (exit 2); anything else is a failed check (exit 1). */
315+
function reportCheckFailure(
316+
error: unknown,
317+
asJson: boolean,
318+
addMeta: (value: object) => object,
319+
): void {
320+
const message = failureMessage(error);
321+
const usage = error instanceof CliUsageError;
322+
if (asJson) {
323+
const code = usage ? error.code : "runtime_error";
324+
console.log(JSON.stringify(addMeta(jsonFailure(code, message)), null, 2));
325+
} else {
326+
console.error(`${c.error("✗")} Check failed: ${message}`);
327+
}
328+
if (usage) failUsage();
329+
setCommandExitCode(1);
330+
}
331+
322332
const REPORT_GRACE_MS = 5_000;
323333

324334
function untilReported(): { done: () => void } {
@@ -427,7 +437,7 @@ export function parseCheckRange(value: unknown): [number, number] | undefined {
427437
start < 0 ||
428438
end <= start
429439
)
430-
throw new Error("Invalid --range: use non-negative start,end with end > start");
440+
throw new CliUsageError("Invalid --range: use non-negative start,end with end > start");
431441
return [start, end];
432442
}
433443

@@ -474,7 +484,7 @@ function parseFrameCheckTolerance(raw: string | undefined): number | undefined {
474484
}
475485

476486
function frameCheckError(): Error {
477-
return new Error(
487+
return new CliUsageError(
478488
'Invalid --frame-check: use bare --frame-check or "severity=warning|error;seek=.25,.75;tol=4" (all fields optional)',
479489
);
480490
}
@@ -513,7 +523,7 @@ function parseProseCoverageFloor(raw: string | undefined): number | undefined {
513523
}
514524

515525
function layoutError(): Error {
516-
return new Error(
526+
return new CliUsageError(
517527
'Invalid --layout: use "proseCoverageFloor=0.05" with a fraction from 0 to 1 (inclusive)',
518528
);
519529
}
@@ -615,7 +625,7 @@ function captionSeeks(
615625
}
616626

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

‎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)