Make CLI output machine-readable and pipeable - #588
Draft
razor-x wants to merge 2 commits into
Draft
Conversation
Replace ad hoc console.log calls with an injectable Output so the CLI has one place that decides what goes where, and so output can be asserted in tests with an in-memory implementation. - Only command results go to stdout: prompts, spinners, progress, and other information are written to stderr. - Add --json to read request params from stdin and write the response as JSON. The JSON format is used automatically when stdout is not a terminal, and --no-json opts out. - Support unix pipes end to end: params may be piped or redirected in, and the response piped or redirected out. - Trim responses to the response key and pagination, using the response key from the API blueprint. - Exit non-zero on a failed request or an error. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NKsb8oTieozDEGJtiwWqBo
…traction-a6znxb # Conflicts: # src/lib/interact-for-custom-metadata.ts
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR refactors the CLI to produce machine-readable, pipeable output. Only API responses are written to stdout (as JSON or pretty-printed text), while prompts, progress, and other information are written to stderr. This allows CLI commands to be safely piped into other programs.
Key Changes
Output abstraction: Created
Outputinterface with separate methods for data (stdout), text (stdout), info/warn/error (stderr). ImplementedcreateOutput()factory supporting both JSON and text formats.Response trimming: Added
selectResponsePayload()to reduce API responses to only the response key and pagination, removing transport metadata likeokandrequest_id.JSON mode: Implemented
--jsonflag to read request params from stdin as JSON and write responses as JSON. Automatically enabled when stdout is not a terminal.Stdin param reading: Added
readStdinJson()andparseJsonParams()utilities to parse request parameters from stdin or--jsonflag, with proper error handling.Prompt refactoring: Extracted
prompt()andcanPrompt()utilities that render prompts to stderr and prevent prompting when stdin is not a TTY (piped input).CLI flag handling: Introduced
cliFlagsset to prevent CLI-specific flags (--json,-y,--help, etc.) from being sent as request parameters.Response key extraction: Added
getResponseKey()to determine the response key for a command from the API blueprint, used to trim responses appropriately.Error handling: Failed requests now exit with code 1 and report only the error object on stdout for inspection from pipes.
Updated all interactions: Migrated all
promptsimports to use the newprompt()wrapper, and replacedconsole.logcalls withoutput.info(),output.error(), etc.Notable Implementation Details
getOutput()/setOutput()to allow tests to inject a memory-based output implementation.--jsonare merged with flag params, with flags taking precedence.-y(non-interactive) since there's nobody to prompt.test/cli.test.ts) covering version, help, JSON I/O, param merging, error handling, and output formatting.https://claude.ai/code/session_01NKsb8oTieozDEGJtiwWqBo