feat: add PR preview deployments via Cloudflare Pages

.github/workflows/pages-preview.yml

@@ -0,0 +1,276 @@
+name: PR Preview
+
+on:
+  pull_request:
+    branches: [main]
+    types: [opened, synchronize, reopened, closed]
+    paths:
+      - "docs/**"
+      - "site/**"
+      - "mkdocs.yml"
+      - "src/ai_company/**"
+      - ".github/workflows/pages-preview.yml"
+
+permissions: {}
+
+concurrency:
+  group: "pages-preview-${{ github.event.pull_request.number }}"
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build Preview
+    if: github.event.action != 'closed'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          persist-credentials: false
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      # --- MkDocs (documentation at /docs) ---
+      - name: Set up Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.14"
+          allow-prereleases: true
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@6b9c6063abd6010835644d4c2e1bef4cf5cd0fca # v6.0.1
+
+      - name: Install docs dependencies
+        run: uv sync --group docs --no-dev
+
+      - name: Build MkDocs
+        run: uv run mkdocs build --strict
+
+      # --- Astro (landing page at /) ---
+      - name: Set up Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: "22"
+
+      - name: Install Astro dependencies
+        working-directory: site
+        run: npm ci
+
+      - name: Build Astro
+        working-directory: site
+        run: npm run build
+
+      # --- Merge outputs ---
+      - name: Merge Astro + MkDocs into final output
+        run: |
+          # Guard against Astro accidentally producing a docs/ route
+          if [ -d "site/dist/docs" ]; then
+            echo "::error::Astro output contains 'docs/' directory which would overwrite MkDocs output"
+            exit 1
+          fi
+          # Astro output goes to root (use /. to avoid glob edge cases)
+          cp -r site/dist/. _site/
+          # MkDocs output is already at _site/docs/ from the build step
+
+      # --- Inject preview banner ---
+      - name: Inject preview banner
+        env:
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: |
+          python3 << 'PYEOF'
+          import os, pathlib, re
+          from datetime import datetime, timezone
+
+          pr_number = os.environ["PR_NUMBER"]
+          short_sha = os.environ["HEAD_SHA"][:7]
+          build_iso = datetime.now(timezone.utc).isoformat()
+
+          style = (
+              "background:linear-gradient(90deg,#f59e0b,#d97706);"
+              "color:#000;text-align:center;padding:10px 16px;"
+              "font-weight:600;font-size:14px;position:sticky;"
+              "top:0;z-index:9999;"
+              "box-shadow:0 2px 4px rgba(0,0,0,0.15)"
+          )
+          time_ago_js = (
+              "<script>"
+              "(function(){"
+              f"var t=new Date('{build_iso}').getTime();"
+              "function u(){"
+              "var d=Math.floor((Date.now()-t)/1e3),"
+              "s=d<60?d+'s ago':d<3600?Math.floor(d/60)+'m ago':"
+              "d<86400?Math.floor(d/3600)+'h ago':Math.floor(d/86400)+'d ago';"
+              "document.getElementById('preview-age').textContent=s}"
+              "u();setInterval(u,30000)"
+              "})()"
+              "</script>"
+          )
+          banner = (
+              f'<div style="{style}">'
+              f"Development Preview &mdash; PR #{pr_number}"
+              f' &mdash; <code style="background:rgba(0,0,0,0.1);'
+              f'padding:2px 6px;border-radius:3px;font-size:12px">'
+              f"{short_sha}</code>"
+              f' &mdash; built <span id="preview-age"></span>'
+              f"</div>"
+              f"{time_ago_js}"
+          )
+          count = 0
+          for f in pathlib.Path("_site").rglob("*.html"):
+              text = f.read_text(encoding="utf-8")
+              updated = re.sub(r"(<body[^>]*>)", lambda m: m.group(1) + banner, text, count=1)
+              if updated != text:
+                  f.write_text(updated, encoding="utf-8")
+                  count += 1
+          print(f"Injected preview banner into {count} HTML files")
+          PYEOF
+
+      - name: Upload preview artifact
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7
+        with:
+          name: preview-site
+          path: _site
+          retention-days: 5
+
+  deploy-preview:
+    name: Deploy Preview
+    needs: build
+    if: github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - name: Download preview artifact
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+        with:
+          name: preview-site
+          path: _site
+
+      - name: Set up Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: "22"
+
+      - name: Deploy to Cloudflare Pages
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: |
+          npm i --no-save wrangler@3.114.17 > /dev/null
+          npx wrangler pages deploy _site --project-name=synthorg-pr-preview --branch="pr-${PR_NUMBER}"
+
+      - name: Comment preview URL
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        env:
+          PREVIEW_URL: "https://pr-${{ github.event.pull_request.number }}.synthorg-pr-preview.pages.dev"
+        with:
+          script: |
+            const url = process.env.PREVIEW_URL;
+            const headSha = context.payload?.pull_request?.head?.sha || context.sha;
+            const marker = '<!-- synthorg-pr-preview -->';
+            const body = [
+              marker,
+              '## Preview Deployment',
+              '',
+              `**URL:** ${url}`,
+              '',
+              `Built from commit \`${headSha.substring(0, 7)}\``,
+            ].join('\n');
+
+            const comments = await github.paginate(
+              github.rest.issues.listComments,
+              {
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                per_page: 100,
+              }
+            );
+            const existing = comments.find(
+              c => c.user?.login === 'github-actions[bot]' && c.body?.includes(marker)
+            );
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+                body,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body,
+              });
+            }
+
+  cleanup-preview:
+    name: Cleanup Preview
+    if: >-
+      github.event.action == 'closed' &&
+      github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - name: Delete preview comment
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        with:
+          script: |
+            const marker = '<!-- synthorg-pr-preview -->';
+            const comments = await github.paginate(
+              github.rest.issues.listComments,
+              {
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                per_page: 100,
+              }
+            );
+            const existing = comments.find(
+              c => c.user?.login === 'github-actions[bot]' && c.body?.includes(marker)
+            );
+            if (existing) {
+              await github.rest.issues.deleteComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+              });
+              console.log(`Deleted preview comment ${existing.id}`);
+            } else {
+              console.log('No preview comment found');
+            }
+
+      - name: Delete branch deployments
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: |
+          BRANCH="pr-${PR_NUMBER}"
+          # List deployments for this branch (per_page=100 to cover busy PRs)
+          # Note: Cloudflare prevents deleting the latest deployment per branch — that one will remain
+          DEPLOYMENTS=$(curl -sf \
+            "https://api.cloudflare.com/client/v4/accounts/${CLOUDFLARE_ACCOUNT_ID}/pages/projects/synthorg-pr-preview/deployments?per_page=100" \
+            -H "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}" \
+            | jq -r ".result[] | select(.deployment_trigger.metadata.branch == \"${BRANCH}\") | .id") || true
+          if [ -z "$DEPLOYMENTS" ]; then
+            echo "No deployments found for branch ${BRANCH}"
+            exit 0
+          fi
+          for DEPLOY_ID in $DEPLOYMENTS; do
+            echo "Deleting deployment ${DEPLOY_ID}..."
+            RESPONSE=$(curl -s -w "\n%{http_code}" -X DELETE \
+              "https://api.cloudflare.com/client/v4/accounts/${CLOUDFLARE_ACCOUNT_ID}/pages/projects/synthorg-pr-preview/deployments/${DEPLOY_ID}?force=true" \
+              -H "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}")
+            HTTP_CODE=$(echo "$RESPONSE" | tail -1)
+            if [ "$HTTP_CODE" -ge 400 ]; then
+              echo "::warning::Failed to delete deployment ${DEPLOY_ID} (HTTP ${HTTP_CODE}) — may be the latest deployment (Cloudflare restriction)"
+            fi
+          done
+          echo "Cleaned up preview deployments for ${BRANCH}"

