feat: add PR preview deployments via Cloudflare Pages

.github/workflows/pages-preview.yml

@@ -0,0 +1,183 @@
+name: PR Preview
+
+on:
+  pull_request:
+    branches: [main]
+    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
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          persist-credentials: false
+
+      # --- 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 }}
+        run: |
+          python3 << 'PYEOF'
+          import os, pathlib, re
+
+          pr_number = os.environ["PR_NUMBER"]
+          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)"
+          )
+          banner = (
+              f'<div style="{style}">'
+              f"Development Preview &mdash; PR #{pr_number}"
+              f" &mdash; Not a release version"
+              f"</div>"
+          )
+          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: Deploy to Cloudflare Pages
+        id: deploy
+        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 > /dev/null 2>&1
+          DEPLOY_OUTPUT=$(npx wrangler pages deploy _site --project-name=synthorg-pr-preview --branch="pr-${PR_NUMBER}" 2>&1)
+          echo "$DEPLOY_OUTPUT"
+          DEPLOY_URL=$(echo "$DEPLOY_OUTPUT" | grep -oP 'https://[^\s]+\.pages\.dev' | tail -1)
+          echo "deployment-url=${DEPLOY_URL}" >> "$GITHUB_OUTPUT"
+
+      - name: Comment preview URL
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        env:
+          DEPLOY_URL: ${{ steps.deploy.outputs.deployment-url }}
+        with:
+          script: |
+            const url = process.env.DEPLOY_URL || '';
+            if (!url) {
+              console.log('No deployment URL found — skipping comment');
+              return;
+            }
+            const headSha = context.payload?.pull_request?.head?.sha || context.sha;
+            const body = [
+              '## 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.body?.includes('## Preview Deployment'));
+            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,
+              });
+            }

CLAUDE.md

@@ -173,6 +173,7 @@ 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. Build job runs regardless (catches build failures); deploy job skips on fork PRs (no secrets access). 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

docs/getting_started.md

@@ -150,6 +150,6 @@ VS Code should auto-detect the `.venv` directory. If not, use **Python: Select I
 
 ## Next Steps
 
-- [CONTRIBUTING.md](../.github/CONTRIBUTING.md) — branch, commit, and PR workflow
-- [CLAUDE.md](../CLAUDE.md) — code conventions and quick command reference
-- [DESIGN_SPEC.md](../DESIGN_SPEC.md) — full high-level design specification
+- [CONTRIBUTING.md](https://github.com/Aureliolo/synthorg/blob/main/.github/CONTRIBUTING.md) — branch, commit, and PR workflow
+- [CLAUDE.md](https://github.com/Aureliolo/synthorg/blob/main/CLAUDE.md) — code conventions and quick command reference
+- [DESIGN_SPEC.md](https://github.com/Aureliolo/synthorg/blob/main/DESIGN_SPEC.md) — full high-level design specification

src/ai_company/communication/messenger.py

@@ -291,7 +291,7 @@ async def receive(
             - *timeout* expires without a message arriving.
             - The bus is shut down while waiting.
             - The subscription is cancelled via :meth:`unsubscribe`
-              while a ``receive()`` call is in flight.
+                while a ``receive()`` call is in flight.
         """
         return await self._bus.receive(
             channel_name,