feat: add verbosity levels to release command

docs/issues/367-add-verbosity-levels-to-release-command.md

@@ -12,20 +12,20 @@
 - [Generic Command Progress Listener for Verbosity](./drafts/generic-command-progress-listener-for-verbosity.md) — architectural design for the `CommandProgressListener` trait
 - [Progress Reporting in Application Layer](../features/progress-reporting-in-application-layer/README.md)
 
-**Status**: 🔜 **NOT STARTED** — Ready for implementation
+**Status**: ✅ **COMPLETED** — Implementation finished
 
-**Branch**: TBD
+**Branch**: `367-add-verbosity-levels-to-release-command`
 **PR**: TBD
 
 ## Current Implementation Status
 
-**Pending Implementation**:
+**Implemented**:
 
-- [ ] **Normal (default)**: Show 2 main workflow phases (validate + release)
-- [ ] **Verbose (`-v`)**: Show all 7 service-specific release steps
-- [ ] **VeryVerbose (`-vv`)**: Show detail messages (files deployed, templates rendered, paths)
-- [ ] **Debug (`-vvv`)**: Show debug messages (Ansible commands, working directories, full outputs)
-- [ ] **Documentation**: User guide update with verbosity examples and patterns
+- [x] **Normal (default)**: Show 2 main workflow phases (validate + release)
+- [x] **Verbose (`-v`)**: Show all 7 service-specific release steps
+- [x] **VeryVerbose (`-vv`)**: Show detail messages (files deployed, templates rendered, paths)
+- [x] **Debug (`-vvv`)**: Show debug messages (Ansible commands, working directories, full outputs)
+- [x] **Documentation**: User guide updated with verbosity examples and patterns
 
 ## Overview
 
@@ -35,13 +35,13 @@ Add graduated verbosity levels (`-v`, `-vv`, `-vvv`) to the `release` command to
 
 ## Goals
 
-- [ ] Reuse `CommandProgressListener` infrastructure from provision/configure commands
-- [ ] Apply same four verbosity levels to release command
-- [ ] Show service-specific release steps, template rendering, file deployments at different detail levels
-- [ ] Maintain backward compatibility (default = Normal level)
-- [ ] Keep user output completely separate from tracing logs
-- [ ] Update user documentation with verbosity examples
-- [ ] Help text examples already present (global flags)
+- [x] Reuse `CommandProgressListener` infrastructure from provision/configure commands
+- [x] Apply same four verbosity levels to release command
+- [x] Show service-specific release steps, template rendering, file deployments at different detail levels
+- [x] Maintain backward compatibility (default = Normal level)
+- [x] Keep user output completely separate from tracing logs
+- [x] Update user documentation with verbosity examples
+- [x] Help text examples already present (global flags)
 
 ## 🏗️ Architecture Requirements
 
@@ -73,29 +73,29 @@ The following components **already exist** from previous verbosity implementatio
 
 **What's needed for release command**:
 
-- [ ] Pass `CommandProgressListener` to release command handler
-- [ ] Add `on_step_started()` calls for all 7 service-specific release steps
-- [ ] Add `on_detail()` calls for template rendering, file deployments, and service operations
-- [ ] Add `on_debug()` calls for Ansible commands, working directories, full outputs
-- [ ] Update user guide documentation
-- [ ] Verify help text shows verbosity options (already present from global flags)
+- [x] Pass `CommandProgressListener` to release command handler
+- [x] Add `on_step_started()` calls for all 7 service-specific release steps
+- [x] Add `on_detail()` calls for template rendering, file deployments, and service operations
+- [x] Add `on_debug()` calls for Ansible commands, working directories, full outputs
+- [x] Update user guide documentation
+- [x] Verify help text shows verbosity options (already present from global flags)
 
 ### Module Structure Requirements
 
