MCP: the agent facade moves into src/agent/, assembled into the development page only

The command tables and the page-side reads, screens and dispatch (scripts/lib/mcp-commands.js and
mcp-page.js) become src/agent/, the facade window.TUBES.call(tool, args) in the page's own scope.
A new <!-- @include-dev agent --> line in src/index.html pastes it in after the game, but only in the
development page (npm run dev, the MCP server, i18n-check, tests that ask with load({agent:true})).
The build drops the line whole: _site/ is byte for byte what main builds.

Tests load the page players get by default, the build test fails if anything outside src/agent/ names
the facade's api/API_ names, and the pages test checks the built page carries none of it and still
plays. ADR 0004 records the rule.
This commit is contained in:
Wolfgang Nagele 2026-11-03 14:51:42 -05:00
parent b2366ed260
commit 5b76685e5c
27 changed files with 1052 additions and 869 deletions

View file

@ -14,6 +14,7 @@ load, so splitting code across files costs nothing at runtime. Why it works this
src/index.html the shell: <head>, static markup, `<!-- @include styles -->`, `<!-- @include game -->`
src/styles/NN-*.css CSS, in order (phones last)
src/game/NN-area/NN-*.js the game script, in order (see the map in docs/ARCHITECTURE.md)
src/agent/NN-*.js the agent facade the MCP server drives: in the development page only
site/ static files copied as they are (dictionaries, icons, service worker)
```
@ -34,7 +35,8 @@ npm test -- tests/peering.test.js # one suite
```
A browser error points at a line of the assembled page; the dev server prints the `src/` file and line
next to it. `npm run page -- -o /tmp/page.html` writes the assembled page if you want to look at it.
next to it. `npm run page -- -o /tmp/page.html` writes the page players get if you want to look at it;
`npm run page -- --source --dev -o /tmp/page.html` the development page `npm run dev` serves.
## Where new code goes
@ -48,9 +50,13 @@ next to it. `npm run page -- -o /tmp/page.html` writes the assembled page if you
- **Actions:** add `name:(args)=>{…},` to the matching `src/game/90-actions/*.js`. Only
`10-interface.js` declares `const ACT={`; the others are `Object.assign(ACT,{ … });`. A new area can get
a new `NN-area.js` file of that second form. The MCP server types every action: a new one also gets
an entry in `scripts/lib/mcp-commands.js` (a game command with its argument domains, a view, a draft
or a session action) or in the server's `DENY` list in `scripts/lib/mcp-page.js`;
`tests/mcp-commands.test.js` fails until it has one.
an entry in `src/agent/20-commands.js` (a game command with its argument domains, a view, a draft,
a session action, or `API_DENY`); `tests/mcp-commands.test.js` fails until it has one.
- **Agent code** (`src/agent/`, the facade the MCP server plays through) is assembled into the
development page only (`<!-- @include-dev agent -->`): players never download it. Its top-level names
start with `api`/`API_`, and **nothing in `src/game/` may name them**: that would work in `npm run dev`
and break for players (`tests/build.test.js` checks). Tests load the players' page; a test of the
facade asks for `load({ agent: true })`. See docs/adr/0004-dev-only-code.md.
- **Panels and modals:** `93-ui/` (HUD, side panels), `94-dashboard/` (NOC dashboard, bank), `95-modals/`.
- **Styles:** the matching `src/styles/*.css`; phone rules go in `60-phone.css`.
- **Data tables** (cities, cables, networks): one entry per line, and keep id-keyed objects such as

View file

@ -7,7 +7,8 @@ description: Write deterministic jsdom tests for Series of Tubes features and fi
Tests use `node:test` and `tests/harness.js`, which assembles the game page from `src/`
(once per test file) and loads it in jsdom with the animation loop off, a seeded `Math.random` and a recording fake canvas.
Code runs inside the page through `ev()`.
Code runs inside the page through `ev()`. `load()` is the page players get; tests of the agent facade
(`src/agent/`, `window.TUBES`) ask for the development page with `load({ agent: true })`.
## Pattern