@drmxrcy/tcg-core 0.0.0-202602060542

package/src/moves/create-move.test.ts

@@ -0,0 +1,331 @@
+import { describe, expect, it } from "bun:test";
+import { produce } from "immer";
+import { createMockContext } from "../testing/test-context-factory";
+import type { CardId, PlayerId } from "../types";
+import { createCardId, createPlayerId } from "../types";
+import { createMove } from "./create-move";
+import type { MoveContext } from "./move-system";
+
+describe("createMove Helper", () => {
+  /**
+   * Test game state structure
+   */
+  type TestGameState = {
+    players: Record<PlayerId, { health: number; mana: number }>;
+    cards: Record<CardId, { name: string; damage: number }>;
+  };
+
+  /**
+   * Test move parameter types - using a record type like real game implementations
+   */
+  type TestMoveParams = {
+    // Move with specific params
+    quest: { cardId: CardId };
+    // Move with multiple params
+    challenge: { attackerId: CardId; defenderId: CardId };
+    // Move with optional params
+    playCard: { cardId: CardId; alternativeCost?: number };
+    // Move with no params
+    pass: Record<string, never>;
+  };
+
+  const player1 = createPlayerId("p1");
+  const player2 = createPlayerId("p2");
+  const card1 = createCardId("card1");
+  const card2 = createCardId("card2");
+
+  const initialState: TestGameState = {
+    players: {
+      [player1]: { health: 20, mana: 5 },
+      [player2]: { health: 20, mana: 5 },
+    },
+    cards: {
+      [card1]: { name: "Character A", damage: 0 },
+      [card2]: { name: "Character B", damage: 0 },
+    },
+  };
+
+  describe("Type Narrowing", () => {
+    it("should narrow params for single-param move", () => {
+      // Create a move with narrowed params using createMove
+      const questMove = createMove<
+        TestGameState,
+        TestMoveParams,
+        "quest" // ✅ Narrows to TestMoveParams["quest"]
+      >({
+        condition: (state, context) => {
+          // ✅ context.params is { cardId: CardId }
+          const { cardId } = context.params;
+          return !!state.cards[cardId];
+        },
+        reducer: (draft, context) => {
+          // ✅ context.params is { cardId: CardId }
+          const { cardId } = context.params;
+          const card = draft.cards[cardId];
+          if (card) {
+            card.damage += 1;
+          }
+        },
+      });
+
+      // Verify the move works correctly
+      const context: MoveContext<TestMoveParams["quest"]> = createMockContext({
+        playerId: player1,
+        params: { cardId: card1 },
+      });
+
+      // Test condition
+      expect(questMove.condition?.(initialState, context)).toBe(true);
+
+      // Test reducer
+      const nextState = produce(initialState, (draft) => {
+        questMove.reducer(draft, context);
+      });
+
+      expect(nextState.cards[card1].damage).toBe(1);
+    });
+
+    it("should narrow params for multi-param move", () => {
+      // Create a move with multiple params
+      const challengeMove = createMove<
+        TestGameState,
+        TestMoveParams,
+        "challenge" // ✅ Narrows to TestMoveParams["challenge"]
+      >({
+        condition: (state, context) => {
+          // ✅ context.params is { attackerId: CardId; defenderId: CardId }
+          const { attackerId, defenderId } = context.params;
+          return !!state.cards[attackerId] && !!state.cards[defenderId];
+        },
+        reducer: (draft, context) => {
+          // ✅ context.params is { attackerId: CardId; defenderId: CardId }
+          const { attackerId, defenderId } = context.params;
+          const attacker = draft.cards[attackerId];
+          const defender = draft.cards[defenderId];
+          if (attacker && defender) {
+            defender.damage += 3;
+          }
+        },
+      });
+
+      const context: MoveContext<TestMoveParams["challenge"]> =
+        createMockContext({
+          playerId: player1,
+          params: { attackerId: card1, defenderId: card2 },
+        });
+
+      expect(challengeMove.condition?.(initialState, context)).toBe(true);
+
+      const nextState = produce(initialState, (draft) => {
+        challengeMove.reducer(draft, context);
+      });
+
+      expect(nextState.cards[card2].damage).toBe(3);
+    });
+
+    it("should narrow params for move with optional fields", () => {
+      // Create a move with optional params
+      const playCardMove = createMove<
+        TestGameState,
+        TestMoveParams,
+        "playCard" // ✅ Narrows to TestMoveParams["playCard"]
+      >({
+        reducer: (draft, context) => {
+          // ✅ context.params is { cardId: CardId; alternativeCost?: number }
+          const { cardId, alternativeCost } = context.params;
+          const player = draft.players[context.playerId];
+          const cost = alternativeCost ?? 3;
+          player.mana -= cost;
+
+          // Use cardId (verify it's available)
+          const card = draft.cards[cardId];
+          if (card) {
+            card.damage = 0; // Reset damage on play
+          }
+        },
+      });
+
+      // Test with alternativeCost
+      const contextWithAlt: MoveContext<TestMoveParams["playCard"]> =
+        createMockContext({
+          playerId: player1,
+          params: { cardId: card1, alternativeCost: 2 },
+        });
+
+      const nextState1 = produce(initialState, (draft) => {
+        playCardMove.reducer(draft, contextWithAlt);
+      });
+
+      expect(nextState1.players[player1].mana).toBe(3); // 5 - 2
+
+      // Test without alternativeCost
+      const contextWithoutAlt: MoveContext<TestMoveParams["playCard"]> =
+        createMockContext({
+          playerId: player1,
+          params: { cardId: card1 }, // alternativeCost is optional
+        });
+
+      const nextState2 = produce(initialState, (draft) => {
+        playCardMove.reducer(draft, contextWithoutAlt);
+      });
+
+      expect(nextState2.players[player1].mana).toBe(2); // 5 - 3 (default)
+    });
+
+    it("should narrow params for no-param move", () => {
+      // Create a move with no params
+      const passMove = createMove<
+        TestGameState,
+        TestMoveParams,
+        "pass" // ✅ Narrows to TestMoveParams["pass"] (empty object)
+      >({
+        reducer: (draft, context) => {
+          // ✅ context.params is {} (empty object)
+          const player = draft.players[context.playerId];
+          player.mana = 10; // Reset mana on pass
+        },
+      });
+
+      const context: MoveContext<TestMoveParams["pass"]> = createMockContext({
+        playerId: player1,
+        params: {},
+      });
+
+      const nextState = produce(initialState, (draft) => {
+        passMove.reducer(draft, context);
+      });
+
+      expect(nextState.players[player1].mana).toBe(10);
+    });
+  });
+
+  describe("Runtime Behavior", () => {
+    it("should return the definition unchanged", () => {
+      const definition = {
+        condition: (state: TestGameState) => state.players[player1].mana >= 1,
+        reducer: (draft: any) => {
+          draft.players[player1].mana -= 1;
+        },
+      };
+
+      const result = createMove<TestGameState, TestMoveParams, "quest">(
+        definition,
+      );
+
+      // Runtime behavior: returns the same object
+      expect(result).toBe(definition);
+      expect(result.condition).toBe(definition.condition);
+      expect(result.reducer).toBe(definition.reducer);
+    });
+
+    it("should work with move definitions without conditions", () => {
+      const definition = {
+        reducer: (draft: any) => {
+          draft.players[player1].health -= 1;
+        },
+      };
+
+      const result = createMove<TestGameState, TestMoveParams, "pass">(
+        definition,
+      );
+
+      expect(result).toBe(definition);
+      expect(result.condition).toBeUndefined();
+    });
+
+    it("should work with move definitions with metadata", () => {
+      const definition = {
+        reducer: (draft: any) => {
+          draft.players[player1].health += 5;
+        },
+        metadata: {
+          category: "healing",
+          tags: ["buff"],
+        },
+      };
+
+      const result = createMove<TestGameState, TestMoveParams, "pass">(
+        definition,
+      );
+
+      expect(result.metadata?.category).toBe("healing");
+      expect(result.metadata?.tags).toEqual(["buff"]);
+    });
+  });
+
+  describe("Integration with GameMoveDefinitions", () => {
+    it("should work correctly when aggregated into move map", () => {
+      // Create individual moves using createMove
+      const quest = createMove<TestGameState, TestMoveParams, "quest">({
+        reducer: (draft, context) => {
+          const { cardId } = context.params;
+          draft.cards[cardId].damage += 1;
+        },
+      });
+
+      const challenge = createMove<TestGameState, TestMoveParams, "challenge">({
+        reducer: (draft, context) => {
+          const { attackerId, defenderId } = context.params;
+          draft.cards[defenderId].damage += 2;
+        },
+      });
+
+      const pass = createMove<TestGameState, TestMoveParams, "pass">({
+        reducer: (draft, context) => {
+          draft.players[context.playerId].mana = 10;
+        },
+      });
+
+      // Aggregate into a move map (simulating GameMoveDefinitions)
+      const moves = {
+        quest,
+        challenge,
+        pass,
+      };
+
+      // Verify all moves are accessible and work correctly
+      expect(moves.quest).toBe(quest);
+      expect(moves.challenge).toBe(challenge);
+      expect(moves.pass).toBe(pass);
+
+      // Test executing quest move
+      const questContext: MoveContext<TestMoveParams["quest"]> =
+        createMockContext({
+          playerId: player1,
+          params: { cardId: card1 },
+        });
+
+      const state1 = produce(initialState, (draft) => {
+        moves.quest.reducer(draft, questContext);
+      });
+
+      expect(state1.cards[card1].damage).toBe(1);
+
+      // Test executing challenge move
+      const challengeContext: MoveContext<TestMoveParams["challenge"]> =
+        createMockContext({
+          playerId: player1,
+          params: { attackerId: card1, defenderId: card2 },
+        });
+
+      const state2 = produce(state1, (draft) => {
+        moves.challenge.reducer(draft, challengeContext);
+      });
+
+      expect(state2.cards[card2].damage).toBe(2);
+
+      // Test executing pass move
+      const passContext: MoveContext<TestMoveParams["pass"]> =
+        createMockContext({
+          playerId: player1,
+          params: {},
+        });
+
+      const state3 = produce(state2, (draft) => {
+        moves.pass.reducer(draft, passContext);
+      });
+
+      expect(state3.players[player1].mana).toBe(10);
+    });
+  });
+});

