refactor: replace anyhow::Result with concrete error enums

- Add ProvisionTemplateError for template rendering operations
- Add SshError for connectivity operations
- Add RemoteActionError for validation actions
- Improve error context with structured variants
- Update all method signatures to use concrete errors
- Add proper error mapping and source chaining

All tests passing (176 tests) and linters clean.

Author: josecelano

src/actions/cloud_init.rs

@@ -1,8 +1,7 @@
-use anyhow::{anyhow, Context, Result};
 use std::path::Path;
 use tracing::info;
 
-use crate::actions::RemoteAction;
+use crate::actions::{RemoteAction, RemoteActionError};
 use crate::ssh::SshClient;
 
 /// Action that checks if cloud-init has completed successfully on the server
@@ -29,30 +28,39 @@ impl RemoteAction for CloudInitValidator {
         "cloud-init-validation"
     }
 
-    async fn execute(&self, server_ip: &str) -> Result<()> {
+    async fn execute(&self, server_ip: &str) -> Result<(), RemoteActionError> {
         info!("🔍 Validating cloud-init completion...");
 
         // Check cloud-init status
         let status_output = self
             .ssh_client
             .execute(server_ip, "cloud-init status")
-            .context("Failed to check cloud-init status")?;
+            .map_err(|source| RemoteActionError::SshCommandFailed {
+                action_name: self.name().to_string(),
+                source,
+            })?;
 
         if !status_output.contains("status: done") {
-            return Err(anyhow!(
-                "Cloud-init status is not 'done': {}",
-                status_output
-            ));
+            return Err(RemoteActionError::ValidationFailed {
+                action_name: self.name().to_string(),
+                message: format!("Cloud-init status is not 'done': {status_output}"),
+            });
         }
 
         // Check for completion marker file
         let marker_exists = self
             .ssh_client
             .check_command(server_ip, "test -f /var/lib/cloud/instance/boot-finished")
-            .context("Failed to check cloud-init completion marker")?;
+            .map_err(|source| RemoteActionError::SshCommandFailed {
+                action_name: self.name().to_string(),
+                source,
+            })?;
 
         if !marker_exists {
-            return Err(anyhow!("Cloud-init completion marker file not found"));
+            return Err(RemoteActionError::ValidationFailed {
+                action_name: self.name().to_string(),
+                message: "Cloud-init completion marker file not found".to_string(),
+            });
         }
 
         info!("✅ Cloud-init validation passed");

src/actions/docker.rs

@@ -1,8 +1,7 @@
-use anyhow::{Context, Result};
 use std::path::Path;
 use tracing::{info, warn};
 
-use crate::actions::RemoteAction;
+use crate::actions::{RemoteAction, RemoteActionError};
 use crate::ssh::SshClient;
 
 /// Action that validates Docker installation and daemon status on the server
@@ -29,7 +28,7 @@ impl RemoteAction for DockerValidator {
         "docker-validation"
     }
 
-    async fn execute(&self, server_ip: &str) -> Result<()> {
+    async fn execute(&self, server_ip: &str) -> Result<(), RemoteActionError> {
         info!("🔍 Validating Docker installation...");
 
         // Check Docker version
@@ -48,7 +47,10 @@ impl RemoteAction for DockerValidator {
         let daemon_active = self
             .ssh_client
             .check_command(server_ip, "sudo systemctl is-active docker")
-            .context("Failed to check Docker daemon status")?;
+            .map_err(|source| RemoteActionError::SshCommandFailed {
+                action_name: self.name().to_string(),
+                source,
+            })?;
 
         if daemon_active {
             info!("   ✓ Docker daemon is active");

src/actions/docker_compose.rs

@@ -1,8 +1,7 @@
-use anyhow::{Context, Result};
 use std::path::Path;
 use tracing::{info, warn};
 
-use crate::actions::RemoteAction;
+use crate::actions::{RemoteAction, RemoteActionError};
 use crate::ssh::SshClient;
 
 /// Action that validates Docker Compose installation and basic functionality on the server
@@ -29,14 +28,17 @@ impl RemoteAction for DockerComposeValidator {
         "docker-compose-validation"
     }
 
-    async fn execute(&self, server_ip: &str) -> Result<()> {
+    async fn execute(&self, server_ip: &str) -> Result<(), RemoteActionError> {
         info!("🔍 Validating Docker Compose installation...");
 
         // First check if Docker is available (Docker Compose requires Docker)
         let docker_available = self
             .ssh_client
             .check_command(server_ip, "docker --version")
-            .context("Failed to check Docker availability for Compose")?;
+            .map_err(|source| RemoteActionError::SshCommandFailed {
+                action_name: self.name().to_string(),
+                source,
+            })?;
 
         if !docker_available {
             warn!("⚠️  Docker Compose validation skipped");
@@ -73,7 +75,10 @@ impl RemoteAction for DockerComposeValidator {
                 server_ip,
                 &format!("echo '{test_compose_content}' > /tmp/test-docker-compose.yml"),
             )
-            .context("Failed to create test docker-compose.yml")?;
+            .map_err(|source| RemoteActionError::SshCommandFailed {
+                action_name: self.name().to_string(),
+                source,
+            })?;
 
         if !create_test_success {
             warn!("   ⚠️  Could not create test docker-compose.yml file");
@@ -87,7 +92,10 @@ impl RemoteAction for DockerComposeValidator {
                 server_ip,
                 "cd /tmp && docker-compose -f test-docker-compose.yml config",
             )
-            .context("Failed to validate docker-compose configuration")?;
+            .map_err(|source| RemoteActionError::SshCommandFailed {
+                action_name: self.name().to_string(),
+                source,
+            })?;
 
         if validate_success {
             info!("   ✓ Docker Compose configuration validation passed");

src/actions/mod.rs

@@ -1,4 +1,32 @@
-use anyhow::Result;
+use thiserror::Error;
+
+use crate::command::CommandError;
+
+/// Errors that can occur during remote action execution
+#[derive(Error, Debug)]
+pub enum RemoteActionError {
+    /// SSH command execution failed
+    #[error("SSH command execution failed during '{action_name}': {source}")]
+    SshCommandFailed {
+        action_name: String,
+        #[source]
+        source: CommandError,
+    },
+
+    /// Action validation failed
+    #[error("Action '{action_name}' validation failed: {message}")]
+    ValidationFailed {
+        action_name: String,
+        message: String,
+    },
+    
+    /// Action execution failed with custom error
+    #[error("Action '{action_name}' execution failed: {message}")]
+    ExecutionFailed {
+        action_name: String,
+        message: String,
+    },
+}
 
 pub mod cloud_init;
 pub mod docker;
@@ -29,6 +57,6 @@ pub trait RemoteAction {
     ///
     /// # Returns
     /// * `Ok(())` if the action executes successfully
-    /// * `Err(anyhow::Error)` if the action fails or encounters an error
-    async fn execute(&self, server_ip: &str) -> Result<()>;
+    /// * `Err(RemoteActionError)` if the action fails or encounters an error
+    async fn execute(&self, server_ip: &str) -> Result<(), RemoteActionError>;
 }

src/bin/e2e_tests.rs

@@ -11,6 +11,7 @@ use torrust_tracker_deploy::ansible::AnsibleClient;
 use torrust_tracker_deploy::lxd::LxdClient;
 use torrust_tracker_deploy::opentofu::OpenTofuClient;
 use torrust_tracker_deploy::ssh::SshClient;
+use torrust_tracker_deploy::stages::ProvisionTemplateRenderer;
 // Import template system
 use torrust_tracker_deploy::template::file::File;
 use torrust_tracker_deploy::template::wrappers::ansible::inventory::{
@@ -49,6 +50,7 @@ struct TestEnvironment {
     ssh_key_path: PathBuf,
     template_manager: TemplateManager,
     opentofu_client: OpenTofuClient,
+    provision_renderer: ProvisionTemplateRenderer,
     ssh_client: SshClient,
     lxd_client: LxdClient,
     ansible_client: AnsibleClient,
@@ -105,6 +107,10 @@ impl TestEnvironment {
         // Create Ansible client pointing to build/ansible directory
         let ansible_client = AnsibleClient::new(project_root.join("build/ansible"), verbose);
 
+        // Create provision template renderer
+        let provision_renderer =
+            ProvisionTemplateRenderer::new(project_root.join("build"), verbose);
+
         if verbose {
             println!(
                 "🔑 SSH key copied to temporary location: {}",
@@ -125,6 +131,7 @@ impl TestEnvironment {
             ssh_key_path: temp_ssh_key,
             template_manager,
             opentofu_client,
+            provision_renderer,
             ssh_client,
             lxd_client,
             ansible_client,
@@ -135,42 +142,10 @@ impl TestEnvironment {
 
     /// Stage 1: Render provision templates (`OpenTofu`) to build/tofu/ directory
     async fn render_provision_templates(&self) -> Result<()> {
-        println!("🏗️  Stage 1: Rendering provision templates to build directory...");
-
-        // Create build directory structure
-        let build_tofu_dir = self.build_dir.join("tofu/lxd");
-        tokio::fs::create_dir_all(&build_tofu_dir)
-            .await
-            .context("Failed to create build/tofu/lxd directory")?;
-
-        // Copy static tofu templates (no variables for now)
-        // Get template paths, creating them from embedded resources if needed
-        let source_main_tf = self
-            .template_manager
-            .get_template_path("tofu/lxd/main.tf")?;
-        let dest_main_tf = build_tofu_dir.join("main.tf");
-        tokio::fs::copy(&source_main_tf, &dest_main_tf)
-            .await
-            .context("Failed to copy main.tf to build directory")?;
-
-        // Copy cloud-init.yml
-        let source_cloud_init = self
-            .template_manager
-            .get_template_path("tofu/lxd/cloud-init.yml")?;
-        let dest_cloud_init = build_tofu_dir.join("cloud-init.yml");
-        tokio::fs::copy(&source_cloud_init, &dest_cloud_init)
+        self.provision_renderer
+            .render(&self.template_manager)
             .await
-            .context("Failed to copy cloud-init.yml to build directory")?;
-
-        if self.verbose {
-            println!(
-                "   ✅ Provision templates copied to: {}",
-                build_tofu_dir.display()
-            );
-        }
-
-        println!("✅ Stage 1 complete: Provision templates ready");
-        Ok(())
+            .map_err(|e| anyhow::anyhow!(e))
     }
 
     /// Stage 3: Render configuration templates (`Ansible`) with runtime variables to build/ansible/
@@ -384,7 +359,10 @@ async fn run_full_deployment_test(env: &TestEnvironment) -> Result<()> {
     let instance_ip = env.provision_infrastructure()?;
 
     // Wait for SSH connectivity
-    env.ssh_client.wait_for_connectivity(&instance_ip).await?;
+    env.ssh_client
+        .wait_for_connectivity(&instance_ip)
+        .await
+        .map_err(|e| anyhow::anyhow!(e))?;
 
     // Stage 3: Render configuration templates with runtime variables
     env.render_configuration_templates(&instance_ip).await?;
@@ -395,7 +373,10 @@ async fn run_full_deployment_test(env: &TestEnvironment) -> Result<()> {
 
     // Validate cloud-init completion
     let cloud_init_validator = CloudInitValidator::new(&env.ssh_key_path, "torrust", env.verbose);
-    cloud_init_validator.execute(&instance_ip).await?;
+    cloud_init_validator
+        .execute(&instance_ip)
+        .await
+        .map_err(|e| anyhow::anyhow!(e))?;
 
     // Run the install-docker playbook
     // NOTE: We skip the update-apt-cache playbook in E2E tests to avoid CI network issues
@@ -405,7 +386,10 @@ async fn run_full_deployment_test(env: &TestEnvironment) -> Result<()> {
 
     // 7. Validate Docker installation
     let docker_validator = DockerValidator::new(&env.ssh_key_path, "torrust", env.verbose);
-    docker_validator.execute(&instance_ip).await?;
+    docker_validator
+        .execute(&instance_ip)
+        .await
+        .map_err(|e| anyhow::anyhow!(e))?;
 
     // 8. Run the install-docker-compose playbook
     println!("📋 Step 3: Installing Docker Compose...");
@@ -414,7 +398,10 @@ async fn run_full_deployment_test(env: &TestEnvironment) -> Result<()> {
     // 9. Validate Docker Compose installation
     let docker_compose_validator =
         DockerComposeValidator::new(&env.ssh_key_path, "torrust", env.verbose);
-    docker_compose_validator.execute(&instance_ip).await?;
+    docker_compose_validator
+        .execute(&instance_ip)
+        .await
+        .map_err(|e| anyhow::anyhow!(e))?;
 
     println!("🎉 Full deployment E2E test completed successfully!");
     println!("   ✅ Cloud-init setup completed");

src/lib.rs

@@ -25,4 +25,5 @@ pub mod command;
 pub mod lxd;
 pub mod opentofu;
 pub mod ssh;
+pub mod stages;
 pub mod template;