create-eigen-game 0.13.0 → 0.13.1

package/src/link-firebase.ts

@@ -0,0 +1,70 @@
+/**
+ * Reads the two deployment values that exist only once a Firebase project
+ * does, so the closing summary can name what is still missing.
+ *
+ * Reading only. `configure_firebase` writes them, into `wrangler.jsonc` and
+ * `app-config.json`, because it is also what a project runs later when
+ * reconfiguring, and one implementation is what keeps the scaffold-time path
+ * and the re-run path identical. This module exists so the summary can tell
+ * the difference between "filled in" and "still owed", not to do it again.
+ *
+ * Its own module for the same reason `summary.ts` is: `index.ts` runs a
+ * scaffold, and this is worth asserting without one. The package `exports` map
+ * does not expose it.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+/** What the Firebase step managed to settle, and what it left for the console. */
+export interface FirebaseLink {
+  /** The project now in `wrangler.jsonc`, or null when FlutterFire recorded none. */
+  projectId: string | null;
+  /** The OAuth web client now in `app-config.json`, or null when Google sign-in is not enabled yet. */
+  googleWebClientId: string | null;
+}
+
+function readJson(path: string): unknown {
+  if (!existsSync(path)) return undefined;
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    // A file this step only reads is never worth failing a finished scaffold
+    // for. The value counts as unset, and the summary says so.
+    return undefined;
+  }
+}
+
+/**
+ * The project FlutterFire recorded for the Dart output this app uses.
+ *
+ * `firebase.json` is FlutterFire's own record rather than something this
+ * scaffold writes, so it is read defensively: a shape that does not match is
+ * treated as "not configured", which is the same answer as a run that never
+ * happened.
+ */
+export function configuredProject(appRoot: string): string | null {
+  const record = readJson(resolve(appRoot, "firebase.json")) as { flutter?: { platforms?: { dart?: Record<string, { projectId?: unknown }> } } } | undefined;
+  const projectId = record?.flutter?.platforms?.dart?.["lib/firebase_options.dart"]?.projectId;
+  return typeof projectId === "string" && projectId !== "" ? projectId : null;
+}
+
+/**
+ * The OAuth web client id that `configure_firebase` copied into
+ * `app-config.json`, when there was one to copy.
+ *
+ * Empty is an ordinary outcome rather than a failure. Firebase creates that
+ * client when the Google sign-in provider is enabled, which is a console
+ * action no CLI can perform, so a project that has never had it enabled has
+ * nothing to offer here.
+ */
+export function configuredWebClientId(appRoot: string): string | null {
+  const config = readJson(resolve(appRoot, "app-config.json")) as Record<string, unknown> | undefined;
+  const value = config?.GOOGLE_WEB_CLIENT_ID;
+  return typeof value === "string" && value !== "" ? value : null;
+}
+
+/** What the Firebase step settled, for the summary to report. */
+export function readFirebaseLink(root: string): FirebaseLink {
+  const appRoot = resolve(root, "app");
+  return { projectId: configuredProject(appRoot), googleWebClientId: configuredWebClientId(appRoot) };
+}

package/src/prompt.ts

