Add Symlink Utilities Extraction with Comprehensive Bash Testing

[ooloth]

💪 What

Symlink Utilities Extraction: Complete extraction and migration of symlink management functionality from the monolithic bin/update/symlinks.zsh into reusable bash utilities with comprehensive testing and improved error handling.

Files Changed

• lib/symlink-utils.bash - Shared symlink utility functions (19 tests, all passing)
• bin/install/symlinks.bash - Complete symlink installation script using shared utilities
• test/setup/test-symlink-utils-bash.bats - Comprehensive unit tests for all symlink functions

Core Functionality Extracted

Symlink Management:

• maybe_symlink() - Safe symlink creation with target validation and directory creation
• remove_broken_symlinks() - Cleanup utility for invalid/broken symlinks
• is_symlink_correct() - Verification function for symlink target correctness
• get_relative_path() - Cross-platform relative path calculation
• maybe_symlink_relative() - Relative symlink creation for portable configurations

Installation Workflow:

• create_dotfiles_symlinks() - Complete workflow for all dotfiles symlinks
• create_config_symlinks() - Automated config directory symlinking with fd/find fallback
• create_vscode_symlinks() - VS Code configuration management
• create_yazi_symlinks() - Yazi theme and flavor setup
• verify_symlinks() - Post-installation validation and verification

Enhanced Features

• Smart directory creation - Automatically creates target directories as needed
• Broken symlink cleanup - Removes invalid symlinks before creating new ones
• Cross-platform compatibility - Python fallback for relative path calculation
• Multiple operation modes - create, verify, clean operations
• Graceful error handling - Continues operation when optional components missing

🤔 Why

Code reusability: The original bin/update/symlinks.zsh contained useful utility functions that were only available in that specific script. Extracting them allows other installation scripts to use the same reliable symlink management.

Better testing: The original script was difficult to test due to its monolithic structure. The extracted utilities have comprehensive unit tests covering all edge cases and error conditions.

Improved maintenance: Separated concerns make the code easier to understand, modify, and debug. The installation script focuses on workflow while utilities handle the mechanics.

Consistency with migration project: Follows the established pattern of bash utilities with comprehensive testing and zero shellcheck warnings.

👀 Usage

Basic symlink creation:

source "$DOTFILES_ROOT/lib/symlink-utils.bash"

# Create single symlink
maybe_symlink "/path/to/source.txt" "/target/directory"

# Create relative symlink
maybe_symlink_relative "/path/to/source.txt" "/target/directory"

# Verify symlink is correct
if is_symlink_correct "/target/file.txt" "/expected/source.txt"; then
    echo "Symlink is correct"
fi

Batch operations:

# Clean up broken symlinks
remove_broken_symlinks "$HOME/.config"

# Create all dotfiles symlinks
./bin/install/symlinks.bash create

# Verify critical symlinks
./bin/install/symlinks.bash verify

# Clean broken symlinks only
./bin/install/symlinks.bash clean

Integration in other scripts:

#\!/usr/bin/env bash
source "$DOTFILES_ROOT/lib/symlink-utils.bash"

# Safe symlink creation with validation
for config_file in config/*; do
    maybe_symlink "$config_file" "$HOME/.config"
done

# Cleanup before new symlinks
remove_broken_symlinks "$HOME/.config"

👩‍🔬 How to validate

Run all symlink utility tests:

# All 19 tests for symlink utilities
./test/run-tests.zsh test-symlink-utils-bash
# OR
bats test/setup/test-symlink-utils-bash.bats

Test symlink creation workflow:

# Create test symlinks
./bin/install/symlinks.bash create

# Verify they were created correctly
./bin/install/symlinks.bash verify

# Clean up broken symlinks
./bin/install/symlinks.bash clean

Test individual utilities:

# Test symlink creation
source lib/symlink-utils.bash
maybe_symlink "$PWD/README.md" "/tmp/test"
ls -la /tmp/test/README.md

# Test broken symlink removal
ln -s /nonexistent /tmp/broken
remove_broken_symlinks /tmp
# Should remove the broken symlink

Verify shellcheck compliance:

shellcheck lib/symlink-utils.bash
shellcheck bin/install/symlinks.bash
# Both should show no warnings (only info about sourcing)

All 19 tests pass, zero shellcheck warnings, maintains complete feature parity with original implementation while adding comprehensive error handling and validation.

🔗 Related links

• Bash Migration Task Documentation - Project roadmap
• PR #17: Homebrew Utilities Migration - Parallel development track
• PR #18: Core Utility Libraries Migration - Foundation utilities
• PR #19: Dry-run and Error Handling Migration - Error handling utilities
• Original symlinks.zsh - Reference implementation to be replaced