-- [ ] Follow same pattern as provision/configure commands (reference implementations)
-- [ ] Handler emits step-level progress events
-- [ ] Workflow coordinates service steps and emits progress for each service
-- [ ] Service steps emit detail and debug events
-- [ ] Infrastructure layer (Ansible, template rendering) remains unaware of listener
+- [x] Follow same pattern as provision/configure commands (reference implementations)
+- [x] Handler emits step-level progress events
+- [x] Workflow coordinates service steps and emits progress for each service
+- [x] Service steps emit detail and debug events
+- [x] Infrastructure layer (Ansible, template rendering) remains unaware of listener
 
 ### Architectural Constraints
 
-- [ ] Verbosity flags control **only UserOutput** (user-facing messages)
-- [ ] **Do not** mix verbosity with tracing logs (logs use `RUST_LOG`)
-- [ ] Follow separation documented in [user-output-vs-logging-separation.md](../research/UX/user-output-vs-logging-separation.md)
-- [ ] Maintain channel separation (stdout for results, stderr for progress)
-- [ ] Backward compatible (default = Normal level, existing output unchanged)
-- [ ] Reuse `CommandProgressListener` trait (do not create command-specific variants)
+- [x] Verbosity flags control **only UserOutput** (user-facing messages)
+- [x] **Do not** mix verbosity with tracing logs (logs use `RUST_LOG`)
+- [x] Follow separation documented in [user-output-vs-logging-separation.md](../research/UX/user-output-vs-logging-separation.md)
+- [x] Maintain channel separation (stdout for results, stderr for progress)
+- [x] Backward compatible (default = Normal level, existing output unchanged)
+- [x] Reuse `CommandProgressListener` trait (do not create command-specific variants)
 
 ### Anti-Patterns to Avoid
 
@@ -266,12 +266,12 @@ torrust-tracker-deployer release my-env -vvv
 
 **Tasks**:
 
-- [ ] Task 1.1: Update `ReleaseCommandHandler::execute()` to accept optional `&dyn CommandProgressListener`
-- [ ] Task 1.2: Add `TOTAL_RELEASE_STEPS` constant (7 services)
-- [ ] Task 1.3: Add `on_step_started()` calls before each service release in `workflow::execute()`
-- [ ] Task 1.4: Pass listener from controller to handler
-- [ ] Task 1.5: Update E2E tests to pass `None` for listener (backward compatibility)
-- [ ] Task 1.6: Test Normal and Verbose levels work correctly
+- [x] Task 1.1: Update `ReleaseCommandHandler::execute()` to accept optional `&dyn CommandProgressListener`
+- [x] Task 1.2: Add `TOTAL_RELEASE_STEPS` constant (7 services)
+- [x] Task 1.3: Add `on_step_started()` calls before each service release in `workflow::execute()`
+- [x] Task 1.4: Pass listener from controller to handler
+- [x] Task 1.5: Update E2E tests to pass `None` for listener (backward compatibility)
+- [x] Task 1.6: Test Normal and Verbose levels work correctly
 
 **Rationale**: Matches the pattern established in provision and configure commands. Handler orchestrates high-level workflow, emitting progress for each major service step.
 
@@ -294,20 +294,20 @@ torrust-tracker-deployer release my-env -vvv
 
 **Tasks**:
 
-- [ ] Task 2.1: Update all 7 service release functions to accept optional `&dyn CommandProgressListener`
-- [ ] Task 2.2: Add `on_detail()` calls for:
+- [x] Task 2.1: Update all 7 service release functions to accept optional `&dyn CommandProgressListener`
+- [x] Task 2.2: Add `on_detail()` calls for:
   - Storage directory creation
   - Database initialization
   - Template rendering operations
   - File deployment paths
   - Service-specific operations
-- [ ] Task 2.3: Add `on_debug()` calls for:
+- [x] Task 2.3: Add `on_debug()` calls for:
   - Ansible command execution
   - Working directories
   - Template source/output paths
   - Playbook names
