turn-based-game-mcp shared-library.instructions.md

Shared Library Development

Purpose

Patterns for the @turn-based-mcp/shared package. Covers game implementations, storage abstraction, type system design, and constants.

Library Architecture

Module Organization

• Group related functionality in logical modules (games/, storage/, utils/, types/)
• Use barrel exports (index.ts) for clean external API
• Keep internal implementation details private
• Expose only necessary types and functions

Game Implementation Pattern

All games must implement the Game<TGameState, TMove> interface:

export class GameClass implements Game<GameState, MoveType> {
  validateMove(state: GameState, move: MoveType, playerId: string): boolean {
    // Validate move logic
  }
  
  applyMove(state: GameState, move: MoveType, playerId: string): GameState {
    // Apply move and return new state (immutable)
  }
  
  checkGameEnd(state: GameState): GameResult | null {
    // Check for win/draw conditions
  }
  
  getValidMoves(state: GameState): MoveType[] {
    // Return all possible moves
  }
  
  getInitialState(players: Player[]): GameState {
    // Create initial game state
  }
}

Storage Abstraction

Dual Storage Pattern

Provide both direct SQLite access and HTTP API client functions:

// Direct database access (web app)
export async function getGame(id: string): Promise<GameSession | undefined>
export async function setGame(id: string, session: GameSession): Promise<void>

// HTTP API client (MCP server)
export async function getGameForMCP(id: string): Promise<GameSession | undefined>
export async function createGameForMCP(playerName: string): Promise<GameSession>

Storage Interface

interface GameStorage {
  // CRUD operations
  get<T>(id: string): Promise<GameSession<T> | undefined>
  set<T>(id: string, session: GameSession<T>): Promise<void>
  getAll<T>(): Promise<GameSession<T>[]>
  delete(id: string): Promise<boolean>
}

Type System Design