Merge pull request #5 from chrisreddington/main

Add Elicitation, Linting, Convert test infrastructure, Other refinements

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

.github/workflows/ci.yml

@@ -31,26 +31,30 @@ jobs:
         run: npm ci
 
       - name: Build shared package
-        run: npm run build --workspace=shared
+        run: npm run build --workspace=@turn-based-mcp/shared
+
+      - name: Verify shared build artifacts
+        run: |
+          test -f shared/dist/index.js || (echo 'shared/dist/index.js missing' && exit 1)
+          test -f shared/dist/testing/index.js || (echo 'shared/dist/testing/index.js missing' && exit 1)
 
       - name: Type check all workspaces
         run: npm run type-check
 
       - name: Build web package
-        run: npm run build --workspace=web
+        run: npm run build --workspace=@turn-based-mcp/web
 
       - name: Build mcp-server package
-        run: npm run build --workspace=mcp-server
-
-      - name: Lint web package
-        run: npm run lint --workspace=web
-
-      # Future: Add test steps when tests are implemented
-      # - name: Run tests - shared
-      #   run: npm run test --workspace=shared
-      # 
-      # - name: Run tests - web
-      #   run: npm run test --workspace=web
-      # 
-      # - name: Run tests - mcp-server
-      #   run: npm run test --workspace=mcp-server
+        run: npm run build --workspace=@turn-based-mcp/mcp-server
+
+      - name: Run tests - shared
+        run: npm run test --workspace=@turn-based-mcp/shared
+
+      - name: Run tests - web
+        run: npm run test --workspace=@turn-based-mcp/web
+
+      - name: Run tests - mcp-server
+        run: npm run test --workspace=@turn-based-mcp/mcp-server
+
+      - name: Lint all packages
+        run: npm run lint:all

.vscode/mcp.json

@@ -2,7 +2,7 @@
   "servers": {
     "turn-based-games": {
       "command": "node",
-      "args": ["dist/index.js"],
+      "args": ["dist/server.js"],
       "cwd": "./mcp-server"
     },
     "playwright": {

eslint.config.js

@@ -0,0 +1,31 @@
+// @ts-check
+
+import eslint from '@eslint/js';
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+  eslint.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    files: ['**/*.{js,mjs,cjs,ts}'],
+    languageOptions: {
+      parserOptions: {
+        ecmaVersion: 'latest',
+        sourceType: 'module',
+      },
+    },
+    rules: {
+      // Add any global rules here
+    },
+  },
+  {
+    ignores: [
+      '**/node_modules/**',
+      '**/dist/**',
+      '**/.next/**',
+      '**/coverage/**',
+      '**/*.config.js',
+      '**/*.config.ts',
+    ],
+  }
+);

mcp-server/eslint.config.js

@@ -0,0 +1,41 @@
+// @ts-check
+
+import eslint from '@eslint/js';
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+  eslint.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    files: ['**/*.{js,mjs,cjs,ts}'],
+    languageOptions: {
+      parserOptions: {
+        ecmaVersion: 'latest',
+        sourceType: 'module',
+      },
+    },
+    rules: {
+      // MCP server specific rules
+      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+      '@typescript-eslint/explicit-function-return-type': 'warn',
+      '@typescript-eslint/no-explicit-any': 'warn',
+      'no-console': 'off', // Console logging is often needed for MCP servers
+    },
+  },
+  {
+    files: ['**/*.test.ts', 'vitest.*.ts'],
+    rules: {
+      '@typescript-eslint/explicit-function-return-type': 'off',
+      '@typescript-eslint/no-explicit-any': 'off',
+    },
+  },
+  {
+    ignores: [
+      'node_modules/**',
+      'dist/**',
+      'coverage/**',
+      '*.config.js',
+      '*.config.ts',
+    ],
+  }
+);