From 09844cbf3f68785c82ec6c97f0b5cfb83c4b88d0 Mon Sep 17 00:00:00 2001 From: Cal Corum Date: Fri, 30 Jan 2026 11:56:25 -0600 Subject: [PATCH] Add dev-server skill and update development ports - 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 --- .claude/settings.json | 16 ++ .claude/skills/dev-server/SKILL.md | 162 +++++++++++++++++ .claude/skills/dev-server/preflight.sh | 164 +++++++++++++++++ .claude/skills/frontend-phase/SKILL.md | 241 +++++++++++++++++++++++++ frontend/.env.development | 6 +- 5 files changed, 586 insertions(+), 3 deletions(-) create mode 100644 .claude/settings.json create mode 100644 .claude/skills/dev-server/SKILL.md create mode 100755 .claude/skills/dev-server/preflight.sh create mode 100644 .claude/skills/frontend-phase/SKILL.md diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 0000000..f22e6b9 --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,16 @@ +{ + "skills": { + "dev-server": { + "path": ".claude/skills/dev-server", + "description": "Start frontend and backend dev servers with pre-flight checks. Use when user says 'start dev', 'dev server', '/dev-server', or wants to run the development environment." + }, + "frontend-phase": { + "path": ".claude/skills/frontend-phase", + "description": "Track and manage frontend implementation phases. Use for /frontend-phase commands." + }, + "frontend-code-audit": { + "path": ".claude/skills/frontend-code-audit", + "description": "Run code audits on frontend code for anti-patterns and issues." + } + } +} diff --git a/.claude/skills/dev-server/SKILL.md b/.claude/skills/dev-server/SKILL.md new file mode 100644 index 0000000..daf69e6 --- /dev/null +++ b/.claude/skills/dev-server/SKILL.md @@ -0,0 +1,162 @@ +# Dev Server Skill + +Start both frontend and backend development servers with pre-flight checks. + +## Usage + +``` +/dev-server [command] +``` + +**Commands:** +- `start` (default) - Run checks and start both servers +- `stop` - Stop all running dev servers +- `status` - Check if servers are running + +## Instructions + +When this skill is invoked, follow these steps: + +### 1. Pre-flight Checks + +Run all checks in parallel where possible: + +#### Environment Variables +Check that required env files exist and have valid values: + +**Frontend** (`frontend/.env.development`): +- `VITE_API_BASE_URL` - Must be a valid URL +- `VITE_WS_URL` - Must be a valid URL +- `VITE_OAUTH_REDIRECT_URI` - Must be a valid URL + +**Backend** (`backend/.env` or environment): +- `DATABASE_URL` - PostgreSQL connection string +- `REDIS_URL` - Redis connection string +- `JWT_SECRET` - Must be set (check length >= 32) + +#### Port Availability +Check if default ports are available: +- Frontend: 5173, 3000, 3001 (Vite will auto-increment) +- Backend: 8000, 8001 + +```bash +# Check port availability +lsof -i :8000 2>/dev/null | grep LISTEN +lsof -i :5173 2>/dev/null | grep LISTEN +``` + +#### Dependencies +Verify dependencies are installed: +```bash +# Frontend +[ -d "frontend/node_modules" ] || echo "Run: cd frontend && npm install" + +# Backend +[ -f "backend/.venv/bin/activate" ] || echo "Run: cd backend && uv sync" +``` + +#### Database/Redis +Check if PostgreSQL and Redis are accessible: +```bash +# PostgreSQL (if DATABASE_URL is set) +pg_isready -d "$DATABASE_URL" 2>/dev/null + +# Redis (if REDIS_URL is set) +redis-cli -u "$REDIS_URL" ping 2>/dev/null +``` + +### 2. Report Issues + +If any checks fail, display a clear report: + +```markdown +## Pre-flight Check Results + +| Check | Status | Action Required | +|-------|--------|-----------------| +| Frontend .env | MISSING | Create frontend/.env.development | +| Port 8000 | IN USE | Kill process or use --port 8001 | +| node_modules | MISSING | Run: cd frontend && npm install | +| PostgreSQL | OK | - | +``` + +If there are blocking issues, ask the user how to proceed. + +### 3. Start Servers + +Start both servers in the background: + +```bash +# Start backend first (frontend depends on it) +cd backend && uv run uvicorn app.main:app --reload --port $BACKEND_PORT 2>&1 & + +# Wait for backend to be ready +sleep 3 + +# Start frontend +cd frontend && npm run dev 2>&1 & +``` + +### 4. Verify and Display Status + +Wait for both servers to be ready, then display: + +```markdown +## Dev Environment Ready + +| Service | URL | Status | +|---------|-----|--------| +| Frontend | http://localhost:5173/ | Running | +| Backend API | http://localhost:8000/ | Running | +| Backend Docs | http://localhost:8000/docs | Running | +| PostgreSQL | localhost:5432 | Connected | +| Redis | localhost:6379 | Connected | + +**Quick Links:** +- App: http://localhost:5173/ +- API Docs: http://localhost:8000/docs +- Health Check: http://localhost:8000/api/health +``` + +### 5. Stop Command + +When `stop` is requested: +```bash +pkill -f "uvicorn app.main:app" +pkill -f "vite" +``` + +### 6. Status Command + +When `status` is requested, check running processes and display current state. + +## Common Gotchas + +The skill should check for and warn about: + +1. **Port mismatch** - Frontend .env pointing to wrong backend port +2. **Missing OAuth config** - Google/Discord credentials not set +3. **Database not migrated** - Check if alembic migrations are pending +4. **Redis not running** - Socket.IO requires Redis for pub/sub +5. **Old processes** - Zombie uvicorn/vite processes from crashed sessions +6. **TypeScript errors** - Run `npm run typecheck` before starting + +## Environment Variable Reference + +### Frontend (.env.development) +```bash +VITE_API_BASE_URL=http://localhost:8000 +VITE_WS_URL=http://localhost:8000 +VITE_OAUTH_REDIRECT_URI=http://localhost:5173/auth/callback +``` + +### Backend (.env) +```bash +DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/mantimon +REDIS_URL=redis://localhost:6379/0 +JWT_SECRET=your-secret-key-at-least-32-characters +GOOGLE_CLIENT_ID=optional +GOOGLE_CLIENT_SECRET=optional +DISCORD_CLIENT_ID=optional +DISCORD_CLIENT_SECRET=optional +``` diff --git a/.claude/skills/dev-server/preflight.sh b/.claude/skills/dev-server/preflight.sh new file mode 100755 index 0000000..abe0987 --- /dev/null +++ b/.claude/skills/dev-server/preflight.sh @@ -0,0 +1,164 @@ +#!/bin/bash +# Pre-flight checks for Mantimon TCG dev environment +# Runs validation checks before starting dev servers + +PROJECT_ROOT="$(cd "$(dirname "$0")/../../.." && pwd)" +FRONTEND_DIR="$PROJECT_ROOT/frontend" +BACKEND_DIR="$PROJECT_ROOT/backend" + +# Colors for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +NC='\033[0m' # No Color + +echo "Running pre-flight checks..." +echo "" + +ISSUES=0 +WARNINGS=0 + +# Check function +check() { + local name="$1" + local status="$2" + local message="$3" + + if [ "$status" = "OK" ]; then + echo -e " ${GREEN}✓${NC} $name" + elif [ "$status" = "WARN" ]; then + echo -e " ${YELLOW}⚠${NC} $name: $message" + ((WARNINGS++)) + else + echo -e " ${RED}✗${NC} $name: $message" + ((ISSUES++)) + fi +} + +echo "=== Environment Files ===" + +# Frontend .env.development +if [ -f "$FRONTEND_DIR/.env.development" ]; then + # Check for required vars + if grep -q "VITE_API_BASE_URL" "$FRONTEND_DIR/.env.development"; then + check "Frontend .env.development" "OK" + else + check "Frontend .env.development" "FAIL" "Missing VITE_API_BASE_URL" + fi +else + check "Frontend .env.development" "FAIL" "File not found" +fi + +# Backend .env (optional - might use system env) +if [ -f "$BACKEND_DIR/.env" ]; then + check "Backend .env" "OK" +else + check "Backend .env" "WARN" "No .env file (using system environment?)" +fi + +echo "" +echo "=== Dependencies ===" + +# Frontend node_modules +if [ -d "$FRONTEND_DIR/node_modules" ]; then + check "Frontend node_modules" "OK" +else + check "Frontend node_modules" "FAIL" "Run: cd frontend && npm install" +fi + +# Backend venv +if [ -d "$BACKEND_DIR/.venv" ]; then + check "Backend .venv" "OK" +else + check "Backend .venv" "FAIL" "Run: cd backend && uv sync" +fi + +echo "" +echo "=== Port Availability ===" + +# Check port 8000 +if lsof -i :8000 2>/dev/null | grep -q LISTEN; then + PID=$(lsof -t -i :8000 2>/dev/null | head -1) + PROC=$(ps -p $PID -o comm= 2>/dev/null || echo "unknown") + check "Port 8000" "WARN" "In use by $PROC (PID $PID)" +else + check "Port 8000" "OK" +fi + +# Check port 8001 +if lsof -i :8001 2>/dev/null | grep -q LISTEN; then + PID=$(lsof -t -i :8001 2>/dev/null | head -1) + PROC=$(ps -p $PID -o comm= 2>/dev/null || echo "unknown") + check "Port 8001" "WARN" "In use by $PROC (PID $PID)" +else + check "Port 8001" "OK" +fi + +# Check frontend ports +for PORT in 5173 3000 3001; do + if lsof -i :$PORT 2>/dev/null | grep -q LISTEN; then + check "Port $PORT" "WARN" "In use (Vite will try next port)" + break + fi +done +check "Frontend ports" "OK" + +echo "" +echo "=== Services ===" + +# PostgreSQL +if command -v pg_isready &> /dev/null; then + if pg_isready -q 2>/dev/null; then + check "PostgreSQL" "OK" + else + check "PostgreSQL" "WARN" "Not running or not accessible" + fi +else + check "PostgreSQL" "WARN" "pg_isready not found" +fi + +# Redis +if command -v redis-cli &> /dev/null; then + if redis-cli ping 2>/dev/null | grep -q PONG; then + check "Redis" "OK" + else + check "Redis" "WARN" "Not running" + fi +else + check "Redis" "WARN" "redis-cli not found" +fi + +echo "" +echo "=== Configuration Consistency ===" + +# Check if frontend API URL matches an available port +if [ -f "$FRONTEND_DIR/.env.development" ]; then + API_URL=$(grep "VITE_API_BASE_URL" "$FRONTEND_DIR/.env.development" | cut -d= -f2) + API_PORT=$(echo "$API_URL" | grep -oE '[0-9]+$') + + if [ -n "$API_PORT" ]; then + if lsof -i :$API_PORT 2>/dev/null | grep -q LISTEN; then + # Check if it's our backend + if curl -s "http://localhost:$API_PORT/docs" 2>/dev/null | grep -q "swagger"; then + check "API URL -> Backend" "OK" + else + check "API URL -> Backend" "WARN" "Port $API_PORT in use but not our backend" + fi + else + check "API URL -> Backend" "WARN" "Backend not running on port $API_PORT" + fi + fi +fi + +echo "" +echo "=== Summary ===" +if [ $ISSUES -gt 0 ]; then + echo -e "${RED}$ISSUES issue(s) found that need to be fixed${NC}" + exit 1 +elif [ $WARNINGS -gt 0 ]; then + echo -e "${YELLOW}$WARNINGS warning(s) - servers may still start${NC}" + exit 0 +else + echo -e "${GREEN}All checks passed!${NC}" + exit 0 +fi diff --git a/.claude/skills/frontend-phase/SKILL.md b/.claude/skills/frontend-phase/SKILL.md new file mode 100644 index 0000000..4b60f1a --- /dev/null +++ b/.claude/skills/frontend-phase/SKILL.md @@ -0,0 +1,241 @@ +# Frontend Phase Workflow Skill + +Manage the phased frontend development workflow for Mantimon TCG. + +## Usage + +``` +/frontend-phase # Show current phase status and next task +/frontend-phase status # Same as above +/frontend-phase next # Show detailed info about next incomplete task +/frontend-phase start # Mark task as in-progress +/frontend-phase done # Mark task as complete (with tests) +/frontend-phase plan # Create detailed plan for next NOT_STARTED phase +``` + +## Files + +- **Master Plan:** `frontend/PROJECT_PLAN_FRONTEND.json` +- **Phase Plans:** `frontend/project_plans/PHASE_FN_*.json` + +## Workflow + +### Starting a New Phase + +1. Run `/frontend-phase plan` to create the detailed plan for the next NOT_STARTED phase +2. Review and adjust the generated plan +3. Run `/frontend-phase next` to see the first task + +### Working on Tasks + +1. Run `/frontend-phase next` to see task details +2. Run `/frontend-phase start ` to mark it in-progress +3. Implement the task following the details in the plan +4. Write tests with docstrings explaining "what" and "why" +5. Run `/frontend-phase done ` when complete with passing tests + +### Completing a Phase + +When all tasks are complete: +1. Update master plan status to "COMPLETE" +2. Add completedDate +3. Increment completedPhases count + +## Instructions + +When `/frontend-phase` or `/frontend-phase status` is invoked: + +1. **Read Master Plan** + ``` + frontend/PROJECT_PLAN_FRONTEND.json + ``` + +2. **Find Current Phase** + - Look for first phase with `status: "in_progress"` or `status: "IN_PROGRESS"` + - If none, look for first phase with `status: "NOT_STARTED"` + +3. **Read Phase Plan** (if exists) + ``` + frontend/project_plans/PHASE_FN_*.json + ``` + +4. **Display Status** + ``` + ## Phase FN: [Phase Name] + + Status: IN_PROGRESS + Progress: X/Y tasks complete + + ### Completed Tasks + - [x] F0-001: Task name + - [x] F0-002: Task name + + ### Next Task + **F0-003: Task name** + Category: components | Priority: 3 + Dependencies: [F0-001, F0-002] + + [Brief description from plan] + + Run `/frontend-phase next` for full details. + ``` + +--- + +When `/frontend-phase next` is invoked: + +1. Find the first task where `completed: false` and all dependencies are met +2. Display full task details: + ``` + ## F0-003: Task Name + + **Category:** components + **Priority:** 3 + **Dependencies:** F0-001, F0-002 (all complete) + + ### Description + [Full description from plan] + + ### Implementation Details + - Detail 1 + - Detail 2 + - Detail 3 + + ### Files to Create/Modify + - `src/components/Foo.vue` (create) + - `src/App.vue` (modify) + + ### Notes + [Any notes from the plan] + + --- + Run `/frontend-phase start F0-003` to begin work. + ``` + +--- + +When `/frontend-phase start ` is invoked: + +1. Verify task exists and dependencies are met +2. Log that work is starting (no file modification needed) +3. Display the task details for reference +4. Create Claude Code tasks using TaskCreate if task has multiple sub-items + +--- + +When `/frontend-phase done ` is invoked: + +1. Verify tests exist and pass for the task (run `npm run test`) +2. Update the phase plan JSON: + - Set `completed: true` + - Set `tested: true` +3. Update `completedTasks` count in meta +4. Check if phase is complete (all tasks done) +5. If phase complete, prompt to update master plan + +--- + +When `/frontend-phase plan` is invoked: + +1. Find next NOT_STARTED phase in master plan +2. Read existing phase plans for format reference (check `frontend/project_plans/`) +3. Generate detailed plan based on: + - Phase description and deliverables from master plan + - Architecture patterns from `frontend/CLAUDE.md` + - Existing code patterns in the codebase + - Site plan and design system from master plan +4. Create `frontend/project_plans/` directory if it doesn't exist +5. Write to `frontend/project_plans/PHASE_FN_[name].json` +6. Update master plan phase status to "in_progress" + +## Task Schema + +```json +{ + "id": "F0-001", + "name": "Short task name", + "description": "What this task accomplishes", + "category": "setup|components|composables|stores|pages|game|tests|styling", + "priority": 1, + "completed": false, + "tested": false, + "dependencies": ["F0-000"], + "files": [ + {"path": "src/components/Foo.vue", "status": "create|modify"} + ], + "details": [ + "Specific implementation step 1", + "Specific implementation step 2" + ], + "estimatedHours": 2, + "notes": "Optional implementation notes" +} +``` + +## Phase Plan Schema + +```json +{ + "meta": { + "phaseId": "PHASE_F0", + "name": "Project Foundation", + "version": "1.0.0", + "created": "2026-01-30", + "lastUpdated": "2026-01-30", + "totalTasks": 8, + "completedTasks": 0, + "status": "in_progress" + }, + "tasks": [ + // Array of task objects + ] +} +``` + +## Categories + +Frontend-specific task categories: + +| Category | Description | +|----------|-------------| +| `setup` | Project scaffolding, config, tooling | +| `components` | Vue components (UI, cards, game) | +| `composables` | Vue composables (useAuth, useDeck, etc.) | +| `stores` | Pinia stores | +| `pages` | Route page components | +| `game` | Phaser scenes, game objects, animations | +| `tests` | Test files and testing infrastructure | +| `styling` | Tailwind config, CSS, design system | +| `api` | API client, Socket.IO client | + +## Rules + +1. **Dependencies First** - Never start a task with incomplete dependencies +2. **Tests Required** - Every task must have tests before marking complete +3. **Docstrings Required** - Test docstrings explain "what" and "why" +4. **Commit Approval** - Never commit without user approval +5. **One Task at a Time** - Focus on completing current task before starting next +6. **Update Plans** - Keep plan files in sync with actual progress +7. **Mobile-First** - All UI work follows mobile-first responsive design +8. **TypeScript Strict** - No `any` types, explicit typing required + +## Test Command + +Before marking a task complete: +```bash +cd frontend && npm run test +cd frontend && npm run lint +cd frontend && npm run typecheck +``` + +## Memory Integration + +After completing a task or phase, consider storing learnings: +```bash +python ~/.claude/skills/memorygraph/client.py store \ + --type solution \ + --title "Completed PHASE_F0 F0-003" \ + --content "Implemented Vue Router with auth guards..." \ + --tags "mantimon,frontend,vue-router" \ + --importance 0.6 +``` diff --git a/frontend/.env.development b/frontend/.env.development index 4b8d81b..9c487dc 100644 --- a/frontend/.env.development +++ b/frontend/.env.development @@ -2,10 +2,10 @@ # These values are used when running `npm run dev` # Backend API base URL (FastAPI server) -VITE_API_BASE_URL=http://localhost:8000 +VITE_API_BASE_URL=http://localhost:8001 # WebSocket URL (Socket.IO server - same as API in development) -VITE_WS_URL=http://localhost:8000 +VITE_WS_URL=http://localhost:8001 # OAuth redirect URI (must match OAuth provider configuration) -VITE_OAUTH_REDIRECT_URI=http://localhost:5173/auth/callback +VITE_OAUTH_REDIRECT_URI=http://localhost:3001/auth/callback