cli-design

Route only data and results to stdout, and send all progress, spinners, warnings, and errors to stderr. stdout is block-buffered when piped for throughput, while stderr is unbuffered so diagnostics appear immediately even when stdout is piped to another program.

Use 0 for success, 1 for domain failures, 2 for invalid usage, 75 for temporary failures that retry logic can act on, and 78 for configuration errors. Codes 130 and 143 represent SIGINT and SIGTERM; never use codes above 125 for application errors since they are reserved for signals.

Add a --json flag that emits only valid JSON on stdout using a consistent envelope with ok, data, and error fields. Errors must be structured JSON too, including a machine-readable code, message, fix suggestion, and a transient boolean for retry logic.

Yes, check flags first, then NO_COLOR, FORCE_COLOR, TERM=dumb, CI, and finally isatty on each stream independently. When stdout is piped but stderr is a TTY, you can still show spinners on stderr while keeping piped stdout free of ANSI escape codes.

Piping breaks when diagnostics or ANSI codes leak onto stdout, or when SIGPIPE is unhandled. In Node.js, SIGPIPE is ignored by default and surfaces as an EPIPE error, so you must catch it and exit silently with code 141.

Spawn the CLI as a subprocess with a test runner helper that captures stdout, stderr, and exit code independently. Assert that --json output parses as valid JSON, non-zero exits always include a stderr explanation, and piped output contains no ANSI codes or spinner characters.