copilot-setup.yml

name: Setup Copilot Development Environment

# This workflow can be triggered manually to set up or validate the Copilot development environment
# It serves as a guide for what gets configured when using GitHub Copilot with this repository

on:
  workflow_dispatch:
    inputs:
      validate_only:
        description: 'Only validate setup without making changes'
        required: false
        type: boolean
        default: true

permissions:
  contents: read

jobs:
  setup-guide:
    name: Copilot Environment Setup Guide
    runs-on: ubuntu-latest
    permissions:
      contents: read
    
    steps:
      - name: Harden the runner
        uses: step-security/harden-runner@fa2e9d605c4eeb9fcad4c99c224cee0c6c7f3594 # v2.16.0
        with:
          egress-policy: audit

      - name: Checkout repository
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

      - name: Setup Node.js
        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
        with:
          node-version: '25'
          cache: 'npm'

      - name: Cache dependencies
        uses: actions/cache@cdf6c1fa76f9f475f3d7449005a359c84ca0f306 # v5.0.3
        with:
          path: ~/.npm
          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-node-

      - name: Display Copilot Configuration
        run: |
          echo "## GitHub Copilot Development Environment"
          echo ""
          echo "### Configuration Files"
          echo "- ✅ .github/copilot-instructions.md - Coding guidelines for Copilot"
          echo "- ✅ .github/copilot-setup-steps.yml - Pre-installation steps and MCP servers"
          echo "- ✅ .github/mcp-config.json - MCP server configuration"
          echo "- ✅ .devcontainer/devcontainer.json - Dev container with Copilot extensions"
          echo ""
          echo "### Available MCP Servers"
          echo ""
          echo "The following Model Context Protocol servers are configured:"
          echo ""
          
      - name: List MCP Servers
        run: |
          echo "#### 🗂️ Filesystem Server"
          echo "- Provides secure file access to project directories"
          echo "- Allows Copilot to read/write code files"
          echo "- Command: @modelcontextprotocol/server-filesystem"
          echo ""
          echo "#### 🐙 GitHub Server"
          echo "- Access to repository data, issues, and PRs"
          echo "- Enables Copilot to understand project context"
          echo "- Command: @modelcontextprotocol/server-github"
          echo ""
          echo "#### 📚 Git Server"
          echo "- Git operations and repository history"
          echo "- Helps understand code evolution"
          echo "- Command: @modelcontextprotocol/server-git"
          echo ""
          echo "#### 🧠 Memory Server"
          echo "- Maintains context across conversations"
          echo "- Remembers previous interactions"
          echo "- Command: @modelcontextprotocol/server-memory"
          echo ""
          echo "#### 🔍 Brave Search Server (Optional)"
          echo "- Searches documentation and best practices"
          echo "- Requires BRAVE_API_KEY environment variable"
          echo "- Command: @modelcontextprotocol/server-brave-search"
          echo ""
          echo "#### 🎭 Playwright Server"
          echo "- Browser automation for testing"
          echo "- Useful for debugging and E2E tests"
          echo "- Command: @modelcontextprotocol/server-playwright"

      - name: Cache apt packages
        uses: actions/cache@cdf6c1fa76f9f475f3d7449005a359c84ca0f306 # v5.0.3
        with:
          path: /var/cache/apt/archives
          key: ${{ runner.os }}-apt-${{ hashFiles('.github/workflows/copilot-setup.yml') }}
          restore-keys: |
            ${{ runner.os }}-apt-

      - name: Install System Dependencies
        run: |
          echo "### Installing System Dependencies"
          sudo apt-get update || exit 1
          sudo apt-get install -y build-essential || exit 1
          sudo apt-get install -y xvfb libgtk2.0-0 libgtk-3-0 libgbm-dev libnotify-dev libnss3 libxss1 libasound2 libxtst6 xauth || exit 1
          sudo apt-get install -y graphviz || exit 1
          echo "✅ System dependencies installed"

      - name: Install Node Dependencies
        run: |
          echo "### Installing Node.js Dependencies"
          npm ci --ignore-scripts
          echo "✅ Node.js dependencies installed"

      - name: Build Project
        run: |
          echo "### Building TypeScript Project"
          npm run build
          echo "✅ Project built successfully"

      - name: Validate TypeScript
        run: |
          echo "### Validating TypeScript Configuration"
          npx tsc --noEmit
          echo "✅ TypeScript validation passed"

      - name: Check Linting
        run: |
          echo "### Checking ESLint Configuration"
          npm run lint -- --max-warnings 0 || echo "⚠️ Linting has warnings"

      - name: Test MCP Server Availability
        run: |
          echo "### Testing MCP Server Availability"
          echo "Note: MCP servers are installed on-demand when Copilot needs them"
          echo ""
          echo "Verifying key MCP server packages:"
          for pkg in filesystem github git memory playwright; do
            if npm view @modelcontextprotocol/server-$pkg version > /dev/null 2>&1; then
              echo "✅ @modelcontextprotocol/server-$pkg is available"
            else
              echo "⚠️ @modelcontextprotocol/server-$pkg not found"
            fi
          done

      - name: Display Setup Summary
        run: |
          echo ""
          echo "## 🎉 Copilot Environment Setup Complete!"
          echo ""
          echo "### Quick Start with Copilot"
          echo ""
          echo "1. **Use GitHub Codespaces:**"
          echo "   - Click 'Code' → 'Create codespace on main'"
          echo "   - Copilot extensions are pre-installed"
          echo "   - Environment is automatically configured"
          echo ""
          echo "2. **Use Local Development:**"
          echo "   - Open repository in VS Code"
          echo "   - Install GitHub Copilot extension"
          echo "   - Open .github/copilot-instructions.md for guidelines"
          echo ""
          echo "3. **Use Copilot Chat:**"
          echo "   - Ask questions about the codebase"
          echo "   - Get code suggestions"
          echo "   - Debug issues with AI assistance"
          echo ""
          echo "### Key Features"
          echo ""
          echo "✅ Intelligent code completion with context"
          echo "✅ Inline documentation and examples"
          echo "✅ Security-first coding suggestions"
          echo "✅ TypeScript strict mode support"
          echo "✅ PixiJS game development assistance"
          echo "✅ Test generation with Vitest/Cypress"
          echo "✅ React 19 best practices"
          echo ""
          echo "### MCP Servers Enhance Copilot With:"
          echo ""
          echo "🗂️ Direct file system access"
          echo "🐙 GitHub repository context"
          echo "📚 Git history understanding"
          echo "🧠 Conversation memory"
          echo "🔍 Documentation search (with API key)"
          echo "🎭 Browser automation tools"
          echo ""
          echo "For more information, see:"
          echo "- .github/copilot-instructions.md"
          echo "- .github/copilot-setup-steps.yml"
          echo "- .github/mcp-config.json"

      - name: Create Setup Report
        run: |
          cat > setup-report.md << 'EOF'
          # Copilot Development Environment Setup Report
          
          ## ✅ Configuration Status
          
          ### Files Present
          - [x] `.github/copilot-instructions.md` - Coding guidelines
          - [x] `.github/copilot-setup-steps.yml` - Setup configuration
          - [x] `.github/mcp-config.json` - MCP server configuration
          - [x] `.devcontainer/devcontainer.json` - Dev container configuration
          
          ### MCP Servers Configured
          - [x] Filesystem Server - File access
          - [x] GitHub Server - Repository context
          - [x] Git Server - Version control
          - [x] Memory Server - Context persistence
          - [x] Playwright Server - Browser automation
          - [ ] Brave Search Server - Requires API key
          
          ### System Dependencies
          - [x] Node.js 25
          - [x] Build tools
          - [x] Display server (Xvfb)
          - [x] Cypress dependencies
          - [x] Graphics tools
          
          ### Project Dependencies
          - [x] NPM packages installed
          - [x] TypeScript compiled
          - [x] Build successful
          
          ## 🚀 Usage Instructions
          
          ### For GitHub Codespaces
          1. Click "Code" button
          2. Select "Codespaces" tab
          3. Click "Create codespace on main"
          4. Wait for automatic setup
          5. Start coding with Copilot!
          
          ### For Local Development
          1. Clone the repository
          2. Open in VS Code
          3. Install GitHub Copilot extension
          4. Run `npm install`
          5. Run `npm run dev`
          
          ### MCP Servers
          MCP servers are automatically loaded when you use GitHub Copilot in:
          - VS Code with Copilot extension
          - GitHub Codespaces
          - Copilot Chat
          
          ## 📚 Documentation
          
          - **Coding Guidelines**: `.github/copilot-instructions.md`
          - **Setup Steps**: `.github/copilot-setup-steps.yml`
          - **MCP Config**: `.github/mcp-config.json`
          - **Dev Container**: `.devcontainer/devcontainer.json`
          
          ## 🔒 Security Notes
          
          - All MCP servers use read-only access where possible
          - Filesystem server restricted to project directories
          - No secrets stored in configuration
          - GITHUB_TOKEN and BRAVE_API_KEY use environment variables
          
          ## 🎮 Stack-Specific Features
          
          ### React + TypeScript
          - Strict type checking
          - Component best practices
          - Hook usage patterns
          
          ### PixiJS
          - Game loop patterns
          - Sprite management
          - Performance optimization
          
          ### Testing
          - Vitest unit tests
          - Cypress E2E tests
          - 80% coverage target
          
          EOF
          
          cat setup-report.md

      - name: Upload Setup Report
        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
        with:
          name: copilot-setup-report
          path: setup-report.md
          if-no-files-found: error