feat: [#355] add JSON output to show command

[josecelano]

Overview

Adds JSON output format support to the show command, enabling machine-readable environment information for automation and scripting. This implements #355 and contributes to Phase 1 of EPIC #348 (JSON output for high-value commands).

Changes

Implementation

• DTOs with Serialization (Application Layer):

  • Added #[derive(Serialize)] to all show command DTOs:
    • EnvironmentInfo, InfrastructureInfo
    • ServiceInfo, LocalhostServiceInfo, TlsDomainInfo
    • PrometheusInfo, GrafanaInfo

• JsonView (Presentation Layer):

  • Created JsonView struct with render() method using serde_json::to_string_pretty()
  • Reorganized views/ module: TextView in separate file, new mod.rs with re-exports
  • Comprehensive unit tests for all state variations

• Controller Wiring:

  • Updated show controller to accept output_format: OutputFormat
  • Added view selection logic: match output_format { Text => TextView, Json => JsonView }
  • Updated router to pass context.output_format() through

Documentation

• Updated docs/user-guide/commands/show.md:
  • Added --output-format option documentation
  • JSON examples for Provisioned and Running states
  • Automation examples using jq for JSON parsing

Usage

# Human-readable text output (default)
torrust-tracker-deployer show my-env

# Machine-readable JSON output
torrust-tracker-deployer show my-env --output-format json
torrust-tracker-deployer show my-env -o json

Examples

Provisioned State (JSON)

{
  "name": "my-environment",
  "state": "Provisioned",
  "provider": "LXD",
  "created_at": "2026-02-16T17:56:43.788700279Z",
  "infrastructure": {
    "instance_ip": "10.140.190.85",
    "ssh_port": 22,
    "ssh_user": "torrust",
    "ssh_key_path": "/home/user/.ssh/torrust_key"
  },
  "services": null,
  "prometheus": null,
  "grafana": null,
  "state_name": "provisioned"
}

Running State (JSON)

{
  "name": "my-environment",
  "state": "Running",
  "services": {
    "udp_trackers": ["udp://udp.tracker.local:6969/announce"],
    "https_http_trackers": ["https://http.tracker.local/announce"],
    "api_endpoint": "https://api.tracker.local/api",
    "api_uses_https": true,
    "health_check_url": "https://health.tracker.local/health_check",
    "tls_domains": [...]
  },
  "prometheus": {
    "access_note": "Internal only (localhost:9090)"
  },
  "grafana": {
    "url": "https://grafana.tracker.local/",
    "uses_https": true
  },
  "state_name": "running"
}

Automation Example

# Extract API URL and check tracker stats
API_URL=$(torrust-tracker-deployer show my-env -o json | \
    jq -r '.services.api_endpoint // empty')

if [ -n "$API_URL" ]; then
    curl "$API_URL/stats"
fi

Testing

Unit Tests

• ✅ All 398 tests passing, 89 ignored, 0 failed
• New tests in json_view.rs:
  • it_should_render_json_for_created_state
  • it_should_render_json_for_provisioned_state
  • it_should_produce_valid_json (validates with serde_json::from_str)
  • 2 doc tests demonstrating API usage

Manual Testing

Verified with real environments:

# Provisioned state - tested with text-output-test
cargo run -- show text-output-test -o json | python3 -m json.tool
✓ Valid JSON structure
✓ Nulls for services/prometheus/grafana (expected for Provisioned)

# Running state - tested with lxd-local-https-example
cargo run -- show lxd-local-https-example -o json | python3 -m json.tool
✓ Valid JSON structure
✓ Complete service information
✓ All tracker endpoints present

Linters

• ✅ All linters passing: markdown, yaml, toml, cspell, clippy, rustfmt, shellcheck
• ✅ No clippy warnings with -- -D warnings

Architecture

Follows the Strategy Pattern established in:

• #349 - JSON output for create command
• #352 - JSON output for provision command

Benefits from refactor PR #354 which properly organized the views module structure.

Roadmap Progress

• Task 12.1: create command JSON output (Add JSON Output to create Command #349) ✅ Merged
• Task 12.2: provision command JSON output (Add JSON output to provision command #352) ✅ Merged
• Task 12.3: show command JSON output (Add JSON output to show command #355) ✅ This PR
• Task 12.4: run command JSON output
• Task 12.5: list command JSON output

Related Issues

• Implements: Add JSON output to show command #355 (Add JSON output to show command)
• Part of: EPIC: Add JSON output format support #348 (EPIC: Add JSON output for automated workflows)
• Parent Refactor: refactor: separate view data from views in presentation layer #354 (Separate view data from views in presentation layer)

Checklist

• Implementation complete (DTOs, JsonView, controller wiring)
• Unit tests added and passing
• Manual testing with real environments
• Documentation updated
• All linters passing
• Follows Strategy Pattern from Add JSON Output to create Command #349 and Add JSON output to provision command #352

[josecelano]

ACK 09dfda7