Add JSON output format support to create command

[josecelano]

Summary

Implements issue #349 - Adds machine-readable JSON output format to the create environment command, enabling automation workflows and CI/CD integration.

Changes

Architecture (5 Phases)

Phase 0: View Layer Extraction (67c10ff)

• Extracted view layer for create command following MVC pattern
• Created EnvironmentDetailsData DTO and EnvironmentDetailsView
• Aligned with existing provision/list/show command architecture

Phase 1: Global OutputFormat Argument (7ce64b0)

• Added OutputFormat enum (Text | Json) with clap integration
• Added --output-format global CLI argument
• Extended GlobalArgs and ExecutionContext with format support

Phase 2: Strategy Pattern Implementation (2ecb391)

• Separated TextView and JsonView implementations
• Applied SOLID principles with Strategy Pattern
• Added Serialize derive to EnvironmentDetailsData

Phase 3: Format Switching (afa7ef9)

• Wired output_format through ExecutionContext → Router → Controller
• Implemented format switching with match expression
• Added OutputFormatting error variant with detailed help

Phase 4: Documentation (ad2ac21)

• Added comprehensive "Output Formats" section to user guide
• Documented JSON schema with field descriptions
• Added 8+ automation examples (Shell, CI/CD, Python, multi-env)
• Explained stdout/stderr channel separation

Features

✅ Two Output Formats:

• Text (default): Human-readable numbered list with progress indicators
• JSON: Machine-readable structured data for automation

✅ JSON Output Schema:

{
  "environment_name": "my-env",
  "instance_name": "torrust-tracker-vm-my-env",
  "data_dir": "./data/my-env",
  "build_dir": "./build/my-env",
  "created_at": "2026-02-16T13:38:02.446056727Z"
}

✅ CLI Usage:

# Default text output
torrust-tracker-deployer create environment --env-file config.json

# JSON output for automation
torrust-tracker-deployer create environment --env-file config.json --output-format json

# Short form
torrust-tracker-deployer create environment --env-file config.json -o json

Quality Assurance

• ✅ All 2230 unit tests pass
• ✅ All 394 doctests pass
• ✅ All linters pass (clippy, rustfmt, markdown, yaml, toml, cspell, shellcheck)
• ✅ Pre-commit checks pass
• ✅ E2E testing completed:
  • Default text output verified
  • JSON output validated with jq
  • Error handling tested
  • Channel separation confirmed (stdout/stderr)
• ✅ No unused dependencies (cargo-machete clean)

Documentation

• User guide updated with comprehensive examples
• JSON schema documented with field descriptions
• Automation examples for Shell, CI/CD, Python
• Output channel separation explained
• Usage guidelines included

Testing

Manual Verification

# Text output (default)
./target/release/torrust-tracker-deployer create environment \
  --env-file envs/test.json

# JSON output
./target/release/torrust-tracker-deployer create environment \
  --env-file envs/test.json \
  --output-format json

# JSON validation with jq
./target/release/torrust-tracker-deployer create environment \
  --env-file envs/test.json \
  -o json \
  --log-output file-only | jq .

Automation Example

# Extract environment details
DATA_DIR=$(./target/release/torrust-tracker-deployer create environment \
  --env-file config.json \
  -o json \
  --log-output file-only | jq -r '.data_dir')

Related

• Closes Add JSON Output to create Command #349
• Part of Epic EPIC: Add JSON output format support #348 - Add JSON output format support
• Roadmap Section 12.1

Breaking Changes

None. This is a backward-compatible addition. Default behavior (text output) is preserved.

Future Work

This implementation provides the foundation for adding JSON output to other commands:

• provision (refactor: improve TrackerContext type safety with structured database configs #350)
• show (Add JSON output format support to create command #351)
• list (Add JSON output to provision command #352)
• status (feat: [#352] add JSON output to provision command #353)

[josecelano]

ACK ad2ac21