package/src/moves/create-move.ts

@@ -0,0 +1,64 @@
+import type { GameMoveDefinition } from "../game-definition/move-definitions";
+
+/**
+ * Create a type-safe move definition with proper parameter narrowing
+ *
+ * This helper ensures that move parameters are correctly narrowed to the specific
+ * move's parameter type, avoiding TypeScript's limitations with module boundary
+ * type inference.
+ *
+ * @template TState - Game state type
+ * @template TMoves - Record of move names to parameter types
+ * @template K - Specific move name (keyof TMoves)
+ * @template TCardMeta - Card metadata type
+ * @template TCardDefinition - Card definition type
+ *
+ * @param definition - The move definition (reducer, condition, metadata)
+ * @returns The same move definition with proper type narrowing
+ *
+ * @example
+ * ```typescript
+ * type GameMoves = {
+ *   quest: { cardId: string };
+ *   playCard: { cardId: string; cost: number };
+ * };
+ *
+ * export const quest = createMove<GameState, GameMoves, "quest", CardMeta>({
+ *   condition: (state, context) => {
+ *     const { cardId } = context.params; // ✅ Typed as { cardId: string }
+ *     return true;
+ *   },
+ *   reducer: (draft, context) => {
+ *     const { cardId } = context.params; // ✅ Typed as { cardId: string }
+ *     // Implementation...
+ *   }
+ * });
+ * ```
+ *
+ * **Why this is needed**:
+ * Without this helper, when you export a move with an explicit type annotation:
+ * ```typescript
+ * export const quest: MoveDefinition<GameState, GameMoves, CardMeta> = {...}
+ * ```
+ * TypeScript sees `context.params` as the full `GameMoves` type union, not just
+ * the narrowed `GameMoves["quest"]` type.
+ *
+ * This helper uses TypeScript's generic inference to properly narrow the type
+ * at the definition site, avoiding module boundary issues.
+ */
+export function createMove<
+  TState,
+  TMoves extends Record<string, any>,
+  K extends keyof TMoves,
+  TCardMeta = any,
+  TCardDefinition = any,
+>(
+  definition: GameMoveDefinition<
+    TState,
+    TMoves[K], // ✅ Narrow to specific move's params
+    TCardMeta,
+    TCardDefinition
+  >,
+): GameMoveDefinition<TState, TMoves[K], TCardMeta, TCardDefinition> {
+  return definition;
+}

