Skip to content

QUICKSTART.md

Latest commit

 

History

History
211 lines (147 loc) · 3.78 KB

QUICKSTART.md

File metadata and controls

211 lines (147 loc) · 3.78 KB

Quick Start Guide

Getting Started

1. Prerequisites

Install Node.js

# Check Node.js version (requires >= 18.0.0)
node --version

# If not installed or version is too old, visit https://nodejs.org/ to download

Install GitHub Copilot CLI

# Method 1: Using npm (recommended)
npm install -g @github/copilot-cli

# Method 2: Using GitHub CLI extension
gh extension install github/gh-copilot

# Login authentication
copilot auth login

# Verify installation
copilot --version

Important: Make sure you have a valid GitHub Copilot subscription!

2. Clone and Install Project

# Navigate to project directory
cd cyber-chess-roast

# Install dependencies
npm install

3. Configure Environment Variables (Optional)

# Copy example configuration
cp .env.example .env

# Edit .env file if needed
# In most cases, default configuration will work

4. Start Application

# Start development server (frontend + backend)
npm run dev

Wait a few seconds until you see:

✅ Copilot commentator ready!
🚀 Server running at http://localhost:3000
⚡ Vite dev server running at http://localhost:5173

5. Open Browser

Visit: http://localhost:5173

You should see the chess board and commentary panel!

6. Start Playing

  1. Click a piece (such as a white pawn)
  2. Click the target square to move
  3. AI commentator will analyze and comment on every move in real-time!

🎯 Common Troubleshooting

Issue 1: "copilot: command not found"

Solution:

# Check if copilot CLI is in PATH
which copilot       # macOS/Linux
where copilot       # Windows

# If not found, reinstall
npm install -g @github/copilot-cli

Issue 2: "Copilot authentication required"

Solution:

# Re-login
copilot auth logout
copilot auth login

# Check status
copilot auth status

Issue 3: Port Already in Use

Solution:

# Edit .env file to change port
echo "PORT=3001" >> .env

# Or kill the process using the port
# Windows PowerShell:
Stop-Process -Id (Get-NetTCPConnection -LocalPort 3000).OwningProcess -Force

# macOS/Linux:
lsof -ti:3000 | xargs kill -9

Issue 4: WebSocket Connection Failed

Checklist:

  • Is backend server running?
  • Is firewall blocking the connection?
  • Are there any errors in browser console?

Solution:

# Restart development server
Ctrl+C  # Stop
npm run dev  # Restart

Issue 5: Dependency Installation Failed

Solution:

# Clear npm cache
npm cache clean --force

# Delete node_modules and package-lock.json
rm -rf node_modules package-lock.json

# Reinstall
npm install

📝 Development Tips

Debug Mode

# Enable verbose logging
LOG_LEVEL=debug npm run dev:server

# Start frontend in another terminal
npm run dev:client

Run Frontend Only (with mock data)

npm run dev:client

Run Backend Only

npm run dev:server

View Real-time Logs

Backend logs will show:

  • Copilot SDK initialization status
  • Processing of each move
  • AI commentary generation process
  • WebSocket connection status

🚀 Production Deployment

# 1. Build project
npm run build

# 2. Start production server
npm start

# 3. Visit http://localhost:3000

💡 Usage Tips

  1. At least 5 moves: Required to generate game summary
  2. Observe phases: AI automatically recognizes opening/middlegame/endgame
  3. Streaming commentary: Wait for AI to complete commentary on one move before making the next
  4. Reset game: Can restart at any time

🎮 Shortcuts (Future Feature)

  • R - Reset game
  • U - Undo last move
  • S - Generate summary
  • ? - Show help

Enjoy the fun of AI commentary! ♟️🤖

For questions, please see the complete README.md or submit an Issue.