Bundle Station Master v0.5.3: games in progress, and a way to end one

Pin moves to v0.5.3, package version to 0.5.3:0.

The health check no longer just probes a port. It fetches the server's own
/api/health and reports what it says — "Multiplayer server is ready — 3
games in progress", with ", 1 waiting to start" appended only when a lobby
exists and "no games in progress" on an idle server. A server that doesn't
answer is reported as STARTING, never failed: the server replays its saved
games before binding its port, so a boot legitimately looks like nothing is
listening, and calling that a failure makes an ordinary restart look like a
crash.

Two new actions, both only-running. Games in Progress is read-only and
lists every game and lobby with players, Day/Stage/phase, who it waits on,
when it started and when it last moved. Manage Game picks one from a
dropdown built live from the server and either exports it or ends it —
ending being the only way a game finishes other than being played out,
since an abandoned game otherwise stays active and is resumed on every
restart forever. Ending always returns the deleted game's save, so nothing
is destroyed without being handed back first.

They are only-running because none of it is readable from disk: a save is a
seed plus a list of moves, so whose-turn-it-is exists only after a replay
through the engine, which lives in the game repo rather than here. The
running server has already done that work and is asked for the answer.
startos/serverApi.ts is the single place that asks.

store.json gained adminSecret (32 chars) beside joinSecret, seeded on
install and backfilled on update for a volume written before the field
existed. It is deliberately NOT the join secret: every player holds that
one, so gating a delete with it would let anyone at the table destroy
anyone else's game. init/generateJoinSecret.ts is renamed generateSecrets.ts
now that it mints both.

Also brought getJoinSecret's result strings under i18n(). They shipped as
plain strings two commits ago, which actions.md is explicit about — every
user-facing string including result titles, messages and thrown errors.
The new actions follow it, so the old one shouldn't be the odd one out.

Verified on phoenix.local, installed as an UPDATE from 0.5.2:0 rather than
a fresh install, which exercised three things at once: the boot log line
("Resuming 1 saved game(s)…"), the engine-version refusal firing for real
on a game recorded under 0.5.2, and the adminSecret backfill (store.json
came out with both secrets, 24 and 32 chars). Then, from inside the
container: the package-generated admin secret authenticating against
/api/games (200) while a wrong one is refused (403), health counts tracking
0 -> lobby 1 -> active 1 through a create/bot/start, and every field the
actions render present and correct on the listing.

