### Troubleshooting Package Installation Issues

Source: https://github.com/thecardgoat/tcg-engines/blob/main/agents.md

Guidance for resolving package installation problems, emphasizing the use of `bun install`, clearing the cache, and checking the `packageManager` field in `package.json`.

```bash
bun pm cache rm
```

--------------------------------

### Install Dependencies and Run Development Server (Bash)

Source: https://github.com/thecardgoat/tcg-engines/blob/main/apps/content-mgmt/README.md

This snippet outlines the steps to set up and run the development environment for the Content Management Service. It includes installing dependencies, configuring environment variables, setting up the database, and starting the development server.

```bash
bun install

cp .env.example .env

docker-compose up -d postgres-content

bun run db:push

bun run dev
```

--------------------------------

### Install Project Dependencies with Bun

Source: https://github.com/thecardgoat/tcg-engines/blob/main/agents.md

Installs all project dependencies using Bun, the primary package manager for this project. This command should be run from the project's root directory.

```bash
bun install
```

--------------------------------

### Verification Commands

Source: https://github.com/thecardgoat/tcg-engines/blob/main/agents.md

A set of commands to verify the correct installation and versions of Node.js, npm, Bun, and fnm, as well as to install dependencies and run a check-types command.

```bash
node -v
npm -v
bun -v
fnm --version
bun install
bun run check-types
```

--------------------------------

### Quick Start: Card Management Tooling with TypeScript

Source: https://github.com/thecardgoat/tcg-engines/blob/main/packages/core/docs/guides/card-tooling.md

Demonstrates a quick start for building card management tools using @tcg/core/tooling. It shows defining card types, creating parsers and generators, and using a FileWriter to save formatted TypeScript code.

```typescript
import {
  CardParser,
  CardGenerator,
  FileWriter,
  formatTypeScript,
  generateVariableName,
} from '@tcg/core/tooling';

// 1. Define your card type
type MyCard = {
  name: string;
  type: 'creature' | 'spell';
  cost: number;
  text: string;
};

// 2. Create a parser
class MyCardParser extends CardParser<string, MyCard> {
  protected doParse(text: string): ParserResult<MyCard> {
    // Parse logic here
    return { success: true, data: card, warnings: [] };
  }
}

// 3. Create a generator
class MyCardGenerator extends CardGenerator<MyCard> {
  protected generateContent(card: MyCard): string {
    return `export const ${generateVariableName(card.name)} = ${JSON.stringify(card, null, 2)};`;
  }

  protected generateFileName(card: MyCard): string {
    return `${card.name.toLowerCase()}.ts`;
  }
}

// 4. Use them together
const parser = new MyCardParser();
const generator = new MyCardGenerator();
const writer = new FileWriter('./cards');

const result = parser.parse('Fireball|spell|3|Deal 3 damage');
if (result.success) {
  const code = generator.generate(result.data);
  const formatted = await formatTypeScript(code);
  await writer.write(generator.generateFileName(result.data), formatted);
}
```

--------------------------------

### Install and Use Node.js 24 with fnm

Source: https://github.com/thecardgoat/tcg-engines/blob/main/agents.md

Installs Node.js version 24 using fnm and sets it as the active version. Includes verification commands for Node.js and npm.

```bash
fnm install 24
fnm use 24
node -v
npm -v
```

--------------------------------

### Common Project Commands

Source: https://github.com/thecardgoat/tcg-engines/blob/main/agents.md

A list of frequently used commands for the TCG Engines project, covering dependency installation, type checking, testing, linting, formatting, CI checks, and building.

```bash
bun install
bun run check-types
bun test
bun run lint
bun run format
bun run ci-check
bun run build
```

--------------------------------

### Install Bun Package Manager

Source: https://github.com/thecardgoat/tcg-engines/blob/main/agents.md

Installs the Bun JavaScript runtime and package manager. After installation, restart the terminal or source the shell configuration.

```bash
curl -fsSL https://bun.sh/install | bash
```

--------------------------------

### Automated Setup Script

Source: https://github.com/thecardgoat/tcg-engines/blob/main/agents.md

Executes the automated setup script for the TCG Engines project. This is the quickest way to configure the development environment.

```bash
chmod +x setup.sh
./setup.sh
```

--------------------------------

