@dreamboard-games/workspace-codegen 0.1.0

package/src/__fixtures__/sdk-types/valid-player-scoped-seed-homes.ts

@@ -0,0 +1,59 @@
+import { defineTopologyManifest } from "@dreamboard/sdk-types";
+
+defineTopologyManifest({
+  players: {
+    minPlayers: 2,
+    maxPlayers: 2,
+    optimalPlayers: 2,
+  },
+  cardSets: [],
+  zones: [
+    {
+      id: "main-hand",
+      name: "Main Hand",
+      scope: "perPlayer",
+    },
+  ],
+  boardTemplates: [],
+  boards: [
+    {
+      id: "player-grid",
+      name: "Player Grid",
+      layout: "square",
+      scope: "perPlayer",
+      spaces: [{ id: "cell-a", row: 0, col: 0 }],
+      relations: [],
+      containers: [],
+      edges: [],
+      vertices: [],
+    },
+  ],
+  pieceTypes: [{ id: "meeple", name: "Meeple" }],
+  pieceSeeds: [
+    {
+      id: "worker-a",
+      typeId: "meeple",
+      ownerId: "player-1",
+      home: {
+        type: "space",
+        boardId: "player-grid",
+        spaceId: "cell-a",
+      },
+    },
+  ],
+  dieTypes: [{ id: "d6", name: "D6", sides: 6 }],
+  dieSeeds: [
+    {
+      id: "die-a",
+      typeId: "d6",
+      ownerId: "player-1",
+      home: {
+        type: "zone",
+        zoneId: "main-hand",
+      },
+    },
+  ],
+  resources: [],
+  setupOptions: [],
+  setupProfiles: [],
+} as const);

package/src/authoring-benchmark.test.ts

@@ -0,0 +1,362 @@
+import { lstat, mkdir, mkdtemp, readFile, rm, symlink } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { expect, test } from "bun:test";
+import type { GameTopologyManifest } from "@dreamboard/sdk-types";
+import { generateAuthoritativeFiles } from "./index.js";
+import { validateManifestAuthoring } from "./manifest-validation.js";
+import { materializeManifest } from "../../../apps/dreamboard-cli/src/services/project/manifest-authoring.ts";
+
+const repoRoot = path.resolve(import.meta.dir, "../../..");
+const benchmarkRoot = path.join(repoRoot, "examples", "board-contract-lab");
+const thingsInRingsRoot = path.join(repoRoot, "examples", "things-in-rings");
+const pnpmBinary = process.platform === "win32" ? "pnpm.cmd" : "pnpm";
+const miseBinary = process.platform === "win32" ? "mise.cmd" : "mise";
+const WORKSPACE_NODE_MODULES = path.join(
+  repoRoot,
+  "apps",
+  "dreamboard-cli",
+  "node_modules",
+);
+const UI_SDK_NODE_MODULES = path.join(
+  repoRoot,
+  "packages",
+  "ui-sdk",
+  "node_modules",
+);
+const SDK_TYPES_PACKAGE_ROOT = path.join(repoRoot, "packages", "sdk-types");
+const EXPECTED_UI_FRAMEWORK_TSCONFIG = `{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "paths": {
+      "@dreamboard/manifest-contract": [
+        "../shared/manifest-contract.ts"
+      ],
+      "@dreamboard/ui-contract": [
+        "../shared/generated/ui-contract.ts"
+      ],
+      "@shared/*": [
+        "../shared/*"
+      ]
+    }
+  },
+  "include": [
+    "./**/*.ts",
+    "./**/*.tsx",
+    "../shared/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist"
+  ]
+}
+`;
+
+async function loadBenchmarkManifest(): Promise<GameTopologyManifest> {
+  return materializeManifest(benchmarkRoot) as Promise<GameTopologyManifest>;
+}
+
+async function ensureSymlink(targetPath: string, linkPath: string) {
+  try {
+    await lstat(linkPath);
+    return;
+  } catch {
+    // Fall through and create the symlink.
+  }
+
+  await mkdir(path.dirname(linkPath), { recursive: true });
+  await symlink(
+    targetPath,
+    linkPath,
+    process.platform === "win32" ? "junction" : "dir",
+  );
+}
+
+function collectComponentHomeTypes(
+  manifest: GameTopologyManifest,
+): Set<string> {
+  const homes = new Set<string>();
+
+  for (const cardSet of manifest.cardSets) {
+    if (cardSet.type !== "manual") {
+      continue;
+    }
+    for (const card of cardSet.cards) {
+      if (card.home?.type) {
+        homes.add(card.home.type);
+      }
+    }
+  }
+
+  for (const component of [...manifest.pieceSeeds, ...manifest.dieSeeds]) {
+    if (component.home?.type) {
+      homes.add(component.home.type);
+    }
+  }
+
+  return homes;
+}
+
+function decodeOutput(buffer: Uint8Array<ArrayBufferLike>): string {
+  return new TextDecoder().decode(buffer);
+}
+
+function runNode20ExampleScript(exampleRoot: string, scriptName: string) {
+  return Bun.spawnSync({
+    cmd: [
+      miseBinary,
+      "exec",
+      "node@20",
+      "--",
+      pnpmBinary,
+      "--dir",
+      exampleRoot,
+      scriptName,
+    ],
+    cwd: repoRoot,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+}
+
+function throwTypecheckError(
+  label: string,
+  result: ReturnType<typeof Bun.spawnSync>,
+): never {
+  throw new Error(
+    [
+      `Typecheck failed for ${label}`,
+      "",
+      "stdout:",
+      decodeOutput(result.stdout),
+      "",
+      "stderr:",
+      decodeOutput(result.stderr),
+    ].join("\n"),
+  );
+}
+
+async function formatWithRepoPrettier(
+  relativePath: string,
+  content: string,
+): Promise<string> {
+  const tempRoot = await mkdtemp(
+    path.join(os.tmpdir(), "db-authoring-benchmark-"),
+  );
+  const tempFile = path.join(tempRoot, relativePath);
+
+  await Bun.write(tempFile, content);
+
+  try {
+    const result = Bun.spawnSync({
+      cmd: [
+        pnpmBinary,
+        "exec",
+        "prettier",
+        "--log-level",
+        "warn",
+        "--write",
+        tempFile,
+      ],
+      cwd: repoRoot,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    if (result.exitCode !== 0) {
+      throw new Error(
+        [
+          `Prettier failed for generated benchmark file ${relativePath}`,
+          "",
+          "stdout:",
+          decodeOutput(result.stdout),
+          "",
+          "stderr:",
+          decodeOutput(result.stderr),
+        ].join("\n"),
+      );
+    }
+
+    return await readFile(tempFile, "utf8");
+  } finally {
+    await rm(tempRoot, { recursive: true, force: true });
+  }
+}
+
+test("board-contract-lab covers the stricter authored manifest surfaces", async () => {
+  const manifest = await loadBenchmarkManifest();
+  const validation = validateManifestAuthoring(manifest);
+
+  expect(validation.errors).toEqual([]);
+  expect(new Set(manifest.boards.map((board) => board.layout))).toEqual(
+    new Set(["generic", "hex", "square"]),
+  );
+  expect(new Set(manifest.boards.map((board) => board.scope))).toEqual(
+    new Set(["shared", "perPlayer"]),
+  );
+  expect(
+    new Set(
+      manifest.boards
+        .map((board) => board.templateId)
+        .filter((templateId): templateId is string => Boolean(templateId)),
+    ),
+  ).toEqual(
+    new Set(["market-template", "frontier-template", "player-mat-template"]),
+  );
+  expect(new Set(manifest.cardSets.map((cardSet) => cardSet.type))).toEqual(
+    new Set(["manual", "preset"]),
+  );
+  expect(collectComponentHomeTypes(manifest)).toEqual(
+    new Set(["zone", "space", "container", "edge", "vertex", "slot"]),
+  );
+  expect(manifest.setupOptions.map((option) => option.id)).toEqual([
+    "map",
+    "market",
+    "crew",
+  ]);
+  expect(manifest.setupProfiles.map((profile) => profile.id)).toEqual([
+    "standard-expedition",
+    "river-draft",
+  ]);
+});
+
+test("board-contract-lab authoritative generated files stay in sync with workspace-codegen", async () => {
+  const manifest = await loadBenchmarkManifest();
+  const authoritativeFiles = generateAuthoritativeFiles(manifest);
+
+  expect(Object.keys(authoritativeFiles).sort()).toEqual([
+    "app/index.ts",
+    "app/tsconfig.framework.json",
+    "shared/generated/ui-contract.ts",
+    "shared/manifest-contract.ts",
+    "shared/manifest-literals.ts",
+    "shared/manifest-runtime.ts",
+    "shared/manifest-types.ts",
+    "ui/tsconfig.framework.json",
+  ]);
+
+  for (const [relativePath, expected] of Object.entries(authoritativeFiles)) {
+    const filePath = path.join(benchmarkRoot, relativePath);
+    const actual = await readFile(filePath, "utf8");
+    const formattedExpected = await formatWithRepoPrettier(
+      relativePath,
+      expected,
+    );
+    expect(actual).toBe(formattedExpected);
+  }
+}, 20_000);
+
+test("authoritative ui framework tsconfig uses the scaffold format", async () => {
+  const authoritativeFiles = generateAuthoritativeFiles(
+    await loadBenchmarkManifest(),
+  );
+
+  expect(authoritativeFiles["ui/tsconfig.framework.json"]).toBe(
+    EXPECTED_UI_FRAMEWORK_TSCONFIG,
+  );
+});
+
+test("generated ui-contract.ts exposes a typed useHexBoardView wrapper", async () => {
+  const manifest = await loadBenchmarkManifest();
+  const authoritativeFiles = generateAuthoritativeFiles(manifest);
+
+  const uiContract = authoritativeFiles["shared/generated/ui-contract.ts"];
+  if (!uiContract) {
+    throw new Error(
+      "Missing shared/generated/ui-contract.ts in codegen output.",
+    );
+  }
+
+  // Imports static topology and exports the workspace-typed helper.
+  expect(uiContract).toContain("staticBoards");
+  expect(uiContract).toContain("createHexBoardView");
+  expect(uiContract).toContain("export function useHexBoardView");
+
+  // Constrains the boardId argument to the manifest's hex-board ids and
+  // narrows TSpaceView.id to that board's space-id type.
+  expect(uiContract).toContain("export type HexBoardId");
+  expect(uiContract).toContain("keyof typeof hexStaticBoards");
+  expect(uiContract).toContain("Id extends HexBoardId");
+  expect(uiContract).toContain("BoardSpaceIdOf");
+});
+
+test("generated ui-contract.ts exposes typed interaction form wrappers", async () => {
+  const manifest = await loadBenchmarkManifest();
+  const authoritativeFiles = generateAuthoritativeFiles(manifest);
+
+  const uiContract = authoritativeFiles["shared/generated/ui-contract.ts"];
+  if (!uiContract) {
+    throw new Error(
+      "Missing shared/generated/ui-contract.ts in codegen output.",
+    );
+  }
+
+  expect(uiContract).toContain("InteractionForm as InteractionFormGeneric");
+  expect(uiContract).toContain("export type InteractionFieldRenderers");
+  expect(uiContract).toContain(
+    "export type InteractionFormProps<Key extends InteractionKey>",
+  );
+  expect(uiContract).toContain("export function InteractionForm");
+  expect(uiContract).toContain("export function InteractionField");
+});
+
+test("generated ui-contract.ts exposes typed Radix-style primitives without GameShell wrappers", async () => {
+  const manifest = await loadBenchmarkManifest();
+  const authoritativeFiles = generateAuthoritativeFiles(manifest);
+
+  const uiContract = authoritativeFiles["shared/generated/ui-contract.ts"];
+  if (!uiContract) {
+    throw new Error(
+      "Missing shared/generated/ui-contract.ts in codegen output.",
+    );
+  }
+
+  expect(uiContract).toContain("export const UI = createDreamboardUI");
+  expect(uiContract).toContain("export const Interaction = UI.Interaction");
+  expect(uiContract).toContain("export const Prompt = UI.Prompt");
+  expect(uiContract).toContain("export const Zone = UI.Zone");
+  expect(uiContract).toContain("export const Board = UI.Board");
+  expect(uiContract).not.toContain("WorkspaceGameShell");
+  expect(uiContract).not.toContain("GameShell as GameShellGeneric");
+  expect(uiContract).not.toContain("defineMarketSurface");
+  expect(uiContract).not.toContain("definePlayerCardsSurface");
+});
+
+test("board-contract-lab manifest authoring typechecks", async () => {
+  await ensureSymlink(
+    WORKSPACE_NODE_MODULES,
+    path.join(benchmarkRoot, "node_modules"),
+  );
+  await ensureSymlink(
+    SDK_TYPES_PACKAGE_ROOT,
+    path.join(benchmarkRoot, "node_modules", "@dreamboard", "sdk-types"),
+  );
+  await ensureSymlink(
+    UI_SDK_NODE_MODULES,
+    path.join(benchmarkRoot, "ui", "node_modules"),
+  );
+
+  const result = runNode20ExampleScript(benchmarkRoot, "typecheck:manifest");
+
+  if (result.exitCode !== 0) {
+    throwTypecheckError(`${benchmarkRoot} manifest`, result);
+  }
+}, 60_000);
+
+test("generated app contracts typecheck under Node 20 without a larger heap", async () => {
+  const examples = [thingsInRingsRoot, benchmarkRoot];
+
+  for (const exampleRoot of examples) {
+    const result = runNode20ExampleScript(exampleRoot, "typecheck:app");
+    if (result.exitCode !== 0) {
+      throwTypecheckError(`${exampleRoot} app`, result);
+    }
+  }
+}, 120_000);

package/src/hex-geometry.ts

@@ -0,0 +1,69 @@
+import type { HexSpaceSpec, HexVertexRef } from "@dreamboard/sdk-types";
+
+const HEX_CORNERS = ["ne-e", "e-se", "se-sw", "sw-w", "w-nw", "nw-ne"] as const;
+type HexCorner = (typeof HEX_CORNERS)[number];
+
+const HEX_CORNER_OFFSETS: Record<HexCorner, readonly [number, number, number]> =
+  {
+    "ne-e": [2, -1, -1],
+    "e-se": [1, -2, 1],
+    "se-sw": [-1, -1, 2],
+    "sw-w": [-2, 1, 1],
+    "w-nw": [-1, 2, -1],
+    "nw-ne": [1, 1, -2],
+  };
+
+function cubeFromAxial(
+  space: Pick<HexSpaceSpec, "q" | "r">,
+): readonly [number, number, number] {
+  const x = space.q;
+  const z = space.r;
+  return [x, -x - z, z] as const;
+}
+
+function cornerGeometryKey(
+  space: Pick<HexSpaceSpec, "q" | "r">,
+  corner: HexCorner,
+): string {
+  const [x, y, z] = cubeFromAxial(space);
+  const [dx, dy, dz] = HEX_CORNER_OFFSETS[corner];
+  return `${3 * x + dx},${3 * y + dy},${3 * z + dz}`;
+}
+
+export function resolveHexVertexGeometryKey(
+  ref: HexVertexRef,
+  spacesById: ReadonlyMap<string, HexSpaceSpec>,
+): string {
+  const resolvedSpaces = [...ref.spaces]
+    .sort((left, right) => left.localeCompare(right))
+    .map((spaceId) => {
+      const space = spacesById.get(spaceId);
+      if (!space) {
+        throw new Error(
+          `Hex vertex ref references unknown space '${spaceId}'.`,
+        );
+      }
+      return space;
+    });
+  const keyCounts = new Map<string, number>();
+  for (const space of resolvedSpaces) {
+    for (const corner of HEX_CORNERS) {
+      const key = cornerGeometryKey(space, corner);
+      keyCounts.set(key, (keyCounts.get(key) ?? 0) + 1);
+    }
+  }
+  const candidates = [...keyCounts.entries()]
+    .filter(([, count]) => count === resolvedSpaces.length)
+    .map(([key]) => key)
+    .sort((left, right) => left.localeCompare(right));
+  if (candidates.length !== 1) {
+    throw new Error(
+      `Hex vertex ref spaces '${ref.spaces.join(", ")}' do not resolve to exactly one shared vertex.`,
+    );
+  }
+  const vertexKey = candidates[0];
+  if (vertexKey === undefined) {
+    throw new Error("internal: expected exactly one hex vertex geometry key");
+  }
+  return vertexKey;
+}

package/src/index.ts

@@ -0,0 +1,64 @@
+import type { GameTopologyManifest } from "@dreamboard/sdk-types";
+import {
+  generateManifestContractSources,
+  materializeManifestTable,
+} from "./manifest-contract.js";
+import { validateManifestAuthoring } from "./manifest-validation.js";
+import {
+  AUTHORITATIVE_GENERATED_FILES,
+  isAllowedGamePath,
+  isAuthoritativeGeneratedPath,
+  isCliStaticPath,
+  isDynamicSeedPath,
+  isLibraryPath,
+  PRESERVED_USER_FILES,
+  SEED_FILES,
+  SEED_FILE_PATTERNS,
+  WORKSPACE_CODEGEN_OWNERSHIP,
+} from "./ownership.js";
+import {
+  generateFrameworkFiles,
+  generateSeedFiles,
+  isFrameworkOwnedSetupProfilesSeed,
+  SETUP_PROFILES_SEED_MARKER,
+} from "./seeds.js";
+export {
+  materializeCardSet,
+  materializePresetCardSet,
+} from "./preset-card-sets.js";
+export { materializeManifestTable };
+
+export {
+  AUTHORITATIVE_GENERATED_FILES,
+  isAllowedGamePath,
+  isAuthoritativeGeneratedPath,
+  isCliStaticPath,
+  isDynamicSeedPath,
+  isLibraryPath,
+  PRESERVED_USER_FILES,
+  SEED_FILES,
+  SEED_FILE_PATTERNS,
+  WORKSPACE_CODEGEN_OWNERSHIP,
+};
+
+export function generateAuthoritativeFiles(
+  manifest: GameTopologyManifest,
+): Record<string, string> {
+  return {
+    ...generateManifestContractSources(manifest),
+    ...generateFrameworkFiles(manifest),
+  };
+}
+
+export { generateSeedFiles };
+export { isFrameworkOwnedSetupProfilesSeed, SETUP_PROFILES_SEED_MARKER };
+export { validateManifestAuthoring };
+
+export function generateDynamicGeneratedFiles(
+  manifest: GameTopologyManifest,
+): Record<string, string> {
+  return {
+    ...generateAuthoritativeFiles(manifest),
+    ...generateSeedFiles(manifest),
+  };
+}