Merge #305: refactor: improve release handler code organization and reduce duplication

45588ce chore: remove release handler analysis document (Jose Celano)
629bed5 refactor: move service availability checks to release() functions (Jose Celano)
fabe399 refactor: remove instance_ip parameter from release workflow (Jose Celano)
da242e3 refactor: improve workflow module readability (Jose Celano)
806ea87 refactor: extract release workflow to dedicated module (Jose Celano)
c031138 refactor: extract release steps into service-specific modules (Jose Celano)
d5f95e1 refactor: normalize error types to include source for error chaining (Jose Celano)
f87fa2c refactor: convert unused self methods to associated functions (Jose Celano)
a7b2a17 refactor: remove unused instance_ip parameters from step methods (Jose Celano)
36dd723 refactor: extract AnsibleClient construction helper (Jose Celano)
8330d50 refactor: group release workflow steps by service (Jose Celano)
c724492 docs: add code quality analysis for release handler (Jose Celano)

Pull request description:

  ## Summary

  This PR refactors the release command handler to improve code organization, reduce duplication, and enhance maintainability.

  ## Changes

  ### Module Reorganization
  - **Extract service-specific steps into dedicated modules** under `steps/`:
    - `tracker.rs` - Tracker service release steps
    - `prometheus.rs` - Prometheus service release steps
    - `grafana.rs` - Grafana service release steps
    - `mysql.rs` - MySQL service release steps
    - `caddy.rs` - Caddy service release steps
    - `compose.rs` - Docker Compose deployment steps
    - `common.rs` - Shared utilities (ansible client factory)

  ### Workflow Extraction
  - **Extract release workflow to dedicated module** (`workflow.rs`) - Separates orchestration logic from handler state management

  ### Code Quality Improvements
  - **Remove `instance_ip` parameter from workflow** - The IP is now obtained from the environment object within each step, reducing coupling
  - **Move service availability checks to `release()` functions** - Eliminates repetitive conditional checks in every step function (~90 lines removed)
  - **Improve workflow module readability** - Use explicit imports and remove redundant comments

  ## Benefits

  1. **Better separation of concerns**: Each service has its own module with clear responsibilities
  2. **Reduced duplication**: Service availability checks now happen once per service, not per step
  3. **Improved testability**: Smaller, focused modules are easier to test in isolation
  4. **Enhanced maintainability**: Changes to one service don't affect others
  5. **Clearer control flow**: The main `release()` function in each module shows the complete service workflow

  ## Testing

  - All pre-commit checks pass
  - E2E tests pass (both infrastructure lifecycle and deployment workflow tests)
  - Documentation builds successfully

ACKs for top commit:
  josecelano:
    ACK 45588ce

Tree-SHA512: 3b2e29f5b5068a5d70d50060638e750ff2934c82161c40c51520cdf6648851bfbb6aac18ad97158f02c562dec565ddd8f40fddf26b8ed731d677f36f59cea4a7

Author: josecelano

src/application/command_handlers/release/errors.rs

@@ -19,6 +19,13 @@
 //! - **Explicit State Transitions**: Type-safe state machine for environment lifecycle
 //! - **Explicit Errors**: All errors implement `.help()` with actionable guidance
 //!
+//! ## Module Organization
+//!
+//! - `handler.rs` - Core handler with `execute()`, state transitions, workflow orchestration
+//! - `workflow.rs` - Release workflow orchestration (step coordination)
+//! - `errors.rs` - Error types for release operations
+//! - `steps/` - Service-specific step implementations (tracker, prometheus, etc.)
+//!
 //! ## Release Workflow
 //!
 //! The command handler orchestrates a multi-step workflow:
@@ -40,6 +47,8 @@
 
 pub mod errors;
 pub mod handler;
+mod steps;
+mod workflow;
 
 #[cfg(test)]
 mod tests;

src/application/command_handlers/release/handler.rs

@@ -0,0 +1,120 @@
+//! Caddy service release steps
+//!
+//! This module contains all steps required to release the Caddy service:
+//! - Configuration template rendering
+//! - Configuration deployment to remote
+//!
+//! All steps are optional and only execute if HTTPS is configured.
+
+use std::sync::Arc;
+
+use tracing::info;
+
+use super::common::ansible_client;
+use crate::application::command_handlers::common::StepResult;
+use crate::application::command_handlers::release::errors::ReleaseCommandHandlerError;
+use crate::application::steps::application::DeployCaddyConfigStep;
+use crate::application::steps::rendering::RenderCaddyTemplatesStep;
+use crate::domain::environment::state::ReleaseStep;
+use crate::domain::environment::{Environment, Releasing};
+use crate::domain::template::TemplateManager;
+
+/// Release the Caddy service (if HTTPS enabled)
+///
+/// Executes all steps required to release Caddy:
+/// 1. Render configuration templates
+/// 2. Deploy configuration to remote
+///
+/// If HTTPS is not configured, all steps are skipped.
+///
+/// # Errors
+///
+/// Returns a tuple of (error, step) if any Caddy step fails
+#[allow(clippy::result_large_err)]
+pub fn release(
+    environment: &Environment<Releasing>,
+) -> StepResult<(), ReleaseCommandHandlerError, ReleaseStep> {
+    // Check if HTTPS is configured
+    if environment.context().user_inputs.https().is_none() {
+        info!(
+            command = "release",
+            service = "caddy",
+            status = "skipped",
+            "HTTPS not configured - skipping all Caddy steps"
+        );
+        return Ok(());
+    }
+
+    render_templates(environment)?;
+    deploy_config_to_remote(environment)?;
+    Ok(())
+}
+
+/// Render Caddy configuration templates
+///
+/// # Errors
+///
+/// Returns a tuple of (error, `ReleaseStep::RenderCaddyTemplates`) if rendering fails
+#[allow(clippy::result_large_err)]
+fn render_templates(
+    environment: &Environment<Releasing>,
+) -> StepResult<(), ReleaseCommandHandlerError, ReleaseStep> {
+    let current_step = ReleaseStep::RenderCaddyTemplates;
+
+    let template_manager = Arc::new(TemplateManager::new(environment.templates_dir()));
+    let step = RenderCaddyTemplatesStep::new(
+        Arc::new(environment.clone()),
+        template_manager,
+        environment.build_dir().clone(),
+    );
+
+    step.execute().map_err(|e| {
+        (
+            ReleaseCommandHandlerError::TemplateRendering {
+                message: e.to_string(),
+                source: Box::new(e),
+            },
+            current_step,
+        )
+    })?;
+
+    info!(
+        command = "release",
+        step = %current_step,
+        "Caddy configuration templates rendered successfully"
+    );
+
+    Ok(())
+}
+
+/// Deploy Caddy configuration to the remote host
+///
+/// # Errors
+///
+/// Returns a tuple of (error, `ReleaseStep::DeployCaddyConfigToRemote`) if deployment fails
+#[allow(clippy::result_large_err)]
+fn deploy_config_to_remote(
+    environment: &Environment<Releasing>,
+) -> StepResult<(), ReleaseCommandHandlerError, ReleaseStep> {
+    let current_step = ReleaseStep::DeployCaddyConfigToRemote;
+
+    DeployCaddyConfigStep::new(ansible_client(environment))
+        .execute()
+        .map_err(|e| {
+            (
+                ReleaseCommandHandlerError::CaddyConfigDeployment {
+                    message: e.to_string(),
+                    source: Box::new(e),
+                },
+                current_step,
+            )
+        })?;
+
+    info!(
+        command = "release",
+        step = %current_step,
+        "Caddy configuration deployed to remote successfully"
+    );
+
+    Ok(())
+}

src/application/command_handlers/release/mod.rs

@@ -0,0 +1,14 @@
+//! Common utilities shared across release steps
+
+use std::sync::Arc;
+
+use crate::adapters::ansible::AnsibleClient;
+use crate::domain::environment::{Environment, Releasing};
+
+/// Create an Ansible client configured for the environment's build directory
+///
+/// This is a helper function to reduce duplication across step implementations.
+#[must_use]
+pub fn ansible_client(environment: &Environment<Releasing>) -> Arc<AnsibleClient> {
+    Arc::new(AnsibleClient::new(environment.build_dir().join("ansible")))
+}

