feat(polish): phase 10 — search, accessibility, SEO and a real CSP

PLAN.md §13 phase 10, with four decisions of record — D47-D50, taking the count to fifty. Three were straightforward; the CSP turned into the phase's real work, because the thing meant to be a configuration flag was broken in a dependency and broken silently. D47 — search reaches the marketing pages, and the header gets a box. Base.astro marks its <main> as a Pagefind body, so all ten join the index the docs already query, and Search.astro opens it in a <dialog>. Nothing is fetched until the dialog is opened (the bundle is 120 kB and these pages otherwise ship almost no JavaScript). Pagefind titles a result from the first <h1>, and these pages have editorial ones — "The app for a deployment you already use" — so the index is given the page's short name instead. applyBrand.mjs now re-indexes after a rewrite, closing a note phase 2 left for this phase. D48 — the CSP is a real response header, sent by the container. Not a <meta>, which ignores frame-ancestors, and not advice for someone's reverse proxy, which puts the strictest promise in §6 outside what this repo tests. Three things fought it, all the same shape — correct build, broken page, no error: * Astro does not hash <script is:inline>, and Starlight ships six per docs page, so the first build with CSP on had a strict header and a dead theme switcher. The hashes are now generated into src/config/cspHashes.mjs and checkCsp.mjs verifies every inline block against its own page's policy. * Expressive Code writes ~3,700 inline style ATTRIBUTES, which cannot be hashed, hence style-src-attr 'unsafe-inline' — scoped to that directive, so script-src is untouched. * @astrojs/node matched a request to a policy with pathname.includes(), a substring test: /modules/ was served /docs/modules/building-a-module's policy and rendered with its own stylesheet refused. scripts/serve.mjs keeps the same _headers.json and matches by equality; test/headers.test.mjs starts the server and reads the responses, because nothing that reads dist/ can see this. D49 — robots.txt allows everything and names the sitemap (there was no way to find it: no robots.txt, and D9 rules out a search console). D50 — Organization and SoftwareApplication, no ratings and no docs-wide Article markup. checkA11y.mjs is the eleventh check: seven structural rules over all fifty pages, verified by breaking each in turn. The walk at 390/768/1280 found no overflow anywhere, the CSP violations above, a 17x17 consent checkbox (WCAG 2.2 SC 2.5.8 wants 24), and a skip link that moved the scroll but not the focus. npm run verify is green: fourteen steps, both test suites, all eleven checks. Co-Authored-By: Claude <noreply@anthropic.com>
2026-08-25 14:14:53 -05:00
parent a34c2ce538
commit e71ff4acd4
22 changed files with 1724 additions and 19 deletions
--- a/.gitea/workflows/pr-checks.yml
+++ b/.gitea/workflows/pr-checks.yml
@@ -158,3 +158,45 @@ jobs:
        env:
          GITEA_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
        run: npm run check:reference
+
+      - name: The headers the server actually sends
+        # PLAN.md §6 / D48, phase 10. Every other check reads dist/; this one starts
+        # scripts/serve.mjs and reads the responses, because the defect it exists for
+        # happened after the build was already correct. @astrojs/node matched a request to a
+        # policy with a SUBSTRING test, so /modules/ was served the policy built for
+        # /docs/modules/building-a-module — every file on disk right, the bytes on the wire
+        # wrong, and the page rendered with its own stylesheet refused.
+        #
+        # It needs the build, so it cannot live in the "Unit tests" step above.
+        run: npm run test:served
+
+      - name: Accessibility
+        # PLAN.md §13, phase 10. Seven structural rules over every built page: one <h1> and
+        # no skipped heading level, an alt attribute on every image, a label on every form
+        # control, an accessible name on every link and button, <html lang>, one <main> with
+        # a skip link that reaches it, and no positive tabindex.
+        #
+        # Structural on purpose. A static check cannot measure contrast on a rendered page
+        # or find a focus trap, and a check that pretended to would be trusted for things it
+        # cannot see. What it does catch is the class of defect that is invisible to a
+        # sighted author and permanent once shipped — and it covers Starlight's forty pages
+        # too, so a dependency upgrade that loses a label is a red build rather than a
+        # discovery.
+        #
+        # After the build, because it reads dist/client. No token and no network.
+        run: npm run check:a11y
+
+      - name: Content-Security-Policy
+        # PLAN.md §6 / D48. The policy is a real response header — the Node adapter's
+        # staticHeaders writes dist/_headers.json and the standalone server sends it — so
+        # frame-ancestors applies and the operator's proxy needs no CSP config.
+        #
+        # The check that matters is the second one: every inline script and style must be
+        # covered by a hash in ITS OWN page's policy. Astro does not hash <script is:inline>,
+        # and Starlight ships six of them per documentation page, so the first build with CSP
+        # enabled had a strict, correct header and a dead theme switcher — a failure with no
+        # symptom except a console message. A Starlight upgrade can reintroduce it at any
+        # time, which is why this runs on every PR rather than once.
+        #
+        # After the build, because it reads dist/. No token and no network.
+        run: npm run check:csp