@flayerlabs/gamemode-cli 0.1.0

package/dist/scaffold.js

@@ -0,0 +1,553 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+/**
+ * A new game, playable before it does anything.
+ *
+ * The first command has to produce something that runs. A scaffold that needs a database, a chain
+ * and a wallet before it shows anything is a scaffold most people abandon, and an agent given one
+ * has nothing to check its work against.
+ *
+ * So what comes out is a complete, working guessing game: rules, a page, and tests that pass. It is
+ * meant to be edited into something else, not read and replaced.
+ */
+export async function scaffold(name) {
+    if (!/^[a-z][a-z0-9-]{0,48}$/.test(name)) {
+        throw new Error('A name should be lower case letters, numbers and dashes, e.g. my-game');
+    }
+    const root = join(process.cwd(), name);
+    await mkdir(join(root, 'src', 'game'), { recursive: true });
+    await mkdir(join(root, 'test'), { recursive: true });
+    for (const [path, contents] of Object.entries(await files(name))) {
+        await mkdir(dirname(join(root, path)), { recursive: true });
+        await writeFile(join(root, path), contents);
+    }
+    return root;
+}
+/**
+ * Source runs read the repository's canonical contract. Builds copy that same file beside the
+ * compiled module, which gives the published CLI the identical contract without maintaining a
+ * second authored string.
+ */
+async function readAgentContract() {
+    return readAsset('./AGENTS.md', '../templates/game/AGENTS.template.md');
+}
+async function readCreatorSkill() {
+    return readAsset('./build-game-mode/SKILL.md', '../../../.agents/skills/build-game-mode/SKILL.md');
+}
+async function readCreatorSkillMetadata() {
+    return readAsset('./build-game-mode/agents/openai.yaml', '../../../.agents/skills/build-game-mode/agents/openai.yaml');
+}
+async function readAsset(packaged, source) {
+    try {
+        return await readFile(new URL(packaged, import.meta.url), 'utf8');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        return readFile(new URL(source, import.meta.url), 'utf8');
+    }
+}
+export function dependencyVersionFor(version) {
+    if (typeof version !== 'string' ||
+        !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.test(version)) {
+        throw new Error('the CLI package has no valid version');
+    }
+    return /^\d+\.\d+\.\d+$/.test(version) ? `^${version}` : version;
+}
+async function sdkVersionRange() {
+    const manifest = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+    return dependencyVersionFor(manifest.version);
+}
+const files = async (name) => {
+    const sdk = await sdkVersionRange();
+    return {
+        'package.json': `${JSON.stringify({
+            name,
+            private: true,
+            type: 'module',
+            scripts: {
+                dev: 'vite',
+                test: 'gamemode check src/game/rules.ts && vitest run',
+                check: 'gamemode check src/game/rules.ts',
+                typecheck: 'tsc --noEmit',
+            },
+            dependencies: {
+                '@flayerlabs/gamemode-client': sdk,
+                '@flayerlabs/gamemode-spec': sdk,
+            },
+            devDependencies: {
+                '@flayerlabs/gamemode-cli': sdk,
+                typescript: '^5.7.2',
+                vite: '^5.4.21',
+                vitest: '^2.1.8',
+            },
+        }, null, 2)}\n`,
+        'AGENTS.md': await readAgentContract(),
+        'README.md': `# ${name}
+
+This is a Flaunch Game Mode. The browser owns the game experience. Pure server rules decide which
+actions earn points.
+
+## Start the game
+
+Install dependencies and run the local game:
+
+\`\`\`bash
+pnpm install
+pnpm dev
+\`\`\`
+
+The local room uses the real rules with a mock economy. It needs no server, chain or wallet.
+
+Run the evidence before you finish a change:
+
+\`\`\`bash
+pnpm test
+pnpm typecheck
+\`\`\`
+
+## Work with an agent
+
+Ask the agent to read \`AGENTS.md\` before it edits the game. Use \`$build-game-mode\` when the
+agent supports repository skills.
+
+The project includes:
+
+\`\`\`text
+src/game/rules.ts   pure server rules and scoring
+src/play.ts         browser game and room subscriptions
+test/rules.test.ts  scoring, secrecy and replay checks
+\`\`\`
+
+Start with the working game. Change one complete play loop at a time and keep the tests green.
+
+## Connect a live gate
+
+Finish the game against the mock room first. Then follow the
+[gate guide](https://github.com/flayerlabs/gamemode-sdk/blob/main/docs/guides/run-a-gate.md).
+
+For the rules and client workflow, read the
+[game guide](https://github.com/flayerlabs/gamemode-sdk/blob/main/docs/guides/build-a-game.md).
+`,
+        '.agents/skills/build-game-mode/SKILL.md': await readCreatorSkill(),
+        '.agents/skills/build-game-mode/agents/openai.yaml': await readCreatorSkillMetadata(),
+        'src/game/rules.ts': `import { defineGame, type Decision, type PlayerId, type Refusal } from '@flayerlabs/gamemode-spec';
+import { scheduleWithin } from '@flayerlabs/gamemode-spec/schedule';
+
+/**
+ * Guess the number.
+ *
+ * A complete, working game so there is something to run before there is something to read. Change
+ * it into whatever you are actually making.
+ */
+
+export interface Config {
+  /** How many rounds before the game ends. */
+  rounds: number;
+  /** Highest number a player might guess. */
+  ceiling: number;
+  /** What a correct guess is worth. */
+  points: number;
+  roundMs: number;
+}
+
+export interface State {
+  config: Config;
+  /** The supplied round seed, kept in server state so every answer derives from it. */
+  roundSeed: number;
+  round: number;
+  /** Derived from the round seed. Never sent to anyone until the answer is revealed. */
+  answer: number;
+  endsAt: number;
+  over: boolean;
+  guesses: Record<PlayerId, number>;
+  scores: Record<PlayerId, number>;
+}
+
+export type Action = { guess: number };
+
+export type Event =
+  | { t: 'joined'; player: PlayerId }
+  | { t: 'guessed'; player: PlayerId; guess: number }
+  | { t: 'next'; answer: number; endsAt: number }
+  | { t: 'over' };
+
+/** Deterministic in the seed, so every player gets the same game and a replay gets the same one. */
+function answerFor(seed: number, round: number, ceiling: number): number {
+  const mixed = Math.imul(seed ^ (round + 1), 2654435761) >>> 0;
+  return (mixed % ceiling) + 1;
+}
+
+export const rules = defineGame<Config, State, Event, Action, PublicView, PlayerView>({
+  id: '${name}',
+
+  parseAction(input): Action | null {
+    if (typeof input !== 'object' || input === null) return null;
+    const { guess } = input as { guess?: unknown };
+    if (typeof guess !== 'number' || !Number.isInteger(guess) || guess < 1) return null;
+    return { guess };
+  },
+
+  initRound(config, seed, window) {
+    scheduleWithin(
+      window,
+      Array.from({ length: config.rounds }, (_, round) => ({ value: round, durationMs: config.roundMs })),
+    );
+    return {
+      config,
+      roundSeed: seed,
+      round: 0,
+      answer: answerFor(seed, 0, config.ceiling),
+      endsAt: config.rounds > 0 ? window.opensAt + config.roundMs : window.closesAt,
+      over: config.rounds === 0,
+      guesses: {},
+      scores: {},
+    };
+  },
+
+  decide(state, command): Decision<Event> | Refusal {
+    switch (command.kind) {
+      case 'join':
+        return state.scores[command.player] === undefined
+          ? { events: [{ t: 'joined', player: command.player }] }
+          : { events: [] };
+
+      case 'leave':
+        return { events: [] };
+
+      case 'wake': {
+        if (state.over) return { events: [] };
+        const next = state.round + 1;
+        if (next >= state.config.rounds) return { events: [{ t: 'over' }] };
+        return {
+          events: [
+            {
+              t: 'next',
+              answer: answerFor(state.roundSeed, next, state.config.ceiling),
+              endsAt: state.endsAt + state.config.roundMs,
+            },
+          ],
+        };
+      }
+
+      case 'action': {
+        if (state.over) return { refuse: 'guess.game_over' };
+        if (state.scores[command.player] === undefined) return { refuse: 'guess.not_playing' };
+        if (state.guesses[command.player] !== undefined) return { refuse: 'guess.already_guessed' };
+        if (command.action.guess > state.config.ceiling) return { refuse: 'guess.out_of_range' };
+
+        const right = command.action.guess === state.answer;
+        return {
+          events: [{ t: 'guessed', player: command.player, guess: command.action.guess }],
+          // Paid immediately, because a guess is right or wrong the moment it lands and there is
+          // nothing to reveal later. A game with a reveal should award at the reveal instead.
+          awards: right ? [{ player: command.player, points: state.config.points }] : [],
+        };
+      }
+    }
+  },
+
+  evolve(state, event) {
+    switch (event.t) {
+      case 'joined':
+        return { ...state, scores: { ...state.scores, [event.player]: 0 } };
+      case 'guessed': {
+        const right = event.guess === state.answer;
+        return {
+          ...state,
+          guesses: { ...state.guesses, [event.player]: event.guess },
+          scores: right
+            ? { ...state.scores, [event.player]: (state.scores[event.player] ?? 0) + state.config.points }
+            : state.scores,
+        };
+      }
+      case 'next':
+        return { ...state, round: state.round + 1, answer: event.answer, endsAt: event.endsAt, guesses: {} };
+      case 'over':
+        return { ...state, over: true };
+    }
+  },
+
+  publicView(state): PublicView {
+    return {
+      round: state.round + 1,
+      rounds: state.config.rounds,
+      ceiling: state.config.ceiling,
+      endsAt: state.endsAt,
+      over: state.over,
+      // WHO has guessed, never WHAT. The answer is not in this type at all, which is what makes
+      // leaking it impossible rather than unlikely.
+      guessed: Object.keys(state.guesses),
+      standings: Object.entries(state.scores)
+        .map(([player, score]) => ({ player, score }))
+        .sort((a, b) => b.score - a.score || a.player.localeCompare(b.player)),
+    };
+  },
+
+  playerView(state, player): PlayerView {
+    const guess = state.guesses[player];
+    return {
+      playing: state.scores[player] !== undefined,
+      score: state.scores[player] ?? 0,
+      yourGuess: guess ?? null,
+      // Only ever told about your own guess, and only once you have made it.
+      wasRight: guess === undefined ? null : guess === state.answer,
+    };
+  },
+
+  nextWakeAt(state) {
+    return state.over ? null : state.endsAt;
+  },
+
+  rewardBounds(config) {
+    return { maxPointsPerPlayer: config.rounds * config.points };
+  },
+});
+
+export interface PublicView {
+  round: number;
+  rounds: number;
+  ceiling: number;
+  endsAt: number;
+  over: boolean;
+  guessed: PlayerId[];
+  standings: { player: PlayerId; score: number }[];
+}
+
+export interface PlayerView {
+  playing: boolean;
+  score: number;
+  yourGuess: number | null;
+  wasRight: boolean | null;
+}
+`,
+        'src/play.ts': `import { createMockRoom, type Snapshot } from '@flayerlabs/gamemode-client';
+import { rules, type Action, type Config, type PlayerView, type PublicView } from './game/rules.js';
+
+const config: Config = { rounds: 3, ceiling: 10, points: 500, roundMs: 10_000 };
+const room = createMockRoom(rules, { config, lobbyMs: 1_000, roundMs: 60_000 });
+const app = document.querySelector<HTMLElement>('#app');
+if (!app) throw new Error('the page needs an #app element');
+const gameRoot = app;
+
+let latest: Snapshot<PublicView, PlayerView> | null = null;
+
+function render(snapshot = latest): void {
+  if (!snapshot) return;
+  latest = snapshot;
+  const { publicView, playerView } = snapshot;
+  const seconds = Math.max(0, Math.ceil((publicView.endsAt - room.now()) / 1_000));
+  const balance = room.economy.current();
+
+  gameRoot.innerHTML = \`
+    <main>
+      <p class="eyebrow">${name}</p>
+      <h1>Guess the number</h1>
+      <p>Round \${publicView.round} of \${publicView.rounds} · <span data-clock>\${seconds}s</span> left</p>
+      <div class="numbers" aria-label="Choose a number">
+        \${Array.from({ length: publicView.ceiling }, (_, index) => {
+          const guess = index + 1;
+          const selected = playerView?.yourGuess === guess;
+          return \`<button data-guess="\${guess}" \${playerView?.yourGuess !== null || publicView.over ? 'disabled' : ''} \${selected ? 'aria-pressed="true"' : ''}>\${guess}</button>\`;
+        }).join('')}
+      </div>
+      <p class="result">\${publicView.over
+        ? 'Game over'
+        : playerView?.wasRight === true
+          ? 'Correct!'
+          : playerView?.wasRight === false
+            ? 'Not this time'
+            : 'Pick once before the round ends.'}</p>
+      <dl>
+        <div><dt>Score</dt><dd>\${playerView?.score ?? 0}</dd></div>
+        <div><dt>Available</dt><dd>\${balance.availableWei} wei</dd></div>
+      </dl>
+    </main>
+  \`;
+
+  for (const button of gameRoot.querySelectorAll<HTMLButtonElement>('[data-guess]')) {
+    button.addEventListener('click', () => {
+      const guess = Number(button.dataset.guess);
+      void room.send({ guess } satisfies Action);
+    });
+  }
+}
+
+room.subscribe((snapshot) => render(snapshot));
+room.economy.subscribe(() => render());
+const clock = setInterval(() => {
+  const countdown = gameRoot.querySelector<HTMLElement>('[data-clock]');
+  if (!latest || !countdown) return;
+  countdown.textContent = \`\${Math.max(0, Math.ceil((latest.publicView.endsAt - room.now()) / 1_000))}s\`;
+}, 250);
+window.addEventListener('pagehide', () => {
+  clearInterval(clock);
+  room.dispose();
+});
+`,
+        'index.html': `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>${name}</title>
+    <style>
+      :root { color: #f8fafc; background: #09090b; font-family: ui-sans-serif, system-ui, sans-serif; }
+      body { min-height: 100vh; margin: 0; display: grid; place-items: center; }
+      main { width: min(36rem, calc(100vw - 3rem)); }
+      .eyebrow { color: #a78bfa; font-weight: 700; letter-spacing: .12em; text-transform: uppercase; }
+      h1 { margin: .25rem 0; font-size: clamp(2.25rem, 8vw, 4.5rem); line-height: .95; }
+      .numbers { display: grid; grid-template-columns: repeat(5, 1fr); gap: .65rem; margin: 2rem 0; }
+      button { min-height: 3.5rem; border: 1px solid #3f3f46; border-radius: .75rem; color: inherit; background: #18181b; font: inherit; cursor: pointer; }
+      button:hover:not(:disabled), button[aria-pressed="true"] { border-color: #a78bfa; background: #4c1d95; }
+      button:disabled { cursor: default; opacity: .65; }
+      .result { min-height: 1.5rem; color: #d4d4d8; }
+      dl { display: flex; gap: 1rem; }
+      dl div { flex: 1; padding: 1rem; border: 1px solid #27272a; border-radius: .75rem; }
+      dt { color: #a1a1aa; font-size: .8rem; text-transform: uppercase; }
+      dd { margin: .25rem 0 0; font-size: 1.25rem; }
+    </style>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/play.ts"></script>
+  </body>
+</html>
+`,
+        'test/rules.test.ts': `import { describe, expect, it } from 'vitest';
+import { Round } from '@flayerlabs/gamemode-spec/round';
+import { isRefusal } from '@flayerlabs/gamemode-spec';
+import { rules, type Config } from '../src/game/rules.js';
+
+const OPENS = 1_000_000;
+const config: Config = { rounds: 3, ceiling: 10, points: 500, roundMs: 10_000 };
+
+function game(roundSeed = 42) {
+  const r = Round.start(rules, config, roundSeed, { opensAt: OPENS, closesAt: OPENS + 300_000 });
+  r.send({ kind: 'join', player: 'you', seed: 1, at: OPENS - 100 });
+  return r;
+}
+
+function answers(roundSeed: number): number[] {
+  const r = game(roundSeed);
+  const result = [r.snapshot().answer];
+  for (let round = 1; round < config.rounds; round++) {
+    r.advanceTo(OPENS + round * config.roundMs);
+    result.push(r.snapshot().answer);
+  }
+  return result;
+}
+
+/** The answer is deliberately not in the public view, so a test has to find it the hard way. */
+function correctGuess(r: ReturnType<typeof game>, at: number): number {
+  for (let guess = 1; guess <= config.ceiling; guess++) {
+    const probe = game();
+    probe.send({ kind: 'action', player: 'you', action: { guess }, at });
+    if (probe.playerView('you').wasRight) return guess;
+  }
+  throw new Error('no correct guess found');
+}
+
+describe('${name}', () => {
+  it('pays for a correct guess', () => {
+    const r = game();
+    const at = OPENS + 1_000;
+    r.send({ kind: 'action', player: 'you', action: { guess: correctGuess(r, at) }, at });
+    expect(r.pointsFor('you')).toBe(config.points);
+  });
+
+  it('pays nothing for a wrong one', () => {
+    const r = game();
+    const at = OPENS + 1_000;
+    const wrong = (correctGuess(r, at) % config.ceiling) + 1;
+    r.send({ kind: 'action', player: 'you', action: { guess: wrong }, at });
+    expect(r.pointsFor('you')).toBe(0);
+  });
+
+  it('allows one guess a round', () => {
+    const r = game();
+    r.send({ kind: 'action', player: 'you', action: { guess: 1 }, at: OPENS + 1_000 });
+    const second = r.send({ kind: 'action', player: 'you', action: { guess: 2 }, at: OPENS + 2_000 });
+    expect(second).toEqual({ refuse: 'guess.already_guessed' });
+  });
+
+  it('refuses a guess from someone who never joined', () => {
+    const r = game();
+    expect(r.send({ kind: 'action', player: 'nobody', action: { guess: 1 }, at: OPENS + 1_000 })).toEqual({
+      refuse: 'guess.not_playing',
+    });
+  });
+
+  it('refuses a guess outside the range, and nonsense before that', () => {
+    const r = game();
+    expect(r.send({ kind: 'action', player: 'you', action: { guess: 999 }, at: OPENS + 1_000 })).toEqual({
+      refuse: 'guess.out_of_range',
+    });
+    expect(rules.parseAction({ guess: 'four' })).toBeNull();
+    expect(rules.parseAction({ guess: 1.5 })).toBeNull();
+    expect(rules.parseAction(null)).toBeNull();
+  });
+
+  it('never puts the answer where everyone can see it', () => {
+    const r = game();
+    const everything = JSON.stringify(r.publicView());
+    for (let n = 1; n <= config.ceiling; n++) {
+      expect(everything).not.toContain(\`"answer":\${n}\`);
+    }
+    expect(everything).not.toContain('answer');
+  });
+
+  it('runs out of rounds and stops', () => {
+    const r = game();
+    r.advanceTo(OPENS + 10 * config.roundMs);
+    expect(r.publicView().over).toBe(true);
+    expect(rules.nextWakeAt(r.snapshot())).toBeNull();
+  });
+
+  it('refuses an authored schedule that cannot fit the launch window', () => {
+    expect(() =>
+      Round.start(rules, config, 42, {
+        opensAt: OPENS,
+        closesAt: OPENS + config.rounds * config.roundMs - 1,
+      }),
+    ).toThrow(/schedule needs/);
+  });
+
+  it('replaying the same guesses gives the same result', () => {
+    const a = game();
+    const b = game();
+    for (const r of [a, b]) r.send({ kind: 'action', player: 'you', action: { guess: 4 }, at: OPENS + 1_000 });
+    expect(a.snapshot()).toEqual(b.snapshot());
+  });
+
+  it('derives every answer from the supplied round seed', () => {
+    const first = answers(42);
+    expect(answers(42)).toEqual(first);
+    const variations = Array.from({ length: 32 }, (_, seed) => answers(seed));
+    for (let round = 0; round < config.rounds; round++) {
+      expect(new Set(variations.map((result) => result[round])).size).toBeGreaterThan(1);
+    }
+  });
+
+  it('says what a perfect game is worth', () => {
+    expect(rules.rewardBounds(config)).toEqual({ maxPointsPerPlayer: 1_500 });
+  });
+});
+`,
+        'tsconfig.json': `${JSON.stringify({
+            compilerOptions: {
+                target: 'ES2022',
+                module: 'NodeNext',
+                moduleResolution: 'NodeNext',
+                strict: true,
+                noUncheckedIndexedAccess: true,
+                verbatimModuleSyntax: true,
+                skipLibCheck: true,
+                noEmit: true,
+            },
+            include: ['src', 'test'],
+        }, null, 2)}\n`,
+        '.gitignore': 'node_modules/\ndist/\n',
+    };
+};
+//# sourceMappingURL=scaffold.js.map

