Smoke e2e, docs consistency pass, status summary

Built: e2e/run.js + lib.js (playwright-core, in-process server, temp DB): desktop flow, phone touch portrait/landscape, layout matrix on 5 viewports x pop/map/trade/world (overflow + console errors), WebSocket push incoming-banner without reload. 61/61 checks, ~54 s, identical over 4 runs; the push and overflow checks were shown to fail when the behaviour is removed.
Docs: fixed stale numbers/claims in DESIGN, DECISIONS, BALANCE, API (undocumented routes, rate limits, notification types), DEPLOY, NEXT (status-at-a-glance on top). Deploy path exercised in a scratch dir: migrations, healthz, signup/build, admin CLI, SIGKILL catch-up, backup restore.

Tested: npm test 207/207, npm run e2e 61/61, bot run 50x14d INVARIANTS OK.
NOT tested: Chromium only; no systemd/nginx Proxy Manager/Node 22.13 run; e2e does not cover units, alliances, messages, trade or end-game flows beyond empty-state rendering; no nb, PWA or polling-fallback e2e; docs/workflows/ still empty.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Q2MJaQ5LXAHzGnTDgceT14
This commit is contained in:
jvanvik 2026-10-11 20:34:35 +02:00
parent 931f59e11e
commit cc0524de5e
8 changed files with 533 additions and 38 deletions

View file

