mantimon-tcg/.claude/skills/dev-server/SKILL.md

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

# Check port availability
lsof -i :8000 2>/dev/null | grep LISTEN
lsof -i :5173 2>/dev/null | grep LISTEN

Dependencies

Verify dependencies are installed:

# 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:

# 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:

## 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:

# 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:

## 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:

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)

VITE_API_BASE_URL=http://localhost:8000
VITE_WS_URL=http://localhost:8000
VITE_OAUTH_REDIRECT_URI=http://localhost:5173/auth/callback

Backend (.env)

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