refactor: [#107] extract DestroyCommandController with private step methods

- Create DestroyCommandController struct to encapsulate workflow orchestration
- Extract private step methods: validate_environment_name, initialize_dependencies, tear_down_infrastructure, complete_workflow
- Add DESTROY_WORKFLOW_STEPS constant for step count
- Simplify handle_destroy_command to be a thin wrapper over controller
- Improve testability by separating concerns between presentation and application layers
- Add comprehensive documentation with # Errors sections for public methods

This refactor improves code clarity, maintainability, and testability while maintaining backward compatibility with existing tests.

Author: josecelano

src/presentation/commands/destroy/handler.rs

@@ -3,43 +3,205 @@
 //! This module handles the destroy command execution at the presentation layer,
 //! including environment validation, repository initialization, and user interaction.
 
+use std::path::PathBuf;
 use std::sync::{Arc, Mutex};
 
+use crate::application::command_handlers::DestroyCommandHandler;
 use crate::domain::environment::name::EnvironmentName;
+use crate::domain::environment::state::Destroyed;
+use crate::domain::Environment;
+use crate::presentation::commands::context::CommandContext;
 use crate::presentation::commands::factory::CommandHandlerFactory;
 use crate::presentation::progress::ProgressReporter;
 use crate::presentation::user_output::UserOutput;
 
 use super::errors::DestroySubcommandError;
 
-/// Handle the destroy command
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+
+/// Number of main steps in the destroy workflow
+const DESTROY_WORKFLOW_STEPS: usize = 3;
+
+// ============================================================================
+// PRESENTATION LAYER CONTROLLER
+// ============================================================================
+
+/// Presentation layer controller for destroy command workflow
+///
+/// Coordinates user interaction, progress reporting, and input validation
+/// before delegating to the application layer `DestroyCommandHandler`.
+///
+/// # Responsibilities
 ///
-/// This function orchestrates the environment destruction workflow with progress reporting:
-/// 1. Validating the environment name
-/// 2. Tearing down infrastructure
-/// 3. Cleaning up resources
+/// - Validate user input (environment name format)
+/// - Show progress updates to the user
+/// - Format success/error messages for display
+/// - Delegate business logic to application layer
+///
+/// # Architecture
+///
+/// This controller sits in the presentation layer and handles all user-facing
+/// concerns. It delegates actual business logic to the application layer's
+/// `DestroyCommandHandler`, maintaining clear separation of concerns.
+pub struct DestroyCommandController {
+    factory: CommandHandlerFactory,
+    ctx: CommandContext,
+    progress: ProgressReporter,
+}
+
+impl DestroyCommandController {
+    /// Create a new destroy command controller
+    ///
+    /// # Arguments
+    ///
+    /// * `working_dir` - Root directory for environment data storage
+    /// * `user_output` - Shared user output service for consistent formatting
+    pub fn new(working_dir: PathBuf, user_output: Arc<Mutex<UserOutput>>) -> Self {
+        let factory = CommandHandlerFactory::new();
+        let ctx = factory.create_context(working_dir, user_output.clone());
+        let progress = ProgressReporter::new(user_output, DESTROY_WORKFLOW_STEPS);
+
+        Self {
+            factory,
+            ctx,
+            progress,
+        }
+    }
+
+    /// Execute the complete destroy workflow
+    ///
+    /// Orchestrates all steps of the destroy command:
+    /// 1. Validate environment name
+    /// 2. Initialize dependencies
+    /// 3. Tear down infrastructure
+    /// 4. Complete with success message
+    ///
+    /// # Arguments
+    ///
+    /// * `environment_name` - The name of the environment to destroy
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if:
+    /// - Environment name is invalid (format validation fails)
+    /// - Environment cannot be loaded from repository
+    /// - Infrastructure teardown fails
+    /// - Progress reporting encounters a poisoned mutex
+    ///
+    /// # Returns
+    ///
+    /// Returns `Ok(())` on success, or a `DestroySubcommandError` if any step fails.
+    #[allow(clippy::result_large_err)]
+    pub fn execute(&mut self, environment_name: &str) -> Result<(), DestroySubcommandError> {
+        let env_name = self.validate_environment_name(environment_name)?;
+        let handler = self.initialize_dependencies()?;
+        let _destroyed = self.tear_down_infrastructure(&handler, &env_name)?;
+        self.complete_workflow(environment_name)?;
+        Ok(())
+    }
+
+    /// Validate the environment name format
+    ///
+    /// Shows progress to user and validates that the environment name
+    /// meets domain requirements (1-63 chars, alphanumeric + hyphens).
+    #[allow(clippy::result_large_err)]
+    fn validate_environment_name(
+        &mut self,
+        name: &str,
+    ) -> Result<EnvironmentName, DestroySubcommandError> {
+        self.progress.start_step("Validating environment")?;
+
+        let env_name = EnvironmentName::new(name.to_string()).map_err(|source| {
+            DestroySubcommandError::InvalidEnvironmentName {
+                name: name.to_string(),
+                source,
+            }
+        })?;
+
+        self.progress
+            .complete_step(Some(&format!("Environment name validated: {name}")))?;
+
+        Ok(env_name)
+    }
+
+    /// Initialize application layer dependencies
+    ///
+    /// Creates the application layer command handler with all required
+    /// dependencies (repository, clock, etc.).
+    #[allow(clippy::result_large_err)]
+    fn initialize_dependencies(&mut self) -> Result<DestroyCommandHandler, DestroySubcommandError> {
+        self.progress.start_step("Initializing dependencies")?;
+        let handler = self.factory.create_destroy_handler(&self.ctx);
+        self.progress.complete_step(None)?;
+        Ok(handler)
+    }
+
+    /// Execute infrastructure teardown via application layer
+    ///
+    /// Delegates to the application layer `DestroyCommandHandler` to
+    /// orchestrate the actual infrastructure destruction workflow.
+    #[allow(clippy::result_large_err)]
+    fn tear_down_infrastructure(
+        &mut self,
+        handler: &DestroyCommandHandler,
+        env_name: &EnvironmentName,
+    ) -> Result<Environment<Destroyed>, DestroySubcommandError> {
+        self.progress.start_step("Tearing down infrastructure")?;
+
+        let destroyed = handler.execute(env_name).map_err(|source| {
+            DestroySubcommandError::DestroyOperationFailed {
+                name: env_name.to_string(),
+                source,
+            }
+        })?;
+
+        self.progress
+            .complete_step(Some("Infrastructure torn down"))?;
+        Ok(destroyed)
+    }
+
+    /// Complete the workflow with success message
+    ///
+    /// Shows final success message to the user with workflow summary.
+    #[allow(clippy::result_large_err)]
+    fn complete_workflow(&mut self, name: &str) -> Result<(), DestroySubcommandError> {
+        self.progress
+            .complete(&format!("Environment '{name}' destroyed successfully"))?;
+        Ok(())
+    }
+}
+
+// ============================================================================
+// PUBLIC ENTRY POINT
+// ============================================================================
+
+/// Handle the destroy command
 ///
-/// Each step is tracked and timed using `ProgressReporter` for clear user feedback.
+/// This is a thin wrapper over `DestroyCommandController` that serves as
+/// the public entry point for the destroy command.
 ///
 /// # Arguments
 ///
 /// * `environment_name` - The name of the environment to destroy
 /// * `working_dir` - Root directory for environment data storage
 /// * `user_output` - Shared user output service for consistent output formatting
 ///
-/// # Returns
-///
-/// Returns `Ok(())` on success, or a `DestroySubcommandError` if:
-/// - Environment name is invalid
-/// - Environment cannot be loaded
-/// - Destruction fails
-///
 /// # Errors
 ///
-/// This function will return an error if the environment name is invalid,
-/// the environment cannot be loaded, or the destruction process fails.
+/// Returns an error if:
+/// - Environment name is invalid (format validation fails)
+/// - Environment cannot be loaded from repository
+/// - Infrastructure teardown fails
+/// - Progress reporting encounters a poisoned mutex
+///
 /// All errors include detailed context and actionable troubleshooting guidance.
 ///
+/// # Returns
+///
+/// Returns `Ok(())` on success, or a `DestroySubcommandError` on failure.
+///
 /// # Example
 ///
 /// ```rust
@@ -60,48 +222,14 @@ pub fn handle_destroy_command(
     working_dir: &std::path::Path,
     user_output: &Arc<Mutex<UserOutput>>,
 ) -> Result<(), DestroySubcommandError> {
-    // Create factory and context with all shared dependencies
-    let factory = CommandHandlerFactory::new();
-    let ctx = factory.create_context(working_dir.to_path_buf(), user_output.clone());
-
-    // Create progress reporter for 3 main steps
-    let mut progress = ProgressReporter::new(ctx.user_output().clone(), 3);
-
-    // Step 1: Validate environment name
-    progress.start_step("Validating environment")?;
-    let env_name = EnvironmentName::new(environment_name.to_string()).map_err(|source| {
-        DestroySubcommandError::InvalidEnvironmentName {
-            name: environment_name.to_string(),
-            source,
-        }
-    })?;
-    progress.complete_step(Some(&format!(
-        "Environment name validated: {environment_name}"
-    )))?;
-
-    // Step 2: Initialize dependencies
-    progress.start_step("Initializing dependencies")?;
-    let command_handler = factory.create_destroy_handler(&ctx);
-    progress.complete_step(None)?;
-
-    // Step 3: Execute destroy command (tear down infrastructure)
-    progress.start_step("Tearing down infrastructure")?;
-    let _destroyed_env = command_handler.execute(&env_name).map_err(|source| {
-        DestroySubcommandError::DestroyOperationFailed {
-            name: environment_name.to_string(),
-            source,
-        }
-    })?;
-    progress.complete_step(Some("Infrastructure torn down"))?;
-
-    // Complete with summary
-    progress.complete(&format!(
-        "Environment '{environment_name}' destroyed successfully"
-    ))?;
-
-    Ok(())
+    DestroyCommandController::new(working_dir.to_path_buf(), user_output.clone())
+        .execute(environment_name)
 }
 
+// ============================================================================
+// TESTS
+// ============================================================================
+
 #[cfg(test)]
 mod tests {
     use super::*;