fix(cli-framework): safely serialize error data to preserve original CLIError

TY
1d ago
+47-10

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:

  1. Circular references throw TypeError: Converting circular structure to JSON.
  2. BigInt values throw TypeError: Do not know how to serialize a BigInt.
  3. 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

  1. In packages/cli-framework/src/runner.ts, wrap JSON.stringify(error.data, null, 2) in a try/catch guard.
  2. Only write to process.stdout when serialization succeeds and yields a defined string (text !== undefined).
  3. If serialization fails or produces undefined, skip stdout emission and allow the original CLIError to be rethrown untouched.
  4. Added unit tests in packages/cli-framework/src/runner.test.ts verifying that:
    • Circular references in CLIError.data preserve the original error message and suggestion on stderr without throwing a TypeError.
    • BigInt values in CLIError.data preserve the original error message and suggestion on stderr without throwing a TypeError.
    • Payloads serializing to undefined skip stdout writes and preserve the original error on stderr.

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 BigInt data 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.