@ -2,6 +2,41 @@
Honest status, updated at the end of every stage.
## Status at a glance (checked 2026-10-11, Node 24.21)
Where it stands: stages 0-6 are built on the server and in the web client (economy, world, military, expansion, social, trade, end game,
WebSocket push); stage 7 is partly done (bot harness + first balance pass, admin CLI, deploy files). **The game is not balanced, not
playtested by humans, and has never run on the real target (Debian LXC + systemd + nginx Proxy Manager).**
Runnable and checked just now:
- `npm test`: 207 tests pass in about 7 s (rules as pure functions, commands/events/scheduler with a fake clock, REST over HTTP with every
response checked against its schema, push with a real `ws` client, client logic, bot harness, admin CLI). `npm run openapi` leaves
`docs/openapi.json` unchanged (it is in sync with the route table: 68 paths).
- `node tools/bot.js --players 50 --days 14 --speed 1`: about 3 s, `INVARIANTS OK`. `node tools/admin.js help` works.
- The deploy path from DEPLOY.md in a scratch directory, without systemd: first boot (migrations, world), `/healthz`, signup, a build,
`admin.js` status/worlds/users/inspect/events/replay/backup/verify-backup/ban/grant, SIGTERM + restart (state kept), SIGKILL + restart
after a build fell due (caught up in order), restore of a snapshot into a fresh `DB_PATH`.
- `npm run e2e` (`e2e/run.js`, Playwright): see the e2e section of this file, if present; not re-run for this status.
Never run: real devices, Safari/iOS, a Proxmox LXC, a unit under systemd, the backup timer firing, nginx Proxy Manager (WebSocket upgrade,
idle timeouts, real client IPs), Let's Encrypt, a restore on the real box, load with many real sockets, any human player. Node 22.13 (the
stated minimum) was not run, only 24.21.
Known gaps, consolidated (the sections below have the detail and the reasoning):
- **Balance:** nothing is tuned beyond B1/B2 (BALANCE.md). Open: a 3x world's end game is as long as a 1x world's; after the opening days
nobody can contest a built-up landing site (no garrisons, E1); raid loot is split evenly and destroyed on overflow (S4); trade escrow
refunds are clipped at the Rack hall cap without a notice (S2); the capital runs out of things to build long before the backbone opens;
the bots are not humans.
- **Game rules not built:** cancelling training, sitters, night protection, a command to choose a new capital, power draw for units in
transit, alliance rename/description, trade order book / price history / counter-offers, multi-link trade deals.
- **Server:** no `backbone_open` push (sites are created lazily, E2); no `incoming` for confederates and no `town` hint for reinforcing
owners; token revocation reaches an open socket only at the next 30 s ping; tokens never expire and there is no change-password route; no APNs/FCM
sender; `reports.id` can be reused after a full cleanup (S3, low); no recovery sweeper if an `arrive`/`return` handler ever throws (R1);
HTTP connections per IP are not capped; admin `end-world` is a flag flip without ranking snapshot (DEPLOY.md section 6).
- **Client:** no service worker (no offline mode), no light theme, no unit icons or battle simulator, no sound/system notifications; a few
one-tap destructive actions without confirmation; unread-badge state is partly in localStorage; ended-world locking is a DOM sweep.
- **Docs:** `docs/workflows/` (planned stage workflows, CLAUDE.md layout) is empty: no stage workflow was ever written there.
- **Not run in a browser:** takeover/capture flows, the confederation `alliedIncoming` view, real devices (see the client sections).
## Done
- Stage 0 skeleton: db + migrations, clock, scheduler with catch-up, router, auth/tokens, error envelope, openapi generation, static server.
- Stage 1 economy (server): lazy resources, buildings, build queue, storage caps, power battery.
@ -22,8 +57,8 @@ Not done:
is enforced by the military stage (`pactBlocks`).
- Web client: see the client sections below; WebSocket push (stage 6) exists server-side and in the client.
- Message retention/cleanup of old rows, alliance rename/description, mass-mail abuse reporting, sitter accounts.
- Rankings are not cached; battle rankings stay empty until the military stage writes `operator_stats`.
- Not run: Playwright, load, or any bot balance run; the social numbers in `SOCIAL` (limits, TTLs, role table) are first guesses.
- Rankings: the footprint part has a 5 s per-world cache (review R1); battle rankings are filled from `operator_stats` now that the military stage writes it.
- Not run: Playwright, load; the social numbers in `SOCIAL` (limits, TTLs, role table) are first guesses (the bot runs only exercised alliances/NAP/confederation lightly).
## Stage 3/4: military and expansion (server only)
Built (migration `002_military.sql`: `town_units`, `stationed`, `town_research`, `town_power`, `movements`, `reports`, `report_recipients`,
@ -55,13 +90,13 @@ Built: `public/` vanilla JS, no build step, strict-CSP friendly (no inline scrip
map (`js/render.js` canvas: pan, pinch, wheel, keyboard, culling; chunked `GET /map` cache; tile info sheet), alerts
(`GET /notifications`), settings (language, device tokens + revoke, logout).
- `js/api.js`: bearer token, serverTime offset, retry/backoff (network, 429 + Retry-After, 502-504), `Idempotency-Key` per intent,
`ApiError.code`, event emitter with a reserved `push` event (no WebSocket client yet).
`ApiError.code`, event emitter with a `push` event (the WebSocket client `ws.js` came with the military client, below).
- `js/i18n.js`: en + nb, all player-facing names; `PWA`: manifest + icons (no service worker, so no offline mode).
- Tests: `test/client-i18n.test.js` (key parity, names, error codes, formatting), `test/client-api.test.js` (retry, idempotency, offset).
- Looked at with headless Chromium screenshots (phone portrait, phone landscape, desktop) and one scripted signup/build/cancel/map-tap
flow on a phone profile. Not run: real devices, Safari/iOS, Playwright suite.
Gaps: the unread badge is stored in localStorage (no "mark read" route); `/me` exposes the world seed which the client ignores;
no push, no service worker, canvas has no inertia/fling, no light theme.
no service worker (push was added later, see the WebSocket section), canvas has no inertia/fling, no light theme.
## Client: social (alliance, messages, rankings)
Built (all in the nav "More" group, `navGroup: 'more'`): `screens/alliance.js` (found with Peering office gate and translated server
@ -162,7 +197,7 @@ Built (More group; strings in `strings/{trade,world,alerts}.js`, en + nb):
minute. Confederate Carol gets no push for `alliedIncoming` (known server gap): it shows when the Moves screen is opened or the poll runs, and never in her badge.
Found and fixed in the client: `report` pushes now also refetch movements (the incoming banner used to linger up to a few seconds after the arrival).
Not done / not claimed:
- Not run: real devices, Safari, a socket behind nginx Proxy Manager, throttled networks, the Playwright suite (`e2e/` is still empty), long lists (offers > 25 per
- Not run: real devices, Safari, a socket behind nginx Proxy Manager, throttled networks, the full Playwright suite (only the smoke e2e exists), long lists (offers > 25 per
filter paged only up to what the sweep seeded).
- Ended-world locking is a DOM sweep, not per-button wiring: a new primary/danger button that is NOT a game command must carry `data-keep`. Messages, ranking and
settings screens are exempt by selector. Open send/trade sheets that were opened before the end stay usable until the next DOM change or a refused command.
@ -187,7 +222,7 @@ one tick are merged. Small edits outside the new files: `scheduler.js` (outbox,
Tests: `test/push-ws.test.js` (auth ok/bad/timeout, origin, path, per-IP cap and its release, rate limit, bad budget, oversize frame, dead
socket, revoked token, banned user, shutdown, REST with no socket) and `test/push-game.test.js` (build/train done, incoming only to the
defender, report/message/alliance invite hints, recall, coalescing, rollback). Real `ws` client, fake clock, port 0. `npm test`: 113 pass
(run after the push work, with the other agents' changes in the tree at that moment).
when this was written (207 on 2026-10-11, whole suite).
Not done / not claimed:
- The client now exists (`public/js/ws.js`, see "Client: military, expansion, WebSocket") and was run against this server in a headless browser; not through a proxy.
- Revocation closes the socket at the next ping tick (default 30 s), not instantly: `POST /auth/logout` and token deletion do not call push.
@ -220,8 +255,8 @@ Not done / not claimed:
- No `backbone_open` push at the moment the sites appear unless something touches a site first (E2); clients see the phase by polling status.
- Trade: no multi-link deals (each side <= 500), no price history or order book, no counter-offers, no notification when a new offer appears
in reach, offers are not hidden from enemies, the escrow of a taken-over POP goes to the conqueror.
- Ended worlds: movements still `out` and queued builds are left as they were (events cancelled, E3); there is no admin "end world now" or
"reset" yet (stage 7 world lifecycle: the `worldEnd` event can be enqueued by hand); several winners are impossible by design.
- Ended worlds: movements still `out` and queued builds are left as they were (events cancelled, E3); `tools/admin.js end-world` only flips the status (no snapshot, no event cancellation) and `reset-world`
wipes a world's rows; neither runs the real `worldEnd` event (see DEPLOY.md section 6); several winners are impossible by design.
- The ranking snapshot is the same numbers as `/rankings`, computed once; `/rankings/*` after the end still compute live from the frozen state.
- Client for all of this: see "Client: trade, end game, alerts" above.
@ -243,5 +278,13 @@ reading the constant); trade escrow refunds are clipped at the Rack hall cap sil
the capital runs out of things to build ~50 days before the backbone opens at 4 sittings a day; a built-up landing site is out of reach of any
single-POP army (no garrisons, E1), so there is no fight for a site after the first days.
## Stage 7 (ops part): admin CLI, deploy files
Built: `tools/admin.js` (status, migrate, worlds, create-world, end-world, users, operators, ban/unban/revoke-tokens, inspect-operator/-town, events,
replay-events [--simulate], backup/verify-backup (VACUUM INTO, verified, pruned), reset-world, grant), `deploy/` (service, backup service + timer,
`upstream-admin` wrapper), `docs/DEPLOY.md`. Tests: `test/admin-cli.test.js`. Run by hand on 2026-10-11 in a scratch directory: see "Status at a glance".
Not done / not claimed: nothing of it has run under systemd or on Debian 13 (DEPLOY.md lists what was and was not run); no load test with real sockets;
world lifecycle through the CLI is partial (above); no scheduled "create next world".
## Not done
- Everything else. See CLAUDE.md "Working in stages".
- Stage 7 remainder: balance passes beyond B1/B2 with the open items above, a real world lifecycle (start, natural end, reset) driven from the CLI,
load test over HTTP/WebSocket, the full e2e suite and a human playtest. Everything else in CLAUDE.md "Working in stages" is built.