pakker/docs/MIGRATION.md

# Migrating from Pakku to Pakker

This guide helps you migrate from Pakku (Kotlin) to Pakker (Rust).

## Overview

Pakker is designed to be largely compatible with Pakku, maintaining the same configuration format and workflow. Most Pakku modpacks can be imported directly into Pakker with minimal changes.

## Key Differences

### Performance

- **Faster execution** - Rust implementation provides significant speed improvements
- **Lower memory usage** - More efficient resource utilization
- **Parallel operations** - Better concurrency for downloads and processing

### Enhanced Features

- **Non-interactive mode** - `add-prj` command for CI/CD workflows
- **Advanced inspection** - Enhanced `inspect` command with dependency trees
- **Export profiles** - More flexible profile-based export configuration
- **Platform filtering** - Automatic platform-specific mod filtering

### Compatibility

✅ **Compatible**:
- Configuration format (`pakku.json`)
- Lockfile format (`pakku-lock.json`)
- Export formats (CurseForge ZIP, Modrinth .mrpack)
- Override directory structure
- Project properties and metadata

⚠️ **Differences**:
- Some CLI flag names (documented below)
- New features not in Pakku
- Performance characteristics

## Quick Migration

### Step 1: Import Existing Modpack

If you have an existing Pakku modpack:

```bash
# Navigate to your modpack directory
cd my-modpack

# Pakker will use existing pakku.json and pakku-lock.json
pakker ls
```

That's it! Pakker reads the same configuration files.

### Step 2: Verify Projects

```bash
# List all projects
pakker ls

# Inspect specific projects
pakker inspect sodium lithium
```

### Step 3: Test Export

```bash
# Export for your target platform
pakker export --profile curseforge
pakker export --profile modrinth
```

## Configuration Migration

### pakku.json Format

Pakker uses the **same format** as Pakku:

```json
{
  "name": "My Modpack",
  "version": "1.0.0",
  "description": "A performance modpack",
  "author": "YourName",
  "overrides": ["overrides"],
  "serverOverrides": ["server-overrides"],
  "clientOverrides": ["client-overrides"]
}
```

### Export Profiles

Pakker extends Pakku's configuration with enhanced export profiles:

**Pakku format** (still supported):

```json
{
  "exportProfiles": {
    "curseforge": {
      "filterPlatform": "curseforge"
    }
  }
}
```

**Pakker enhancements** (new features):

```json
{
  "exportProfiles": {
    "curseforge": {
      "filterPlatform": "curseforge",
      "includeNonRedistributable": false,
      "overrides": ["overrides", "curseforge-specific"]
    },
    "modrinth": {
      "filterPlatform": "modrinth",
      "includeNonRedistributable": true
    },
    "serverpack": {
      "includeClientOnly": false,
      "serverOverrides": ["server-config"]
    }
  }
}
```

See [EXPORT_PROFILES.md](./EXPORT_PROFILES.md) for complete documentation.

## Command Mapping

Most commands are identical or very similar:

| Pakku | Pakker | Notes |
|-------|--------|-------|
| `pakku init` | `pakker init` | Identical |
| `pakku import` | `pakker import` | Identical |
| `pakku add` | `pakker add` | Identical |
| `pakku add` | `pakker add-prj` | New non-interactive variant |
| `pakku rm` | `pakker rm` | Identical |
| `pakku update` | `pakker update` | Identical |
| `pakku ls` | `pakker ls` | Identical |
| `pakku status` | `pakker status` | Identical |
| `pakku fetch` | `pakker fetch` | Identical |
| `pakku export` | `pakker export` | Enhanced with profiles |
| `pakku link` | `pakker link` | Identical |
| `pakku set` | `pakker set` | Identical |
| `pakku cfg` | `pakker cfg` | Identical |
| `pakku diff` | `pakker diff` | Identical |

### New Commands in Pakker

