initial commit

plan/04-packwiz.md

@@ -0,0 +1,48 @@
+# packwiz — modpack source of truth + offline mod mirror
+
+## Summary
+
+`packwiz` (installed at `~/go/bin/packwiz`) authors the modpack. The `./pack`
+directory is the **single source of truth** for mods, consumed by both:
+- the **server** (itzg `PACKWIZ_URL`), and
+- **clients** (Fjord launcher imports the pack / packwiz-installer).
+
+Caddy serves `./pack` at `packwiz.ulicraft.local`. packwiz only emits **metadata**
+(`pack.toml`, `index.toml`, `mods/*.pw.toml`); the `.pw.toml` files reference
+Modrinth/CF **CDN URLs**, so true offline requires mirroring jars locally.
+
+## Behaviors confirmed
+
+- **Prune**: packwiz-installer tracks a manifest and **removes** client mods no
+  longer in the index on re-run. (Server side via itzg likewise re-syncs.)
+- **Download source**: jars come from CDN URLs in `.pw.toml`, NOT the pack host —
+  unless URLs are rewritten to the local mirror.
+- **itzg side filtering**: itzg downloads **server-side mods only**. Client-only
+  mods MUST be tagged `side = "client"` (not `both`) or the server may pull and
+  crash on them.
+
+## Offline mod mirror (the key work)
+
+`tooling/mirror-mods.sh` (see `08-tooling.md`):
+1. Parse each `mods/*.pw.toml`, download the jar into `./mirror/mods/`.
+2. Copy jars into `./pack/mods-files/` (served at `packwiz.ulicraft.local/...`).
+3. Rewrite each `[download] url` to point at `http://packwiz.ulicraft.local/...`.
+4. `packwiz refresh` to recompute hashes/index.
+
+Result: server + clients install mods entirely from the LAN. No CDN at party time.
+
+## NeoForge pinning
+
+`pack.toml` pins MC `1.21.1` + NeoForge `21.1.x`. Verify exact NeoForge build
+against projects.neoforged.net before locking.
+
+## Tasks
+
+- [ ] `packwiz init` → `./pack` (MC 1.21.1, modloader neoforge, pinned version)
+- [ ] Curate mod shortlist (perf/tech/magic/storage/QoL/worldgen/map/voice)
+- [ ] Tag client-only mods `side = "client"`
+- [ ] `packwiz refresh`; verify `index.toml` committed (clients fetch it)
+- [ ] Write `tooling/mirror-mods.sh` (vendor jars + rewrite URLs + refresh)
+- [ ] Point server `PACKWIZ_URL=http://packwiz.ulicraft.local/pack.toml`
+- [ ] `.gitignore` the vendored `./mirror/` jars; keep `./pack/*.toml` tracked
+- [ ] Test offline install end-to-end (cut internet, install on a fresh client)