Implement Configure CLI Command

[josecelano]

Overview

Implement the CLI presentation layer for the configure command, exposing the existing ConfigureCommandHandler application layer logic to end users. This enables users to transition deployment environments from "Provisioned" state to "Configured" state via the CLI interface.

Specification

See detailed specification: docs/issues/180-implement-configure-cli-command.md

🏗️ Architecture Requirements

DDD Layer: Presentation
Module Path: src/presentation/controllers/configure/
Pattern: CLI Subcommand Controller

Module Structure Requirements

• Follow DDD layer separation (see docs/codebase-architecture.md)
• Match structure of provision controller: mod.rs, errors.rs, handler.rs, tests/
• Use appropriate module organization (see docs/contributing/module-organization.md)

Architectural Constraints

• No business logic in presentation layer (delegate to ConfigureCommandHandler)
• Use ExecutionContext pattern for dependency injection
• Error handling follows project conventions (see docs/contributing/error-handling.md)
• All errors implement .help() with actionable guidance

Anti-Patterns to Avoid

• ❌ Implementing configuration logic in presentation layer
• ❌ Direct infrastructure calls (use application layer)
• ❌ Generic error messages without help guidance

Implementation Plan

Phase 1: CLI Command Definition (15 min)

• Add Configure variant to Commands enum in src/presentation/input/cli/commands.rs
• Add comprehensive documentation following provision pattern
• Verify CLI parsing with --help

Phase 2: Presentation Controller (1-2 hours)

• Create src/presentation/controllers/configure/ directory
• Implement mod.rs with module documentation and exports
• Implement errors.rs with ConfigureSubcommandError and .help() methods
• Implement handler.rs with progress reporting and state validation

Phase 3: Integration (30 min)

• Add configure controller to router in src/presentation/dispatch/router.rs
• Add configure error variant to CommandError in src/presentation/errors.rs
• Update src/presentation/controllers/mod.rs to export configure module

Phase 4: Testing (1-2 hours)

• Create integration tests for successful and error scenarios
• Verify progress reporting and error messages
• Test state validation

Phase 5: Manual E2E Testing (30 min)

• Test complete workflow: create → provision → configure → verify → cleanup
• Verify Docker and Docker Compose installation via SSH
• Test error handling for invalid states

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

Functional Requirements:

• torrust-tracker-deployer configure <name> command is available
• Command validates environment is in "Provisioned" state
• Configuration workflow executes (Docker, Docker Compose installation)
• Environment transitions to "Configured" state on success
• Environment transitions to "ConfigureFailed" state on error
• State changes are persisted to repository

User Experience:

• Progress reporting shows clear step-by-step feedback
• Error messages include actionable help via .help() method
• Command appears in main CLI --help output
• Success message indicates next steps

Code Quality:

• Follows existing presentation layer patterns (matches provision controller)
• Documentation is comprehensive with examples
• No clippy warnings or rustfmt issues

Testing:

• Unit tests pass
• Integration tests cover happy path and error cases
• Manual E2E test confirms full deployment workflow works

Architecture Compliance:

• Presentation layer only (no business logic)
• Uses ExecutionContext pattern
• Integrates with existing ConfigureCommandHandler
• Error handling provides traceability and actionability

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/180-implement-configure-cli-command.md

Notes

Estimated Time: 4-6 hours

Reference Implementation: Follow the exact pattern from src/presentation/controllers/provision/

No New Business Logic: All configuration logic already exists in ConfigureCommandHandler - this task only exposes it via CLI.