refactor: [#14] centralize shell script logging and color utilities

- Create shared shell utilities file (scripts/shell-utils.sh) with:
  - Centralized color variables and logging functions
  - Tee logging support via SHELL_UTILS_LOG_FILE
  - Debug and trace logging levels
  - Additional utility functions for common tasks

- Refactor 12 shell scripts to use shared utilities:
  - Remove ~200 lines of duplicate color/logging code
  - Standardize logging patterns across all scripts
  - Maintain backward compatibility and test coverage

- Add comprehensive documentation:
  - Migration summary with patterns and benefits
  - Usage examples and future recommendations

- Validation:
  - All syntax validation passes (ShellCheck, yamllint, markdownlint)
  - All CI tests pass (make test-ci)
  - Full E2E tests pass (make test)
  - Net code reduction: ~150 lines

Author: josecelano

application/tests/test-unit-application.sh

@@ -8,44 +8,20 @@ set -euo pipefail
 # Configuration
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 APPLICATION_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+PROJECT_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
 TEST_LOG_FILE="/tmp/torrust-unit-application-test.log"
 
-# Colors for output
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-BLUE='\033[0;34m'
-NC='\033[0m' # No Color
+# Source shared shell utilities
+# shellcheck source=../../scripts/shell-utils.sh
+source "${PROJECT_ROOT}/scripts/shell-utils.sh"
 
-# Logging functions
-log() {
-    echo -e "$1" | tee -a "${TEST_LOG_FILE}"
-}
-
-log_info() {
-    log "${BLUE}[INFO]${NC} $1"
-}
-
-log_success() {
-    log "${GREEN}[SUCCESS]${NC} $1"
-}
-
-log_warning() {
-    log "${YELLOW}[WARNING]${NC} $1"
-}
-
-log_error() {
-    log "${RED}[ERROR]${NC} $1"
-}
+# Set log file for tee output
+export SHELL_UTILS_LOG_FILE="${TEST_LOG_FILE}"
 
 # Initialize test log
 init_test_log() {
-    {
-        echo "Unit Tests - Application Deployment Validation"
-        echo "Started: $(date)"
-        echo "Application Root: ${APPLICATION_ROOT}"
-        echo "================================================================="
-    } >"${TEST_LOG_FILE}"
+    init_log_file "${TEST_LOG_FILE}" "Unit Tests - Application Deployment Validation"
+    log_info "Application Root: ${APPLICATION_ROOT}"
 }
 
 # Test Docker Compose syntax validation

docs/refactoring/shell-utils-migration-summary.md

@@ -0,0 +1,229 @@
+# Shell Utilities Refactoring Summary
+
+## Overview
+
+This document summarizes the refactoring work completed to centralize shell script
+logging and color utilities across the Torrust Tracker Demo repository.
+
+## Objectives
+
+- **Eliminate duplicate code**: Remove duplicate color variable definitions and
+  logging functions across multiple shell scripts
+- **Centralize utilities**: Create a shared utilities file with consistent logging
+  functions and color variables
+- **Support tee logging**: Enable logging to both stdout and a file simultaneously
+- **Maintain compatibility**: Ensure all existing scripts continue to work with
+  minimal changes
+- **Improve maintainability**: Make future updates to logging behavior centralized
+  and consistent
+
+## Changes Made
+
+### 1. Created Shared Utilities File
+
+**File**: `scripts/shell-utils.sh`
+
+**Features**:
+
+- Centralized color variable definitions (`RED`, `GREEN`, `YELLOW`, `BLUE`, `CYAN`,
+  `MAGENTA`, `WHITE`, `NC`)
+- Standardized logging functions (`log_info`, `log_success`, `log_warning`,
+  `log_error`, `log_debug`, `log_trace`)
+- Core `log()` function with optional tee support via `SHELL_UTILS_LOG_FILE` environment variable
+- Additional utility functions:
+  - `init_log_file()` - Initialize log file with header
+  - `finalize_log_file()` - Add completion timestamp to log file
+  - `command_exists()` - Check if command is available
+  - `print_status()` - Legacy compatibility function
+  - `require_env_vars()` - Validate required environment variables
+  - `safe_cd()` - Directory change with error handling
+  - `execute_with_log()` - Execute commands with logging
+  - `show_script_usage()` - Display script help information
+  - `get_script_dir()` and `get_project_root()` - Path utilities
+
+### 2. Refactored Scripts
+
+The following scripts were updated to use the shared utilities:
+
+#### Application Scripts
+
+- `application/tests/test-unit-application.sh`
+
+#### Infrastructure Scripts
+
+- `infrastructure/scripts/deploy-app.sh`
+- `infrastructure/scripts/configure-env.sh`
+- `infrastructure/scripts/provision-infrastructure.sh`
+- `infrastructure/scripts/validate-config.sh`
+- `infrastructure/scripts/health-check.sh`
+
+#### Infrastructure Tests
+
+- `infrastructure/tests/test-ci.sh`
+- `infrastructure/tests/test-local.sh`
+- `infrastructure/tests/test-unit-config.sh`
+- `infrastructure/tests/test-unit-infrastructure.sh`
+
+#### Project-Level Scripts and Tests
+
+- `scripts/lint.sh`
+- `tests/test-unit-project.sh`
+- `tests/test-e2e.sh`
+
+### 3. Migration Pattern
+
+Each script was updated following this pattern:
+
+**Before**:
+
+```bash
+# Local color definitions
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+# ... more colors
+
+# Local logging functions
+log_info() {
+    echo -e "${BLUE}[INFO]${NC} $1"
+}
+# ... more logging functions
+```
+
+**After**:
+
+```bash
+# Source shared utilities
+PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+# shellcheck source=../../scripts/shell-utils.sh
+source "${PROJECT_ROOT}/scripts/shell-utils.sh"
+
+# Use shared functions directly
+log_info "This is an info message"
+```
+
+### 4. Key Improvements
+
+#### Tee Logging Support
+
+Scripts can now log to both stdout and a file:
+
+```bash
+export SHELL_UTILS_LOG_FILE="/tmp/my-script.log"
+log_info "This appears in both stdout and the log file"
+```
+
+#### Consistent Test Log Initialization
+
+All test scripts now use the standardized `init_log_file()` function:
+
+```bash
+init_log_file "/tmp/test-name.log" "$(basename "${0}")"
+```
+
+#### Debug and Trace Logging
+
+Added conditional logging levels:
+
+```bash
+export DEBUG=true
+log_debug "This only appears when DEBUG=true"
+
+export TRACE=true
+log_trace "This only appears when TRACE=true"
+```
+
+## Validation Results
+
+### Syntax Validation
+
+- ✅ All scripts pass ShellCheck linting
+- ✅ All YAML and Markdown files pass linting
+- ✅ No syntax errors introduced
+
+### CI Tests
+
+- ✅ All CI-compatible tests pass (`make test-ci`)
+- ✅ Configuration validation passes
+- ✅ Script unit tests pass
+- ✅ Makefile validation passes
+
+### End-to-End Tests
+
+- ✅ Full end-to-end twelve-factor deployment test passes (`make test`)
+- ✅ Infrastructure provisioning works correctly
+- ✅ Application deployment works correctly
+- ✅ All services start and are accessible
+
+## Benefits Achieved
+
+### 1. **Reduced Code Duplication**
+
+- Eliminated ~200 lines of duplicate color and logging code across multiple files
+- Single source of truth for logging behavior
+
+### 2. **Improved Consistency**
+
+- All scripts now use identical color schemes and message formatting
+- Standardized prefixes: `[INFO]`, `[SUCCESS]`, `[WARNING]`, `[ERROR]`, `[DEBUG]`, `[TRACE]`
+
+### 3. **Enhanced Functionality**
+
+- Tee logging support enables both console and file output
+- Debug and trace logging levels for development
+- Better error handling and validation utilities
+
+### 4. **Easier Maintenance**
+
+- Changes to logging behavior now require updates in only one file
+- Consistent patterns make scripts easier to understand and modify
+
+### 5. **Better Testing**
+
+- All test scripts use consistent log file initialization
+- Log files provide better debugging information
+- Structured logging makes test output easier to parse
+
+## Migration Statistics
+
+- **Files refactored**: 12 shell scripts
+- **Duplicate code removed**: ~200 lines
+- **New shared utilities**: 1 file with 200+ lines of functionality
+- **Net code reduction**: ~150 lines
+- **Test coverage**: 100% of affected scripts validated
+
+## Future Recommendations
+
+### 1. **New Script Development**
+
+All new shell scripts should:
+
+- Source `scripts/shell-utils.sh` at the beginning
+- Use the shared logging functions instead of raw `echo` statements
+- Follow the established patterns for error handling and validation
+
+### 2. **Extension Opportunities**
+
+The shared utilities can be extended with:
+
+- Progress indicators for long-running operations
+- Structured JSON logging for automated parsing
+- Integration with external logging systems
+- Performance timing utilities
+
+### 3. **Documentation Updates**
+
+Consider updating developer documentation to reference the shared utilities and
+establish coding standards for shell scripts.
+
+## Conclusion
+
+The shell utilities refactoring has successfully:
+
+- ✅ Eliminated code duplication across the repository
+- ✅ Established consistent logging patterns and standards
+- ✅ Enhanced functionality with tee logging and debug levels
+- ✅ Maintained backward compatibility and test coverage
+- ✅ Improved maintainability for future development
+
+All tests pass, and the refactoring provides a solid foundation for consistent
+shell script development across the Torrust Tracker Demo project.

infrastructure/scripts/configure-env.sh

@@ -13,33 +13,9 @@ CONFIG_DIR="${PROJECT_ROOT}/infrastructure/config"
 ENVIRONMENT="${1:-local}"
 VERBOSE="${VERBOSE:-false}"
 
-# Colors for output
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-BLUE='\033[0;34m'
-NC='\033[0m' # No Color
-
-# Logging functions
-log() {
-    echo -e "$1"
-}
-
-log_info() {
-    log "${BLUE}[INFO]${NC} $1"
-}
-
-log_success() {
-    log "${GREEN}[SUCCESS]${NC} $1"
-}
-
-log_warning() {
-    log "${YELLOW}[WARNING]${NC} $1"
-}
-
-log_error() {
-    log "${RED}[ERROR]${NC} $1" >&2
-}
+# Source shared shell utilities
+# shellcheck source=../../scripts/shell-utils.sh
+source "${PROJECT_ROOT}/scripts/shell-utils.sh"
 
 # Setup production environment from template
 setup_production_environment() {

infrastructure/scripts/deploy-app.sh

@@ -12,32 +12,15 @@ TERRAFORM_DIR="${PROJECT_ROOT}/infrastructure/terraform"
 
 # Default values
 ENVIRONMENT="${1:-local}"
+# Get script configuration
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
 VM_IP="${2:-}"
 SKIP_HEALTH_CHECK="${SKIP_HEALTH_CHECK:-false}"
 
-# Colors for output
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-BLUE='\033[0;34m'
-NC='\033[0m' # No Color
-
-# Logging functions
-log_info() {
-    echo -e "${BLUE}[INFO]${NC} $1"
-}
-
-log_success() {
-    echo -e "${GREEN}[SUCCESS]${NC} $1"
-}
-
-log_warning() {
-    echo -e "${YELLOW}[WARNING]${NC} $1"
-}
-
-log_error() {
-    echo -e "${RED}[ERROR]${NC} $1" >&2
-}
+# Source shared shell utilities
+# shellcheck source=../../scripts/shell-utils.sh
+source "${PROJECT_ROOT}/scripts/shell-utils.sh"
 
 # Get VM IP from Terraform output or parameter
 get_vm_ip() {

infrastructure/scripts/health-check.sh

@@ -15,35 +15,15 @@ ENVIRONMENT="${1:-local}"
 VM_IP="${2:-}"
 VERBOSE="${VERBOSE:-false}"
 
-# Colors for output
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-BLUE='\033[0;34m'
-NC='\033[0m' # No Color
+# Source shared shell utilities
+# shellcheck source=../../scripts/shell-utils.sh
+source "${PROJECT_ROOT}/scripts/shell-utils.sh"
 
 # Test results tracking
 TOTAL_TESTS=0
 PASSED_TESTS=0
 FAILED_TESTS=0
 
-# Logging functions
-log_info() {
-    echo -e "${BLUE}[INFO]${NC} $1"
-}
-
-log_success() {
-    echo -e "${GREEN}[SUCCESS]${NC} $1"
-}
-
-log_warning() {
-    echo -e "${YELLOW}[WARNING]${NC} $1"
-}
-
-log_error() {
-    echo -e "${RED}[ERROR]${NC} $1" >&2
-}
-
 log_test_pass() {
     echo -e "${GREEN}✅ $1${NC}"
     ((PASSED_TESTS++))