feat(cli): add stable JSON output contract - #176
Merged
Conversation
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
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
Adds a versioned global
--jsoncontract for read-only automation commands while keeping human-readable output as the default. Success writes one JSON document to stdout, failures write a structured JSON error to stderr, and documented exit categories cover invalid input, configuration, unavailable dependencies, transient transport, conflicts, and unexpected failures.Adds machine-readable
doctor,status,paths,job validate,job list,job show, andjob runsoutput. The path projection consumesPushPaths, including the post-#165 runtime owner, and documentsstateas the legacy migration source after #173 moved live cursor/session state intopush.db. Job-run JSON omits stored output, errors, message content, and co-located backend session IDs.Why
Automation and agents need stable schemas, clean streams, and reliable exit codes. Mutation commands reject JSON mode because interrupted outcomes cannot always be classified as safe to retry.
Test plan
Verified on exact commit
93f554c, rebased onto3911f1b:cargo fmt --all -- --checkcargo clippy --locked --all-targets -- -D warningscargo build --lockedcargo test --locked(376 unit, 2 docs, 14 init CLI, 13 JSON CLI, 3 crash tests; 408 total)uv run --with-requirements requirements-docs.txt mkdocs build --strictgit diff origin/main...HEAD --checkRisks
Service status parsing is covered with launchd and systemd command fixtures, including loaded-but-stopped launchd services and operational manager failures. Live systemd behavior was not independently exercised.
Related issue
Closes #166