-- [ ] Task 2.4: Pass listener from workflow to all service steps
-- [ ] Task 2.5: Test VeryVerbose and Debug levels work correctly
+- [x] Task 2.4: Pass listener from workflow to all service steps
+- [x] Task 2.5: Test VeryVerbose and Debug levels work correctly
 
 **Rationale**: Service steps are the natural place to report detailed progress. They know what files are being rendered, where they're deployed, and what Ansible commands execute. Following the same pattern as configure command.
 
@@ -324,12 +324,12 @@ torrust-tracker-deployer release my-env -vvv
 
 **Tasks**:
 
-- [ ] Task 3.1: Add "Verbosity Levels" section to release.md
-- [ ] Task 3.2: Include examples for all 4 verbosity levels (Normal, Verbose, VeryVerbose, Debug)
-- [ ] Task 3.3: Document use cases for each level
-- [ ] Task 3.4: Add examples showing combined usage with other flags
-- [ ] Task 3.5: Verify help text includes verbosity examples (already present from global flags)
-- [ ] Task 3.6: Update this issue spec with implementation status
+- [x] Task 3.1: Add "Verbosity Levels" section to release.md
+- [x] Task 3.2: Include examples for all 4 verbosity levels (Normal, Verbose, VeryVerbose, Debug)
+- [x] Task 3.3: Document use cases for each level
+- [x] Task 3.4: Add examples showing combined usage with other flags
+- [x] Task 3.5: Verify help text includes verbosity examples (already present from global flags)
+- [x] Task 3.6: Update this issue spec with implementation status
 
 **Rationale**: Same validation as provision/configure commands. Ensure clean, readable output and comprehensive documentation.
 
@@ -343,38 +343,38 @@ torrust-tracker-deployer release my-env -vvv
 
 **Quality Checks**:
 
-- [ ] Pre-commit checks pass: `./scripts/pre-commit.sh`
-- [ ] No unused dependencies: `cargo machete`
-- [ ] All existing tests pass
-- [ ] No clippy warnings
+- [x] Pre-commit checks pass: `./scripts/pre-commit.sh`
+- [x] No unused dependencies: `cargo machete`
+- [x] All existing tests pass
+- [x] No clippy warnings
 
 **Task-Specific Criteria**:
 
-- [ ] Release command accepts `-v`, `-vv`, `-vvv` flags (global flags, already works)
-- [ ] Default behavior (no flags) remains unchanged from current output
-- [ ] Verbose level (`-v`) shows all 7 service-specific release steps
-- [ ] VeryVerbose level (`-vv`) shows template rendering, file deployments, storage operations
-- [ ] Debug level (`-vvv`) shows Ansible commands, working directories, full paths
-- [ ] User output stays completely separate from tracing logs
-- [ ] `RUST_LOG` continues to control logging independently
-- [ ] Help text clearly explains verbosity levels (verified in global flags)
-- [ ] Output remains clean and readable at all verbosity levels
-- [ ] Channel separation maintained (stdout for results, stderr for progress)
-- [ ] Pattern matches provision/configure command implementations (consistency)
+- [x] Release command accepts `-v`, `-vv`, `-vvv` flags (global flags, already works)
+- [x] Default behavior (no flags) remains unchanged from current output
+- [x] Verbose level (`-v`) shows all 7 service-specific release steps
+- [x] VeryVerbose level (`-vv`) shows template rendering, file deployments, storage operations
+- [x] Debug level (`-vvv`) shows Ansible commands, working directories, full paths
+- [x] User output stays completely separate from tracing logs
+- [x] `RUST_LOG` continues to control logging independently
+- [x] Help text clearly explains verbosity levels (verified in global flags)
+- [x] Output remains clean and readable at all verbosity levels
+- [x] Channel separation maintained (stdout for results, stderr for progress)
+- [x] Pattern matches provision/configure command implementations (consistency)
 
 **Documentation Criteria**:
 
