Phase 0.2 landed in link#24: the sidecar gained a four-flag CLI, --print-config,
and config-anchored data paths. Three sections of the installer plan asserted
facts that change as a result, so they are corrected rather than appended to.
- Status table: 0.1 merged (servuo-plugins#7/#8, overlay v0.1.1 released), 0.2 in
review, repo bootstrap merged. 0.3 (bundle CI) is next and now unblocked — both
components it composes exist.
- Phase 0 item 2 gains an "As built" subsection matching item 1's: why four
hand-rolled flags rather than a parsing crate, why --print-config provisions
instead of only reporting, why config_created/token_generated exist, and why no
platform data directories are compiled into the binary.
- §2.3 (working-directory trap): half-closed in the sidecar — a relative
[store].path now anchors to the config file's directory — while the service
definitions still pin both env vars, and why that is not redundant.
- §2.4 (token handoff): the installer reads the handoff block out of one
--print-config call and never parses the log, which is not a contract.
- §5 Phase 2 / Phase 4, §6: the ordering that follows (print-config before service
registration), which doctor rows the CLI answers, that only the host is
substituted into the printed URLs because web.bind is often 0.0.0.0, and that the
printed token must not reach a log or support bundle.
- link/INTEGRATION.md §1: how to read the token back, replacing "the sidecar logs
it" with the supported command and its output.
Co-Authored-By: Claude <noreply@anthropic.com>
Tracks what actually landed while starting the installer plan, and corrects
the parts of the plan that the work proved wrong or stale.
Progress:
A Phase 0 status table at the top, so the plan says where it is rather
than needing a reader to reconstruct it from PR links.
Phase 0 item 1 (§5) now records the release workflow as built, including
its three deviations from link's copy — structural gates instead of build
gates, no bump commit and therefore no push to main, and overlay.toml as
the home for the declared protocol version. Plus the fixed tarball prefix
and why: the installer would otherwise have to parse the version it is
trying to read.
New §7.0 documents the overlay manifest as generated, and states plainly the
two things about it that carry weight: `protocol` is hand-maintained and has
to be (nothing in CI can derive it, which is exactly why §7.1's gate 1 has
something to compare), and `files` is what lets `doctor` distinguish
"operator edited a deployed file" from "the overlay moved on".
Corrections:
§2.6 the plugin's protocol version now has a home (overlay.toml), and
servuo-plugins now has a release workflow.
§7.2 the dispatch step is deliberately deferred to Phase 0 item 3.
§7.4 no longer "open risk" — the v3 cutover merged. The rule it motivated
(never hardcode a protocol version) is restated as permanent rather
than as a workaround for a mid-flight cutover.
§8 open question 4 (branch targeting) resolved: servuo-plugins#6 merged,
main == edge, everything targets main.
Version examples in §3, §5 and §7.1 said uo-link v3.x.y / 3.0.1, conflating
the release version with the protocol version. link is actually at v0.3.0 —
the two are independent, and the bundle names release versions, so an example
implying they track each other is actively misleading. Now uses the real
values (link 0.3.0, overlay 0.1.0, 30 overlay files).
Co-Authored-By: Claude <noreply@anthropic.com>
The installer needs CI that reacts when a component publishes a release. Adds
that as section 7, folded into version tracking because the bundle IS the compat
matrix -- which closes the "where does the compat matrix live" gap section 7
previously left open.
- 7.1 Bundle manifest: CI publishes an exact, protocol-checked combination of
component versions; the installer resolves against it at run time and
--bundle <tag> pins one. A link release regenerates JSON and leaves the
installer binary untouched, so operators don't re-download the installer for a
sidecar patch and the repo doesn't accumulate releases with identical code.
Two compose-time gates: sidecar PROTOCOL_VERSION must equal the overlay
manifest's declared version, and every asset's SHA256 must match.
- 7.2 Triggers: each component's release job POSTs to the installer's
workflow-dispatch endpoint (link's release.yml already declares
workflow_dispatch and already holds a write:repository token), plus a nightly
cron so a missed dispatch self-heals. repository_dispatch avoided -- support
is uncertain on this Gitea version.
- 7.3 Stale overlay: dispatch, don't wait. Components self-release on merge to
their own main, so the release normally already exists. If main is ahead with
*releasable* commits (docs:/chore: correctly cut nothing), fire that repo's
workflow, compose from what exists now, warn loudly, and let the nightly fold
in the result. Dispatching another repo's workflow is fine -- it still runs
its own gates -- but polling it is not, since Gitea's dispatch endpoint
returns no run handle.
Bundle CI becomes a Phase 0 deliverable, since Phase 1 resolves what to install
from the bundle. `update` now moves between checked combinations rather than two
independently-latest artifacts.
Co-Authored-By: Claude <noreply@anthropic.com>
Design of record for a deployment tool that takes a stock ServUO install and
configures it for Runic Gateway. Supersedes the informal overview it grew from,
which described a ServUO integration that does not match how servuo-plugins
actually ships.
Corrections that change the design:
- There is no RunicGateway.dll and no Plugins/ dir. The plugin ships as C#
source compiled by ServUO at boot, so the step is a hash-compare sync of
overlay/ -- but a successful copy does not mean a working bridge, because
ScriptCompiler.Compile() ignores dotnet build's exit code and reloads the
stale Scripts.dll.
- Stock ServUO files ARE modified, by three diffs in patches/. Made an opt-in,
skippable tier: git apply against a hand-modified shard will fail, and the
EventSink.cs patch needs a full core solution rebuild.
- Config paths collided with what the sidecar actually reads. Split ownership:
sidecar.toml stays the sidecar's schema, install.json is the installer's.
Service definitions pin UOLINK_CONFIG and UOLINK_DB_PATH, since the sidecar
writes relative to CWD and would land in VirtualStore under Program Files.
- The token handoff was missing entirely -- the largest "installed it and
nothing happened" failure mode.
- deploy.ps1 cannot be the cross-platform deployer; it stays the developer tool.
Decisions: public audience, unsigned binaries anchored on SHA256SUMS, Rust,
release-tarball plugin distribution, printed token handoff, new installer repo,
warn-and-skip on non-57.4 ServUO, and an uninstall that never edits the shard
tree -- it prints the files to delete and the hunks to revert.
Phases 0-5, with Phase 0 (a release workflow for servuo-plugins, which has
none today) gating everything else. Two open questions remain in section 8.
Co-Authored-By: Claude <noreply@anthropic.com>
