diff --git a/.claude/skills/edit-the-game/SKILL.md b/.claude/skills/edit-the-game/SKILL.md index 7dc75dd..aca2564 100644 --- a/.claude/skills/edit-the-game/SKILL.md +++ b/.claude/skills/edit-the-game/SKILL.md @@ -14,6 +14,7 @@ load, so splitting code across files costs nothing at runtime. Why it works this src/index.html the shell:
, static markup, ``, `` 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,16 @@ 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 (``): 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 })`. Where agent code must change what the game does (agent mode + locks the clock, adds a Settings section and a HUD badge), the game calls `HOOKS.x?.()` and reads + `UI.clockLocked` (`50-state.js`), and agent code fills them in: add a hook there rather than an `if` for + the agent in a game file. 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 diff --git a/.claude/skills/github-pages/SKILL.md b/.claude/skills/github-pages/SKILL.md index 205db5b..c0ed652 100644 --- a/.claude/skills/github-pages/SKILL.md +++ b/.claude/skills/github-pages/SKILL.md @@ -31,6 +31,10 @@ one, redesign the feature. - **Limits:** about 1 GB for the whole site, 100 MB per file. - **Paths:** the site lives at the domain root (`site/CNAME`), so `/` paths are fine; unknown paths get `404.html`. +- **Local tools are not hosting.** `npm run dev` and the MCP server (`npm run mcp`, also over `--http`) + run on a developer's own machine against a checkout; nothing they serve is deployed, and the game + never depends on them. Their code stays out of `_site/` (`src/agent/` is development-only, see + `docs/adr/0004-dev-only-code.md`). ## How it deploys diff --git a/.claude/skills/write-tests/SKILL.md b/.claude/skills/write-tests/SKILL.md index efe406c..42937b9 100644 --- a/.claude/skills/write-tests/SKILL.md +++ b/.claude/skills/write-tests/SKILL.md @@ -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 diff --git a/CHANGELOG.md b/CHANGELOG.md index 919ff0f..cb6a431 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,13 @@ All notable changes to this project are documented here. The project follows ## [Unreleased] - A new button next to the speed controls opens a NOC screen in a window of its own, to keep on a second display beside the map. It is a dark wallboard with a live world map of your links and POPs, traffic and money graphs, alarms, and your hottest ports with their upgrade buttons, which work on the running game; click a POP to see its ports. Details has the full dashboard, and Full screen fills the display. The new window only shows and sends clicks: your network is still played and saved in the game window. Phones do not show the button. +- The NOC intern has a new order, Keep peering headroom, that adds capacity to your PNI and IX ports before they fill up (#234). A single port at a POP with several routers gets a second port in a LAG; any other port moves up to the smallest size that fits. It has the same Headroom and Budget dials as the transit order, and it waits out DDoS floods, link faults and PNI augments already on order. The monthly figure in the intern's log now counts IX ports too. +- Latency customers only ask for a ceiling something you can build meets. Before, a Mars ground station could ask for 4.3 ms between Pevek and Anadyr, where the only sea route takes 7.7 ms at best. (#273) +- Money now shows billions (`$1.20B`) and bandwidth shows petabits (`1.00 Pbps`) instead of running on in millions and terabits, including on the NOC graph and the fiber labels on the map. +- DE-Kicks ports stop getting dearer once they cost four times the list price. Before, the yearly price harmonisation kept compounding, so a long game ended up paying $100k a month for one port at Frankfurt or Mumbai. +- An exchange port, a transit port or a PNI can now be stepped down one size from its panel, so shrinking a port no longer means leaving and rejoining (a PNI cannot while an augment is on order). +- The traceroute can follow the metrics, the lowest latency or the quietest links, like a customer circuit. +- If you run the game on your own computer, an AI agent can now play it in your browser while you watch. Turn the Agent API on in Settings (the section only appears in a copy of the game you run with npm run dev, never on seriesoftub.es) and point an AI client at the game's MCP server: every move happens live on your screen, and docs/MCP.md in the repository explains the setup. You choose the clock: a pace from one simulated day every 30 seconds to 5 minutes, which nobody can pause and which waits while no agent is connected, or the agent moves time itself. Your game, your settings and the windows you open stay yours. - Every capital in Africa is on the map, which puts every capital of the world in the game: 33 new cities from Porto-Novo, Bamako and Niamey to Khartoum, Juba, Mogadishu, Brazzaville, Tripoli, Rabat and Pretoria. Each country brings its real telcos, Nigeria gets its wholesale backbone up to Abuja, and the island capitals of the Comoros, São Tomé and Equatorial Guinea sit on their real cables. - Every capital in South, East and Southeast Asia and the Pacific is on the map: Thimphu, Kathmandu, Bandar Seri Begawan, Phnom Penh, Vientiane, Ulaanbaatar, Naypyidaw, Pyongyang, Dili, Hanoi and Wellington, with the island capitals Tarawa, Palikir, Yaren, Funafuti and Port Vila. Each country brings its real telcos, North Korea reaches the world only through China and Russia, and the islands hang on their real cables. - Every capital in the Middle East, the Caucasus and Central Asia is on the map, from Yerevan and Baku to Kabul, Tehran, Baghdad, Jerusalem, Amman, Kuwait City, Beirut, Damascus, Sanaa and Manama, with Ankara and Islamabad. Each country brings its real telcos, and Bahrain is an island on the Gulf's cables. diff --git a/CLAUDE.md b/CLAUDE.md index e383fa1..439c4a1 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -5,7 +5,8 @@ https://seriesoftub.es, hosted on GitHub Pages. The game is one static page with Its source is many small files in `src/` (`src/styles/*.css`, `src/game/**/*.js`, the shell `src/index.html`); the build pastes them together, in path order, into a single `index.html`, the same one-file page players have always loaded. Static files (dictionaries, icons, service worker) -live in `site/`. +live in `site/`. `src/agent/` (the facade the MCP server plays through) goes into the development page only, +never into the page players get, and nothing in `src/game/` may use it (`docs/adr/0004-dev-only-code.md`). Read these before larger changes: @@ -20,7 +21,7 @@ Read these before larger changes: ```bash npm ci # once: installs jsdom for the tests -npm run dev # play while developing: http://localhost:8080, reloads on save +npm run dev # play while developing: http://localhost:8080, reloads on save (--host to share) npm test # node:test + jsdom, every tests/*.test.js, must stay green node scripts/i18n-check.js # must report "0 missing, 0 unused, 0 broken" (and sorted dictionaries) node scripts/i18n-add.js FILE.json # add/change/remove translations (see `add-strings`) @@ -28,7 +29,7 @@ npm run build # builds _site/ for GitHub Pages (assembles src/, s npm run serve # build and serve the production site locally npm run perf -- --base-ref origin/main # big-network benchmark vs main (see `performance`) npm run perf -- --base-ref origin/main --browser # the same, also in real Chromium (desktop and phone) -npm run mcp # the game as a local MCP server for AI clients (docs/MCP.md) +npm run mcp # the game as a local MCP server for AI clients, stdio or --http (docs/MCP.md) ``` ## Hard rules diff --git a/README.md b/README.md index cc6e3fb..ec085fa 100644 --- a/README.md +++ b/README.md @@ -52,11 +52,11 @@ and remembers the one you pick under Settings or on the title screen. ```sh npm ci -npm run dev # development server: assembles src/ on every request, reloads on save +npm run dev # development server on localhost (--host to share): assembles src/ on every request, reloads on save npm test # headless tests: boot, geography, a year of play, every incident, every panel npm run build # writes the site for GitHub Pages to _site/, with version and date stamped in npm run i18n:check # lists text missing from (or stale in) the translations -npm run mcp # the game as an MCP server, so an AI client can play and debug it (docs/MCP.md) +npm run mcp # the game as an MCP server, so an AI client can play and debug it, headless or in your tab (docs/MCP.md) ``` ## Community diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 9734907..f067aa0 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -11,8 +11,10 @@ src/ the game page, in pieces i18n/en.js the English for every label → inlined at the top of the page's `; return html.replace('', `${hint}${RELOAD}