Refactor command handlers to reduce duplication and improve maintainability

[josecelano]

Overview

Refactor src/application/command_handlers to reduce code duplication, improve maintainability, enhance testability, and standardize patterns across all command handlers while preserving existing behavior.

Refactoring Plan

See detailed refactoring plan: docs/refactors/plans/command-handlers-refactoring.md

The plan identifies key code quality issues and proposes 7 improvements organized in 3 phases:

• Phase 0: Extract common helpers (failure context builder, state persistence, step result type)
• Phase 1: Standardize error handling with .help() methods and remove test exposure
• Phase 2: Improve consistency (logging patterns, method ordering)

Target Files

• src/application/command_handlers/provision/handler.rs
• src/application/command_handlers/configure/handler.rs
• src/application/command_handlers/destroy/handler.rs
• src/application/command_handlers/create/handler.rs
• src/application/command_handlers/test.rs

Implementation Plan

Phase 0: Quick Wins (High Impact, Low Effort)

• 0: Extract common failure context builder
• 1: Extract state persistence helper
• 2: Extract step execution result type

Phase 1: Structural Improvements (High Impact, Medium Effort)

• 3: Standardize error handling with help methods
• 4: Remove pub(crate) test exposure

Phase 2: Consistency & Polish (Medium Impact, Low Effort)

• 5: Consistent logging patterns
• 6: Standardize method ordering

Acceptance Criteria

Quality Checks:

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

Refactoring Criteria:

• All 7 active proposals implemented
• 150-200 lines of code reduced
• 80%+ of identified duplication eliminated
• Zero behavioral changes (verified by tests)
• All existing tests pass (including E2E)
• Test coverage maintained or improved
• All documentation updated

Success Metrics

• Lines of code reduced: Target 150-200 lines
• Duplication eliminated: Target 80%+
• Test coverage: Maintain 100% of current coverage
• Build time: No degradation
• All linters pass with no new warnings

Timeline

• Estimated Duration: 2-3 weeks
• Target Completion: Mid-November 2025

Related

• Active Refactorings: docs/refactors/active-refactorings.md
• Refactoring Plan: docs/refactors/plans/command-handlers-refactoring.md