### Start Svelte development server

Source: https://github.com/thecardgoat/tcg-engines/blob/main/apps/operating-system/README.md

These commands start the development server for a Svelte project after dependencies have been installed. The `--open` flag automatically opens the application in a new browser tab.

```shell
npm run dev

# or start the server and open the app in a new browser tab
npm run dev -- --open
```

--------------------------------

### Client Setup for MultiplayerEngine in TypeScript

Source: https://github.com/thecardgoat/tcg-engines/blob/main/packages/core/src/engine/MULTIPLAYER.md

Sets up the MultiplayerEngine in client mode. It applies patches received from the server to maintain synchronized state and provides methods to get the current state, player-specific views, and check valid moves.

```typescript
import { MultiplayerEngine } from "@tcg/core";

const client = new MultiplayerEngine(gameDefinition, players, {
  mode: "client",

  // Callback when patches are applied
  onPatchesApplied: (patches) => {
    console.log(`Applied ${patches.length} patches from server`);
    updateUI(); // Refresh your game UI
  },
});

// Receive and apply patches from server
websocket.on("message", (data) => {
  if (data.type === "PATCH_UPDATE") {
    client.applyServerPatches(data.patches);
  }
});

// Get current state
const state = client.getState();

// Get player-specific view (hides private information)
const playerView = client.getPlayerView(playerId);

// Check valid moves for UI (enable/disable buttons)
const validMoves = client.getValidMoves(playerId);
const canDraw = client.canExecuteMove("drawCard", { playerId });

```

--------------------------------

### AI Agent Package Management Commands

Source: https://github.com/thecardgoat/tcg-engines/blob/main/agents.md

Demonstrates the correct Bun commands for package management, emphasizing their use over npm equivalents for AI agents working with this project.

```bash
bun install
bun add <package>
bun remove <package>
```

--------------------------------

### Troubleshooting fnm Not Found

Source: https://github.com/thecardgoat/tcg-engines/blob/main/agents.md

Provides steps to resolve the 'fnm not found' issue after installation, including restarting the terminal, sourcing shell configuration, and checking the PATH.

```bash
source ~/.bashrc  # or source ~/.zshrc
echo $PATH | grep fnm
```

--------------------------------

### Troubleshooting Bun Not Found

Source: https://github.com/thecardgoat/tcg-engines/blob/main/agents.md

Instructions to resolve 'bun not found' errors, such as restarting the terminal, manually adding Bun to the PATH, and verifying the installation.

```bash
export PATH="$HOME/.bun/bin:$PATH"
which bun
```

--------------------------------

### Configure Game Definition with Setup, Moves, and End Conditions

Source: https://github.com/thecardgoat/tcg-engines/blob/main/packages/template-engine/README.md

This TypeScript example demonstrates how to configure the overall game definition, including the initial setup, the defined moves, win/loss conditions, and player-specific views. This is essential for setting up your custom game.

```typescript
export const yourGameDefinition: GameDefinition<YourGameState, YourGameMoves> = {
  name: "Your Game Name",

  setup: (players) => ({
    // Initialize game state
  }),

  moves,

  endIf: (state) => {
    // Check win conditions
    if (someCondition) {
      return { winner: winnerId, reason: "Victory condition met" };
    }
    return undefined;
  },

  playerView: (state, playerId) => ({
    // Filter state for each player
    // Hide opponent secrets
  }),
};
```

--------------------------------

### Illustrate Card Definition vs. Instance in TypeScript

Source: https://github.com/thecardgoat/tcg-engines/blob/main/packages/core/docs/ENGINE_INTEGRATION.md

Provides examples of a static `CardDefinition` and a runtime `CardInstance` in TypeScript. The definition outlines what a card is, while the instance represents its current state in the game.

```typescript
// Definition (in code)
const definition: CardDefinition = {
  id: "card-001",
  name: "Example",
  power: 3,
};

// Instance (in game state)
const instance: CardInstance = {
  definitionId: "card-001",
  instanceId: "game-123-card-456",
  ownerId: "player1",
  zone: "play",
  
  // Current state
  damage: 1,
  tapped: true,
};
```

--------------------------------

### Troubleshooting Node.js Version Issues

Source: https://github.com/thecardgoat/tcg-engines/blob/main/agents.md

