Add JSON output to run command

[josecelano]

Parent Epic: #348 - Add JSON output format support
Related: Roadmap Section 12.4, #349 (create) ✅, #352 (provision) ✅, #355 (show) ✅
Specification: docs/issues/357-add-json-output-to-run-command.md

Overview

Add machine-readable JSON output format (--output-format json or -o json) to the run command. This enables automation workflows and AI agents to programmatically extract service URLs and verify which services are running without parsing human-readable text.

Goals

• Implement JSON output format for run command
• Preserve existing human-readable output as default
• Enable automation to extract service URLs and verify service availability
• Follow the architecture pattern established in Add JSON Output to create Command #349, Add JSON output to provision command #352, and Add JSON output to show command #355

Value Proposition

For Automation: Scripts can parse JSON to extract service URLs (API, tracker, health check, Grafana) and verify they are accessible programmatically.

For AI Agents: Machine-readable format enables agents to understand service configuration and verify deployment success without regex parsing.

For CI/CD: Pipelines can extract service endpoints, verify expected services are running, and configure DNS based on TLS domain information.

Architecture

Pattern: Strategy Pattern with TextView and JsonView
Location: src/presentation/views/commands/run/
DTOs: Reuse existing ServiceInfo and GrafanaInfo from src/application/command_handlers/show/info/

Specification Details

See full specification: docs/issues/357-add-json-output-to-run-command.md

JSON Output Structure

{
  "environment_name": "my-env",
  "state": "Running",
  "services": {
    "udp_trackers": ["udp://udp.tracker.local:6969/announce"],
    "https_http_trackers": ["https://http.tracker.local/announce"],
    "direct_http_trackers": ["http://10.140.190.133:7070/announce"],
    "api_endpoint": "https://api.tracker.local/api",
    "api_uses_https": true,
    "health_check_url": "https://health.tracker.local/health_check",
    "health_check_uses_https": true,
    "tls_domains": [...]
  },
  "grafana": {
    "url": "https://grafana.tracker.local/",
    "uses_https": true
  }
}

Actual Current Output (Verified via Live Deployment)

The specification includes the actual current text output captured from live deployments to ensure we can verify the text format doesn't break when adding JSON support:

Basic HTTP-only:

✅ Run command completed for 'test-run-output-basic'

Services are now accessible:
  Tracker (UDP):  udp://udp.tracker.local:6969/announce
  Tracker (HTTP): http://10.140.190.133:7070/announce
  API:            http://10.140.190.133:1212/api
  Health Check:   http://10.140.190.133:1313/health_check
  Grafana:        http://10.140.190.133:3000/

Tip: Run 'torrust-tracker-deployer show test-run-output-basic' for full details

HTTPS with DNS hint:

✅ Run command completed for 'test-run-output-https'

Services are now accessible:
  Tracker (UDP):  udp://udp.tracker.local:6969/announce
  Tracker (HTTP): https://http.tracker.local/announce
  API:            https://api.tracker.local/api
  Health Check:   https://health.tracker.local/health_check
  Grafana:        https://grafana.tracker.local/


Note: HTTPS services require DNS configuration. See 'show' command for details.

Tip: Run 'torrust-tracker-deployer show test-run-output-https' for full details

Use Cases

1. Extract Service URLs for Testing: Automation scripts parse JSON to test API/health check endpoints
2. Verify Service Configuration: AI agents verify HTTPS is enabled, expected services are running
3. CI/CD Integration: Pipelines verify deployment success by checking service availability
4. DNS Configuration Automation: Extract TLS domains and instance IP for DNS updates

Implementation Steps

1. Create src/presentation/views/commands/run/ module
2. Implement TextView (refactor existing output logic)
3. Implement JsonView (serialize service information)
4. Wire view selection in RunCommandController
5. Update router to pass output_format
6. Add unit tests for both views
7. Update user documentation

Success Criteria

• JSON output format implemented
• Human-readable text output unchanged (backward compatible)
• All service URLs included in JSON output
• TLS domain information included when configured
• Grafana information included when configured
• Unit tests pass for both TextView and JsonView
• All linters pass
• User documentation updated

References

• Specification: docs/issues/357-add-json-output-to-run-command.md
• Previous implementations: Add JSON Output to create Command #349 (create), Add JSON output to provision command #352 (provision), Add JSON output to show command #355 (show)
• Parent EPIC: EPIC: Add JSON output format support #348
• Output handling: docs/contributing/output-handling.md