pakker/docs/README.md

# Pakker

A fast, reliable multiplatform modpack manager for Minecraft, written in Rust.

## Overview

Pakker is a command-line tool for managing Minecraft modpacks across multiple
platforms including CurseForge, Modrinth, and GitHub. It provides a streamlined
workflow for creating, maintaining, and distributing modpacks with support for
automated dependency resolution, version management, and multi-platform exports.

## Key Features

### Multi-Platform Support

- **CurseForge**, **Modrinth**, and **GitHub** integration
- Unified project management across all platforms
- Platform-specific filtering and optimizations
- Automatic platform-specific manifest generation

### Intelligent Project Management

- **Dependency Resolution** - Automatically resolve and manage project
  dependencies
- **Version Management** - Update strategies (latest, specific version, pinned)
- **Project Inspection** - Detailed project information with dependency trees
- **Fuzzy Matching** - Typo-tolerant project searches with suggestions

### Flexible Export System

- **Profile-Based Exports** - Customize exports for different platforms and use
  cases
- **Platform Filtering** - Automatically exclude projects not available on
  target platform
- **Override Management** - Separate override directories for client/server
  configurations
- **Non-Interactive Mode** - Full CI/CD support with scriptable commands

### Advanced Configuration

- **Profile-Specific Settings** - Override paths, filtering rules, and export
  behavior per profile
- **Project-Level Customization** - Per-project export settings, aliases, and
  properties
- **Side Detection** - Automatic client/server/both classification
- **Redistributable Control** - Manage non-redistributable mod inclusion per
  profile

## Installation

### From Source

```bash
git clone https://github.com/yourusername/pakker
cd pakker
cargo build --release
```

The binary will be available at `target/release/pakker`.

### Prerequisites

- Rust 1.70 or later
- Git (for remote repository features)

## Quick Start

### Initialize a New Modpack

```bash
# Create a new modpack for Fabric 1.20.1
pakker init -m 1.20.1 -l fabric

# Or for Forge
pakker init -m 1.20.1 -l forge
```

### Add Mods

```bash
# Interactive mode - search and select
pakker add sodium

# Non-interactive with platform specification
pakker add-prj --mr sodium --yes

# Add with specific properties
pakker add-prj --cf jei --side both --yes
```

### Inspect Projects

```bash
# View project details
pakker inspect sodium

# Multiple projects with dependency trees
pakker inspect sodium lithium phosphor

# View all projects
pakker ls
```

### Fetch Mod Files

```bash
# Download all mod files
pakker fetch

# Or use sync to update and fetch
pakker sync
```

### Export Modpack

```bash
# Export for CurseForge
pakker export --profile curseforge

# Export for Modrinth
pakker export --profile modrinth

# Export server pack
pakker export --profile serverpack
```

## Project Structure

```
my-modpack/
├── pakku.json              # Modpack configuration
├── pakku-lock.json         # Lockfile with resolved versions
├── mods/                   # Downloaded mod files
├── overrides/              # Files to include in all exports
├── server-overrides/       # Server-specific files
└── client-overrides/       # Client-specific files
```

## Configuration Example

### Basic Configuration (`pakku.json`)

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

### With Export Profiles

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

## Common Workflows

### Development Workflow

```bash
# Initialize project
pakker init -m 1.20.1 -l fabric

# Add core mods
pakker add-prj --mr fabric-api --yes
pakker add-prj --mr sodium --yes
pakker add-prj --mr lithium --yes

# Configure and test
pakker fetch
# ... test in game ...

# Add more mods
pakker add create

# Check status
pakker status

# Export for testing
pakker export --profile modrinth
```

### CI/CD Pipeline

```bash
# Non-interactive project addition
pakker add-prj --mr fabric-api --yes --no-deps
pakker add-prj --cf jei --yes

# Update to latest versions
pakker update --yes

# Fetch all files
pakker fetch

# Export for all platforms
pakker export --profile curseforge -o dist/curseforge.zip
pakker export --profile modrinth -o dist/modrinth.mrpack
pakker export --profile serverpack -o dist/server.zip
```

### Multi-Platform Release

```bash
# Add projects from multiple platforms
pakker add-prj --mr sodium --cf sodium --yes
pakker add-prj --mr lithium --cf lithium --yes

# Configure CurseForge export (no non-redistributable)
# Configure Modrinth export (allow all)
# (in pakku.json - see Export Profiles documentation)

# Export for both
pakker export --profile curseforge -o releases/curseforge-pack.zip
pakker export --profile modrinth -o releases/modrinth-pack.mrpack
```

## Documentation