- `pakker add-prj` - Non-interactive project addition for CI/CD
- `pakker inspect` - Enhanced project inspection with dependency trees
- `pakker sync` - Combined update + fetch operation
- `pakker credentials` - Credential management
- `pakker remote` - Git remote management
- `pakker fork` - Fork configuration

## Feature Comparison

### Project Management

| Feature | Pakku | Pakker | Notes |
|---------|-------|--------|-------|
| Add projects | ✅ | ✅ | Enhanced with `add-prj` |
| Remove projects | ✅ | ✅ | Identical |
| Update projects | ✅ | ✅ | Identical |
| List projects | ✅ | ✅ | Identical |
| Project properties | ✅ | ✅ | Identical |
| Dependencies | ✅ | ✅ | Enhanced inspection |

### Export System

| Feature | Pakku | Pakker | Notes |
|---------|-------|--------|-------|
| CurseForge export | ✅ | ✅ | Identical format |
| Modrinth export | ✅ | ✅ | Identical format |
| Server pack | ✅ | ✅ | Enhanced filtering |
| Export profiles | ✅ | ✅ | Extended features |
| Override dirs | ✅ | ✅ | Identical |
| Platform filtering | ❌ | ✅ | New in Pakker |
| Profile-specific overrides | ❌ | ✅ | New in Pakker |

### Configuration

| Feature | Pakku | Pakker | Notes |
|---------|-------|--------|-------|
| pakku.json | ✅ | ✅ | Same format |
| pakku-lock.json | ✅ | ✅ | Same format |
| Project config | ✅ | ✅ | Identical |
| Export profiles | ✅ | ✅ | Extended in Pakker |

## Migration Scenarios

### Scenario 1: Local Development

**Pakku workflow:**

```bash
pakku init
pakku add sodium lithium
pakku fetch
pakku export
```

**Pakker workflow:**

```bash
pakker init
pakker add sodium lithium
pakker fetch
pakker export --profile modrinth
```

No changes needed!

### Scenario 2: CI/CD Pipeline

**Pakku workflow:**

```bash
# Interactive, requires user input
pakku add sodium
pakku add lithium
pakku fetch
pakku export
```

**Pakker workflow:**

```bash
# Fully automated
pakker add-prj --mr sodium --yes --no-deps
pakker add-prj --mr lithium --yes --no-deps
pakker update --all --yes
pakker fetch
pakker export --profile modrinth -o dist/pack.mrpack
```

Benefits: No interactive prompts, perfect for CI/CD.

### Scenario 3: Multi-Platform Release

**Pakku workflow:**

```bash
# Manual export for each platform
pakku export
# Manually select CurseForge
pakku export
# Manually select Modrinth
```

**Pakker workflow:**

```bash
# Script multiple exports
pakker export --profile curseforge -o dist/cf.zip
pakker export --profile modrinth -o dist/mr.mrpack
pakker export --profile serverpack -o dist/server.zip
```

Benefits: Scriptable, reproducible builds.

## Migrating CI/CD Workflows

### GitHub Actions

**Before (Pakku):**

```yaml
- name: Setup Pakku
  run: |
    # Install Pakku
    
- name: Build modpack
  run: |
    pakku fetch
    pakku export
```

**After (Pakker):**

```yaml
- name: Setup Pakker
  run: |
    # Install Pakker
    cargo install pakker
    
- name: Build modpack
  run: |
    pakker fetch
    pakker export --profile curseforge -o dist/curseforge.zip
    pakker export --profile modrinth -o dist/modrinth.mrpack
```

### GitLab CI

**Before (Pakku):**

```yaml
build:
  script:
    - pakku fetch
    - pakku export
```

**After (Pakker):**

```yaml
build:
  script:
    - pakker fetch
    - pakker export --profile curseforge -o curseforge.zip
    - pakker export --profile modrinth -o modrinth.mrpack
  artifacts:
    paths:
      - "*.zip"
      - "*.mrpack"
```

## Troubleshooting

### Projects Not Found After Migration

**Problem**: Pakker can't find projects that worked in Pakku.

