wp-migrate

# WordPress Migration Skill

This skill provides expertise for working with the wp-migrate.sh WordPress migration tool.

## Project Overview

wp-migrate.sh is a comprehensive WordPress migration tool that operates in two modes:

1. **Push Mode**: Migrates WordPress sites between servers via SSH (source → destination)
2. **Archive Mode**: Imports WordPress backup archives (Duplicator, Jetpack Backup, Solid Backups) on destination server

**Current Version**: Check the latest release

```bash
git describe --tags --abbrev=0  # Get current version from git
```

**Latest Release**: See [GitHub Releases](https://github.com/BWBama85/wp-migrate.sh/releases/latest)

**Repository**: BWBama85/wp-migrate.sh

**Main Branch**: main

## Core Capabilities

### Migration Modes

#### Push Mode
- Transfers wp-content and database from source to destination via SSH
- Enables maintenance mode on both servers during migration
- Creates timestamped backups before overwriting
- Performs URL search-replace to align destination domain
- Excludes object-cache.php to preserve destination caching infrastructure
- Supports StellarSites managed hosting compatibility (--stellarsites flag)

#### Archive Mode
- Auto-detects archive format (Duplicator, Jetpack Backup, Solid Backups)
- Extracts archives to temporary directory
- Validates disk space (requires 3x archive size)
- Creates backups of destination database and wp-content before import
- Automatically aligns table prefixes if different from wp-config.php
- Performs URL search-replace to align with destination URLs
- Provides rollback instructions with exact commands

### Key Features
- **Migration preview with confirmation**: Pre-migration summary with detailed stats and confirmation prompt (v2.6.0)
- **Rollback command**: Automatic restoration from backups with --rollback flag (v2.6.0)
- **Progress indicators**: Real-time progress bars for long-running operations when pv is installed (v2.6.0)
- **Dry-run mode**: Preview all operations without making changes (--dry-run)
- **Verbose logging**: Show detailed diagnostic information (--verbose)
- **Trace mode**: Show every command before execution (--trace)
- **Plugin preservation**: Preserve destination plugins/themes not in source (--preserve-dest-plugins)
- **StellarSites mode**: Managed hosting compatibility with mu-plugins exclusion (--stellarsites)
- **Skip search-replace**: Fast migrations that only update home/siteurl options (--no-search-replace)
- **Automation support**: Skip confirmation prompts with --yes flag for CI/CD (v2.6.0)
- **Quiet mode**: Suppress progress indicators for non-interactive scripts with --quiet (v2.6.0)

## Common Tasks

### Running Migrations

**Push Mode:**
```bash
./wp-migrate.sh --dest-host user@dest.example.com --dest-root /var/www/site
```

**Archive Mode:**
```bash
./wp-migrate.sh --archive /path/to/backup.zip
./wp-migrate.sh --archive /path/to/backup.tar.gz --archive-type jetpack
```

**Dry Run:**
```bash
./wp-migrate.sh --dest-host user@dest --dest-root /var/www/site --dry-run --verbose
```

**Rollback (v2.6.0):**
```bash
./wp-migrate.sh --rollback  # Auto-detects latest backups
./wp-migrate.sh --rollback --rollback-backup /path/to/specific/backup  # Specific backup
./wp-migrate.sh --rollback --yes  # Skip confirmation for automation
```

**Automation-Friendly (v2.6.0):**
```bash
./wp-migrate.sh --archive /path/to/backup.zip --yes --quiet  # CI/CD: skip prompts, no progress bars
```

### Testing

**Run all tests:**
```bash
make test
```

**Run specific test:**
```bash
./test-wp-migrate.sh
```

**ShellCheck validation:**
```bash
shellcheck wp-migrate.sh
```

### Development Workflow

#### Code Structure (v2+)
The project uses a modular source structure:

```
src/
├── header.sh           # Shebang, defaults, variable declarations
├── lib/
│   ├── core.sh         # Core utilities (log, err, validate_url)
│   ├── functions.sh    # All other functions
│   └── adapters/       # Archive format adapters
│       ├── README.md
│       ├── duplicator.sh
│       ├── jetpack.sh
│       └── solidbackups.sh
└── main.sh             # Argument parsing and main execution
```

**IMPORTANT**: Modifications should be made in `src/` files, NOT in `wp-migrate.sh` directly.

#### Build Process

After modifying source files:
```bash
make build
```

This will:
1. Run shellcheck on concatenated source
2. Concatenate src/ files into dist/wp-migrate.sh
3. Copy to ./wp-migrate.sh (repo root)
4. Generate SHA256 checksum

#### Pre-commit Hook
A pre-commit hook prevents committing source changes without rebuilding:
```bash
ln -s ../../.githooks/pre-commit .git/hooks/pre-commit
```

### Git Workflow

1. **Branching**: Create from main using descriptive names:
   - `feature/<slug>` for enhancements
   - `fix/<slug>` for bug fixes
   - `docs/<slug>` for documentation
   - `chore/<slug>` for maintenance

2. **Commits**: Use .gitmessage template format:
   ```
   type: short imperative summary

   Longer explanation if needed
   ```

   Types: feat, fix, docs, chore, refactor, test

3. **Changelog**: Update CHANGELOG.md under [Unreleased] section with every feature or fix

4. **Pull Requests**:
   - Use .github/pull_request_template.md checklist
   - Include comprehensive summary based on ALL commits (not just latest)
   - Include test plan with verification steps
   - Reference related issues

5. **Merging**: Keep main release-ready with `git merge --no-ff` or squash after review

6. **Releases**: Tag with semantic versioning (e.g., `git tag v2.7.0`)

### Creating Pull Requests

When creating PRs, ensure:
- Review ALL commits in the branch (use `git log main..HEAD` and `git diff main...HEAD`)
- Summary covers complete scope of changes
- Test plan verifies all functionality
- CHANGELOG.md is updated
- ShellCheck passes
- Tests pass (make test)

### Common Files to Check

- [wp-migrate.sh](wp-migrate.sh) - Main script (built artifact, don't edit directly)
- [src/](src/) - Modular source files (edit these)
- [src/lib/adapters/](src/lib/adapters/) - Archive format adapters
- [CHANGELOG.md](CHANGELOG.md) - Version history
- [README.md](README.md) - User documentation
- [Makefile](Makefile) - Build and test targets
- [test-wp-migrate.sh](test-wp-migrate.sh) - Test script

## Troubleshooting Guide

### Common Issues

**Permission Errors on Managed Hosts (StellarSites)**
- Symptom: "Permission denied" when syncing wp-content
- Solution: Use `--stellarsites` flag to exclude protected mu-plugins
- Details: Managed hosts protect certain mu-plugins directories (e.g., `stellarsites-cloud`)

**Database Import Fails**
- Check table prefix alignment (script auto-detects and updates wp-config.php)
- Verify sufficient disk space (3x archive size for archive mode)
- Check MySQL max_allowed_packet size for large imports

**URL Search-Replace Issues**
- Use `--verbose` to see detected URLs
- Override with `--dest-home-url` or `--dest-site-url` if detection fails
- Use `--no-search-replace` for faster migrations that only need home/siteurl updated

**Archive Detection Fails**
- Use explicit `--archive-type` to specify format (duplicator, jetpack, solidbackups)
- Verify archive structure matches adapter expectations (see src/lib/adapters/)
- Check detailed validation errors with --verbose (v2.6.0+)

**Non-Interactive Context Failures (v2.6.0)**
- Symptom: Script exits with "This script requires a TTY for confirmation prompts"
- Solution: Add `--yes` flag when running in CI/CD, cron, or pipeline contexts
- Details: Migration preview and rollback require confirmation by default; use --yes to bypass

**Rollback Issues (v2.6.0)**
- Auto-detection looks for latest timestamped backups in db-backups/ and wp-content.backup-*
- If backups aren't found, use `--rollback-backup /path/to/backup` to specify explicitly
- Rollback only works for archive mode migrations (restores from local backups)

**SSH Connection Issues**
- Add custom SSH options with `--ssh-opt` (can be repeated)
- Examples: `--ssh-opt 'Port=2222'` or `--ssh-opt 'ProxyJump=bastion'`

**ShellCheck Errors**
- Install ShellCheck: `brew install shellcheck` (macOS) or see https://www.shellcheck.net/
- Run: `shellcheck wp-migrate.sh`
- All code must be ShellCheck-clean before merging

### Debugging Commands

**Show verbose migration preview:**
```bash
./wp-migrate.sh --dest-host user@dest --dest-root /var/www/site --dry-run --verbose
```

**Show every command (trace mode):**
```bash
./wp-migrate.sh --dest-host user@dest --dest-root /var/www/site --dry-run --trace
```

**Check archive structure:**
```bash
unzip -l /path/to/backup.zip | head -50
tar -tzf /path/to/backup.tar.gz | head -50
```

**Verify wp-cli on destination:**
```bash
ssh user@dest 'cd /var/www/site && wp core version'
```

## Archive Adapter System

The script uses an extensible adapter system for different backup formats.

### Supported Formats

1. **Duplicator**: ZIP archives with `dup-installer/dup-database__*.sql` structure
2. **Jetpack Backup**: ZIP/TAR.GZ archives with `sql/*.sql` multi-file structure
3. **Solid Backups**: ZIP archives with split SQL in `wp-content/uploads/backupbuddy_temp/{ID}/`

### Adding New Adapters

See [src/lib/adapters/README.md](src/lib/adapters/README.md) for contributor guide.

Each adapter must implement:
- `validate_<adapter>()` - Check if file matches format
- `extract_<adapter>()` - Extract archive to temp directory
- `detect_db_<adapter>()` - Find database file(s)
- `detect_wp_content_<adapter>()` - Find wp-content directory

## Best Practices

### When Assisting with Code Changes

1. **Always check if source files need modification** (src/) not wp-migrate.sh directly
2. **Run `make build` after any source changes** to regenerate wp-migrate.sh
3. **Run ShellCheck validation** before committing
4. **Update CHANGELOG.md** for all features and fixes
5. **Use TodoWrite** to track multi-step tasks
6. **Create focused PRs** addressing single concerns

### When Testing Migrations

1. **Always start with dry-run** to preview operations
2. **Use verbose mode** for troubleshooting (--verbose or --trace)
3. **Verify backups** before destructive operations
4. **Test rollback procedures** in safe environments
5. **Check logs** in logs/ directory after migrations

### When Creating Releases

1. **Update CHANGELOG.md** with version number and date
2. **Create git tag** with semantic version (e.g., v2.7.0)
3. **Generate GitHub release** with changelog excerpt
4. **Verify tests pass** on clean checkout
5. **Update README** if user-facing changes exist

## Common Patterns

### Searching Code
Use Grep tool for code searches:
```
pattern: "function_name"
output_mode: "content"
-n: true (show line numbers)
```

### Reading Source Files
Use Read tool for file contents:
```
file_path: /Volumes/personal/codeprojects/bash/wp-migrate/src/lib/functions.sh
```

### Editing Code
Use Edit tool for precise changes:
```
file_path: /Volumes/personal/codeprojects/bash/wp-migrate/src/lib/functions.sh
old_string: "exact match from file"
new_string: "replacement text"
```

### Running Git Commands
```bash
git status
git diff main...HEAD  # See all changes in branch
git log main..HEAD    # See all commits in branch
```

## Critical Reminders

- **NEVER edit wp-migrate.sh directly** - edit files in src/ instead
- **ALWAYS run `make build`** after source changes
- **ALWAYS update CHANGELOG.md** for features and fixes
- **ALWAYS run ShellCheck** before committing (make test)
- **ALWAYS commit both source AND built files** together
- **ALWAYS review ALL commits** when creating PRs (not just latest commit)
- **ALWAYS use TodoWrite** for multi-step tasks to track progress