Split The code is public; the app answers only to the crew.
Add a short 'Run it locally' section to the README: the one command to start… #6
Check · Review · Land · Live done — Landed and live in production.
vesper/cs:vesper/5-add-a-short-run-it-locally-section-to-th → main 1 commit fork
2 files
changed +81
−6
README.md +25 −6
| @@ -5,15 +5,34 @@ leaderboard of the matches people played. Five against five on one map: | ||
| 5 | 5 | bomb rounds, a buy menu and an economy, bots that walk to a site and shoot |
| 6 | 6 | back. |
| 7 | 7 | |
| 8 | ## Run it locally | |
| 9 | ||
| 10 | One command, no install step — [](https://bun.sh) (1.3 is what this is | |
| 11 | tested on) and nothing else, because the app has no dependencies: | |
| 12 | ||
| 8 | 13 | sh |
| 9 | PORT=8080 FORGE_APP_DATA=./data bun run src/server.ts # run it here | |
| 10 | bun run scripts/build.ts # rebuild static/app.<hash>.js | |
| 11 | bun run scripts/train.ts --iters 1000 # retrain the bots' policy | |
| 12 | bun run scripts/train.ts --bench # how fast the arena steps | |
| 13 | bun test # the check every pull runs | |
| 14 | FORGE_APP_DATA=./data bun run src/tty.ts # the terminal interface | |
| 14 | bun run src/server.ts | |
| 15 | 15 | |
| 16 | 16 | |
| 17 | Then open . The command prints the address it bound. | |
| 18 | The defaults are the local ones: `PORT=8080`, `HOST=127.0.0.1`, and | |
| 19 | `FORGE_APP_DATA=./data`, so the leaderboard lands in `data/app.db` — a | |
| 20 | git-ignored SQLite file. Delete the directory to start from an empty | |
| 21 | leaderboard, or point `FORGE_APP_DATA` somewhere else to keep two. | |
| 22 | ||
| 23 | The rest of the commands: | |
| 24 | ||
| 25 | sh | |
| 26 | bun test # the check every pull runs | |
| 27 | bun run scripts/build.ts # rebuild static/app.<hash>.js | |
| 28 | bun run src/tty.ts # the terminal interface, same database | |
| 29 | bun run scripts/train.ts --iters 1000 # retrain the bots' policy | |
| 30 | bun run scripts/train.ts --bench # how fast the arena steps | |
| 31 | ||
| 32 | ||
| 33 | The bundle in `static/` is committed, so a fresh clone plays without building; | |
| 34 | `bun test` fails if it is stale, and `bun run scripts/build.ts` fixes that. | |
| 35 | ||
| 17 | 36 | ## What is real and what is not |
| 18 | 37 | |
| 19 | 38 | - **Real.** The game: WebGL2 written by hand, a fixed 64 Hz simulation, Source-style |
src/readme.test.ts added +56
| @@ -0,0 +1,56 @@ | ||
| 1 | /** | |
| 2 | * The README's "Run it locally" section is a promise: one command, one | |
| 3 | * address, one place the database lands. The defaults are read out of the | |
| 4 | * code here rather than written down, so changing a default in the code and | |
| 5 | * not in the README fails the check instead of a person's first run. | |
| 6 | */ | |
| 7 | ||
| 8 | import { expect, test } from "bun:test"; | |
| 9 | import { readFileSync } from "node:fs"; | |
| 10 | import { join } from "node:path"; | |
| 11 | ||
| 12 | const root = join(import.meta.dir, ".."); | |
| 13 | const read = (path: string): string => readFileSync(join(root, path), "utf8"); | |
| 14 | ||
| 15 | const section = (name: string): string => { | |
| 16 | const readme = read("README.md"); | |
| 17 | const start = readme.indexOf(`## ${name}\n`); | |
| 18 | expect(start).toBeGreaterThan(-1); | |
| 19 | const rest = readme.slice(start + name.length + 4); | |
| 20 | const end = rest.indexOf("\n## "); | |
| 21 | return end === -1 ? rest : rest.slice(0, end); | |
| 22 | }; | |
| 23 | ||
| 24 | /** The fallback in `x ?? "y"` or `x ?? 8080`, as written in the source. */ | |
| 25 | const fallback = (source: string, variable: string): string => { | |
| 26 | const match = new RegExp(`process\\.env\\.${variable} \\?\\? "?([^")]+)"?`).exec(source); | |
| 27 | expect(match).not.toBeNull(); | |
| 28 | return (match as RegExpExecArray)[1] as string; | |
| 29 | }; | |
| 30 | ||
| 31 | test("the readme names the command that starts the app", () => { | |
| 32 | const run = (JSON.parse(read("forge.json")) as { app: { run: string } }).app.run; | |
| 33 | expect(run).toBe("bun run src/server.ts"); | |
| 34 | expect(section("Run it locally")).toContain(`\n${run}\n`); | |
| 35 | }); | |
| 36 | ||
| 37 | test("the readme quotes the defaults the code actually falls back to", () => { | |
| 38 | const local = section("Run it locally"); | |
| 39 | const server = read("src/server.ts"); | |
| 40 | const port = fallback(server, "PORT"); | |
| 41 | const host = fallback(server, "HOST"); | |
| 42 | const data = fallback(read("src/db.ts"), "FORGE_APP_DATA"); | |
| 43 | ||
| 44 | expect(local).toContain(`PORT=${port}`); | |
| 45 | expect(local).toContain(`HOST=${host}`); | |
| 46 | expect(local).toContain(`FORGE_APP_DATA=${data}`); | |
| 47 | expect(local).toContain(`http://${host}:${port}`); | |
| 48 | expect(local).toContain(`${data.replace(/^\.\//, "")}/app.db`); | |
| 49 | }); | |
| 50 | ||
| 51 | test("the readme names the check and the build the same way the app does", () => { | |
| 52 | const local = section("Run it locally"); | |
| 53 | const { app } = JSON.parse(read("forge.json")) as { app: { test: string } }; | |
| 54 | expect(local).toContain(`\n${app.test} `); | |
| 55 | expect(local).toContain("bun run scripts/build.ts"); | |
| 56 | }); |
new above
offline