From 5a0a5cedeba62862cba1560b6b9d605c78fdf5f2 Mon Sep 17 00:00:00 2001 From: NotAShelf Date: Thu, 29 Jan 2026 21:13:14 +0300 Subject: [PATCH] docs: prepare Pakker documentation Signed-off-by: NotAShelf Change-Id: I03df3787081bde6ebf0366a24320307a6a6a6964 --- docs/COMMANDS.md | 971 ++++++++++++++++++++++++++++++++++++++++ docs/EXPORT_PROFILES.md | 348 ++++++++++++++ docs/MIGRATION.md | 511 +++++++++++++++++++++ docs/README.md | 455 +++++++++++++++++++ 4 files changed, 2285 insertions(+) create mode 100644 docs/COMMANDS.md create mode 100644 docs/EXPORT_PROFILES.md create mode 100644 docs/MIGRATION.md create mode 100644 docs/README.md diff --git a/docs/COMMANDS.md b/docs/COMMANDS.md new file mode 100644 index 0000000..0290e89 --- /dev/null +++ b/docs/COMMANDS.md @@ -0,0 +1,971 @@ +# 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 new file mode 100644 index 0000000..6ecb63d --- /dev/null +++ b/docs/EXPORT_PROFILES.md @@ -0,0 +1,348 @@ +# 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 new file mode 100644 index 0000000..769471b --- /dev/null +++ b/docs/MIGRATION.md @@ -0,0 +1,511 @@ +# 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 new file mode 100644 index 0000000..3d01ae5 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,455 @@ +# 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.