09844cbf3f
- 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>
163 lines
4.0 KiB
Markdown
163 lines
4.0 KiB
Markdown
# 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
|
|
```
|