Implement Provision Console Command

[josecelano]

Overview

Implement the presentation layer for the provision console command to enable users to provision VM infrastructure from the CLI. The application layer ProvisionCommandHandler is already implemented - this task focuses on creating the console interface (CLI command, controller, router integration, and user interaction).

Specification

See detailed specification: docs/issues/implement-provision-console-command.md

(Link will be updated after issue number is assigned and file is renamed)

🏗️ Architecture Requirements

DDD Layer: Presentation
Module Path: src/presentation/
Pattern: CLI Subcommand + Controller (single command pattern)

Module Structure Requirements

• Follow DDD layer separation (see docs/codebase-architecture.md)
• Use ExecutionContext pattern for dependency injection
• Controller follows destroy controller reference pattern
• Error handling uses explicit enum errors (see docs/contributing/error-handling.md)
• Module organization follows project conventions (see docs/contributing/module-organization.md)

Architectural Constraints

• No business logic in presentation layer - delegate to ProvisionCommandHandler
• Single command pattern - No subcommands, direct execution like destroy
• Dependencies flow toward application layer - Controller depends on ProvisionCommandHandler
• User output through UserOutput trait - Consistent output formatting
• Error messages are actionable - Include help methods with troubleshooting steps

Anti-Patterns to Avoid

• ❌ Implementing provisioning logic in controller (already in ProvisionCommandHandler)
• ❌ Direct infrastructure access from presentation layer
• ❌ Using anyhow for command-specific errors
• ❌ Mixing routing and execution logic

Implementation Plan

Phase 1: CLI Command Definition (30 minutes)

• Add Provision variant to Commands enum in src/presentation/input/cli/commands.rs
• Add comprehensive documentation comments
• Test CLI parsing with cargo build

Phase 2: Controller Structure (1 hour)

• Create src/presentation/controllers/provision/ directory
• Create mod.rs with module exports
• Create errors.rs with ProvisionSubcommandError enum
• Implement help() method for all error variants
• Implement Display and Error traits
• Implement From conversions for error types

Phase 3: Controller Handler (2 hours)

• Create handler.rs with main handle() function
• Implement environment name validation
• Implement repository initialization
• Load environment from repository (validate Created state)
• Create progress reporter with 9 steps
• Call ProvisionCommandHandler::execute()
• Handle success and error cases
• Add comprehensive documentation

Phase 4: Router Integration (30 minutes)

• Add provision module to src/presentation/controllers/mod.rs
• Update src/presentation/dispatch/router.rs with provision route
• Update CommandError if needed for provision errors
• Test routing with minimal integration test

Phase 5: Testing (1.5 hours)

• Create src/presentation/controllers/provision/tests/mod.rs
• Add unit tests for error help messages
• Add unit tests for handler with mock services
• Add integration test for successful provision
• Add integration test for error cases (invalid state, not found)
• Test CLI parsing and routing

Phase 6: Documentation and Review (30 minutes)

• Update module documentation
• Verify all error messages are actionable
• Check code follows module organization conventions
• Verify import style (short names, no long paths)
• Run linters and fix any issues

Phase 7: Manual End-to-End Testing (45 minutes)

Perform complete workflow testing to verify the provision command integrates correctly with create and destroy commands:

• Step 1: Create temporary test directory
• Step 2: Run create command (verify state shows Created)
• Step 3: Run provision command (verify all 9 steps, state shows Provisioned, instance IP saved)
• Step 4: Run destroy command (verify infrastructure torn down)
• Step 5: Validate state consistency (Created → Provisioned → Destroyed)
• Step 6: Test error scenarios (non-existent environment, already provisioned)

Acceptance Criteria

Note for Contributors: These criteria define what the PR reviewer will check. Use this as your pre-review checklist before submitting the PR to minimize back-and-forth iterations.

Quality Checks:

• Pre-commit checks pass: ./scripts/pre-commit.sh

CLI Integration:

• torrust-tracker-deployer provision <environment> command is available
• torrust-tracker-deployer provision --help shows clear documentation
• CLI parsing correctly extracts environment name parameter

Controller Implementation:

• Controller follows destroy controller reference pattern
• Handler function uses ExecutionContext pattern
• Error type provides actionable help messages for all variants
• Progress reporter shows all 9 provisioning steps
• Success message includes instance IP address

Router Integration:

• Provision command is registered in dispatch router
• Router correctly routes to provision controller
• Error handling flows correctly through layers

Error Handling:

• Invalid environment name shows validation rules
• Environment not found suggests create workflow
• Invalid state error explains current state and required state
• All error messages follow actionability principles
• Errors include context for traceability

Testing:

• Unit tests cover error help messages
• Unit tests cover handler logic with mocks
• Integration tests verify successful provision workflow
• Integration tests verify error cases
• All tests pass locally
• Manual E2E testing completed successfully

Code Quality:

• Follows DDD layer placement guidelines
• Respects dependency flow rules
• Uses appropriate module organization
• Import style uses short names
• Documentation is comprehensive
• No clippy warnings
• Code is formatted with rustfmt

User Experience:

• Progress updates are clear and informative
• Success message includes all relevant information
• Error messages guide users to solutions
• Command integrates seamlessly with existing CLI

Related

• Parent: Scaffolding for main app - 8/9 tasks complete (89%) #2 (Epic: Scaffolding for main app)
• Roadmap: Roadmap #1 (Project Roadmap)
• Specification: docs/issues/implement-provision-console-command.md