CLAUDE.md

@@ -173,6 +173,14 @@ src/ai_company/
 
 - **Jobs**: lint (ruff) + type-check (mypy src/ tests/) + test (pytest + coverage) run in parallel → ci-pass (gate)
 - **Pages**: `.github/workflows/pages.yml` — builds Astro landing + MkDocs docs, merges, deploys to GitHub Pages on push to main
+- **PR Preview**: `.github/workflows/pages-preview.yml`
+  - Builds site on PRs (same path triggers as Pages), injects "Development Preview" banner, deploys to Cloudflare Pages (`synthorg-pr-preview` project) via wrangler CLI
+  - Each PR gets a unique preview URL at `pr-<number>.synthorg-pr-preview.pages.dev`
+  - Requires `CLOUDFLARE_API_TOKEN` + `CLOUDFLARE_ACCOUNT_ID` secrets
+  - Checks out PR head SHA (not merge commit) so build matches reported commit
+  - Build job runs regardless (catches build failures); deploy job skips on fork PRs (no secrets access)
+  - Cleanup job deletes preview comment and Cloudflare deployments on PR close
+  - Concurrency group cancels stale builds on rapid pushes
 - **Docker**: `.github/workflows/docker.yml` — builds backend + web images, pushes to GHCR, signs with cosign. Scans: Trivy (CRITICAL = hard fail, HIGH = warn-only) + Grype (critical cutoff). CVE triage via `.github/.trivyignore.yaml` and `.github/.grype.yaml`. Images only pushed after scans pass. Triggers on push to main and version tags (`v*`).
 - **Matrix**: Python 3.14
 - **Dependabot**: daily uv + github-actions + docker updates, grouped minor/patch, no auto-merge

DESIGN_SPEC.md

@@ -3263,6 +3263,7 @@ synthorg/
 │   │   ├── release.yml             # Release Please (automated versioning + GitHub Releases)
 │   │   ├── secret-scan.yml         # Gitleaks on push/PR + weekly
 │   │   ├── pages.yml               # Build Astro + MkDocs → deploy GitHub Pages
+│   │   ├── pages-preview.yml       # PR preview → Cloudflare Pages
 │   │   └── zizmor.yml              # Workflow security analysis (zizmor)
 │   ├── actions/
 │   │   └── setup-python-uv/        # Composite action: Python + uv install