@@ -0,0 +1,182 @@
+/**
+ * Every question this CLI asks, in one module so the wording lives together
+ * and can be asserted. `cli.ts` is the bin entry and runs `main` on import,
+ * which makes anything defined there untestable.
+ *
+ * The organization prompt is the reason this drops to `@clack/core` rather
+ * than using `@clack/prompts`' `text`. The suffix: `flutter create --org X
+ * --project-name Y` derives `X.Y`, so the organization is a *prefix*, and the
+ * reliable way to say so is to render the rest of the identifier, dimmed,
+ * while it is being typed. `text` has no hook for that; a custom `TextPrompt`
+ * render returns a string, so it does.
+ *
+ * Everything else comes from `@clack/prompts` rather than being drawn here.
+ * Its symbols are exported for exactly this, and they are not constants: each
+ * falls back to ASCII on a terminal that cannot show the box-drawing
+ * characters, which a hand-typed `│` cannot do.
+ */
+import type { Readable, Writable } from "node:stream";
+import { TextPrompt } from "@clack/core";
+import { confirm, isCancel, S_BAR, S_BAR_END, select, symbol } from "@clack/prompts";
+import color from "picocolors";
+import type { PackageManager } from "./index.js";
+
+/**
+ * Where a question reads its answer from. Parameters for the same reason every
+ * clack prompt takes them: a prompt is otherwise the one part of a CLI that
+ * cannot be driven by a test.
+ */
+export interface Io {
+  input?: Readable;
+  output?: Writable;
+}
+
+/**
+ * Two or more dot-separated Java identifiers. `flutter create --org` accepts
+ * anything and defers the complaint to Gradle, which reports it as a manifest
+ * error in a generated file, so `com.example-games` costs a full scaffold and
+ * a first build before anyone learns that a hyphen is not legal in a package
+ * segment.
+ */
+export const ORG = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)+$/;
+
+/** The default, which an empty answer accepts. */
+export const DEFAULT_ORG = "com.example";
+
+const bar = color.gray(S_BAR);
+
+/** A `com.acme.chess` answer to a game called `chess`, which yields `com.acme.chess.chess`. */
+export function repeatsGameName(org: string, game: string): boolean {
+  return org.split(".").at(-1) === game;
+}
+
+/** The organization implied by an answer that already ends in the game name. */
+export function withoutGameName(org: string): string | undefined {
+  const shorter = org.split(".").slice(0, -1).join(".");
+  return ORG.test(shorter) ? shorter : undefined;
+}
+
+/**
+ * Asks, with the game name rendered dimmed after the cursor so the shape of
+ * the answer is visible while it is being given.
+ *
+ * Returns the organization, `undefined` for the default, or `null` when
+ * cancelled.
+ *
+ * `input` and `output` default to this process's, and are parameters for the
+ * same reason every clack prompt takes them: a prompt is otherwise the one
+ * part of a CLI that cannot be driven by a test.
+ */
+export async function askForOrg(game: string, registering: boolean, io: Io = {}): Promise<string | undefined | null> {
+  const input = io.input ?? process.stdin;
+  const output = io.output ?? process.stdout;
+  const suffix = color.dim(`.${game}`);
+  const prompt = new TextPrompt({
+    input,
+    output,
+    // An empty answer is the default, not a mistake.
+    validate: (value) => (value === undefined || value === "" || ORG.test(value) ? undefined : "Two or more dot-separated segments, as in com.example or dev.yourname.games."),
+    render() {
+      const typed = String(this.value ?? "");
+      const shown = typed === "" ? `${color.dim(DEFAULT_ORG)}${suffix}` : `${this.userInputWithCursor}${suffix}`;
+      const problem = this.state === "error" ? `\n${bar}  ${color.yellow(this.error ?? "")}` : "";
+      return [`${bar}`, `${symbol(this.state)}  Organization in reverse domain notation`, `${bar}  ${shown}${problem}`, color.gray(S_BAR_END)].join("\n");
+    },
+  });
+
+  // The two things that make this answer permanent, said before it is given
+  // rather than after: Google Play freezes the identifier at the first upload,
+  // and FlutterFire matches an existing Android app on exactly this string, so
+  // it also decides whether the run adopts an app the chosen Firebase project
+  // already has or registers a new one.
+  output.write(`${bar}  ${color.dim("Prefixes the Android applicationId, which Google Play makes permanent at first upload.")}\n`);
+  if (registering) output.write(`${bar}  ${color.dim("Also the Android app registered in the Firebase project you pick next.")}\n`);
+
+  const answer = await prompt.prompt();
+  if (isCancel(answer)) return null;
+
+  const org = String(answer).trim();
+  if (org === "" || org === DEFAULT_ORG) return undefined;
+
+  // The mistake the dimmed suffix is there to prevent, caught for the person
+  // who pasted an identifier rather than typing one and never watched it grow.
+  const shorter = repeatsGameName(org, game) ? withoutGameName(org) : undefined;
+  if (shorter !== undefined) {
+    const shorten = await confirm({
+      message: `That gives ${color.yellow(`${org}.${game}`)}, the game name twice. Use ${color.green(shorter)} instead?`,
+      initialValue: true,
+      input,
+      output,
+    });
+    if (isCancel(shorten)) return null;
+    if (shorten) return shorter;
+  }
+
+  return org;
+}
+
+/**
+ * A yes/no question, with its reason on the line above.
+ *
+ * The three below share this so cancellation is handled in one place: ^C
+ * during any question has to mean the run stops having written nothing, and
+ * that is only true if every call site checks. `null` is that answer.
+ *
+ * `hint` is written rather than passed to `confirm`, which has nowhere to put
+ * it. It is the same dimmed line the organization prompt uses, and carries the
+ * thing that makes the default the default: a question whose answer is
+ * pre-chosen owes the reader why.
+ */
+async function ask(message: string, initialValue: boolean, hint: string, io: Io): Promise<boolean | null> {
+  const input = io.input ?? process.stdin;
+  const output = io.output ?? process.stdout;
+  output.write(`${bar}\n${bar}  ${color.dim(hint)}\n`);
+  const answer = await confirm({ message, initialValue, input, output });
+  return isCancel(answer) ? null : answer;
+}
+
+/**
+ * Asked only when {@link firebaseReadiness} found something missing, and
+ * defaulted to "no" because the honest answer usually is: the tools are two
+ * commands away, and the alternative is an app that throws at launch until
+ * they are installed anyway.
+ */
+export function askToScaffoldWithoutFirebase(io: Io = {}): Promise<boolean | null> {
+  return ask("Scaffold anyway, and connect Firebase yourself later?", false, "Everything except the app's sign-in still works, and `firebase:configure` finishes the job.", io);
+}
+
+/** Defaulted to yes: the scaffold is a few hundred generated files, and a commit is what makes the first `git diff` the first game change rather than all of them. */
+export function askForGit(io: Io = {}): Promise<boolean | null> {
+  return ask("Initialise a git repository and commit the scaffold?", true, "Commits once, so your first diff is your first game change.", io);
+}
+
+/**
+ * Defaulted to no, and the hint says why rather than leaving it as an
+ * arbitrary-looking choice: `release.yml` needs an upload keystore and a Play
+ * service account, so a project that takes the workflows before it has either
+ * gets a red `main` from its first push.
+ */
+export function askForWorkflows(io: Io = {}): Promise<boolean | null> {
+  return ask("Add the GitHub Actions workflows?", false, "Release needs a signing keystore and a Play service account, so this fails until you have both. `add workflows` writes them later.", io);
+}
+
+/**
+ * The package manager, asked only when nothing else could say.
+ *
+ * `npm create` and `pnpm create` both set `npm_config_user_agent`, so this is
+ * reached by the paths that do not: a global install, or running the binary
+ * directly. Rare, but it decides what every generated script says, and the old
+ * silent fallback to pnpm was a guess printed into a project's package.json.
+ */
+export async function askForPackageManager(io: Io = {}): Promise<PackageManager | null> {
+  const answer = await select({
+    message: "Which package manager should the generated scripts use?",
+    options: [
+      { value: "pnpm", label: "pnpm" },
+      { value: "npm", label: "npm" },
+    ],
+    input: io.input ?? process.stdin,
+    output: io.output ?? process.stdout,
+  });
+  return isCancel(answer) ? null : (answer as PackageManager);
+}

