Mod Manager for Weft

.github/workflows/ci.yml

@@ -0,0 +1,108 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [master]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  rust:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-22.04, windows-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+
+      # Windows and macOS need nothing beyond the toolchain.
+      - name: Install Tauri system packages
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf
+
+      - uses: dtolnay/rust-toolchain@b725eda525362e7cf34af9a7243cac1e3f01a7ec # stable
+        with:
+          toolchain: stable
+          components: rustfmt, clippy
+
+      - uses: Swatinem/rust-cache@d1527c8f67ef9af357290475d4af4b0fab8f12e0 # v2.9.3
+        with:
+          workspaces: src-tauri
+
+      # tauri::generate_context! wants the built frontend to exist.
+      - name: Placeholder frontend
+        shell: bash
+        run: mkdir -p dist && touch dist/index.html
+
+      - name: Format
+        working-directory: src-tauri
+        run: cargo fmt --check
+
+      - name: Clippy
+        working-directory: src-tauri
+        run: cargo clippy --all-targets -- -D warnings
+
+      # Includes bindings_are_current (fails if src/mods/bindings is out of date) and the shared
+      # rule cases in src/dev/fixtures/rules.json (rules_fixture.rs).
+      - name: Test
+        working-directory: src-tauri
+        run: cargo test
+
+  frontend:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: lts/*
+          cache: npm
+
+      - run: npm ci
+
+      # On its own, so a missing translation or a sentence assembled from pieces is labelled as
+      # such, not as a failed build (the build runs it again).
+      - name: Check translations
+        run: npm run check:i18n
+
+      # check:i18n, tsc and vite build
+      - name: Build
+        run: npm run build
+
+      - name: Unit tests
+        run: npm test
+
+  ui:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: lts/*
+          cache: npm
+
+      - run: npm ci
+
+      - name: Install Chromium
+        run: npx playwright install --with-deps chromium
+
+      # Every mock scenario in all four languages at 960×565, plus the safety and keyboard flows.
+      - name: UI tests
+        run: npm run test:ui
+
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        if: failure()
+        with:
+          name: playwright-traces
+          path: test-results/
+          retention-days: 7

.gitignore

@@ -34,4 +34,6 @@ desktop.ini
 # Logs
 logs
 *.log
-*.bak
+*.bak
+test-results/
+playwright-report/

README.md

@@ -23,10 +23,14 @@ The builds aren't code-signed yet:
 
 **Versions** -> **Install** -> back to **Home** -> **Play**. Delete a version with a double click on **Delete** (blocked while the game is running).
 
+**Mods** -> pick the game version -> **Browse** -> **Install**. Each game version keeps its own mods. Mods are native programs that run with your privileges.
+
+Besides the signed [Weft mod index](https://github.com/Weft-Rust/weft-mods-index), you can add GitHub repos under **Sources** or install a zip **From file**. Builds pinned in the index are Reviewed; others are Unreviewed or Unverified. See the [mod manager design](docs/mod-manager/PROPOSAL.md).
+
 ## Data
 
-- **Game data** (worlds, settings): `%APPDATA%\Weft` - the launcher never reads or writes it.
-- **Launcher data**: `%APPDATA%\dev.weft.launcher` - `versions/`, `logs/<tag>.log`, `cache/`, `downloads/`.
+- **Game data** (worlds, settings): `%APPDATA%\Weft` - the launcher never writes it, and only lists its `mods` folder to warn about mods it can't manage.
+- **Launcher data**: `%APPDATA%\dev.weft.launcher` - `versions/`, `logs/<tag>.log`, `cache/`, `downloads/`, and for mods `mods/store/` (downloads by SHA-256) and `profiles/<tag>/` (each version's mod set).
 
 Newer versions may write saves older ones can't open - back up `saves` before downgrading.
 
@@ -40,7 +44,24 @@ npm run tauri dev     # dev mode (plain `cargo run` won't work - UI is served by
 npm run tauri build   # installer
 ```
 
-Before a PR: `cargo fmt --check && cargo clippy` in `src-tauri`, and `npm run build`. UI strings go through `src/i18n` - add keys to all four languages (en, pt-BR, es, ru).
+Before a PR:
+
+- `cargo fmt --check && cargo clippy --all-targets -- -D warnings && cargo test` in `src-tauri`.
+- `npm run build`. It runs `npm run check:i18n` first.
+- UI strings go through `src/i18n`: add every key to all four languages (en, pt-BR, es, ru), with the plural forms each needs. A key built from a prefix goes in the checker's `DYNAMIC` list.
+- `npm test`: the unit tests (vitest).
+- `npm run test:ui`: the UI tests (Playwright, `e2e/`). Run `npx playwright install chromium` once first, or point `PW_CHROMIUM` at an installed Chromium. Each run starts its own mock server on a free port; `PW_PORT=<port>` fixes the port, and `PW_REUSE=1` with it tests a server you already started.
+- After changing an IPC type or command, regenerate `src/mods/bindings` with `cd src-tauri && cargo test export_bindings -- --ignored`. CI fails until it is committed.
+
+CI (`.github/workflows/ci.yml`) runs all of these on every pull request.
+
+### UI without Tauri
+
+```bash
+npm run dev:mock      # http://localhost:1420/?scenario=mods
+```
+
+Runs the UI in a browser against a fake backend that follows the real backend's rules. Scenarios and URL flags are in [docs/dev-mock.md](docs/dev-mock.md).
 
 ## Releasing
 

docs/dev-mock.md

@@ -0,0 +1,60 @@
+# Mock backend
+
+`npm run dev:mock` serves the UI at http://localhost:1420/?scenario=mods against a fake backend
+(`src/dev/mockBackend.ts`). The mock never ships in a production build.
+
+Its rules are ported from the Rust backend (`src/dev/mockRules.ts`), and both are checked against
+the shared cases in `src/dev/fixtures/` (`npm test`, `cargo test`). File system and network failures
+are only simulated as the error code they end in; Rust tests them against real files and a local
+HTTP server.
+
+Pick a state with `?scenario=` and adjust it with flags, which combine:
+`?scenario=mods&index=cached&revoked=cogwork&slow=1`. Flags in the URL override the ones a scenario
+sets. Both lists come from `src/dev/scenarios.ts`; `npm test` fails if this page misses one.
+
+## Scenarios
+
+| Scenario | What it shows | Flags it sets |
+|---|---|---|
+| `mods` | The default: a mod built for another version (with a fitting update), an update, an off prerelease, a source, a local file and a file in the player's own folder. | — |
+| `empty` | The newest version has no mods; the older one has mods to copy. | — |
+| `fresh` | No game version installed. | — |
+| `offline` | No network: the cached index and a source's cached mods. | `index=cached` `source=offline` |
+| `crash` | The game stops while loading Structures, which has an update. | `crash=loadFailed` |
+| `knownfile` | From file picks a catalogued build (Cogwork 0.2.0). | `file=known` |
+| `revoked` | The installed Cogwork build is revoked. | `revoked=cogwork` |
+| `ratelimited` | GitHub rate-limits the source; its last mods are shown. | `source=ratelimited` |
+| `indexdown` | No index on the server (404) and none saved: no Reviewed mods. | `index=unavailable` |
+| `stale` | The index signature is over 30 days old. | `index=stale` |
+| `invalid` | The new index's signature doesn't verify; the last good one is shown. | `index=invalid` |
+| `rollback` | The new index is older than one already accepted; the last good one is shown. | `index=rollback` |
+| `missingdep` | Hearth needs Cogwork (off); Lanterns needs Glowmoss (not installed); Railways needs Signals (no build). | — |
+| `lateblock` | Play itself finds Cogwork revoked; Hearth, which needs it, blocks the start. | `prelaunch=revoke` |
+| `long` | Very long mod names, ids and repos. | `long=1` |
+| `shadowed` | Cogwork is revoked and the player's own folder has a copy: Play is blocked until that file goes. | `revoked=cogwork` `shadow=cogwork` |
+| `slowrefresh` | A refresh revokes Cogwork at once while the source lantern-dev/lanterns takes three seconds. | `slowsource=lantern-dev/lanterns` `refreshrevokes=cogwork` |
+| `chain` | Chimneys → Hearth → Cogwork, both installed and off; Junctions → Railways → Signals, which has no build. | `chain=1` |
+
+## Flags
+
+| Flag | Values | Effect |
+|---|---|---|
+| `index` | `fresh`, `stale`, `cached`, `unavailable`, `unreachable`, `invalid`, `rollback`, `unsaved` | State of the signed index. `unavailable`: none saved, server answers 404. `unreachable`: none saved, no network. `unsaved`: fresh but not saved (`cacheError`). |
+| `source` | `ok`, `notfound`, `ratelimited`, `offline` | State of the added GitHub source. |
+| `nomods` | `noReleases`, `noModFiles`, `unreadable`, `noDigest`, `disagrees`, `invalid` | The source has no usable mods, for this reason. |
+| `race` | `stale`, `error` | The first refresh answers last, with an older catalogue or an error. The page keeps the newer answer. |
+| `slowsource` | `<repo>` | That source takes three seconds; the index is shown before it answers. |
+| `refreshrevokes` | `<mod id>` | The next refresh's index revokes that mod's installed builds, once. |
+| `revoked` | `<mod id>` | Revokes that mod's installed builds. |
+| `abi` | `error` | The version's ABI can't be found. |
+| `fail` | `install`, `network`, `toolarge`, `dep`, `meanwhile`, `catalog`, `sources` | Comma-separated. `install`: the hash check fails. `network`: the download breaks off midway. `toolarge`: the zip is refused before downloading. `dep`: a dependency's download fails. `meanwhile`: a newer Glowmoss appears after the first plan, so that plan is refused and planned again. `catalog`: the catalogue fails to load. `sources`: the sources list is damaged. |
+| `file` | `unverified`, `known`, `notamod`, `revoked`, `revokedlate`, `wrongplatform` | What From file picks; `revokedlate` is revoked during the install. |
+| `shadow` | `<mod id>` | The player's own folder has a copy of that mod. Tests delete it with `window.mockPlayer.deleteFile(name)`. |
+| `revocations` | `messy` | Uppercase hashes, no reason or time, and one entry that isn't a hash: only that one is dropped. |
+| `chain` | `1` | Adds Chimneys and Junctions. |
+| `crash` | `wrongVersion`, `loadFailed`, `notAMod`, `wrongName`, `missingDep`, `initPanicked`, `exit` | The game stops with this failure; `exit` names no mod. |
+| `prelaunch` | `revoke`, `storemissing` | Play finds Cogwork revoked, or the store's copy of Structures gone (`ModStoreMissing`). |
+| `long` | `1` | Adds very long names, ids and repos. |
+| `slow` | `1` | Everything takes four times as long. |
+| `fast` | `1` | Everything takes a quarter as long. |
+| `profile` | `fail`, `failafterplay` | Reading a version's set fails: always, or only the first read after Play. |

docs/mod-manager/AUTHORING.md

@@ -0,0 +1,83 @@
+# Publishing a Weft mod
+
+For mod authors: how to ship a mod the launcher can install, first from your own GitHub repo
+(players see it as **Unreviewed**), then in the signed Weft mod index (**Reviewed**). The exact
+rules are in [INDEX_FORMAT.md](INDEX_FORMAT.md); this page is the path through them.
+
+## 1. The zip
+
+One `<id>.zip` per build, where `<id>` is your mod id: `[a-z0-9_]{1,64}`, not `base`, and equal to
+your crate name (the engine refuses a mismatch). Inside, nothing but:
+
+```text
+<id>.dll          Windows
+lib<id>.so        Linux
+lib<id>.dylib     macOS
+assets/…          textures, lang files, and assets/textures/gui/icon.png
+```
+
+No other files at the top, no folders above these, no `..`, absolute paths or links. Ship the
+libraries for the platforms you build, and list them in `platforms`. Limits: 512 MB, 20,000 entries
+and 1 GB unpacked ([all limits](INDEX_FORMAT.md#size-limits)).
+
+## 2. The release
+
+- **Tag** each build `<id>-v<version>`, for example `lanterns-v1.2.0`, to keep several mods in one
+  repo apart. Any tag works if it is 1–100 letters, digits, `.`, `_` or `-` and doesn't start with
+  `.`.
+- **Version** is semver (`1.2.0`, `1.3.0-beta.1`). A prerelease on GitHub is a prerelease in the
+  launcher too.
+- Make the release (not a draft) with `<id>.zip` and `<id>.mod.json` as its assets. GitHub records
+  a SHA-256 digest for each asset; a zip without one is skipped.
+- A new build is a new version and a new release, every time. If two releases share a version or
+  a zip hash, the older one's copy is skipped.
+
+## 3. `<id>.mod.json`
+
+Describe the build exactly as GitHub has it: the example and every rule are in
+[INDEX_FORMAT, `<id>.mod.json`](INDEX_FORMAT.md#idmodjson-for-unreviewed-sources), and
+[`schema/mod.schema.json`](schema/mod.schema.json) checks the shape. The fields that trip people:
+
+- `asset.url` is the zip's `browser_download_url`, character for character, and `asset.size` and
+  `asset.sha256` are the zip's.
+- `weft.abi` is the FNV-1a-64 hash of the raw bytes of `crates/abi/src/lib.rs` at the Weft commit
+  you built against, as 16 lowercase hex digits. Players get your build only on Weft versions with
+  the same ABI.
+- `deps` lists every mod yours needs to load, by id.
+- `provenance` from your own repo is shown as your claim, never as a record: leave it `null`, or
+  describe your attestation (step 4).
+
+Then add your repo in the launcher (Mods → Sources).
+
+### When a source shows no mods
+
+The Sources dialog shows one reason: that of the release that passed the most checks. The checks run in this order:
+
+| Reason | Means |
+| --- | --- |
+| `noReleases` | The repo has no published releases. |
+| `noModFiles` | No release has an `<id>.zip` together with its `<id>.mod.json`. |
+| `unreadable` | An `<id>.mod.json` couldn't be read as JSON, or isn't a description. |
+| `noDigest` | GitHub has no SHA-256 digest for the zip, so nothing could be checked. |
+| `disagrees` | The description doesn't match GitHub's record of the release: tag, repo, asset name, URL, size or hash, or the id isn't the zip's. |
+| `invalid` | It matches, but breaks a [rule every entry follows](INDEX_FORMAT.md#rules-the-launcher-enforces). |
+
+## 4. Into the signed index
+
+A build in the index is **Reviewed**: someone read it, and the index signature pins its bytes, so a
+changed release can't change what players install.
+
+1. Build in GitHub Actions and attest the zip with
+   [`actions/attest-build-provenance`](https://github.com/actions/attest-build-provenance), from a
+   workflow in `.github/workflows/`.
+2. Open a pull request on `Weft-Rust/weft-mods-index` that adds the version to your mod's entry
+   (the mod too, the first time): the same fields as your `<id>.mod.json`, with `source.commit`
+   the full commit the release was built from.
+3. A reviewer reads the source at that commit, runs `gh attestation verify` on the zip, and adds
+   `reviewed` and `provenance`. The launcher shows a build record only when that record is complete
+   ([INDEX_FORMAT, Provenance](INDEX_FORMAT.md#provenance)).
+4. Once merged, CI signs the index and Pages serves it; players get it on their next refresh.
+
+If a build turns out to be harmful or broken, ask for its `sha256` to be revoked, with a reason.
+Launchers learn of it when they next read the index, and turn the build off the next time its
+version's mods are read or before Play. A running game keeps it until it stops.