@table-games-engine/game-kit 0.0.0-stage → 0.1.1

package/dist/index.js

@@ -0,0 +1,370 @@
+// src/game-json.ts
+import Ajv from "ajv";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+// schema/game.schema.json
+var game_schema_default = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  $id: "https://github.com/Dmitry-Kucher/table-games-engine/game.schema.json",
+  title: "Store game metadata (game.json)",
+  type: "object",
+  definitions: {
+    localized: {
+      oneOf: [
+        { type: "string", minLength: 1 },
+        { type: "object", minProperties: 1, additionalProperties: { type: "string", minLength: 1 } }
+      ]
+    }
+  },
+  required: ["slug", "name", "version", "engine", "players", "locales", "description", "rules", "authors", "listed", "client"],
+  additionalProperties: false,
+  properties: {
+    $schema: { type: "string" },
+    slug: { type: "string", pattern: "^[a-z][a-z0-9-]{1,40}$" },
+    name: { $ref: "#/definitions/localized" },
+    version: { type: "string", pattern: "^\\d+\\.\\d+\\.\\d+$" },
+    engine: { type: "string", minLength: 1 },
+    players: {
+      type: "object",
+      required: ["min", "max"],
+      additionalProperties: false,
+      properties: { min: { type: "integer", minimum: 2 }, max: { type: "integer", minimum: 2 } }
+    },
+    locales: { type: "array", minItems: 1, uniqueItems: true, items: { type: "string", pattern: "^[a-z]{2}(-[A-Z]{2})?$" } },
+    description: { $ref: "#/definitions/localized" },
+    rules: { type: "object", minProperties: 1, additionalProperties: { type: "string", pattern: "\\.md$" } },
+    tags: { type: "array", items: { type: "string" } },
+    cover: { type: "string" },
+    authors: { type: "array", minItems: 1, items: { type: "string", minLength: 1 } },
+    credits: { type: "string" },
+    listed: { type: "boolean" },
+    client: {
+      type: "object",
+      required: ["kind", "entry"],
+      additionalProperties: false,
+      properties: { kind: { enum: ["iframe"] }, entry: { type: "string", minLength: 1 } }
+    },
+    presets: {
+      type: "array",
+      minItems: 1,
+      items: {
+        type: "object",
+        required: ["id", "name", "config"],
+        additionalProperties: false,
+        properties: {
+          id: { type: "string", pattern: "^[a-z0-9-]+$" },
+          name: { $ref: "#/definitions/localized" },
+          config: { type: "object" }
+        }
+      }
+    },
+    simulation: {
+      type: "object",
+      additionalProperties: false,
+      properties: { maxSteps: { type: "integer", minimum: 1 } }
+    }
+  }
+};
+
+// src/game-json.ts
+var DEFAULT_MAX_STEPS = 2e3;
+var validateSchema = new Ajv({ allErrors: true }).compile(game_schema_default);
+function validateGameJson(raw, dir) {
+  if (!validateSchema(raw)) {
+    return {
+      ok: false,
+      errors: (validateSchema.errors ?? []).map((e) => `${e.instancePath || "/"} ${e.message ?? "invalid"}`)
+    };
+  }
+  const game = raw;
+  const errors = [];
+  const coverage = (field, value) => {
+    if (typeof value === "string") return;
+    for (const l of game.locales) if (!value[l]) errors.push(`${field}: missing locale "${l}"`);
+  };
+  coverage("name", game.name);
+  coverage("description", game.description);
+  game.presets?.forEach((p, i) => coverage(`presets[${i}].name`, p.name));
+  for (const l of game.locales) {
+    const file = game.rules[l];
+    if (!file) errors.push(`rules: missing locale "${l}"`);
+    else if (!existsSync(join(dir, file))) errors.push(`rules.${l}: file "${file}" not found`);
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (const p of game.presets ?? []) {
+    if (seen.has(p.id)) errors.push(`presets: duplicate id "${p.id}"`);
+    seen.add(p.id);
+  }
+  if (game.players.min > game.players.max) errors.push(`players: min (${game.players.min}) > max (${game.players.max})`);
+  return errors.length > 0 ? { ok: false, errors } : { ok: true, game };
+}
+
+// src/load-game.ts
+import { readFileSync } from "node:fs";
+import { join as join2 } from "node:path";
+import { pathToFileURL } from "node:url";
+import { tsImport } from "tsx/esm/api";
+async function loadGame(dir) {
+  const checked = validateGameJson(JSON.parse(readFileSync(join2(dir, "game.json"), "utf8")), dir);
+  if (!checked.ok) throw new Error(`game.json is invalid:
+  ${checked.errors.join("\n  ")}`);
+  const mod = await tsImport(pathToFileURL(join2(dir, "logic/index.ts")).href, import.meta.url);
+  if (!mod.default) throw new Error("logic/index.ts must `export default` the GamePlugin");
+  return { game: checked.game, plugin: mod.default };
+}
+
+// src/simulate.ts
+import { createHash } from "node:crypto";
+import {
+  driveAction,
+  rulesFromPlugin,
+  setupMatch
+} from "@table-games-engine/core";
+var MOVE_WARN_LIMIT = 5e3;
+var DEFAULT_PRESET = { id: "default", name: "Default", config: {} };
+function runSimulation(plugin, opts) {
+  if (!plugin.legalMoves) {
+    return { ok: false, played: 0, warnings: [], failures: [{ preset: "-", players: 0, seed: opts.seed, step: 0, reason: "plugin has no legalMoves", lastMoves: [] }] };
+  }
+  const failures = [];
+  const warnings = /* @__PURE__ */ new Set();
+  let played = 0;
+  for (const preset of opts.presets.length > 0 ? opts.presets : [DEFAULT_PRESET]) {
+    for (const players of opts.players) {
+      for (let i = 0; i < opts.matches; i++) {
+        const seed = opts.seed + i;
+        const first = playMatch(plugin, preset, players, seed, opts, warnings);
+        played += 1;
+        if (first.failure) {
+          failures.push(first.failure);
+          continue;
+        }
+        const replay = playMatch(plugin, preset, players, seed, opts, warnings);
+        if (replay.failure || replay.hash !== first.hash) {
+          failures.push({
+            preset: preset.id,
+            players,
+            seed,
+            step: first.step,
+            reason: "non-deterministic: replaying the same seed produced a different final state",
+            lastMoves: first.moves.slice(-20)
+          });
+        }
+      }
+    }
+  }
+  return { ok: failures.length === 0, played, failures, warnings: [...warnings] };
+}
+function playMatch(plugin, preset, players, seed, opts, warnings) {
+  const moves = [];
+  const fail = (step, reason) => ({
+    failure: { preset: preset.id, players, seed, step, reason, lastMoves: moves.slice(-20) },
+    hash: "",
+    step,
+    moves
+  });
+  const playerIds = Array.from({ length: players }, (_, i) => `p${i + 1}`);
+  let state;
+  try {
+    state = setupMatch(plugin, { playerIds, config: preset.config, seed: `sim-${seed}` });
+  } catch (e) {
+    return fail(0, `setup threw: ${message(e)}`);
+  }
+  const rules = rulesFromPlugin(plugin);
+  const random = mulberry32(seed);
+  for (let step = 0; step < opts.maxSteps; step++) {
+    if (state.result) return { failure: null, hash: hashState(state), step, moves };
+    const actor = state.priority.holder ?? state.turn.activePlayer;
+    let options;
+    try {
+      options = plugin.legalMoves(state, actor);
+    } catch (e) {
+      return fail(step, `legalMoves threw: ${message(e)}`);
+    }
+    if (options.length === 0) return fail(step, `legalMoves is empty for ${String(actor)}, who must act`);
+    if (options.length > MOVE_WARN_LIMIT) {
+      warnings.add(`${preset.id}: legalMoves returned ${options.length} moves (> ${MOVE_WARN_LIMIT})`);
+    }
+    const move = options[Math.floor(random() * options.length)];
+    moves.push(move);
+    let driven;
+    try {
+      driven = driveAction(rules, state, { ...move, clientId: `sim-${step}`, stateVersion: state.version });
+    } catch (e) {
+      return fail(step, `game logic threw: ${message(e)}`);
+    }
+    if (!driven.ok) {
+      const why = driven.error.valid ? "unknown" : `${driven.error.error.code}: ${driven.error.error.message}`;
+      return fail(step, `legalMoves offered a move the engine rejected (${why})`);
+    }
+    state = driven.state;
+  }
+  return state.result ? { failure: null, hash: hashState(state), step: opts.maxSteps, moves } : fail(opts.maxSteps, `no result after maxSteps=${opts.maxSteps}`);
+}
+function formatReport(r) {
+  const lines = [`simulate: ${r.played} matches, ${r.failures.length} failed`];
+  for (const w of r.warnings) lines.push(`  warning: ${w}`);
+  for (const f of r.failures.slice(0, 5)) {
+    lines.push(`  FAIL preset=${f.preset} players=${f.players} seed=${f.seed} step=${f.step}: ${f.reason}`);
+    lines.push(`    replay: game-kit simulate --preset ${f.preset} --players ${f.players} --seed ${f.seed} -n 1`);
+    for (const m of f.lastMoves) lines.push(`    ${JSON.stringify(m)}`);
+  }
+  return lines.join("\n");
+}
+function hashState(s) {
+  return createHash("sha256").update(JSON.stringify(s)).digest("hex");
+}
+function message(e) {
+  return e instanceof Error ? e.message : String(e);
+}
+function mulberry32(seed) {
+  let a = seed >>> 0;
+  return () => {
+    a = a + 1831565813 >>> 0;
+    let t = a;
+    t = Math.imul(t ^ t >>> 15, t | 1);
+    t ^= t + Math.imul(t ^ t >>> 7, t | 61);
+    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+  };
+}
+
+// src/check.ts
+import { readFileSync as readFileSync2 } from "node:fs";
+import { join as join3 } from "node:path";
+import { build } from "vite";
+
+// src/lint.ts
+import { relative } from "node:path";
+import { ESLint } from "eslint";
+import tseslint from "typescript-eslint";
+var ALLOWED = "may import only @table-games-engine/core and relative paths";
+var allowedImports = {
+  meta: { type: "problem", schema: [] },
+  create(context) {
+    const check = (node, source) => {
+      if (typeof source !== "string") return;
+      if (source === "@table-games-engine/core" || source.startsWith("./") || source.startsWith("../")) return;
+      context.report({ node, message: `Store game logic ${ALLOWED} (found "${source}").` });
+    };
+    return {
+      ImportDeclaration: (n) => check(n, n.source.value),
+      ExportNamedDeclaration: (n) => n.source && check(n, n.source.value),
+      ExportAllDeclaration: (n) => check(n, n.source.value),
+      ImportExpression: (n) => context.report({ node: n, message: `Dynamic import is not allowed; logic ${ALLOWED}.` })
+    };
+  }
+};
+var NONDETERMINISM = "is non-deterministic or environment-dependent; use ctx.random*/state instead";
+var logicLintConfig = [
+  {
+    files: ["logic/**/*.ts"],
+    languageOptions: { parser: tseslint.parser },
+    plugins: { "game-kit": { rules: { "allowed-imports": allowedImports } } },
+    rules: {
+      "game-kit/allowed-imports": "error",
+      "no-restricted-properties": ["error", { object: "Math", property: "random", message: `Math.random ${NONDETERMINISM}.` }],
+      "no-restricted-globals": [
+        "error",
+        ...["Date", "globalThis", "window", "process", "setTimeout", "setInterval", "fetch", "require"].map((name) => ({
+          name,
+          message: `'${name}' ${NONDETERMINISM}.`
+        }))
+      ],
+      "no-restricted-syntax": [
+        "error",
+        ...["let", "var"].flatMap((kind) => [
+          { selector: `Program > VariableDeclaration[kind='${kind}']`, message: `module-level '${kind}' is shared mutable state across matches.` },
+          { selector: `Program > ExportNamedDeclaration > VariableDeclaration[kind='${kind}']`, message: `module-level '${kind}' is shared mutable state across matches.` }
+        ])
+      ]
+    }
+  }
+];
+async function lintLogic(dir) {
+  const eslint = new ESLint({ cwd: dir, overrideConfigFile: true, overrideConfig: logicLintConfig });
+  const results = await eslint.lintFiles(["logic/**/*.ts"]);
+  const lines = results.flatMap(
+    (r) => r.messages.map((m) => `${relative(dir, r.filePath)}:${m.line}:${m.column} ${m.message}`)
+  );
+  return lines.length > 0 ? lines.join("\n") : null;
+}
+
+// src/exec.ts
+import { spawnSync } from "node:child_process";
+function runTool(cmd, args, cwd) {
+  const r = spawnSync(cmd, [...args], { cwd, stdio: "inherit", shell: process.platform === "win32" });
+  return r.status ?? 1;
+}
+
+// src/check.ts
+async function runCheck(dir, stages = defaultStages) {
+  for (const stage of stages) {
+    let failure;
+    try {
+      failure = await stage.run(dir);
+    } catch (e) {
+      failure = e instanceof Error ? e.message : String(e);
+    }
+    if (failure !== null) return { ok: false, failedStage: stage.name, message: failure };
+  }
+  return { ok: true };
+}
+var tool = (name, cmd, args) => ({
+  name,
+  run: async (dir) => runTool(cmd, args, dir) === 0 ? null : `${cmd} ${args.join(" ")} failed`
+});
+function simulateStage(opts) {
+  return {
+    name: "simulate",
+    run: async (dir) => {
+      const { game, plugin } = await loadGame(dir);
+      const presets = (game.presets ?? []).filter((p) => !opts.preset || p.id === opts.preset);
+      if (opts.preset && presets.length === 0) return `unknown preset "${opts.preset}"`;
+      const { min, max } = game.players;
+      if (opts.players !== void 0 && (opts.players < min || opts.players > max)) {
+        return `--players ${opts.players} is outside game.json players (${min}..${max})`;
+      }
+      const report = runSimulation(plugin, {
+        matches: opts.matches,
+        seed: opts.seed,
+        maxSteps: game.simulation?.maxSteps ?? DEFAULT_MAX_STEPS,
+        players: opts.players !== void 0 ? [opts.players] : Array.from({ length: max - min + 1 }, (_, i) => min + i),
+        presets
+      });
+      console.log(formatReport(report));
+      return report.ok ? null : "simulation failed (see above)";
+    }
+  };
+}
+var defaultStages = [
+  {
+    name: "game.json",
+    run: async (dir) => {
+      const r = validateGameJson(JSON.parse(readFileSync2(join3(dir, "game.json"), "utf8")), dir);
+      return r.ok ? null : r.errors.join("\n");
+    }
+  },
+  { name: "lint", run: lintLogic },
+  tool("typecheck", "npx", ["tsc", "--noEmit", "-p", "."]),
+  tool("test", "npx", ["vitest", "run"]),
+  simulateStage({ matches: 1e3, seed: 1 }),
+  {
+    name: "client-build",
+    run: async (dir) => {
+      await build({ root: join3(dir, "client"), logLevel: "warn", build: { outDir: "dist", emptyOutDir: true } });
+      return null;
+    }
+  }
+];
+export {
+  DEFAULT_MAX_STEPS,
+  defaultStages,
+  formatReport,
+  lintLogic,
+  loadGame,
+  runCheck,
+  runSimulation,
+  simulateStage,
+  validateGameJson
+};

package/dist/lint.d.ts

@@ -0,0 +1,3 @@
+import { type Linter } from 'eslint';
+export declare const logicLintConfig: Linter.Config[];
+export declare function lintLogic(dir: string): Promise<string | null>;

package/dist/load-game.d.ts

@@ -0,0 +1,6 @@
+import type { GamePlugin } from '@table-games-engine/core';
+import { type GameJson } from './game-json.js';
+export declare function loadGame(dir: string): Promise<{
+    game: GameJson;
+    plugin: GamePlugin;
+}>;

package/dist/preview.d.ts

@@ -0,0 +1,4 @@
+export declare function preview(dir: string, opts: {
+    preset?: string;
+    locale?: string;
+}): Promise<void>;

package/dist/simulate.d.ts

@@ -0,0 +1,26 @@
+import { type GamePlugin, type LegalMove } from '@table-games-engine/core';
+import type { Preset } from './game-json.js';
+export interface SimulateOptions {
+    readonly matches: number;
+    readonly seed: number;
+    readonly maxSteps: number;
+    /** Player counts to play, e.g. every count from game.json players.min to max. */
+    readonly players: ReadonlyArray<number>;
+    readonly presets: ReadonlyArray<Preset>;
+}
+export interface MatchFailure {
+    readonly preset: string;
+    readonly players: number;
+    readonly seed: number;
+    readonly step: number;
+    readonly reason: string;
+    readonly lastMoves: ReadonlyArray<LegalMove>;
+}
+export interface SimulateReport {
+    readonly ok: boolean;
+    readonly played: number;
+    readonly failures: ReadonlyArray<MatchFailure>;
+    readonly warnings: ReadonlyArray<string>;
+}
+export declare function runSimulation(plugin: GamePlugin, opts: SimulateOptions): SimulateReport;
+export declare function formatReport(r: SimulateReport): string;

package/host/index.html

@@ -0,0 +1,19 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>game-kit preview</title>
+    <style>
+      body { font-family: system-ui, sans-serif; margin: 16px; }
+      #seats { display: grid; grid-template-columns: 1fr 1fr; gap: 16px; }
+      iframe { width: 100%; height: 70vh; border: 1px solid #ccc; border-radius: 8px; }
+      #log { font-size: 12px; color: #666; white-space: pre-wrap; }
+    </style>
+  </head>
+  <body>
+    <h1 id="title">game-kit preview</h1>
+    <div id="seats"></div>
+    <pre id="log"></pre>
+    <script type="module" src="./main.ts"></script>
+  </body>
+</html>

package/host/main.ts

@@ -0,0 +1,70 @@
+/**
+ * Reference store host: two device sessions, one private match, one
+ * sandboxed iframe + bridge per seat. Store web hosts follow this shape.
+ */
+import { Client, type Session, type Socket } from '@heroiclabs/nakama-js';
+import type { LegalMove, PlayerView } from '@table-games-engine/core';
+import { createBridgeHost, iframePort, type StatePayload } from '@table-games-engine/game-kit/bridge';
+
+declare const __GAME_KIT__: { gameId: string; config: Record<string, unknown>; locale: string; clientUrl: string; title: string };
+const cfg = __GAME_KIT__;
+const log = (m: string) => (document.getElementById('log')!.textContent += `${m}\n`);
+document.getElementById('title')!.textContent = `${cfg.title} — preview (${cfg.locale})`;
+
+const client = new Client('defaultkey', '127.0.0.1', '7350', false);
+const run = crypto.randomUUID().slice(0, 8);
+
+async function seat(index: number, session: Session, matchId: string): Promise<void> {
+  const iframe = document.createElement('iframe');
+  iframe.setAttribute('sandbox', 'allow-scripts');
+  iframe.src = `${cfg.clientUrl}?locale=${encodeURIComponent(cfg.locale)}`;
+  document.getElementById('seats')!.appendChild(iframe);
+
+  const socket: Socket = client.createSocket(false, false);
+  let version = 0;
+  let counter = 0;
+  let last: StatePayload | null = null;
+  const bridge = createBridgeHost(iframePort(iframe), (move: LegalMove) => {
+    const base = { clientId: `s${index}-${counter++}`, stateVersion: version };
+    const envelope =
+      move.data.type === 'action' ? { kind: 'action', ...base, action: move.data } : { kind: move.type, ...base };
+    void socket.sendMatchState(matchId, 1, JSON.stringify(envelope));
+  });
+  socket.onmatchdata = (msg) => {
+    const body = JSON.parse(typeof msg.data === 'string' ? msg.data : new TextDecoder().decode(msg.data));
+    if (msg.op_code === 1) {
+      const view = body.view as PlayerView;
+      version = body.version;
+      const seatIndex = Object.keys(view.players).indexOf(view.viewerId as string);
+      last = { view, seat: seatIndex, legalMoves: body.legalMoves ?? [], status: 'active' };
+      bridge.pushState(last);
+    } else if (msg.op_code === 2 && body.ok === false) {
+      log(`seat ${index + 1}: rejected ${body.error?.code}: ${body.error?.message}`);
+      bridge.notice('rejected');
+    } else if (msg.op_code === 4 && last) {
+      last = { ...last, legalMoves: [], status: 'finished', result: body.result };
+      bridge.pushState(last);
+      log(`match ended: ${JSON.stringify(body.result)}`);
+    }
+  };
+  socket.ondisconnect = () => bridge.notice('reconnecting');
+  await socket.connect(session, true);
+  await socket.joinMatch(matchId);
+}
+
+async function start(): Promise<void> {
+  const s1 = await client.authenticateDevice(`gk-${run}-seat1-device`, true, `seat1-${run}`);
+  const s2 = await client.authenticateDevice(`gk-${run}-seat2-device`, true, `seat2-${run}`);
+  const rpc = await client.rpc(s1, 'create_tabletop_match', JSON.stringify({
+    gameId: cfg.gameId,
+    playerIds: [s1.user_id, s2.user_id],
+    config: cfg.config,
+  }) as never);
+  const payload = rpc.payload as unknown;
+  const { matchId } = (typeof payload === 'string' ? JSON.parse(payload) : payload) as { matchId: string };
+  log(`match ${matchId}`);
+  await seat(0, s1, matchId);
+  await seat(1, s2, matchId);
+}
+
+start().catch((e) => log(`error: ${e instanceof Error ? e.message : JSON.stringify(e)}`));

package/nakama/docker-compose.yml

@@ -0,0 +1,59 @@
+# Nakama + Postgres stack for local playground / smoke testing.
+#
+# Boots Postgres 12 first (Nakama's metadata store), waits for it to be
+# healthy, then starts Nakama 3.21+. Nakama's TS runtime loads our
+# bundled `build/index.js` via the `runtime.path` and
+# `runtime.js_entrypoint` settings in `local.yml` (mounted read-only).
+#
+# Ports
+#   7350 — Nakama HTTP API (gRPC, REST, WebSocket socket)
+#   7351 — Nakama Console (browser UI)
+#   7349 — Nakama gRPC (cluster / admin)
+services:
+  postgres:
+    image: postgres:12-alpine
+    environment:
+      POSTGRES_DB: nakama
+      POSTGRES_USER: nakama
+      POSTGRES_PASSWORD: localdev
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U nakama -d nakama"]
+      interval: 3s
+      timeout: 3s
+      retries: 20
+    expose:
+      - "5432"
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+
+  nakama:
+    # Use the Docker Hub multi-arch image (amd64 + arm64). The
+    # `registry.heroiclabs.com` mirror is amd64-only at older tags and
+    # crashes under Rosetta on Apple Silicon.
+    image: heroiclabs/nakama:3.30.0
+    depends_on:
+      postgres:
+        condition: service_healthy
+    entrypoint:
+      - "/bin/sh"
+      - "-ecx"
+      - >
+        /nakama/nakama migrate up --database.address postgres://nakama:localdev@postgres:5432/nakama &&
+        exec /nakama/nakama
+        --config /nakama/data/local.yml
+        --database.address postgres://nakama:localdev@postgres:5432/nakama
+    healthcheck:
+      test: ["CMD", "/nakama/nakama", "healthcheck"]
+      interval: 5s
+      timeout: 5s
+      retries: 20
+    ports:
+      - "7349:7349"
+      - "7350:7350"
+      - "7351:7351"
+    volumes:
+      - ./local.yml:/nakama/data/local.yml:ro
+      - ./build:/nakama/data/modules:ro
+
+volumes:
+  pgdata: