Skip to content

Commit 21814c3

Browse files
jrusso1020claude
andcommitted
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]>
1 parent aeb5991 commit 21814c3

39 files changed

Lines changed: 435 additions & 137 deletions

‎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: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -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) => {
@@ -174,6 +211,21 @@ describe("agent-mode contract", () => {
174211
},
175212
);
176213

214+
it("a runtime failure under --json is an envelope that says why, not empty stdout", async () => {
215+
const run = await runAsAgent(["info", "--json"]);
216+
expectQuiet(run);
217+
expect(run.code).toBe(1);
218+
expectJsonFailure(run, "runtime_error");
219+
expect(run.stdout).toContain("No composition found");
220+
});
221+
222+
it("an unknown command under --json is an envelope with the suggestion", async () => {
223+
const run = await runAsAgent(["rendr", "--json"]);
224+
expect(run.code).toBe(2);
225+
expectJsonFailure(run, "unknown_command");
226+
expect(JSON.parse(run.stdout).error.hint).toBe("Did you mean 'hyperframes render'?");
227+
});
228+
177229
it("an unknown flag suggests the flag it most likely means", async () => {
178230
const run = await runAsAgent(["render", "--out", "x.mp4"]);
179231
expect(run.code).toBe(2);

‎packages/cli/src/cli.ts‎

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

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

544551
async function showRequestedUsage(print: (text: string) => void): Promise<void> {
@@ -585,6 +592,7 @@ function commandResultForError(error: unknown): CommandResult {
585592
// fallow-ignore-next-line complexity
586593
async function executeCli(): Promise<void> {
587594
let result: CommandResult = { exitCode: 0, kind: "success" };
595+
let failure: unknown;
588596
try {
589597
if (isHelp) await showRequestedUsage(console.log);
590598
else {
@@ -595,6 +603,7 @@ async function executeCli(): Promise<void> {
595603
const error = isCittyError(caught, "E_UNKNOWN_COMMAND")
596604
? await unknownCommandError(await resolveCommandUsage(main as CommandDef, argv))
597605
: caught;
606+
failure = error;
598607
result = commandResultForError(error);
599608
if (!(error instanceof CliResultSignal)) {
600609
commandFailed = true;
@@ -610,6 +619,9 @@ async function executeCli(): Promise<void> {
610619
} finally {
611620
const pending = consumeCommandResult();
612621
if (pending.exitCode !== 0 || result.exitCode === 0) result = pending;
622+
if (jsonOutput && result.exitCode !== 0 && !jsonOutput.wroteStdout()) {
623+
writeJsonFailure(jsonErrorBody(failure, result, jsonOutput.stderrText()));
624+
}
613625
await finalizeCli(result);
614626
}
615627
}

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

Lines changed: 3 additions & 2 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 { jsonFailure } from "../utils/jsonError.js";
45

56
export const examples: Example[] = [
67
["Add a block to the current project", "hyperframes add claude-code-window"],
@@ -556,7 +557,7 @@ export default defineCommand({
556557
// Not a single item — try as a tag for bulk install
557558
if (!(singleErr instanceof AddError) || singleErr.code !== "unknown-item") {
558559
const msg = singleErr instanceof Error ? singleErr.message : String(singleErr);
559-
if (json) console.log(JSON.stringify({ ok: false, error: msg }));
560+
if (json) console.log(JSON.stringify(jsonFailure("runtime_error", msg)));
560561
else console.error(c.error(msg));
561562
failCommand();
562563
}
@@ -579,7 +580,7 @@ export default defineCommand({
579580

580581
if (items.length === 0) {
581582
const msg = singleErr instanceof Error ? singleErr.message : String(singleErr);
582-
if (json) console.log(JSON.stringify({ ok: false, error: msg }));
583+
if (json) console.log(JSON.stringify(jsonFailure("runtime_error", msg)));
583584
else console.error(c.error(msg));
584585
failCommand();
585586
}

‎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
@@ -382,7 +382,10 @@ describe("capture command — vision control", () => {
382382
const payload = log.mock.calls.at(-1)?.[0];
383383
expect(typeof payload).toBe("string");
384384
if (typeof payload !== "string") throw new Error("Expected JSON failure payload");
385-
expect(JSON.parse(payload)).toMatchObject({ ok: false, error: "required extraction failed" });
385+
expect(JSON.parse(payload)).toMatchObject({
386+
ok: false,
387+
error: expect.objectContaining({ message: "required extraction failed" }),
388+
});
386389
} finally {
387390
rmSync(dir, { recursive: true, force: true });
388391
}

‎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: 2 additions & 1 deletion
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 { jsonFailure } from "../utils/jsonError.js";
4344

4445
export const examples: Example[] = [
4546
["Run the full verification gate", "hyperframes check"],
@@ -305,7 +306,7 @@ export function createCheckCommand(
305306
const message = normalizeErrorMessage(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)