package/src/summary.ts

@@ -0,0 +1,86 @@
+/**
+ * The closing summary, and the only output of a scaffold anyone reads.
+ *
+ * A run drives several tools with plenty to say, so where the project went,
+ * what to edit, and what to run are worth restating at the bottom. Returned in
+ * pieces rather than as one block, because the CLI renders each in a different
+ * shape: the outcomes as status lines, the commands as a boxed note, the
+ * destination as the closing line.
+ *
+ * Its own module so it can be asserted: `cli.ts` is the bin entry and runs
+ * `main` on import, which makes anything defined there untestable. The package
+ * `exports` map does not expose this, so it is internal despite being
+ * importable by the tests.
+ */
+import type { PackageManager, ScaffoldResult } from "./index.js";
+
+export interface Summary {
+  /** What became of the repository and of Firebase, when there is something to say. */
+  status: string[];
+  /** The commands worth having, as one block. */
+  next: string;
+  /** One-line asides, after the block. */
+  footnotes: string[];
+  /** The closing line. */
+  headline: string;
+}
+
+/** Two-column rows, aligned to the widest left cell. */
+function columns(rows: [string, string][]): string[] {
+  const width = Math.max(...rows.map(([left]) => left.length));
+  return rows.map(([left, right]) => `  ${left.padEnd(width)}  ${right}`);
+}
+
+export function summarise(result: ScaffoldResult, manager: PackageManager, workflows: boolean): Summary {
+  const run = manager === "npm" ? "npm run" : "pnpm";
+  const status: string[] = [];
+
+  // Only the outcomes that leave the reader something to know. `failed` has
+  // already warned, in more detail than a summary line could carry.
+  if (result.git === "committed") status.push(`Committed as "Scaffold ${result.name}"`);
+  if (result.git === "existing") status.push("Created inside a repository you already had, so nothing was committed");
+  // `failed` has warned already, and the step reappears below as the next
+  // thing to run, which is the whole of the advice.
+  if (result.firebase === "configured") status.push(result.git === "committed" ? "Firebase is configured, and everything it generated is in that commit" : "Firebase is configured");
+  if (result.link?.projectId != null) status.push(`FIREBASE_PROJECT_ID is set to ${result.link.projectId}, and app-config.json points at the local Worker`);
+
+  // What is left, and only what is left. Everything here comes from the
+  // Firebase console rather than from any CLI, which is why a scaffold that
+  // filled in everything it could still ends with a list: the web target
+  // refuses to start without a VAPID key, and there is no OAuth client to copy
+  // until somebody enables the provider that creates it.
+  const remaining: [string, string][] = [];
+  if (result.link !== undefined) {
+    if (result.link.googleWebClientId === null) {
+      remaining.push(["Enable Google sign-in", "Console > Authentication > Sign-in method"]);
+      remaining.push(["GOOGLE_WEB_CLIENT_ID", "that same page, under Web SDK configuration"]);
+    }
+    remaining.push(["FIREBASE_VAPID_KEY", "Console > Project settings > Cloud Messaging > Web configuration"]);
+  }
+
+  const next = [
+    "Write the game",
+    ...columns([
+      ["server/src/module/v1.ts", "the authoritative rules"],
+      ["app/lib/game/v1/rules.dart", "the presentation twin"],
+    ]),
+    "",
+    `Then, from ${result.name}/`,
+    ...columns([
+      [`cd server && ${run} test:watch`, "rules and twin fixtures"],
+      [`cd server && ${run} dev`, "the Worker, on http://localhost:8787"],
+      [`${run} contract`, "regenerate after a schema change"],
+      // Named here because it is the one step the game itself cannot do
+      // without: rules, fixtures and the Worker all run unconfigured, and the
+      // app throws `Firebase is not configured` at launch until this has run
+      // once.
+      ...(result.firebase === "configured" ? [] : [[`${run} firebase:configure`, "connect Firebase before the app runs"] as [string, string]]),
+    ]),
+    ...(remaining.length === 0 ? [] : ["", "Before the app runs, from the Firebase console", ...columns(remaining), "", "  The values go in app/app-config.json. Both are public, not secrets."]),
+  ].join("\n");
+
+  const footnotes = ["Docs: https://eigeninteractive.com"];
+  if (!workflows) footnotes.unshift("No CI workflows yet: `create-eigen-game add workflows` writes them when shipping is the next step.");
+
+  return { status, next, footnotes, headline: `${result.name} is ready, at ${result.root}` };
+}

