Skip to content

Commit 85efaec

Browse files
jrusso1020claude
andauthored
fix(cli): every --json failure answers with one envelope, and --json only where supported (#6622)
* fix(cli): every --json failure answers with one envelope, and --json only where supported Under --json, failures came back as a bare string (`"error": "Command failed"` from lint), a command-specific shape, or nothing at all on stdout (info, compositions, render, snapshot, cloud get). Now every failure is `{"ok": false, "error": {"code", "message", "hint"?}}`: - jsonFailure() in utils/jsonError.ts builds it. The commands that printed `{ok: false, error: "<text>"}` use it, keeping their extra fields (lint's findings, validate's errors). A refused timeline edit now writes it to stdout instead of stderr, and keeps its `reason` and `fix` fields. - When a --json run fails without writing anything to stdout, cli.ts writes the envelope itself: usage errors carry their own code (unknown_flag, unknown_command, json_unsupported, confirmation_required), anything else is runtime_error with the message the command printed on stderr. --json is no longer accepted by every command. A command supports it by declaring a `json` arg; the others reject it with exit 2 and the code json_unsupported, instead of accepting the flag and printing prose. The contract test now checks every command's --json path, and packages/cli gets an AGENTS.md with the rules: stdout is data, stderr is messages, never prompt without a TTY, exit 2 for usage errors, --json always returns an envelope. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * fix(cli): put the real failure in the --json envelope, never the generic text or a notice lint --json and check --json in a directory with no project answered "message": "Command failed". The project check reports the problem, then throws a presented "Command failed" with the real error as its cause, and the command's own catch serialized that generic text. failureMessage() now returns the cause, or else what the command reported through errorBox, and every command catch that writes a --json failure uses it (lint, check, validate, layout, snapshot, compare, grade-compare, media-treatment, tts, remove-background, add, skills, lambda policies). compare, grade-compare and add share failCaught() for that catch. The boundary envelope follows the same order: the error's own message unless it is the generic one, then its cause, then the errorBox title and hint, and only then the stderr text. Notices (the telemetry disclosure, deprecation lines, diag progress) are no longer captured, so validate, layout and inspect no longer put "is deprecated" in the error message. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * fix(cli): render --json keeps human output off stdout so a failure answers with the envelope Under --json a single render printed its header, lint findings and progress on stdout, so a later failure such as `render --variables '{bad' --json` ended with no JSON envelope. --json now silences that output the way --batch --json already did, and --variables is parsed before the browser check so a bad value fails without a Chrome download. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * fix(cli): a --strict lint abort says why, even under --json Under --json the render is quiet, so a --strict lint abort printed nothing and the envelope said only "Command failed". The abort is now an error box on stderr in every mode, naming the error and warning counts and the first finding, and the --json envelope carries the same message. Lint now runs before the browser check, so the abort never waits on a Chrome download. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * test(cli): time the render setup cancel from the wrapper's exit The 1 s budget started when the command did. With lint now running before the browser check, its subprocess (about 250 ms here) sat inside that budget, and the test failed once under load. The budget now starts when the wrapper exits, which is the latency the test is about. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> --------- Co-authored-by: Claude Opus 5.5 (1M context) <[email protected]>
1 parent b6eaed7 commit 85efaec

47 files changed

Lines changed: 676 additions & 198 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/packages/cli.mdx‎

Lines changed: 21 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -46,9 +46,10 @@ default to the current directory: `npx hyperframes check ./my-video`. A few
4646
take it as a flag instead — `add`, `transcribe`, `feedback`, `skills`, `history`, and
4747
the `timeline` edit commands use `--dir`.
4848

49-
**`--json` for agents and scripts.** Almost every command accepts it. The
50-
payload is wrapped with a `_meta` field so a script can spot an outdated CLI
51-
from any command's output, without a second call:
49+
**`--json` for agents and scripts.** Most commands accept it, and the ones
50+
that do not reject it with exit 2. The payload is wrapped with a `_meta` field
51+
so a script can spot an outdated CLI from any command's output, without a
52+
second call:
5253

5354
```json
5455
{
@@ -67,6 +68,23 @@ background process, and never under CI or `HYPERFRAMES_NO_UPDATE_CHECK=1`.
6768
`--json` never makes a network request of its own. Deprecated commands add
6869
`_meta.deprecated: true`.
6970

71+
A failure under `--json` always prints one JSON object on stdout, with a
72+
machine-readable `code` and, when there is a next step, a `hint`:
73+
74+
```json
75+
{
76+
"ok": false,
77+
"error": {
78+
"code": "unknown_flag",
79+
"message": "Unknown flag: --out",
80+
"hint": "Did you mean --output? Run 'hyperframes render --help' to see its flags."
81+
}
82+
}
83+
```
84+
85+
Some commands add their own fields next to `error`, such as `findings` from
86+
`lint` or `reason` and `fix` from a refused `timeline` edit.
87+
7088
**Flags, not prompts.** A missing required flag fails immediately with a usage
7189
example rather than waiting for input. Two commands are interactive on a TTY:
7290
`init` prompts for a project name and example unless you pass

‎packages/cli/AGENTS.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Working on the CLI
2+
3+
Read this before you add or change a command in `packages/cli`.
4+
5+
## CLI rules for agents
6+
7+
Coding agents and CI run this CLI far more often than people do, with no
8+
terminal and nobody to answer a question. Every command follows these rules,
9+
and `src/cli.agentMode.test.ts` runs every registered command the way an agent
10+
does to hold them.
11+
12+
- **Stdout is data, stderr is messages.** Results go to stdout. Progress,
13+
warnings, notices and errors go to stderr.
14+
- **Never prompt without a person.** `isUnattended()` in
15+
`src/utils/attendedTerminal.ts` is true without a TTY, under CI, inside a
16+
coding agent, or with `HYPERFRAMES_AGENT=1`. Import prompts and spinners from
17+
`src/ui/prompts.ts`, never from `@clack/prompts` (lint enforces it): its
18+
prompts refuse to ask when unattended. A command that needs a confirmation
19+
takes `--yes` and calls `confirmationRequired()` when it is missing.
20+
- **Exit codes.** 0 success, 1 the command ran and failed, 2 the command line
21+
is wrong. Throw `CliUsageError` for a usage error; it exits 2.
22+
- **`--json` always returns an envelope.** A command supports `--json` by
23+
declaring a `json` arg; every other command rejects the flag with exit 2. On
24+
failure, stdout is `{"ok": false, "error": {"code", "message", "hint"?}}`.
25+
Build it with `jsonFailure()` from `src/utils/jsonError.ts`. If a failing
26+
`--json` run printed nothing, `cli.ts` writes the envelope for it.
27+
- **Define commands with `defineCommand` from `src/utils/defineCommand.ts`**
28+
and register them in `commandLoaders` in `src/cli.ts`. The contract test
29+
picks up a new command from there, with no change to the test.

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

Lines changed: 99 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import { spawn } from "node:child_process";
2-
import { mkdtempSync, readdirSync, readFileSync, rmSync } from "node:fs";
2+
import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
33
import { tmpdir } from "node:os";
44
import { dirname, join } from "node:path";
55
import { fileURLToPath } from "node:url";
@@ -101,6 +101,18 @@ function expectQuiet(run: Run): void {
101101
expect(output).not.toMatch(NAG);
102102
}
103103

104+
function declaresJson(command: CommandDef): boolean {
105+
const args = command.args;
106+
return typeof args === "object" && args !== null && "json" in args;
107+
}
108+
109+
function expectJsonFailure(run: Run, code?: string): void {
110+
const parsed = JSON.parse(run.stdout) as { ok?: unknown; error?: { code?: unknown } };
111+
expect(parsed.ok).toBe(false);
112+
expect(typeof parsed.error?.code).toBe("string");
113+
if (code) expect(parsed.error?.code).toBe(code);
114+
}
115+
104116
const commands = await registeredCommands();
105117
// From source, `preview` refuses to load until the studio packages are built; the test job does
106118
// not build them, so preview is only spawned where they are.
@@ -130,6 +142,31 @@ describe("agent-mode contract", () => {
130142
},
131143
);
132144

145+
it.each(
146+
spawnable
147+
.filter((c) => declaresJson(c.command))
148+
.map((c) => [c.path.join(" "), c.path] as const),
149+
)("%s --json answers a usage error with the JSON envelope", async (_label, path) => {
150+
const run = await runAsAgent([...path, "--json", "--not-a-real-flag"]);
151+
expectQuiet(run);
152+
expect(run.code, run.stderr).toBe(2);
153+
expectJsonFailure(run);
154+
});
155+
156+
it.each(
157+
spawnable
158+
.filter((c) => !declaresJson(c.command))
159+
.map((c) => [c.path.join(" "), c.path] as const),
160+
)(
161+
"%s has no JSON output, so --json is a usage error, answered as JSON",
162+
async (_label, path) => {
163+
const run = await runAsAgent([...path, "--json"]);
164+
expectQuiet(run);
165+
expect(run.code, run.stderr).toBe(2);
166+
expectJsonFailure(run);
167+
},
168+
);
169+
133170
it.each(spawnable.map((c) => [c.path.join(" "), c.path] as const))(
134171
"%s rejects an unknown flag with exit 2",
135172
async (_label, path) => {
@@ -187,6 +224,67 @@ describe("agent-mode contract", () => {
187224
},
188225
);
189226

227+
it.each([["lint"], ["check"], ["info"], ["validate"], ["layout"], ["inspect"]])(
228+
"%s --json in an empty directory names the real failure, and no notice",
229+
async (name) => {
230+
const run = await runAsAgent([name, "--json"]);
231+
const parsed = JSON.parse(run.stdout) as { ok: boolean; error: { message: string } };
232+
expect(parsed.ok).toBe(false);
233+
expect(parsed.error.message).toContain("No composition found");
234+
expect(parsed.error.message).not.toMatch(/Command failed|deprecated|anonymous usage/);
235+
},
236+
);
237+
238+
it("a missing argument under --json is a usage_error with the real message", async () => {
239+
const run = await runAsAgent(["capture", "--json"]);
240+
expect(run.code).toBe(2);
241+
expectJsonFailure(run, "usage_error");
242+
expect(JSON.parse(run.stdout).error.message).toContain("Missing URL");
243+
});
244+
245+
it("a runtime failure under --json is an envelope that says why, not empty stdout", async () => {
246+
const run = await runAsAgent(["info", "--json"]);
247+
expectQuiet(run);
248+
expect(run.code).toBe(1);
249+
expectJsonFailure(run, "runtime_error");
250+
expect(run.stdout).toContain("No composition found");
251+
});
252+
253+
it("a render that fails under --json prints only the envelope on stdout", async () => {
254+
const project = join(home, "render-json");
255+
mkdirSync(project, { recursive: true });
256+
writeFileSync(join(project, "index.html"), "<!doctype html><html><body></body></html>");
257+
const run = await runAsAgent(["render", project, "--variables", "{bad", "--json"]);
258+
expectQuiet(run);
259+
expect(run.code, run.stderr).toBe(1);
260+
expect(run.stdout.trim().split("\n")).toHaveLength(1);
261+
expectJsonFailure(run, "runtime_error");
262+
expect(JSON.parse(run.stdout).error.message).toBe("Invalid JSON in --variables");
263+
});
264+
265+
it("a --strict lint abort under --json names the lint errors, on stdout and stderr", async () => {
266+
const project = join(home, "render-strict");
267+
mkdirSync(project, { recursive: true });
268+
writeFileSync(
269+
join(project, "index.html"),
270+
'<!doctype html><html><body><div data-composition-id="main"></div></body></html>',
271+
);
272+
const run = await runAsAgent(["render", project, "--strict", "--json"]);
273+
expectQuiet(run);
274+
expect(run.code, run.stderr).toBe(1);
275+
expectJsonFailure(run, "runtime_error");
276+
const { message } = JSON.parse(run.stdout).error as { message: string };
277+
expect(message).toMatch(/Aborting render due to lint issues in --strict mode: [1-9]\d* error/);
278+
expect(run.stderr).toContain(message);
279+
});
280+
281+
it("an unknown command under --json is an envelope with the suggestion", async () => {
282+
const run = await runAsAgent(["rendr", "--json"]);
283+
expect(run.code).toBe(2);
284+
expectJsonFailure(run, "unknown_command");
285+
expect(JSON.parse(run.stdout).error.hint).toBe("Did you mean 'hyperframes render'?");
286+
});
287+
190288
it("an unknown flag suggests the flag it most likely means", async () => {
191289
const run = await runAsAgent(["render", "--out", "x.mp4"]);
192290
expect(run.code).toBe(2);

‎packages/cli/src/cli.ts‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,7 @@ import { reportCommandFailure, trackCommandFailures } from "./utils/command-fail
9595
import { isRenderSucceeded } from "./utils/render-success-state.js";
9696
import { resolveCommandUsage, type ResolvedCommandUsage } from "./utils/commandUsageResolution.js";
9797
import { closestMatch } from "./utils/didYouMean.js";
98+
import { jsonErrorBody, watchOutput, writeJsonFailure } from "./utils/jsonError.js";
9899
import { isDevMode } from "./utils/env.js";
99100
import {
100101
CliResultSignal,
@@ -218,6 +219,8 @@ const cliCommandArg = process.argv[2];
218219
// check), so its type can't be inferred from its own initializer.
219220
const command: string = cliCommandArg && cliCommandArg in subCommands ? cliCommandArg : "unknown";
220221
const hasJsonFlag = process.argv.includes("--json");
222+
// Under --json a failure always answers on stdout with the shared envelope (see executeCli).
223+
const jsonOutput = hasJsonFlag ? watchOutput() : undefined;
221224

222225
// Captured references — populated when the lazy imports resolve.
223226
// Used in exit handlers where dynamic import() is unsafe (beforeExit loops,
@@ -539,7 +542,11 @@ async function unknownCommandError(requested: ResolvedCommandUsage): Promise<Cli
539542
if (match) console.error(`Did you mean '${group} ${match}'?`);
540543
console.error("");
541544
await showUsage(requested.command, requested.parent, console.error);
542-
return new CliUsageError(`Unknown command: ${word}`, { presented: true });
545+
return new CliUsageError(`Unknown command: ${word}`, {
546+
presented: true,
547+
code: "unknown_command",
548+
hint: match ? `Did you mean '${group} ${match}'?` : undefined,
549+
});
543550
}
544551

545552
// A group like `timeline` also takes a project directory, so a word it does not know may be one.
@@ -598,6 +605,7 @@ function commandResultForError(error: unknown): CommandResult {
598605
// fallow-ignore-next-line complexity
599606
async function executeCli(): Promise<void> {
600607
let result: CommandResult = { exitCode: 0, kind: "success" };
608+
let failure: unknown;
601609
try {
602610
if (isHelp) await showRequestedUsage(console.log);
603611
else {
@@ -608,6 +616,7 @@ async function executeCli(): Promise<void> {
608616
const error = isCittyError(caught, "E_UNKNOWN_COMMAND")
609617
? await unknownCommandError(await resolveCommandUsage(main as CommandDef, argv))
610618
: caught;
619+
failure = error;
611620
result = commandResultForError(error);
612621
if (!(error instanceof CliResultSignal)) {
613622
commandFailed = true;
@@ -623,6 +632,9 @@ async function executeCli(): Promise<void> {
623632
} finally {
624633
const pending = consumeCommandResult();
625634
if (pending.exitCode !== 0 || result.exitCode === 0) result = pending;
635+
if (jsonOutput && result.exitCode !== 0 && !jsonOutput.wroteStdout()) {
636+
writeJsonFailure(jsonErrorBody(failure, result, jsonOutput.stderrText()));
637+
}
626638
await finalizeCli(result);
627639
}
628640
}

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

Lines changed: 3 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
import { failCommand } from "../utils/commandResult.js";
22
import { defineCommand } from "../utils/defineCommand.js";
33
import type { Example } from "./_examples.js";
4+
import { failCaught } from "../utils/jsonError.js";
45

56
export const examples: Example[] = [
67
["Add a block to the current project", "hyperframes add claude-code-window"],
@@ -555,10 +556,7 @@ export default defineCommand({
555556
} catch (singleErr) {
556557
// Not a single item — try as a tag for bulk install
557558
if (!(singleErr instanceof AddError) || singleErr.code !== "unknown-item") {
558-
const msg = singleErr instanceof Error ? singleErr.message : String(singleErr);
559-
if (json) console.log(JSON.stringify({ ok: false, error: msg }));
560-
else console.error(c.error(msg));
561-
failCommand();
559+
failCaught(singleErr, json, c.error);
562560
}
563561

564562
let config = loadProjectConfig(projectDir);
@@ -578,10 +576,7 @@ export default defineCommand({
578576
}
579577

580578
if (items.length === 0) {
581-
const msg = singleErr instanceof Error ? singleErr.message : String(singleErr);
582-
if (json) console.log(JSON.stringify({ ok: false, error: msg }));
583-
else console.error(c.error(msg));
584-
failCommand();
579+
failCaught(singleErr, json, c.error);
585580
}
586581

587582
if (!json) {

‎packages/cli/src/commands/auth/status.ts‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ import {
3737
type OfflineEngineLine,
3838
type UnconfiguredContext,
3939
} from "./status-guidance.js";
40+
import { jsonFailure } from "../../utils/jsonError.js";
4041

4142
interface VerifiedStatus {
4243
credential: ResolvedCredential;
@@ -132,7 +133,9 @@ function handleUnconfigured(asJson: boolean): never {
132133
function handleResolveError(err: unknown, asJson: boolean): never {
133134
if (!isAuthError(err)) throw err;
134135
if (asJson) {
135-
console.log(JSON.stringify({ configured: false, error: err.message, hint: err.hint ?? null }));
136+
console.log(
137+
JSON.stringify({ configured: false, ...jsonFailure("auth_error", err.message, err.hint) }),
138+
);
136139
} else {
137140
console.error(c.error(err.message));
138141
if (err.hint) console.error(c.dim(err.hint));

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

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -386,7 +386,10 @@ describe("capture command — vision control", () => {
386386
const payload = log.mock.calls.at(-1)?.[0];
387387
expect(typeof payload).toBe("string");
388388
if (typeof payload !== "string") throw new Error("Expected JSON failure payload");
389-
expect(JSON.parse(payload)).toMatchObject({ ok: false, error: "required extraction failed" });
389+
expect(JSON.parse(payload)).toMatchObject({
390+
ok: false,
391+
error: expect.objectContaining({ message: "required extraction failed" }),
392+
});
390393
} finally {
391394
rmSync(dir, { recursive: true, force: true });
392395
}

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

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ import { normalizeErrorMessage } from "../utils/errorMessage.js";
77
import { diag } from "../ui/diagnostics.js";
88
import type { CapturePhaseProgress } from "../capture/types.js";
99
import { parseCaptureDeadline } from "../capture/captureWatchdog.js";
10+
import { jsonFailure } from "../utils/jsonError.js";
1011

1112
const CAPTURE_PHASE_PREFIX = "HYPERFRAMES_CAPTURE_PHASE ";
1213

@@ -347,7 +348,7 @@ export default defineCommand({
347348
/* best-effort */
348349
}
349350
if (isJson) {
350-
console.log(JSON.stringify({ ok: false, error: errMsg }));
351+
console.log(JSON.stringify(jsonFailure("runtime_error", errMsg)));
351352
} else {
352353
console.error(`\n ✗ Capture failed: ${errMsg}\n`);
353354
}

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -850,7 +850,7 @@ it("rejects malformed caption-zone specs instead of silently disabling the gate"
850850
expect(log).toHaveBeenCalledTimes(1);
851851
expect(JSON.parse(String(log.mock.calls[0]?.[0]))).toEqual({
852852
ok: false,
853-
error: expect.stringContaining("Invalid --caption-zone"),
853+
error: expect.objectContaining({ message: expect.stringContaining("Invalid --caption-zone") }),
854854
_meta: { version: "test" },
855855
});
856856
});

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

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@ import type { CaptionZoneOptions, FrameCheckOptions, LayoutOptions } from "../ut
4040
import { resolveLocalBrowserGpuMode } from "../browser/gpuPolicy.js";
4141
import { preResolveHostileMediaProxies, type PreparedMediaFile } from "../utils/checkBrowser.js";
4242
import { parseTimeoutMs } from "../utils/timeoutArg.js";
43+
import { failureMessage, jsonFailure } from "../utils/jsonError.js";
4344

4445
export const examples: Example[] = [
4546
["Run the full verification gate", "hyperframes check"],
@@ -302,10 +303,10 @@ export function createCheckCommand(
302303
}
303304
setCommandExitCode(checkExitCode(report));
304305
} catch (error) {
305-
const message = normalizeErrorMessage(error);
306+
const message = failureMessage(error);
306307
if (asJson) {
307308
console.log(
308-
JSON.stringify(dependencies.withMeta({ ok: false, error: message }), null, 2),
309+
JSON.stringify(dependencies.withMeta(jsonFailure("runtime_error", message)), null, 2),
309310
);
310311
} else {
311312
console.error(`${c.error("✗")} Check failed: ${message}`);

0 commit comments

Comments
 (0)