Steps to fix incorrect Node.js versions, including ensuring fnm is configured, manually switching versions, and checking the `.node-version` file.

```bash
fnm use 24
```

--------------------------------

### Server Setup for MultiplayerEngine in TypeScript

Source: https://github.com/thecardgoat/tcg-engines/blob/main/packages/core/src/engine/MULTIPLAYER.md

Sets up the MultiplayerEngine in server mode. It executes moves authoritatively, generates Immer patches, and broadcasts them to clients via a callback. It also handles rejected moves.

```typescript
import { MultiplayerEngine } from "@tcg/core";

const server = new MultiplayerEngine(gameDefinition, players, {
  mode: "server",
  seed: "game-123-seed",

  // Callback when moves generate patches
  onPatchBroadcast: (broadcast) => {
    // Send patches to all connected clients via your network layer
    websocket.broadcast({
      type: "PATCH_UPDATE",
      patches: broadcast.patches,
      historyIndex: broadcast.historyIndex,
    });
  },

  // Callback when moves are rejected
  onMoveRejected: (moveId, error, errorCode) => {
    console.error(`Move ${moveId} rejected: ${error}`);
  },
});

// Execute moves (server only)
const result = server.executeMove("playCard", {
  playerId: createPlayerId("p1"),
  data: { cardId: "card-123" },
});

// Patches are automatically broadcast via onPatchBroadcast callback

```

--------------------------------

### Install Dependencies and Run Checks with Bun

Source: https://github.com/thecardgoat/tcg-engines/blob/main/README.md

This snippet shows how to install project dependencies and run a CI check using the Bun package manager. It's a crucial first step for setting up the development environment.

```bash
bun install
bun run ci-check  # Ensure everything passes
```

--------------------------------

### Install fnm (Fast Node Manager)

Source: https://github.com/thecardgoat/tcg-engines/blob/main/agents.md

Installs fnm, a tool for managing Node.js versions. After installation, it's recommended to restart the terminal or source the shell configuration.

```bash
curl -o- https://fnm.vercel.app/install | bash
source ~/.bashrc  # or source ~/.zshrc
```

--------------------------------

### Quick Start: Testing Game Engine Moves and State

Source: https://github.com/thecardgoat/tcg-engines/blob/main/packages/core/docs/guides/testing-utilities.md

Demonstrates the basic TDD workflow: setting up a test engine, executing a move, and asserting state changes. It also shows how to use deterministic RNG for reproducible tests.

```typescript
import {
  expectMoveSuccess,
  expectStateProperty,
  createTestCard,
  createTestDeck,
  withSeed,
} from '@tcg/core/testing';
import { RuleEngine } from '@tcg/core';

// 1. Create test game setup
const gameDefinition = { /* your game */ };
const engine = new RuleEngine(gameDefinition, players, { seed: 'test' });

// 2. Execute and test moves
expectMoveSuccess(engine, 'playCard', {
  playerId: 'p1',
  data: { cardId: 'card-123' }
});

// 3. Verify state changes
expectStateProperty(engine, 'players[0].hand.length', 6);
expectStateProperty(engine, 'field.length', 1);

// 4. Test with deterministic RNG
const shuffled = withSeed('test-seed', (rng) => {
  return rng.shuffle([1, 2, 3, 4, 5]);
});
```

--------------------------------

### AI Agent Script Execution with Bun

Source: https://github.com/thecardgoat/tcg-engines/blob/main/agents.md

Shows how AI agents should execute scripts and packages using Bun, including running scripts from package.json and using `bunx` for package execution.

```bash
bun run <script>
bunx turbo run build
```

--------------------------------

### Basic Game Logging Setup (TypeScript)

Source: https://github.com/thecardgoat/tcg-engines/blob/main/packages/core/docs/LOGGING.md

An example of initializing the `RuleEngine` with basic logging enabled for 'NORMAL_PLAYER' level and pretty printing. It shows how the engine automatically logs game events like move execution and phase transitions.

```typescript
const engine = new RuleEngine(gameDefinition, players, {
  seed: 'game-123',
  logger: {
    level: 'NORMAL_PLAYER',
    pretty: true
  }
});

// Game automatically logs:
// - Move execution
// - Phase/turn transitions
// - Errors

engine.executeMove('playCard', {
  playerId: 'player-1',
  params: { cardId: 'card-42' }
});
```

