134 Commits

Author	SHA1	Message	Date
wtclaude	732927a6bb	fix(modules): three defects a real install exposed (phase 4, slice 1) ... Standing the slice-2 screen up against a live server and installing the published module-uo v0.3.0 through it found three things, none of which any unit test in this repo could have caught. Two of them are older than this phase. 1. The boot refresh nulled every install's provenance -------------------------------------------------------- `installed_modules.source` and `.sha256` exist so the admin panel can say where a module came from. They never survived a restart. `lifecycle.boot()` re-records every scanned module with no source and no sha256 -- correctly, because a scan finds a directory and never where it came from -- and `upsert` assigned both columns unconditionally. So an install's provenance lasted exactly until the restart that install asked for, and the screen then described a module installed from a URL as "placed on the volume by hand". Verified live: install, restart, provenance gone. Nothing could have caught it before now. Phase 4 wrote the first non-null value these columns had ever had, so lifecycle.js's comment asserting that "recordInstalled leaves what it is not given" described an intention rather than the statement below it -- and modules.model.test.js's fake reproduced the defect faithfully, assigning unconditionally just like the SQL. Fixed with COALESCE(VALUES(col), col): a value overwrites, a NULL leaves what is there. The fake now matches, and two tests pin both directions -- a boot refresh must not wipe it, and a re-install from a new URL must still replace it, or the column would become write-once and an upgrade would for ever show where the first version came from. 2. The restart killed the server on Windows instead of stopping it ------------------------------------------------------------------ The route called `process.kill(process.pid, 'SIGTERM')` to reach server.js's graceful-shutdown handler. That works on Linux. **Windows has no POSIX signals, and Node documents SIGTERM there as unconditional termination of the target process** -- so on a Windows host the restart killed the server outright: no module onShutdown, no listener close, no pool close, no log flush. Observed exactly that: the process was gone and the shutdown handler had logged nothing at all. `process.on('SIGTERM', ...)` is an ordinary EventEmitter listener, so `process.emit('SIGTERM')` reaches the same handler on every platform without involving the OS. One shutdown path, still; it just gets there by an event. Deployment is Linux containers and would never have shown this. Development is not, and neither is the smoke that found it. The test was worse than useless: it stubbed `process.kill` and asserted it had been called with SIGTERM, which is precisely the call whose MEANING differs by platform. It now waits for the SIGTERM EVENT -- what server.js is actually subscribed to -- so a pass here means the handler would run. 3. `present()` did not publish the running version -------------------------------------------------- An upgrade writes new files and a new row while the old code stays loaded, so the row's version is a promise about the next boot rather than a description of this one. Adds `liveVersion` from the loader beside `liveState`, so the screen can tell the two apart instead of reporting the new version as running. 723 server tests (+2), manifest and OpenAPI both unchanged. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-12 03:48:27 -05:00
wtclaude	b30e82cde2	feat(modules): install, uninstall, purge and restart (phase 4, slice 1) ... The consumer half of a release module-uo's CI has been publishing since phase 3 closed. Before this, core had the installed_modules provenance columns and no code that could ever fill them: nothing fetched, verified, unpacked, removed or purged anything, and there was no admin route at all. Adds modules/archive.js, modules/install.js, schema.runPurge(), lifecycle.stop(), loader.stopHook(), and /api/v1/admin/modules with eight routes. 797 server tests (+76), manifest 158 -> 166 + 2 internal, OpenAPI gains 8 operations and loses nothing. Reject, never sanitise ---------------------- The download is the easy part: an https-only allowlist re-checked on every redirect hop, a declared sha256 compared against the bytes that arrived, and a byte cap. Unpacking is where the archive chooses the filenames, and core writes into a directory bind-mounted from the host, so an escape is not confined to the container. archive.js inspects the whole archive before a byte is unpacked and refuses absolute and drive-absolute paths, `..` segments, NUL bytes, backslashes, anything that is not a regular file or a directory, more than one top-level entry, and anything over the entry or byte caps. Refusing symlinks and hardlinks outright is what keeps this off the majority of node-tar's published advisories rather than depending on the library to contain them. That two-pass shape is load-bearing, and it was measured rather than assumed: extracting an archive whose fourth member escapes upward throws under node-tar 7.5.22 -- and leaves the first three members on disk. The loader scans that directory at require time on the next boot, so a half-unpacked module is a module. Everything therefore happens in a scratch directory that is removed on any failure, and the move into place is the last step. `tar` is pinned to ^7.5.22 rather than the ^6 that installs by default: 6.x is flagged critical, and reading the advisory list is what the file's header now says out loud -- almost all of it is hardlink or symlink traversal and PAX header interpretation differentials, which is exactly this feature's threat model. Two things the plan had wrong ----------------------------- The bundle's top-level directory is `module-uo-<version>`, not the module id -- so "the top-level name must equal the id" was checked against nothing real. The extractor strips that level instead, because its name belongs to whoever published the bundle and the directory it lands in is core's. What is checked instead is the unpacked module.json: a manifest promising `uo` and delivering something else is refused rather than installed under the name it promised. And purge cannot be a follow-up action (decision 5): purge.sql lives inside the directory uninstall deletes. It is offered in the uninstall flow and as a standalone action on a still-installed module, and the standalone one refuses unless the module is already disabled -- dropping tables under something that is still serving leaves it answering out of a world that no longer exists. Disable now means stopped ------------------------- lifecycle.stop() dispatches that one module's onShutdown before flipping the guard, so a module an operator switches off actually releases its sockets and closes its streams instead of merely becoming unreachable. The hook runs first and the state moves after it, because while onShutdown runs the module is still `started` and that is the only state in which its routes and the world it is tearing down agree. A hook that throws does not stop the disable -- the opposite of the boot path's rule, and deliberately. Enable is not its mirror and there is no start(id) beside it. There is no onBoot re-dispatch and the hooks were never promised re-entrant, so enable moves the row and the restart route starts it. A test pins that enable does not touch the loader, because "fixing" it is a one-line change that would put a module with closed sockets back on the nav. Restart raises SIGTERM against its own process rather than calling the shutdown path directly, so server.js's handler stays the one graceful-shutdown path and this route cannot drift from it. The allowlist bootstraps from MODULE_SOURCE_HOSTS into a settings row and is admin-managed after that (decision 6); seedDefault is INSERT IGNORE, so changing the variable on an existing deployment is a no-op by design. An empty list forbids every install rather than allowing every host -- the safe direction for a value someone might blank by accident. Verified against the real v0.3.0 release ---------------------------------------- Not a fixture: fetched the published install manifest over the real Gitea host and its redirect chain, verified the sha256, inspected and unpacked the 252,517-byte artifact to 82 files, and then booted core against the result -- the module registered its five mounts, seven streams and eight capabilities and resolved its client chunk, with no scratch directory left behind. Two defects this slice's own tooling caught, both of which had already been written down as classes: - the controller destructured runPurge at require time, capturing the function rather than the module, which made the one dependency whose ORDER matters the one that could not be substituted; - two swagger annotations carried an apostrophe inside a quoted string, dropped silently by swagger-autogen before slice 5 taught it to fail loudly. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-12 03:09:45 -05:00
wtclaude	adff20be7b	feat(modules): merge module OpenAPI fragments into /api/docs.json (phase 3, slice 5) ... Core's half of the slice that closes phase 3. Two things: the request-time fragment merge core has owed since phase 1, and the last of core's UO copy. **The merge (MODULE_API.md §6.1a).** `swagger-output.json` is core's own routes and cannot be anything else — it is generated on a developer's machine and committed, so it must come out the same regardless of what they had checked out, and a module arrives on a volume long after the image was built. Module routes therefore reach the document at request time, from the `swagger-fragment.json` each module ships: `swagger/docsSpec.js` merges the fragments of STARTED modules over the committed spec, cached on a new loader state version and rebuilt when a module's state moves. Until now neither half existed. `swagger/mergeSpec.js` named the request-time caller in its header and that caller was never written, so the 72 routes module-uo serves were in no OpenAPI spec at all — core's standing rule ("never ship a route that isn't in the spec") broken by the extraction rather than by a route. Core wins every key collision, `swagger-output.json` is never mutated (it is a require()d JSON module — one in-place merge would be permanent AND cumulative), and a fragment that is missing or unreadable costs that module its paths and nothing else. The Swagger UI is now built per request for the same reason the JSON is: bound once at require time it would show core's routes for the life of the process while /api/docs.json showed the merged set. **The last of core's UO copy** (slice 4 deferred it; §5.2's check reads code, not prose, so none of this was caught): - 31 UO schemas and 4 UO tags in `swagger/swagger.js`, describing routes core has not served since slice 1 — 578 lines. They moved to module-uo, namespaced `Uo…`, and arrive back through the merge on an instance that installs it. - `info.description` said "a private Ultima Online shard". - README.md's 48 UO mentions, including the architecture diagram and the whole `## Shard integration (uo-link)` section, now `## Modules`. - `TOWNCRIER_DURATION_SEC` and `UOLINK_*` in the two `.env.example`s: read by the module, not by core, and documented in the module's README instead. **Two dropped annotations, and the reason nobody knew.** swagger-autogen reports an annotation it cannot parse and then prints Success in green, having skipped it. `npm run swagger` now captures its diagnostics and fails — which immediately found `POST /api/v1/admin/invites` and `POST /api/v1/auth/invite/:token/accept` documented with an EMPTY request body, both since the day they were written. Fixing the tag list also cleared five tags used by routes but never declared (`Admin · Email`, `Admin · Invites`, `Admin · Moderation`, `Admin · Pages`, `Auth · Me`) — the same defect class, in the other direction. - 646 server tests (+9), 157 client tests unchanged - routes.manifest.json unchanged (158 public + 2 internal); check:modules clean - swagger-output.json: 128 paths, 69 schemas, 0 orphan tags, 0 orphan schemas - verified against a real boot with module-uo installed: 197 merged paths (128 core + 69 module), all four module tags, 31 Uo schemas, no dangling $refs, /api/docs renders the module's operations with zero console errors Refs: docs/website/MODULE_API.md §2.8, §6.1a; MODULE_SYSTEM.md §2.7.1 Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-11 22:57:37 -05:00
wtclaude	0c4eacfa4a	refactor(modules)!: de-UO core's copy, and enforce it (phase 3, slice 4) ... Phase 3's acceptance criterion 1, made real. Three things, one review: **The dead bindings.** `client/src/api/client.js` still carried ~190 lines of UO namespaces — `shard`, `atlas`, the two SSE URLs, `admin.shard/shardOps/atlas/ userShard`, the uo-link and town-crier calls, `player.shard` — with zero core consumers since slice 3 deleted the views. module-uo vendors its own bindings. The five assertions core's `apiClient.test.js` made about those URLs moved with them (Module-uo#5); the encoding test that used `governorHistory` now uses a core route. **The copy.** Core is the platform, not one game's site, so its words are game-neutral now: `About`, `Screenshots`, `Website`'s cards, `Status` (which was never about a game server at all — it reports site mode), `Wiki`, `SiteFooter`, the default hero, `brand.js`'s tagline and description, the seeded wiki categories, and two user-visible NavEditor strings that named a module's admin screen by its proper name. Which game an instance is for is the operator's to say — BRAND_* vars, the hero editor, CMS pages — and every real instance already does: `.env.uomysticmoon.example` sets both brand strings explicitly, so nothing live changes wording. Wiki page SLUGS are untouched: `seedDefault*` only inserts what is absent, so renaming one adds a duplicate page to every install. Also gone: an orphan comment block in `schema.sql` describing the spawn-atlas tables slice 1 took away, and the two settings rows core seeded for a module (`game_account_signup`, `uo_link_protocol_3_migrated`). The second was a live defect — see Module-uo#5, which takes ownership of both and repairs the one-shot migration core's ordering had disabled. **The check.** `scripts/checkModuleIdentifiers.js` + `npm run check:modules`, first step of the server-tests job because it needs no dependencies. It reads CODE, not prose — file names, import specifiers, route path literals, declared identifiers and property names — per §5.2, so core's English may still say "shard" where saying it is worth more than the word costs. Two things it gets right only because getting them wrong was tried first: it matches WHOLE WORDS (a substring pass flags `defaultImage`, which contains "ultIma", four times in this repo), and it strips comments and string bodies in one character walk (a comment contains quotes, a string contains `//`) — the `checkImports.js` lesson. It has its own 17-test suite, because a boundary check that silently stops checking is worse than none. The three §6.5 grandfathering allowlists are exempt by name, and an exemption that stops matching fails the build rather than lingering. BREAKING CHANGE: core no longer seeds `game_account_signup` or `uo_link_protocol_3_migrated`; module-uo's schema fragment does. An install running core without module-uo keeps whatever rows it already has and gains no new ones — nothing in core reads either key. Deferred to slice 5, deliberately: README.md's 48 UO mentions, including a `## Shard integration (uo-link)` section and the architecture diagram. That is documentation, which §5.2 does not cover, and it belongs with the phase-closing docs pass rather than half-done here. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-11 21:41:18 -05:00
wtclaude	5bdb6a7e10	fix(modules): guard the portal's nav icon, resolve MODULES_DIR absolutely ... Both found by the §7.7 browser smoke, running the slice-3 pair together, and neither is visible to any test in either repo. `PlayerPortalLayout` rendered `<n.icon />` unguarded while `AdminLayout` guarded its equivalent. `icon` is optional in the nav contract, and every core row in that sidebar has always had one — so the difference cost nothing until a module registered a row without, and then it was not a missing glyph, it was React error #130 and a blank player portal. Guarded now, like its neighbour. `MODULES_DIR` is resolved absolute. `resolveClient` checks containment by comparing an absolute `path.resolve(dir, entry)` against the module directory, so a RELATIVE `MODULES_DIR` — which is what §7.7's own recipe produces when run from `server/` — failed every module with "client.entry escapes the module directory". A perfectly-placed entry, and a message pointing at the module. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-11 18:54:31 -05:00
wtclaude	f7d27f7a06	refactor(client): delete the UO client half (phase 3, slice 3) ... 35 files and 5,332 lines out — twelve public pages, seven admin views, two player views, eight components, the two `data/` leaves and the three `lib/` ones, plus the two tests that came with them. §2.7.1's estimate of 51 files / ~3,700 lines was measured differently and is corrected in the docs PR. The seams core keeps, each smaller than what it replaced: Nine rows leave the public header and six leave the admin sidebar, and both lists are now free of `feature` gates and of `IconShard`. `moduleTitle` already handled a module page's heading, so the six TITLES entries and the `/admin/characters` branch of `sectionTitle` simply go. `/player` had `PlayerCharacters` as its index — a UO page — and rather than name a replacement or invent a landing screen it now resolves to the first row of the portal nav this viewer can reach (`firstDestinationFor`, beside `allowedPathsFor` and reading the BASE nav for the same reason: an override is presentation and where everybody lands is behaviour). With the module installed that is still Characters, so a player's first screen after signing in does not change. Deliberately generic and deliberately not in the portal layout — the admin index is the same question with a hardcoded answer, and if the two logged-in areas ever become one this is what serves both. `game_account_signup` goes with the rest of core's UO prose: the mode list, the derived public flag, the validation and a Site Settings field whose help text named Bridge.cfg. The row itself is untouched and module-uo reads it through ctx.settings — the data stays, the semantics move. KNOWN BREAK, accepted by the org lead: the shipped Android app reads `gameAccountSignup` off `/public/settings` (PublicDto.kt:80). The field has a `= false` default so nothing crashes; the app silently stops offering game-account creation until it reads the module's `/public/shard/features` instead. Out of scope here, recorded in the Android plan, and it lands well before this workstream's cutover reaches `main`. 620 server + 161 client tests. Manifest 158 public + 2 internal, unchanged; routes.guards unchanged. The OpenAPI spec loses exactly one property, and only because it was hand-written in swagger.js — regeneration alone would have left the spec documenting a field core no longer returns. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-11 18:39:55 -05:00
wtclaude	5b5006c365	feat(modules): a third slot, nav icons, and api.BASE (phase 3, slice 3) ... The three things core owes the client half before it can leave, all additive, all MODULE_API 1.2.0 → 1.3.0. `player.invite.accepted` is the third extension slot. Core's invite page owned a UO game-account step — it read a `gameAccountSignup` flag out of core's own settings and posted to a shard route — and an invite is a core concept that staff receive too, so the page stays and its optional next step becomes a slot. Named for the place, like the other two. Whether there is a step at all is the filling module's call, made from data core does not have; core keeps the shell, the skip control and the destination. `icon` on a nav item, because without it the six extracted UO rows would have been the only text-only entries in a sidebar where every other row has a glyph. Core supplies no fallback — an invented one is core making a presentation choice for content it knows nothing about. `icon` was already among the fields an override may not touch, so the concept predates a module being able to send one. `api.BASE` was in §3.5 from the first draft and never actually published. `request` is fetch-only, so an EventSource builds its own URL, and the shard's live feed is two of them; the alternative is a module hardcoding `/api/v1`, which asserts something about core that core has not promised. `AcceptInvite` is the one legitimate reader of `extensionFor` outside Slot.jsx: the answer decides a NAVIGATION, not a decoration. Decoration goes inside `<Slot wrap>`, which is why `hasExtension` stayed deleted. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-11 18:39:36 -05:00
wtclaude	1d1350558b	feat(modules): client extension slots (phase 3, slice 2) ... The client twin of the server's declareSlot/registerExtension, and the same rule in both halves: core declares a slot, only core declares one, and at most one module fills it. Core renders <Slot name> and gets nothing back when the slot is unfilled, so an instance with no module installed renders exactly what it rendered before -- the same untouched-path guarantee withModuleNav makes. A slot is named for a PLACE, never for a meaning. Core supplies the position and the styling; the label, the target, the data and whether anything renders at all are the module's. The moment core types a slot by its content it has re-acquired the game semantics phase 3 exists to remove. This is the one place the client registry is not fail-open. An unknown slot, a non-component and a second fill all throw, matching checkExtensionShape server-side, because a dropped nav row costs a link the viewer can reach another way while a silently dropped extension is invisible to everyone including its author. A throw is always a programming error and never a race: core declares in its own bundle and every module chunk is a deferred script injected after it. Reading stays fail-safe -- undeclared and unfilled both read null -- and a filling component renders inside an error boundary. That asymmetry is where the client differs from the server: a module route that throws costs the module's own page, but an extension throws inside CORE's, and the whole reason core keeps ownership of that page is that it stays usable. Core decorates a slot through <Slot wrap>, not by asking whether it is filled. The obvious alternative is right about the unfilled case and wrong about the failed one -- the extension is filled, so the separator renders, and then the component throws into the boundary and leaves the separator behind on its own. wrap puts core's decoration inside the boundary where it shares the extension's fate. Found in a browser, with the footer's separator, which is the only place either could have been found. MODULE_API_VERSION 1.1.0 -> 1.2.0, both halves: the two state ONE version. Contract: docs/website/MODULE_API.md 3.7. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-11 16:45:08 -05:00
wtclaude	f5e6025dcc	test: re-point core's suite at what core still owns ... 25 of 82 test files left with the module. Three that core keeps needed splitting rather than moving, and the split is the boundary in each case. announceJobs.test.js keeps the announce PIPELINE -- the shared backoff schedule, the parent-status rollup, core's Discord leg -- and loses the town-crier text building and classification, which are a module's leg. pushDispatch.test.js keeps the SSRF guard and publish() delivering a content-free tickle, and loses mapShardEvent and the shard fan-out, which are a module's catalog. playerRouteAccess.test.js is the one worth explaining. It guards a real past bug -- an admin 403'd off their own characters -- and it did so through /player/shard/accounts, which is now module-owned. The guarantee it protects is CORE's, though: /player/* is role-agnostic self-service, staff are a superset of players. So it stays here and asserts that through /player/appeals, a core route with the same gate. Moving it would have left core with no test of its own tier rule, which is precisely what regressed once before. The remaining updates are core's own tests catching up: ctx has four more members, registerCore now registers only what core owns (one stream, one leg, no filled slot), and the extension-slot test asks for the DECLARED slot's router rather than the filled one, since core declares it and a module fills it. The gated-surface floor drops from >100 to >50 -- it is there so a filter matching nothing fails loudly, not to track core's exact route count. 616 core tests and 160 client tests pass; the module's own suite is 351. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-11 12:08:26 -05:00
wtclaude	39d731d87a	refactor(modules)!: move the UO server half out to module-uo ... 40 files, ~9,674 lines, 27 of 68 tables. Core no longer contains anything that knows what a shard is. BREAKING for a deployment only in the sense that the module must be installed for these URLs to answer -- no URL moved. routes.manifest.json goes 228 -> 158 public routes here, and the 70 that left reappear byte-identical when the module is loaded: verified by generating the manifest against core+module and diffing it against the pre-extraction file. Zero missing, zero added, and routes.guards identical across all 228, so no auth gate moved either. The five tier mounts are gone from public/admin/player index.js and are still served: the loader mounts them onto the same routers after every core mount. That ordering is also what keeps the prefixes unclaimable -- the collision check asks the live router what core owns, so a second module claiming /shard is rejected against the mounts actually present rather than against a list. server.js loses its eight UO call sites to the module's onBoot/onShutdown. schema.sql loses its 27 shard_*/uo_link_* statements; the two that FK into users are why the fragment replays AFTER core's schema, and no core table ever referenced a module table, which is what makes core still able to boot alone. Verified against a running server with the module installed: it loads, mounts five prefixes, replays 35 statements, warms up and reaches `started`; public shard and atlas routes answer 200 with real data (800 creatures, 6,455 spawners), admin and player answer 401 from core's tier gates, and the extension slot answers at /admin/users/:id/shard/*. Core's own SPA renders the shard and atlas pages unchanged against the module-served API, with no console errors and no CSP reports. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-11 12:08:03 -05:00
wtclaude	f50541f374	feat(modules): ctx additions and the post-hook registry (API 1.1.0) ... Everything the extraction needed from core that ctx did not already offer. Additions only, so minor. ctx.activity.log, because an admin action a module performs has to land in core's one audit log or the trail has a hole exactly where a module operates the game -- a module keeping its own log would be a second place to look, which in practice means a place nobody looks. Write-only; reading the log is the admin panel's job and it spans every actor. ctx.users.getById, one function for one caller: the admin.users.detail slot router needs the user its prefix names. ctx.site.baseUrl, because a module has to build absolute links and §2.7 forbids it reading core's APP_BASE_URL -- a getter, not a captured string, so it cannot go stale against the env. ctx.middleware.rateLimit is core's makeLimiter, plus accountChangeLimiter handed over whole. The split is deliberate: a module states its own window and cap because it knows what its endpoints cost, and takes the plumbing from core so there is one express-rate-limit in the process and one place a breach is logged. accountChangeLimiter is shared policy -- core's /auth/me and /player/account sit behind the same counter -- so a module's account-change route has to land IN it rather than beside it. marketLimiter was UO policy living in core's file and leaves with the route it guards. registerPostHook is the fourth registry, and the last thing binding core to the module. Core's post controller called newsGump.syncPost directly: core's CMS naming a UO file. It now publishes what it already knows and a subscriber decides what to do with it. Not folded into registerAnnounceLeg, which fires on the same transition, because a leg is a one-shot DELIVERY with retry and classification while a post hook maintains idempotent STATE, runs on delete as well as save, and refreshes silently on an edit. Also fixes a real loader defect the extraction exposed: schema table names were matched against the RAW file, so a fragment whose header says "every CREATE TABLE carries IF NOT EXISTS" was rejected for a prefix violation on a table called `carries`. module-uo's fragment hit exactly that. Both scans now read split statements, which strip comments -- the same class of bug as a boundary check failing on its own documentation. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-11 12:07:45 -05:00
wtclaude	a103e0ce10	feat(modules): mount the modules directory as a volume (phase 2, PR 9) ... Closes Phase 2. Modules live on a mount, never in the image — that is what lets an operator add one to a pull-only deployment without building anything. `./modules` is a bind mount rather than a named volume: placing a module directory by hand is a supported install (MODULE_SYSTEM.md §2.5), and that has to be doable from the host rather than through `docker cp`. Read-write, because the admin panel's install/uninstall unpacks and removes directories there. The directory is tracked via its README so it exists in the checkout with the operator's own ownership — Docker recreates a missing bind-mount source as root:root, which the container user could not then write. `.dockerignore` excludes it so a module in the builder's working tree can never ship inside an image. Also corrects the route-manifest generator's list of filesystem-conditional mounts, which never picked up `/modules` when PR 7 added it. Comment only; the generator filters on an allowlist, so its behaviour was already right. Verified against a real container, not just a parsed compose file: image carries an empty node-owned /app/modules despite a module in the build context; a module on the bind mount loads, mounts, replays and reaches `started`; `/api/v1/public/modules` lists it; the chunk serves from the entry's directory only (server source and module.json 404) with `no-cache`; the injected tag follows core's bundle; and in Chrome the page renders on first paint inside core's PublicLayout with its nav row interleaved into core's public nav, under enforced `script-src 'self'` with zero CSP reports and no console errors. Removing the directory by hand reconciles the row to `startup_failed`/`require` and leaves core healthy with no injection. 933 server + 160 client tests pass, manifest unchanged at 230 routes, swagger regenerates byte-identical. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-11 00:48:48 -05:00
wtclaude	e0927bc255	feat(modules): the client registry, window.__rg and the chunk's script injection ... Phase 2, PR 7 of docs/website/MODULE_SYSTEM.md 2.7 — the client half's delivery. A module's prebuilt chunk is served, injected, handed core's React and its UI kit, and its routes are rendered by App.jsx. The registry is empty on a bare core, so nothing an operator can see changes. Client: - modules/registry.js — registerRoutes/registerNav/registerFeatureProvider, with the URL namespace written by core, never by the module - modules/shared.js — window.__rg: React, react-dom/client, react-router-dom, react/jsx-runtime, the registry, the seven-member UI kit and the request primitive, frozen - App.jsx reads routesFor for all three areas; nav consumption is PR 8 - main.jsx publishes the global, then mounts on DOMContentLoaded Server: - the loader validates client.entry and publishes clientChunks() and clientEntryUrls(); an entry in the module root is rejected, because the directory it sits in is what gets served - app.js mounts each chunk at /modules/<id>/ behind the module's state guard with no-cache; anything else under /modules is a 404, not the SPA shell - htmlShell injects the tag before </body>, so core's bundle runs first wherever a bundler puts it Found by loading a real chunk in a browser, and fixed here: core mounted before any module chunk had evaluated, because document.readyState during a deferred script is 'interactive', not 'loading'. Every test passed against that build. The smoke is written down in MODULE_API.md 7.7. 933 server tests (+23), 123 client tests (+14). routes.manifest.json unchanged at 230 routes; the OpenAPI spec regenerates byte-identical. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-10 22:54:16 -05:00
wtclaude	291c30f6ff	feat(modules): publish the installed-module list at /api/v1/public/modules ... Phase 2, PR 6 of docs/website/MODULE_SYSTEM.md 2.7 — the first module-system URL a client can see. The SPA and the Android app feature-detect against the capabilities a module declares; the shape is settled in MODULE_API.md 2.9. Four decisions, and what is absent from the payload is most of the design: * started modules only. A module that is disabled or failed to load is ABSENT, exactly as 4.4 already leaves its routes and its nav absent, so a client renders a site without that capability rather than advertising one that 503s. * no state, failure_stage or failure_reason. Where a module broke belongs to the admin Modules screen, and the reason is an exception string from inside core — not anonymous-visitor business. * no client chunk URL. htmlShell injects a script tag per started module (3.1.3), so the browser is handed the tag rather than a URL to fetch. This endpoint feature-detects; it does not load. MODULE_SYSTEM 2.6 step 4 is amended to match (API 6.7). * no siteMode gate and no database — the same class as /public/status and /public/version, so a client can still feature-detect during maintenance. It is a capability router of its own rather than a fifth singleton in site.router.js, and that is load-bearing: the loader's prefix-collision probe reads the live tier stack and skips root-mounted layers, because a use('/', ...) matches every path. A route inside the root-mounted site router would be invisible to it — mounting use('/modules', ...) is what makes "no module may claim /modules" a rule the loader enforces. 910 tests pass (+9, every one on the boundary — what must NOT appear). routes.manifest.json gains exactly the one route and routes.guards.json records it with an empty gates list, which is itself the assertion that it is ungated. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-10 22:03:22 -05:00
wtclaude	32ed8e4411	fix(test): stop the suite reaching a real database, and make it exit ... `npm test` never terminated. Twenty-two test files omitted the two lines that point the pool at a dead port, so utils/db.js -- which builds its mariadb pool at require time and calls dotenv.config() itself -- picked up server/.env and opened five live connections to the developer's MariaDB. The tests still passed, because they stub their models and never issue a query; the only symptoms were a process that never exited and five connections held for as long as it lived. Thirty stranded workers is 150 connections, which is the whole server's limit, and that is the "too many connections" this workspace has hit before. The convention was right and only ever as good as the next test file's memory of it, so it moves into the harness: test/_setup.js is loaded with --require by the npm script, ahead of the test file it hosts, which is the only moment early enough to matter. It pins the dead port -- dotenv does not overwrite an existing variable, so an explicit DB_PORT= still wins for anyone who wants a live database -- and closes the pool after the file's tests, so the process exits at once instead of waiting out the driver's connect retries. The per-file preambles stay: they keep `node --test test/one.test.js` safe on its own. Two supporting fixes: - db.close() is idempotent. pool.end() throws "pool is already closed" on a second call, and closing twice is now normal rather than exceptional -- the harness closes the pool for every file on top of the suites that close it themselves, and a SIGINT followed by a SIGTERM already reached the shutdown handler twice. - test/_helper.js's close() destroys open connections. server.close() only stops accepting and waits for existing connections to end, and node's global fetch keeps its sockets alive, so the listener outlived the test that created it -- invisible until now, because the pool was holding the process open anyway. announceJobs.test.js alone: 120s+ hang -> 0.35s. The whole suite now finishes in ~75s where it previously did not finish at all: 901 tests, 901 pass, verified three times on CI's exact platform (node:20 on Linux, via Docker). Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-10 21:27:47 -05:00
wtclaude	21196466ed	feat(modules): boot/shutdown hook dispatch and the installed_modules reconcile ... Phase 2, PR 5 of docs/website/MODULE_SYSTEM.md 2.7. api.onBoot/api.onShutdown stop throwing, server.js gains one call on each side, and the 2.4 state machine finally runs against real outcomes -- which is what makes 4.5's `disabled` 404 leg reachable for the first time. Dispatch and reconcile live in src/modules/lifecycle.js rather than in the loader, for the reason the schema replay does: routeManifest.js and swagger.js both require app.js against a dead pool, so the loader may not reach the database. The two halves meet at exactly one function, loader.setState(), so the in-memory record the dispatch guard reads and the row the admin panel reads are moved together and cannot disagree. Four decisions, all recorded in MODULE_API.md 2.5 and 4.4: - The loader classifies its failures by 4.3 step, so failure_stage says where a module broke instead of being a column nothing ever filled. The four steps readManifest covers in one pass label themselves; the rest are inferred from how far load() had got, and an unlabelled throw is recorded against the step that was running rather than guessed at. - A row whose directory is gone is marked startup_failed rather than left claiming `enabled` -- the boot reset has just moved it there, and a row claiming to be enabled for a module that is not on the volume is the one state that is simply untrue. An uninstall leaves `disabled`, which the reset never touches, so this catches only a hand-deleted directory. - Core's eight UO boot call sites stay in server.js until Phase 3. Unlike a registered announce leg, a boot call site already has somewhere to live, so moving it now would be extraction done early in a phase whose exit criterion is that nothing changes. - onBoot gets no timeout. Shutdown races a SIGKILL and boot does not, and a slow onBoot delaying the listener is the contract's promise to a module that must warm up before it serves. The operator's switch wins over everything: a disabled module is guarded, not booted, and does not have its failure re-recorded, or an outcome would silently switch it back on next boot. Every database write in the reconcile is individually caught -- a row that will not update is worse reporting, never a failed boot. 900 tests pass (17 new). routes.manifest.json is unchanged at 229 routes and the OpenAPI spec regenerates byte-identical. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-10 20:32:00 -05:00
wtclaude	97f19b4221	docs(modules): note that registerExtension's spec-file argument is core-only ... Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-10 17:53:59 -05:00
wtclaude	6195c76d61	feat(modules): the three de-entanglement registries, with core as the registrant ... Phase 2 PR 4 of docs/website/MODULE_SYSTEM.md §2.7. Adds server/src/modules/registries.js and moves core's own notification streams, announce leg and users-detail routes behind it, so the three seams §1.8 and §1.9 named are exercised on every boot before any module depends on them. Registering is validate-then-commit per registrant: the loader stages what a module claims and the second pass commits it, so a module that throws halfway through register() — or fails checkDeclared after it — leaves nothing behind. That is the registry-side twin of PR 2's second-pass mount rule. Four decisions, all the recommended option: - announce legs became a child table. `announce_job_legs` replaces the towncrier_*/discord_* column groups, so the leg set is data: core registers `discord`, module-uo will register `towncrier`, and a module cannot ALTER a core table to add its own. Backfill is guarded on information_schema (a SELECT of a dropped column is a parse error, not a runtime one) and the columns go with DROP COLUMN IF EXISTS. Verified against the live dev DB: three legacy jobs migrated faithfully, three replays, no duplicates. - `mapEvent` dropped from registerNotificationStreams. §1.8 already inverts the push path so a module owns fromShardEvent and calls core's publish() with a stream id it resolved; a second mapping mechanism was a leftover. The public safety filter, the kinds it reads and the streams it protects now live in one file and move together. - core registers through the same staging area a module uses, via an explicit registries.registerCore() in app.js before modules.load(). - core's six /admin/users/:id/shard/* paths now go through the `admin.users.detail` slot, and getUser moved back to admin.controller.js. Found on the way, and the reason two build tools changed: - scripts/routeManifest.js could not decode a parameterised mount. Its unwinder expected `(?:([^\/]+?))`; express 4.22 emits `(?:\/([^/]+?))` with the separator inside the group. The branch had never run. It threw rather than guessing, which is what it is for. - swagger-autogen cannot follow a route into an extension slot — the slot's router is created by declareSlot() and filled later, so there is no literal mount for a static parse. Regenerating deleted 407 lines and printed `Swagger-autogen: Success`, the spike's exact failure (MODULE_API.md §7.4). swagger/slotSpecs.js generates a fragment per filled slot and re-roots it at the prefix the router actually hangs at in the live app — read from the express stack via routeManifest's own mountPath, so the manifest and the spec cannot disagree. swagger/mergeSpec.js is the merge helper core owes for module fragments anyway (§6.1a), proved here against core's own slot first. 884 tests pass (856 before). routes.manifest.json is unchanged at 229 routes. The OpenAPI spec diff is two lines of intent: the retry endpoint's summary, and its `leg` no longer being a fixed enum. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-10 17:47:59 -05:00
wtclaude	2892d01b24	feat(modules): replay module schema fragments after core's ... Phase 2, PR 3 of docs/website/MODULE_SYSTEM.md 2.7. ensureSchema() now replays every installed module's schema fragment immediately after core's schema.sql, per MODULE_API.md 2.6. The work splits across two files on the line of whether a database is needed to know the answer. loader.js VALIDATES a fragment at load time, before anything is mounted, because every rule 2.6 states about the SQL is knowable by reading it; a module that breaks one never mounts (4.4, left column). modules/schema.js EXECUTES it, so the only failures there are the ones the database alone could report, and those are post-mount and answer 503 (4.4, right column). Validation is a leading-verb allowlist -- CREATE, ALTER, INSERT, UPDATE, the four core's own schema.sql uses -- rather than the DROP denylist 2.6 words it as. A fragment is replayed on every boot, so TRUNCATE and DELETE would empty a table at each restart and RENAME would fail at the second one; a denylist only ever bans what somebody thought of. A CREATE TABLE missing IF NOT EXISTS is rejected for the same reason: it works once and fails every boot after, which presents to an operator as a module that broke on restart. The splitter moves to utils/sqlStatements.js so core's schema and a fragment are split by literally the same code, which is what 2.6 promises. It is its own file rather than an export of utils/db.js because the loader validates fragments at require time and must not drag the mariadb pool into app.js's require chain. The replay sits outside ensureSchema's wait-for-the-database retry loop: a fragment that throws is one module's failure, not a signal the database is coming up, and retrying core's whole schema nine more times over one module's bad SQL would turn a 503'd module into a two-minute boot. Found while wiring it: db/seed.js calls ensureSchema() standalone for `npm run seed`, without ever requiring app.js, so the loader has not scanned and fragments()'s 7.6 throw would have broken seeding outright. The replay asks isLoaded() and logs the skip rather than swallowing it -- a booting server quietly getting no module tables is the thing 7.6 exists to prevent. Verification: - 856 server tests pass, 14 new. moduleSchema.test.js injects the query fn, so the exact statements and their order are asserted with the pool at a dead port like every other suite. - routes.manifest.json and routes.guards.json diffs are zero lines, 229 routes -- the phase 2 exit criterion. swagger-output.json regenerates byte-identical. - Run for real against the local MariaDB with two fixture modules: a good fragment created its table, applied its ALTER and seeded its row; a fragment whose SQL passes validation but the server rejects (`id NOTATYPE`) marked only that module startup_failed, its route answering 503 while the other answered 200; a second ensureSchema on the same database was a clean no-op. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-10 16:56:58 -05:00
wtclaude	ec1ca7e794	feat(modules): the filesystem module loader ... Phase 2 PR 2 of docs/website/MODULE_SYSTEM.md 2.7. Adds server/src/modules/{loader,semver,version}.js: the synchronous scan of MODULES_DIR, manifest validation, prefix and table-name collision rejection, per-module try/catch and the mount into the three tier routers behind the MODULE_API.md 4.5 dispatch guard. Two decisions the contract left open, both now written up there: - The load trigger is one explicit modules.load(tierRouters) call in app.js, not a lazy scan (API 7.6). Accessors throw until it has run, because "no modules installed" is a real answer a caller must not be handed by accident. - Whether core owns a prefix is asked of the live tier routers via express's own layer.match(), skipping root-mounted layers, rather than a hardcoded table -- the spike's was already stale when written (API 4.3). Mounting is a second pass after every module is validated. Doing it inside the scan loop makes the first module's layers indistinguishable from core's, so the second module claiming a taken prefix is told it collided with core and the module-versus-module check is unreachable. registerExtension/NotificationStreams/AnnounceLeg and onBoot/onShutdown throw "not available until phase 2 PR 4/5" rather than no-op; an accepting stub would let a module believe it had registered something. No schema replay, no boot dispatch, no installed_modules reconcile -- those are PRs 3 and 5, and until PR 5 a record's state is in memory only. No module ships on the volume, so nothing an operator or client can see changes: 842 tests pass, routes.manifest.json is unchanged at 229 routes and swagger-output.json regenerates byte-identical. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-10 14:35:27 -05:00
wtclaude	3add0063bf	feat(modules): installed_modules and the module state machine ... Phase 2 PR 1 of the module system (docs/website/MODULE_SYSTEM.md 2.7). The table and the state machine only: no loader, no routes, no boot wiring, so nothing an operator or a client can see changes and the route manifest diff is zero lines. The five states of 2.4 live in one `state` column: installed -> enabled -> started, with disabled and startup_failed as the recoverable ones. The row is a record of what happened, never the source of truth for what is mounted -- the loader scans the filesystem at require time, before the database is reachable (MODULE_API.md 4.1), which is what keeps routes.manifest.json generatable against a dead database. Two rules the model owns and the boot path will lean on: - Every boot resets each non-disabled row to `enabled` and clears its recorded failure, so a startup_failed module is retried on the next restart and a fixed one recovers with no admin-panel visit. `disabled` is the one operator decision rather than outcome, so it survives untouched -- and a disabled module's failure is a no-op, never a re-enable. - A failure carries the stage it happened at, and every non-failing transition clears it, so a running module can never show a stale reason. An illegal move throws instead of writing a row that misrepresents the state, except on the two boot-path softenings noted above, because one module's failure must never become everybody's. 22 model tests over an in-memory fake; the SQL and the DDL were round-tripped against a real MariaDB separately. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-10 06:35:57 -05:00
wtclaude	b517d7b2df	feat(theming): dropdown sections and added links in the public header ... Phase 10 of docs/website/THEMING_AND_NAV.md, asked for before the edge -> main cutover. An admin can now create dropdown sections in the public header, organise the coded entries into them, and add links of their own. This deliberately amends §7, which said the override layer "cannot introduce a `to` that is not already in the hardcoded NAV array". That stays true of every CODED entry; an admin may now also add a link, restricted to a same-origin path — no scheme, no protocol-relative //host. A link carries no gate of its own and needs none: the page behind it enforces its own access, so an added link advertises a route and never grants one. The invariant is kept structurally rather than by vigilance. Coded entries live in an `items` map whose keys must be routes the base array declares, so that map cannot invent a route; everything that CAN name an arbitrary path lives in `links`, which is the one place the path rule is applied — on both the write and the read path. nav_public therefore grew a { items, sections, links } wrapper. A bare map still reads as the items map, and a nav with no sections still stores one, so this changed nothing for a nav that does not use it. Free to do now because nothing has shipped; after the cutover it would have needed a migration. The Public tab gets its own editor. A public section is an entry in the top-level order that the admin created and can drag among the pills, unlike the admin sidebar's four coded sections, where only membership moves — that is a tree rather than a list of groups. Deleting a section returns its entries to the top level rather than removing them, which is the one destructive act this screen could otherwise commit. The dropdown opens on click and never on hover, and its trigger is not a link: a hover menu is unusable on touch, and a trigger that navigates means tapping to open takes you somewhere instead. Escape closes and returns focus, an outside press closes, navigating closes, and Arrow Up/Down walk the items. pruneNav applies the shard-feature gate inside a section and drops one it leaves empty, so a dropdown never opens onto nothing. Also fixes a bug this surfaced in the phase 6-8 code: the save path judged "does this route still exist?" against the palette — the base array already filtered to what the editing admin can see — so on the public header a feature-gated row's override could never be carried through and would have been silently reset. Membership is now judged against the full coded nav while the rows still come from the palette. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-08 00:42:19 -05:00
wtclaude	32a3ff104a	feat(theming): wire the three navs and add the admin nav builder ... Phases 6-8 of docs/website/THEMING_AND_NAV.md. The public header, the admin sidebar and the player portal now read their override row, and /admin/navigation writes them: rename, reorder by drag, hide, and — on the admin sidebar — move a row into another existing section. The merge always runs BEFORE the role and shard-feature filters in the layouts, which are unchanged and remain the boundary. An override is presentation: it cannot introduce a route, cannot touch a `roles` or `feature` gate, and a stored `hidden: false` on a gated item shows nobody anything. The design scoped these phases as client work, but the server had no way to store a nav row: updateSettings validates and stringifies theme_visual and brand_assets and lets everything else through, so a nav object would have been written as "[object Object]" and read as absent for ever. utils/navOverrides.js mirrors utils/brandAssets.js — strict on write with the offending key named, forgiving on read. It validates shape only; whether a `to` exists is settled client-side at merge time, because the base NAV arrays are client constants and a server-side copy would be a second source of truth that drifts. The nav editor cannot be hidden — its own toggle is disabled, the write path drops `hidden` on that one `to`, and AdminLayout strips it again before merging, which also covers a row edited straight in the database. Orders are written only when the sequence actually differs from the code's, and the comparison is restricted to the rows the editing admin can see, so renaming one item does not pin the position of every other one and a role- or feature-gated item missing from their palette is not mistaken for a reorder. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-08 00:02:33 -05:00
wtclaude	847cfd2d2b	feat(theming): brand-asset overrides and a cached, settings-aware HTML shell ... Phase 5 of docs/website/THEMING_AND_NAV.md: uploaded logo/hero/favicon overrides on top of the BRAND_* env defaults, delivered through an HTML shell that is no longer built once at boot. - utils/htmlShell.js owns the shell lifecycle: rendered lazily, cached per process, invalidated on a brand_assets/theme_visual write with a 5-minute TTL so other workers converge. A settings-read failure renders the env-only shell and caches that, so a DB outage is not a failing query per page view, and with no rows the output is byte-identical to what app.js served before. - POST /admin/settings/brand-asset/:slot uploads one asset and writes the row in the same call, so an upload never leaves an unreferenced file. It reuses the shared multer allowlist and only tightens it per slot: favicons are PNG-only and capped at 512 KB, logos at 1 MB, heroes at 8 MB. Refused files are unlinked before the response. - utils/brandAssets.js constrains a stored asset to a same-origin path under /uploads, /brand or /assets — these are the only settings values written straight into the page as a URL. Strict on write, forgiving on read. - The shell also carries the resolved theme as a <style id="theme-boot"> block, removing the first-paint flash phases 3-4 deferred; SiteContext drops that block once a successful settings fetch has been applied. - BrandLogo renders beside the MoonDot on all six shells and renders nothing when no logo is set, which is the shipped default. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-07 20:09:56 -05:00
wtclaude	3d6b2e23a7	feat(theming): server-resolved theme engine and admin appearance UI ... Phases 3-4 of docs/website/THEMING_AND_NAV.md. Three presets, the curated font shortlist, and /admin/appearance to drive them. The design put the presets in theme.css as [data-theme] blocks. That does not work: SiteContext writes --accent as an inline style on <html>, which beats any attribute-selector block, so a preset's accent would have been painted over by BRAND_ACCENT_COLOR while getPublic().brand.accent -- the value the Android app themes itself from -- reported the other one. Presets now live in server/src/config/themePresets.js. themeResolve.js layers :root <- preset <- custom per field into a token map, getPublic() returns it as `theme`, and the client writes it onto <html>. One authority for the merge, and brand.accent is by construction the accent the site paints. theme.css's :root is untouched, so an instance with no row gets no theme block and renders as today. Also: presets carry the full 15-token palette (eight would have left Fantasy with blue-grey borders); the option catalog is served from GET /settings/theme/options so the form cannot offer what the server rejects; validation is strict on write and forgiving on read; and the Discord bot now fetches the effective accent instead of its boot-time env copy. Fixes a Phase 0 bug in passing: settings/nav.controller.js imported the logger factory rather than calling it, so a DB fault would have thrown a TypeError inside the catch instead of returning 500. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-07 19:16:23 -05:00
wtclaude	ec0036ce6d	feat(theming): settings-store, nav merge util and radius tokens ... Phases 0-2 of docs/website/THEMING_AND_NAV.md. Groundwork only: no admin UI, no consumer wiring, and an instance that never touches the new settings keys renders exactly as it does today. Phase 0 - settings store: - settingsDb.remove() and DELETE /api/v1/admin/settings/:key, the "reset to default" primitive. Defaults for these keys live in BRAND_* env, theme.css and the hardcoded NAV arrays, so reset has to delete the row rather than store a copy of the default. Allowlisted to the five theming/nav keys plus hero_layout_draft, admin-only, idempotent. - GET /api/v1/settings/nav behind requireAuth with no role gate. AdminLayout renders for editors and moderators and PlayerPortalLayout for players, and none of them can read GET /admin/settings, so without this their nav override would silently never apply. - A fifth router group for it: /public is anonymous, /admin/settings is adminOnly, /player is self-scoped data. This is configuration that needs a login. - parseJsonSetting() in utils/settingsJson.js. settings.value is TEXT, so every JSON key arrives as a string; malformed or wrong-shaped reads as absent, never as an error and never half-applied. - theme_visual / brand_assets / nav_public join PUBLIC_KEYS; nav_admin and nav_player deliberately do not. Phase 1 - client/src/lib/navOverrides.js, the pure merge util. Presentation only: it can set label/order/hidden and (grouped navs) group, and nothing else. It cannot introduce a `to`, cannot touch roles/feature, and hidden:false cannot un-hide anything - the existing filters run afterward, unchanged, and remain the boundary. Phase 2 - promoted 23 border-radius literals in theme.css to four tokens at today's values (14x8px, 4x999px, 4x10px, 1x12px). The 7px/6px editor chrome and the two 50% circles stay literal. --shadow-card and --panel-grad were already tokens. Tests: 16 new server tests, 20 new client tests. The route-manifest guard now also asserts /settings/** sits behind requireAuth. Swagger and both route artifacts regenerated. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-07 18:15:29 -05:00
wtclaude	01a559792c	fix(shard): answer with the instance name when the shard is unnamed ... ServUO ships Server.cfg with `Name=My Shard`. An operator who never edited it publishes that verbatim, so the rules page read "My Shard" under a header carrying the real name. That value is the shard saying *unnamed* rather than naming anything, so the site now answers with its own. `settings.getInstanceName()` resolves `site_title || BRAND_NAME` — the same resolution `getPublic().brand.name` already uses, so an install that set only the site title can never show two different names on two pages. Bare `brand.name` would have been wrong for exactly that case. Substituted at INGEST rather than on read: world.ruleset is also broadcast live, and the same object is handed to the SSE fan-out, so a read-time fix would be undone by the next reconnect's frame. Matched case- and padding-insensitively but only as a whole value, so a shard genuinely called "My Shard Reborn" keeps its name. Fixes a second ruleset writer found on the way: uoLinkSocket.backfill() called shardState.setRuleset directly instead of going through the dispatcher as ingestEach does, so the boot/reconnect snapshot silently skipped this normalization. The two arrival orders have to produce the same stored frame. Also renders a placeholder row on an unscored leaderboard — the instance name with an em dash where a score goes, deliberately not shaped like an entry (no medal, no bar) because a placeholder that looked like a real standing would be a fabricated one. Presentation only; the API still sends an empty `top`. Verified live against the shard + sidecar: rules page and leaderboards on web and Android both correct. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U7CBg11prhLimL9iHSX1bP	2026-08-01 00:58:21 -05:00
wtclaude	779a304173	feat(shard)!: declare wire protocol 3 ... The site's declared version is the admin-set uo_link_config.protocol column, so the sidecar's PROTOCOL_VERSION 2 -> 3 bump has to be matched here or every REST call 409s and uoLinkSocket closes the WS on the ws.hello mismatch. Five places carry the number and all five move together: the column default, the model's DEFAULT_PROTOCOL (what a site with nothing saved yet declares), the two `config.protocol || 1` fallbacks in uoLinkClient/uoLinkSocket -- unreachable today, but an unset value quietly sending 1 is exactly the confusing 409 the version check exists to prevent -- the admin form's initial value, and the documented env default. The boot migration is the only subtle part. schema.sql is re-run on EVERY boot, and `protocol` is admin-editable, so a bare UPDATE would silently un-pin an operator who had deliberately pinned an older sidecar in Admin -> Shard. It is therefore gated on a marker row in `settings`, written after the UPDATE: the first boot on this build migrates, every later boot is a no-op. `protocol < 3` rather than `= 2` picks up an install still on the old default of 1, which could not have been talking to a v2 sidecar anyway. A fresh install has no row to update and just gets the marker plus the new column default. Verified against the local MariaDB through ensureSchema (the production path): 2 -> 3 with the marker written and the column default now 3; pinned back to 2 by hand, re-ran, and it STAYED 2 -- the one-shot property holds. 673 server tests, 47 client tests, client build green. Co-Authored-By: Claude <noreply@anthropic.com>	2026-07-29 18:03:48 -05:00
wtclaude	8771a1cf6c	feat(shard): the player-vendor marketplace ... Protocol 3.0 §8, the website half. Ingests vendor.listing / vendor.listing.remove into shard_vendors + shard_vendor_items, serves a searchable public API over them, and ships /site/market and /site/market/vendors/:serial. Three things the pages have to say out loud, all consequences of how the data is gathered: - The prices are NOT live. The shard sweeps vendors round-robin, so a shop can be a full cycle behind. The banner is driven by the OLDEST vendor row, not the newest — the one stale shop is the one that wastes somebody's trip. - A shop can be truncated. `total` exceeding `count` means the shop holds more than the shard publishes per frame; the vendor page says "showing 250 of 3,104" rather than presenting a partial shop as complete. - An item may have no name. On a shard with no cliloc table the honest render is the item id, never an invented label. ## The pre-wired visibility rules, re-checked Part A pre-wired market.ownerName and market.location before the frame existed, and the sibling rule it pre-wired for leaderboards (`characterName`) turned out to be INERT because projectValue matches literal JSON keys. Both market rules were checked against the real frame this time: - `ownerName` is a real key. Kept. - `location` is a real key ONLY because the frame nests it. Flat map/x/y/region would have made the rule match nothing — the same failure, one part later. It is nested on the wire and on the read model so one rule hides the facet, the coordinates, the region and the house together; five flat keys would be five rules that drift apart. - `ownerSerial` was ADDED. An admin who hides the owner's name and leaves a serial that the leaderboards and guild boards resolve back to that same name has not hidden anything. Tests assert all three bite, on the stored read model AND on the raw frame — the market's SSE stream is off by default but an admin can turn it on, and a rule that worked on only one path is exactly the leak §3.6.1 records. ## Notable - **No payload column on shard_vendors**, unlike shard_points_boards next door. The board's top-N is a fixed-size list read whole; here the items ARE the searchable rows, so they are normalized and nothing is left worth duplicating. - **display_name is denormalized at ingest** (literal name preferred over the cliloc — a player set it, so it is more specific). Resolving at query time would put the cliloc table on the hot path and make search-by-name impossible. Because the shard's diff sweep will not re-send an unchanged shop just because the site learned what its items are called, a cliloc import now triggers a bulk re-resolution — 50 ms per thousand rows, never throws. - **updated_at is written explicitly** on every upsert. MariaDB does not fire ON UPDATE CURRENT_TIMESTAMP when every column is written back unchanged, and a shop re-published identically is still freshly confirmed — without this the staleness banner would age a perfectly current shop forever. - **LIKE wildcards in `q` are escaped.** `%` and `_` are LIKE metacharacters, not SQL ones, so parameterization does not neutralize them: `?q=%` would otherwise match every listing on the shard. - **Rate-limited** (60/min/IP), the only limited public read. Every other public GET is an indexed lookup of bounded size; this is a LIKE scan plus a COUNT over the largest shard_* table, anonymous by default. - Reconnect backfill pages /market, bounded by MARKET_SNAPSHOT_MAX = 5000 and stopping on a short page as well as on `total`, so a concurrent sweep shrinking the index cannot spin the walk. ## How it was tested 673 server tests pass (27 new). Client builds clean; swagger-output.json, routes.manifest.json and routes.guards.json regenerated. Verified full-stack against the live MariaDB and a real shard, not only units: - 27 real vendors / 1,040 listings swept off the ServUO tree, through the Rust sidecar, into the site — names resolving through the cliloc table ("longsword", "katana"), real facets and regions in the filters. - `?q=sword` 682, `?q=%` and `?q=_` **0** (the escape), map/region/price/sort filters, paging, and the vendor detail route. - Visibility live: fields gated to staff vanish for an anonymous caller while shopName and price survive; audience=player 403s; enabled=0 404s; and /shard/features correctly drops `market` so the nav hides it. - Re-publishing a shop smaller leaves no orphan items; an identical re-publish moves updated_at. - The limiter fires (38x200 then 32x429 on a 70-request burst). Not covered by an automated test: the two React pages are presentational and this repo's client suite covers pure-logic modules only. They were driven against the live API above, but not rendered in a DOM harness. Co-Authored-By: Claude <noreply@anthropic.com>	2026-07-29 09:51:50 -05:00
wtclaude	bda031566a	feat(shard): read clilocs from a source SET so shard items get names ... Shards edit items and add new ones, and those carry cliloc ids no stock client table has. Reading exactly one converted file meant an operator had to re-export 5 MB every time they added one item — friction enough that the table would simply go stale, which is the failure the spawn atlas was redesigned to avoid in the first place. So this mirrors spawnAtlasSource.readSources(): a BASE (the converted client table) plus every operator-maintained overlay under `custom/`, all re-read on every boot and hash-gated as a SET. Later sources win, so an overlay both adds ids the client never had and overrides stock ones the shard re-purposed. Adding, editing or removing any overlay counts as drift. `custom/` is the one convention here that is ours rather than the shard's, and deliberately so: ServUO has no server-side notion of a custom cliloc — they live in the patched client a shard distributes, and nothing in the tree declares them. There is nothing to discover. (An operator who does patch their client cliloc needs no overlay: convert the patched file and the edits are in the base.) Scale, measured on the live shard: its script tree references 16,434 cliloc ids and only 37 are absent from stock — tens against a 67k base, which is why this is an overlay and not a second table. The set brings back a hazard a single file did not have, and it gets the atlas's answer. A corrupt source fails the parse loudly, but a source that has VANISHED parses perfectly and imports a table quietly missing everything it contributed — an unmounted volume is indistinguishable from a deliberate deletion. So it is staged, not applied (`needsReview`), reported by both the import and status(), and accepted with `{approve:true}`. That is a flag rather than the atlas's approve/reject pair because the atlas stores a pending decision SO THAT approving re-parses; here nothing is stored, so re-reading at approval time is automatic. Also reports a per-source breakdown (entries/added/overrode) on import and in status, which is how an operator confirms an overlay took effect — "overrode: 0" on a file meant to re-label stock items says it did not. Two bugs this surfaced, both found by running a shard-style overlay rather than by another stock-table fixture: - displayText tidied punctuation unconditionally, so a custom "Runic Gateway Sigil (v2)" rendered as "(v2". Stripping leftover brackets is right after a placeholder is removed and wrong otherwise — the same condition the `%` rule already had. - CANDIDATE_NAMES did not include `clilocs.plain`, which is the exact filename CLILOCS.md and the export tool's README tell operators to write. Pointing at the directory they were told to create failed with NO_FILE. Verified end to end against the live MariaDB and a real server boot: base-only import, overlay adding one id and overriding another (per-source breakdown correct), unchanged set as a no-op, an edited overlay re-importing and withdrawing its override, a vanished overlay refused with the table intact, status reporting missingSources, approve applying it, and a file-path configuration still finding overlays beside it. All three resolve correctly through the running server: shard-added, overridden and stock. 646 server tests pass (16 new in clilocSource.test.js, 3 new in clilocParse.test.js); swagger, routes.manifest.json and routes.guards.json regenerated. Co-Authored-By: Claude <noreply@anthropic.com>	2026-07-29 06:46:12 -05:00
wtclaude	b61a4d6721	feat(shard): resolve cliloc names for items and reward titles ... Protocol 3.0 §8.6 (docs/link/v3.md), the dependency order 5 was sequenced behind. Items on the wire carry a LabelNumber, not a name — the bridge has always sent it (char.profile.equipment.cliloc, reward titles as a cliloc number in string form, and one per marketplace listing) but the site had no table to resolve it against, so a character sheet could only render `id 1023721` where the game renders "quarter staff". The number was never the missing piece. The table was. Sourced from a file the operator converts once from their own client, at a path from the `cliloc_client_path` setting falling back to UO_CLIENT_PATH. Nothing client-derived is committed: UO's strings are EA's, exactly as the creature sprites are. A shard with nothing configured is fully supported — names render as ids, as they did before. The conversion step is not avoidable, and that is the substantive finding here: every current client ships its cliloc files COMPRESSED (first DWORD's high byte 0x8E, the Mythic container), and ServUO's own bundled Ultima.StringList cannot read that either — so VendorSearch.GetItemName is already inert on such a shard and the plugin could not supply names instead. v3.md's original "read the client's Cliloc.enu" recommendation was therefore not implementable as written, and its committed db/data/clilocs.json artifact also predates the Part C corrections (no committed derived snapshots, nothing EA-derived shipped). Replaced with the spawn-atlas pattern: parse on boot from an operator-configured path, hash-gated, output gitignored. - utils/clilocParse.js — pure parsers, fs-free so the suite runs in CI. Accepts the plain binary layout and delimited text, sniffed by header rather than extension. Rejects a compressed file BY NAME: without that check the plain parser reads it as ~19k records of negative ids and 60 KB "strings" before dying mid-file, and the resulting error names the wrong problem. displayText() drops the ~1_val~ arguments the bridge never sends. - utils/clilocSource.js — the fs layer. hashSource reports `compressed` so the admin panel can flag an unconverted file WITHOUT parsing 5 MB per poll; otherwise pointing at a client directory reports a healthy file with pending drift ("ready to import") and the operator only finds out on failure. - model/shardClilocs — refresh/status/lookup. All-or-nothing replace (DELETE, not TRUNCATE — TRUNCATE is DDL in MariaDB and implicitly commits). Batched server-side resolution behind a capped cache; never throws, because a cliloc lookup is decoration on a character sheet. - Deliberately NO staged-approval flow, unlike the atlas: the atlas escalates facet loss because a half-copied tree and a real map change are indistinguishable from inside the process, whereas a partial cliloc copy makes the parser fail on a truncated record. The ambiguity the atlas must escalate is one this parser simply detects. - No public route. The table is never served AS a table: 67k rows would dwarf any page using them, and the Android client consumes the same resolved JSON. Two parser bugs found by building it, both now covered by tests: trimming a text line before splitting ate the trailing separator on empty-text entries and silently dropped 55,994 of 123,490 while still reporting success; and Number('') is 0, not NaN, so a line starting with a separator imported as a bogus cliloc 0. Verified against the real client table (123,490 entries) and the live MariaDB: import 663 ms, hash-gated boot no-op 14 ms, cold resolve 4.2 ms / warm 0.015 ms. Binary and TSV imports converge on the same 67,496 rows with identical keys (blank entries — half the table — are dropped at import). A file truncated to half its length is refused with TRUNCATED and leaves the previous table serving. Boot logs verified for both the import and the compressed-file warning; neither blocks startup. All three admin routes exercised over HTTP with a real session. 629 server tests pass; client builds clean; swagger, routes.manifest.json and routes.guards.json regenerated. Not covered by an automated test: the character sheet renders resolved names in presentational React with no DOM test harness in this repo, and was not rendered against a live linked-player profile — that needs a logged-in player with a linked game account and a shard answering a profile RPC. Co-Authored-By: Claude <noreply@anthropic.com>	2026-07-29 04:21:38 -05:00
wtclaude	26094459ae	feat(shard): ingest points.board and publish the leaderboards ... Protocol 3.0 §7 (docs/link/v3.md). The shard publishes ~25 points/loyalty leaderboards — Queen's Loyalty, Void Pool, the nine city loyalties, Clean Up Britannia — and the site renders them, plus each character's own standings on their sheet. Server - shard_points_boards: one row per system, keyed by the shard's PointsType name. The top-N list stays inside `payload` — a fixed-size list read whole, exactly like shard_governors.candidates. Normalizing into an entries table buys nothing until something needs a per-character reverse lookup, and a character's own standings already ride inside char.profile. - shardIngest routes points.board to upsertPointsBoard and deliberately does NOT log it: this is board state like guild.update, and the shard emits a frame every time anyone's score moves a top ten. - uoLinkSocket backfills /points through snapshot() with ingestEach rather than a replace*: there is no points.remove and the system set is fixed, so upserting IS the reconciliation, and a system the operator later excludes keeps its last-known board rather than vanishing. - GET /public/shard/points and /points/:system behind requireFeature('leaderboards'), both projected per §3.6.1. :system is constrained to an identifier before any query runs; 404 for a system never published, distinct from a published board nobody has scored in (200, empty top). The leaderboards field rule now keys on `name`, not `characterName` Part A pre-wired FEATURES.leaderboards.fields = { characterName: ... }, but projectValue matches on the LITERAL JSON key and the wire key is `name`. As written the rule was inert: an admin tightening character names would have got no enforcement and no error — precisely the failure §3.6.1 records for the flattened `ownerAcct` spelling. Fixed, with a test that fails if it is renamed back, and the admin panel's FIELD_LABEL carries the meaning instead. Client - routes/public/Leaderboards.jsx at /site/leaderboards. A points.board frame describes ONE system, so live frames merge over the fetched set by system key rather than replacing it wholesale the way the ruleset does. Filter matches board name, system key, or any ranked player — the last is what makes it useful ("where do I appear?"). - A "Loyalty & Points" section in CharacterSheet.jsx, one edit serving both PlayerCharacter and AdminCharacter. - Both treat maxPoints: 0 as UNCAPPED and both fall back to humanising the system key when nameString is null. Neither is defensive padding: on a real shard uncapped and cliloc-only names are the majority case. Verified end to end against the local MariaDB, the Rust sidecar, and the real ServUO shard: backfill from /points, live SSE delivery (a board absent from the initial fetch appearing without a reload, and an existing one updating in place), REST reflecting the overwrite, and the gate at every rung — 200 by default with names, names stripped but points kept at fieldRules name=staff, 403 plus dropped from /features at audience=staff, 404 when disabled. Page rendered clean, no console errors beyond the pre-existing React Router v7 warnings. 605 server tests pass; routes.manifest.json, routes.guards.json and the OpenAPI spec regenerated. Co-Authored-By: Claude <noreply@anthropic.com>	2026-07-28 21:04:44 -05:00
wtclaude	7c769ea8fd	feat(atlas): serve the spawn atlas and give operators a panel for it ... Protocol 3.0 order 3 (Part C), second of two website PRs. #112 built the data pipeline; this makes it reachable — six public routes, five admin ones, two public pages and an admin panel. Still website-only: no plugin, no sidecar, no new event kinds, no wire change. The API sits at /api/v1/public/atlas, not under /public/shard. Nothing here touches the sidecar, so the pages stay complete while the shard is down, and a /shard prefix would imply a dependency the atlas does not have. Unlike /shard/* it IS site-mode gated, like /posts and /wiki: a bestiary is site content. Every route carries requireFeature('atlas') and projects its response. The atlas feature declares no sensitive fields, so the projection is a no-op today — the call is there because v3.md 3.6.1's rule is that the FIRST field needing a gate should be covered by construction rather than by a retrofit. Two bugs the UI surfaced, both fixed here: Respawn delays were stored in the wrong unit, sometimes. XmlSpawner writes MinDelay/MaxDelay in minutes and switches to seconds only when a delay does not divide into whole minutes, flagging it per record with DelayInSec. A `5` means five minutes on one spawner and five seconds on the next, both plausible, and the pipeline stored the raw number. 170 of 6,455 stock spawners are second flagged. The parser normalises to seconds; the API and UI carry seconds. That exposed the hash gate as a trap. "Has the tree changed?" is the wrong question on its own: an install whose maps never change would have kept serving the old readings forever, because the only thing compared was the tree. PARSER_VERSION is now stored beside the source hashes and a mismatch counts as drift, so any future parse correction lands on the next boot. Also renamed the detail route's spawn-point array to `spawners` — it was `points`, which is the COUNT on the search route, so one key meant a number in one place and an array in the other. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U7CBg11prhLimL9iHSX1bP	2026-07-28 19:51:22 -05:00
Claude	a4ef9d676d	Merge remote-tracking branch 'origin/edge' into feat/spawn-atlas-parse	2026-07-28 16:45:56 -05:00
wtclaude	2801ec8f4d	refactor(atlas): derive the atlas from the shard's tree on every boot ... Replaces the committed-artifact design from the first commit. Two problems with it, both raised in review: **Facets are not a fixed list.** The first pass carried a hardcoded table of the six stock UO facets to reconcile the spelling drift between sources. That is wrong: a shard may add facets, replace them outright, or rename them when its maps are updated, and a built-in list quietly mishandles all three. Nothing in the atlas names a facet any more. The facet set is discovered from the tree — spawn records and region definitions are the authority — and the loose spellings in Data/Locations are matched against it by key and prefix. Custom facets get identical treatment; the tests use `Sosaria` and `Underdark` precisely so a stock-facet assumption cannot creep back in. **A snapshot goes stale.** Maps change over a server's life, so a build-once artifact silently drifts from the world players actually see. The tree is now the single source of truth and the atlas is re-derived on every boot. ## What that changed - **The committed artifact is gone** — 1.41 MB of generated JSON removed, along with `scripts/buildSpawnAtlas.js` and the whole encode/decode seam it needed (`encodePoint`/`readPoint`, the tuple encoding, the omitted-defaults scheme and their round-trip tests). Nothing to keep in sync, nothing to go stale. - **NEW `src/utils/spawnAtlasSource.js`** — the only thing that touches a ServUO tree; shared by the boot path and the CLI. Parsers stay pure and fs-free. - **NEW `src/model/shardAtlas/`** — `.db.js` (the one-transaction replace) and `.model.js` (the refresh decision). - **`scripts/importSpawnAtlas.js`** is now a thin CLI over the model: `--servuo`, `--force`, `--approve`, `--reject`, `--status`. `atlas:build` is gone; `atlas:import` remains. - Path comes from the `spawn_atlas_servuo_path` admin setting, falling back to `SERVUO_PATH`. The setting wins, matching how the rest of the shard integration is admin-managed rather than env-configured. ## Two contracts on the boot path **It never blocks startup.** No path, an unreadable mount, a malformed file, a database error — every one is caught and logged, and the site comes up serving whatever atlas it already had. Verified by booting the real server with no path, a broken path, and a good path. **A facet disappearing is never applied automatically.** Losing a facet is the signature of a half-copied or mid-update tree as much as of a real map change, and boot cannot tell them apart. The refresh is staged in `shard_atlas_pending` for an admin to approve or reject, and startup continues regardless. Additions and every other change apply immediately, since none of them can destroy something an operator would miss. Only the decision is stored, not the parsed world: a few KB of source hashes and the facet diff. Approving re-parses, so what gets applied matches the tree at approval time rather than at boot. A rejection is remembered against those exact hashes, so a declined refresh does not re-prompt on every restart — changing the tree changes the hashes and asks again. Hash-gated, so the common case (restart, maps unchanged) reads and hashes the tree (~120 ms) and writes nothing. A real change costs a ~400 ms parse. The admin approve/reject UI is part of the second PR, with the rest of the routes and pages. Until then the CLI covers it. ## Verification - **564 server tests pass**, 28 new in `spawnAtlas.source.test.js` covering the custom-facet build, the spelling reconciliation, hash gating, and every branch of the refresh decision — including that `refreshOnBoot` survives a database that throws on every call. - End-to-end against the local MariaDB and the real ServUO tree: 6,455 points, 800 creatures, 23,927 point/type rows, 387 regions, 558 landmarks, 25 altars, 83.2% of points resolved to a place name. - The facet gate exercised against a real tree copy with `malas.xml` removed: staged rather than applied, atlas untouched with all 293 Malas points intact, reject then stays quiet on re-run, approve applies and drops the facet. - Booted the real server under all three source conditions; none blocked. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U7CBg11prhLimL9iHSX1bP	2026-07-28 16:41:33 -05:00
wtclaude	353cce9f26	feat(atlas): parse a ServUO tree into a committed spawn atlas artifact ... Protocol 3.0 order 3 (Part C), first of two website PRs. This half is the data pipeline only — parsers, the build/import CLI, and the tables. No routes and no client, so nothing is user-visible yet; the API and pages follow in PR 2. Part C is website-only: no plugin, no sidecar, no new event kinds, no wire change. ## Parsing `src/utils/spawnAtlasParse.js` is pure and fs-free so CI covers it with no ServUO tree. Zero new dependencies — `Regions.xml` genuinely nests, so it gets a small hand-rolled subset tokenizer rather than a new XML package. The 10.5 MB of `Spawns/*.xml` never touches it: those records are flat and get a streaming regex sweep instead. The high-value transform is point-in-rect placement — highest region priority wins, ties break to the smaller rect, then a nearest-landmark fallback within 200 tiles, else "Wilderness". That is what turns "lizardman at 5411,1234" into "Despise, Felucca", and it resolves 83.2% of points (5,369 of 6,455). Three things the real data forced, none of which were in the design: - **Only 6 facets, not 13.** `Eodon.xml`, `GravewaterLake.xml` and the other named-area files carry TerMur/Trammel points, so the facet comes from each record's own `<Map>` and the artifact shards 6 ways. - **Facet names disagree across sources.** `Data/Locations/*.xml` spells them `Ter Mur` and `Tokuno Islands`; `<Map>` and `<Facet name>` say `TerMur` and `Tokuno`. Unreconciled this is silent — the landmark fallback simply never fires on those facets and every unregioned spawn there reads "Wilderness". - **Spawn type tokens carry XmlSpawner directives**: `Fairy,{RND,4,8}`, `alchemist/z/-50`, `Agralem/Name/Agralem`. Taken literally these invent creatures that do not exist AND split real ones in two, since `Fairy` and `Fairy,{RND,4,8}` slug apart. 71 of 845 entries were affected; stripping at the first `/` or `,` leaves 800 clean ones. ## Artifact `npm run atlas:build -- --servuo <path>` writes `db/data/spawnAtlas.*.json`: 6 facet shards + a compact index + a small indented `meta`. 1.41 MB committed, down from 4.40 MB by dropping `facet` per record, omitting defaulted fields, and tuple-encoding the ~24,000 type entries. `encodePoint()` and the importer's `readPoint()` are exact inverses and are round-tripped in tests. Display spelling is chosen deterministically (most common, ties to the capitalised form) because the spawn files are inconsistent about case and the name would otherwise depend on file read order — a spurious diff on every unrelated rebuild. ## Import `npm run atlas:import` needs no ServUO tree, which is the whole reason build and import are separate: the container has the artifact but not the tree. It reloads all six tables in one transaction (DELETE, not TRUNCATE, which is DDL and would implicitly commit), so a failed import leaves the previous atlas intact. ## No artwork, by design The repo ships no creature art and no extraction tooling. Sprites live in the operator's own client `.mul`/`.uop` files and are theirs, not ours to redistribute. `shard_spawn_creatures.art` is nullable and NULL on every fresh import; an operator who wants art extracts it themselves, drops it under `server/uploads/atlas/` (already gitignored) and maps slugs in a gitignored `spawnAtlas.art.json`. Text-only is the normal, fully supported state. ## Verification - **544 server tests pass**, 57 new across `spawnAtlas.parse.test.js` (the `:OBJ=` split, directive stripping, nested-region priority inheritance, half-open rects, the facet reconciliation, tokenizer edge cases) and `spawnAtlas.build.test.js` (aggregation, deterministic naming, and the encode/decode round trip). - Built and imported for real against the local MariaDB and the ServUO tree at `C:\Users\colby\Desktop\ServUO`: 6,455 points, 800 creatures, 23,927 point/type rows, 387 regions, 558 landmarks, 25 champion altars. - "Where does a lizardman spawn?" answers Shrines / Isamu-Jima / Yew across Felucca, Trammel and Tokuno. No routes changed, so the OpenAPI spec and route manifest are untouched. --- - [x] AI-assisted: written with **Claude Code** (Claude Opus 5), reviewed before opening. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U7CBg11prhLimL9iHSX1bP	2026-07-28 16:07:30 -05:00
wtclaude	61d6bfaca2	feat(shard): ingest world.ruleset and publish it at /site/rules ... Protocol 3.0 §5 (docs/link/v3.md). The shard publishes its own ruleset — expansion, which optional systems are on, skill/stat caps, account and house limits, champion scroll rules, the save/restart schedule — and the site renders it, so the rules page cannot drift from how the shard actually plays. Server - shard_ruleset: a singleton table (id = 1) holding the whole frame in `payload`, with `rev` and `expansion` hoisted. Nothing is normalized out: the frame is a flat description of config read as one page, and splitting it into columns would mean a schema change every time the shard grows a block. - shardIngest routes world.ruleset to setRuleset and deliberately does NOT log it — the shard re-emits the whole ruleset on every sidecar connect, so logging would append a duplicate row per reconnect, and server.hello already marks each of those. - uoLinkSocket backfills GET /ruleset explicitly rather than via snapshot(), which asserts an array; this covers the order where the sidecar was already up and holding the ruleset when we reconnected. - GET /public/shard/ruleset behind requireFeature('ruleset') and projected, per §3.6.1's rule that a shard read which doesn't project is a bug. `null` means the shard has never published one — a real answer, distinct from a published ruleset, and the page says so. Client - routes/public/Rules.jsx at /site/rules, live via world.ruleset (a frame is a complete ruleset, not a delta, so the newest one wins outright). Caps are rendered from tenths — 7000 is 700.0, and showing the raw number would mislead. A systems key this build doesn't know still renders, humanised, so a newer plugin can't go invisible against an older client. - Nav entry gated on the `ruleset` feature, so it hides rather than 403s. Verified end to end against the local MariaDB and a sidecar fed by a fake shard: backfill snapshot, live SSE delivery of a changed ruleset, REST reflecting the overwrite, an empty /feed (not logged), and the gate — 200 by default, 403 at audience=staff (and dropped from /features so nav hides it), 404 when disabled. Page rendered clean at all breakpoints checked, no console errors. 497 server tests pass; routes.manifest.json, routes.guards.json and the OpenAPI spec regenerated. Co-Authored-By: Claude <noreply@anthropic.com>	2026-07-28 14:35:24 -05:00
wtclaude	f30ea66fce	fix(shard): enforce visibility on the REST reads that bypassed it ... Protocol 3.0 Part A follow-up, found by the live five-rung smoke test. Part A implemented the visibility framework correctly on the SSE path and on /guilds + /governors, but the remaining public REST reads never called into it. The result was that one event was projected live and served verbatim from history: * GET /public/shard/feed returned the stored payload as-is, so actor.acct and actor.webId were readable ANONYMOUSLY for every logged kind - player.death, player.murdered, mob.killed, quest.complete, skill.gain, fame/karma.change, mob.login/logout, guild.join. Broader than the guild-leader leak Part A set out to close, since it covers every player rather than board holders. * GET /public/shard/idoc returned ownerAcct - the house owner's game account - to anonymous callers. * The `houses` field rules (owner/price -> staff) were dead config: neither getIdoc nor getHouses projected, so an admin could set them in the panel and nothing happened. * /feed filtered on PUBLIC_KINDS, a module-load constant derived from the compiled DEFAULTS, so live audience changes did not reach it. With `guilds` moved to staff, /guilds 403'd while /feed happily served guild.join to anonymous. Four fixes, all at the root rather than per-route: 1. Rule 1 now matches a field's MEANING, not one spelling. The wire nests actors (leader.acct) but the read models flatten them (shapeHouse -> ownerAcct, shapeGuild -> leaderWebId), and an exact-key check missed every flattened one. isLockedField() locks a key that is or ends in acct/webId, case-insensitively, so it fails closed for shapes not yet written. The admin PUT rejects those spellings too - `ownerAcct` is no longer configurable. 2. visibleKinds(level, config) resolves readable kinds from the LIVE config; getFeed uses it and projects each row against its own kind's feature. Deliberately independent of the `stream` flag, which governs SSE fan-out only - so market history stays readable with its firehose off. This makes the set a superset of PUBLIC_KINDS by exactly the two vendor kinds. 3. getIdoc/getHouses/getChamps/getPresence project, so every shard surface honours the same config. 4. shardEvents.db.list treats an EMPTY kinds array as "serve nothing". It previously fell through to the unfiltered query, so a fully-gated config would have dumped the whole event log, staff audit included. Also fixes a bug introduced while wiring this up: projectValue recursed into any object, so a Date column came back as {}. It now walks arrays and plain objects only. The unit tests used JSON fixtures and could not have caught it - the live /idoc read did. Verified live against MariaDB + a stub sidecar, all five rungs: 13 routes x 5 rungs, defaults reproducing pre-v3 access exactly, zero acct/webId below admin on any read, unmapped kinds (staff.command, cheat.detect, login.attempt) reaching only admin on SSE, and audience / enabled / stream changes taking effect live on an already-open stream. Tests: 487 server (+9). Swagger regenerated; route manifest unchanged. Co-Authored-By: Claude <noreply@anthropic.com>	2026-07-28 10:49:55 -05:00
wtclaude	f3450686e0	feat(shard): admin-configurable visibility for every shard surface ... Protocol 3.0 Part A. Replaces the static PUBLIC_KINDS allowlist - which was the entire public/admin boundary - with per-feature, per-field audience control an admin owns from Admin -> Shard Visibility. Closes a live leak. BridgeJson.Actor() writes acct and webId; shapeGuild() returned the stored payload verbatim; GET /api/v1/public/shard/guilds is anonymous. Guild leaders' game account names and website user ids were readable by anyone, and the same path existed for governors. Both are now projected. The ladder is anonymous < logged_in < player < staff < admin, each rung implying the ones below. Staff satisfy `player` without a linked account (as /player/* already does); `editor` is a content role and gets no shard privilege, since mapping it to staff would silently widen what editors see. Two invariants are code, not configuration, and both reject rather than silently ignore: 1. acct/webId are admin-only always - not configurable, discarded on read as well as rejected on write. 2. A kind absent from KIND_FEATURE never reaches anyone below admin. Fail closed, so a shard emitting a new event degrades to staff-only rather than to public. Enforcement is three points over one config: requireFeature() on routes (404 disabled, 403 out-of-rung) plus field projection; per-connection filtering on SSE, where a subscriber's rung is resolved once at subscribe time and frozen so a long-open stream cannot gain privilege; and /public/shard/features so the SPA hides links it cannot follow. PUBLIC_KINDS still exists and is still exported (/feed filtering, notificationStreams) but is now derived from the kind map, so the two can no longer drift. Defaults reproduce pre-3.0 behavior exactly - a test pins the derived set against the old allowlist. Also fixes an SSE resource leak found while testing: a client dropped because its write threw was removed from the bucket but its keepalive interval was never cleared, firing forever on a dead socket. Both paths now go through one drop(). Tests: 478 server (33 new across shardVisibility + shardBroadcast), 43 client. Route manifest and OpenAPI spec regenerated. Co-Authored-By: Claude <noreply@anthropic.com>	2026-07-28 10:04:48 -05:00
wtclaude	620781b7bc	feat(auth): honor and establish trusted devices on the SSO login paths ... "Trust this device" did nothing for anyone who signs in with Google or Discord. sso.controller went straight from needsTotp(user) to staging a pending-TOTP challenge and never consulted resolveTrustedDevice, so an SSO user was asked for a code on EVERY sign-in no matter how many times they had ticked the box — and POST /auth/sso/totp accepted only `code`, so that step could not establish a trust either. The password paths (web + native) were unaffected and already worked; this closes the gap for SSO, on the website AND in the Android app. Server: - finishLogin and finishMobileLogin now run the same trusted-device check as auth.controller.login, via one shared helper: honor a trust that belongs to THIS user, stamp last_used_at, log auth.login.trusted_device. A store error falls through to the challenge — fail closed to asking for the code. - POST /auth/sso/totp gains optional trustDevice + deviceName, sets the rg_trust cookie, and mirrors the password path's { trustLimitReached, devices } response at the cap (the sign-in still completes). Recovery codes stay password-only. Android coverage, without leaking a secret into a URL: - The app opens SSO in a Custom Tab, which shares the system browser's cookie jar, so the rg_trust cookie set on that TOTP form is presented back on the next app sign-in. That alone makes native SSO skip the code. Passing the app's token into the start URL was rejected — it would put a 256-bit secret in query strings, Referer headers and access logs. - To also cover the app's NATIVE password login, ticking the box sets mobile_auth_sessions.trust_device (a boolean; never the token), and /auth/mobile/sso/exchange mints a platform:'mobile' trust and returns { trustToken }. Minting there keeps the raw token on an authenticated app→server call, out of the deep link and out of the bridge row. Best-effort: at the cap the response just omits it rather than failing a good sign-in. Client: the trust checkbox is no longer hidden on the SSO second step, on both the admin and player login screens. On the mobile bridge the deep-link redirect takes priority over the cap prompt — the sign-in succeeded and the link is single-use, so stalling there would strand the app. Tests: 8 new cases in server/test/ssoTrustedDevice.test.js (verified to fail against the pre-fix controller). Full suites green — server 445, client 43 — and routes.manifest.json is a zero-line diff: no URL moved, only +2 handlers on /auth/sso/totp in routes.guards.json for the two new validators. Swagger regenerated. Verified live against the running server and real MariaDB: the TOTP step issues rg_trust and persists the row, a subsequent SSO callback carrying it skips the code, and an invalid trust is still challenged. Co-Authored-By: Claude <noreply@anthropic.com>	2026-07-28 01:01:12 -05:00
wtclaude	a6fd5659c4	fix(shard): stop an undecryptable uo-link token 500ing every live-shard route ... `uoLinkClient.call()` resolved the uo-link config OUTSIDE its try/catch. resolveConfig() decrypts the stored auth token, and secretBox.decrypt throws when the ciphertext can't be authenticated — SECRET_ENC_KEY rotated, or a DB dump restored into an environment keyed differently. That throw escaped the client entirely, breaking its documented "never throws / always returns { ok, data, status }" contract and turning a misconfiguration into a 500 on every route that does a live sidecar round-trip: GET /admin/uo-link/config GET /{admin,player}/shard/char/:serial GET /{admin,player}/shard/roster/:account GET /{admin,player}/shard/vendors/:account Found by a live smoke test of all 200 routes at every access level. Public shard routes were unaffected because they read the DB via getSafe(), which never decrypts. Move resolveConfig() inside the try so the failure returns the standard { ok: false } shape, and log it at ERROR with a distinct message: a wrong key previously looked identical to "the shard is offline", with no clue why. Those routes now degrade to 503, and GET /admin/uo-link/config returns 200 again — it is the screen an admin needs to re-enter the token and recover, so having it 500 locked them out of the fix. Also gate the admin Dashboard's site-mode toggle. PUT /admin/site-mode is adminOnly, but the button rendered for every staff role, and toggle() had a try/finally with no catch — so an editor clicking it got an unhandled promise rejection and zero UI feedback. Gate the control on role === 'admin' (the rule AdminLayout already documents: never show a non-admin a control that would 403) and surface a message if the call is refused anyway. Adds server/test/uoLinkClient.test.js, which fails against the unfixed client. Co-Authored-By: Claude <noreply@anthropic.com>	2026-07-28 00:22:40 -05:00
wtclaude	565a7d2c20	refactor(server): split public, player and residual auth into capability routers (PR 5) ... The last split PR of docs/website/API_V2_PLAN.md § Phase 2. public.routes.js, player.routes.js and auth.routes.js are deleted; each group is now a directory whose index.js owns the group gate and the mount table and declares no routes. Every one of the 200 manifest routes is now in a capability router. public/ posts (2) wiki (4) pages (2) shard (12) site (4, group root) player/ account (8) shard (8) appeals (4), behind noindex + requireAuth auth/ login (2) register (1) invite (2) password (3) session (2, root) No URL moves. All four gates zero-diff: routes.manifest.json (200 public + 2 internal), routes.guards.json, swagger-output.json (198 operations), and docs/website/api-route-inventory.json was already in sync. 434 tests green. Notes on the non-mechanical parts: - public/index.js and auth/index.js carry no group gate, deliberately, and say so. The public surface is anonymous by contract (logged-out SPA, Discord bot, Android ShardStreamClient on /public/shard/stream); /auth is where a caller becomes authenticated. player/index.js gates on requireAuth only, never requireRole('player') — staff are a superset of players. - GET /auth/me has a mount-order dependency: use('/me', meRouter) matches the bare /me, so the request runs meRouter's noindex + requireAuth and falls through. session.router.js must stay mounted last. Verified by the counterfactual — mounting it first still 401s but drops X-Robots-Tag, which no manifest or guards file can see. - loginGuards moved to auth/loginGuards.js (frozen) rather than being copied into the three routers that spread it; sso.routes.js drops its duplicate. - The :param shadowing check was re-run in dispatch order against the built stack: 86 routes, 64 literal, none shadowed. /public/wiki/{categories,tags} ahead of /:slug is the only ordering-sensitive pair. Co-Authored-By: Claude <noreply@anthropic.com>	2026-07-27 20:52:14 -05:00
wtclaude	8fd0d82580	refactor(server): split admin shard, uo-link, email, discord-bot, settings and dashboard into capability routers ... PR 4 of the in-place admin router split (docs/website/API_V2_PLAN.md § Phase 2), and the last admin one: it moves the entire residual 33 and DELETES admin.routes.js. Every one of the 110 admin routes is now declared in a capability router. No URL, gate or handler changes. shard.router.js (16) /admin/shard uoLink.router.js ( 5) /admin/uo-link email.router.js ( 6) /admin/email discordBot.router.js ( 2) /admin/discord-bot settings.router.js ( 2) /admin/settings dashboard.router.js ( 2) GET /dashboard + PUT /site-mode, at the group root admin.routes.js deleted, was 33 No gate moved to router level. Every adminOnly in the residual file was per-route, and modAccess on /shard must stay per-route because half that router must not have it — which keeps the per-route handler count intact, the one number routes.guards.json can actually check. /shard is the first prefix where two tiers share one router: 7 self-service account-linking routes (no extra gate, served by the same player/shard controller handlers, tagged `Admin · Account`) alongside 9 in-game staff ops on modAccess. Prefix ownership beats tag grouping — splitting by tag would put two routers under one prefix for no gain. The tag mismatch stays; retagging is a real spec diff and belongs in a PR about tags. dashboard.router.js is the one router mounted at the group root rather than a prefix: GET /dashboard and PUT /site-mode share no path segment. That is safe only because the file declares no router-level middleware — a bare use(gate) in a root-mounted router would run for every request passing through toward another mount. The file carries a comment saying so. Acceptance — all four gates zero-diff: routes.manifest.json unchanged (200 public + 2 internal) routes.guards.json unchanged (no route lost or gained a gate) swagger-output.json unchanged (198 operations) api-route-inventory.json already in sync plus 434 server tests green. Verified separately, because no gate can catch it: introspecting the built stack, all 59 literal admin paths still dispatch to their own layer — nothing is captured first by a /:param sibling. The manifest sorts its entries, so declaration order is invisible to it. Also repoints the comments that referenced admin.routes.js by name (botActivity/moderation controllers, the town-crier cap mirror in announceJobs.logic.js) and generalizes the "the path is on the line after router.get(" rationale in routeManifest.js, README.md and pr-checks.yml, which was never about that one file. Co-Authored-By: Claude <noreply@anthropic.com>	2026-07-27 20:02:28 -05:00
wtclaude	00ad16858a	refactor(server): split admin posts, uploads, wiki and pages into capability routers ... PR 3 of the in-place admin router split (docs/website/API_V2_PLAN.md § Phase 2). Moves the content tier out of the residual admin.routes.js into one router file per capability, each mounted at the prefix it already owned. No URL, gate or handler changes. posts.router.js ( 9) /admin/posts uploads.router.js ( 1) /admin/uploads wiki.router.js (14) /admin/wiki pages.router.js ( 7) /admin/pages admin.routes.js (33) residual, was 64 All four capabilities are editor tier, so no gate moved: the shared `noindex, isLoggedIn, staffOnly` in admin/index.js is their whole gate. The multer config moved to admin/imageUpload.js because the two routes that share it (POST /posts/upload and POST /uploads) now live in different files; duplicating a mimetype allowlist is how the two copies drift. It stays in admin/ because UPLOAD_DIR is resolved relative to __dirname. Acceptance — all four gates zero-diff: routes.manifest.json unchanged (200 public + 2 internal) routes.guards.json unchanged (no route lost or gained a gate) swagger-output.json unchanged (198 operations) api-route-inventory.json already in sync plus 434 server tests green. Verified separately, because no gate can catch it: the wiki router's literal /categories and /tags paths still precede /:slug in declaration order. The manifest sorts its entries, so a reordering there would be invisible. Co-Authored-By: Claude <noreply@anthropic.com>	2026-07-27 19:24:07 -05:00
wtclaude	bd53a0b8a4	refactor(server): split admin moderation, bot-activity and activity into capability routers ... PR 2 of the domain split (docs/website/API_V2_PLAN.md § Phase 2). Carves 18 more routes out of admin.routes.js into one router file per business capability, in place, with every URL unchanged: moderation.router.js (15) /admin/moderation modAccess at router level botActivity.router.js (2) /admin/bot-activity adminOnly per route activity.router.js (1) /admin/activity staff-wide, no extra gate The residual admin.routes.js drops from 82 routes to 64. Moderation was already gated by a prefix mount (adminRouter.use('/moderation', modAccess)), so moderationRouter.use(modAccess) is the exact equivalent now that the router is mounted at a prefix. Bot-activity's adminOnly was per-route and is deliberately kept per-route: that is what holds the per-route handler count in routes.guards.json, the only signal that would catch a dropped gate, since requireRole(...) returns an anonymous arrow and never appears by name. /activity gets its own file rather than waiting for dashboard.router.js in PR 4 — it is the staff audit log, a different capability from the dashboard's stats overview and from the botScore middleware's in-memory ban state. Acceptance: - routes.manifest.json zero-diff (200 public + 2 internal) - routes.guards.json zero-diff - swagger-output.json zero-diff (198 operations) - api-route-inventory.json already in sync - 434 server tests green - role gates verified identical to main by reading the requireRole role sets off the live Express stack for every moved route plus untouched controls Co-Authored-By: Claude <noreply@anthropic.com>	2026-07-27 18:53:15 -05:00
wtclaude	8ad892725f	refactor(server): split admin users, account, invites and auth providers into capability routers ... First of the five domain-split PRs in docs/website/API_V2_PLAN.md § Phase 2. Pure mechanical re-wiring: routes move between files, no handler, gate, validator or annotation changes, and not one URL moves. New src/router/v1/admin/index.js owns the two things the group shares — the `noindex, isLoggedIn, staffOnly` gate and the mount table — and declares no routes itself. The gate sits ahead of every mount so a capability router extracted in a later PR cannot silently ship without it. Four capability routers mount at the prefix they already owned inside the monolith: account.router.js 6 routes -> /admin/account (self-service, no adminOnly) users.router.js 15 routes -> /admin/users (adminOnly, router-level) invites.router.js 3 routes -> /admin/invites (adminOnly, per-route) authProviders.router.js 4 routes -> /admin/auth (adminOnly, per-route) admin.routes.js keeps the other 82 (6+15+3+4+82 = the 110 inventoried admin routes) and is mounted last at the group root; none of the four prefixes appears in it, so nothing depends on mount ordering. It disappears when PR 5 lands. Handlers still live in admin.controller.js and usersShard.controller.js — this re-wires routes, not logic. `adminOnly` moves with the routes that use it, and `usersRouter.use(adminOnly)` is exactly equivalent to the old `adminRouter.use('/users', adminOnly)` now that the router is mounted at /users. All three generated gates are zero-diff: routes.manifest.json unchanged (200 public + 2 internal) routes.guards.json unchanged — no route lost or gained a gate swagger-output.json unchanged, byte-for-byte The spec staying byte-identical depends on the path normalization landed in the preceding commit; without it the four collection routes would have documented as /api/v1/admin/{users,invites,account}/ with a trailing slash. Server tests green (434/434). Co-Authored-By: Claude <noreply@anthropic.com>	2026-07-27 15:54:00 -05:00
wtclaude	1a61cd1638	build(swagger): normalize and sort generated OpenAPI path keys ... Prepares the committed spec for the admin router domain split (docs/website/API_V2_PLAN.md § Phase 2) by post-processing swagger-autogen's output in swagger/swagger.js. No route, handler or annotation changes. Trailing slashes are stripped from path keys. swagger-autogen builds a path by string-concatenating the mount prefix with the route argument, so a capability router mounted at /users whose collection route is router.get('/') documents as /api/v1/admin/users/ — advertising a URL no client calls while dropping the one the SPA, the Android app and the Discord bot all do. Express is indifferent (non-strict routing treats the two as one route, and routes.manifest.json records the canonical slash-less form), but the published spec is a contract. The split creates one of these per capability router, so it is fixed once here rather than by contorting the route declarations in every router file. Path keys are also sorted. The generator emits them in router-traversal order, so moving a route between files rewrites most of this ~5k-line committed artifact even when the API is provably unchanged, burying the one line a reviewer needs to see. OpenAPI attaches no meaning to path order, and scripts/routeManifest.js already sorts for the same reason. Verified inert: the regenerated spec is byte-for-byte the sorted form of the previously committed one — same 198 operations, zero added or removed, and no trailing-slash keys (there were none to strip yet; the guard is for the split). A collision after normalization throws rather than silently dropping an operation. Server tests green (434/434). Co-Authored-By: Claude <noreply@anthropic.com>	2026-07-27 15:49:31 -05:00
wtclaude	9b74999610	feat(security): soak the tightened CSP on report-only, with a same-origin sink ... Phase 1 of docs/website/API_V2_PLAN.md. The tightened policy ships on Content-Security-Policy-Report-Only alongside the unchanged enforced one for a release; a follow-up PR flips it after the soak comes back clean. The plan expected a two-directive delta. It is one. `form-action 'self'` was described as absent because it is not in the directives object in app.js — but the middleware runs with `useDefaults: true` and helmet's defaults already supply it, so the header served in production has carried it all along. Caught by capturing the live header from the running app instead of reading the config. It is now written out explicitly in config/csp.js regardless: a security directive should not depend on a third-party library's default surviving its next major version. The enforced header's contents do not change at all, and a test pins it verbatim. So the whole behavioural delta is `frame-ancestors 'self'` -> `'none'`. That is still the directive most worth soaking: a frame-ancestors report is generated by the browser of whoever framed the site, which is the only way to find out that something legitimately embeds us before an enforcing policy breaks it. The policies move to config/csp.js, with the report-only one derived by spread from the enforced one so the two cannot drift and the object reads as a diff. `report-to` needs somewhere to point, so this adds POST /api/csp-report -- same-origin on purpose, since reports describe attacks against this site and should not go to a third-party collector. It is mounted outside /api/v1 next to /api/health: the browser learns the path from the policy header, never from a client build, so it is not versioned client contract. It is necessarily unauthenticated -- browsers send reports with no session, and gating it would silence exactly the anonymous visitors worth hearing about -- so it is bounded on every axis: * both wire formats, since report-uri (Firefox/Safari) sends hyphenated keys in application/csp-report and report-to (Chrome) sends camelCase envelopes in application/reports+json; handling one silently drops half the browsers, * report-to also needs the Reporting-Endpoints response header or it is inert, * 16 KB body cap, per-IP rate limit, fixed field allowlist, every logged field truncated (script-sample is attacker-influenced and can carry a whole inline script), * always 204, even for malformed input: a 4xx would reach the global error handler, which logs the offending body -- turning an open endpoint into a log-flood primitive. Nothing is persisted; reports go to the `csp` log tag. routes.manifest.json moves 199 -> 200, which is the freeze from PR 0 working as designed: the one new URL is visible as a reviewed +1 rather than slipping through. Swagger regenerated to match. Co-Authored-By: Claude <noreply@anthropic.com>	2026-07-27 15:19:26 -05:00
wtclaude	1079b3fc05	chore(server): freeze the URL surface with a generated route manifest ... PR 0 of the router domain split (docs/website/API_V2_PLAN.md § Phase 2). The split promises that admin.routes.js can be carved into one router file per business capability without moving a single URL. That promise has to be proved by a diff, not asserted in review — this lands the tool that proves it, with no router file moved. scripts/routeManifest.js walks the live Express stack (runtime introspection, not source parsing: route paths in admin.routes.js sit on the line *after* `adminRouter.get(`, which defeats greps) and writes a sorted { method, path } list to routes.manifest.json. It reproduces the frozen baseline in docs/website/api-route-inventory.json byte-for-byte — 199 public routes plus 2 on the internal listener — so the freeze is confirmed accurate, not just claimed. Scope is /api/** and /.well-known/** plus the internal app. The SPA catch-all, /uploads and /brand are filesystem-conditional static mounts, so including them would make the output depend on whether CI had built the client. Static mounts are not API contract. Also emits routes.guards.json — a review aid, not a contract: per route, the handler count and the *named* middleware on its mount chain. Router-level `use(noindex, isLoggedIn, staffOnly)` gates never appear in an individual route's own stack, so an extracted capability router that forgot to re-apply one would otherwise publish authenticated endpoints silently. Names are a hint only (requireRole(...) returns an anonymous arrow), but a vanished requireAuth is unambiguous — and the test suite asserts every /admin/** and /player/** route still carries it. The plan's optional unauthenticated-status snapshot was tried and dropped, as it allowed: against the dead-port mariadb pool the tests use, the sweep sits on the pool's acquire timeout and had not finished after two minutes. A flaky two-minute gate is worse than none; the requireAuth assertion covers the same regression deterministically. CI runs `npm run routes:manifest -- --check` on every PR, so a URL change can only merge by deliberately committing the new manifest. Co-Authored-By: Claude <noreply@anthropic.com>	2026-07-27 14:55:38 -05:00
wtclaude	c075ab981c	fix(moderation): windowValue must not fall back to the 30d total on a null column ... windowValue mapped only the 24h/7d keys and used `?? row.d30` as the fallback: const col = { '24h': row.d1, '7d': row.d7 }[key] ?? row.d30 so a null d1/d7 (which the function is documented to tolerate) returned the 30-day count instead of 0, inflating the 24h/7d moderation tiles. It happens to be masked today because `SUM(created_at >= ?)` nulls d1/d7/d30 only in unison, but the contract is wrong and the existing test used an all-null row that hid it. Map all three window keys explicitly so each reads its own column and a null coerces to 0 via `Number(col) || 0`. Add a regression test with a null narrow column and a non-null d30. Co-Authored-By: Claude <noreply@anthropic.com>	2026-07-22 13:14:02 -05:00