docs(installer): record Phase 1 as built #90

wtclaude · 2026-08-04T20:00:00Z

wtclaude commented

2026-08-04 20:00:00 +00:00

What & why

Docs half of installer#4 (feat(installer): implement Phase 1 — the installer core).

PLAN.md moves from "Phase 0 complete, no installer code exists yet" to "Phase 1 built, on edge", and the Phase 1 section gains an As built block in the same shape as the Phase 0 entries. It records the decisions the design had left open, each with the reason it went that way:

why the crate lands on edge rather than main — release.yml publishes on every push to main, and its crate guard was written to arm "the moment Phase 1 lands the crate", which would have released a binary that deploys the overlay but cannot install the sidecar;
why the library target is not named after the binary — Windows' UAC installer detection refuses to launch an unsigned executable whose name contains install (os error 740), and Cargo names test harnesses after their target, so cargo test was unrunnable on Windows;
the dependency set and why each choice follows from the MinGW cross-build;
path-based rather than name-based shard-running detection — deploy.ps1's process-name match is Windows-only reasoning, and on Linux would report "not running" for a live shard;
reading ServUO's version from Server/AssemblyInfo.cs, with unknown treated as not supported;
the two rules the live smoke run corrected: install.json recording a state rather than the run's verb (or an unchanged re-run rewrites it), and the Bridge.cfg keep comparing against the last hash deployed rather than the last hash seen (or a kept file is overwritten on the very next run);
what was verified on a real 57.4 tree and in a scratch tree.

INSTALL.md gets the same status note plus one troubleshooting row: Windows elevates the binary on launch because its file name contains install. That is expected — it needs Administrator anyway — and running from an already-elevated shell avoids the prompt.

No contract changes: every command, flag and path in INSTALL.md is unchanged, since the guide was written as the specification Phase 1 builds to.

How it was tested

Prose only. Cross-checked against the code as merged in installer#4 — the "as built" claims (flag surface, record fields, keep rule, detection order, verification steps) were each read back off the implementation, and the verification list is the set of runs actually performed on this machine.

Checklist

I have read CONTRIBUTING.md.
The change builds and existing tests/checks pass locally.
I have added or updated tests/docs where it makes sense.
My commits are reasonably scoped with clear messages.

AI-assisted contributions (required)

AI tools were used. Tool(s): Claude Code. I have reviewed and understand every change, and take responsibility for it. AI-authored commits are marked with a Co-Authored-By trailer.

License

I agree that my contribution is licensed under this project's license (GNU GPL v3.0 or later), and I have the right to contribute it.

## What & why Docs half of [installer#4](https://gitea.whitlocktech.com/RunicGateway/installer/pulls/4) (`feat(installer): implement Phase 1 — the installer core`). **PLAN.md** moves from "Phase 0 complete, no installer code exists yet" to "Phase 1 built, on `edge`", and the Phase 1 section gains an **As built** block in the same shape as the Phase 0 entries. It records the decisions the design had left open, each with the reason it went that way: - **why the crate lands on `edge` rather than `main`** — `release.yml` publishes on every push to `main`, and its crate guard was written to arm "the moment Phase 1 lands the crate", which would have released a binary that deploys the overlay but cannot install the sidecar; - **why the library target is not named after the binary** — Windows' UAC installer detection refuses to launch an unsigned executable whose name contains `install` (`os error 740`), and Cargo names test harnesses after their target, so `cargo test` was unrunnable on Windows; - the dependency set and why each choice follows from the MinGW cross-build; - **path-based rather than name-based shard-running detection** — `deploy.ps1`'s process-name match is Windows-only reasoning, and on Linux would report "not running" for a live shard; - reading ServUO's version from `Server/AssemblyInfo.cs`, with `unknown` treated as *not* supported; - the two rules the live smoke run corrected: `install.json` recording a **state** rather than the run's verb (or an unchanged re-run rewrites it), and the `Bridge.cfg` keep comparing against the last hash **deployed** rather than the last hash **seen** (or a kept file is overwritten on the very next run); - what was verified on a real 57.4 tree and in a scratch tree. **INSTALL.md** gets the same status note plus one troubleshooting row: Windows elevates the binary on launch because its file name contains `install`. That is expected — it needs Administrator anyway — and running from an already-elevated shell avoids the prompt. No contract changes: every command, flag and path in INSTALL.md is unchanged, since the guide was written as the specification Phase 1 builds to. ## How it was tested Prose only. Cross-checked against the code as merged in installer#4 — the "as built" claims (flag surface, record fields, keep rule, detection order, verification steps) were each read back off the implementation, and the verification list is the set of runs actually performed on this machine. ## Checklist - [x] I have read [CONTRIBUTING.md](CONTRIBUTING.md). - [x] The change builds and existing tests/checks pass locally. - [x] I have added or updated tests/docs where it makes sense. - [x] My commits are reasonably scoped with clear messages. ## AI-assisted contributions (required) - [x] AI tools were used. Tool(s): `Claude Code`. I have reviewed and understand every change, and take responsibility for it. AI-authored commits are marked with a `Co-Authored-By` trailer. ## License - [x] I agree that my contribution is licensed under this project's license (**GNU GPL v3.0 or later**), and I have the right to contribute it.

wtclaude added 1 commit 2026-08-04 20:00:02 +00:00

docs(installer): record Phase 1 as built 4bdc764742

PLAN.md moves from "Phase 0 complete, no code exists" to "Phase 1 built, on
edge", and the Phase 1 section gains an "As built" block in the same shape as
the Phase 0 entries — covering the decisions that were not already settled by
the design: why the crate lands on `edge` instead of `main`, why the library
target is not named after the binary (Windows UAC installer detection makes
`cargo test` unrunnable under that name), the dependency choices that follow
from the MinGW cross-build, path-based rather than name-based shard-running
detection, reading ServUO's version from Server/AssemblyInfo.cs, and the two
rules the smoke test corrected — install.json recording a state rather than the
run's verb, and the Bridge.cfg keep comparing against the last hash deployed
rather than the last hash seen.

INSTALL.md gains the same status note and one troubleshooting row: Windows
elevates the binary on launch because its file name contains "install", which
is expected and needs no action beyond running from an elevated shell.

Co-Authored-By: Claude <noreply@anthropic.com>

wtclaude referenced this pull request from RunicGateway/installer

2026-08-04 20:00:35 +00:00

feat(installer): implement Phase 1 — the installer core #4

whitlocktech merged commit ce02abbc11 into main

2026-08-04 20:00:59 +00:00

whitlocktech deleted branch feat/installer-phase-1

2026-08-04 20:01:00 +00:00

whitlocktech referenced this issue from a commit

2026-08-04 20:01:01 +00:00

Merge pull request 'docs(installer): record Phase 1 as built' (#90) from feat/installer-phase-1 into main

Sign in to join this conversation.