Skip to content

refactor(cli): add a JSON-or-text output helper and migrate two commands - #908

Merged
jussielo-amd merged 4 commits into
mainfrom
refactor-json-or-text-helper
Nov 5, 2026
Merged

jussielo-amd merged 4 commits into
mainfrom
refactor-json-or-text-helper

Conversation

@jussielo-amd

@jussielo-amd jussielo-amd commented Nov 5, 2026 •

Copy link
Copy Markdown
Collaborator

Why

Commands with a --json flag each branch on it by hand: if json { println!("{}", serde_json::to_string_pretty(&value)?) } else { print!(..) }. Nothing says what the JSON newline, the error on a failed serialization, or the text form's trailing newline should be, so each site decides for itself. #773 asks for a shared helper that new commands must use and existing ones adopt incrementally, not a bulk retrofit. This PR is the first step.

What

  • apps/rocm/src/cli_report.rs (the existing shared CLI-output module) gains trait JsonOrText: Serialize { fn render_text(&self) -> String } and print_json_or_text(json, &value).
    • JSON mode writes pretty JSON plus exactly one newline. Text mode writes render_text() verbatim, so the text owns its trailing newline.
    • The output is fully built before the first write, so a serialization failure prints nothing and returns an error with context. A failed write also returns an error with context (see the behaviour note below).
    • A writer-based inner function (write_json_or_text) is unit-tested with a Vec<u8>, a value that fails to serialize, and a writer that fails.
  • Migrated, with stdout unchanged byte for byte:
    • rocm storage report: StorageReport implements the trait on top of the existing render_report.
    • rocm diagnose (the non---report path): a small borrowing view, DiagnoseOutput, serializes as the report and renders the text, including the model-readiness block and the remote-inspection note that used to be separate println!s. New unit tests pin each of those pieces.
  • AGENTS.md gets the "Shared UI components" (CLI) bullet asking new --json commands to use it; docs/architecture.md lists it in the cli_report.rs entry.

Behaviour difference on a closed stdout

Stdout bytes are unchanged, but what happens when the reader of stdout has gone away differs for the two migrated commands. Before, println!/print! panicked on a failed write (exit 101). Now the helper returns an error failed to write the command output, which main prints as Error: ... on stderr and exits with ExitCode::FAILURE (1). On Unix this only shows up where the failure reaches the process as a write error: main calls reset_sigpipe() at startup, so rocm storage report | head is ended by SIGPIPE itself before and after this change, with no panic and no error. Where there is no SIGPIPE to deliver (Windows, for a closed pipe) the old behaviour was the panic and the new behaviour is the error and exit code above. This is read from reset_sigpipe and run in apps/rocm/src/main.rs and the helper; it was not exercised against a real closed pipe here, and the unit test write_failure_is_an_error_not_a_panic covers the error path with a writer that always fails.

Call-site survey (current main)

The numbers in the issue are out of date: there are 6 --json flags in apps/rocm (examine, diagnose, fix, update, storage report, services list) and 9 if json branches.

Site Status
storage report migrated
diagnose migrated
diagnose --report refusal (envelope value plus an explanation string) clean fit, needs a tiny wrapper like DiagnoseOutput; left to keep this diff small
fix with no id (catalog) JSON comes back pre-serialized from rocm-core; fits once core exposes the value
fix <id> --json not output, an argument guard that bails
examine not a fit: the JSON mode gathers differently from the text mode (the text path writes, the JSON path must not)
update not a fit: compact JSON, and audit events recorded around each print
diagnose --report (prepared report) not a fit: the text mode prints the JSON and then performs a delivery
services list not a fit as is: two loaders returning pre-rendered strings, and the JSON form is read back by rocm remote

Outside that, internal-bridge-snapshot, internal-sandbox-run, the rocmd CLI and the three engine adapters print JSON only (no text form), so they are not candidates.

Migration plan

Per the issue: new --json commands use the helper (documented in AGENTS.md); existing sites move over when they are next touched, starting with the two "fits with a wrapper" rows above. No bulk retrofit.

Verification

Run locally on the PR head plus the follow-up test commit: cargo fmt --all --check; cargo clippy -p rocm --all-targets -- -D warnings; cargo test -p rocm --bin rocm --no-fail-fast (1477 passed, 8 ignored, 0 failed, including the new tests); cargo xtask manifest --check; cargo xtask check-crate-edges. Not run locally: the workspace-wide gate, python scripts/smoke_local.py and cargo xtask e2e; CI carries those. The commits are signed and carry a Signed-off-by trailer, and CI has built and tested the change.

The new tests were shown to fail with their target broken (AGENTS.md section 3), each by a one-line edit that was then reverted:

  • Dropping the document.push('\n') in write_json_or_text turns json_mode_writes_pretty_json_and_one_trailing_newline red.
  • Dropping the .context("failed to serialize the command output as JSON") turns serialization_failure_is_an_error_and_writes_nothing red.
  • Dropping the .context("failed to write the command output") turns write_failure_is_an_error_not_a_panic red.
  • Making StorageReport::render_text return a different string than render_report turns json_or_text_impl_renders_the_report_and_serializes_it red.

Scenario coverage

The output of the two migrated commands is unchanged, so no new Gherkin scenario is added (a refactor, per AGENTS.md section 3); the new unit tests cover the helper, the storage report impl and the diagnose views. Existing scenarios already run the migrated commands through the real binary, and this change keeps them passing: for rocm storage report text, server-records-01 (@id:server-records-storage-report-names-the-folder) and uninstall-05 (@id:uninstall-moved-data-folder-keeps-its-own-cache); for rocm diagnose, diagnose-01 (@id:diagnose-matches-known-symptom) for the text form, diagnose-03 (@id:diagnose-json-has-match-flag) for --json, and diagnose-21 (@id:diagnose-model-too-large-is-refused-with-something-that-fits) for the model block in both forms. They run on the mock lane on every PR. No scenario passes --json to rocm storage report, so the JSON half of that impl is covered only by the unit test.

Refs #773

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues remain for the shared CLI output changes, though compilation, linting, and tests still depend on CI.

No open issues 🎉

What changed in this PR

Introduces shared JSON-or-text output handling for the CLI, starting the incremental migration requested in #773 without a bulk retrofit.

Changes:

  • Adds JsonOrText and print_json_or_text with consistent formatting, error propagation, and unit tests.
  • Migrates storage report and the non---report diagnose path while preserving their output.
  • Documents helper adoption guidance and updates the architecture inventory.

Compilation, linting, and tests were not run locally; verification remains dependent on CI.

File Description
docs/​architecture.md Lists the shared output helpers in the module inventory.
apps/​rocm/​src/​storage.rs Routes storage reports through the new helper.
apps/​rocm/​src/​diagnose_cmd.rs Adds a report view and output-preservation tests.
apps/​rocm/​src/​cli_report.rs Defines the trait, writer helper, and formatting/error tests.
AGENTS.md Documents when commands should adopt the helper.

Review effort: Balanced

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues are recorded for the shared CLI output helper and its initial command migrations.

No open issues 🎉

Review effort: Balanced

@jussielo-amd
jussielo-amd marked this pull request as ready for review November 5, 2026 11:04
@jussielo-amd
jussielo-amd requested a review from a team as a code owner November 5, 2026 11:04
Every command with a --json flag branched on it by hand and called
serde_json::to_string_pretty itself. Add JsonOrText and print_json_or_text
to cli_report.rs so a command with one value and one text rendering prints
it one way, with the serialization and write errors surfaced and the output
built before anything is written.

Migrate `rocm storage report` and `rocm diagnose` (output unchanged) as the
first call sites, and add the AGENTS.md bullet asking new commands to use it.
The remaining sites move over incrementally as they are touched.

Refs #773

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
… and cover the diagnose views

Switch the `rocm storage report` call site to the shared helper (output
unchanged). Pin the pieces of `rocm diagnose` output that moved into
DiagnoseOutput (the JSON being the report itself, the blank line before the
model readiness, the remote-inspection note), and say in docs/architecture.md
and the doc comments what JsonOrText covers.