-- [ ] User guide (`docs/user-guide/commands/release.md`) updated with verbosity section
-- [ ] Examples provided for all 4 verbosity levels
-- [ ] Symbol legend explained (⏳ ✅ 📋 🔍)
-- [ ] Use cases documented for each verbosity level
-- [ ] Combined flag usage examples provided
+- [x] User guide (`docs/user-guide/commands/release.md`) updated with verbosity section
+- [x] Examples provided for all 4 verbosity levels
+- [x] Symbol legend explained (⏳ ✅ 📋 🔍)
+- [x] Use cases documented for each verbosity level
+- [x] Combined flag usage examples provided
 
 **Out of Scope**:
 
-- [ ] Quiet mode (`-q`) - defer to future work
-- [ ] Silent mode - defer to future work
-- [ ] Per-step timing breakdown - not needed, total duration is sufficient
+- [x] Quiet mode (`-q`) - defer to future work
+- [x] Silent mode - defer to future work
+- [x] Per-step timing breakdown - not needed, total duration is sufficient
 
 ## Related Documentation
 

docs/user-guide/commands/release.md

@@ -130,6 +130,168 @@ torrust-tracker-deployer release my-environment
 torrust-tracker-deployer run my-environment
 ```
 
+## Verbosity Levels
+
+The release command supports multiple verbosity levels to control the amount of progress detail displayed:
+
+### Default (Normal) - Essential Progress Only
+
+Shows only the essential progress and results:
+
+```bash
+torrust-tracker-deployer release my-environment
+```
+
+**Output**:
+
+```text
+⏳ [1/2] Validating environment...
+⏳   ✓ Environment name validated: my-environment (took 0ms)
+⏳ [2/2] Releasing application...
+⏳   ✓ Application released successfully (took 45.8s)
+✅ Release command completed successfully for 'my-environment'
+```
+
+### Verbose (`-v`) - Show Service Release Steps
+
+Shows all 7 service-specific release steps:
+
+```bash
+torrust-tracker-deployer release my-environment -v
+```
+
+**Output**:
+
+```text
+⏳ [1/2] Validating environment...
+⏳   ✓ Environment name validated: my-environment (took 0ms)
+⏳ [2/2] Releasing application...
+📋   [Step 1/7] Releasing Tracker service...
+📋   [Step 2/7] Releasing Prometheus service...
+📋   [Step 3/7] Releasing Grafana service...
+📋   [Step 4/7] Releasing MySQL service...
+📋   [Step 5/7] Releasing Backup service...
+📋   [Step 6/7] Releasing Caddy service...
+📋   [Step 7/7] Deploying Docker Compose configuration...
+⏳   ✓ Application released successfully (took 43.2s)
+✅ Release command completed successfully for 'my-environment'
+```
+
+**Use Case**: When you want visibility into which service is being deployed.
+
+### Very Verbose (`-vv`) - Show Detailed Operations
+
+Shows template rendering, file paths, and deployment details:
+
+```bash
+torrust-tracker-deployer release my-environment -vv
+```
+
+**Output** (excerpt):
+
+```text
+⏳ [1/2] Validating environment...
+⏳   ✓ Environment name validated: my-environment (took 0ms)
+⏳ [2/2] Releasing application...
+📋   [Step 1/7] Releasing Tracker service...
+📋      → Creating storage directories: /opt/torrust/storage/tracker/{lib,log,etc}
+📋      → Initializing database: tracker.db
+📋      → Rendering tracker.toml from template
+📋      → Deploying config to /opt/torrust/storage/tracker/etc/tracker.toml
+📋   [Step 2/7] Releasing Prometheus service...
+📋      → Creating storage directories: /opt/torrust/storage/prometheus/etc
+📋      → Rendering prometheus.yml from template
+📋      → Deploying config to /opt/torrust/storage/prometheus/etc/prometheus.yml
+📋   [Step 3/7] Releasing Grafana service...
+📋      → Creating storage directories: /opt/torrust/storage/grafana/{data,provisioning}
+📋      → Rendering Grafana provisioning files (datasources, dashboards)
+📋      → Deploying provisioning to /opt/torrust/storage/grafana/provisioning
+📋   [Step 7/7] Deploying Docker Compose configuration...
+📋      → Rendering docker-compose.yml and .env from templates
+📋      → Deploying docker-compose.yml and .env to /opt/torrust
+⏳   ✓ Application released successfully (took 43.5s)
+✅ Release command completed successfully for 'my-environment'
+```
+
+**Use Case**: Troubleshooting release issues or verifying what files are being deployed where.
+
+### Debug (`-vvv`) - Show Technical Details
+
+Shows Ansible commands, working directories, and full execution details:
+
+```bash
+torrust-tracker-deployer release my-environment -vvv
+```
+
+**Output** (excerpt):
+
+```text
+⏳ [1/2] Validating environment...
+⏳   ✓ Environment name validated: my-environment (took 0ms)
+⏳ [2/2] Releasing application...
+📋   [Step 1/7] Releasing Tracker service...
+🔍      → Ansible working directory: ./build/my-environment/ansible
+🔍      → Executing playbook: ansible-playbook create-tracker-storage.yml
+📋      → Creating storage directories: /opt/torrust/storage/tracker/{lib,log,etc}
+🔍      → Executing playbook: ansible-playbook init-tracker-database.yml
+📋      → Initializing database: tracker.db
+🔍      → Template source: ./data/my-environment/templates/tracker/
+📋      → Rendering tracker.toml from template
+🔍      → Template output: ./build/my-environment/tracker
+🔍      → Executing playbook: ansible-playbook deploy-tracker-config.yml
+📋      → Deploying config to /opt/torrust/storage/tracker/etc/tracker.toml
+📋   [Step 7/7] Deploying Docker Compose configuration...
+🔍      → Template source: ./data/my-environment/templates/docker-compose/
+📋      → Rendering docker-compose.yml and .env from templates
+🔍      → Template output: ./build/my-environment/docker-compose
+🔍      → Ansible working directory: ./build/my-environment/ansible
+🔍      → Executing playbook: ansible-playbook deploy-compose-files.yml
+📋      → Deploying docker-compose.yml and .env to /opt/torrust
+⏳   ✓ Application released successfully (took 43.8s)
+✅ Release command completed successfully for 'my-environment'
+```
+
+**Use Case**: Deep troubleshooting, debugging, or when you need to understand exactly what commands are being executed.
+
+### Symbol Legend
+
+| Symbol | Meaning                          | Verbosity Level |
+| ------ | -------------------------------- | --------------- |
+| ⏳     | Operation in progress            | Normal+         |
+| ✅     | Operation completed successfully | Normal+         |
+| 📋     | Detailed contextual information  | VeryVerbose     |
+| 🔍     | Technical implementation detail  | Debug           |
+
+### Combining with Other Options
+
+Verbosity flags can be combined with other command options:
+
+```bash
+# Very verbose release with trace logging
+RUST_LOG=trace torrust-tracker-deployer release my-environment -vv
+```
+
+**Note**: Verbosity flags (`-v`, `-vv`, `-vvv`) control user-facing progress output, while `RUST_LOG` controls internal application logging for debugging purposes.
+
+```bash
+# 1. Create environment
+torrust-tracker-deployer create template --provider lxd > my-env.json
+# Edit my-env.json with your settings
+torrust-tracker-deployer create environment --env-file my-env.json
+
+# 2. Provision infrastructure
+torrust-tracker-deployer provision my-environment
+
+# 3. Configure system
+torrust-tracker-deployer configure my-environment
+
+# 4. Release application
+torrust-tracker-deployer release my-environment
+
+# 5. Start services (next step)
+torrust-tracker-deployer run my-environment
+```
+
 ## What Gets Configured
 
 ### Tracker Configuration (`tracker.toml`)