diff --git a/docs/COMMANDS.md b/docs/COMMANDS.md deleted file mode 100644 index 0290e89..0000000 --- a/docs/COMMANDS.md +++ /dev/null @@ -1,971 +0,0 @@ -# Pakker Command Reference - -Complete reference for all Pakker commands. - -## Table of Contents - -- [Global Options](#global-options) -- [Project Management](#project-management) - - [init](#init) - - [import](#import) - - [add](#add) - - [add-prj](#add-prj) - - [rm](#rm) - - [ls](#ls) - - [inspect](#inspect) -- [Updates and Sync](#updates-and-sync) - - [update](#update) - - [fetch](#fetch) - - [sync](#sync) - - [status](#status) -- [Project Configuration](#project-configuration) - - [set](#set) - - [link](#link) - - [unlink](#unlink) -- [Export](#export) - - [export](#export-1) -- [Configuration](#configuration) - - [cfg](#cfg) - - [credentials](#credentials) -- [Remote Management](#remote-management) - - [remote](#remote) - - [remote-update](#remote-update) - - [fork](#fork) -- [Utilities](#utilities) - - [diff](#diff) - ---- - -## Global Options - -All commands support these global flags: - -```bash --v, --verbose # Enable verbose output --vv # Very verbose (debug level) --vvv # Trace level logging -``` - -Examples: - -```bash -pakker -v add sodium # Info logging -pakker -vv fetch # Debug logging -pakker -vvv export # Trace logging -``` - ---- - -## Project Management - -### init - -Initialize a new modpack project in the current directory. - -**Usage:** - -```bash -pakker init [OPTIONS] -``` - -**Options:** - -- `-t, --target ` - Target platform (default: multiplatform) -- `-m, --mc-version ` - Minecraft version (default: 1.20.1) -- `-l, --loader ` - Mod loader (default: fabric) -- `--loader-version ` - Specific loader version - -**Examples:** - -```bash -# Initialize Fabric 1.20.1 modpack -pakker init - -# Initialize Forge 1.19.4 modpack -pakker init -m 1.19.4 -l forge - -# Initialize with specific loader version -pakker init -l fabric --loader-version 0.15.0 - -# Initialize for CurseForge only -pakker init --target curseforge -``` - -**Output:** - -Creates: -- `pakku.json` - Configuration file -- `pakku-lock.json` - Lockfile -- `overrides/` - Override directory - ---- - -### import - -Import an existing modpack from CurseForge or Modrinth. - -**Usage:** - -```bash -pakker import -``` - -**Supported Formats:** - -- CurseForge ZIP files -- Modrinth .mrpack files -- Local directories with manifest -- Remote URLs - -**Examples:** - -```bash -# Import from local file -pakker import modpack.zip -pakker import pack.mrpack - -# Import from URL -pakker import https://example.com/modpack.zip - -# Import from directory -pakker import ./existing-modpack/ -``` - ---- - -### add - -Interactively add projects to the modpack. - -**Usage:** - -```bash -pakker add ... -``` - -**Features:** - -- Interactive platform selection -- Automatic dependency resolution -- Fuzzy search with suggestions -- Version selection - -**Examples:** - -```bash -# Add single project -pakker add sodium - -# Add multiple projects -pakker add sodium lithium phosphor - -# Add with typo correction -pakker add sodum -# Suggests: Did you mean "sodium"? -``` - ---- - -### add-prj - -Add projects non-interactively with explicit platform specification. - -**Usage:** - -```bash -pakker add-prj [OPTIONS] -``` - -**Platform Options:** - -- `--cf, --curseforge ` - CurseForge project ID or slug -- `--mr, --modrinth ` - Modrinth project ID or slug -- `--gh, --github ` - GitHub repository (format: owner/repo) - -**Property Options:** - -- `--type ` - Project type (mod, resourcepack, shader, modpack) -- `--side ` - Project side (client, server, both) -- `--strategy ` - Update strategy (latest, specific, pinned) -- `--version ` - Specific version to use -- `--redistributable ` - Allow redistribution (true/false) -- `--subpath ` - Custom subpath in mods directory -- `--alias ` - Project alias -- `--export ` - Include in exports (true/false) - -**Control Options:** - -- `--yes, -y` - Skip all confirmations -- `--no-deps` - Don't resolve dependencies - -**Examples:** - -```bash -# Add from Modrinth -pakker add-prj --mr sodium --yes - -# Add from CurseForge -pakker add-prj --cf jei --yes - -# Add from multiple platforms (creates unified project) -pakker add-prj --mr sodium --cf sodium --yes - -# Add with custom properties -pakker add-prj --mr sodium --side client --strategy pinned --yes - -# Add without dependencies (for CI) -pakker add-prj --mr fabric-api --yes --no-deps - -# Add with alias -pakker add-prj --mr sodium --alias "sodium-mod" --yes - -# Add GitHub release -pakker add-prj --gh "IrisShaders/Iris" --yes -``` - -**CI/CD Usage:** - -```bash -#!/bin/bash -# Batch add mods -mods=( - "fabric-api" - "sodium" - "lithium" - "phosphor" -) - -for mod in "${mods[@]}"; do - pakker add-prj --mr "$mod" --yes --no-deps || exit 1 -done - -# Resolve all dependencies at once -pakker update --yes -``` - ---- - -### rm - -Remove projects from the modpack. - -**Usage:** - -```bash -pakker rm ... -``` - -**Examples:** - -```bash -# Remove single project -pakker rm sodium - -# Remove multiple projects -pakker rm sodium lithium phosphor - -# Remove with confirmation -pakker rm outdated-mod -``` - ---- - -### ls - -List all projects in the modpack. - -**Usage:** - -```bash -pakker ls [OPTIONS] -``` - -**Options:** - -- `--type ` - Filter by type -- `--side ` - Filter by side -- `--platform ` - Filter by platform - -**Examples:** - -```bash -# List all projects -pakker ls - -# List only mods -pakker ls --type mod - -# List client-only projects -pakker ls --side client - -# List CurseForge projects -pakker ls --platform curseforge -``` - -**Output Format:** - -``` -sodium (v0.5.0) - both - [CF, MR] -lithium (v0.11.2) - both - [CF, MR] -iris (v1.6.4) - client - [CF, MR] -``` - ---- - -### inspect - -View detailed information about projects including dependencies. - -**Usage:** - -```bash -pakker inspect [PROJECT]... -``` - -**Features:** - -- Project metadata (name, version, platforms) -- File information (name, size, hashes) -- Dependency trees with visualization -- Circular dependency detection -- Property display - -**Examples:** - -```bash -# Inspect single project -pakker inspect sodium - -# Inspect multiple projects -pakker inspect sodium lithium phosphor - -# View modpack overview (no arguments) -pakker inspect - -# Fuzzy matching with suggestions -pakker inspect sodum -# Suggests: Did you mean "sodium"? -``` - -**Example Output:** - -``` -Sodium v0.5.0 - Type: mod - Side: client - Platforms: curseforge, modrinth - - Files: - sodium-fabric-0.5.0+mc1.20.jar - Size: 2.3 MB - SHA1: abc123... - - Dependencies: - └── fabric-api v0.87.0 - └── fabric-loader >=0.14.0 - - Properties: - Redistributable: true - Update Strategy: latest - Export: true -``` - ---- - -## Updates and Sync - -### update - -Update projects to newer versions. - -**Usage:** - -```bash -pakker update [PROJECT]... [OPTIONS] -``` - -**Options:** - -- `--yes, -y` - Skip confirmations -- `--all` - Update all projects - -**Examples:** - -```bash -# Update specific project -pakker update sodium - -# Update multiple projects -pakker update sodium lithium - -# Update all projects -pakker update --all - -# Update without confirmation (CI) -pakker update --all --yes -``` - ---- - -### fetch - -Download all project files. - -**Usage:** - -```bash -pakker fetch [OPTIONS] -``` - -**Options:** - -- `--force` - Re-download existing files - -**Examples:** - -```bash -# Fetch all files -pakker fetch - -# Force re-download -pakker fetch --force -``` - -**Output:** - -``` -Fetching 42 files... -✓ sodium-fabric-0.5.0.jar (local) -✓ lithium-fabric-0.11.2.jar (download) -✓ fabric-api-0.87.0.jar (download) -... -``` - ---- - -### sync - -Update projects and fetch files in one command. - -**Usage:** - -```bash -pakker sync [OPTIONS] -``` - -**Options:** - -- `--yes, -y` - Skip confirmations - -**Examples:** - -```bash -# Sync everything -pakker sync - -# Sync without confirmation -pakker sync --yes -``` - -Equivalent to: - -```bash -pakker update --all --yes -pakker fetch -``` - ---- - -### status - -Check for available updates. - -**Usage:** - -```bash -pakker status -``` - -**Examples:** - -```bash -pakker status -``` - -**Example Output:** - -``` -Updates available: - sodium: v0.5.0 → v0.5.1 - lithium: v0.11.1 → v0.11.2 - -No updates: - fabric-api (v0.87.0) - iris (v1.6.4) -``` - ---- - -## Project Configuration - -### set - -Modify project properties. - -**Usage:** - -```bash -pakker set [OPTIONS] -``` - -**Options:** - -- `--type ` - Set project type -- `--side ` - Set project side -- `--strategy ` - Set update strategy -- `--version ` - Set specific version (use with strategy=specific) -- `--redistributable ` - Set redistributable flag -- `--subpath ` - Set custom subpath -- `--alias ` - Set project alias -- `--export ` - Set export flag - -**Examples:** - -```bash -# Change project side -pakker set sodium --side client - -# Pin to specific version -pakker set fabric-api --strategy specific --version 0.87.0 - -# Always update to latest -pakker set lithium --strategy latest - -# Never update -pakker set custom-mod --strategy pinned - -# Mark as non-redistributable -pakker set optifine --redistributable false - -# Don't include in exports -pakker set dev-mod --export false - -# Set custom subpath -pakker set performance-mod --subpath "mods/performance/" -``` - ---- - -### link - -Link projects together (define relationships). - -**Usage:** - -```bash -pakker link -``` - -**Examples:** - -```bash -# Link projects -pakker link sodium fabric-api -``` - ---- - -### unlink - -Remove project links. - -**Usage:** - -```bash -pakker unlink -``` - -**Examples:** - -```bash -# Unlink projects -pakker unlink sodium fabric-api -``` - ---- - -## Export - -### export - -Export modpack for distribution. - -**Usage:** - -```bash -pakker export [OPTIONS] -``` - -**Options:** - -- `--profile ` - Export profile (curseforge, modrinth, serverpack, or custom) -- `-o, --output ` - Output file path - -**Built-in Profiles:** - -- `curseforge` - CurseForge ZIP format with manifest.json -- `modrinth` - Modrinth .mrpack format -- `serverpack` - Server-optimized pack (no client-only mods) - -**Examples:** - -```bash -# Export for CurseForge -pakker export --profile curseforge - -# Export for Modrinth -pakker export --profile modrinth - -# Export with custom output path -pakker export --profile curseforge -o dist/modpack-v1.0.0.zip - -# Export server pack -pakker export --profile serverpack -o server.zip - -# Export all formats -pakker export --profile curseforge -o dist/cf.zip -pakker export --profile modrinth -o dist/mr.mrpack -pakker export --profile serverpack -o dist/server.zip -``` - -**Profile Configuration:** - -Configure profiles in `pakku.json`: - -```json -{ - "exportProfiles": { - "curseforge": { - "filterPlatform": "curseforge", - "includeNonRedistributable": false - }, - "production": { - "filterPlatform": "modrinth", - "overrides": ["overrides", "prod-config"] - } - } -} -``` - -See [EXPORT_PROFILES.md](./EXPORT_PROFILES.md) for complete documentation. - ---- - -## Configuration - -### cfg - -Configure modpack properties. - -**Usage:** - -```bash -pakker cfg [OPTIONS] -``` - -**Options:** - -- `--name ` - Set modpack name -- `--version ` - Set modpack version -- `--description ` - Set description -- `--author ` - Set author - -**Examples:** - -```bash -# Set modpack name -pakker cfg --name "My Awesome Pack" - -# Set version -pakker cfg --version "1.0.0" - -# Set multiple properties -pakker cfg --name "Performance Pack" --author "YourName" --version "2.0.0" -``` - ---- - -### credentials - -Manage platform API credentials. - -**Usage:** - -```bash -# View credentials -pakker credentials - -# Set credentials -pakker credentials set --curseforge -pakker credentials set --modrinth - -# Remove credentials -pakker credentials remove --curseforge -pakker credentials remove --modrinth -``` - -**Examples:** - -```bash -# Set CurseForge API key -pakker credentials set --curseforge $CF_API_KEY - -# Set Modrinth token -pakker credentials set --modrinth $MR_TOKEN - -# View current credentials -pakker credentials - -# Remove CurseForge key -pakker credentials remove --curseforge -``` - -**Credential Storage:** - -Credentials are stored securely: -1. System keyring (if available) -2. Pakker credentials file (encrypted) -3. Environment variables - -**Benefits:** - -- Higher API rate limits -- Access to private/early-access mods -- Faster downloads -- Better error messages - ---- - -## Remote Management - -### remote - -Manage Git remote repositories for modpack configuration. - -**Usage:** - -```bash -# Add remote -pakker remote add - -# List remotes -pakker remote list - -# Remove remote -pakker remote remove -``` - -**Examples:** - -```bash -# Add origin remote -pakker remote add origin https://github.com/user/modpack.git - -# Add upstream -pakker remote add upstream https://github.com/original/modpack.git - -# List all remotes -pakker remote list - -# Remove remote -pakker remote remove origin -``` - ---- - -### remote-update - -Pull modpack configuration updates from remote Git repository. - -**Usage:** - -```bash -pakker remote-update [REMOTE] -``` - -**Examples:** - -```bash -# Update from default remote -pakker remote-update - -# Update from specific remote -pakker remote-update upstream - -# Update and sync -pakker remote-update && pakker sync -``` - ---- - -### fork - -Manage fork configuration. - -**Usage:** - -```bash -pakker fork [OPTIONS] -``` - -**Options:** - -- `--ref ` - Set fork reference (branch, tag, commit) -- `--type ` - Set reference type - -**Examples:** - -```bash -# Fork from branch -pakker fork --ref main --type branch - -# Fork from tag -pakker fork --ref v1.0.0 --type tag - -# Fork from commit -pakker fork --ref abc1234 --type commit -``` - ---- - -## Utilities - -### diff - -Show differences between local and remote modpack configuration. - -**Usage:** - -```bash -pakker diff [REMOTE] -``` - -**Examples:** - -```bash -# Show diff with default remote -pakker diff - -# Show diff with specific remote -pakker diff upstream - -# Show diff in detail -pakker -v diff -``` - -**Example Output:** - -``` -Changes in remote: - + sodium v0.5.1 (added) - - old-mod v1.0.0 (removed) - ~ lithium v0.11.1 → v0.11.2 (updated) - -Local changes: - + custom-mod v1.0.0 (added) -``` - ---- - -## Common Patterns - -### CI/CD Pipeline - -```bash -#!/bin/bash -set -e - -# Add projects non-interactively -pakker add-prj --mr fabric-api --yes --no-deps -pakker add-prj --mr sodium --yes --no-deps -pakker add-prj --mr lithium --yes --no-deps - -# Resolve dependencies -pakker update --all --yes - -# Fetch 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 -``` - -### Batch Updates - -```bash -# Update all projects -pakker update --all --yes - -# Fetch new versions -pakker fetch - -# Export updated pack -pakker export --profile modrinth -o updated-pack.mrpack -``` - -### Platform Migration - -```bash -# Add projects from new platform -pakker add-prj --mr sodium --cf sodium --yes -pakker add-prj --mr lithium --cf lithium --yes - -# Export for both platforms -pakker export --profile curseforge -o cf-pack.zip -pakker export --profile modrinth -o mr-pack.mrpack -``` - ---- - -## Environment Variables - -### Credentials - -```bash -export CURSEFORGE_API_KEY="your-key" -export MODRINTH_TOKEN="your-token" -``` - -### Verbosity - -```bash -export PAKKER_LOG=debug # or info, warn, error -``` - -### Cache - -```bash -export PAKKER_CACHE_DIR="$HOME/.cache/pakker" -``` - ---- - -## Exit Codes - -- `0` - Success -- `1` - General error -- `2` - Invalid arguments -- `3` - Project not found -- `4` - Network error -- `5` - File system error - ---- - -## See Also - -- [Main Documentation](./README.md) -- [Export Profiles](./EXPORT_PROFILES.md) -- [Migration Guide](./MIGRATION.md) -- [Examples](../examples/) diff --git a/docs/EXPORT_PROFILES.md b/docs/EXPORT_PROFILES.md deleted file mode 100644 index 6ecb63d..0000000 --- a/docs/EXPORT_PROFILES.md +++ /dev/null @@ -1,348 +0,0 @@ -# Export Profiles Configuration - -Pakker supports profile-specific export configurations, allowing you to customize export behavior for different platforms and use cases. - -## Overview - -Export profiles enable you to: -- Use different override directories per profile -- Filter projects by platform availability -- Control non-redistributable mod inclusion -- Customize client-only mod filtering -- Override settings per project - -## Configuration - -Add an `exportProfiles` section to your `pakku.json` file: - -```json -{ - "name": "My Modpack", - "version": "1.0.0", - "overrides": ["overrides"], - "exportProfiles": { - "curseforge": { - "filterPlatform": "curseforge", - "includeNonRedistributable": false, - "overrides": ["overrides", "curseforge-overrides"] - }, - "modrinth": { - "filterPlatform": "modrinth", - "includeNonRedistributable": true - }, - "serverpack": { - "includeClientOnly": false, - "serverOverrides": ["server-config"] - } - } -} -``` - -## Profile Configuration Options - -### `filterPlatform` (string, optional) - -Filter projects to only include those available on the specified platform. - -**Supported values**: `"curseforge"`, `"modrinth"`, `"github"` - -**Example**: -```json -{ - "filterPlatform": "modrinth" -} -``` - -Projects without a Modrinth version will be excluded from the export. - ---- - -### `includeNonRedistributable` (boolean, optional) - -Control whether non-redistributable mods are included in the export. - -**Default**: `false` for CurseForge, `true` for others - -**Example**: -```json -{ - "includeNonRedistributable": false -} -``` - ---- - -### `includeClientOnly` (boolean, optional) - -Control whether client-only mods are included in server pack exports. - -**Default**: `false` for serverpack profile, `true` for others - -**Example**: -```json -{ - "includeClientOnly": false -} -``` - ---- - -### `overrides` (array of strings, optional) - -Override directories to include in the export. Replaces global `overrides` setting. - -**Example**: -```json -{ - "overrides": ["overrides", "platform-specific-overrides"] -} -``` - ---- - -### `serverOverrides` (array of strings, optional) - -Server-specific override directories. Replaces global `serverOverrides` setting. - -**Example**: -```json -{ - "serverOverrides": ["server-config", "server-scripts"] -} -``` - ---- - -### `clientOverrides` (array of strings, optional) - -Client-specific override directories. Replaces global `clientOverrides` setting. - -**Example**: -```json -{ - "clientOverrides": ["client-config", "shaderpacks"] -} -``` - ---- - -### `projectOverrides` (object, optional) - -Per-project configuration within this profile. Not yet implemented. - -**Future feature**: -```json -{ - "projectOverrides": { - "sodium": { - "export": false - }, - "optifine": { - "export": true, - "subpath": "mods/performance/" - } - } -} -``` - -## Default Profiles - -Pakker provides sensible defaults for common profiles: - -### CurseForge Default - -```json -{ - "filterPlatform": "curseforge", - "includeNonRedistributable": false -} -``` - -### Modrinth Default - -```json -{ - "filterPlatform": "modrinth", - "includeNonRedistributable": true -} -``` - -### ServerPack Default - -```json -{ - "includeClientOnly": false -} -``` - -These defaults are used automatically when exporting with `pakker export --profile ` if no custom configuration is specified. - -## Usage Examples - -### Example 1: Multi-Platform Modpack - -```json -{ - "name": "Multi-Platform Pack", - "version": "1.0.0", - "overrides": ["overrides"], - "exportProfiles": { - "curseforge": { - "filterPlatform": "curseforge", - "includeNonRedistributable": false, - "overrides": ["overrides", "curseforge-overrides"] - }, - "modrinth": { - "filterPlatform": "modrinth", - "includeNonRedistributable": true, - "overrides": ["overrides", "modrinth-overrides"] - } - } -} -``` - -**Usage**: -```bash -pakker export --profile curseforge -pakker export --profile modrinth -``` - ---- - -### Example 2: Server Pack with Custom Config - -```json -{ - "name": "Survival Server", - "version": "2.0.0", - "overrides": ["overrides"], - "serverOverrides": ["server-base"], - "exportProfiles": { - "serverpack": { - "includeClientOnly": false, - "serverOverrides": ["server-base", "server-production"] - } - } -} -``` - -**Usage**: -```bash -pakker export --profile serverpack -``` - ---- - -### Example 3: Development vs Production - -```json -{ - "name": "Dev Pack", - "version": "1.0.0-dev", - "overrides": ["overrides"], - "exportProfiles": { - "dev": { - "includeNonRedistributable": true, - "overrides": ["overrides", "dev-config"] - }, - "production": { - "filterPlatform": "curseforge", - "includeNonRedistributable": false, - "overrides": ["overrides", "prod-config"] - } - } -} -``` - -**Usage**: -```bash -pakker export --profile dev # For testing -pakker export --profile production # For release -``` - -## How Profile Configuration Works - -### Priority Order - -1. **Profile-specific settings** from `exportProfiles.` -2. **Profile defaults** (curseforge/modrinth/serverpack) -3. **Global settings** from root `pakku.json` - -### Example Resolution - -Given this configuration: - -```json -{ - "overrides": ["overrides"], - "serverOverrides": ["server-global"], - "exportProfiles": { - "myprofile": { - "overrides": ["custom-overrides"] - } - } -} -``` - -When exporting with `--profile myprofile`: -- `overrides`: Uses `["custom-overrides"]` (from profile) -- `serverOverrides`: Uses `["server-global"]` (from global, no profile override) - -### Filter Execution Order - -Export rules are executed in this order: - -1. **Copy project files** - Download and copy mod files -2. **Filter by platform** - Remove mods not available on target platform -3. **Copy overrides** - Copy override directories -4. **Generate manifest** - Create platform-specific manifest -5. **Filter non-redistributable** - Remove non-redistributable mods (if configured) -6. **Filter client-only** - Remove client-only mods (for server packs) - -## Migration from Pakku - -If you're migrating from Pakku, export profiles work the same way. The configuration format is compatible. - -### Pakku Configuration - -```json -{ - "exportProfiles": { - "curseforge": { - "filterPlatform": "curseforge" - } - } -} -``` - -This works identically in Pakker. - -## Troubleshooting - -### Mods Missing from Export - -**Problem**: Some mods are missing after export. - -**Solution**: Check if `filterPlatform` is excluding them. Use `pakker inspect ` to see platform availability. - ---- - -### Override Files Not Copied - -**Problem**: Override files aren't appearing in the export. - -**Solution**: Verify the override path in your profile config matches the actual directory structure. - ---- - -### Non-Redistributable Mods Included - -**Problem**: Non-redistributable mods are in the export when they shouldn't be. - -**Solution**: Set `includeNonRedistributable: false` in your profile configuration. - -## See Also - -- [Export Command Documentation](./COMMANDS.md#export) -- [Configuration Reference](./CONFIGURATION.md) -- [Project Configuration](./PROJECTS.md) diff --git a/docs/MIGRATION.md b/docs/MIGRATION.md deleted file mode 100644 index 769471b..0000000 --- a/docs/MIGRATION.md +++ /dev/null @@ -1,511 +0,0 @@ -# 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 ` | -| 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! diff --git a/docs/README.md b/docs/README.md index 3d01ae5..af6fe8d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -9,447 +9,8 @@ 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. +Pakker is _greatly_ inspired by [Pakku](https://github.com/juraj-hrivnak/Pakku), +bringing similar functionality with improved performance and additional features +through Rust implementation.