**Solution**: Verify lockfile format:

```bash
# Check lockfile
cat pakku-lock.json

# Re-fetch projects
pakker fetch

# If issues persist, re-add problematic projects
pakker rm problematic-mod
pakker add-prj --mr problematic-mod --yes
```

### Export Format Differences

**Problem**: Exported packs look different.

**Solution**: Pakker may organize files slightly differently. Both formats are valid:

```bash
# Inspect export
unzip -l curseforge.zip

# Verify manifest
jq . manifest.json
```

If needed, configure export profiles to match Pakku behavior exactly.

### Performance Issues

**Problem**: Pakker seems slower than expected.

**Solution**: Pakker should be faster than Pakku. Check:

```bash
# Enable logging
pakker -vv fetch

# Check network connectivity
pakker status

# Verify credentials (for rate limits)
pakker credentials
```

### Configuration Not Recognized

**Problem**: Some configuration options don't work.

**Solution**: Ensure you're using compatible options:

```json
{
  "name": "My Pack",
  "version": "1.0.0",
  "overrides": ["overrides"]
}
```

Pakker supports all Pakku options plus new ones. Check [EXPORT_PROFILES.md](./EXPORT_PROFILES.md) for new features.

## Best Practices

### 1. Test Before Full Migration

```bash
# Copy modpack to test directory
cp -r my-modpack my-modpack-test
cd my-modpack-test

# Test with Pakker
pakker ls
pakker fetch
pakker export --profile modrinth

# Verify exports match expectations
```

### 2. Update CI/CD Gradually

1. Test Pakker locally first
2. Update a single workflow
3. Verify builds succeed
4. Roll out to all workflows

### 3. Use New Features

Take advantage of Pakker enhancements:

```bash
# Non-interactive project addition
pakker add-prj --mr sodium --yes

# Enhanced inspection
pakker inspect sodium

# Profile-based exports
pakker export --profile production -o release.mrpack
```

### 4. Keep Backward Compatibility

If you need to support both Pakku and Pakker:

```json
{
  "exportProfiles": {
    "curseforge": {
      "filterPlatform": "curseforge"
    }
  }
}
```

Use the common subset of features that both support.

## Getting Help

### Resources

- [Pakker Documentation](./README.md)
- [Command Reference](./COMMANDS.md)
- [Export Profiles](./EXPORT_PROFILES.md)

### Common Issues

| Issue | Solution |
|-------|----------|
| Project not found | Try explicit platform: `pakker add-prj --mr <name>` |
| Export fails | Check export profile configuration |
| Missing files | Run `pakker fetch` |
| Slow performance | Verify network, add credentials |
| Config not recognized | Check pakku.json syntax with `jq` |

### Support Channels

- GitHub Issues: Report bugs and feature requests
- Documentation: Check docs/ directory
- Examples: See examples/ directory

## Migration Checklist

- [ ] Backup existing modpack directory
- [ ] Install Pakker
- [ ] Verify `pakker ls` shows all projects
- [ ] Test `pakker fetch` downloads files
- [ ] Test export for your target platform
- [ ] Update CI/CD workflows
- [ ] Test automated builds
- [ ] Update documentation
- [ ] Train team members on new commands
- [ ] Monitor for issues

## Feature Roadmap

Pakker aims for full Pakku compatibility plus enhancements. If you find missing features, please report them!

**Current Status:**
- ✅ Core functionality (add, remove, update, export)
- ✅ Multi-platform support
- ✅ Export profiles
- ✅ CI/CD workflows
- ✅ Dependency resolution

**Planned:**
- Custom export rules
- Advanced project filtering
- Enhanced remote sync
- Plugin system

## Summary

Migrating from Pakku to Pakker is straightforward:

1. **No configuration changes** needed for basic usage
2. **Same commands** for most operations
3. **Enhanced features** available when ready
4. **Better performance** out of the box
5. **CI/CD friendly** with non-interactive modes

Most users can start using Pakker immediately with existing Pakku modpacks!