refactor: [#61] extract step execution result type (Proposal #2)

Author: josecelano

docs/refactors/plans/command-handlers-refactoring.md

@@ -28,13 +28,13 @@ This refactoring addresses code quality issues in `src/application/command_handl
 **Total Active Proposals**: 7
 **Total Postponed**: 2
 **Total Discarded**: 2
-**Completed**: 2
+**Completed**: 3
 **In Progress**: 0
-**Not Started**: 5
+**Not Started**: 4
 
 ### Phase Summary
 
-- **Phase 0 - Quick Wins (High Impact, Low Effort)**: ⏳ 2/3 completed (66%)
+- **Phase 0 - Quick Wins (High Impact, Low Effort)**: ✅ 3/3 completed (100%)
 - **Phase 1 - Structural Improvements (High Impact, Medium Effort)**: ⏳ 0/2 completed (0%)
 - **Phase 2 - Consistency & Polish (Medium Impact, Low Effort)**: ⏳ 0/2 completed (0%)
 
@@ -441,7 +441,8 @@ Created `TypedEnvironmentRepository` wrapper in the domain layer (`src/domain/en
 
 ### Proposal #2: Extract Step Execution Result Type
 
-**Status**: ⏳ Not Started  
+**Status**: ✅ Completed  
+**Commit**: c04ef8b  
 **Impact**: 🟢🟢 Medium  
 **Effort**: 🔵 Low  
 **Priority**: P0
@@ -516,14 +517,14 @@ async fn execute_provisioning_with_tracking(
 
 #### Implementation Checklist
 
-- [ ] Create `src/application/command_handlers/common/step_tracking.rs`
-- [ ] Define `StepResult` type alias
-- [ ] Update provision handler signatures
-- [ ] Update configure handler signatures
-- [ ] Update destroy handler signatures
-- [ ] Verify all tests pass
-- [ ] Run linter
-- [ ] Update documentation
+- [x] Create type alias in `src/application/command_handlers/common/mod.rs`
+- [x] Define `StepResult<T, E, S>` type alias with documentation
+- [x] Update provision handler signatures (1 method)
+- [x] Update configure handler signatures (1 method)
+- [x] Update destroy handler signatures (1 method)
+- [x] Verify all tests pass (991 unit tests + 48 integration tests)
+- [x] Run linter (all linters pass)
+- [x] Update documentation (comprehensive doc comments added)
 
 #### Testing Strategy
 

src/application/command_handlers/common/mod.rs

@@ -4,3 +4,30 @@
 //! to reduce code duplication and improve maintainability.
 
 pub mod failure_context;
+
+/// Result type for step execution in command handlers
+///
+/// This type alias captures the common pattern used across all command handlers
+/// where step execution can fail with both an error and the step that was being
+/// executed when the failure occurred.
+///
+/// # Type Parameters
+///
+/// * `T` - The success value type (e.g., `Environment<Provisioned>` or `()`)
+/// * `E` - The error type (e.g., `ProvisionCommandHandlerError`)
+/// * `S` - The step type (e.g., `ProvisionStep`)
+///
+/// # Example
+///
+/// ```rust,ignore
+/// fn execute_with_tracking(
+///     &self,
+///     environment: &Environment<Provisioning>,
+/// ) -> StepResult<Environment<Provisioned>, ProvisionCommandHandlerError, ProvisionStep> {
+///     let current_step = ProvisionStep::RenderTemplates;
+///     self.render_templates()
+///         .map_err(|e| (e, current_step))?;
+///     // ... more steps
+/// }
+/// ```
+pub type StepResult<T, E, S> = Result<T, (E, S)>;

src/application/command_handlers/configure/handler.rs

@@ -6,6 +6,7 @@ use tracing::{info, instrument};
 
 use super::errors::ConfigureCommandHandlerError;
 use crate::adapters::ansible::AnsibleClient;
+use crate::application::command_handlers::common::StepResult;
 use crate::application::steps::{InstallDockerComposeStep, InstallDockerStep};
 use crate::domain::environment::repository::{EnvironmentRepository, TypedEnvironmentRepository};
 use crate::domain::environment::state::{ConfigureFailureContext, ConfigureStep};
@@ -137,7 +138,7 @@ impl ConfigureCommandHandler {
     fn execute_configuration_with_tracking(
         &self,
         environment: &Environment<Configuring>,
-    ) -> Result<Environment<Configured>, (ConfigureCommandHandlerError, ConfigureStep)> {
+    ) -> StepResult<Environment<Configured>, ConfigureCommandHandlerError, ConfigureStep> {
         // Track current step and execute each step
         // If an error occurs, we return it along with the current step
 

src/application/command_handlers/destroy/handler.rs

@@ -5,6 +5,7 @@ use std::sync::Arc;
 use tracing::{info, instrument};
 
 use super::errors::DestroyCommandHandlerError;
+use crate::application::command_handlers::common::StepResult;
 use crate::application::steps::DestroyInfrastructureStep;
 use crate::domain::environment::repository::{EnvironmentRepository, TypedEnvironmentRepository};
 use crate::domain::environment::{Destroyed, Environment};
@@ -201,13 +202,8 @@ impl DestroyCommandHandler {
             crate::domain::environment::Destroying,
         >,
         opentofu_client: &Arc<crate::adapters::tofu::client::OpenTofuClient>,
-    ) -> Result<
-        (),
-        (
-            DestroyCommandHandlerError,
-            crate::domain::environment::state::DestroyStep,
-        ),
-    > {
+    ) -> StepResult<(), DestroyCommandHandlerError, crate::domain::environment::state::DestroyStep>
+    {
         use crate::domain::environment::state::DestroyStep;
 
         // Step 1: Conditionally destroy infrastructure via OpenTofu

src/application/command_handlers/provision/handler.rs

@@ -9,6 +9,7 @@ use super::errors::ProvisionCommandHandlerError;
 use crate::adapters::ansible::AnsibleClient;
 use crate::adapters::ssh::{SshConfig, SshCredentials};
 use crate::adapters::tofu::client::InstanceInfo;
+use crate::application::command_handlers::common::StepResult;
 use crate::application::steps::{
     ApplyInfrastructureStep, GetInstanceInfoStep, InitializeInfrastructureStep,
     PlanInfrastructureStep, RenderAnsibleTemplatesStep, RenderOpenTofuTemplatesStep,
@@ -175,7 +176,7 @@ impl ProvisionCommandHandler {
     async fn execute_provisioning_with_tracking(
         &self,
         environment: &Environment<Provisioning>,
-    ) -> Result<(Environment<Provisioned>, IpAddr), (ProvisionCommandHandlerError, ProvisionStep)>
+    ) -> StepResult<(Environment<Provisioned>, IpAddr), ProvisionCommandHandlerError, ProvisionStep>
     {
         let ssh_credentials = environment.ssh_credentials();