--------------------------------

### TCG Engine Initialization and Core Operations

Source: https://github.com/thecardgoat/tcg-engines/blob/main/agent-os/product/philosophy.md

Illustrates the basic setup and usage of the TCG engine framework. It shows how to initialize the engine with a game definition and players, and highlights the core operations handled by the framework, such as move validation and state updates.

```typescript
// ✅ Framework provides structure
const engine = new RuleEngine(gameDefinition, players, {
  seed: "deterministic-seed",
});

// Framework handles:
// - Move validation
// - State updates
// - History tracking
// - Network synchronization
// - Player views
// - Game end detection
// - Flow orchestration

// ❌ Don't build your own state management
// ❌ Don't implement your own move validation
// ❌ Don't write custom network sync
```

--------------------------------

### Creating Game Instances with RuleEngine in TypeScript

Source: https://github.com/thecardgoat/tcg-engines/blob/main/packages/core/docs/ENGINE_INTEGRATION.md

Demonstrates how to create a game engine instance using `RuleEngine` from @tcg/core and set up the initial game state with players.

```typescript
import { RuleEngine } from "@tcg/core";
import { yourGame } from "./game-definition";

// Create engine
const engine = new RuleEngine(yourGame, {
  seed: "deterministic-seed",
});

// Setup initial state
const players: Player[] = [
  { id: "player1", name: "Alice" },
  { id: "player2", name: "Bob" },
];

const initialState = engine.setup({ players });
```

--------------------------------

### New TargetingSpec Example

Source: https://github.com/thecardgoat/tcg-engines/blob/main/packages/gundam-cards/MIGRATION.md

An example of the new TargetingSpec structure for defining target selection in the consolidated Effect type. It includes count, valid targets, chooser, and timing.

```typescript
{
  count: { min: 1, max: 2 },
  validTargets: [{
    type: "unit",
    owner: "opponent",
    state: { hasDamageAtLeast: 0 },
  }],
  chooser: "controller",
  timing: "on_resolution",
}
```

--------------------------------

### Legacy TargetQuery Example

Source: https://github.com/thecardgoat/tcg-engines/blob/main/packages/gundam-cards/MIGRATION.md

An example of the legacy TargetQuery structure used for defining target selection criteria for card effects. It specifies controller, card type, count, and filters.

```typescript
{
  controller: "OPPONENT",
  cardType: "UNIT",
  count: { min: 1, max: 2 },
  filters: [{ type: "hp", comparison: "lte", value: 5 }],
}
```

--------------------------------

### Initialize RuleEngine with Logging Configuration

Source: https://github.com/thecardgoat/tcg-engines/blob/main/packages/core/docs/LOGGING.md

Demonstrates how to initialize the RuleEngine with various logging configurations, including different verbosity levels and enabling pretty printing. This sets up the core logging behavior for the game engine.

```typescript
import { RuleEngine } from '@tcg/core';

const engine = new RuleEngine(gameDefinition, players, {
  seed: 'game-123',
  logger: {
    level: 'DEVELOPER',  // or SILENT, NORMAL_PLAYER, ADVANCED_PLAYER
    pretty: true
  }
});
```

```typescript
const engine = new RuleEngine(gameDefinition, players, {
  logger: { level: 'SILENT' }
});
```

```typescript
const engine = new RuleEngine(gameDefinition, players, {
  logger: { level: 'NORMAL_PLAYER', pretty: true }
});
```

```typescript
const engine = new RuleEngine(gameDefinition, players, {
  logger: { level: 'ADVANCED_PLAYER', pretty: true }
});
```

```typescript
const engine = new RuleEngine(gameDefinition, players, {
  logger: { level: 'DEVELOPER', pretty: true }
});
```

--------------------------------

### Testing: Behavior vs. Implementation (TypeScript)

Source: https://github.com/thecardgoat/tcg-engines/blob/main/packages/core/docs/INTEGRATION.md

Illustrates the difference between testing the observable behavior of a game move and testing its internal implementation details. The good example checks the game state after a move, while the bad example spies on a function call.

