MHW-Mod-Manager/plan.md

# Native Linux Mod Manager for Monster Hunter Wilds

## Context

There is no native Linux mod manager for Monster Hunter Wilds. Fluffy Manager 5000 is the de-facto
standard but is Windows-only, so Linux players run it under a second Wine prefix or hand-copy files
into the game directory. This project builds a native GTK4 desktop app that reproduces Fluffy's
workflow — a checkbox mod list with screenshots, categories, search, conflict detection and archive
import — while handling the things Fluffy does not: Proton/Steam integration, and safe recovery when
a title update shifts the vanilla PAK ceiling.

The project directory is empty apart from an IntelliJ `GENERAL_MODULE` stub (`MHW-Mod-Manager.iml`,
no SDK pinned), so this is greenfield.

### Verified facts this design rests on

Gathered from the live system and from research this session:

| Fact | Source |
|---|---|
| Installed game is **Wilds**, app `2246340`, at `~/.steam/steam/steamapps/common/MonsterHunterWilds` | `appmanifest_2246340.acf` |
| Two parallel PAK chains, both currently ending at **015**: `re_chunk_000.pak.patch_NNN.pak` and `re_chunk_000.pak.sub_000.pak.patch_NNN.pak` | directory listing |
| Higher patch number wins; mods slot **above** the vanilla ceiling, which rises with every title update | community guides |
| Loose mods live in `natives/STM/…`, loaded by REFramework's loose file loader | REFramework docs |
| Loose file loader is toggled by `LooseFileLoader_Enabled` in **`re2_fw_config.txt`** in the game root — the filename keeps its RE2 origin across all RE Engine games — and must be set *before* launch | REFramework issue tracker |
| REFramework = `dinput8.dll` in game root; on Proton it needs `WINEDLLOVERRIDES="dinput8.dll=n,b" %command%` | REFramework docs |
| Lua mods → `reframework/autorun/`, DLL plugins → `reframework/plugins/`, `reframework/data/` holds user settings and must be preserved | cleanup guides |
| No `libraryfolders.vdf` extra libraries, no REFramework, no `natives/` present yet — clean slate | system inspection |

### Decisions taken with the user

- **Target:** Monster Hunter Wilds only (not MH:World).
- **Stack:** Python 3.14 + GTK4/libadwaita via system PyGObject.
- **v1 extras:** load order UI, mod loader setup, profiles, `nxm://` integration.

### Constraint: zero third-party runtime dependencies

Bazzite is an immutable distro, so the app must run without `pip install`. Everything needed is
already present and verified on this machine:

- UI — system PyGObject, `Gtk 4.0` + `Adw 1` (`/usr/lib64/python3.14/site-packages/gi`)
- zip — stdlib `zipfile`; **7z** — `/usr/bin/7z` (26.02); **rar** — `/usr/bin/unrar`
- HTTP — stdlib `urllib.request`; config — stdlib `json` / `configparser`

`pyproject.toml` declares no runtime deps. A venv is only needed for dev tooling, and must be
created with `--system-site-packages` or `gi` disappears.

---

## Architecture

```
src/mhwmm/
├── __main__.py            entry point
├── app.py                 Adw.Application; HANDLES_COMMAND_LINE for nxm:// single-instance forwarding
├── core/                  ← pure logic, no GTK imports, fully unit-testable
│   ├── paths.py           XDG dirs + library layout
│   ├── config.py          settings.json, atomic save
│   ├── steam.py           VDF parser, app discovery, launch-option read/verify
│   ├── modinfo.py         Fluffy-compatible modinfo.ini + screenshot discovery
│   ├── archive.py         format sniffing, extraction, path-traversal rejection
│   ├── layout.py          classify an extracted tree → deployment entries
│   ├── library.py         Mod model; import / scan / rename / delete
│   ├── deploy.py          link engine, manifest, conflicts, transactional apply/rollback
│   ├── paks.py            vanilla baseline, slot allocation, title-update re-slotting
│   ├── profiles.py        named enabled-sets + load order
│   ├── loader.py          REFramework detect/install, re2_fw_config.txt, Proton wiring
│   └── nexus.py           nxm:// parse, Nexus API client, downloads
└── ui/                    window, mod_list, details, setup, conflicts, prefs
```