src/application/command_handlers/release/steps/caddy.rs

@@ -0,0 +1,111 @@
+//! Docker Compose release steps
+//!
+//! This module contains all steps required to deploy Docker Compose:
+//! - Template rendering
+//! - Compose files deployment to remote
+
+use std::path::{Path, PathBuf};
+use std::sync::Arc;
+
+use tracing::info;
+
+use crate::adapters::ansible::AnsibleClient;
+use crate::application::command_handlers::common::StepResult;
+use crate::application::command_handlers::release::errors::ReleaseCommandHandlerError;
+use crate::application::steps::{DeployComposeFilesStep, RenderDockerComposeTemplatesStep};
+use crate::domain::environment::state::ReleaseStep;
+use crate::domain::environment::{Environment, Releasing};
+use crate::domain::template::TemplateManager;
+
+/// Release Docker Compose configuration
+///
+/// Executes all steps required to deploy Docker Compose:
+/// 1. Render Docker Compose templates
+/// 2. Deploy compose files to remote
+///
+/// # Errors
+///
+/// Returns a tuple of (error, step) if any Docker Compose step fails
+pub async fn release(
+    environment: &Environment<Releasing>,
+) -> StepResult<(), ReleaseCommandHandlerError, ReleaseStep> {
+    let compose_build_dir = render_templates(environment).await?;
+    deploy_files_to_remote(environment, &compose_build_dir)?;
+    Ok(())
+}
+
+/// Render Docker Compose templates to the build directory
+///
+/// # Errors
+///
+/// Returns a tuple of (error, `ReleaseStep::RenderDockerComposeTemplates`) if rendering fails
+async fn render_templates(
+    environment: &Environment<Releasing>,
+) -> StepResult<PathBuf, ReleaseCommandHandlerError, ReleaseStep> {
+    let current_step = ReleaseStep::RenderDockerComposeTemplates;
+
+    let template_manager = Arc::new(TemplateManager::new(environment.templates_dir()));
+    let step = RenderDockerComposeTemplatesStep::new(
+        Arc::new(environment.clone()),
+        template_manager,
+        environment.build_dir().clone(),
+    );
+
+    let compose_build_dir = step.execute().await.map_err(|e| {
+        (
+            ReleaseCommandHandlerError::TemplateRendering {
+                message: e.to_string(),
+                source: Box::new(e),
+            },
+            current_step,
+        )
+    })?;
+
+    info!(
+        command = "release",
+        compose_build_dir = %compose_build_dir.display(),
+        "Docker Compose templates rendered successfully"
+    );
+
+    Ok(compose_build_dir)
+}
+
+/// Deploy compose files to the remote host via Ansible
+///
+/// # Arguments
+///
+/// * `environment` - The environment in Releasing state
+/// * `compose_build_dir` - Path to the rendered compose files
+///
+/// # Errors
+///
+/// Returns a tuple of (error, `ReleaseStep::DeployComposeFilesToRemote`) if deployment fails
+#[allow(clippy::result_large_err)]
+fn deploy_files_to_remote(
+    environment: &Environment<Releasing>,
+    compose_build_dir: &Path,
+) -> StepResult<(), ReleaseCommandHandlerError, ReleaseStep> {
+    let current_step = ReleaseStep::DeployComposeFilesToRemote;
+
+    let ansible_client = Arc::new(AnsibleClient::new(environment.ansible_build_dir()));
+    let step = DeployComposeFilesStep::new(ansible_client, compose_build_dir.to_path_buf());
+
+    step.execute().map_err(|e| {
+        (
+            ReleaseCommandHandlerError::ComposeFilesDeployment {
+                message: e.to_string(),
+                source: Box::new(e),
+            },
+            current_step,
+        )
+    })?;
+
+    info!(
+        command = "release",
+        compose_build_dir = %compose_build_dir.display(),
+        instance_ip = ?environment.instance_ip(),
+        "Compose files deployed to remote host successfully"
+    );
+
+    Ok(())
+}