package/dist/scaffold.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold.js","sourceRoot":"","sources":["../src/scaffold.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@flayerlabs/gamemode-cli",
+  "version": "0.1.0",
+  "description": "Create and validate Flaunch Game Modes",
+  "license": "MIT",
+  "author": "Flayer Labs",
+  "homepage": "https://github.com/flayerlabs/gamemode-sdk#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/flayerlabs/gamemode-sdk.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/flayerlabs/gamemode-sdk/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "bin": {
+    "gamemode": "dist/main.js"
+  },
+  "scripts": {
+    "prebuild": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "tsc -p tsconfig.build.json && node scripts/copy-agent-contract.mjs",
+    "prepack": "pnpm build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/lint.ts

@@ -0,0 +1,85 @@
+/**
+ * Checking that a game's rules are pure.
+ *
+ * `decide` and `evolve` must give the same answer for the same input, forever. Replay, reconnect,
+ * audit and anti-cheat all rest on it, and every one of them fails quietly rather than loudly when
+ * it stops being true — a round that scores differently on replay does not announce itself.
+ *
+ * Text rather than a full parse, deliberately. An agent writing `Date.now()` in a reducer is the
+ * failure this catches, and it catches that perfectly. A syntax tree would catch cleverer evasions
+ * that nobody is attempting, at the cost of a dependency and a lot of code.
+ */
+
+export interface Finding {
+  line: number;
+  found: string;
+  why: string;
+}
+
+interface Rule {
+  pattern: RegExp;
+  why: string;
+}
+
+const RULES: Rule[] = [
+  { pattern: /\bDate\s*\.\s*now\s*\(/, why: 'time must come from the command, as command.at' },
+  { pattern: /\bnew\s+Date\s*\(/, why: 'time must come from the command, as command.at' },
+  { pattern: /\bperformance\s*\.\s*now\s*\(/, why: 'time must come from the command, as command.at' },
+  { pattern: /\bMath\s*\.\s*random\s*\(/, why: 'randomness must be derived from the seed on the join command' },
+  { pattern: /\bcrypto\s*\.\s*(getRandomValues|randomUUID)\s*\(/, why: 'randomness must be derived from the seed on the join command' },
+  { pattern: /\bfetch\s*\(/, why: 'rules cannot reach the network' },
+  { pattern: /\brequire\s*\(\s*['"]node:/, why: 'rules cannot reach the system' },
+  { pattern: /\bfrom\s+['"]node:/, why: 'rules cannot reach the system' },
+  { pattern: /\bprocess\s*\.\s*env\b/, why: 'rules cannot read configuration; it belongs in the round config' },
+  { pattern: /\bglobalThis\b/, why: 'rules cannot reach outside themselves' },
+];
+
+/** Lines that are only a comment. A rule named in prose is documentation, not a violation. */
+function isComment(line: string): boolean {
+  const trimmed = line.trim();
+  return trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*');
+}
+
+/**
+ * Module-level mutable state: a `let` or `var` at column zero.
+ *
+ * Two calls with the same arguments must not differ because of something one of them left behind.
+ */
+function moduleState(line: string): boolean {
+  return /^(let|var)\s+\w/.test(line);
+}
+
+export function lintRules(source: string): Finding[] {
+  const findings: Finding[] = [];
+
+  source.split('\n').forEach((line, index) => {
+    if (isComment(line)) return;
+
+    for (const rule of RULES) {
+      const match = rule.pattern.exec(line);
+      if (match) findings.push({ line: index + 1, found: match[0].replace(/\s+/g, ''), why: rule.why });
+    }
+    if (moduleState(line)) {
+      findings.push({
+        line: index + 1,
+        found: line.trim().split(/\s+/).slice(0, 2).join(' '),
+        why: 'rules cannot keep state between calls; it belongs in the game state',
+      });
+    }
+  });
+
+  return findings;
+}
+
+/** What a person reads. No codes, no rule names — the line, what is there, and what to do. */
+export function report(file: string, findings: Finding[]): string {
+  if (findings.length === 0) return `${file}: rules look pure.`;
+  return [
+    `${file}: ${findings.length} thing${findings.length === 1 ? '' : 's'} to fix.`,
+    '',
+    ...findings.map((f) => `  line ${f.line}: ${f.found} — ${f.why}`),
+    '',
+    'These have to go. Same input, same answer, every time — replay, reconnect and anti-cheat',
+    'all depend on it, and each of them fails quietly rather than loudly when it stops being true.',
+  ].join('\n');
+}