The `core` / `ui` split is deliberate: every risky behaviour (file deletion, PAK slotting, archive
extraction) lives in `core` with no GTK dependency, so it is testable headlessly.

### On-disk state

```
~/.local/share/mhwilds-mod-manager/
├── mods/<mod-id>/              extracted mod trees (the library)
├── downloads/                  nxm:// downloads
└── state/
    ├── deployed.json           manifest: every path we created in the game dir
    ├── pak-baseline.json       vanilla PAK snapshot (names + size + mtime_ns)
    └── backup/                 pre-existing real files we shadowed
~/.config/mhwilds-mod-manager/
├── settings.json
└── profiles.json
```

---

## Core subsystems

### `layout.py` — classifying a mod

Mods are packaged inconsistently, so the payload root must be discovered rather than assumed. Walk
the extracted tree and emit a list of `(kind, source_abspath, dest_relpath)` entries. A single mod
can produce several kinds at once. Detection, in priority order:

- dir named `natives` (case-insensitive, any depth) → loose assets, payload root is its parent
- dir named `reframework` → Lua/plugin mod, preserving `autorun/` and `plugins/`
- bare `STM/` dir → wrap as `natives/STM`
- `*.pak` at or near root → PAK mod (gets a slot, see below)
- loose `*.lua` at root → `reframework/autorun/`
- loose `*.dll` at root → ambiguous; surface a prompt rather than guessing, since this could be a
  plugin *or* a root-level `dinput8.dll`

### `deploy.py` — the link engine

Deployment is a pure function from (enabled mods, load order) to a desired `dest_relpath →
source_abspath` map, diffed against the last manifest.

- **Later mod in load order wins** a contested path; every contested path is recorded as a conflict
  with its winner and losers, which is what feeds the conflict UI.
- **Link mode** defaults to **symlink** — instant, no disk cost next to a ~100 GB install, works
  across filesystems, and `ls -l` makes managed files self-evident during debugging. Wine resolves
  symlinks transparently on read. Hardlink and copy are available in preferences.
- **Shadowing:** if an unmanaged real file already occupies a destination, move it to
  `state/backup/` and record it; restore on undeploy.
- **Transactional:** build plan → apply → write manifest via temp-file + `os.replace`. Roll back on
  mid-apply failure.

### Safety rules (non-negotiable — this writes into a ~100 GB game install)

1. Never delete anything in the game directory that is not in our manifest **and** whose on-disk
   state still matches what we recorded.
2. Never delete a PAK we did not create.
3. Every destructive operation is preceded by a "Preview changes" plan the user can inspect.
4. `reframework/data/` is never touched — it holds user presets and script settings.

### `paks.py` — surviving title updates

This is the standout feature and the main thing Fluffy handles badly. Leftover mod PAKs numbered
above the vanilla ceiling are the single most common cause of the community's spurious
"`re_chunk_000.pak.patch_NNN.pak` is corrupted" reports.

- Snapshot the vanilla ceiling per chain at setup (currently `015` for both chains) along with each
  vanilla PAK's size and mtime.
- Allocate mod slots from `ceiling + 1` upward, in load order.
- **On every startup**, re-scan. If a PAK appears inside our slot range that we do not own, Steam
  has patched the game: undeploy mod PAKs, re-derive the ceiling, re-slot, redeploy, and tell the
  user plainly ("Game updated — mod PAKs re-slotted to 017+").

Note that loose files and PAKs conflict if they supply the same asset, so the conflict checker spans
both delivery mechanisms rather than treating them separately.

### `steam.py` — library and launch options

A ~40-line text-VDF parser handles `libraryfolders.vdf` and `localconfig.vdf`. Launch options live
at `userdata/<uid>/config/localconfig.vdf` → `…/apps/2246340/LaunchOptions`.

**Steam rewrites `localconfig.vdf` on exit, so writing it while Steam runs silently loses the
change.** The app therefore *reads and verifies* by default, showing the exact required string with
a Copy button. Writing it is an explicit opt-in action, gated on Steam not running, and backs the
file up first.

### `loader.py` — REFramework setup

Status panel with a per-check ✓/✗: `dinput8.dll` present · `LooseFileLoader_Enabled=true` ·
launch-option override present. One-click install fetches the latest `MHWILDS.zip` from the
`praydog/REFramework-nightly` GitHub releases API and extracts `dinput8.dll` to the game root.
`re2_fw_config.txt` is patched key-wise, preserving unrelated settings, and created if absent.

### `nexus.py` — nxm:// handling

- Handler desktop file registers `x-scheme-handler/nxm`; `Gio.ApplicationFlags.HANDLES_COMMAND_LINE`
  forwards the URL to the already-running instance over D-Bus.
- Parse `nxm://monsterhunterwilds/mods/<mod_id>/files/<file_id>?key=…&expires=…`, then
  `GET /v1/games/monsterhunterwilds/mods/{mod}/files/{file}/download_link.json?key=…&expires=…`
  with an `apikey` header. The `key`/`expires` pair is what lets **non-premium** accounts download,
  so it must be passed through rather than dropped.
- Also fetch `/v1/games/monsterhunterwilds/mods/{mod}.json` to prefill name, version, summary and
  thumbnail. Surface the rate-limit response headers.
- API key stored in libsecret when `gi.repository.Secret` is importable, else a `0600` JSON file.

### UI

`Adw.NavigationSplitView`. Sidebar: search, category filter, profile selector, and the mod list —
each row a `Gtk.CheckButton`, name, version, category badge and a conflict-warning icon. Load order
by drag-and-drop with up/down keyboard fallback. Content pane: auto-detected `screenshot.png|jpg`
(Fluffy-compatible), metadata, description, and Files / Conflicts tabs. Header: Import Mod, Deploy,
overflow menu. Archives can be dropped onto the window to import. `Adw.StatusPage` covers first-run
and game-not-found. Toasts report results.

Toggling a checkbox deploys immediately, matching Fluffy; a batched "pending changes" mode is a
preference.

---

## Implementation phases

Each phase ends in something runnable.

1. **Skeleton + game discovery** — `pyproject.toml`, `paths`, `config`, `steam`; window that finds
   the install and shows both PAK chains and the detected ceiling.
2. **Library import** — `archive`, `modinfo`, `layout`, `library`; import archives, list mods with
   screenshots and metadata. No writes to the game dir yet.
3. **Deploy engine** — `deploy` + `paks`; enable/disable, conflict detection, load order,
   preview-changes, undeploy round-trip. The correctness core.
4. **Loader setup** — `loader`; REFramework install, `re2_fw_config.txt`, launch-option verification.
5. **Profiles + polish** — `profiles`, preferences, search/categories, drag reorder, toasts.
6. **Nexus** — `nexus`, desktop files, scheme registration, download queue.

## Verification

Automated (stdlib `unittest`, no GTK needed, runs headless):

- **Round-trip invariant — the key test:** snapshot a synthetic game dir, deploy N mods, undeploy,
  assert the tree is byte-identical including backups restored and empty dirs pruned.
- Zip-slip and absolute-path entries are rejected by `archive`.
- `layout` classification across the packaging shapes listed above.
- Conflict winner follows load order; reordering flips the winner.
- PAK slot allocation, and re-slotting when a synthetic `patch_016` appears from outside.
- VDF parser against the real `libraryfolders.vdf` and `appmanifest_2246340.acf` on this machine.
- `nxm://` URL parsing including `key`/`expires` passthrough.

Manual, against the real install:

1. Launch, confirm it finds `MonsterHunterWilds` and reports ceiling `015` on both chains.
2. Install REFramework via the app; confirm `dinput8.dll` and `LooseFileLoader_Enabled=true`, and
   that it reports the missing `WINEDLLOVERRIDES` launch option with the exact string to copy.
3. Import a real Wilds mod, enable it, and verify the symlinks under `natives/STM/` resolve.
4. Enable two mods touching the same asset; confirm the conflict shows and reordering flips the
   winner.
5. Disable everything and confirm the game directory returns to exactly its pre-mod state — compare
   against a `find`-based snapshot taken before step 3.
6. Launch the game through Steam and confirm the mod loads.

Step 5 is the acceptance gate: the manager must be able to fully undo itself.