@drmxrcy/tcg-lorcana 0.0.0-202602060544

package/README.md

@@ -0,0 +1,160 @@
+# @drmxrcy/tcg-lorcana
+
+Disney Lorcana TCG engine built with `@drmxrcy/tcg-core` framework.
+
+## Overview
+
+This package implements the complete Disney Lorcana trading card game using the `@drmxrcy/tcg-core` framework. It serves as both a production-ready Lorcana engine and a reference implementation demonstrating best practices for building TCG engines.
+
+## Status
+
+🚧 **Work in Progress** - Package structure and configuration complete. Game logic implementation in progress.
+
+## Installation
+
+This is a workspace package. Install dependencies from the monorepo root:
+
+```bash
+bun install
+```
+
+## Development
+
+### Available Scripts
+
+```bash
+# Type checking
+bun run check-types
+
+# Formatting
+bun run format
+
+# Linting
+bun run lint
+
+# Testing
+bun run test
+bun run test:watch
+bun run test:coverage
+
+# Run all checks
+bun run check
+```
+
+### Project Structure
+
+```
+src/
+├── game-definition/     # Game definition and configuration
+├── moves/               # Move handlers
+├── cards/               # Card definitions and abilities
+├── types/               # TypeScript type definitions
+├── queries/             # State query functions
+├── rules/               # Rule implementations
+└── index.ts             # Main entry point
+```
+
+Each directory contains a README.md explaining its purpose and usage.
+
+## Architecture
+
+This package integrates with `@drmxrcy/tcg-core` by:
+
+1. **Defining game-specific state** - Extends base `GameState` with Lorcana data
+2. **Registering moves** - Implements move handlers for all player actions
+3. **Configuring zones** - Defines zones (Deck, Hand, Play, Discard, Inkwell)
+4. **Defining flow** - Specifies turn/phase/step structure
+5. **Implementing abilities** - Creates keyword, triggered, and activated abilities
+
+## Usage Example
+
+```typescript
+import { RuleEngine } from "@drmxrcy/tcg-core";
+import { lorcanaGame } from "@drmxrcy/tcg-lorcana";
+
+// Create engine instance
+const engine = new RuleEngine(lorcanaGame, {
+  seed: "game-seed-123",
+});
+
+// Setup game with player decks
+const initialState = engine.setup({
+  players: {
+    player1: { deckId: "deck-1" },
+    player2: { deckId: "deck-2" },
+  },
+});
+
+// Execute moves
+const result = engine.executeMove("playCard", {
+  playerId: "player1",
+  params: { cardId: "card-123" },
+});
+
+// Get current state
+const state = engine.getState();
+```
+
+## Dependencies
+
+- `@drmxrcy/tcg-core` - Core TCG engine framework
+- All dependencies from `@drmxrcy/tcg-core` (Immer, Zod, nanoid, seedrandom, etc.)
+
+## Boundaries
+
+This package uses Turborepo boundaries to enforce clean architecture:
+
+- ✅ Can depend on: `@drmxrcy/tcg-core`
+- ❌ Cannot depend on: Other game engines, UI packages, networking
+
+## Testing
+
+All game mechanics are tested through behavior-driven tests:
+
+```typescript
+describe("Quest Move", () => {
+  it("gains lore equal to card's lore value", () => {
+    const engine = createTestEngine();
+    // Test implementation
+  });
+  
+  it("exerts the character", () => {
+    // Test implementation
+  });
+  
+  it("rejects questing with exerted character", () => {
+    // Test implementation
+  });
+});
+```
+
+## Documentation
+
+- **Product Mission**: `.agent-os/packages/lorcana-engine/product/mission.md`
+- **Tech Stack**: `.agent-os/packages/lorcana-engine/product/tech-stack.md`
+- **Roadmap**: `.agent-os/packages/lorcana-engine/product/roadmap.md`
+- **Integration Guide**: `@packages/core/ENGINE_INTEGRATION.md`
+
+## Contributing
+
+This package follows strict coding standards:
+
+- TypeScript strict mode (no `any` types)
+- Test-driven development (TDD mandatory)
+- Behavior-driven testing (no mocking)
+- Immutable state (via Immer)
+- Pure functions preferred
+- Biome for formatting and linting
+
+See `@.agent-os/standards/` for detailed guidelines.
+
+## License
+
+MIT
+
+## References
+
+- [Disney Lorcana Official Site](https://www.disneylorcana.com/)
+- [Lorcana Official Rules](https://www.disneylorcana.com/rules)
+- `@drmxrcy/tcg-core` framework documentation
+

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@drmxrcy/tcg-lorcana",
+  "version": "0.0.0-202602060544",
+  "description": "Disney Lorcana TCG engine implementation using @drmxrcy/tcg-core framework",
+  "private": false,
+  "main": "./src/index.ts",
+  "types": "./src/index.d.ts",
+  "files": [
+    "src/"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./testing": {
+      "types": "./src/testing/index.ts",
+      "default": "./src/testing/index.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc --noEmit && mkdir -p dist",
+    "typecheck": "tsc --noEmit",
+    "check-types": "tsc --noEmit",
+    "format": "bun x @biomejs/biome check --fix --max-diagnostics=none --diagnostic-level=error --linter-enabled=false ./src",
+    "lint": "bun x @biomejs/biome lint --fix --max-diagnostics=none --diagnostic-level=error ./src",
+    "test": "AGENT=1 bun test --silent",
+    "test:watch": "bun test --watch",
+    "test:coverage": "bun test --coverage",
+    "check": "turbo format lint check-types test"
+  },
+  "dependencies": {
+    "@drmxrcy/tcg-core": "workspace:*",
+    "@drmxrcy/tcg-lorcana-types": "workspace:*",
+    "immer": "11.0.1"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.3.11",
+    "@types/bun": "1.3.4",
+    "typescript": "5.9.3"
+  },
+  "peerDependencies": {
+    "typescript": "5.9.3"
+  }
+}

package/src/__tests__/integration/move-enumeration.test.ts

@@ -0,0 +1,256 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import {
+  LorcanaTestEngine,
+  PLAYER_ONE,
+  PLAYER_TWO,
+} from "../../testing/lorcana-test-engine";
+
+describe("Move Enumeration Integration", () => {
+  describe("Phase Transition Integration", () => {
+    let testEngine: LorcanaTestEngine;
+
+    beforeEach(() => {
+      testEngine = new LorcanaTestEngine(
+        { hand: 7, deck: 10 },
+        { hand: 7, deck: 10 },
+        { skipPreGame: false },
+      );
+    });
+
+    afterEach(() => {
+      testEngine.dispose();
+    });
+
+    it.todo("should enumerate moves correctly across setup → mulligan → main phase", () => {
+      // Phase 1: Choose First Player
+      expect(testEngine.getGamePhase()).toBe("chooseFirstPlayer");
+
+      const choosingPlayer = testEngine.getCtx().choosingFirstPlayer;
+      let availableMoves = testEngine.getAvailableMoves(
+        choosingPlayer || PLAYER_ONE,
+      );
+
+      // Should have chooseWhoGoesFirstMove available
+      expect(availableMoves).toContain("chooseWhoGoesFirstMove");
+
+      // Execute choice
+      testEngine.changeActivePlayer(choosingPlayer || PLAYER_ONE);
+      testEngine.chooseWhoGoesFirst(PLAYER_ONE);
+
+      // Phase 2: Mulligan
+      expect(testEngine.getGamePhase()).toBe("mulligan");
+
+      // Both players should have alterHand available
+      availableMoves = testEngine.getAvailableMoves(PLAYER_ONE);
+      expect(availableMoves).toContain("alterHand");
+
+      availableMoves = testEngine.getAvailableMoves(PLAYER_TWO);
+      expect(availableMoves).toContain("alterHand");
+
+      // Execute mulligans
+      testEngine.changeActivePlayer(PLAYER_ONE);
+      testEngine.alterHand([]);
+
+      testEngine.changeActivePlayer(PLAYER_TWO);
+      testEngine.alterHand([]);
+
+      // Phase 3: Main Phase (or next phase in flow)
+      // After mulligan, game should transition to next phase
+      const finalPhase = testEngine.getGamePhase();
+      expect(finalPhase).not.toBe("mulligan");
+      expect(finalPhase).not.toBe("chooseFirstPlayer");
+    });
+
+    it("should show different available moves for different players", () => {
+      const choosingPlayer = testEngine.getCtx().choosingFirstPlayer;
+      const otherPlayer =
+        choosingPlayer === PLAYER_ONE ? PLAYER_TWO : PLAYER_ONE;
+
+      // Choosing player should see chooseWhoGoesFirstMove
+      const chooserMoves = testEngine.getAvailableMoves(
+        choosingPlayer || PLAYER_ONE,
+      );
+      expect(chooserMoves).toContain("chooseWhoGoesFirstMove");
+
+      // Other player should see no moves
+      const otherMoves = testEngine.getAvailableMoves(otherPlayer);
+      expect(otherMoves).toEqual([]);
+    });
+
+    it("should enumerate moves correctly after OTP transitions", () => {
+      const choosingPlayer = testEngine.getCtx().choosingFirstPlayer;
+
+      // Before choosing - only chooser has moves
+      const chooserMoves = testEngine.getAvailableMoves(
+        choosingPlayer || PLAYER_ONE,
+      );
+      expect(chooserMoves.length).toBeGreaterThan(0);
+
+      // Choose first player
+      testEngine.changeActivePlayer(choosingPlayer || PLAYER_ONE);
+      testEngine.chooseWhoGoesFirst(PLAYER_ONE);
+
+      // After choosing - OTP (player_one) should have mulligan move (has priority)
+      const p1Moves = testEngine.getAvailableMoves(PLAYER_ONE);
+      const p2Moves = testEngine.getAvailableMoves(PLAYER_TWO);
+
+      expect(p1Moves).toContain("alterHand");
+      // Player two doesn't have priority yet, so no alterHand
+      expect(p2Moves).not.toContain("alterHand");
+    });
+  });
+
+  describe("Multiple Players", () => {
+    let testEngine: LorcanaTestEngine;
+
+    beforeEach(() => {
+      testEngine = new LorcanaTestEngine(
+        { hand: 7, deck: 10 },
+        { hand: 7, deck: 10 },
+        { skipPreGame: false },
+      );
+    });
+
+    afterEach(() => {
+      testEngine.dispose();
+    });
+
+    it("should enumerate different moves for each player simultaneously", () => {
+      const choosingPlayer = testEngine.getCtx().choosingFirstPlayer;
+      const otherPlayer =
+        choosingPlayer === PLAYER_ONE ? PLAYER_TWO : PLAYER_ONE;
+
+      // Get moves for both players at the same time
+      const chooserMoves = testEngine.getAvailableMoves(
+        choosingPlayer || PLAYER_ONE,
+      );
+      const otherPlayerMoves = testEngine.getAvailableMoves(otherPlayer);
+
+      // Chooser has moves, other doesn't
+      expect(chooserMoves.length).toBeGreaterThan(0);
+      expect(otherPlayerMoves.length).toBe(0);
+
+      // Results should be independent
+      expect(chooserMoves).toContain("chooseWhoGoesFirstMove");
+      expect(otherPlayerMoves).not.toContain("chooseWhoGoesFirstMove");
+    });
+
+    it("should handle rapid enumeration calls without errors", () => {
+      const choosingPlayer = testEngine.getCtx().choosingFirstPlayer;
+
+      // Call enumeration multiple times rapidly
+      for (let i = 0; i < 10; i++) {
+        const moves = testEngine.getAvailableMoves(
+          choosingPlayer || PLAYER_ONE,
+        );
+        expect(moves).toContain("chooseWhoGoesFirstMove");
+      }
+
+      // State should remain consistent
+      expect(testEngine.getGamePhase()).toBe("chooseFirstPlayer");
+    });
+  });
+
+  describe("Edge Cases", () => {
+    let testEngine: LorcanaTestEngine;
+
+    beforeEach(() => {
+      testEngine = new LorcanaTestEngine(
+        { hand: 7, deck: 10 },
+        { hand: 7, deck: 10 },
+        { skipPreGame: false },
+      );
+    });
+
+    afterEach(() => {
+      testEngine.dispose();
+    });
+
+    it("should handle enumeration for player with no available moves", () => {
+      const choosingPlayer = testEngine.getCtx().choosingFirstPlayer;
+      const otherPlayer =
+        choosingPlayer === PLAYER_ONE ? PLAYER_TWO : PLAYER_ONE;
+
+      // Other player has no moves during chooseFirstPlayer phase
+      const moves = testEngine.getAvailableMoves(otherPlayer);
+
+      expect(moves).toEqual([]);
+      expect(Array.isArray(moves)).toBe(true);
+    });
+
+    it("should handle enumeration after move is no longer available", () => {
+      const choosingPlayer = testEngine.getCtx().choosingFirstPlayer;
+
+      // Before executing move
+      let moves = testEngine.getAvailableMoves(choosingPlayer || PLAYER_ONE);
+      expect(moves).toContain("chooseWhoGoesFirstMove");
+
+      // Execute move
+      testEngine.changeActivePlayer(choosingPlayer || PLAYER_ONE);
+      testEngine.chooseWhoGoesFirst(PLAYER_ONE);
+
+      // After executing move - should no longer be available
+      moves = testEngine.getAvailableMoves(choosingPlayer || PLAYER_ONE);
+      expect(moves).not.toContain("chooseWhoGoesFirstMove");
+    });
+
+    it("should return consistent results for same state", () => {
+      const choosingPlayer = testEngine.getCtx().choosingFirstPlayer;
+
+      // Call multiple times without changing state
+      const moves1 = testEngine.getAvailableMoves(choosingPlayer || PLAYER_ONE);
+      const moves2 = testEngine.getAvailableMoves(choosingPlayer || PLAYER_ONE);
+      const moves3 = testEngine.getAvailableMoves(choosingPlayer || PLAYER_ONE);
+
+      // All results should be identical
+      expect(moves1).toEqual(moves2);
+      expect(moves2).toEqual(moves3);
+    });
+
+    it("should handle invalid player ID gracefully", () => {
+      // Try to get moves for a non-existent player
+      const moves = testEngine.getAvailableMoves("invalid_player_id");
+
+      // Should return empty array (no moves available)
+      expect(Array.isArray(moves)).toBe(true);
+      expect(moves).toEqual([]);
+    });
+  });
+
+  describe("Performance", () => {
+    let testEngine: LorcanaTestEngine;
+
+    beforeEach(() => {
+      testEngine = new LorcanaTestEngine(
+        { hand: 7, deck: 10 },
+        { hand: 7, deck: 10 },
+        { skipPreGame: false },
+      );
+    });
+
+    afterEach(() => {
+      testEngine.dispose();
+    });
+
+    it("should enumerate moves quickly (<100ms for typical state)", () => {
+      const choosingPlayer = testEngine.getCtx().choosingFirstPlayer;
+
+      const startTime = performance.now();
+
+      // Enumerate moves 100 times
+      for (let i = 0; i < 100; i++) {
+        testEngine.getAvailableMoves(choosingPlayer || PLAYER_ONE);
+      }
+
+      const endTime = performance.now();
+      const totalTime = endTime - startTime;
+      const avgTime = totalTime / 100;
+
+      // Average time per enumeration should be under 500ms (higher threshold for CI parallel execution)
+      expect(avgTime).toBeLessThan(500);
+
+      // Log for visibility (not an assertion)
+      console.log(`Average enumeration time: ${avgTime.toFixed(2)}ms`);
+    });
+  });
+});