deploy.yml

name: Deploy Documentation

on:
  push:
    branches:
      - main  # Auto-deploy to dev
    tags:
      - 'v*'  # Deploy to prod on version tags
  pull_request:
    branches:
      - main  # Validate PRs
  workflow_dispatch:  # Manual trigger
    inputs:
      environment:
        description: 'Environment to deploy to'
        required: true
        type: choice
        options:
          - dev
          - prod

# Cancel in-progress runs for same branch
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

# Required permissions for GitHub Deployments and Cloudflare Pages
permissions:
  contents: write  # Changed from read to write for commit comments
  deployments: write
  pull-requests: write

jobs:
  # Build unified documentation (runs for all triggers)
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout capiscio-docs
        uses: actions/checkout@v4
        with:
          path: capiscio-docs
          fetch-depth: 0  # Full history for git-revision-date plugin
      
      - name: Checkout capiscio-core
        uses: actions/checkout@v4
        with:
          repository: capiscio/capiscio-core
          path: capiscio-core
          fetch-depth: 0
          token: ${{ secrets.GITHUB_TOKEN }}

      - name: Checkout capiscio-sdk-python
        uses: actions/checkout@v4
        with:
          repository: capiscio/capiscio-sdk-python
          path: capiscio-sdk-python
          fetch-depth: 0
          token: ${{ secrets.GITHUB_TOKEN }}

      - name: Checkout capiscio-python
        uses: actions/checkout@v4
        with:
          repository: capiscio/capiscio-python
          path: capiscio-python
          fetch-depth: 0
          token: ${{ secrets.GITHUB_TOKEN }}

      - name: Checkout capiscio-node
        uses: actions/checkout@v4
        with:
          repository: capiscio/capiscio-node
          path: capiscio-node
          fetch-depth: 0
          token: ${{ secrets.GITHUB_TOKEN }}

      - name: Checkout validate-a2a
        uses: actions/checkout@v4
        with:
          repository: capiscio/validate-a2a
          path: validate-a2a
          fetch-depth: 0
          token: ${{ secrets.GITHUB_TOKEN }}

      - name: Checkout capiscio-rfcs
        uses: actions/checkout@v4
        with:
          repository: capiscio/capiscio-rfcs
          path: capiscio-rfcs
          fetch-depth: 0
          token: ${{ secrets.GITHUB_TOKEN }}

      - name: Checkout capiscio-mcp-python
        uses: actions/checkout@v4
        with:
          repository: capiscio/capiscio-mcp-python
          path: capiscio-mcp-python
          fetch-depth: 0
          token: ${{ secrets.GITHUB_TOKEN }}
      
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
          cache: 'pip'
      
      - name: Install dependencies
        run: |
          # Install capiscio-sdk-python with all its dependencies (pydantic, etc.)
          # The [dev] extra ensures all optional deps are available for mkdocstrings
          pip install -e "capiscio-sdk-python[dev]"
          
          # Now install docs requirements
          cd capiscio-docs
          pip install -r requirements-docs.txt
      
      - name: Build documentation
        run: |
          cd capiscio-docs
          mkdocs build --strict --verbose
        env:
          ENABLE_MONOREPO: 'true'
          ENABLE_GIT_DATES: 'true'
      
      - name: Copy _redirects to site root
        run: |
          cp capiscio-docs/docs/_redirects capiscio-docs/site/_redirects
      
      - name: Create _headers file for Cloudflare
        run: |
          cd capiscio-docs/site
          cat > _headers << 'EOF'
          /*
            X-Frame-Options: DENY
            X-Content-Type-Options: nosniff
            Referrer-Policy: strict-origin-when-cross-origin
            Permissions-Policy: geolocation=(), microphone=(), camera=()
            Cache-Control: public, max-age=3600, must-revalidate
          
          /*.html
            Cache-Control: public, max-age=600, must-revalidate
          
          /assets/*
            Cache-Control: public, max-age=31536000, immutable
          
          /sitemap.xml
            Cache-Control: public, max-age=3600
          EOF
      
      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: documentation
          path: capiscio-docs/site/
          retention-days: 7
  
  # Deploy to DEV (automatic on main push or manual)
  deploy-dev:
    needs: build
    if: |
      (github.event_name == 'push' && github.ref == 'refs/heads/main') ||
      (github.event_name == 'workflow_dispatch' && inputs.environment == 'dev')
    runs-on: ubuntu-latest
    steps:
      - name: Download artifact
        uses: actions/download-artifact@v4
        with:
          name: documentation
          path: site/
      
      - name: Block search engines (Dev only)
        run: |
          cd site
          # Override robots.txt to block all crawlers
          cat > robots.txt << 'EOF'
          User-agent: *
          Disallow: /
          EOF
          
          # Add X-Robots-Tag header to prevent indexing
          cat > _headers << 'EOF'
          /*
            X-Frame-Options: DENY
            X-Content-Type-Options: nosniff
            Referrer-Policy: strict-origin-when-cross-origin
            Permissions-Policy: geolocation=(), microphone=(), camera=()
            X-Robots-Tag: noindex, nofollow
            Cache-Control: public, max-age=600, must-revalidate
          
          /*.html
            Cache-Control: public, max-age=300, must-revalidate
          
          /assets/*
            Cache-Control: public, max-age=31536000, immutable
          EOF
      
      - name: Deploy to Cloudflare Pages (Dev)
        uses: cloudflare/pages-action@v1
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          projectName: capiscio-docs-dev
          directory: site
          gitHubToken: ${{ secrets.GITHUB_TOKEN }}
          branch: main
          wranglerVersion: '3'
      
      - name: Comment on commit
        if: github.event_name == 'push'
        uses: actions/github-script@v7
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            const sha = context.sha;
            const message = `## 🚀 Dev Deployment Complete
            
            📍 **Environment:** Development
            🔗 **URL:** https://dev-docs.capisc.io
            📝 **Commit:** ${sha.substring(0, 7)}
            
            > Auto-deployed from main branch`;
            
            github.rest.repos.createCommitComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              commit_sha: sha,
              body: message
            });
  
  # Deploy to PROD (on version tags or manual)
  deploy-prod:
    needs: build
    if: |
      (github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')) ||
      (github.event_name == 'workflow_dispatch' && inputs.environment == 'prod')
    runs-on: ubuntu-latest
    steps:
      - name: Download artifact
        uses: actions/download-artifact@v4
        with:
          name: documentation
          path: site/
      
      - name: Deploy to Cloudflare Pages (Production)
        uses: cloudflare/pages-action@v1
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          projectName: capiscio-docs
          directory: site
          gitHubToken: ${{ secrets.GITHUB_TOKEN }}
          branch: main
          wranglerVersion: '3'
      
      - name: Create release comment
        if: startsWith(github.ref, 'refs/tags/v')
        uses: actions/github-script@v7
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            const tag = context.ref.replace('refs/tags/', '');
            const message = `## 🎉 Production Deployment Complete
            
            📍 **Environment:** Production
            🔗 **URL:** https://docs.capisc.io
            🏷️ **Version:** ${tag}
            
            Documentation has been deployed to production!`;
            
            // Create a release if it doesn't exist
            try {
              await github.rest.repos.createRelease({
                owner: context.repo.owner,
                repo: context.repo.repo,
                tag_name: tag,
                name: `Documentation ${tag}`,
                body: message,
                draft: false,
                prerelease: false
              });
            } catch (error) {
              console.log('Release might already exist:', error.message);
            }
      
      - name: Check links (Production only)
        run: |
          pip install linkchecker
          # Wait for propagation
          sleep 30
          linkchecker https://docs.capisc.io --no-warnings --ignore-url=/search || true
        continue-on-error: true
  
  # PR Validation (no deployment)
  validate-pr:
    needs: build
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - name: Download artifact
        uses: actions/download-artifact@v4
        with:
          name: documentation
          path: site/
      
      - name: Check for broken links
        run: |
          pip install linkchecker
          cd site
          python -m http.server 8000 &
          sleep 5
          linkchecker http://localhost:8000 --no-warnings --check-extern || true
        continue-on-error: true
      
      - name: Validate build
        run: |
          cd site
          # Check that critical files exist
          test -f index.html
          test -f sitemap.xml
          test -f robots.txt
          echo "✅ Build validation passed"
      
      - name: Add validation comment
        uses: actions/github-script@v7
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            const prNumber = context.payload.pull_request.number;
            
            const comment = `## ✅ Documentation Build Successful
            
            The documentation build completed successfully and passed validation checks.
            
            - ✅ Build completed without errors
            - ✅ Critical files present (index.html, sitemap.xml, robots.txt)
            - ✅ Link validation completed
            
            > This PR will deploy to **dev-docs.capisc.io** when merged to main.
            `;
            
            github.rest.issues.createComment({
              issue_number: prNumber,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: comment
            });