- **[Commands Reference](./COMMANDS.md)** - Complete command documentation
- **[Export Profiles](./EXPORT_PROFILES.md)** - Profile configuration guide
- **[Migration Guide](./MIGRATION.md)** - Migrating from Pakku
- **[Examples](../examples/)** - Configuration examples

## Command Overview

| Command       | Description                                            |
| ------------- | ------------------------------------------------------ |
| `init`        | Initialize a new modpack project                       |
| `import`      | Import an existing modpack                             |
| `add`         | Add projects interactively                             |
| `add-prj`     | Add projects non-interactively with explicit platforms |
| `rm`          | Remove projects                                        |
| `update`      | Update projects to newer versions                      |
| `ls`          | List all projects in modpack                           |
| `inspect`     | View detailed project information                      |
| `fetch`       | Download all project files                             |
| `sync`        | Update and fetch in one command                        |
| `export`      | Export modpack for distribution                        |
| `status`      | Check for available updates                            |
| `set`         | Modify project properties                              |
| `link`        | Link related projects                                  |
| `diff`        | Show differences with remote                           |
| `credentials` | Manage API credentials                                 |
| `cfg`         | Configure modpack properties                           |

See [COMMANDS.md](./COMMANDS.md) for detailed usage.

## Features in Detail

### Dependency Resolution

Pakker automatically resolves and manages dependencies:

```bash
pakker add sodium
# Automatically adds fabric-api as a dependency
```

Dependencies are tracked in `pakku-lock.json` and can be inspected:

```bash
pakker inspect sodium
# Shows:
# Dependencies: fabric-api
```

### Project Side Detection

Projects are automatically classified as client-only, server-only, or both:

- **Client-only**: Shaders, client performance mods, minimap mods
- **Server-only**: Server management mods, world generation mods
- **Both**: Most gameplay mods, APIs, libraries

Override this with:

```bash
pakker set sodium --side client
```

### Version Management

Control how projects are updated:

```bash
# Pin to specific version
pakker set sodium --strategy specific --version 0.5.0

# Always use latest
pakker set lithium --strategy latest

# Manual updates only
pakker set fabric-api --strategy pinned
```

### Export Profiles

Customize export behavior per platform:

- **Override directories** - Different overrides per export
- **Platform filtering** - Exclude unavailable mods
- **Redistributable control** - Manage non-redistributable content
- **Client/server filtering** - Remove client-only mods from server packs

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

### Remote Repositories

Sync modpack configuration with Git repositories:

```bash
# Add remote
pakker remote add origin https://github.com/user/modpack.git

# Pull updates
pakker remote-update

# Configuration is automatically synced
```

### Credentials Management

Store platform API credentials securely:

```bash
# Set credentials
pakker credentials set --curseforge YOUR_CF_KEY
pakker credentials set --modrinth YOUR_MR_TOKEN

# Credentials are used automatically for:
# - Private mods
# - Rate limit increases
# - Authenticated downloads
```

## Platform Compatibility

### CurseForge

- Full project search and metadata
- Automatic manifest generation
- Non-redistributable mod detection
- Curse modpack import support

### Modrinth

- Complete Modrinth API integration
- .mrpack format import/export
- Environment metadata support
- Full modpack search

### GitHub

- GitHub Releases integration
- Direct JAR downloads
- Version tag support

## Advanced Usage

### Fuzzy Project Search

Don't remember exact names? Pakker helps:

```bash
pakker add sodum
# Suggested: Did you mean "sodium"?
```

### Batch Operations

Add multiple projects efficiently:

```bash
pakker add-prj --mr sodium --yes
pakker add-prj --mr lithium --yes
pakker add-prj --mr phosphor --yes
```

Or use a script:

```bash
#!/bin/bash
mods=("sodium" "lithium" "phosphor" "iris")
for mod in "${mods[@]}"; do
  pakker add-prj --mr "$mod" --yes
done
```

### Inspect Dependency Trees

Visualize complex dependency relationships:

```bash
pakker inspect create
# Shows:
# create v0.5.1
# ├── flywheel v0.6.10
# │   └── forge-api v1.20.1
# └── registrate v1.3.3
```

### Custom Export Profiles

Create specialized export configurations:

```json
{
  "exportProfiles": {
    "production": {
      "filterPlatform": "curseforge",
      "includeNonRedistributable": false,
      "overrides": ["overrides", "prod-config"]
    },
    "development": {
      "includeNonRedistributable": true,
      "overrides": ["overrides", "dev-config"]
    },
    "client": {
      "includeClientOnly": true,
      "overrides": ["overrides", "client-extras"]
    }
  }
}
```

## Acknowledgments

Pakker is inspired by [Pakku](https://github.com/juraj-hrivnak/Pakku), bringing
similar functionality with improved performance and additional features through
Rust implementation.