package/templates/app-overlay/lib/game/README.md

@@ -5,7 +5,7 @@ the authoritative TypeScript schemas. Regenerate them after changing a schema
 or shared fixture:
 
 ```sh
-dart run eigen_flutter:generate_payloads \
+dart run eigen_codegen:generate_payloads \
   --contract ../server/game-contract.json \
   --output lib/game/generated/payloads.dart \
   --fixtures-output test/fixtures

package/templates/app-overlay/lib/main.dart.template

@@ -1,6 +1,6 @@
+import 'package:eigen_firebase/eigen_firebase.dart';
 import 'package:eigen_flutter/eigen_flutter.dart';
 import 'package:firebase_core/firebase_core.dart';
-import 'package:firebase_messaging/firebase_messaging.dart';
 
 import 'firebase_options.dart';
 import 'game/module.dart';
@@ -16,7 +16,7 @@ const _appHost = String.fromEnvironment('APP_HOST');
 const _authDomain = String.fromEnvironment('AUTH_DOMAIN');
 
 Future<void> main() async {
-  await runEngineApp(
+  await runFirebaseEngineApp(
     module: const ExampleGameModule(),
     config: AppConfig(
       // `seedColor` is left at its default, the EigenInteractive teal that the
@@ -31,14 +31,17 @@ Future<void> main() async {
       ),
       engine: EngineConfig(
         apiBaseUrl: _apiBaseUrl,
-        googleWebClientId: _googleWebClientId,
         appHost: _appHost.isEmpty ? null : _appHost,
-        authDomain: _authDomain.isEmpty ? null : _authDomain,
-        firebaseVapidKey: _firebaseVapidKey,
       ),
     ),
     firebaseOptions: DefaultFirebaseOptions.currentPlatform,
+    firebase: FirebaseAdapterConfig(
+      googleWebClientId: _googleWebClientId,
+      vapidKey: _firebaseVapidKey,
+      authDomain: _authDomain.isEmpty ? null : _authDomain,
+    ),
     onBackgroundMessage: _onBackgroundMessage,
+    telemetry: FirebaseTelemetryPolicy.releaseOnly(),
   );
 }
 

package/templates/project/README.md

@@ -163,7 +163,7 @@ Required values are intentionally empty in a fresh scaffold. The app reports
 all missing or malformed declarations at startup instead of continuing with
 placeholder endpoints.
 
-The `eigen_flutter` Android plugin enables Firebase's current FID-based
+The `eigen_firebase` Android plugin enables Firebase's current FID-based
 messaging mode and supplies a Firebase SDK new enough to support it. The
 scaffolder leaves Flutter's generated manifest and `gradle.properties`
 untouched; it adds only the application-level core-library desugaring block
@@ -233,7 +233,7 @@ the engine's mark on your listing. Replace them before a first release:
 | `assets/icon/icon_foreground.png` | 1024×1024 Android adaptive foreground, transparent, artwork inside the centre 66% |
 | `assets/icon/splash.png` / `splash_dark.png` | Splash artwork for light and dark |
 
-The notification icon is the exception: `eigen_flutter` ships a default
+The notification icon is the exception: `eigen_firebase` ships a default
 `ic_notification` drawable, so nothing is missing and nothing breaks if you
 leave it. To use your own, add
 `android/app/src/main/res/drawable/ic_notification.xml`, a monochrome

package/templates/project/package.json

@@ -4,10 +4,10 @@
   "scripts": {
     "build:android": "cd app && flutter build appbundle --release --dart-define-from-file=app-config.json",
     "build:web": "cd app && flutter build web --release --output ../server/public --dart-define-from-file=app-config.json",
-    "contract": "cd server && {{PACKAGE_MANAGER}} run contract && cd ../app && dart run eigen_flutter:generate_payloads --contract ../server/game-contract.json --output lib/game/generated/payloads.dart --fixtures-output test/fixtures",
-    "contract:check": "cd server && {{PACKAGE_MANAGER}} run contract:check && cd ../app && dart run eigen_flutter:generate_payloads --contract ../server/game-contract.json --output lib/game/generated/payloads.dart --fixtures-output test/fixtures --check",
+    "contract": "cd server && {{PACKAGE_MANAGER}} run contract && cd ../app && dart run eigen_codegen:generate_payloads --contract ../server/game-contract.json --output lib/game/generated/payloads.dart --fixtures-output test/fixtures",
+    "contract:check": "cd server && {{PACKAGE_MANAGER}} run contract:check && cd ../app && dart run eigen_codegen:generate_payloads --contract ../server/game-contract.json --output lib/game/generated/payloads.dart --fixtures-output test/fixtures --check",
     "deploy": "{{PACKAGE_MANAGER}} run build:web && cd server && {{PACKAGE_MANAGER}} run deploy",
-    "firebase:configure": "cd app && dart run eigen_flutter:configure_firebase --worker ../server",
+    "firebase:configure": "cd app && dart run eigen_firebase:configure_firebase --worker ../server",
     "format": "biome check --write .",
     "lint": "biome check ."
   },

package/templates/worker/.dev.vars.example

@@ -2,3 +2,4 @@
 # Firebase Console > Project settings > Service accounts. Never commit .dev.vars.
 FIREBASE_CLIENT_EMAIL=
 FIREBASE_PRIVATE_KEY=
+SOCKET_TICKET_SECRET=replace-with-at-least-32-random-characters

package/templates/worker/README.md

@@ -28,13 +28,16 @@ the Worker's non-secret environment variables in local development and
 production. Copy `.dev.vars.example` to `.dev.vars`, then fill
 `FIREBASE_CLIENT_EMAIL` and `FIREBASE_PRIVATE_KEY` from the same Firebase
 project's service-account JSON. These credentials are required for FCM and
-complete Firebase account deletion; `.dev.vars` is git-ignored.
+complete Firebase account deletion. Also replace `SOCKET_TICKET_SECRET` with at
+least 32 random characters; `openssl rand -base64 32` generates one.
+`.dev.vars` is git-ignored.
 
-For deployment, store both values as Wrangler secrets:
+For deployment, store all three values as Wrangler secrets:
 
 ```sh
 npx wrangler secret put FIREBASE_CLIENT_EMAIL
 npx wrangler secret put FIREBASE_PRIVATE_KEY
+npx wrangler secret put SOCKET_TICKET_SECRET
 ```
 
 `WEB_APP_ORIGIN` is the exact Flutter web origin the engine automatically

package/templates/worker/src/module/v1.ts

@@ -57,6 +57,7 @@ export const rulesV1: GameRules<State, Observation, Action, Config> = {
   // create asking for a range outside this, so it is the one place a
   // fixed-size game says so. Read `config` if the count is a creation choice.
   playerLimits: () => ({ minPlayers: 2, maxPlayers: 2 }),
+  timingOptions: () => [{ mode: "untimed" }],
 
   ratingPool: () => null,
   botSeatable: () => true,