@eigeninteractive/testkit 0.5.1 → 0.6.0

package/dist/local-state.d.ts

@@ -1,177 +1,138 @@
-/**
- * Read a Worker's LOCAL `.wrangler` state directly: the D1 index and the
- * per-game Durable Object databases, opened as plain SQLite files.
- *
- * This is a development and debugging surface, never a runtime one. Nothing here
- * runs on Workers: it is Node reading files that `wrangler dev` left on disk,
- * which is why it lives in the testkit (a `devDependency`) behind its own
- * subpath, and why it reads them through Node's built-in `node:sqlite` rather
- * than a driver package. `better-sqlite3` would work and was tried first, but
- * `drizzle-orm` declares it as an OPTIONAL PEER: installing it anywhere in the
- * workspace re-resolves drizzle's peer set for every importer, which changed the
- * types `packages/server` compiles against and broke its `dts` build. A
- * debugging tool is not worth perturbing the engine's own dependency graph, and
- * the built-in module costs nothing: no native build, no `allowBuilds` opt-in,
- * and no dependency at all.
- *
- * Two stores, two different questions, and the reason a game-shaped reader
- * exists at all:
- *
- * - **D1 is the index.** Discovery, history, ratings, identity. Its `games` row
- *   is a display read-model written by the DO as a fire-and-forget mirror.
- * - **The game's DO is the session.** One SQLite database per game, holding the
- *   authoritative status, roster and the append-only transition log.
- *
- * A question like "why is this game not starting" therefore cannot be answered
- * from either store alone, and answering it from a generic table browser means
- * knowing which of the two to distrust. {@link LocalStore.game} joins them and
- * reports the disagreement as a value, so a stale mirror reads as a stale
- * mirror rather than as a mystery.
- *
- * Every open is read-only, so this is safe to run against a live `wrangler dev`.
- *
- * @module @eigeninteractive/testkit/local-state
- */
 import { DatabaseSync } from "node:sqlite";
+//#region src/local-state.d.ts
 /** A local Durable Object database: one game's whole session. */
