Update instructions and reduce type union duplication

Author: chrisreddington

.github/instructions/mcp-server.instructions.md

@@ -145,7 +145,7 @@ Implement consistent difficulty levels across all games:
 ```typescript
 export function calculateTicTacToeMove(
   gameState: TicTacToeGameState,
-  difficulty: 'easy' | 'medium' | 'hard' = 'medium'
+  difficulty: Difficulty = 'medium'
 ): TicTacToeMove {
   const validMoves = getValidMoves(gameState)
 

.github/instructions/shared-library.instructions.md

@@ -140,6 +140,89 @@ export function getGameDisplayName(type: GameType): string {
 }
 ```
 
+## Constants and Common Values
+
+### Centralized Constants and Derived Types
+**Types are derived from constants using `as const` assertions - constants are the single source of truth:**
+
+```typescript
+// ✅ Constants define the source of truth
+export const DIFFICULTIES = ['easy', 'medium', 'hard'] as const
+export const GAME_TYPES = ['tic-tac-toe', 'rock-paper-scissors'] as const
+export const PLAYER_IDS = { HUMAN: 'player1', PLAYER2: 'player2', AI: 'ai' } as const
+
+// ✅ Types are derived from constants
+export type Difficulty = typeof DIFFICULTIES[number]
+export type GameType = typeof GAME_TYPES[number] 
+export type PlayerId = typeof PLAYER_IDS[keyof typeof PLAYER_IDS]
+
+// ✅ Import the derived types
+import type { Difficulty, GameType } from '@turn-based-mcp/shared'
+
+// ❌ Don't define duplicate union types
+export type Difficulty = 'easy' | 'medium' | 'hard'  // This duplicates the constants!
+```
+
+### Available Constants
+Key constants provided by the shared library:
+
+```typescript
+// Constants with derived types
+export const GAME_TYPES = ['tic-tac-toe', 'rock-paper-scissors'] as const
+export const DIFFICULTIES = ['easy', 'medium', 'hard'] as const
+export const PLAYER_IDS = { HUMAN: 'player1', PLAYER2: 'player2', AI: 'ai' } as const
+export const GAME_STATUSES = ['waiting', 'playing', 'finished'] as const
+
+// Derived types (auto-generated from constants)
+export type GameType = typeof GAME_TYPES[number]
+export type Difficulty = typeof DIFFICULTIES[number]
+export type PlayerId = typeof PLAYER_IDS[keyof typeof PLAYER_IDS]
+export type GameStatus = typeof GAME_STATUSES[number]
+
+// Default values
+export const DEFAULT_PLAYER_NAME = 'Player'
+export const DEFAULT_AI_DIFFICULTY: Difficulty = 'medium'
+
+// UI display configuration
+export const DIFFICULTY_DISPLAY = {
+  easy: { emoji: '😌', label: 'Easy' },
+  medium: { emoji: '🎯', label: 'Medium' },
+  hard: { emoji: '🔥', label: 'Hard' }
+} as const
+```
+
+### Type Guards and Utilities
+Use provided validation functions that work with the constants:
+
+```typescript
+// Type guards (check against the constant arrays)
+export function isSupportedGameType(gameType: string): gameType is GameType
+export function isValidDifficulty(difficulty: string): difficulty is Difficulty
+export function isValidPlayerId(playerId: string): playerId is PlayerId
+
+// Display helpers
+export function getDifficultyDisplay(difficulty: Difficulty)
+```
+
+### Architecture Benefits
+This approach ensures:
+- **Single source of truth**: Constants define what values are valid
+- **Type safety**: TypeScript derives exact types from the constant values
+- **Runtime validation**: Type guards check against the same arrays used to derive types
+- **Maintainability**: Add a new difficulty by updating one constant array
+
+### Testing Constants
+For mocking and test data, use shared testing utilities:
+
+```typescript
+// Test data from shared/src/testing/
+import { 
+  mockTicTacToeGameState, 
+  mockRPSGameState,
+  createMockGameSession 
+} from '@turn-based-mcp/shared/testing'
+```
+
 ## Testing Infrastructure
 
 ### Test Database Utilities

.github/instructions/testing.instructions.md

@@ -31,6 +31,33 @@ Follow these testing patterns for the turn-based games platform:
   })
   ```
 
+## Shared Testing Utilities
+
+**Use centralized mock data and test utilities from the shared package:**
+
+```typescript
+// ✅ Import shared testing utilities
+import { 
+  mockTicTacToeGameState, 
+  mockRPSGameState,
+  createMockGameSession,
+  setupTestDatabase,
+  clearTestDatabase 
+} from '@turn-based-mcp/shared/testing'
+
+// ✅ Use shared constants in tests
+import { DIFFICULTIES, GAME_TYPES } from '@turn-based-mcp/shared'
+
+// ❌ Don't recreate mock data locally
+const localMockGameState = { /* duplicated data */ }  // Use shared mocks instead!
+```
+
+**Available shared testing utilities:**
+- Mock game states: `mockTicTacToeGameState`, `mockRPSGameState`
+- Factory functions: `createMockGameSession`, `createMockPlayer`
+- Database utilities: `setupTestDatabase`, `clearTestDatabase`, `teardownTestDatabase`
+- Type assertions and validation helpers
+
 ## Component Testing
 
 - Always render components with realistic props

.github/instructions/typescript.instructions.md

@@ -15,6 +15,37 @@ Follow these TypeScript patterns for consistent, type-safe code:
 - Use barrel exports (`index.ts`) for clean imports
 - Re-export shared types from `@turn-based-mcp/shared`
 
+### Shared Types and Constants
+**Always import types derived from shared constants - don't duplicate union types:**
+
+```typescript
+// ✅ Import types derived from constants
+import type { Difficulty, GameType, PlayerId } from '@turn-based-mcp/shared'
+import { DIFFICULTIES, DEFAULT_AI_DIFFICULTY, GAME_TYPES, PLAYER_IDS } from '@turn-based-mcp/shared'
+
+// ✅ Use the imported types
+const [aiDifficulty, setAiDifficulty] = useState<Difficulty>('medium')
+const playerIds: PlayerId[] = Object.values(PLAYER_IDS)
+
+// ❌ Don't define duplicate union types
+type Difficulty = 'easy' | 'medium' | 'hard'  // This duplicates shared constants!
+type PlayerId = 'player1' | 'player2' | 'ai'  // Use the derived type instead!
+```
+
+**Key principle: Types are derived from constants using `as const` assertions:**
+```typescript
+// In shared/src/constants/game-constants.ts
+export const DIFFICULTIES = ['easy', 'medium', 'hard'] as const
+export type Difficulty = typeof DIFFICULTIES[number]  // 'easy' | 'medium' | 'hard'
+```
+
+**Common types available from shared package:**
+- `Difficulty` - AI difficulty levels (derived from `DIFFICULTIES`) 
+- `GameType` - Supported game types (derived from `GAME_TYPES`)
+- `PlayerId` - Player identifiers (derived from `PLAYER_IDS`)
+- `GameStatus` - Game state values (derived from `GAME_STATUSES`)
+- Game-specific interfaces: `TicTacToeGameState`, `RPSGameState`, etc.
+
 ### Interface Design
 - Use interfaces for object shapes and component props
 - Include JSDoc comments for complex properties

mcp-server/src/ai/rock-paper-scissors-ai.ts

@@ -1,8 +1,7 @@
-import type { RPSGameState, RPSMove, RPSChoice } from '@turn-based-mcp/shared'
+import type { RPSGameState, RPSMove, RPSChoice, Difficulty } from '@turn-based-mcp/shared'
 import { RockPaperScissorsGame } from '@turn-based-mcp/shared'
 
 export type Strategy = 'random' | 'adaptive' | 'pattern'
-export type Difficulty = 'easy' | 'medium' | 'hard'
 
 /**
  * AI opponent for Rock Paper Scissors with multiple strategic approaches

mcp-server/src/ai/tic-tac-toe-ai.ts

@@ -1,8 +1,6 @@
-import type { TicTacToeGameState, TicTacToeMove } from '@turn-based-mcp/shared'
+import type { TicTacToeGameState, TicTacToeMove, Difficulty } from '@turn-based-mcp/shared'
 import { TicTacToeGame } from '@turn-based-mcp/shared'
 
-export type Difficulty = 'easy' | 'medium' | 'hard'
-
 /**
  * AI opponent for Tic-Tac-Toe with configurable difficulty levels
  * 

shared/src/constants/game-constants.ts

@@ -1,34 +1,46 @@
 /**
  * Shared game constants
- * Single source of truth for game types, difficulties, and default values
+ * Single source of truth for game types, difficulties, player IDs, and default values
  */
 
-import type { GameType, Difficulty } from '../types/game'
-
 /**
  * Supported game types
  */
-export const GAME_TYPES: readonly GameType[] = ['tic-tac-toe', 'rock-paper-scissors'] as const
+export const GAME_TYPES = ['tic-tac-toe', 'rock-paper-scissors'] as const
 
 /**
  * Available AI difficulty levels
  */
-export const DIFFICULTIES: readonly Difficulty[] = ['easy', 'medium', 'hard'] as const
-
-/**
- * Default player configurations
- */
-export const DEFAULT_PLAYER_NAME = 'Player'
-export const DEFAULT_AI_DIFFICULTY: Difficulty = 'medium'
+export const DIFFICULTIES = ['easy', 'medium', 'hard'] as const
 
 /**
  * Standard player IDs used across the system
  */
 export const PLAYER_IDS = {
   HUMAN: 'player1',
+  PLAYER2: 'player2', 
   AI: 'ai'
 } as const
 
+/**
+ * Game status values
+ */
+export const GAME_STATUSES = ['waiting', 'playing', 'finished'] as const
+
+/**
+ * Derive types from constants
+ */
+export type GameType = typeof GAME_TYPES[number]
+export type Difficulty = typeof DIFFICULTIES[number]
+export type PlayerId = typeof PLAYER_IDS[keyof typeof PLAYER_IDS]
+export type GameStatus = typeof GAME_STATUSES[number]
+
+/**
+ * Default player configurations
+ */
+export const DEFAULT_PLAYER_NAME = 'Player'
+export const DEFAULT_AI_DIFFICULTY: Difficulty = 'medium'
+
 /**
  * Difficulty display configuration
  */
@@ -52,6 +64,20 @@ export function isValidDifficulty(difficulty: string): difficulty is Difficulty
   return DIFFICULTIES.includes(difficulty as Difficulty)
 }
 
+/**
+ * Type guard to check if a string is a valid player ID
+ */
+export function isValidPlayerId(playerId: string): playerId is PlayerId {
+  return Object.values(PLAYER_IDS).includes(playerId as PlayerId)
+}
+
+/**
+ * Type guard to check if a string is a valid game status
+ */
+export function isValidGameStatus(status: string): status is GameStatus {
+  return GAME_STATUSES.includes(status as GameStatus)
+}
+
 /**
  * Get difficulty display configuration
  */

shared/src/testing/api-test-utils.ts

@@ -6,7 +6,7 @@
  */
 
 import { vi } from 'vitest'
-import type { GameSession, Player, BaseGameState } from '../types/game'
+import type { GameSession, Player, BaseGameState, GameType } from '../types/game'
 import type { TicTacToeGameState, RPSGameState, TicTacToeMove, RPSMove } from '../types/games'
 
 /**
@@ -82,7 +82,7 @@ export function createMockRPSGameState(overrides: Partial<RPSGameState> = {}): R
 /**
  * Create a mock game session
  */
-export function createMockGameSession<T extends BaseGameState>(gameState: T, gameType: 'tic-tac-toe' | 'rock-paper-scissors'): GameSession<T> {
+export function createMockGameSession<T extends BaseGameState>(gameState: T, gameType: GameType): GameSession<T> {
   return {
     gameState,
     gameType,
@@ -110,7 +110,7 @@ export function createSharedGameMocks(gameClass: string) {
 /**
  * Create storage function mocks for a specific game type
  */
-export function createStorageMocks(gameType: 'tic-tac-toe' | 'rock-paper-scissors') {
+export function createStorageMocks(gameType: GameType) {
   if (gameType === 'tic-tac-toe') {
     return {
       getTicTacToeGame: vi.fn(),

shared/src/types/game.ts

@@ -1,14 +1,14 @@
 // Core game types
-export type PlayerId = 'player1' | 'player2' | 'ai';
+import type { PlayerId, GameStatus, GameType, Difficulty } from '../constants/game-constants'
+
+export type { PlayerId, GameStatus, GameType, Difficulty }
 
 export interface Player {
   id: PlayerId;
   name: string;
   isAI: boolean;
 }
 
-export type GameStatus = 'waiting' | 'playing' | 'finished';
-
 export interface BaseGameState {
   id: string;
   players: Player[];
@@ -39,10 +39,6 @@ export interface Game<TGameState extends BaseGameState, TMove> {
   getInitialState(players: Player[], options?: any): TGameState;
 }
 
-export type GameType = 'tic-tac-toe' | 'rock-paper-scissors';
-
-export type Difficulty = 'easy' | 'medium' | 'hard';
-
 // Generic game session for API communication
 export interface GameSession<TGameState extends BaseGameState = BaseGameState> {
   gameState: TGameState;

web/src/app/games/rock-paper-scissors/page.tsx

@@ -5,7 +5,7 @@ import { RPSGameBoard } from '../../../components/games/RPSGameBoard'
 import { GameInfoPanel } from '../../../components/games/GameInfoPanel'
 import { GameContainer, GameControls, ConfirmationModal } from '../../../components/ui'
 import { MCPAssistantPanel } from '../../../components/shared'
-import type { RPSGameState, RPSMove } from '@turn-based-mcp/shared'
+import type { RPSGameState, RPSMove, Difficulty } from '@turn-based-mcp/shared'
 import type { GameSession } from '@turn-based-mcp/shared'
 
 export default function RockPaperScissorsPage() {
@@ -16,7 +16,7 @@ export default function RockPaperScissorsPage() {
   const [availableGames, setAvailableGames] = useState<GameSession<RPSGameState>[]>([])
   const [showCreateForm, setShowCreateForm] = useState(false)
   const [showJoinForm, setShowJoinForm] = useState(false)
-  const [aiDifficulty, setAiDifficulty] = useState<'easy' | 'medium' | 'hard'>('medium')
+  const [aiDifficulty, setAiDifficulty] = useState<Difficulty>('medium')
   const [gamesToShow, setGamesToShow] = useState(5)
   const [showDeleteModal, setShowDeleteModal] = useState(false)
   const [gameToDelete, setGameToDelete] = useState<string | null>(null)
@@ -431,7 +431,7 @@ export default function RockPaperScissorsPage() {
                 </label>
                 <select
                   value={aiDifficulty}
-                  onChange={(e) => setAiDifficulty(e.target.value as 'easy' | 'medium' | 'hard')}
+                  onChange={(e) => setAiDifficulty(e.target.value as Difficulty)}
                   className="w-full px-4 py-3 bg-white/60 dark:bg-slate-700/60 border border-slate-200 dark:border-slate-600 rounded-xl focus:outline-none focus:ring-2 focus:ring-green-500 focus:border-transparent transition-all duration-200"
                 >
                   <option value="easy">🟢 Easy - Random moves</option>