Expose game configuration (energy types, card types, rule constants) via
/api/config endpoint so frontend can dynamically load game rules without
hardcoding values.
Add CardRarityTier enum for pull rate calculations (common through
crown_rare). Add CardSubtype enum for Pokemon classifications (basic,
stage1, stage2, ex, etc.). Update CardDefinition model with new fields
for subtypes and rarity display.
Document local skill files in .claude/skills/ so they are discoverable
when invoking /backend-phase, /frontend-phase, /code-audit,
/frontend-code-audit, and /dev-server commands.
- Replace manual fetch calls with apiClient.get() and apiClient.patch()
- Remove manual token handling (apiClient handles this automatically)
- Add typed UserProfileResponse interface for API response
- Improve error handling with ApiError type checking
- Gains automatic token refresh on 401 with retry logic
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The frontend routing guard checks has_starter_deck to decide whether to
redirect users to starter selection. The field was missing from the API
response, causing authenticated users with a starter deck to be
incorrectly redirected to /starter on page refresh.
- Add has_starter_deck computed property to User model
- Add has_starter_deck field to UserResponse schema
- Add unit tests for User model properties
- Add API tests for has_starter_deck in profile response
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
ProfilePage implementation:
- Full profile page with avatar, editable display name, session count
- LinkedAccountCard and DisplayNameEditor components
- useProfile composable wrapping user store operations
- Support for linking/unlinking OAuth providers
- Logout and logout-all-devices functionality
Profanity service with bypass detection:
- Uses better-profanity library for base detection
- Enhanced to catch common bypass attempts:
- Number suffixes/prefixes (shit123, 69fuck)
- Leet-speak substitutions (sh1t, f@ck, $hit)
- Separator characters (s.h.i.t, f-u-c-k)
- Integrated into PATCH /api/users/me endpoint
- 17 unit tests covering all normalization strategies
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Features:
- Add useAuth composable with OAuth flow and token management
- Add useStarter composable with API integration and dev mock fallback
- Implement app auth initialization blocking navigation until ready
- Complete StarterSelectionPage with 5 themed deck options
Bug fixes:
- Fix CORS by adding localhost:3001 to allowed origins
- Fix OAuth URL to include redirect_uri parameter
- Fix emoji rendering in nav components (use actual chars, not escapes)
- Fix requireStarter guard timing by allowing navigation from /starter
- Fix starter "already selected" detection for 400 status code
Documentation:
- Update dev-server skill to use `docker compose` (newer CLI syntax)
- Update .env.example with port 3001 in CORS comment
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Complete the AuthCallbackPage to handle OAuth redirects by parsing tokens
from URL fragment, fetching user profile, and redirecting based on starter
deck status. Includes open-redirect protection and comprehensive tests.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add /dev-server skill with preflight checks for environment, deps,
ports, and services before starting frontend/backend
- Add /frontend-phase skill for tracking implementation phases
- Register skills in .claude/settings.json
- Update .env.development ports (8001 for API, 3001 for frontend)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Code audit fixes:
- Update LoginPage for OAuth (Google/Discord buttons, no password)
- Delete RegisterPage.vue (OAuth-only app)
- Delete AppHeader.vue (superseded by NavSidebar, had bugs)
- Add ErrorBoundary component for graceful error handling
Also adds Phase F1 (Authentication Flow) plan with 10 tasks.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Create responsive layout system based on route meta:
- DefaultLayout: sidebar (desktop) / bottom tabs (mobile)
- MinimalLayout: centered content for auth pages
- GameLayout: full viewport for Phaser game
Navigation components:
- NavSidebar: desktop sidebar with main nav + user menu
- NavBottomTabs: mobile bottom tab bar
UI components (tied to UI store):
- LoadingOverlay: full-screen overlay with spinner
- ToastContainer: stacked notification toasts
Also adds Vue Router meta type declarations.
Phase F0 is now complete (8/8 tasks).
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Create typed event interfaces for game namespace
- Add full game state types (GameState, Card, CardInPlay, etc.)
- Implement connection manager singleton with auth
- Add auto-reconnection with exponential backoff
- Provide helper methods for game actions (joinGame, sendAction, etc.)
- Add typed event subscription helpers with unsubscribe
Phase F0 progress: 7/8 tasks complete
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Create ApiError class with status helpers (isNotFound, etc.)
- Create typed fetch wrapper with get/post/put/patch/delete methods
- Auto-inject Authorization header from auth store
- Handle 401 with automatic token refresh and retry
- Add query parameter support and proper URL building
- Add comprehensive tests (11 tests)
Phase F0 progress: 6/8 tasks complete
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Refactor auth store for OAuth flow (access/refresh tokens)
- Add token refresh logic and expiry tracking
- Create user store for profile data and linked accounts
- Create UI store for loading overlay, toasts, and modals
- Update router guard tests for new auth store structure
- Add comprehensive tests (45 total passing)
Phase F0 progress: 5/8 tasks complete
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add environment configuration with type-safe config.ts
- Implement navigation guards (requireAuth, requireGuest, requireStarter)
- Update router to match sitePlan routes and layouts
- Create placeholder pages for all sitePlan routes
- Update auth store User interface for OAuth flow
- Add phase plan tracking for F0
Phase F0 progress: 4/8 tasks complete
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Rename project instructions file to Claude Code standard name
- Add .gitignore to exclude IDE files and frontend-poc/
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- REST endpoints for auth, users, collections, decks, games
- WebSocket events (client→server and server→client)
- Key backend files to reference
- Type definitions to mirror from backend schemas
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Update status to COMPLETE with completedDate 2026-01-30
- Increment completedPhases from 4 to 5
- Update deliverables list with actual implementations
- 306 new tests added, 1505 total tests
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add UserRepository and LinkedAccountRepository protocols to protocols.py
- Add UserEntry and LinkedAccountEntry DTOs for service layer decoupling
- Implement PostgresUserRepository and PostgresLinkedAccountRepository
- Refactor UserService to use constructor-injected repositories
- Add get_user_service factory and UserServiceDep to API deps
- Update auth.py and users.py endpoints to use UserServiceDep
- Rewrite tests to use FastAPI dependency overrides (no monkey patching)
This follows the established repository pattern used by DeckService and
CollectionService, enabling future offline fork support.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Create 16 integration tests across 7 test classes covering:
- JWT authentication (valid/invalid/expired tokens)
- Game join flow with Redis connection tracking
- Action execution and state broadcasting
- Turn timeout Redis operations (start/get/cancel/extend)
- Disconnection cleanup
- Spectator filtered state
- Reconnection tracking
Uses testcontainers for real Redis/Postgres integration. Completes
Phase 4 (Game Service + WebSocket) with all 18 tasks finished.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add REST API endpoints for game lifecycle operations:
- POST /games - Create new game between two players
- GET /games/{game_id} - Get game info for reconnection
- GET /games/me/active - List user's active games
- POST /games/{game_id}/resign - Resign from game via HTTP
Includes proper reverse proxy support for WebSocket URL generation
(X-Forwarded-* headers -> settings.base_url -> Host header fallback).
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add GameNamespaceHandler with full event handling for real-time gameplay:
- handle_join: Join/rejoin games with visibility-filtered state
- handle_action: Execute actions and broadcast state to participants
- handle_resign: Process resignation and end game
- handle_disconnect: Notify opponent of disconnection
- Broadcast helpers for state, game over, and opponent status
Includes 28 unit tests covering all handler methods.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add GameEndResult dataclass with winner, loser, final views, duration
- Add _map_end_reason() to map core GameEndReason to DB EndReason
(raises ValueError for unknown reasons to catch missing enum sync)
- Enhance end_game() to build replay data and return comprehensive result
- Add archive_to_history() to GameStateManager for complete game archival:
- Creates GameHistory record with replay data
- Deletes ActiveGame record
- Clears Redis cache
- All in single transaction
- Add ArchiveResult dataclass for archive operation metadata
- Add TODO for session_factory DI refactor in GameStateManager
- Update tests: 5 new end_game tests, 6 new archive_to_history tests
Phase 4 progress: 10/18 tasks complete
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add pending forced action and game_over fields to GameJoinResult:
- pending_forced_action: Included when player must complete a forced
action (e.g., select new active after KO). Essential for reconnection
so client knows what action is required.
- game_over: Boolean indicating if game has already ended.
- is_your_turn: Now True when player has pending forced action, even if
it's technically opponent's turn.
The join_game method now handles both initial joins and reconnections
(resume). The last_event_id parameter is accepted for future event
replay support.
Tests: 4 new tests for forced action handling and game_over flag.
Total 51 tests for GameService.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Standardizes the phased development workflow:
- /backend-phase status - Show current phase and progress
- /backend-phase next - Show details of next task
- /backend-phase start <id> - Begin working on task
- /backend-phase done <id> - Mark task complete with tests
- /backend-phase plan - Create plan for next NOT_STARTED phase
Reads from PROJECT_PLAN_MASTER.json and project_plans/PHASE_*.json.
Ensures dependencies are met before starting tasks and tests exist
before marking complete.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Fix audit warnings about empty string defaults hiding data corruption:
1. get_connection_info(): Validate required fields (user_id, connected_at,
last_seen) exist before creating ConnectionInfo. Return None and log
warning for corrupted records instead of returning invalid data.
2. unregister_connection(): Log warning if user_id is missing during
cleanup. Existing code safely handles this (skips cleanup), but now
we have visibility into data corruption.
Test added for corrupted data case.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Three changes to fail fast instead of silently degrading:
1. GameService.create_game: Raise GameCreationError when energy card
definition not found instead of logging warning and continuing.
A deck with missing energy cards is fundamentally broken.
2. CardService.load_all: Collect all card file load failures and raise
CardServiceLoadError at end with comprehensive error report. Prevents
startup with partial card data that causes cryptic runtime errors.
New exceptions: CardLoadError, CardServiceLoadError
3. GameStateManager.recover_active_games: Return RecoveryResult dataclass
with recovered count, failed game IDs with error messages, and total.
Enables proper monitoring and alerting for corrupted game state.
Tests added for energy card error case. Existing tests updated for
new RecoveryResult return type.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add forced action handling, turn boundary detection, and DB persistence:
- Check for pending forced actions before allowing regular actions
- Only specified player can act during forced action (except resign)
- Only specified action type allowed during forced action
- Detect turn boundaries (turn number OR current player change)
- Persist to Postgres at turn boundaries for durability
- Include pending_forced_action in GameActionResult for client
New exceptions: ForcedActionRequiredError
Tests: 11 new tests covering forced actions, turn boundaries, and
pending action reporting. Total 47 tests for GameService.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add create_game method that loads decks via DeckService, converts
CardDefinitions to CardInstances, and persists to Redis/Postgres
- Build card registry from only the cards in play (not all cards)
- Add GameCreationError exception and GameCreateResult dataclass
- Add creation_engine_factory for DI-based testing (no monkey patching)
- Add helper methods: _cards_to_instances, _build_card_registry
- Update tests with proper mocks for success, deck failure, engine failure
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Migrate all usages to the proper mode/value fields:
- Weakness: mode=MULTIPLICATIVE, value=2
- Resistance: mode=ADDITIVE, value=-30
Remove backwards compatibility code and legacy test.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- ConnectionManager: Add redis_factory constructor parameter
- GameService: Add engine_factory constructor parameter
- AuthHandler: New class replacing standalone functions with
token_verifier and conn_manager injection
- Update all tests to use constructor DI instead of patch()
- Update CLAUDE.md with factory injection patterns
- Update services README with new patterns
- Add socketio README documenting AuthHandler and events
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
WebSocket Message Schemas (WS-002):
- Add Pydantic models for all client/server WebSocket messages
- Implement discriminated unions for message type parsing
- Include JoinGame, Action, Resign, Heartbeat client messages
- Include GameState, ActionResult, Error, TurnStart server messages
Connection Manager (WS-003):
- Add Redis-backed WebSocket connection tracking
- Implement user-to-sid mapping with TTL management
- Support game room association and opponent lookup
- Add heartbeat tracking for connection health
Socket.IO Authentication (WS-004):
- Add JWT-based authentication middleware
- Support token extraction from multiple formats
- Implement session setup with ConnectionManager integration
- Add require_auth helper for event handlers
Socket.IO Server Setup (WS-001):
- Configure AsyncServer with ASGI mode
- Register /game namespace with event handlers
- Integrate with FastAPI via ASGIApp wrapper
- Configure CORS from application settings
Game Service (GS-001):
- Add stateless GameService for game lifecycle orchestration
- Create engine per-operation using rules from GameState
- Implement action-based RNG seeding for deterministic replay
- Add rng_seed field to GameState for replay support
Architecture verified:
- Core module independence (no forbidden imports)
- Config from request pattern (rules in GameState)
- Dependency injection (constructor deps, method config)
- All 1090 tests passing
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Create tests/conftest.py with testcontainers for Postgres and Redis
- Auto-detect Docker Desktop socket and disable Ryuk for compatibility
- Update tests/db/conftest.py and tests/services/conftest.py to use shared fixtures
- Fix test_resolve_effect_logs_exceptions: logger was disabled by pytest
- Fix test_save_and_load_with_real_redis: use redis_url fixture
- Minor lint fix in engine_validation.py
Tests now auto-start containers on run - no need for `docker compose up`
All 1199 tests passing.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Project plan updates:
- Mark all 14 Phase 3 tasks as completed
- Update acceptance criteria to met
- Update master plan status to Phase 4 next
- Add detailed deliverables list for Phase 3
Documentation updates:
- Add UNSET sentinel pattern to CLAUDE.md
- Document when to use UNSET vs None for nullable fields
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
UNSET sentinel pattern:
- Add UNSET sentinel in protocols.py for nullable field updates
- Fix inability to clear deck description (UNSET=keep, None=clear)
- Fix repository inability to clear validation_errors
Starter deck improvements:
- Remove unused has_starter_deck from CollectionService
- Add deprecation notes to old starter deck methods
Validation improvements:
- Add energy type validation in deck_validator.py
- Add energy type validation in deck schemas
- Add VALID_ENERGY_TYPES constant
Game loading fix:
- Fix get_deck_for_game silently skipping invalid cards
- Now raises ValueError with clear error message
Tests:
- Add TestEnergyTypeValidation test class
- Add TestGetDeckForGame test class
- Add tests for validate_energy_types utility function
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Critical fixes:
- Add admin API key authentication for admin endpoints
- Add race condition protection via unique partial index for starter decks
- Make starter deck selection atomic with combined method
Moderate fixes:
- Fix DI pattern violation in validate_deck_endpoint
- Add card ID format validation (regex pattern)
- Add card quantity validation (1-99 range)
- Fix exception chaining with from None (B904)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Implemented with Repository Protocol pattern for offline fork support:
- CollectionService with PostgresCollectionRepository
- DeckService with PostgresDeckRepository
- DeckValidator with DeckConfig + CardService injection
- Starter deck definitions (5 types: grass, fire, water, psychic, lightning)
- Pydantic schemas for collection and deck APIs
- Unit tests for DeckValidator (32 tests passing)
Architecture follows pure dependency injection - no service locator patterns.
Added CLAUDE.md documenting DI requirements and patterns.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Discord OAuth callback now redirects to frontend with tokens in URL fragment
(more secure than query params - fragment not sent to server)
- Error responses also redirect with error in query params
- Fix deps.py import: get_session_dependency -> get_session
Part of Phase 2 Authentication completion.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
