feat: [#352] add JSON output to provision command

[josecelano]

Overview

Adds machine-readable JSON output format (--output-format json) to the provision command, enabling automation workflows to programmatically extract provisioned instance details without regex parsing of console output.

Closes #352
Parent Epic: #348

What Changed

Implementation (Commit: 422692f)

Added Files:

• src/presentation/views/commands/provision/provision_details.rs - DTO for provision output data
• src/presentation/views/commands/provision/text_view.rs - Human-readable text output (default)
• src/presentation/views/commands/provision/json_view.rs - Machine-readable JSON output
• src/presentation/views/commands/provision/mod.rs - Module exports and documentation

Modified Files:

• src/presentation/controller/commands/provision/handler.rs - Strategy Pattern format switching
• src/presentation/controller/errors.rs - OutputFormatting error variant
• src/presentation/controller/router.rs - output_format parameter passing

7 files changed: 707 insertions(+), 108 deletions(-)

Documentation (Commit: 2341244)

Updated Files:

• docs/user-guide/commands/provision.md - Added Output Formats section with 6 automation examples
• docs/user-guide/commands.md - Updated common options
• docs/issues/352-add-json-output-to-provision-command.md - Updated implementation status

3 files changed: 464 insertions(+), 114 deletions(-)

Architecture

Follows the Strategy Pattern established in #349:

• DTO Layer: ProvisionDetailsData for data transfer
• View Layer: TextView and JsonView for format-specific rendering
• Controller Layer: Format selection via ExecutionContext::output_format()

DDD Compliance: Views in presentation layer only format data, no business logic.

JSON Output Schema

{
  "environment_name": "my-environment",
  "instance_name": "torrust-tracker-vm-my-environment",
  "instance_ip": "10.140.190.42",
  "ssh_private_key_path": "/home/user/.ssh/id_rsa",
  "ssh_public_key_path": "/home/user/.ssh/id_rsa.pub",
  "ssh_username": "torrust",
  "ssh_port": 22,
  "provider": "lxd",
  "domains": [],
  "provisioned_at": "2026-02-16T13:38:02.446056727Z"
}

Testing

Unit Tests ✅

• 22 tests passing (18 view tests + 4 controller tests)
• Text view: 3 tests (non-HTTPS, HTTPS with domains, field formatting)
• JSON view: 5 tests (structure, HTTPS, non-HTTPS, serialization, field types)
• Controller: 4 tests (text format, JSON format, format routing, error handling)

Manual Tests ✅

• 10/10 tests passed with real provisioned VMs
• JSON output validation with jq
• IP address extraction
• Field extraction for automation
• HTTPS domains array population
• Default text output (backward compatibility)
• Stdout/stderr separation
• Provider field correctness
• Timestamp format (ISO 8601)
• Empty domains array for HTTP-only

Quality Checks ✅

• ✅ All 2252 unit tests passing
• ✅ All linters passing (markdown, yaml, toml, cspell, clippy, rustfmt, shellcheck)
• ✅ No unused dependencies (cargo-machete)
• ✅ Pre-commit checks passing

Use Cases Enabled

1. SSH Connection Automation

JSON=$(torrust-tracker-deployer provision my-env -o json --log-output file-only)
IP=$(echo "$JSON" | jq -r '.instance_ip')
ssh -i "$(echo "$JSON" | jq -r '.ssh_private_key_path')" \
    "$(echo "$JSON" | jq -r '.ssh_username')@$IP"

2. CI/CD Pipeline Integration

- name: Provision
  run: |
    OUTPUT=$(torrust-tracker-deployer provision $ENV -o json)
    echo "ip=$(echo $OUTPUT | jq -r '.instance_ip')" >> $GITHUB_OUTPUT

3. DNS Automation (HTTPS deployments)

DOMAINS=$(torrust-tracker-deployer provision tracker -o json | jq -r '.domains[]')
# Update DNS A records with provisioned IP

Breaking Changes

None. Default behavior unchanged (human-readable text output).

Documentation

• ✅ Output Formats section added to provision command docs
• ✅ JSON schema documented with field descriptions
• ✅ 6 automation examples (Shell, GitHub Actions, Python, Terraform, domain extraction)
• ✅ Common options updated

Reviewer Notes

• Pattern Consistency: Identical architecture to Add JSON Output to create Command #349 (create command JSON output)
• Test Coverage: Comprehensive unit tests + 10 real-world manual tests
• Documentation: User guide includes automation examples for common workflows
• Backward Compatibility: Existing text output preserved as default

Checklist

• Implementation complete and committed
• Unit tests passing (22 tests)
• Manual E2E tests passing (10 tests)
• All linters passing
• Documentation updated
• No unused dependencies
• Pre-commit checks passing

[josecelano]

ACK 2341244