package/src/moves/move-enumeration.ts

@@ -0,0 +1,228 @@
+/**
+ * Move Enumeration System
+ *
+ * Provides types and interfaces for enumerating all possible moves
+ * with their valid parameters. This enables AI agents and UI components
+ * to discover available actions at any game state.
+ *
+ * @packageDocumentation
+ */
+
+import type { CardOperations } from "../operations/card-operations";
+import type { CardRegistry } from "../operations/card-registry";
+import type { CounterOperations } from "../operations/counter-operations";
+import type { GameOperations } from "../operations/game-operations";
+import type { ZoneOperations } from "../operations/zone-operations";
+import type { SeededRNG } from "../rng/seeded-rng";
+import type { CardId, PlayerId } from "../types";
+
+/**
+ * Enumerated Move Result
+ *
+ * Represents a single valid move with all its parameter values.
+ * Returned by RuleEngine.enumerateMoves() for each possible move + parameter combination.
+ *
+ * @template TParams - Move-specific parameter type
+ *
+ * @example
+ * ```typescript
+ * const moves = engine.enumerateMoves(playerId, { validOnly: true });
+ * for (const move of moves) {
+ *   console.log(`${move.moveId}:`, move.params);
+ *   if (move.isValid) {
+ *     // Execute the move
+ *     engine.executeMove(move.moveId, {
+ *       playerId: move.playerId,
+ *       params: move.params
+ *     });
+ *   }
+ * }
+ * ```
+ */
+export type EnumeratedMove<TParams = unknown> = {
+  /** Move identifier */
+  moveId: string;
+
+  /** Player who can execute this move */
+  playerId: PlayerId;
+
+  /** Fully populated parameters for this move */
+  params: TParams;
+
+  /** Optional source card for this move */
+  sourceCardId?: CardId;
+
+  /** Optional targets for this move */
+  targets?: string[][];
+
+  /** Whether this move is currently valid (passed condition check) */
+  isValid: boolean;
+
+  /** If not valid, reason for failure */
+  validationError?: {
+    reason: string;
+    errorCode: string;
+    context?: Record<string, unknown>;
+  };
+
+  /** Optional metadata for UI/AI consumption */
+  metadata?: {
+    displayName?: string;
+    description?: string;
+    category?: string;
+    priority?: number;
+    [key: string]: unknown;
+  };
+};
+
+/**
+ * Enumeration Context
+ *
+ * Provided to enumerator functions, contains all information needed
+ * to discover valid parameters. Similar to MoveContext but focused on
+ * read-only operations for parameter discovery.
+ *
+ * @template TCardMeta - Card metadata type
+ * @template TCardDefinition - Card definition type
+ *
+ * @example
+ * ```typescript
+ * const enumerator: MoveEnumerator<GameState, PlayCardParams> = (state, context) => {
+ *   // Get all cards in player's hand
+ *   const handCards = context.zones.getCardsInZone('hand', context.playerId);
+ *
+ *   // Generate parameter combination for each card
+ *   return handCards.map(cardId => ({ cardId }));
+ * };
+ * ```
+ */
+export type MoveEnumerationContext<
+  TCardMeta = unknown,
+  TCardDefinition = unknown,
+> = {
+  /** Player to enumerate moves for */
+  playerId: PlayerId;
+
+  /** Zone operations for querying card locations */
+  zones: ZoneOperations;
+
+  /** Card operations for querying card state */
+  cards: CardOperations<TCardMeta>;
+
+  /** Game operations for game-level state */
+  game: GameOperations;
+
+  /** Counter operations for querying card counters/flags */
+  counters: CounterOperations;
+
+  /** Card registry for static card definitions */
+  registry?: CardRegistry<TCardDefinition>;
+
+  /** Flow state (turn, phase, segment) */
+  flow?: {
+    currentPhase?: string;
+    currentSegment?: string;
+    turn: number;
+    currentPlayer?: PlayerId;
+    isFirstTurn: boolean;
+  };
+
+  /** RNG for deterministic enumeration if needed */
+  rng: SeededRNG;
+};
+
+/**
+ * Move Enumerator Function
+ *
+ * Game-provided function that generates all possible parameter combinations
+ * for a given move. Returns an array of parameter objects.
+ *
+ * Each parameter object returned will be validated against the move's condition
+ * and included in the enumeration results.
+ *
+ * @template TGameState - Game state type
+ * @template TParams - Move-specific parameter type
+ * @template TCardMeta - Card metadata type
+ * @template TCardDefinition - Card definition type
+ *
+ * @param state - Current game state (readonly)
+ * @param context - Enumeration context with player, operations, etc.
+ * @returns Array of possible parameter combinations
+ *
+ * @example
+ * ```typescript
+ * // Simple card play enumerator
+ * const playCardEnumerator: MoveEnumerator<GameState, PlayCardParams> = (state, context) => {
+ *   const handCards = context.zones.getCardsInZone('hand', context.playerId);
+ *   return handCards.map(cardId => ({ cardId }));
+ * };
+ *
+ * // Attack enumerator with multiple targets
+ * const attackEnumerator: MoveEnumerator<GameState, AttackParams> = (state, context) => {
+ *   const results: AttackParams[] = [];
+ *   const attackers = context.zones.getCardsInZone('field', context.playerId);
+ *
+ *   for (const attackerId of attackers) {
+ *     const targets = getValidTargets(state, attackerId);
+ *     for (const targetId of targets) {
+ *       results.push({ attackerId, targetId });
+ *     }
+ *   }
+ *
+ *   return results;
+ * };
+ * ```
+ */
+export type MoveEnumerator<
+  TGameState,
+  TParams = unknown,
+  TCardMeta = unknown,
+  TCardDefinition = unknown,
+> = (
+  state: TGameState,
+  context: MoveEnumerationContext<TCardMeta, TCardDefinition>,
+) => TParams[];
+
+/**
+ * Move Enumeration Options
+ *
+ * Configuration for enumeration behavior.
+ *
+ * @example
+ * ```typescript
+ * // Get only valid moves
+ * const validMoves = engine.enumerateMoves(playerId, {
+ *   validOnly: true
+ * });
+ *
+ * // Get all moves with metadata
+ * const allMoves = engine.enumerateMoves(playerId, {
+ *   validOnly: false,
+ *   includeMetadata: true
+ * });
+ *
+ * // Enumerate specific moves only
+ * const attackMoves = engine.enumerateMoves(playerId, {
+ *   moveIds: ['attack', 'special-attack'],
+ *   validOnly: true
+ * });
+ *
+ * // Limit results per move
+ * const limitedMoves = engine.enumerateMoves(playerId, {
+ *   maxPerMove: 10  // Max 10 parameter combinations per move
+ * });
+ * ```
+ */
+export type MoveEnumerationOptions = {
+  /** Only return valid moves (passed condition check). Default: false */
+  validOnly?: boolean;
+
+  /** Include metadata in results. Default: false */
+  includeMetadata?: boolean;
+
+  /** Filter to specific move IDs. Default: all moves */
+  moveIds?: string[];
+
+  /** Maximum number of results per move (optional limit) */
+  maxPerMove?: number;
+};