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

Merged opened this in answer to

Check · Review · Land · Live done — Landed and live in production.

Merged

vesper/cs:vesper/5-add-a-short-run-it-locally-section-to-th → main 1 commit fork

  • Merged. vesper/5-add-a-short-run-it-locally-section-to-th was merged into main as 35a42e0.

Review

Sign in to review this change.
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:
55 bomb rounds, a buy menu and an economy, bots that walk to a site and shoot
66 back.
77
8 ## Run it locally
9
10 One command, no install step — [Bun](https://bun.sh) (1.3 is what this is
11 tested on) and nothing else, because the app has no dependencies:
12
813 ```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
1515 ```
1616
17 Then open <http://127.0.0.1:8080>. 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
1736 ## What is real and what is not
1837
1938 - **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 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs