feat: implement migration tool for legacy configuration (Issue #34)

[chutch3]

🎯 Implements Issue #34: Migration Tool for Legacy Configuration

Overview

This PR implements a comprehensive migration tool that converts legacy multi-file configuration (services.yaml + machines.yml + volumes.yaml + .env) to the unified homelab.yaml format introduced in Issue #33.

Key Features

• 🔄 Automatic Conversion: Migrates all configuration formats seamlessly
• 🔍 Dry Run Mode: Preview changes before applying them
• 🎯 Deployment Type Support: Handles Docker Compose and Docker Swarm configurations
• ✅ Integrated Validation: Built-in validation using existing schema tools
• 📚 Comprehensive Documentation: Detailed migration guide with examples

Deliverables

🛠️ Migration Tool

• scripts/migrate_to_homelab_yaml.sh - Comprehensive migration script with advanced options

📚 Documentation

• docs/migration/legacy-to-homelab-yaml.md - Complete migration guide with examples and troubleshooting

Migration Capabilities

Service Configuration Migration

• ✅ Image Extraction: From compose.image or container.image
• ✅ Port Detection: Uses port field or extracts from compose.ports
• ✅ Storage Detection: Sets storage: true if volumes are present
• ✅ Environment Variables: Converts arrays and objects to unified format
• ✅ Complex Configurations: Preserves advanced settings in overrides

Machine Configuration Migration

• ✅ Name Generation: Creates clean machine names from hostnames
• ✅ Role Preservation: Maintains manager/worker roles for Docker Swarm
• ✅ Label Conversion: Converts to "key=value" array format
• ✅ Default Fallback: Creates default machine if none exist

Environment Variable Migration

• ✅ Variable Export: Loads all environment variables
• ✅ Readonly Handling: Safely handles UID/GID conflicts
• ✅ Quote Processing: Cleans up quoted values
• ✅ Comment Filtering: Ignores comments and empty lines

Usage Examples

Basic Migration

# Preview migration
./scripts/migrate_to_homelab_yaml.sh --dry-run

# Migrate to homelab.yaml
./scripts/migrate_to_homelab_yaml.sh

# Validate output
./scripts/migrate_to_homelab_yaml.sh --validate

Advanced Migration

# Docker Swarm migration with custom output
./scripts/migrate_to_homelab_yaml.sh \
  --deployment docker_swarm \
  --output production-homelab.yaml \
  --validate \
  --force

# Custom input files
./scripts/migrate_to_homelab_yaml.sh \
  --services config/my-services.yaml \
  --machines custom-machines.yml \
  --dry-run

Migration Example

Legacy Configuration (Before)

# services.yaml
services:
  actual:
    port: 5006
    compose:
      image: actualbudget/actual-server:latest
      environment:
        - DEBUG=actual:config
      volumes:
        - /media/external/budget:/data

# machines.yml
managers:
  - hostname: "manager1.local"
    ip: "192.168.1.100"
    user: "ubuntu"

Unified Configuration (After)

# homelab.yaml
version: "2.0"
deployment: docker_compose

machines:
  manager1:
    host: 192.168.1.100
    user: ubuntu

services:
  actual:
    image: actualbudget/actual-server:latest
    port: 5006
    storage: true
    environment:
      DEBUG: "actual:config"
    overrides:
      docker_compose:
        volumes:
          - "/media/external/budget:/data"

Testing Results

• ✅ Dry Run Mode: Successfully previews migrations without file creation
• ✅ Service Processing: Correctly extracts 6 services from test configuration
• ✅ Environment Loading: Processes 18 environment variables
• ✅ Machine Detection: Handles both manager and worker nodes
• ✅ Validation Integration: Works with existing validation tools

Migration Benefits

1. 🎯 Simplified Configuration: Single file instead of 4+ separate files
2. 🔧 Preserved Functionality: All service definitions and settings maintained
3. 📈 Enhanced Flexibility: Better support for multiple deployment types
4. ✅ Built-in Validation: Immediate feedback on configuration correctness
5. 📚 Clear Documentation: Comprehensive guides and examples

Supported Migration Paths

• Legacy → Docker Compose: Full migration with service distribution
• Legacy → Docker Swarm: Migration with orchestration settings
• Custom Input Files: Flexible source file specification
• Partial Migration: Service-by-service migration support

Integration with Issue #33

This migration tool directly leverages the unified schema implemented in Issue #33:

• Uses the same homelab.yaml format and validation
• Compatible with all schema validation tools
• Follows the same deployment type patterns
• Integrates with existing documentation structure

Next Steps

This migration tool enables users to:

1. Upgrade Existing Installations: Convert legacy configurations easily
2. Test New Format: Preview changes before committing
3. Transition Gradually: Migrate services incrementally if needed
4. Prepare for Translation Engines: Ready for Issues [DOCKER-COMPOSE] Implement Basic Translation Engine #35-39 implementation

Breaking Changes

• No Breaking Changes: Legacy configurations remain supported during transition
• New Migration Process: Introduces new migration workflow
• Optional Adoption: Users can choose when to migrate

Verification

• All pre-commit hooks pass
• Migration script validates correctly with shellcheck
• Dry run mode works without creating files
• Generated configurations pass validation
• Documentation is comprehensive and tested
• Follows conventional commit format

---

Closes #34