Merge #161: feat: [#156] Implement Dispatch Layer with ExecutionContext wrapper

aa531e3 feat: [#156] implement dispatch layer with ExecutionContext wrapper (Jose Celano)
04d0d5f feat: [#156] implement Dispatch Layer with ExecutionContext wrapper (Jose Celano)

Pull request description:

  ## 🎯 Overview

  This PR implements **Proposal 2: Create Dispatch Layer** from the presentation layer reorganization epic ([#154](#154)).

  The Dispatch Layer establishes clear separation between command routing, execution context, and command execution, following the four-layer presentation architecture: **Input → Dispatch → Controllers → Views**.

  ## 📋 What's Implemented

  ### Core Components

  - **ExecutionContext wrapper** around `Arc<Container>` for future-proof command signatures
  - **Central command routing** with `route_command(command, working_dir, &context)` function
  - **Complete dispatch module** with router and context submodules
  - **Bootstrap integration** - Updated `bootstrap/app.rs` to use new dispatch layer
  - **Legacy deprecation** - Marked old `presentation::execute` as deprecated with migration guide

  ### Documentation & Quality

  - **Architectural Decision Record** - [`docs/decisions/execution-context-wrapper.md`](docs/decisions/execution-context-wrapper.md) documenting design rationale
  - **Comprehensive documentation** - Module-level docs explaining architecture and benefits
  - **Fixed all doctest issues** - All 303 documentation tests compile and pass
  - **Linting fixes** - Added 'configurator' to spell-check dictionary, fixed clippy issues

  ## 🏗️ Architecture Benefits

  ### ExecutionContext Design

  The dispatch layer uses an `ExecutionContext` wrapper instead of passing `Container` directly:

  ```rust
  pub struct ExecutionContext {
      container: Arc<Container>,
      // Future extensions without breaking changes:
      // request_id: RequestId,
      // execution_metadata: ExecutionMetadata,
      // tracing_context: TracingContext,
  }
  ```

  **Benefits:**
  - **Future-proof** - Can extend execution context without breaking command signatures
  - **Clear abstraction** - Represents "everything a command needs" vs generic container
  - **Command-specific access** - Convenience methods for common services
  - **Type safety** - Compile-time guarantees for service access

  ### Routing Architecture

  ```rust
  pub fn route_command(
      command: Commands,
      working_dir: &Path,
      context: &ExecutionContext,
  ) -> Result<(), CommandError>
  ```

  **Benefits:**
  - **Centralized routing** - All command dispatch logic in one place
  - **Type safety** - Compile-time guarantees that all commands are handled
  - **Testable** - Router can be tested independently of handlers
  - **Scalable** - Easy to add new commands without modifying existing code

  ## 🔧 Module Structure

  ```text
  src/presentation/dispatch/
  ├── mod.rs       # Layer exports and comprehensive documentation
  ├── router.rs    # Central command routing logic
  └── context.rs   # ExecutionContext wrapper implementation
  ```

  ## ✅ Quality Validation

  All quality checks pass:
  - **1,200+ Unit Tests** ✅ - All pass successfully
  - **E2E Tests** ✅ - Provision and configuration tests validated
  - **Documentation Tests** ✅ - All 303 doctests compile and pass
  - **Linting** ✅ - cargo machete, clippy, rustfmt, shellcheck, cspell all pass
  - **Pre-commit Validation** ✅ - Complete pre-commit suite passes

  ## 📖 Related Documentation

  - **ADR**: [`docs/decisions/execution-context-wrapper.md`](docs/decisions/execution-context-wrapper.md) - Design rationale for ExecutionContext wrapper
  - **Epic Issue**: [#154](#154) - Presentation layer reorganization roadmap
  - **Module Documentation** - Comprehensive docs in `src/presentation/dispatch/mod.rs`

  ## 🚀 Next Steps

  After this PR is merged:
  1. **Update epic progress** - Mark Proposal 2 as completed in [#156](#156)
  2. **Begin Proposal 3** - Start implementing Controllers layer
  3. **Integration** - New dispatch layer is ready for remaining presentation components

  ## 🔍 Migration Guide

  For code using the old `presentation::execute` function:

  ```rust
  // Old (deprecated)
  use torrust_tracker_deployer_lib::presentation::execute;
  execute(command, working_dir, user_output).await?;

  // New (recommended)
  use torrust_tracker_deployer_lib::presentation::dispatch::{route_command, ExecutionContext};
  let context = ExecutionContext::new(Arc::new(container));
  route_command(command, working_dir, &context)?;
  ```

  ---

  **Closes:** #156
  **Part of Epic:** #154

ACKs for top commit:
  josecelano:
    ACK aa531e3

Tree-SHA512: c7a2815acef975d06a620943223a68e34f0463d81621cea96dc3c5a072d43fe6b08da33d5d540cc62cd24ec3f78431260bc85691af6c8dba9bec82081b49270a

Author: josecelano

docs/decisions/README.md

@@ -6,6 +6,7 @@ This directory contains architectural decision records for the Torrust Tracker D
 
 | Status      | Date       | Decision                                                                                            | Summary                                                                                   |
 | ----------- | ---------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| ✅ Accepted | 2025-11-07 | [ExecutionContext Wrapper Pattern](./execution-context-wrapper.md)                                  | Use ExecutionContext wrapper around Container for future-proof command signatures         |
 | ✅ Accepted | 2025-11-03 | [Environment Variable Prefix](./environment-variable-prefix.md)                                     | Use `TORRUST_TD_` prefix for all environment variables                                    |
 | ✅ Accepted | 2025-10-15 | [External Tool Adapters Organization](./external-tool-adapters-organization.md)                     | Consolidate external tool wrappers in `src/adapters/` for better discoverability          |
 | ✅ Accepted | 2025-10-10 | [Repository Rename to Deployer](./repository-rename-to-deployer.md)                                 | Rename from "Torrust Tracker Deploy" to "Torrust Tracker Deployer" for production use     |

docs/decisions/execution-context-wrapper.md

@@ -0,0 +1,231 @@
+# Decision: ExecutionContext Wrapper Pattern
+
+## Status
+
+Accepted
+
+## Date
+
+2025-11-07
+
+## Context
+
+During the implementation of the Dispatch Layer (Proposal 2 from the presentation layer reorganization epic #154), we needed to decide how command handlers should access application services. We had two main options:
+
+1. **Direct Container Access**: Pass the `Container` directly to command handlers
+2. **ExecutionContext Wrapper**: Create an `ExecutionContext` wrapper around the `Container`
+
+### Current Architecture
+
+The Dispatch Layer routes commands to handlers and needs to provide access to application services (user output, repositories, external tool clients, etc.). These services are managed by the dependency injection `Container`.
+
+### Design Options Considered
+
+#### Option 1: Direct Container Access
+
+```rust
+pub fn route_command(
+    command: Commands,
+    working_dir: &Path,
+    container: &Container,
+) -> Result<(), CommandError>
+
+// In handlers:
+fn handle_create_command(container: &Container) {
+    let user_output = container.user_output();
+    // ...
+}
+```
+
+#### Option 2: ExecutionContext Wrapper
+
+```rust
+pub struct ExecutionContext {
+    container: Arc<Container>,
+}
+
+pub fn route_command(
+    command: Commands,
+    working_dir: &Path,
+    context: &ExecutionContext,
+) -> Result<(), CommandError>
+
+// In handlers:
+fn handle_create_command(context: &ExecutionContext) {
+    let user_output = context.user_output();
+    // ...
+}
+```
+
+## Decision
+
+We chose **Option 2: ExecutionContext Wrapper** for the following reasons:
+
+### 1. Future-Proof Command Signatures
+
+By introducing `ExecutionContext`, we can add execution-related data in the future without breaking existing command handler signatures:
+
+```rust
+pub struct ExecutionContext {
+    container: Arc<Container>,
+    // Future additions without breaking changes:
+    // request_id: RequestId,
+    // execution_metadata: ExecutionMetadata,
+    // tracing_context: TracingContext,
+    // user_permissions: UserPermissions,
+    // execution_timeout: Duration,
+}
+```
+
+If we used `Container` directly, adding any execution context would require changing every command handler signature.
+
+### 2. Clear Abstraction and Intent
+
+`ExecutionContext` provides a logical abstraction for "everything a command needs to execute" rather than exposing the dependency injection container directly:
+
+- **Container**: Implementation detail for dependency injection
+- **ExecutionContext**: Execution abstraction for command handlers
+
+This makes the intent clearer and separates concerns properly.
+
+### 3. Type Safety and Interface Clarity
+
+```rust
+// Less clear: What is this container for? Bootstrapping? Testing? Execution?
+fn handle_command(container: &Container)
+
+// Clear: This is specifically for command execution
+fn handle_command(context: &ExecutionContext)
+```
+
+### 4. Command-Specific Service Aggregation
+
+ExecutionContext can provide command-specific convenience methods and service aggregations:
+
+```rust
+impl ExecutionContext {
+    // Direct service access
+    pub fn user_output(&self) -> &Arc<Mutex<UserOutput>> {
+        self.container.user_output()
+    }
+
+    // Future: Command-specific aggregated services
+    pub fn deployment_services(&self) -> DeploymentServices {
+        DeploymentServices {
+            provisioner: self.container.provisioner(),
+            configurator: self.container.configurator(),
+            validator: self.container.validator(),
+        }
+    }
+}
+```
+
+### 5. Enhanced Testability
+
+Different execution contexts can be created for different scenarios:
+
+```rust
+// Production context
+let context = ExecutionContext::new(container);
+
+// Test context with mocks
+let context = TestExecutionContext::new(mock_container);
+
+// Both can implement the same interface
+trait ExecutionContextTrait {
+    fn user_output(&self) -> &Arc<Mutex<UserOutput>>;
+}
+```
+
+### 6. Industry Pattern Alignment
+
+Most frameworks use execution context patterns:
+
+- **Spring Framework**: `ApplicationContext`
+- **ASP.NET Core**: `HttpContext`
+- **Express.js**: Request/Response context
+- **Go**: `context.Context`
+
+This aligns with established patterns for managing execution state.
+
+## Consequences
+
+### Positive
+
+- **Future-Proof**: Can extend execution context without breaking command signatures
+- **Clear Intent**: ExecutionContext clearly indicates its purpose for command execution
+- **Better Abstraction**: Separates execution concerns from dependency injection mechanics
+- **Enhanced Testability**: Enables different contexts for different testing scenarios
+- **Industry Alignment**: Follows established patterns from major frameworks
+
+### Negative
+
+- **Initial Overhead**: Currently just a thin wrapper around Container
+- **Additional Indirection**: One extra layer between commands and services
+- **Learning Curve**: New developers need to understand the wrapper pattern
+
+### Migration Path
+
+If needed, migration from Container to ExecutionContext (or vice versa) is straightforward:
+
+```rust
+// From Container to ExecutionContext
+fn handle_command(container: &Container) -> fn handle_command(context: &ExecutionContext)
+
+// From ExecutionContext to Container
+fn handle_command(context: &ExecutionContext) -> fn handle_command(container: &Container)
+```
+
+## Implementation Details
+
+### Current Implementation
+
+```rust
+pub struct ExecutionContext {
+    container: Arc<Container>,
+}
+
+impl ExecutionContext {
+    pub fn new(container: Arc<Container>) -> Self {
+        Self { container }
+    }
+
+    pub fn container(&self) -> &Container {
+        &self.container
+    }
+
+    pub fn user_output(&self) -> &Arc<Mutex<UserOutput>> {
+        self.container.user_output()
+    }
+}
+```
+
+### Usage Pattern
+
+```rust
+// In bootstrap/app.rs
+let container = Arc::new(Container::new());
+let context = ExecutionContext::new(container);
+
+// In dispatch layer
+route_command(command, working_dir, &context)?;
+
+// In command handlers
+fn handle_create_command(context: &ExecutionContext) {
+    let user_output = context.user_output();
+    // Command implementation
+}
+```
+
+## Related Decisions
+
+- [Presentation Layer Reorganization](../decisions/README.md) - Overall context for the four-layer architecture
+- [Command State Return Pattern](./command-state-return-pattern.md) - How commands return typed states
+
+## References
+
+- [Epic #154: Presentation Layer Reorganization](https://github.com/torrust/torrust-tracker-deployer/issues/154)
+- [Issue #156: Create Dispatch Layer](https://github.com/torrust/torrust-tracker-deployer/issues/156)
+- [Spring Framework ApplicationContext](https://docs.spring.io/spring-framework/docs/current/reference/html/core.html#beans-introduction)
+- [ASP.NET Core HttpContext](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/http-context)
+- [Go Context Package](https://pkg.go.dev/context)

project-words.txt

@@ -23,6 +23,7 @@ cloudinit
 Cockburn
 concepsts
 connrefused
+configurator
 containerd
 cpus
 creds

src/bootstrap/app.rs

@@ -17,6 +17,8 @@
 //! - **Single Responsibility**: Focus only on application bootstrap concerns
 //! - **Clean Separation**: No CLI parsing or business logic in this module
 
+use std::sync::Arc;
+
 use clap::Parser;
 use tracing::info;
 
@@ -56,14 +58,15 @@ pub fn run() {
     );
 
     // Initialize service container for dependency injection
-    let container = bootstrap::Container::new();
+    let container = Arc::new(bootstrap::Container::new());
+    let context = presentation::dispatch::ExecutionContext::new(container);
 
     match cli.command {
         Some(command) => {
             if let Err(e) =
-                presentation::execute(command, &cli.global.working_dir, &container.user_output())
+                presentation::dispatch::route_command(command, &cli.global.working_dir, &context)
             {
-                presentation::handle_error(&e, &container.user_output());
+                presentation::handle_error(&e, &context.user_output());
                 std::process::exit(1);
             }
         }

src/presentation/commands/mod.rs

@@ -28,6 +28,34 @@ pub mod tests;
 
 /// Execute the given command
 ///
+/// **DEPRECATED**: This function is deprecated in favor of the new Dispatch Layer.
+/// Use `crate::presentation::dispatch::route_command` instead.
+///
+/// This function will be removed in a future version. The new dispatch layer
+/// provides better separation of concerns and cleaner architecture.
+///
+/// # Migration Guide
+///
+/// Old code:
+/// ```rust,ignore
+/// use std::sync::{Arc, Mutex};
+/// use crate::presentation::{commands, user_output::UserOutput};
+///
+/// let user_output = Arc::new(Mutex::new(UserOutput::new(/* ... */)));
+/// commands::execute(command, working_dir, &user_output)?;
+/// ```
+///
+/// New code:
+/// ```rust,ignore
+/// use std::sync::Arc;
+/// use crate::bootstrap::Container;
+/// use crate::presentation::dispatch::{route_command, ExecutionContext};
+///
+/// let container = Arc::new(Container::new());
+/// let context = ExecutionContext::new(container);
+/// route_command(command, working_dir, &context)?;
+/// ```
+///
 /// This function serves as the central dispatcher for all CLI commands.
 /// It matches the command type and delegates execution to the appropriate
 /// command handler module.
@@ -65,6 +93,27 @@ pub mod tests;
 ///     }
 /// }
 /// ```
+#[deprecated(
+    since = "0.1.0",
+    note = "Use `crate::presentation::dispatch::route_command` instead"
+)]
+///
+/// ```rust
+/// use clap::Parser;
+/// use torrust_tracker_deployer_lib::presentation::{input::cli, commands, user_output};
+/// use std::{path::Path, sync::{Arc, Mutex}};
+///
+/// let cli = cli::Cli::parse();
+/// if let Some(command) = cli.command {
+///     let working_dir = Path::new(".");
+///     let user_output = Arc::new(Mutex::new(user_output::UserOutput::new(user_output::VerbosityLevel::Normal)));
+///     let result = commands::execute(command, working_dir, &user_output);
+///     match result {
+///         Ok(_) => println!("Command executed successfully"),
+///         Err(e) => commands::handle_error(&e, &user_output),
+///     }
+/// }
+/// ```
 pub fn execute(
     command: Commands,
     working_dir: &std::path::Path,