Add Dry-run and Error Handling Utilities Migration to Bash

[ooloth]

💪 What

Dry-run and Error Handling Utilities Migration: Complete migration of dry-run functionality and error handling from zsh to bash, providing safe preview mode and robust error recovery for all installation processes.

Files Changed

• bin/lib/dry-run-utils.bash - Complete dry-run functionality (20 tests, all passing)
• bin/lib/error-handling.bash - Error handling and retry mechanisms with user-friendly suggestions
• test/setup/test-dry-run-utils-bash.bats - Comprehensive unit tests for dry-run utilities

Core Functionality Migrated

Dry-run Utilities:

• parse_dry_run_flags() - Command line argument parsing for --dry-run flag
• dry_run_log() - Action logging with "DRY RUN:" prefix without execution
• dry_run_execute() - Conditional command execution based on dry-run mode

Error Handling Utilities:

• capture_error() - Command execution with context and detailed error reporting
• retry_with_backoff() - Exponential backoff retry logic for network operations
• handle_error() - User-friendly error messages with contextual suggestions for common error codes

Error Recognition and Suggestions

• EACCES/EPERM - Permission issues → suggest sudo or file permission checks
• ENOENT - File not found → suggest verifying file/directory existence
• ECONNREFUSED/ETIMEDOUT - Network issues → suggest connectivity checks
• ENOSPC - Disk space → suggest freeing up space
• Unknown errors - Generic → suggest syntax verification

🤔 Why

Safe installation preview: Dry-run mode allows users to preview all installation actions without making any system changes, essential for understanding what the setup process will do.

Robust error recovery: Network operations and package installations often fail temporarily - retry logic with exponential backoff provides resilience against transient issues.

User-friendly experience: Clear error messages with actionable suggestions help users resolve issues independently rather than facing cryptic error codes.

👀 Usage

Dry-run Mode:

# Parse command line arguments
parse_dry_run_flags "$@"

# Execute commands conditionally
dry_run_execute "brew install git"
# In dry-run mode: outputs "DRY RUN: brew install git"
# In normal mode: actually executes "brew install git"

# Log actions without execution
dry_run_log "Installing Homebrew packages"

Error Handling:

# Execute with error context
if capture_error "curl -O https://example.com/file" "File download"; then
    echo "Download successful"
else
    echo "Download failed with context"
fi

# Retry with exponential backoff
retry_with_backoff "brew update" 3 2
# Retries up to 3 times with 2s, 4s, 8s delays

# Provide helpful error messages
handle_error "chmod +x script.sh" "EACCES" "Permission denied"

Integration Example:

#\!/usr/bin/env bash
source "bin/lib/dry-run-utils.bash"
source "bin/lib/error-handling.bash"

# Parse flags
parse_dry_run_flags "$@"

# Execute with retry and error handling
if \! retry_with_backoff "dry_run_execute 'brew install git'" 3 1; then
    handle_error "brew install git" "UNKNOWN" "Package installation failed"
    exit 1
fi

👩‍🔬 How to validate

Run dry-run utility tests:

# All 20 tests for dry-run functionality
./test/run-tests.zsh test-dry-run-utils-bash
# OR
bats test/setup/test-dry-run-utils-bash.bats

Test dry-run workflow:

# Test flag parsing
source bin/lib/dry-run-utils.bash
parse_dry_run_flags "--dry-run" "--verbose"
echo $DRY_RUN  # Should output: true

# Test command execution
dry_run_execute "echo 'This will show DRY RUN prefix'"

Test error handling:

# Test retry mechanism
source bin/lib/error-handling.bash
retry_with_backoff "exit 1" 2 1
# Should show retry attempts with backoff

# Test error suggestions
handle_error "cat nonexistent.txt" "ENOENT" "File not found"

Verify shellcheck compliance:

shellcheck bin/lib/dry-run-utils.bash
shellcheck bin/lib/error-handling.bash
# Both should show no warnings

All dry-run tests pass (20/20), zero shellcheck warnings, maintains complete feature parity with original zsh implementations while adding improved error handling.

🔗 Related links

• Bash Migration Task Documentation - Project roadmap
• PR #17: Homebrew Utilities Migration - Parallel development track
• PR #18: Core Utility Libraries Migration - Foundation utilities
• Original dry-run-utils.zsh - Reference implementation
• Original error-handling.zsh - Reference implementation