NOT verified: the actions' own forms and result rendering. `start-cli
package action run` fails with a client-side deserialization error on every
action on this box — including the already-shipped get-join-secret and
actual-budget's equivalent — so it is a start-cli problem, not this
package's. The data path underneath them is verified above; the SDK
form/result rendering needs the web UI.

A test game (TRESTLE-3221, Alice + a bot) is left running on the box so
there is something for Games in Progress to show.
This commit is contained in:
Jesse
2026-08-21 16:00:05 -04:00
parent ea012f1329
commit c95620d566
20 changed files with 801 additions and 85 deletions
+60 -12
View File
@@ -52,19 +52,27 @@ One volume, `data`, mounted at `/data` (`DATA_DIR`).
| --- | --- |
| Volume names | `data` |
| Mount points | `/data` |
| StartOS files | `store.json` — holds the join secret (see File Models) |
| Database | None — flat files. Each game is `games/<gameId>/game.json` (`{ engineVersion, seed, config, playerNames, history, status, createdAt }`) plus `turn-timings.json`, an `index.json` naming every game, and lobby state for games not yet started |
| StartOS files | `store.json` — holds the join and admin secrets (see File Models) |
| Database | None — flat files. The server holds any number of games at once: each is `games/<gameId>/game.json` (`{ engineVersion, seed, config, playerNames, history, status, createdAt, lastMoveAt, botSeats }`) plus `turn-timings.json`, with a top-level `index.json` naming every game and lobby state for those not yet started |
## File Models
One StartOS-managed file, `store.json`, on the `data` volume.
- **`store.json`** — JSON, holds `joinSecret` (a string). Seeded on install with a random
24-character value (`init/generateJoinSecret.ts`) — the daemon will not start without one, so
it is never left unset. Rewritten only by the **Get Join Secret** action, which generates a new
value on every run; the value is otherwise never touched, so a hand edit to it survives until
the action is next run. `main.ts` reads it reactively, so a rewrite restarts the daemon with the
new value automatically.
- **`store.json`** — JSON, holding two independent secrets, both seeded on install by
`init/generateSecrets.ts` and both read reactively by `main.ts`, so rewriting either restarts the
daemon with the new value.
- `joinSecret` — 24 characters. What players need to create or join a game. The daemon will not
start without one, so it is never left unset. Rewritten only by the **Get Join Secret**
action, which mints a new value on every run.
- `adminSecret` — 32 characters. Gates the server's `/api/games` routes, which the two game
actions use. **Deliberately not the join secret**: every player holds that one, so gating a
delete with it would let anyone at the table destroy anyone else's game. It is never shown to
a player and never leaves the package except as the daemon's `ADMIN_SECRET`. Backfilled on
update for a volume written before this field existed, and otherwise never rewritten.
Neither key is re-asserted on start, so a hand edit to either survives until the relevant action
is next run.
Everything else under `/data` — `games/`, `index.json`, lobby and session state — is the
application's own persistence, written directly by the server process, not by a StartOS file
@@ -83,13 +91,26 @@ different one in the same game.
## Installation and First-Run Flow
No setup wizard. On install, a join secret is generated and stored immediately (see File Models),
No setup wizard. On install, both secrets are generated and stored immediately (see File Models),
and a critical task is raised pointing at **Get Join Secret** — the service starts and is usable
the moment the daemon is healthy, but a player cannot create or join a game until the join secret
has been retrieved and shared with them.
**Updating the package ends every game in progress.** A save records the engine version that wrote
it and the server refuses to resume one recorded under different rules, logging the refusal and
leaving the file untouched. This is upstream's deliberate design, not something this package works
around: a move that was legal under the old rules may not be under the new ones. Let games finish
before updating, or accept losing them — rolling the package version back makes them loadable
again, since nothing is deleted.
## Actions
Two of the three read or change the games on the server, and both are `only-running`: what they
report exists only inside the live server process. A save is a seed plus a list of moves, so
"whose turn is it" is answerable only by replaying the game through the engine — which lives in
the game repo, not in this package. The server has already done that work and is asked for the
answer.
- **Get Join Secret** (`get-join-secret`) — run this any time you want to read the current join
secret, or to invalidate it and issue a new one. Every run **generates a fresh secret,
overwrites the stored one, and restarts the daemon** with it — there is no read-only mode.
@@ -97,6 +118,21 @@ has been retrieved and shared with them.
the lobby door, not an in-progress session); it only invalidates the old value for anyone who
has not yet joined or created a game. Completes in a few seconds, safe to repeat.
- **Games in Progress** (`games-in-progress`) — read-only, changes nothing, safe to run at any
time. Lists every game and lobby on the server with its code, players, Day/Stage/phase, who it
is waiting on, when it started and when it last moved. Run it to find a game that has stalled —
a `Last move` days old with a named player under `Waiting on` is someone who is not coming back.
Returns quickly; the server answers from memory.
- **Manage Game** (`manage-game`) — pick a game from a dropdown built live from the server, then
either **Export** it (returns the complete save as copyable text and changes nothing) or **End**
it (deletes it from the server, disconnects anyone still watching, and removes its files and
index entry). **Ending cannot be undone and is not idempotent** — a second attempt reports that
the game no longer exists. It always returns the deleted game's save, so nothing is destroyed
without being handed back first; that text is the only remaining copy, so keep it if the game is
worth replaying. This is the only way a game ends other than being played to a finish: an
abandoned game otherwise stays active and is resumed on every restart indefinitely.
## Tasks
- **Get the join secret to share with players** — raised on install, severity `critical`. Points
@@ -105,9 +141,18 @@ has been retrieved and shared with them.
## Health Checks
- **Multiplayer Server** — `checkPortListening` against the daemon's port. "Not ready" means the
process has not yet bound its port; on a normal start this clears within a second or two; on a
cold container start it briefly reflects the daemon starting up.
- **Multiplayer Server** — fetches the server's own `/api/health` and reports what it says:
*"Multiplayer server is ready — 3 games in progress"*, with *", 1 waiting to start"* appended
only when a lobby exists, and *"no games in progress"* on an idle server. So the check that
proves the server is answering also says how much is going on.
A server that does not answer is reported as **starting, never failed**. The server replays its
saved games before binding its port, so a boot legitimately looks like nothing is listening, and
calling that a failure would make an ordinary restart look like a crash. Replaying measures
around 100 ms per game and only unfinished games are replayed, so in practice this window is a
fraction of a second. A check stuck on "starting" for much longer means the daemon is failing to
come up — read the service logs, where a refused resume names the game and the version that
wrote it.
## Backups and Restore
@@ -148,11 +193,14 @@ file_models:
startos_managed_env_vars:
- DATA_DIR
- JOIN_SECRET
- ADMIN_SECRET
dependencies: none
interfaces:
ui: { type: ui, port: 8081 }
actions:
- get-join-secret
- games-in-progress
- manage-game
tasks:
- { action: get-join-secret, severity: critical }
health_checks: