@drmxrcy/tcg-core 0.0.0-202602060542

package/src/flow/index.ts

@@ -0,0 +1,35 @@
+/**
+ * Task 9: Flow Manager
+ *
+ * Flow orchestration system for turn/phase/segment management.
+ *
+ * Key features:
+ * - Rich FlowContext API (not just state)
+ * - Programmatic and automatic transitions
+ * - Configurable progression logic
+ * - Hierarchical states (turn → phases → segments)
+ * - Lifecycle hooks at all levels
+ *
+ * Note: Originally planned to use XState, but a simple state machine
+ * proved more appropriate. No external dependencies needed.
+ *
+ * @module flow
+ */
+
+export type {
+  EndCondition,
+  FlowContext,
+  FlowDefinition,
+  GameSegmentDefinition,
+  LifecycleHook,
+  PhaseDefinition,
+  StepDefinition,
+  TurnDefinition,
+} from "./flow-definition";
+
+export {
+  FlowManager,
+  type FlowManagerOptions,
+  type FlowStateSnapshot,
+  type SerializedFlowState,
+} from "./flow-manager";

package/src/game-definition/__tests__/game-definition-validation.test.ts

@@ -0,0 +1,359 @@
+import { describe, expect, it } from "bun:test";
+import type { GameDefinition } from "../game-definition";
+import type { GameMoveDefinitions } from "../move-definitions";
+import { validateGameDefinition } from "../validation";
+
+/**
+ * Test suite for GameDefinition validation
+ *
+ * Task 10.3, 10.7, 10.9, 10.11, 10.13: Write tests for validation
+ *
+ * Validates:
+ * - Setup function validation
+ * - Flow configuration validation
+ * - EndIf condition validation
+ * - PlayerView function validation
+ * - Zod schema validation
+ */
+
+type SimpleGameState = {
+  value: number;
+  phase: string;
+};
+
+type SimpleMoves = {
+  increment: Record<string, never>;
+  decrement: Record<string, never>;
+};
+
+describe("GameDefinition - Validation", () => {
+  describe("setup function validation (Task 10.3)", () => {
+    it("should validate that setup function exists", () => {
+      const definition = {
+        name: "Test Game",
+        setup: (players: Array<{ id: string; name?: string }>) => ({
+          value: players.length,
+          phase: "start",
+        }),
+        moves: {} as GameMoveDefinitions<SimpleGameState, SimpleMoves>,
+      };
+
+      const result = validateGameDefinition(definition);
+      expect(result.success).toBe(true);
+    });
+
+    it("should reject definition without setup function", () => {
+      const definition = {
+        name: "Test Game",
+        moves: {} as GameMoveDefinitions<SimpleGameState, SimpleMoves>,
+      } as unknown as GameDefinition<SimpleGameState, SimpleMoves>;
+
+      const result = validateGameDefinition(definition);
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        expect(result.error).toContain("setup");
+      }
+    });
+
+    it("should validate that setup function is callable", () => {
+      const definition = {
+        name: "Test Game",
+        setup: "not a function" as unknown,
+        moves: {} as GameMoveDefinitions<SimpleGameState, SimpleMoves>,
+      } as GameDefinition<SimpleGameState, SimpleMoves>;
+
+      const result = validateGameDefinition(definition);
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        expect(result.error).toContain("setup");
+        expect(result.error).toContain("function");
+      }
+    });
+  });
+
+  describe("moves mapping validation (Task 10.5)", () => {
+    it("should validate that moves object exists", () => {
+      const definition: GameDefinition<SimpleGameState, SimpleMoves> = {
+        name: "Test Game",
+        setup: () => ({ value: 0, phase: "start" }),
+        moves: {
+          increment: {
+            reducer: (draft) => {
+              draft.value += 1;
+            },
+          },
+          decrement: {
+            reducer: (draft) => {
+              draft.value -= 1;
+            },
+          },
+        },
+      };
+
+      const result = validateGameDefinition(definition);
+      expect(result.success).toBe(true);
+    });
+
+    it("should reject definition without moves", () => {
+      const definition = {
+        name: "Test Game",
+        setup: () => ({ value: 0, phase: "start" }),
+      };
+
+      const result = validateGameDefinition(definition as any);
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        expect(result.error).toContain("moves");
+      }
+    });
+
+    it("should validate that each move has a reducer", () => {
+      const definition = {
+        name: "Test Game",
+        setup: () => ({ value: 0, phase: "start" }),
+        moves: {
+          increment: {}, // Missing reducer
+          decrement: {},
+        },
+      };
+
+      const result = validateGameDefinition(definition as any);
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        expect(result.error).toContain("reducer");
+      }
+    });
+  });
+
+  describe("endIf validation (Task 10.9)", () => {
+    it("should accept optional endIf function", () => {
+      const definition: GameDefinition<SimpleGameState, SimpleMoves> = {
+        name: "Test Game",
+        setup: () => ({ value: 0, phase: "start" }),
+        moves: {
+          increment: {
+            reducer: (draft) => {
+              draft.value += 1;
+            },
+          },
+          decrement: {
+            reducer: (draft) => {
+              draft.value -= 1;
+            },
+          },
+        },
+        endIf: (state) => {
+          if (state.value >= 10) {
+            return { winner: "player1", reason: "reached-10" };
+          }
+          return undefined;
+        },
+      };
+
+      const result = validateGameDefinition(definition);
+      expect(result.success).toBe(true);
+    });
+
+    it("should work without endIf function", () => {
+      const definition: GameDefinition<SimpleGameState, SimpleMoves> = {
+        name: "Test Game",
+        setup: () => ({ value: 0, phase: "start" }),
+        moves: {
+          increment: {
+            reducer: (draft) => {
+              draft.value += 1;
+            },
+          },
+          decrement: {
+            reducer: (draft) => {
+              draft.value -= 1;
+            },
+          },
+        },
+      };
+
+      const result = validateGameDefinition(definition);
+      expect(result.success).toBe(true);
+    });
+
+    it("should reject non-function endIf", () => {
+      const definition = {
+        name: "Test Game",
+        setup: () => ({ value: 0, phase: "start" }),
+        moves: {
+          increment: {
+            reducer: (draft: SimpleGameState) => {
+              draft.value += 1;
+            },
+          },
+          decrement: {
+            reducer: (draft: SimpleGameState) => {
+              draft.value -= 1;
+            },
+          },
+        },
+        endIf: "not a function",
+      };
+
+      const result = validateGameDefinition(definition as any);
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        expect(result.error).toContain("endIf");
+        expect(result.error).toContain("function");
+      }
+    });
+  });
+
+  describe("playerView validation (Task 10.11)", () => {
+    it("should accept optional playerView function", () => {
+      const definition: GameDefinition<SimpleGameState, SimpleMoves> = {
+        name: "Test Game",
+        setup: () => ({ value: 0, phase: "start" }),
+        moves: {
+          increment: {
+            reducer: (draft) => {
+              draft.value += 1;
+            },
+          },
+          decrement: {
+            reducer: (draft) => {
+              draft.value -= 1;
+            },
+          },
+        },
+        playerView: (state, playerId) => {
+          // Return filtered state for this player
+          return { ...state, value: playerId === "p1" ? state.value : 0 };
+        },
+      };
+
+      const result = validateGameDefinition(definition);
+      expect(result.success).toBe(true);
+    });
+
+    it("should work without playerView function", () => {
+      const definition: GameDefinition<SimpleGameState, SimpleMoves> = {
+        name: "Test Game",
+        setup: () => ({ value: 0, phase: "start" }),
+        moves: {
+          increment: {
+            reducer: (draft) => {
+              draft.value += 1;
+            },
+          },
+          decrement: {
+            reducer: (draft) => {
+              draft.value -= 1;
+            },
+          },
+        },
+      };
+
+      const result = validateGameDefinition(definition);
+      expect(result.success).toBe(true);
+    });
+
+    it("should reject non-function playerView", () => {
+      const definition = {
+        name: "Test Game",
+        setup: () => ({ value: 0, phase: "start" }),
+        moves: {
+          increment: {
+            reducer: (draft: SimpleGameState) => {
+              draft.value += 1;
+            },
+          },
+          decrement: {
+            reducer: (draft: SimpleGameState) => {
+              draft.value -= 1;
+            },
+          },
+        },
+        playerView: "not a function",
+      };
+
+      const result = validateGameDefinition(definition as any);
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        expect(result.error).toContain("playerView");
+        expect(result.error).toContain("function");
+      }
+    });
+  });
+
+  describe("name validation", () => {
+    it("should require a non-empty name", () => {
+      const definition = {
+        name: "",
+        setup: () => ({ value: 0, phase: "start" }),
+        moves: {
+          increment: {
+            reducer: (draft: SimpleGameState) => {
+              draft.value += 1;
+            },
+          },
+          decrement: {
+            reducer: (draft: SimpleGameState) => {
+              draft.value -= 1;
+            },
+          },
+        },
+      };
+
+      const result = validateGameDefinition(definition as any);
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        expect(result.error).toContain("name");
+      }
+    });
+  });
+
+  // Note: minPlayers and maxPlayers are not part of GameDefinition spec
+  // Player count validation is handled at the application level, not in the core engine
+
+  describe("comprehensive validation (Task 10.13)", () => {
+    it("should validate all fields together", () => {
+      const validDefinition: GameDefinition<SimpleGameState, SimpleMoves> = {
+        name: "Complete Game",
+        setup: (players) => ({
+          value: players.length,
+          phase: "start",
+        }),
+        moves: {
+          increment: {
+            reducer: (draft) => {
+              draft.value += 1;
+            },
+          },
+          decrement: {
+            reducer: (draft) => {
+              draft.value -= 1;
+            },
+          },
+        },
+        endIf: (state) => {
+          if (state.value >= 10) {
+            return { winner: "p1", reason: "goal-reached" };
+          }
+          return undefined;
+        },
+        playerView: (state) => state,
+      };
+
+      const result = validateGameDefinition(validDefinition);
+      expect(result.success).toBe(true);
+    });
+
+    it("should provide detailed error messages for multiple errors", () => {
+      const invalidDefinition = {
+        name: "",
+        setup: "not a function",
+        moves: null,
+      };
+
+      const result = validateGameDefinition(invalidDefinition as any);
+      expect(result.success).toBe(false);
+      // Should report multiple validation failures
+    });
+  });
+});

