Add Clap Subcommand Configuration

[josecelano]

Add Clap Subcommand Configuration

Type: Task
Priority: High
Parent Epic: #10 - UI Layer Destroy Command
Dependencies: #21 - MUST BE COMPLETED FIRST (E2E Infrastructure Preservation)
Estimated Effort: 3-4 hours

---

📋 Issue Overview

Implement the destroy subcommand in the CLI with basic functionality and UserOutput scaffolding. This creates the user-facing interface that calls the DestroyCommandHandler from the application layer.

🔗 Dependencies

Blocking Dependency: Issue #21 (Fix E2E Infrastructure Preservation)

This issue CANNOT be implemented until Issue #21 is completed because:

1. Manual Testing Required: The destroy CLI command must be manually tested to ensure it works correctly
2. E2E Infrastructure Needed: Manual testing requires preserving E2E infrastructure using --keep flag
3. Verification Workflow: Developers need to:
   • Run E2E tests with --keep to provision infrastructure
   • Test the destroy CLI command on that preserved infrastructure
   • Verify complete cleanup using LXD commands (lxc list | grep e2e-provision)

Without Issue #21 completed, the manual testing workflow is broken and this destroy CLI implementation cannot be properly validated.

🎯 Goals

• Add destroy subcommand to Clap configuration
• Wire up subcommand to call DestroyCommandHandler from application layer
• Implement VerbosityLevel enum and UserOutput struct
• Add essential progress messages using UserOutput
• Ensure separation between user output and internal logging

📦 Scope

Clap Subcommand Structure

Add to src/app.rs:

#[derive(Subcommand)]
pub enum Commands {
    /// Destroy an existing deployment environment
    Destroy {
        /// Name of the environment to destroy
        environment: String,
    },
}

UserOutput Integration

• Add VerbosityLevel enum (Quiet, Normal, Verbose, VeryVerbose, Debug)
• Add UserOutput struct with methods for different message types
• Note: Only enum definition for now, no Clap verbosity flags yet
• Use UserOutput for essential destroy command messages

Example Usage

torrust-tracker-deployer destroy <ENVIRONMENT_NAME>

Example Output (Normal verbosity level)

⏳ Destroying environment 'my-env'...
⏳ Tearing down infrastructure...
⏳ Cleaning up resources...
✅ Environment 'my-env' destroyed successfully

✅ Acceptance Criteria

Prerequisites: Issue #21 (Fix E2E Infrastructure Preservation) must be completed before this can be fully tested and accepted.

• destroy subcommand added to Clap configuration
• Subcommand accepts required environment parameter
• VerbosityLevel enum implemented with 5 levels (Quiet, Normal, Verbose, VeryVerbose, Debug)
• UserOutput struct implemented with dual writers and proper channel separation
• Channel strategy follows console output patterns research (progress to stderr, results to stdout)
• Essential destroy messages implemented using appropriate channels
• Subcommand successfully calls DestroyCommandHandler from application layer
• User-friendly error messages for invalid environment names
• Help text provides clear usage information
• Unit tests implemented with buffer writers for output capture and assertion
• Unit tests verify proper channel separation (stdout vs stderr)
• Unit tests cover CLI argument parsing and error handling
• Manual testing completed using E2E test infrastructure (--keep flag)
• Manual testing verifies complete infrastructure, data, and build cleanup
• User output completely separated from internal logging
• All linting passes successfully
• Integration works end-to-end with existing command handler

Manual Testing Procedure

⚠️ Prerequisite: Issue #21 (Fix E2E Infrastructure Preservation) must be completed first. The --keep flag functionality is required for this testing procedure.

Step 1: Set up test infrastructure using E2E tests

# Run E2E provision and destroy test but keep infrastructure (don't auto-destroy)
cargo run --bin e2e_provision_and_destroy_tests -- --keep

# This creates an environment named "e2e-provision" with infrastructure ready for testing

Step 2: Test the new destroy CLI command

# Test help output
cargo run -- help destroy
cargo run -- destroy --help

# Test basic destroy command with the E2E environment
cargo run -- destroy e2e-provision

# Test invalid environment names
cargo run -- destroy invalid-name!
cargo run -- destroy ""

Step 3: Verify complete cleanup

# Verify infrastructure is completely destroyed
ls data/e2e-provision/          # Should not exist
ls build/e2e-provision/         # Should not exist
lxc list | grep e2e-provision   # Should return nothing (VM destroyed)

🔗 Related Issues

• Parent Epic: EPIC: UI Layer Destroy Command #10 (UI Layer Destroy Command)
• Dependencies: Fix E2E Infrastructure Preservation #21 (Fix E2E Infrastructure Preservation) - MUST BE COMPLETED FIRST
• Follows: Rename App Commands to Command Handlers #22 (Rename App Commands to Command Handlers) - benefits from clear terminology

📚 Related Documentation

• Console Output Patterns Research - Channel usage strategy
• User Output vs Logging Separation
• Development Principles

---

Full specification: See docs/issues/add-clap-subcommand-configuration.md