wtclaude
f89044b42e
The fifth chapter, and the template code it teaches out of. Events is the first
thing in the book that goes the other way — chapters 1-4 move data out of the
game and onto a page; an event changes a live world on a schedule, unattended.
**Chapter 5** covers the four declarations (budgets, option sources, leases,
actions), leads with the lease because EVENTS.md §H is right that it is the
primitive that travels and the spawn is the special case, and gives one section
each to the four things that are invisible until an outage: the envelope's
failure default, the idempotency passthrough, recording a resource before
confirming it, and under-declaring `cost`.
**Chapters 3 and 4 gain one section each** for the command plane, because
without them chapter 5 teaches a module to send an idempotency key to a sidecar
the book never told anyone to build a command path in. Both say at the top that
they are skippable until you want chapter 5.
**The template ships one of each declaration**, with `server/sidecarClient.js`
as the near end — a real timeout, a real key passthrough, a simulated transport
in one function marked for replacement. That file is named for the filename
`noGameConnection.test.js` already anticipated, so the test stays green now and
fires correctly the moment `deliver()` becomes a request.
Two things writing it found, both now in the chapter and beside the code:
* **An idempotency key belongs on a command, never on a question.** The first
draft keyed every call including the reads; an at-most-once store then
answers every future read with the first one's reply, forever. The lease
applied correctly and the module could no longer see it. Hence `ask` and
`send` as two functions.
* **A refusal's reason goes in `error`; core reads no other name.** The first
draft used `detail`, on the strength of the one place EVENTS.md §H mentions
it, and every refusal it produced was anonymous on the run console.
Proved by running the template's real declarations through core's real registry
at `edge` (all four accepted) and its real envelopes through the real
`events/dispatch.js` classifier.
**CI is RED on `checkCoreApi` and that is the mechanism working.** The template
now declares `coreApi: ^1.10.0` and `ci/core-ref.json` pins the engagement
cutover, where `main` is still 1.9.0. Equality is the check, a bump is meant to
turn this repo red until someone re-reads the chapters, and the pin move rides
in the events cutover (EVENTS_PLAN.md P16) as its own commit. Do not "fix" it.
Refs EVENTS_PLAN.md Phase 15, EVENTS.md §F, MODULE_API.md 1.10.0.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016wDDVXWMDz82WqE1i969r4
179 lines
9.9 KiB
Markdown
179 lines
9.9 KiB
Markdown
# The template module
|
|
|
|
A Runic Gateway module that builds, loads, and does almost nothing. Copy it,
|
|
rename it, and you have a running module before you have read a chapter.
|
|
|
|
Installed into a core, it adds:
|
|
|
|
- **three public pages** — `/examplegame/status`, `/examplegame/clans` and one
|
|
clan at `/examplegame/clans/:externalId` — and nav rows pointing at the first two;
|
|
- **three API routes** under `/api/v1/public/world` and `/api/v1/public/clans`,
|
|
described in an OpenAPI fragment core merges into its own `/api/docs`;
|
|
- **three tables**, prefixed `examplegame_`, created by an idempotent schema
|
|
fragment and dropped by a purge file;
|
|
- **a Team provider**, which makes this module the authoritative source of Teams
|
|
for the deployment — the one registration where core calls YOU and waits;
|
|
- **three inverted extension slots**, declared by this module on the clan page for
|
|
core to fill;
|
|
- **four event declarations** — a budget dimension, an option source, a lease and
|
|
one action that ledgers what it makes — so an event authored on the website can
|
|
reach the game and be undone afterwards;
|
|
- **both lifecycle hooks**, so there is something to see at boot and at shutdown.
|
|
|
|
That is deliberately less than your module will do. What it is *complete* about is
|
|
the shape: every seam a real module uses is here once, with the reasoning next to
|
|
it, and CI proves the whole thing still builds against a pinned core.
|
|
|
|
## The tree
|
|
|
|
```
|
|
module.json what core reads first — id, version, coreApi, mounts
|
|
server/
|
|
index.js register(ctx, api) — the entire server-side handshake
|
|
core.js the lazy accessors over ctx; read this second
|
|
boot.js onBoot / onShutdown, and the game-restart watch
|
|
sidecarClient.js the one file that talks to your sidecar — transport simulated
|
|
config/eventActions.js budgets, option sources, leases and actions — read chapter 5
|
|
db/schema.sql idempotent, replayed every boot
|
|
db/purge.sql destructive, run only by an explicit admin purge
|
|
model/worldStatus/ the .db.js / .model.js pair
|
|
model/clans/ the Team provider, its SQL, and the audience rule
|
|
router/public/ two routers, two controllers, the #swagger annotations
|
|
swagger/doc.js tags and schemas the annotations refer to
|
|
scripts/checkImports.js the module boundary, enforced
|
|
scripts/swaggerFragment.js generates swagger-fragment.json from your own routes
|
|
test/ the suites — start with entry.test.js
|
|
test/eventActions.test.js the four traps chapter 5 is about, each as a failing test
|
|
client/
|
|
vite.config.js the library build: anchored aliases, external: []
|
|
src/entry.jsx registers routes, nav and declared slots at evaluation time
|
|
src/core.js what core hands you: the UI kit (nine exports)
|
|
src/shim/ the four shared dependencies, re-exported from core
|
|
src/routes/public/ the pages — Clan.jsx is the one with slots in it
|
|
scripts/checkExternals.js asks the BUILT chunk whether a bare import survived
|
|
test/ build.test.js and registration.test.js
|
|
.gitea/workflows/release.yml packaging CI — Gitea
|
|
.github/workflows/release.yml the same, for GitHub. Keep one, delete the other.
|
|
swagger-fragment.json generated; commit it
|
|
```
|
|
|
|
Neither workflow runs while it sits inside the kit — a workflow is only read from
|
|
a repository root. They arm themselves when your copy is a repository of its own.
|
|
|
|
## Build it
|
|
|
|
```bash
|
|
npm ci --prefix server
|
|
npm test --prefix server
|
|
npm run check:imports --prefix server
|
|
|
|
npm ci --prefix client
|
|
npm run build --prefix client # → client/dist/entry.js, the chunk that ships
|
|
npm run check:externals --prefix client
|
|
npm test --prefix client # build FIRST: two of these tests read the chunk
|
|
```
|
|
|
|
`npm test` in `client/` passes with no build, by skipping the tests that need one.
|
|
That is on purpose — the suite has to be runnable before the build — and it means
|
|
**a CI job that tests without building is a job asking nothing.** Build first.
|
|
|
|
Regenerate the OpenAPI fragment whenever a route or an annotation changes:
|
|
|
|
```bash
|
|
npm run swagger --prefix server # writes swagger-fragment.json
|
|
npm run check:swagger --prefix server # fails if it is stale
|
|
```
|
|
|
|
## Install it
|
|
|
|
Three supported ways, and none of them builds anything on the operator's machine:
|
|
|
|
1. **Admin → Modules**, pasting the URL of an install manifest — the JSON the
|
|
release workflow attaches beside the tarball. This is how an operator installs
|
|
your module.
|
|
2. **The `MODULES` environment variable**, `<id>@<version>=<manifest URL>`, for a
|
|
deployment that declares its module set rather than clicking it.
|
|
3. **A directory on the volume.** Copy this whole tree to `<website>/modules/<id>/`
|
|
and restart. The fastest loop while you are developing.
|
|
|
|
For (3): **copy, do not symlink.** The loader lists directory entries and a
|
|
symlink is not a directory, so a linked module is skipped in silence.
|
|
|
|
## Rename it
|
|
|
|
Change `id` in `module.json` first, then work down the list. Nothing here is
|
|
subtle, and the suites catch most of a half-finished job: `schema.test.js` fails
|
|
the moment a table name stops matching the id, and `registration.test.js` fails
|
|
when a nav row stops matching its route.
|
|
|
|
Your id must match `^[a-z][a-z0-9-]{1,31}$`, must equal the directory name core
|
|
loads you from, and becomes your table prefix — so **no hyphen unless you enjoy
|
|
backticking table names**.
|
|
|
|
<!-- rename-sites -->
|
|
|
|
| File | What to change |
|
|
| --- | --- |
|
|
| `module.json` | `id`, `name`, `version`, the `mounts` prefix, `capabilities` |
|
|
| `.gitea/workflows/release.yml` | `GITEA_HOST` and `REPO`, under the `# CHANGE THESE` banner — the only two, and they are wrong until you do. (The `.github/` flavour needs nothing: GitHub supplies `GITHUB_REPOSITORY` and friends.) |
|
|
| `server/package.json` | package `name` and `description` |
|
|
| `server/core.js` | the message every accessor throws |
|
|
| `server/index.js` | the trigger, audience, template and rule-group ids — all four are namespaced with your module id, and core refuses them otherwise |
|
|
| `server/config/eventActions.js` | the budget, option-source, lease and action ids — four separate id spaces, each namespaced with your module id — and every command name the client sends |
|
|
| `server/boot.js` | the placeholder world name |
|
|
| `server/db/schema.sql` | every table name — the prefix must be your id |
|
|
| `server/db/purge.sql` | the same table names |
|
|
| `server/model/worldStatus/worldStatus.db.js` | the `TABLE` constant |
|
|
| `server/model/clans/clanProvider.db.js` | the `CLANS` and `MEMBERS` table constants |
|
|
| `server/model/clans/clanProvider.model.js` | `pageUrlTemplate` — it must match the route `client/src/entry.jsx` registers |
|
|
| `server/router/public/world.router.js` | the `#swagger.tags` name |
|
|
| `server/router/public/clans.router.js` | the `#swagger.tags` name |
|
|
| `server/swagger/doc.js` | the tag, and the `Examplegame…` schema prefix |
|
|
| `server/scripts/swaggerFragment.js` | the generated fragment's `info.title` |
|
|
| `server/test/_fakes.js` | `ctx.moduleId` |
|
|
| `server/test/entry.test.js` | the trigger id the world-status test asserts |
|
|
| `server/test/eventActions.test.js` | the action and lease ids it looks up, and the clan fixture |
|
|
| `server/test/worldStatus.test.js` | the fixture's world name |
|
|
| `server/test/clanProvider.test.js` | the fixture's world name |
|
|
| `server/package-lock.json` | **regenerated** — `npm install --prefix server` |
|
|
| `client/package.json` | package `name` and `description` |
|
|
| `client/vite.config.js` | the guard plugin's `name` |
|
|
| `client/src/core.js` | the console tag on the identity check |
|
|
| `client/src/shim/rg.js` | the console tag on the missing-global error |
|
|
| `client/src/entry.jsx` | `ID`, every route path and nav `to`, and the three `declareModuleSlot` names — core enforces that a slot is namespaced under your id |
|
|
| `client/src/routes/public/Clans.jsx` | the link to the clan page |
|
|
| `client/src/routes/public/Clan.jsx` | the three `<Slot name>` values and their `moduleId` |
|
|
| `client/test/registration.test.js` | the example path in the comment |
|
|
| `client/package-lock.json` | **regenerated** — `npm install --prefix client` |
|
|
| `swagger-fragment.json` | **regenerated** — `npm run swagger --prefix server` |
|
|
|
|
<!-- /rename-sites -->
|
|
|
|
That table is checked. `scripts/checkRenameSites.js` at the root of this kit
|
|
compares it against the tree on every pull request: a file that still mentions the
|
|
placeholder and is not listed fails the build, and so does a listed file with
|
|
nothing left to rename. A checklist nobody verifies is a checklist that is wrong
|
|
by the second edit.
|
|
|
|
**`server/sidecarClient.js` is not on that list and is not an oversight.** It
|
|
carries no placeholder id — its vocabulary is the game's, not the module's — so
|
|
the checker has nothing to hold it to. It is still the file you have the most work
|
|
in: replace `deliver()` with one request to your sidecar, replace the fake game's
|
|
verbs with your game's, and set `TIMEOUT_MS` to what your transport actually
|
|
waits. Chapter 5 is mostly about that file.
|
|
|
|
Two things you do **not** rename: the mount prefixes `/world` and `/clans` need
|
|
not be your id (the server's prefix namespace is shared with core's — `/status`,
|
|
`/settings`, `/version`, `/contact` and `/teams` are already taken, which is why
|
|
the clan router is not mounted at the obvious name), and the `world` / `clan`
|
|
naming throughout is ordinary vocabulary you should replace with your own domain's
|
|
when you replace the feature. **`clan` in particular is the point rather than the
|
|
placeholder:** core's word is Team, yours is whatever your game says, and the
|
|
provider exists because core cannot pick one.
|
|
|
|
## Licence
|
|
|
|
GPL-3.0-or-later, like everything else in this project — see
|
|
[LICENSE.md](LICENSE.md). This directory is meant to be copied and made yours; it
|
|
carries that licence, and so does anything derived from it.
|