From c79374ff06bfc1b6b57ff90395375d4e90c6b8a4 Mon Sep 17 00:00:00 2001 From: wtclaude Date: Wed, 5 Aug 2026 05:52:27 -0500 Subject: [PATCH] docs(readme): describe the tool that exists, not Phase 1 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PLAN.md §5.4. The status section still announced Phase 1 as built and Phase 2 as next, four phases later -- it is the first thing a visitor to this repo reads, and it has been wrong since Phase 2 merged. - The phase table now shows 1-4 built on `edge` and 5 in progress, and the opening says what the binary actually does. - "What the cutover is waiting on" is stated, because "nothing is released yet" invites the question: Phase 5, and the Windows SCM half never having been executed anywhere. - "Planned commands" is now "Commands". All four are implemented. - RUNICGATEWAY_STATE_DIR was described as relocating install.json. Since Phase 2 it relocates everything the installer writes, including the sidecar binary, and suppresses service registration -- an out-of-date description of where a tool writes is worse than none. - A design-constraint bullet for the backup behaviour Phase 5 adds. Co-Authored-By: Claude --- README.md | 50 ++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 38 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 89c280c..37ea320 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,13 @@ never restarts the shard. ## Status -**Phase 1 (installer core) is built, on the `edge` branch. Nothing is released yet.** +**Phases 1 to 4 are built, on the `edge` branch. Nothing is released yet.** + +The binary does everything +[`installer/INSTALL.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/installer/INSTALL.md) +describes: bundle resolution, ServUO detection and validation, the overlay sync, +the opt-in patch tier, `install.json`, the uo-link sidecar and its service, the +token handoff, and `doctor` / `update` / `uninstall`. The design of record is [`installer/PLAN.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/installer/PLAN.md) @@ -42,17 +48,29 @@ sidecar + overlay combination, recomposed on every component release and nightly |---|---| | 0 — prerequisites in the other repos | ✅ merged | | 1 — installer core: bundle resolution, ServUO detection, overlay sync, `install.json` | ✅ on `edge` | -| 2 — uo-link install + service registration | next | -| 3 — the opt-in stock-file patch tier | | -| 4 — `doctor`, `update`, `uninstall` | | +| 2 — uo-link install + service registration | ✅ on `edge` | +| 3 — the opt-in stock-file patch tier | ✅ on `edge` | +| 4 — `doctor`, `update`, `uninstall` | ✅ on `edge` | +| 5 — packaging polish: Linux `aarch64`, backup before overwrite | in progress | **Why `edge`:** `release.yml` publishes an installer binary on every push to -`main`, and a binary that deploys the overlay but cannot yet install the sidecar -is not something to hand an operator. Phases 1 and 2 land on `edge`; the -`edge → main` cutover cuts the first release. PRs into `edge` run the same gates -as PRs into `main`. +`main`, so nothing lands there until the whole tool is worth handing to an +operator. The `edge → main` cutover cuts the first release. PRs into `edge` run +the same gates as PRs into `main`. -Until then, the way to install is by hand — +**What the cutover is waiting on**, per PLAN.md §5: + +1. **Phase 5**, packaging polish — deliberately *before* the first release rather + than after it, because it changes the release layout, and shipping first would + mean a first release immediately superseded by the next. There is no `.deb` + and no MSI: both would give the sidecar binary, its service unit and its + service account a second owner beside this tool. +2. **The Windows SCM half verified on a real host.** `sc create`, the virtual + service account, the failure actions and the token-file ACL have never been + executed anywhere. Running the *systemd* half for real is what turned up a bug + no unit test had, so this is not a formality. + +Until the cutover, the way to install is by hand — [INSTALL.md Appendix A](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/installer/INSTALL.md#appendix-a--installing-by-hand) is the same deployment done with `curl`, `tar` and `systemctl`. @@ -66,7 +84,7 @@ is the same deployment done with `curl`, `tar` and `systemctl`. | [RunicGateway/website](https://gitea.whitlocktech.com/RunicGateway/website) | The public site and admin panel. The installer never contacts it — it prints values for Admin → Shard. | | [RunicGateway/docs](https://gitea.whitlocktech.com/RunicGateway/docs) | All project documentation, including the installer plan. | -## Planned commands +## Commands | Command | What it does | |---|---| @@ -90,6 +108,10 @@ is the same deployment done with `curl`, `tar` and `systemctl`. - **A successful copy is not a working bridge.** ServUO ignores the script build's exit code and silently reloads the previous `Scripts.dll`, so diagnostics verify post-boot state rather than trusting a clean boot. +- **What a run overwrites is copied first.** Every `.cs` file the overlay owns is + replaced unconditionally, so an operator's edit to one is saved under + `backups//` before it goes. Restoring is theirs to do — this tool + will not put an old file back over a newer release. - **The audience is public** — any ServUO operator, not only shards we run. ## Build & run @@ -103,8 +125,12 @@ cargo run -- install --servuo /path/to/ServUO --verify # dry run: writes nothi cargo fmt --check && cargo clippy --all-targets -- -D warnings && cargo test ``` -`RUNICGATEWAY_STATE_DIR` relocates `install.json` (normally `/etc/runicgateway` -or `%ProgramData%\RunicGateway`), which is how a run is tested without root. +`RUNICGATEWAY_STATE_DIR` relocates **everything the installer writes** — state, +data, and the sidecar binary (normally `/etc/runicgateway`, `/var/lib/runicgateway` +and `/usr/bin`, or `%ProgramData%\RunicGateway` and `%ProgramFiles%\RunicGateway`). +It also suppresses service registration, since there is no such thing as a +relocated systemd unit or Windows service. That is how a full run is tested +without root. Two layout notes that look odd until you know why: -- 2.49.1