@flayerlabs/gamemode-cli 0.1.0

package/src/main.ts

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { lintRules, report } from './lint.js';
+import { scaffold } from './scaffold.js';
+
+/**
+ * The whole command line.
+ *
+ * Four things, because four is what it takes to go from nothing to a game somebody can play, and a
+ * fifth would be something to learn rather than something to use.
+ */
+const USAGE = `
+gamemode — build a game for a Flaunch launch
+
+  gamemode new <name>     start a new game you can play straight away
+  gamemode check [file]   check your rules are pure (default: src/game/rules.ts)
+
+Once you have a game:
+
+  pnpm dev                play it, with no server and no wallet
+  pnpm test               check it still works
+`;
+
+async function main(argv: string[]): Promise<number> {
+  const [command, argument] = argv;
+
+  if (!command || command === 'help' || command === '--help') {
+    console.log(USAGE.trim());
+    return 0;
+  }
+
+  if (command === 'new') {
+    if (!argument) {
+      console.error('What should it be called?  gamemode new my-game');
+      return 1;
+    }
+    const created = await scaffold(argument);
+    console.log(`\n  Made ${created}\n`);
+    console.log('  Next:');
+    console.log(`    cd ${argument}`);
+    console.log('    pnpm install');
+    console.log('    pnpm dev\n');
+    return 0;
+  }
+
+  if (command === 'check') {
+    const file = argument ?? 'src/game/rules.ts';
+    let source: string;
+    try {
+      source = readFileSync(file, 'utf8');
+    } catch {
+      console.error(`Could not read ${file}.`);
+      return 1;
+    }
+    const findings = lintRules(source);
+    console.log(report(file, findings));
+    return findings.length === 0 ? 0 : 1;
+  }
+
+  console.error(`Not a command: ${command}`);
+  console.error(USAGE.trim());
+  return 1;
+}
+
+main(process.argv.slice(2))
+  .then((code) => process.exit(code))
+  .catch((error: unknown) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+  });

package/src/scaffold.ts

@@ -0,0 +1,587 @@
+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: string): Promise<string> {
+  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(): Promise<string> {
+  return readAsset('./AGENTS.md', '../templates/game/AGENTS.template.md');
+}
+
+async function readCreatorSkill(): Promise<string> {
+  return readAsset('./build-game-mode/SKILL.md', '../../../.agents/skills/build-game-mode/SKILL.md');
+}
+
+async function readCreatorSkillMetadata(): Promise<string> {
+  return readAsset(
+    './build-game-mode/agents/openai.yaml',
+    '../../../.agents/skills/build-game-mode/agents/openai.yaml',
+  );
+}
+
+async function readAsset(packaged: string, source: string): Promise<string> {
+  try {
+    return await readFile(new URL(packaged, import.meta.url), 'utf8');
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+    return readFile(new URL(source, import.meta.url), 'utf8');
+  }
+}
+
+export function dependencyVersionFor(version: unknown): string {
+  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(): Promise<string> {
+  const manifest = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8')) as {
+    version?: unknown;
+  };
+  return dependencyVersionFor(manifest.version);
+}
+
+const files = async (name: string): Promise<Record<string, string>> => {
+  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',
+  };
+};