POC (#68): git-backed handbook on Astro + Cloudflare — GitHub auth, review workflow, no CMS/DB

.github/workflows/deploy-worker.yml

@@ -0,0 +1,78 @@
+name: Deploy Worker
+# Deploys the handbook Worker whenever app code or content lands on the
+# deployed branch — this is what makes an approved "Submit for approval" merge
+# actually appear on the site. During the POC that branch is i68-handbook-poc;
+# after the POC merges, pushes to main take over (same worker, same workflow).
+#
+# INERT UNTIL CONFIGURED: requires the CLOUDFLARE_API_TOKEN repo secret
+# (repo admin: Settings → Secrets and variables → Actions; token needs
+# Workers Scripts:Edit + Workers KV Storage:Edit). Until it exists, runs
+# skip with a notice instead of failing every merge.
+#
+# Deploy safety: wrangler.toml sets keep_vars=true and pins the SESSION KV id,
+# so CI deploys never wipe dashboard vars/secrets or rebind the session store.
+on:
+  push:
+    branches:
+      - i68-handbook-poc
+      - main
+    paths:
+      - "app/**"
+      # content is doc/*.md (single source since the doc/ refactor) — an
+      # approved editor merge touches ONLY doc/, and it must redeploy too
+      - "doc/**"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+# One deploy at a time, never cancelled mid-upload; queued runs collapse to
+# the latest.
+concurrency:
+  group: deploy-worker
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check for Cloudflare credentials
+        id: creds
+        env:
+          TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+        run: |
+          if [ -n "$TOKEN" ]; then
+            echo "ok=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "ok=false" >> "$GITHUB_OUTPUT"
+            echo "::notice::CLOUDFLARE_API_TOKEN secret not set — skipping deploy (a repo admin must add it; see workflow header)."
+          fi
+      - uses: actions/checkout@v4
+        if: steps.creds.outputs.ok == 'true'
+      - name: Set up pnpm
+        if: steps.creds.outputs.ok == 'true'
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+      - name: Set up Node.js
+        if: steps.creds.outputs.ok == 'true'
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+          cache-dependency-path: app/pnpm-lock.yaml
+      - name: Install dependencies
+        if: steps.creds.outputs.ok == 'true'
+        run: pnpm install --frozen-lockfile
+        working-directory: app
+      - name: Test & build
+        if: steps.creds.outputs.ok == 'true'
+        run: pnpm test && pnpm build
+        working-directory: app
+      - name: Deploy
+        if: steps.creds.outputs.ok == 'true'
+        uses: cloudflare/wrangler-action@v3
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          workingDirectory: app
+          command: deploy

.github/workflows/run-tests.yml

@@ -1,7 +1,7 @@
 name: Run Tests
 on:
   pull_request:
-    types: [review_requested, synchronize, labeled]
+    types: [opened, review_requested, synchronize, labeled]
   push:
     branches:
       - "main"
@@ -11,13 +11,24 @@ permissions:
   pull-requests: write
 
 jobs:
-  run-tests:
+  # ONE copy of the trigger condition; both build jobs hang off it via `needs`
+  # (a skipped gate skips them too). handbook/* head branches are editor
+  # "submit for review" PRs (opened by the handbook app, never
+  # review_requested/labeled) — run-tests is a REQUIRED check on main, so
+  # without that clause those PRs could never merge.
+  gate:
     if: |
       (github.event.action == 'review_requested' ||
       (github.event.action == 'labeled' && github.event.label.name == 'ci-testing') ||
       (github.event.action == 'synchronize' && contains(github.event.pull_request.labels.*.name, 'ci-testing'))) ||
+      (github.event_name == 'pull_request' && startsWith(github.event.pull_request.head.ref, 'handbook/')) ||
       (github.event_name == 'push')
+    runs-on: ubuntu-latest
+    steps:
+      - run: "true"
 
+  run-tests:
+    needs: gate
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
@@ -35,6 +46,35 @@ jobs:
               repo: context.repo.repo,
               labels: ["ci-testing"]
             })
+      - name: Set up pnpm
+        # app/ is a standalone pnpm project (not in the root workspace);
+        # pin its pnpm from app/package.json, not the root's.
+        uses: pnpm/action-setup@v6
+        with:
+          package_json_file: app/package.json
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24 # >=22.18 for node --test importing .ts (type stripping)
+          cache: pnpm
+          cache-dependency-path: app/pnpm-lock.yaml
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+        working-directory: app
+      - name: Typecheck, test, guard, build
+        run: pnpm check && pnpm test && pnpm guard && pnpm build
+        working-directory: app
+
+  # The legacy VitePress site still ships from doc/ until the cutover
+  # (POC.md "Migration & production cutover") — keep its build green too.
+  docs-build:
+    needs: gate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+          token: ${{ secrets.GITHUB_TOKEN }}
       - name: Set up pnpm
         uses: pnpm/action-setup@v6
       - name: Set up Node.js

CLAUDE.md

@@ -0,0 +1,33 @@
+# Claude instructions — osbrjp/handbook
+
+App code lives in `app/` (Astro SSR on Cloudflare Workers). `doc/` is the
+legacy VitePress site. `POC.md` records architecture decisions, deploy
+mechanics, and the cutover plan — read it before changing auth, deploy
+config, or the content workflow.
+
+## Code quality (apply to every change)
+
+- **No duplicates.** Before finishing any change, sweep for copy-pasted
+  logic/markup/CSS it introduced or touched. Extract a helper or shared
+  component when the same rule lives in two places (see
+  `app/src/lib/ui/editorForms.ts`, `app/src/components/Icon.astro` for the
+  established pattern). Don't extract when call sites merely look similar
+  but encode different behavior.
+- **Comments: short, but enough context for the next session.** Explain WHY
+  (the constraint, the trap, the verified fact) — never what the next line
+  does. Delete comments that describe old iterations.
+- **CSS**: source order matters in `global.css` — same-specificity overrides
+  must come AFTER the base rules they override (this has silently broken
+  before; grep "admin-list mobile" for the documented example).
+
+## Hard rules (public repo)
+
+- **Scan every diff before commit/push** for secrets, tokens, personal
+  emails, account ids, and live non-production URLs. Encrypted values and
+  credentials live in Cloudflare/GitHub settings, never in the repo.
+- No allow-lists, no databases: GitHub repo access IS the access control.
+- Use **pnpm** in `app/` (never npm).
+
+## Gates before any commit
+
+Run in `app/`: `pnpm test` and `pnpm build` — both must pass.