package/src/game-definition/__tests__/game-definition.test.ts

@@ -0,0 +1,291 @@
+import { describe, expect, it } from "bun:test";
+import type { Draft } from "immer";
+import { createPlayerId } from "../../types";
+import type { GameDefinition } from "../game-definition";
+import type { GameMoveDefinitions } from "../move-definitions";
+
+/**
+ * Test suite for GameDefinition type system
+ *
+ * Task 10.1: Write tests for GameDefinition type with generics
+ *
+ * Validates:
+ * - Generic type parameters work correctly
+ * - All required fields are present
+ * - Optional fields work as expected
+ * - Type safety is preserved
+ */
+
+// Example game state for testing
+type TestGameState = {
+  players: Array<{ id: string; name: string; score: number }>;
+  currentPlayerIndex: number;
+  phase: "setup" | "playing" | "ended";
+  winner?: string;
+};
+
+// Example moves for testing
+type TestMoves = {
+  incrementScore: { playerId: string; amount: number };
+  nextPlayer: Record<string, never>;
+  endGame: { winnerId: string };
+};
+
+describe("GameDefinition - Type System", () => {
+  describe("basic structure", () => {
+    it("should create a valid GameDefinition with all required fields", () => {
+      const moves: GameMoveDefinitions<TestGameState, TestMoves> = {
+        incrementScore: {
+          reducer: (draft, context) => {
+            const player = draft.players.find((p) => p.id === context.playerId);
+            if (player && context.params?.amount) {
+              player.score += context.params.amount as number;
+            }
+          },
+        },
+        nextPlayer: {
+          reducer: (draft) => {
+            draft.currentPlayerIndex =
+              (draft.currentPlayerIndex + 1) % draft.players.length;
+          },
+        },
+        endGame: {
+          reducer: (draft, context) => {
+            draft.phase = "ended";
+            if (context.params?.winnerId) {
+              draft.winner = context.params.winnerId as string;
+            }
+          },
+        },
+      };
+
+      const definition: GameDefinition<TestGameState, TestMoves> = {
+        name: "Test Game",
+        setup: (players) => ({
+          players: players.map((p, i) => ({
+            id: p.id,
+            name: p.name || `Player ${i + 1}`,
+            score: 0,
+          })),
+          currentPlayerIndex: 0,
+          phase: "setup",
+        }),
+        moves,
+      };
+
+      expect(definition.name).toBe("Test Game");
+      expect(definition.setup).toBeFunction();
+      expect(definition.moves).toEqual(moves);
+    });
+
+    it("should work with optional endIf field", () => {
+      const definition: GameDefinition<TestGameState, TestMoves> = {
+        name: "Test Game",
+        setup: () => ({
+          players: [],
+          currentPlayerIndex: 0,
+          phase: "setup",
+        }),
+        moves: {} as GameMoveDefinitions<TestGameState, TestMoves>,
+        endIf: (state) => {
+          if (state.phase === "ended" && state.winner) {
+            return {
+              winner: state.winner,
+              reason: "game-ended",
+            };
+          }
+          return undefined;
+        },
+      };
+
+      expect(definition.endIf).toBeFunction();
+    });
+
+    it("should work with optional playerView field", () => {
+      const definition: GameDefinition<TestGameState, TestMoves> = {
+        name: "Test Game",
+        setup: () => ({
+          players: [],
+          currentPlayerIndex: 0,
+          phase: "setup",
+        }),
+        moves: {} as GameMoveDefinitions<TestGameState, TestMoves>,
+        playerView: (state, playerId) => {
+          // Filter state for this player
+          return {
+            ...state,
+            players: state.players.map((p) => ({
+              ...p,
+              // Hide scores from other players
+              score: p.id === playerId ? p.score : 0,
+            })),
+          };
+        },
+      };
+
+      expect(definition.playerView).toBeFunction();
+    });
+  });
+
+  describe("generic type safety", () => {
+    it("should enforce state type in setup function", () => {
+      const definition: GameDefinition<TestGameState, TestMoves> = {
+        name: "Test Game",
+        setup: (players) => {
+          // TypeScript should enforce return type
+          const state: TestGameState = {
+            players: players.map((p) => ({
+              id: p.id,
+              name: p.name || "Player",
+              score: 0,
+            })),
+            currentPlayerIndex: 0,
+            phase: "setup",
+          };
+          return state;
+        },
+        moves: {} as GameMoveDefinitions<TestGameState, TestMoves>,
+      };
+
+      const players = [
+        { id: createPlayerId("p1"), name: "Alice" },
+        { id: createPlayerId("p2"), name: "Bob" },
+      ];
+      const initialState = definition.setup(players);
+
+      expect(initialState.players).toHaveLength(2);
+      expect(initialState.phase).toBe("setup");
+    });
+
+    it("should enforce move types in MoveDefinitions", () => {
+      // This test validates type safety at compile time
+      const moves: GameMoveDefinitions<TestGameState, TestMoves> = {
+        incrementScore: {
+          reducer: (draft: Draft<TestGameState>, context) => {
+            // context.params should be type-checked
+            const amount = context.params?.amount as number;
+            const player = draft.players[0];
+            if (player) {
+              player.score += amount;
+            }
+          },
+        },
+        nextPlayer: {
+          reducer: (draft: Draft<TestGameState>) => {
+            draft.currentPlayerIndex += 1;
+          },
+        },
+        endGame: {
+          reducer: (draft: Draft<TestGameState>, context) => {
+            draft.phase = "ended";
+            draft.winner = context.params?.winnerId as string;
+          },
+        },
+      };
+
+      expect(Object.keys(moves)).toEqual([
+        "incrementScore",
+        "nextPlayer",
+        "endGame",
+      ]);
+    });
+
+    it("should enforce state type in endIf function", () => {
+      const definition: GameDefinition<TestGameState, TestMoves> = {
+        name: "Test Game",
+        setup: () => ({
+          players: [],
+          currentPlayerIndex: 0,
+          phase: "setup",
+        }),
+        moves: {} as GameMoveDefinitions<TestGameState, TestMoves>,
+        endIf: (state: TestGameState) => {
+          // Should have access to all state fields
+          if (state.phase === "ended") {
+            return {
+              winner: state.winner || "none",
+              reason: "phase-ended",
+            };
+          }
+          return undefined;
+        },
+      };
+
+      const testState: TestGameState = {
+        players: [],
+        currentPlayerIndex: 0,
+        phase: "ended",
+        winner: "p1",
+      };
+
+      const result = definition.endIf?.(testState);
+      expect(result).toEqual({ winner: "p1", reason: "phase-ended" });
+    });
+
+    it("should enforce state type in playerView function", () => {
+      const definition: GameDefinition<TestGameState, TestMoves> = {
+        name: "Test Game",
+        setup: () => ({
+          players: [],
+          currentPlayerIndex: 0,
+          phase: "setup",
+        }),
+        moves: {} as GameMoveDefinitions<TestGameState, TestMoves>,
+        playerView: (state: TestGameState, playerId: string) => {
+          // Should have access to all state fields
+          return {
+            ...state,
+            players: state.players.map((p) => ({
+              ...p,
+              score: p.id === playerId ? p.score : 0,
+            })),
+          };
+        },
+      };
+
+      const testState: TestGameState = {
+        players: [
+          { id: "p1", name: "Alice", score: 10 },
+          { id: "p2", name: "Bob", score: 20 },
+        ],
+        currentPlayerIndex: 0,
+        phase: "playing",
+      };
+
+      const filteredState = definition.playerView?.(testState, "p1");
+      expect(filteredState?.players[0]?.score).toBe(10);
+      expect(filteredState?.players[1]?.score).toBe(0);
+    });
+  });
+
+  describe("setup function", () => {
+    it("should be deterministic (same players -> same state)", () => {
+      const definition: GameDefinition<TestGameState, TestMoves> = {
+        name: "Test Game",
+        setup: (players) => ({
+          players: players.map((p, i) => ({
+            id: p.id,
+            name: p.name || `Player ${i + 1}`,
+            score: 0,
+          })),
+          currentPlayerIndex: 0,
+          phase: "setup",
+        }),
+        moves: {} as GameMoveDefinitions<TestGameState, TestMoves>,
+      };
+
+      const players = [
+        { id: createPlayerId("p1"), name: "Alice" },
+        { id: createPlayerId("p2"), name: "Bob" },
+      ];
+
+      const state1 = definition.setup(players);
+      const state2 = definition.setup(players);
+
+      expect(state1).toEqual(state2);
+    });
+  });
+
+  // Note: minPlayers and maxPlayers are not part of GameDefinition spec
+  // Player count validation is handled at the application level, not in the core engine
+});