Refs #773

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
Refs #773

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
@jussielo-amd
jussielo-amd force-pushed the refactor-json-or-text-helper branch from b83bf91 to 5a75f5a Compare November 5, 2026 11:31

@juhovainio juhovainio left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good. The JsonOrText trait and print_json_or_text helper cover the three asks in #773 (shared helper, AGENTS.md bullet, incremental migration with no bulk retrofit), the shared-component docs are in sync, and CI is green.

Non-blocking:

  • StorageReport's JsonOrText impl and the rocm storage report call site have no test of their own (inline).
  • The PR body says the new tests were not shown to fail with their target broken; AGENTS.md §3 asks for that mutation check (inline).
  • A closed stdout (e.g. | head) used to panic and now returns an error with a non-zero exit. Stdout bytes are unchanged, but the exit/stderr behaviour differs; worth a sentence in the PR body.
  • The PR body is stale: it says the commits are unsigned and the signature check is expected to fail, and that nothing was compiled, but the commits are verified and CI has built and tested the change.

Comment thread apps/rocm/src/storage.rs
output
}

impl JsonOrText for StorageReport {

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nothing tests this impl or the call site below. Consider a unit test that render_text() equals render_report(&report), or cite the e2e scenario that pins rocm storage report output.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added json_or_text_impl_renders_the_report_and_serializes_it in 5ee279f: it asserts render_text() equals render_report(&report), that the text names the shared-folders section, and that the JSON keeps its four top-level fields. The text form of the call site is pinned through the real binary by the server-records-01 and uninstall-05 scenarios; no scenario passes --json to storage report, so the JSON half is covered by the unit test only.

/// The whole output is built before the first byte is written, so a value that
/// fails to serialize leaves `writer` untouched instead of half a document.
/// Text mode does not render the JSON and JSON mode does not render the text.
fn write_json_or_text(

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please confirm by mutation (drop the push('\n'), drop the .context) that the tests below go red; the PR body says this was not done (AGENTS.md §3).

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done, each by a one-line edit reverted afterwards: dropping push('\n') turns json_mode_writes_pretty_json_and_one_trailing_newline red, dropping the serialize .context turns serialization_failure_is_an_error_and_writes_nothing red, and dropping the write .context turns write_failure_is_an_error_not_a_panic red. The results are in the PR body.

…port and the JSON fields

The JsonOrText impl for StorageReport had no test of its own. The new test checks that render_text() equals render_report() and names the shared-folders section, and that the serialized report keeps its four top-level fields. The text form of the rocm storage report call site is already pinned black-box by the server-records-01 and uninstall-05 scenarios; no scenario passes --json, which is why the JSON half is asserted here.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
@jussielo-amd

Copy link
Copy Markdown
Collaborator Author

Thanks for the approval. The PR body is rewritten: the stale claims that the commits are unsigned and nothing was compiled are gone, it lists what was actually run, adds the mutation results, and names the covering scenarios (server-records-01 and uninstall-05 for the storage report text, diagnose-01, diagnose-03 and diagnose-21 for rocm diagnose). On the closed-stdout difference you noted: on Unix main.rs calls reset_sigpipe() at startup, so | head ends the process by SIGPIPE before and after this PR; where no SIGPIPE is delivered (Windows), println! used to panic with exit 101 and the helper now returns "failed to write the command output", prints Error: ... on stderr and exits 1. I read that from reset_sigpipe and the error path in main.rs and did not run it against a real closed pipe, and the body says so. 5ee279f adds the storage report test; cargo test -p rocm --bin rocm passes (1477), clippy and fmt are clean.

@jussielo-amd
jussielo-amd added this pull request to the merge queue Nov 5, 2026
Merged via the queue into main with commit 7037dbe Nov 5, 2026
30 checks passed
@jussielo-amd
jussielo-amd deleted the refactor-json-or-text-helper branch November 5, 2026 18:30
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.

3 participants