refactor: [#162] decouple template and environment error types with unified CreateCommandError

- Create dedicated CreateEnvironmentTemplateCommandError for template commands
- Implement unified CreateCommandError wrapper with transparent error delegation
- Update template handler to use template-specific error type with proper boxing
- Modify router to map errors correctly via CreateCommandError variants
- Update all tests to handle unified error pattern matching
- Preserve help() method delegation and error chain integrity
- Fix clippy issues: add backticks around UserOutput, use std::io::Error::other

This completes the error architecture decoupling requested, giving each command
its own error type while maintaining a unified interface for the create command.

Author: josecelano

src/presentation/controllers/create/errors.rs

@@ -0,0 +1,40 @@
+//! Unified Create Command Errors
+//!
+//! This module defines a unified error type that encompasses all create subcommand errors,
+//! providing a single interface for environment and template command errors.
+
+use thiserror::Error;
+
+use super::subcommands::{
+    environment::CreateEnvironmentCommandError, template::CreateEnvironmentTemplateCommandError,
+};
+
+/// Unified error type for all create subcommands
+///
+/// This error type provides a unified interface for errors that can occur during
+/// any create subcommand execution (environment creation or template generation).
+/// It wraps the specific command errors while preserving their context and help methods.
+#[derive(Debug, Error)]
+pub enum CreateCommandError {
+    /// Environment creation errors
+    #[error(transparent)]
+    Environment(#[from] CreateEnvironmentCommandError),
+
+    /// Template generation errors
+    #[error(transparent)]
+    Template(#[from] CreateEnvironmentTemplateCommandError),
+}
+
+impl CreateCommandError {
+    /// Get detailed troubleshooting guidance for this error
+    ///
+    /// This method delegates to the specific command error's help method,
+    /// providing context-appropriate troubleshooting guidance.
+    #[must_use]
+    pub fn help(&self) -> &'static str {
+        match self {
+            Self::Environment(err) => err.help(),
+            Self::Template(err) => err.help(),
+        }
+    }
+}

src/presentation/controllers/create/mod.rs

@@ -16,6 +16,7 @@
 //! - `router` - Main command router routing between subcommands
 //! - `subcommands` - Individual subcommand implementations (environment, template)
 //!   - `environment` - Contains environment creation logic, error types, and config loading
+//! - `errors` - Unified error types for all create subcommands
 //!
 //! ## Usage Example
 //!
@@ -38,12 +39,15 @@
 //! }
 //! ```
 
+pub mod errors;
 pub mod router;
 pub mod subcommands;
 
 #[cfg(test)]
 mod tests;
 
 // Re-export commonly used types for convenience
+pub use errors::CreateCommandError;
 pub use router::route_command;
 pub use subcommands::environment::{ConfigFormat, ConfigLoader, CreateEnvironmentCommandError};
+pub use subcommands::template::CreateEnvironmentTemplateCommandError;

src/presentation/controllers/create/router.rs

@@ -8,8 +8,7 @@ use std::path::Path;
 use crate::presentation::dispatch::ExecutionContext;
 use crate::presentation::input::cli::commands::CreateAction;
 
-use super::subcommands;
-use super::subcommands::environment::CreateEnvironmentCommandError;
+use super::{errors::CreateCommandError, subcommands};
 
 /// Route the create command to its appropriate subcommand
 ///
@@ -23,7 +22,7 @@ use super::subcommands::environment::CreateEnvironmentCommandError;
 ///
 /// # Returns
 ///
-/// Returns `Ok(())` on success, or a `CreateEnvironmentCommandError` on failure.
+/// Returns `Ok(())` on success, or a `CreateCommandError` on failure.
 ///
 /// # Errors
 ///
@@ -33,14 +32,16 @@ pub fn route_command(
     action: CreateAction,
     working_dir: &Path,
     context: &ExecutionContext,
-) -> Result<(), CreateEnvironmentCommandError> {
+) -> Result<(), CreateCommandError> {
     match action {
         CreateAction::Environment { env_file } => {
             subcommands::handle_environment_creation(&env_file, working_dir, context)
+                .map_err(CreateCommandError::Environment)
         }
         CreateAction::Template { output_path } => {
             let template_path = output_path.unwrap_or_else(CreateAction::default_template_path);
             subcommands::handle_template_generation(&template_path, context)
+                .map_err(CreateCommandError::Template)
         }
     }
 }

src/presentation/controllers/create/subcommands/template/errors.rs

@@ -1 +1,188 @@
+//! Template Command Errors
+//!
+//! This module defines error types specific to template generation commands.
+//! These errors provide detailed context and actionable guidance for template-related failures.
 
+use std::path::PathBuf;
+use thiserror::Error;
+
+/// Errors that can occur during template generation commands
+///
+/// This error type covers all failure scenarios that can occur during template
+/// generation operations, including file I/O errors, validation failures, and
+/// system-level issues.
+///
+/// All variants include structured context to aid in debugging and provide
+/// actionable guidance to users through the `.help()` method.
+#[derive(Debug, Error)]
+pub enum CreateEnvironmentTemplateCommandError {
+    /// Failed to acquire lock on `UserOutput` for displaying progress/results
+    ///
+    /// This error occurs when the `UserOutput` mutex is poisoned, typically indicating
+    /// that another thread panicked while holding the output lock. This is a system-level
+    /// error that should be rare in normal operation.
+    #[error(
+        "Failed to acquire output lock for displaying template generation progress
+Tip: This indicates a system error - try restarting the command"
+    )]
+    UserOutputLockFailed,
+
+    /// Template file generation failed
+    ///
+    /// This error occurs when the underlying template generation operation fails,
+    /// which could be due to file system permissions, disk space, or template
+    /// processing errors.
+    #[error(
+        "Failed to generate configuration template at '{path}': {source}
+Tip: Check directory permissions and available disk space"
+    )]
+    TemplateGenerationFailed {
+        /// Path where template generation was attempted
+        path: PathBuf,
+        /// The underlying error that caused template generation to fail
+        #[source]
+        source: Box<dyn std::error::Error + Send + Sync>,
+    },
+}
+
+impl CreateEnvironmentTemplateCommandError {
+    /// Get detailed troubleshooting guidance for this error
+    ///
+    /// This method provides comprehensive troubleshooting steps that can be
+    /// displayed to users when they need more help resolving the error.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use torrust_tracker_deployer_lib::presentation::controllers::create::subcommands::template::CreateEnvironmentTemplateCommandError;
+    ///
+    /// fn handle_error(error: CreateEnvironmentTemplateCommandError) {
+    ///     eprintln!("Error: {error}");
+    ///     eprintln!("\nTroubleshooting:\n{}", error.help());
+    /// }
+    /// ```
+    #[must_use]
+    pub fn help(&self) -> &'static str {
+        match self {
+            Self::UserOutputLockFailed => {
+                "User Output Lock Failed - Detailed Troubleshooting:
+
+1. This is a rare system-level error that occurs when another thread panics
+   while displaying output to the user.
+
+2. Try the following steps:
+   - Restart the command
+   - If the error persists, restart your terminal
+   - Check for any background processes that might interfere
+
+3. If the problem continues:
+   - Check system resources (memory, disk space)
+   - Consider running with --verbose for more detailed error information
+   - Report the issue if it's reproducible
+
+For more information, see the troubleshooting guide."
+            }
+
+            Self::TemplateGenerationFailed { .. } => {
+                "Template Generation Failed - Detailed Troubleshooting:
+
+1. Check directory permissions:
+   - Ensure write permissions for the target directory
+   - Verify parent directory exists
+   - Check ownership of the target path
+
+2. Verify available resources:
+   - Check available disk space: df -h (Unix) or dir (Windows)
+   - Ensure sufficient memory is available
+
+3. File system issues:
+   - Check if the path contains invalid characters
+   - Verify the path length is within system limits
+   - Ensure no other process is using the target file
+
+4. Template processing issues:
+   - Check if required template data is available
+   - Verify template format is valid
+   - Look for any corrupted template files
+
+If the problem persists, run with --verbose for detailed logs and report
+the issue with system details."
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::error::Error;
+    use std::path::PathBuf;
+
+    #[test]
+    fn it_should_display_user_output_lock_failed_error() {
+        let error = CreateEnvironmentTemplateCommandError::UserOutputLockFailed;
+        let message = error.to_string();
+
+        assert!(message.contains("Failed to acquire output lock"));
+        assert!(message.contains("Tip: This indicates a system error"));
+    }
+
+    #[test]
+    fn it_should_display_template_generation_failed_error() {
+        let path = PathBuf::from("/test/template.json");
+        let source: Box<dyn std::error::Error + Send + Sync> = Box::new(std::io::Error::new(
+            std::io::ErrorKind::PermissionDenied,
+            "Access denied",
+        ));
+
+        let error = CreateEnvironmentTemplateCommandError::TemplateGenerationFailed {
+            path: path.clone(),
+            source,
+        };
+        let message = error.to_string();
+
+        assert!(message.contains("Failed to generate configuration template"));
+        assert!(message.contains("/test/template.json"));
+        assert!(message.contains("Tip: Check directory permissions"));
+    }
+
+    #[test]
+    fn it_should_have_help_for_all_variants() {
+        let errors = vec![
+            CreateEnvironmentTemplateCommandError::UserOutputLockFailed,
+            CreateEnvironmentTemplateCommandError::TemplateGenerationFailed {
+                path: PathBuf::from("/test"),
+                source: Box::new(std::io::Error::other("test")),
+            },
+        ];
+
+        for error in errors {
+            let help = error.help();
+            assert!(!help.is_empty(), "Help text should not be empty");
+            assert!(
+                help.contains("Troubleshooting") || help.len() > 50,
+                "Help should contain actionable guidance"
+            );
+        }
+    }
+
+    #[test]
+    fn it_should_preserve_error_chain() {
+        let source_error = std::io::Error::new(std::io::ErrorKind::NotFound, "File not found");
+        let error = CreateEnvironmentTemplateCommandError::TemplateGenerationFailed {
+            path: PathBuf::from("/test"),
+            source: Box::new(source_error),
+        };
+
+        // Check that source error is preserved
+        assert!(error.source().is_some(), "Source error should be preserved");
+
+        // Check error chain
+        let chain = std::error::Error::source(&error);
+        assert!(chain.is_some(), "Error chain should exist");
+
+        if let Some(source) = chain {
+            assert!(source.to_string().contains("File not found"));
+        }
+    }
+}

src/presentation/controllers/create/subcommands/template/handler.rs

@@ -6,9 +6,10 @@
 use std::path::Path;
 
 use crate::application::command_handlers::create::config::EnvironmentCreationConfig;
-use crate::presentation::controllers::create::subcommands::environment::CreateEnvironmentCommandError;
 use crate::presentation::dispatch::ExecutionContext;
 
+use super::errors::CreateEnvironmentTemplateCommandError;
+
 /// Handle template generation
 ///
 /// This function generates a configuration template file with placeholder values
@@ -21,7 +22,7 @@ use crate::presentation::dispatch::ExecutionContext;
 ///
 /// # Returns
 ///
-/// Returns `Ok(())` on success, or a `CreateEnvironmentCommandError` on failure.
+/// Returns `Ok(())` on success, or a `CreateEnvironmentTemplateCommandError` on failure.
 ///
 /// # Errors
 ///
@@ -35,12 +36,12 @@ use crate::presentation::dispatch::ExecutionContext;
 pub fn handle_template_generation(
     output_path: &Path,
     context: &ExecutionContext,
-) -> Result<(), CreateEnvironmentCommandError> {
+) -> Result<(), CreateEnvironmentTemplateCommandError> {
     // Lock user output for progress messages
     let user_output = context.user_output();
     let mut output = user_output
         .lock()
-        .map_err(|_| CreateEnvironmentCommandError::UserOutputLockFailed)?;
+        .map_err(|_| CreateEnvironmentTemplateCommandError::UserOutputLockFailed)?;
 
     output.progress("Generating configuration template...");
 
@@ -52,7 +53,10 @@ pub fn handle_template_generation(
             EnvironmentCreationConfig::generate_template_file(output_path)
                 .await
                 .map_err(
-                    |source| CreateEnvironmentCommandError::TemplateGenerationFailed { source },
+                    |source| CreateEnvironmentTemplateCommandError::TemplateGenerationFailed {
+                        path: output_path.to_path_buf(),
+                        source: Box::new(source),
+                    },
                 )
         })?;
 

src/presentation/controllers/create/subcommands/template/mod.rs

@@ -8,3 +8,6 @@ pub mod handler;
 
 // Re-export the main handler function
 pub use handler::handle_template_generation;
+
+// Re-export error types
+pub use errors::CreateEnvironmentTemplateCommandError;