-export interface LocalDurableObject {
-    /** The Durable Object class, parsed from the directory Miniflare names
-     * `<worker>-<ClassName>`. */
-    className: string;
-    /** The hex `DurableObjectId`, which is the filename: `idFromName(name)`
-     * hashed. Not the game id, and not reversible without {@link name}. */
-    id: string;
-    /** The name the object was addressed by, which for a game DO is its
-     * `gameId`. Null only if the object was created by unique id rather than by
-     * name, which the engine never does. */
-    name: string | null;
-    /** Absolute path to the SQLite file. */
-    file: string;
+interface LocalDurableObject {
+  /** The Durable Object class, parsed from the directory Miniflare names
+   * `<worker>-<ClassName>`. */
+  className: string;
+  /** The hex `DurableObjectId`, which is the filename: `idFromName(name)`
+   * hashed. Not the game id, and not reversible without {@link name}. */
+  id: string;
+  /** The name the object was addressed by, which for a game DO is its
+   * `gameId`. Null only if the object was created by unique id rather than by
+   * name, which the engine never does. */
+  name: string | null;
+  /** Absolute path to the SQLite file. */
+  file: string;
 }
 /** What a bound parameter may be: SQLite's own value domain, spelled out here
  * rather than re-exported from `node:sqlite` so the public signature does not
  * depend on a built-in module's type names. */
-export type LocalQueryParam = string | number | bigint | null | Uint8Array;
+type LocalQueryParam = string | number | bigint | null | Uint8Array;
 /** A row of Miniflare's alarm table: the DO's armed alarm, which for a game is
  * its turn deadline plus grace. An absent row means no timer is armed, which is
  * correct for an untimed game and a bug for a timed one mid-turn. */
-export interface LocalAlarm {
-    actorId: string;
-    actorName: string | null;
-    scheduledTime: number | null;
+interface LocalAlarm {
+  actorId: string;
+  actorName: string | null;
+  scheduledTime: number | null;
 }
 /** The engine's `games` row: the D1 index entry, a display mirror of the DO. */
-export interface LocalGameRow {
-    id: string;
-    createdBy: string | null;
-    status: string;
-    access: string;
-    schemaVersion: number;
-    config: unknown;
-    turnSeconds: number | null;
-    budgetSeconds: number | null;
-    incrementSeconds: number | null;
-    rated: boolean;
-    ratingPool: string | null;
-    minPlayers: number;
-    maxPlayers: number;
-    shortCode: string;
-    pendingPlayers: number[] | null;
-    turnDeadline: number | null;
-    outcomes: unknown;
-    finishId: string | null;
-    finishedAt: number | null;
-    archivedAt: number | null;
-    createdAt: number;
-    updatedAt: number;
+interface LocalGameRow {
+  id: string;
+  createdBy: string | null;
+  status: string;
+  access: string;
+  schemaVersion: number;
+  config: unknown;
+  turnSeconds: number | null;
+  budgetSeconds: number | null;
+  incrementSeconds: number | null;
+  rated: boolean;
+  ratingPool: string | null;
+  minPlayers: number;
+  maxPlayers: number;
+  shortCode: string;
+  pendingPlayers: number[] | null;
+  turnDeadline: number | null;
+  outcomes: unknown;
+  finishId: string | null;
+  finishedAt: number | null;
+  archivedAt: number | null;
+  createdAt: number;
+  updatedAt: number;
 }
 /** One seat, from either store. `username` is filled in from D1's `users` and
  * `bots` tables when the reader has an index to join against. */
-export interface LocalSeat {
-    playerIndex: number;
-    userId: string | null;
-    botId: string | null;
-    type: string;
-    username: string | null;
-    displayName: string | null;
+interface LocalSeat {
+  playerIndex: number;
+  userId: string | null;
+  botId: string | null;
+  type: string;
+  username: string | null;
+  displayName: string | null;
 }
 /** The DO's single `meta` row: the authoritative session header. */
-export interface LocalGameMeta {
-    gameId: string;
-    status: string;
-    access: string;
-    schemaVersion: number;
-    config: unknown;
-    turnSeconds: number | null;
-    budgetSeconds: number | null;
-    incrementSeconds: number | null;
-    rated: boolean;
-    ratingPool: string | null;
-    minPlayers: number;
-    maxPlayers: number;
-    createdBy: string | null;
-    rngSeed: string | null;
+interface LocalGameMeta {
+  gameId: string;
+  status: string;
+  access: string;
+  schemaVersion: number;
+  config: unknown;
+  turnSeconds: number | null;
+  budgetSeconds: number | null;
+  incrementSeconds: number | null;
+  rated: boolean;
+  ratingPool: string | null;
+  minPlayers: number;
+  maxPlayers: number;
+  createdBy: string | null;
+  rngSeed: string | null;
 }
 /** One committed transition, decoded. `action` is null at v0 (the start). */
-export interface LocalTransition {
-    version: number;
-    state: unknown;
-    action: {
-        type: string;
-        kind: string;
-        playerIndex: number | null;
-        data: unknown;
-    } | null;
-    pending: number[];
-    deadline: number | null;
-    playerTimes: number[] | null;
-    /** Non-null only while this transition's pending turn consumes a budget
-     * bank. Per-action and hook-override deadlines do not set it. */
-    turnStartedAt: number | null;
-    /** Which seats hold a stored frame at this version. Empty after the finish
-     * compaction, which empties `frames` and leaves replay to re-projection. */
-    frameSeats: number[];
+interface LocalTransition {
+  version: number;
+  state: unknown;
+  action: {
+    type: string;
+    kind: string;
+    playerIndex: number | null;
+    data: unknown;
+  } | null;
+  pending: number[];
+  deadline: number | null;
+  playerTimes: number[] | null;
+  /** Non-null only while this transition's pending turn consumes a budget
+   * bank. Per-action and hook-override deadlines do not set it. */
+  turnStartedAt: number | null;
+  /** Which seats hold a stored frame at this version. Empty after the finish
+   * compaction, which empties `frames` and leaves replay to re-projection. */
+  frameSeats: number[];
 }
 /** Why the game is where it is, and what would move it. Derived rather than
  * stored: this is the sentence a developer actually wants, and every input to
  * it is already on screen above it. */
-export interface LocalGameDiagnosis {
-    /** One line naming the next expected event, or the reason there is none. */
-    summary: string;
-    /** Disagreements between the D1 mirror and the DO's own truth. A non-empty
-     * list means a mirror write was lost, since the DO is authoritative. */
-    mirrorDrift: string[];
+interface LocalGameDiagnosis {
+  /** One line naming the next expected event, or the reason there is none. */
+  summary: string;
+  /** Disagreements between the D1 mirror and the DO's own truth. A non-empty
+   * list means a mirror write was lost, since the DO is authoritative. */
+  mirrorDrift: string[];
 }
 /** Everything both stores know about one game. */
-export interface LocalGameView {
-    gameId: string;
-    /** The D1 index row, or null when D1 has no such game: either the id came
-     * from a DO name and the index was wiped, or the create write never landed. */
-    index: LocalGameRow | null;
-    /** D1's `participants`, which mirror the DO's roster for display. */
-    indexSeats: LocalSeat[];
-    /** The DO file, or null when no Durable Object exists for this game yet.
-     * That is the normal state of a created-but-never-touched lobby: the DO is
-     * created lazily by the first command or socket. */
-    durableObject: LocalDurableObject | null;
-    meta: LocalGameMeta | null;
-    roster: LocalSeat[];
-    transitions: LocalTransition[];
-    /** Recorded `commandId` dedupe entries, newest first. */
-    commands: {
-        commandId: string;
-        createdAt: number;
-        result: unknown;
-    }[];
-    /** Unapplied finish rows: a surviving row means the D1 finish apply has not
-     * succeeded and the admin re-poke is the recovery. */
-    outbox: {
-        finishId: string;
-        createdAt: number;
-        outcomes: unknown;
-    }[];
-    alarm: LocalAlarm | null;
-    diagnosis: LocalGameDiagnosis;
+interface LocalGameView {
+  gameId: string;
+  /** The D1 index row, or null when D1 has no such game: either the id came
+   * from a DO name and the index was wiped, or the create write never landed. */
+  index: LocalGameRow | null;
+  /** D1's `participants`, which mirror the DO's roster for display. */
+  indexSeats: LocalSeat[];
+  /** The DO file, or null when no Durable Object exists for this game yet.
+   * That is the normal state of a created-but-never-touched lobby: the DO is
+   * created lazily by the first command or socket. */
+  durableObject: LocalDurableObject | null;
+  meta: LocalGameMeta | null;
+  roster: LocalSeat[];
+  transitions: LocalTransition[];
+  /** Unapplied finish rows: a surviving row means the D1 finish apply has not
+   * succeeded and the admin re-poke is the recovery. */
+  outbox: {
+    finishId: string;
+    createdAt: number;
+    outcomes: unknown;
+  }[];
+  alarm: LocalAlarm | null;
+  diagnosis: LocalGameDiagnosis;
 }
 /**
  * Walk up from `from` to the nearest directory holding `.wrangler/state/v3`.
@@ -180,7 +141,7 @@ export interface LocalGameView {
  * inside a game repository, including the app half of a two-package layout,
  * where the state lives a directory or two above the shell's cwd.
  */
-export declare function findWranglerState(from?: string): string | null;
+declare function findWranglerState(from?: string): string | null;
 /**
  * Open a SQLite file for reading only.
  *
@@ -194,7 +155,7 @@ export declare function findWranglerState(from?: string): string | null;
  * because that fallback would otherwise CREATE a database rather than report a
  * missing one.
  */
-export declare function openSqlite(file: string): DatabaseSync;
+declare function openSqlite(file: string): DatabaseSync;
 /**
  * A Worker's local state, with its databases opened lazily and held open.
  *
@@ -202,76 +163,79 @@ export declare function openSqlite(file: string): DatabaseSync;
  * {@link close} it. A single instance is the unit both the CLI and a test use,
  * so neither has to know which file backs which resource.
  */
-export declare class LocalStore {
-    #private;
-    /** Absolute path to `.wrangler/state/v3`. */
-    readonly root: string;
-    private constructor();
-    /**
-     * Locate and open the state under `from`, or throw with the one thing the
-     * caller can act on: that no Worker has been run here yet.
-     */
-    static open(from?: string): LocalStore;
-    /**
-     * The engine's D1 database, identified by its schema rather than its name.
-     *
-     * Miniflare names the file after a hash of the database, so there is no
-     * mapping back to the binding. Recognising the engine's own `games` table
-     * instead is both simpler and more honest about what the caller wants: the
-     * database that has games in it, whatever the binding was called.
-     */
-    d1(): {
-        file: string;
-        db: DatabaseSync;
-    } | null;
-    /**
-     * Every local Durable Object database, newest-modified first.
-     *
-     * The directory is `<worker>-<ClassName>`, and a worker name may itself
-     * contain a dash, so the class is everything after the LAST one. Ordering by
-     * mtime puts the game you just touched at the top, which is nearly always the
-     * one being debugged.
-     */
-    durableObjects(): LocalDurableObject[];
-    /** The armed alarm for a Durable Object, from its namespace's metadata
-     * database. Matched on either column because the id is what Miniflare keys
-     * by and the name is what a human recognises. */
-    alarm(target: LocalDurableObject): LocalAlarm | null;
-    /** The D1 index rows, newest-updated first. */
-    games(options?: {
-        status?: string;
-        limit?: number;
-    }): LocalGameRow[];
-    /**
-     * Resolve a game reference the way a developer will type it: a full id, a
-     * six-character short code, or an id prefix long enough to be unique.
-     *
-     * D1 is tried first because it can match a short code, then the DO names, so
-     * a game whose index row was wiped is still reachable by id.
-     */
-    resolveGameId(ref: string): string | null;
-    /** The Durable Object holding a game's session, or null if none exists yet. */
-    gameDurableObject(gameId: string): LocalDurableObject | null;
-    /**
-     * Join both stores for one game: the index row, the session, the transition
-     * log, and the derived diagnosis.
-     *
-     * Returns null only when neither store has heard of the game.
-     */
-    game(ref: string): LocalGameView | null;
-    /** Run a read-only statement against D1 or one game's Durable Object: the
-     * escape hatch for a question this reader does not model. */
-    query(sql: string, options?: {
-        game?: string;
-        params?: LocalQueryParam[];
-    }): Record<string, unknown>[];
-    /** Table names and row counts, for D1 or one game's Durable Object. */
-    tables(options?: {
-        game?: string;
-    }): {
-        name: string;
-        rows: number;
-    }[];
-    /** Release every open handle. */
-    close(): void;
+declare class LocalStore {
+  #private;
+  /** Absolute path to `.wrangler/state/v3`. */
+  readonly root: string;
+  private constructor();
+  /**
+   * Locate and open the state under `from`, or throw with the one thing the
+   * caller can act on: that no Worker has been run here yet.
+   */
+  static open(from?: string): LocalStore;
+  /**
+   * The engine's D1 database, identified by its schema rather than its name.
+   *
+   * Miniflare names the file after a hash of the database, so there is no
+   * mapping back to the binding. Recognising the engine's own `games` table
+   * instead is both simpler and more honest about what the caller wants: the
+   * database that has games in it, whatever the binding was called.
+   */
+  d1(): {
+    file: string;
+    db: DatabaseSync;
+  } | null;
+  /**
+   * Every local Durable Object database, newest-modified first.
+   *
+   * The directory is `<worker>-<ClassName>`, and a worker name may itself
+   * contain a dash, so the class is everything after the LAST one. Ordering by
+   * mtime puts the game you just touched at the top, which is nearly always the
+   * one being debugged.
+   */
+  durableObjects(): LocalDurableObject[];
+  /** The armed alarm for a Durable Object, from its namespace's metadata
+   * database. Matched on either column because the id is what Miniflare keys
+   * by and the name is what a human recognises. */
+  alarm(target: LocalDurableObject): LocalAlarm | null;
+  /** The D1 index rows, newest-updated first. */
+  games(options?: {
+    status?: string;
+    limit?: number;
+  }): LocalGameRow[];
+  /**
+   * Resolve a game reference the way a developer will type it: a full id, a
+   * six-character short code, or an id prefix long enough to be unique.
+   *
+   * D1 is tried first because it can match a short code, then the DO names, so
+   * a game whose index row was wiped is still reachable by id.
+   */
+  resolveGameId(ref: string): string | null;
+  /** The Durable Object holding a game's session, or null if none exists yet. */
+  gameDurableObject(gameId: string): LocalDurableObject | null;
+  /**
+   * Join both stores for one game: the index row, the session, the transition
+   * log, and the derived diagnosis.
+   *
+   * Returns null only when neither store has heard of the game.
+   */
+  game(ref: string): LocalGameView | null;
+  /** Run a read-only statement against D1 or one game's Durable Object: the
+   * escape hatch for a question this reader does not model. */
+  query(sql: string, options?: {
+    game?: string;
+    params?: LocalQueryParam[];
+  }): Record<string, unknown>[];
+  /** Table names and row counts, for D1 or one game's Durable Object. */
+  tables(options?: {
+    game?: string;
+  }): {
+    name: string;
+    rows: number;
+  }[];
+  /** Release every open handle. */
+  close(): void;
 }
+//#endregion
+export { LocalAlarm, LocalDurableObject, LocalGameDiagnosis, LocalGameMeta, LocalGameRow, LocalGameView, LocalQueryParam, LocalSeat, LocalStore, LocalTransition, findWranglerState, openSqlite };
+//# sourceMappingURL=local-state.d.ts.map

package/dist/local-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-state.d.ts","names":[],"sources":["../src/local-state.ts"],"mappings":";;;UAqDiB;;;EAGf;;;EAGA;;;;EAIA;;EAEA;;;;;KAMU,oDAAoD;;;;UAK/C;EACf;EACA;EACA;;;UAIe;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;;;UAKe;EACf;EACA;EACA;EACA;EACA;EACA;;;UAIe;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;;UAIe;EACf;EACA;EACA;IAAU;IAAc;IAAc;IAA4B;;EAClE;EACA;EACA;;;EAGA;;;EAGA;;;;;UAMe;;EAEf;;;EAGA;;;UAIe;EACf;;;EAGA,OAAO;;EAEP,YAAY;;;;EAIZ,eAAe;EACf,MAAM;EACN,QAAQ;EACR,aAAa;;;EAGb;IAAU;IAAkB;IAAmB;;EAC/C,OAAO;EACP,WAAW;;;;;;;;;iBAUG,kBAAkB;;;;;;;;;;;;;;iBAwBlB,WAAW,eAAe;;;;;;;;cAiD7B;;;WAEF;UAKF;;;;;SAQA,KAAK,gBAAgB;;;;;;;;;EAwB5B;IAAQ;IAAc,IAAI;;;;;;;;;;EAqB1B,kBAAkB;;;;EAoBlB,MAAM,QAAQ,qBAAqB;;EAUnC,MAAM;IAAW;IAAiB;MAAwB;;;;;;;;EAgB1D,cAAc;;EAgBd,kBAAkB,iBAAiB;;;;;;;EAsCnC,KAAK,cAAc;;;EA2DnB,MAAM,aAAa;IAAW;IAAe,SAAS;MAA2B;;EASjF,OAAO;IAAW;;IAAyB;IAAc;;;EAczD"}

package/dist/local-state.js

@@ -1,11 +1,2 @@
-import {
-  LocalStore,
-  findWranglerState,
-  openSqlite
-} from "./chunk-YJE4AGHJ.js";
-export {
-  LocalStore,
-  findWranglerState,
-  openSqlite
-};
-//# sourceMappingURL=local-state.js.map
+import { n as findWranglerState, r as openSqlite, t as LocalStore } from "./local-state-CnO-Oi-R.js";
+export { LocalStore, findWranglerState, openSqlite };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eigeninteractive/testkit",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "license": "MIT",
   "description": "Test helpers for games built on the EigenInteractive engine: drive rules through the real kernel and run shared twin fixtures, with no Worker, database or network.",
   "main": "./dist/index.js",
@@ -21,7 +21,8 @@
   },
   "files": [
     "bin",
-    "dist"
+    "dist",
+    "src"
   ],
   "keywords": [
     "eigen",
@@ -35,17 +36,17 @@
   "type": "module",
   "dependencies": {
     "rand-seed": "^3.0.0",
-    "tsx": "^4.23.1",
-    "@eigeninteractive/kernel": "0.5.1"
+    "tsx": "^4.23.12",
+    "@eigeninteractive/kernel": "0.6.0"
   },
   "devDependencies": {
-    "@types/node": "^26.1.1",
+    "@types/node": "^26.2.0",
     "vitest": "^4.1.10",
-    "@eigeninteractive/rules": "0.5.1"
+    "@eigeninteractive/rules": "0.6.0"
   },
   "peerDependencies": {
     "vitest": "^4.1.0",
-    "@eigeninteractive/rules": "^0.5.1"
+    "@eigeninteractive/rules": "^0.6.0"
   },
   "homepage": "https://eigeninteractive.com",
   "repository": {
@@ -60,8 +61,8 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsup && tsc -p tsconfig.build.json",
-    "dev": "tsup --watch",
+    "build": "tsdown",
+    "dev": "tsdown --watch",
     "test": "vitest run --passWithNoTests",
     "typecheck": "tsc --noEmit -p tsconfig.json"
   }

package/src/contract-cli.ts

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { checkConfiguredGameContract, emitConfiguredGameContract } from "./contract-command.js";
+
+try {
+  const { values } = parseArgs({
+    strict: true,
+    options: {
+      check: { type: "boolean" },
+      help: { type: "boolean", short: "h" },
+    },
+  });
+  if (values.help) {
+    console.log(`Usage: eigen-contract [options]
+
+Emit game-contract.json from the configured game module and fixtures.
+
+Options:
+  --check      Fail when the committed contract is stale
+  -h, --help   Show this help`);
+  } else {
+    if (values.check) await checkConfiguredGameContract();
+    else await emitConfiguredGameContract();
+  }
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`eigen-contract: ${message}`);
+  process.exitCode = 1;
+}

package/src/contract-command.ts

@@ -0,0 +1,78 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import type { GameModule } from "@eigeninteractive/rules";
+import { tsImport } from "tsx/esm/api";
+import { checkGameContract, emitGameContract } from "./game-contract.js";
+
+interface EigenPackageConfig {
+  game?: unknown;
+  module?: unknown;
+  fixtures?: unknown;
+  contract?: unknown;
+}
+
+interface PackageManifest {
+  eigen?: EigenPackageConfig;
+}
+
+function configuredString(value: unknown, fallback: string, field: string): string {
+  if (value === undefined) return fallback;
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`package.json eigen.${field} must be a non-empty string`);
+  }
+  return value;
+}
+
+const isGameModule = (value: unknown): value is GameModule => value !== null && typeof value === "object" && "versions" in value && value.versions !== null && typeof value.versions === "object";
+
+/**
+ * Emit a contract from the conventional game package layout.
+ *
+ * The package default-exports its GameModule from `src/module/index.ts` and
+ * declares `{ "eigen": { "game": "…" } }` in package.json. Paths can be
+ * overridden under the same `eigen` object.
+ */
+async function configuredGameContractOptions(root: string) {
+  const manifest = JSON.parse(readFileSync(resolve(root, "package.json"), "utf8")) as PackageManifest;
+  const config = manifest.eigen ?? {};
+  const game = configuredString(config.game, "", "game");
+  if (game.length === 0) {
+    throw new Error('package.json must declare an EigenInteractive game name, e.g. "eigen": { "game": "Chess" }');
+  }
+
+  const modulePath = configuredString(config.module, "src/module/index.ts", "module");
+  const fixturesPath = configuredString(config.fixtures, "src/module/fixtures", "fixtures");
+  const contractPath = configuredString(config.contract, "game-contract.json", "contract");
+  const imported = (await tsImport(pathToFileURL(resolve(root, modulePath)).href, import.meta.url)) as { default?: unknown };
+
+  if (!isGameModule(imported.default)) {
+    throw new Error(`${modulePath} must default-export an EigenInteractive GameModule`);
+  }
+
+  return {
+    game,
+    gameModule: imported.default,
+    fixturesRoot: resolve(root, fixturesPath),
+    output: resolve(root, contractPath),
+  };
+}
+
+/**
+ * Emits `game-contract.json` from an EigenInteractive package's conventional layout.
+ *
+ * This is the programmatic form of the `eigen-contract` executable. Most
+ * games should invoke the executable through their package script.
+ */
+export async function emitConfiguredGameContract(root = process.cwd()): Promise<void> {
+  emitGameContract(await configuredGameContractOptions(root));
+}
+
+/**
+ * Fails when the conventionally configured contract is absent or stale.
+ *
+ * Use this in CI through `eigen-contract --check`.
+ */
+export async function checkConfiguredGameContract(root = process.cwd()): Promise<void> {
+  checkGameContract(await configuredGameContractOptions(root));
+}