feat(cli): add generic output formatter to eliminate --output flag duplication

[jeffmaury]

Summary

Creates a new output.rs module with generic helper functions for formatting CLI command output in JSON, YAML, or table formats. This eliminates ~38 lines of duplicated code across 4 commands and provides a single source of truth for output formatting.

Related Issue

Closes #1750

Changes

• New module: crates/openshell-cli/src/output.rs with 6 helper functions and 14 tests
  • print_output_collection() - For collections of items
  • print_output_single() - For single items
  • print_output_direct() - For pre-formatted output
• Migrated commands in crates/openshell-cli/src/run.rs:
  • gateway_list(): 23 lines → 5 lines
  • sandbox_list(): 17 lines → 5 lines
  • provider_list_profiles(): 12 lines → 7 lines
  • provider_profile_export(): 11 lines → 8 lines
• Documentation:
  • New architecture/cli.md - CLI architecture documentation
  • Updated architecture/README.md - Added CLI architecture reference

Testing

• mise run pre-commit passes
• Unit tests added/updated (14 new tests in output.rs)
• E2E tests added/updated (not applicable - refactor preserves existing behavior)

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[github-actions]

All contributors have signed the DCO ✍️ ✅
_{Posted by the DCO Assistant Lite bot.}

[jeffmaury]

have read the DCO document and I hereby sign the DCO.

[jeffmaury]

recheck

[jeffmaury]

recheck

[johntmyers]

gator-agent

PR Review Status

Validation: this PR is project-valid because it implements the linked validated CLI refactor from #1750 and keeps the work concentrated to CLI output helpers, four existing call sites, and architecture notes.
Head SHA: 6d3f53ffc619bce4e2dfa2cdd905fdfbacdb69c6

Review findings:

• No blocking findings remain from the independent code-only review.

Docs: no Fern docs update is required because this preserves existing CLI behavior; architecture documentation was added under architecture/.

E2E: no test:* label required; this is an interface-preserving CLI refactor and does not affect sandbox lifecycle, gateway/supervisor behavior, policy enforcement, network proxy behavior, provider credential flow, runtime drivers, GPU, or Kubernetes behavior.

Next state: gator:watch-pipeline

[johntmyers]

/ok to test 6d3f53f

[johntmyers]

@jeffmaury thanks for the PR. we keep the arch directory intentionally thin. i think we can remove the cli.md addition and the reference to it. FYI gator to watch for this update.

[johntmyers]

gator-agent

Author Action Needed

Branch Checks are failing on the current head SHA 6d3f53ffc619bce4e2dfa2cdd905fdfbacdb69c6, and maintainer feedback has requested a doc-scope change.

Required author updates:

• Remove architecture/cli.md and the architecture/README.md reference, per the maintainer comment above.
• Fix Rust clippy failures in crates/openshell-cli/src/output.rs tests: replace assert_eq!(..., true) / assert_eq!(..., false) with assert!(...) / assert!(!...). Current failures are clippy::bool_assert_comparison at lines 332, 344, 356, 382, 394, 406, 416, 426, 450, 468, 485, and 500.

Markdown lint also reports architecture/cli.md:20 (MD032/blanks-around-lists), but removing the architecture doc addition should make that failure moot.

Next state: gator:in-review

[johntmyers]

gator-agent

Author Action Needed

Thanks for the follow-up update. The architecture doc feedback is resolved, and the prior bool-assert cleanup is mostly resolved, but the latest head SHA 991cc1825756e24d0c67687c784e7cbd72d65b03 still has one blocking test regression.

Required author update:

• In crates/openshell-cli/src/output.rs, test_print_output_collection_table now uses assert!(result.unwrap()) even though print_output_collection("table", ...) intentionally returns Ok(false) so callers continue to table rendering. Please change it to assert!(!result.unwrap()).

I am keeping this in gator:in-review until that is fixed. After the next update, gator can re-check the diff and then move back to pipeline watch if no review findings remain.

[johntmyers]

/ok to test 991cc18

[johntmyers]

gator-agent

Re-check After Author Update

I re-evaluated latest head 82505eab2db5a83b9db5f66c1d993060bf6a93ed after jeffmaury's 2026-06-08 commit, fix: fix wrong CLI output test.

Disposition: resolved. The prior test_print_output_collection_table regression is fixed with assert!(!result.unwrap()), matching the intended Ok(false) table behavior.

Remaining items:

• No blocking review items remain from the independent code-only re-review.

Docs: no Fern docs update is required because this preserves existing CLI behavior; the architecture doc addition and README reference were removed per maintainer feedback.

E2E: no test:* label required for this interface-preserving CLI refactor.

Next state: gator:watch-pipeline

[johntmyers]

/ok to test 82505ea

[johntmyers]

gator-agent

Maintainer Approval Needed

Gator validation and PR monitoring are complete.

Validation: this PR is project-valid because it implements the linked validated CLI refactor from #1750 and keeps the final change concentrated to CLI output helper reuse in crates/openshell-cli.
Review: no blocking findings remain from the independent code-only review and follow-up re-check at head 82505eab2db5a83b9db5f66c1d993060bf6a93ed.
Docs: no Fern docs update is required because this preserves existing CLI behavior; the architecture doc addition and README reference were removed per maintainer feedback.
Checks: required gates are green: OpenShell / Branch Checks, OpenShell / Helm Lint, and DCO.
E2E: N/A; no test:* labels are required for this interface-preserving CLI refactor, and OpenShell / E2E plus OpenShell / GPU E2E report pass because those labels are not applied.

Human maintainer approval or merge decision is now required.