```typescript
// ✅ Good - tests behavior
it("allows playing a card when resources are sufficient", () => {
  const game = createGame(testSetup);
  const result = game.executeMove({
    type: "PLAY_CARD",
    playerId: "p1",
    cardId: "card-1",
  });

  expect(result.success).toBe(true);
  expect(result.state.zones.play.p1).toContain("card-1");
});

// ❌ Bad - tests implementation
it("calls the playCard function", () => {
  const spy = jest.spyOn(moves, "playCard");
  // ...
});
```

--------------------------------

### Setup Basic Test Environment with Bun

Source: https://github.com/thecardgoat/tcg-engines/blob/main/packages/gundam-engine/docs/zones-and-testing.md

Sets up a basic testing environment using Bun.test, including importing necessary utilities for creating cards, resetting counters, and managing player IDs and zones. It demonstrates a test case for drawing cards from a deck.

```typescript
import { describe, expect, it, beforeEach } from "bun:test";
import {
  createTestCard,
  createTestCards,
  resetCardCounter
} from "@tcg/core/testing";
import { createPlayerId } from "@tcg/core";
import { createPlayerZones } from "@tcg/gundam/zones";

describe("Zone Operations", () => {
  beforeEach(() => {
    // Reset card counter for deterministic test IDs
    resetCardCounter();
  });

  it("should draw cards from deck", () => {
    const playerId = createPlayerId("player1");
    const zones = createPlayerZones(playerId);

    // Create test cards using core utilities
    const cards = createTestCards(5);
    const deckWithCards = { ...zones.deck, cards: cards.map(c => c.id) };

    const result = drawCards(deckWithCards, zones.hand, 2);

    expect(result.cards).toHaveLength(2);
    expect(result.deck.cards).toHaveLength(3);
    expect(result.hand.cards).toHaveLength(2);
  });
});
```

--------------------------------

### Validating in Conditions vs. Enumerators in TypeScript

Source: https://github.com/thecardgoat/tcg-engines/blob/main/packages/core/docs/guides/move-enumeration.md

This example illustrates the best practice of performing validation within conditions rather than filtering directly in the enumerator. The 'Good' example enumerates all hand cards and relies on the condition to filter playable ones.

```typescript
// ❌ Bad: Filtering in enumerator
enumerator: (state, context) => {
  const player = state.players.find(p => p.id === context.playerId);
  const handCards = player?.hand || [];
  
  // Filtering valid cards here
  return handCards
    .filter(cardId => canAffordCard(state, cardId))
    .map(cardId => ({ cardId }));
}

// ✅ Good: Enumerate all, validate in condition
enumerator: (state, context) => {
  const handCards = context.zones.getCardsInZone('hand', context.playerId);
  return handCards.map(cardId => ({ cardId }));
},

condition: (state, context) => {
  return canAffordCard(state, context.params.cardId);
}
```

--------------------------------

### Create a new Svelte project using sv CLI

Source: https://github.com/thecardgoat/tcg-engines/blob/main/apps/operating-system/README.md

This command initializes a new Svelte project with default settings. It uses npx to execute the sv CLI command.

```shell
npx sv create my-app
```

--------------------------------

### Provide Clear Error Messages in Validators (TypeScript)

Source: https://github.com/thecardgoat/tcg-engines/blob/main/packages/core/docs/guides/validation.md

Highlights the importance of providing clear and actionable error messages in validator configurations. The 'GOOD' example shows descriptive messages for required, min, and max constraints, while the 'BAD' example uses vague, unhelpful messages.

```typescript
// GOOD - Clear, actionable messages
validator
  .required('name', 'Card name is required')
  .min('name', 1, 'Card name must not be empty')
  .max('name', 50, 'Card name must be at most 50 characters');

// BAD - Vague messages
validator
  .required('name', 'Invalid')
  .min('name', 1, 'Error')
  .max('name', 50, 'Too long');
```

--------------------------------

### Combine Type Guards for Complex Logic (TypeScript)

Source: https://github.com/thecardgoat/tcg-engines/blob/main/packages/core/docs/guides/validation.md

Shows how to combine multiple type guards and predicate functions to create complex, readable filtering logic. The 'GOOD' example uses `combineTypeGuards` for composability, while the 'BAD' example uses a less maintainable nested conditional.

