fix(cli-framework): safely serialize error data to preserve original CLIError
Summary
Fixes #10087. In the CLI framework runner, safely serialize CLIError.data when running in JSON mode so that serialization failures (such as cyclic structures or BigInts) or non-serializable payloads do not throw an unhandled TypeError that replaces the original command error.
Root Cause & Problem
In packages/cli-framework/src/runner.ts, when a command fails under --json (or auto-JSON in agent mode) and throws a CLIError containing a data payload, the runner attempts to output the payload to stdout before re-throwing the error:
await writeStream(
process.stdout,
`${JSON.stringify(error.data, null, 2)}\n`,
signal,
).catch(() => {});
Because JSON.stringify(error.data, null, 2) runs inside template string interpolation before writeStream is invoked, any exception thrown during serialization escapes before the stream-write promise is created. Consequently:
- Circular references throw
TypeError: Converting circular structure to JSON. BigIntvalues throwTypeError: Do not know how to serialize a BigInt.- Functions or undefined values serialize to
undefined, causing stdout to receive the literal invalid JSON text"undefined\n".
When a TypeError occurs, it preempts throw error;. The top-level error handler catches the TypeError instead of the original CLIError, replacing the command error message and suggestion with the serializer TypeError.
Technical Solution
- In
packages/cli-framework/src/runner.ts, wrapJSON.stringify(error.data, null, 2)in atry/catchguard. - Only write to
process.stdoutwhen serialization succeeds and yields a defined string (text !== undefined). - If serialization fails or produces
undefined, skip stdout emission and allow the originalCLIErrorto be rethrown untouched. - Added unit tests in
packages/cli-framework/src/runner.test.tsverifying that:- Circular references in
CLIError.datapreserve the original error message and suggestion on stderr without throwing a TypeError. BigIntvalues inCLIError.datapreserve the original error message and suggestion on stderr without throwing a TypeError.- Payloads serializing to
undefinedskip stdout writes and preserve the original error on stderr.
- Circular references in
Test Plan
- Ran targeted tests in
packages/cli-framework/src/runner.test.ts:
bun test packages/cli-framework/src/runner.test.ts
All 15 tests passed cleanly (including 3 new regression tests). - Verified Biome formatting and lint checks:
bunx @biomejs/biome@2.4.2 check packages/cli-framework/src/runner.ts packages/cli-framework/src/runner.test.ts
Passed with zero issues and no format changes needed.
Summary by cubic
Fixes a bug in the CLI framework where non-serializable CLIError.data payloads (like circular references or BigInts) caused a TypeError to be thrown, replacing the original CLIError in JSON mode. The framework now safely skips writing error data to stdout when serialization fails, preserving the original error message and hint on stderr. Adds regression tests for these failure cases.
Summary by CodeRabbit
- Bug Fixes
- In JSON mode, CLI errors containing circular or
BigIntdata no longer cause a secondary serialization error. The original error is preserved and the command exits with code 1. - When error data cannot be serialized to JSON or serializes to
undefined, the runner skips writing that JSON output while preserving the original error and exit code.
- In JSON mode, CLI errors containing circular or