Skip to content

feat(cli): add stable JSON output contract - #176

Merged
owainlewis merged 1 commit into
mainfrom
codex/166-json-cli
Jul 30, 2026
Merged

feat(cli): add stable JSON output contract#176
owainlewis merged 1 commit into
mainfrom
codex/166-json-cli

Conversation

@owainlewis

@owainlewis owainlewis commented Jul 30, 2026

Copy link
Copy Markdown
Owner

Summary

Adds a versioned global --json contract 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, and job runs output. The path projection consumes PushPaths, including the post-#165 runtime owner, and documents state as the legacy migration source after #173 moved live cursor/session state into push.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 onto 3911f1b:

  • cargo fmt --all -- --check
  • cargo clippy --locked --all-targets -- -D warnings
  • cargo build --locked
  • cargo 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 --strict
  • git diff origin/main...HEAD --check
  • Fresh independent review of the exact final diff: approved with no remaining findings
  • GitHub CI: strict docs, Ubuntu, and macOS jobs all passed

Risks

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

@owainlewis
owainlewis marked this pull request as ready for review July 30, 2026 13:56
@owainlewis
owainlewis merged commit 4d83511 into main Jul 30, 2026
3 checks passed
@owainlewis
owainlewis deleted the codex/166-json-cli branch July 30, 2026 13:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add a stable JSON CLI contract

1 participant