```typescript
// GOOD - Readable and composable
const isPlayable = combineTypeGuards([
  isCardOfType('creature'),
  (card) => card.cost <= availableMana,
  (card) => !card.exhausted,
]);

// BAD - Hard to read nested conditions
const isPlayable = (card: Card) =>
  card.type === 'creature' &&
  card.cost <= availableMana &&
  !card.exhausted;
```

--------------------------------

### Create Test Engine with Defaults or Customization

Source: https://github.com/thecardgoat/tcg-engines/blob/main/packages/core/docs/guides/testing-utilities.md

Provides utilities to create a test game engine instance. Supports default player configurations, custom player counts, and deterministic seeding for reproducible tests.

```typescript
import { createTestEngine } from '@tcg/core/testing';

// Create with default 2 players
const engine = createTestEngine(gameDefinition);

// Create with custom players
const players = createTestPlayers(4, ['Alice', 'Bob', 'Charlie', 'Dave']);
const engine = createTestEngine(gameDefinition, players);

// Create with deterministic seed
const engine = createTestEngine(gameDefinition, undefined, {
  seed: 'test-seed-123'
});
```

--------------------------------

### Package.json Configuration for TCG Game

Source: https://github.com/thecardgoat/tcg-engines/blob/main/packages/core/docs/ENGINE_INTEGRATION.md

Example package.json for a TCG game engine. It specifies dependencies like @tcg/core and devDependencies such as TypeScript.

```json
{
  "name": "@tcg/your-game",
  "version": "0.1.0",
  "description": "Your TCG engine built with @tcg/core",
  "private": true,
  "main": "./src/index.ts",
  "types": "./src/index.d.ts",
  "dependencies": {
    "@tcg/core": "workspace:*"
  },
  "devDependencies": {
    "@types/bun": "1.2.14",
    "typescript": "5.8.3"
  }
}
```

--------------------------------

### Use Deterministic Seeds for Testing in TypeScript

Source: https://github.com/thecardgoat/tcg-engines/blob/main/packages/core/docs/guides/testing-utilities.md

Highlights the best practice of using deterministic seeds for testing game engines. It contrasts a 'GOOD' example using a fixed string seed with a 'BAD' example using `Math.random()`, which leads to non-deterministic and unreproducible test results.

```typescript
// GOOD - Deterministic and reproducible
const engine = createTestEngine(gameDefinition, players, {
  seed: 'test-draw-phase'
});

// BAD - Non-deterministic
const engine = createTestEngine(gameDefinition, players, {
  seed: `${Math.random()}`
});
```

--------------------------------

### Card Parser: Using and Batch Parsing in TypeScript

Source: https://github.com/thecardgoat/tcg-engines/blob/main/packages/core/docs/guides/card-tooling.md

Demonstrates how to use the `CardParser` for single and batch parsing of card data. It includes examples of handling successful results, errors, and extracting only successful parses.

```typescript
const parser = new SimpleCardParser();

// Parse single card
const result = parser.parse('Fireball|3|spell');
if (result.success) {
  console.log('Parsed:', result.data);
  console.log('Warnings:', result.warnings);
} else {
  console.error('Errors:', result.errors);
}

// Parse batch
const inputs = [
  'Fireball|3|spell',
  'Giant|5|creature',
  'Invalid',
];
const results = parser.parseBatch(inputs);

// Get only successful results
const cards = parser.parseSuccessful(inputs);
console.log(`Parsed ${cards.length} cards successfully`);
```

--------------------------------

### Migrate from RuleEngine to MultiplayerEngine

Source: https://github.com/thecardgoat/tcg-engines/blob/main/packages/core/src/engine/MULTIPLAYER.md

Demonstrates the migration from direct RuleEngine usage to the MultiplayerEngine for handling multiplayer game logic. The MultiplayerEngine automatically handles patch broadcasting.

```typescript
// OLD CODE
const server = new RuleEngine(gameDefinition, players);
const result = server.executeMove("playCard", context);
if (result.success) {
  broadcastToClients(result.patches);
}

// NEW CODE
const server = new MultiplayerEngine(gameDefinition, players, {
  mode: "server",
  onPatchBroadcast: (broadcast) => broadcastToClients(broadcast.patches),
});
const result = server.executeMove("playCard", context);
// Patches automatically broadcast via callback
```