Dev/mjolley/v10

.env.example

@@ -0,0 +1,54 @@
+# Copy to .env and fill in. Everything here is also set on Netlify, per environment.
+#
+# The site builds and runs with none of these. Supabase driven parts stay quiet rather
+# than failing, so a fork or a first clone works before anybody has been given keys.
+# See supabase/README.md for where each value comes from.
+
+# Safe to expose. Ships in the browser bundle by design.
+PUBLIC_SUPABASE_URL=
+
+# The v2 project ref, for pnpm types. Not defaulted on purpose: the old ref still serves
+# the live site and regenerating against it would quietly empty the generated types.
+SUPABASE_PROJECT_REF=
+
+PUBLIC_SUPABASE_ANON_KEY=
+
+# Never expose. Bypasses row level security completely. Server only, and it is what
+# every write on the site goes through.
+SUPABASE_SERVICE_ROLE_KEY=
+
+# Rotatable secret used to hash a visitor's IP into a like dedupe token. Rotating it
+# forgets who liked what without ever having stored an address. Any long random string.
+LIKE_IP_SECRET=
+
+# Drafts a title, a one line summary and a slug for a submitted dev disaster. Without a
+# key the drafter falls back to the story's own opening line and never calls out, which
+# works but reads flatter. AI_API_URL and AI_MODEL default to OpenAI chat completions and
+# gpt-4o-mini, so only the key is usually needed.
+AI_API_KEY=
+AI_API_URL=
+AI_MODEL=
+
+# Used once, after a data load, if the badge matcher is to key on stable Twitch ids
+# rather than on logins. Not needed at build time or at runtime. See docs/backfill.md.
+TWITCH_CLIENT_ID=
+TWITCH_CLIENT_SECRET=
+
+# PARKED FOR V1. The three below are listed for completeness and must stay unset. v1 sends
+# no email of any kind, so there is no sender, no address and no drain on a timer. Setting
+# any of them is step one of turning notifications on, which is a decision with a real
+# ongoing cost attached, not a configuration gap to be filled in. docs/notifications.md is
+# the procedure, including the copy on submit, privacy, terms and account that has to
+# change back at the same time. docs/new-project.md deliberately omits all three.
+#
+# RESEND_API_KEY   Mail provider key. src/lib/mail.ts is written but nothing calls it.
+# MAIL_FROM        From address. Would need a domain verified with the provider.
+# NOTIFY_SECRET    Bearer token for the drain at /api/notifications/. Unset, that route
+#                  404s every request before it touches the database, which is the only
+#                  reason it is safe to leave in the route table. The table it would drain
+#                  does not exist either: the enqueue trigger and email_outbox are both
+#                  held in supabase/deferred/, so nothing queues and there is nothing to
+#                  send. Do not read these as "configured off". They are absent.
+RESEND_API_KEY=
+MAIL_FROM=
+NOTIFY_SECRET=

.gitattributes

@@ -0,0 +1,8 @@
+# Generated artifacts are committed so CI can regenerate them and diff. That only works
+# if the checked out bytes match what the generator writes, so these stay LF on every
+# platform regardless of core.autocrlf.
+src/styles/themes.css        text eol=lf
+src/lib/themes.generated.ts  text eol=lf
+src/lib/ec-themes.generated.mjs text eol=lf
+src/config/taxonomy.json     text eol=lf
+public/_redirects            text eol=lf

.github/workflows/ci.yml

@@ -0,0 +1,190 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build and gates
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    steps:
+
+      - uses: actions/checkout@v7
+      - name: Check out the content submodule
+        env:
+          CONTENT_DEPLOY_KEY: ${{ secrets.CONTENT_DEPLOY_KEY }}
+        run: |
+          if [ -z "$CONTENT_DEPLOY_KEY" ]; then
+            echo "::error::CI cannot read src/content, so no collection would have any entries."
+            echo "src/content is a git submodule pointing at michaeljolley/content, which is"
+            echo "private. The default GITHUB_TOKEN is scoped to this repository only and"
+            echo "cannot clone another one."
+            echo ""
+            echo "Fix, once, by hand:"
+            echo "  1. ssh-keygen -t ed25519 -C 'baldbeardedbuilder.com CI' -f content-ci -N ''"
+            echo "  2. On michaeljolley/content, Settings, Deploy keys, Add deploy key."
+            echo "     Paste content-ci.pub. Leave write access UNCHECKED, a build only reads."
+            echo "  3. On this repository, save the private half, the whole content-ci file"
+            echo "     including its BEGIN and END lines, as the secret CONTENT_DEPLOY_KEY."
+            echo "  4. Delete both local files. GitHub keeps the only copies that matter."
+            echo ""
+            echo "A deploy key rather than a token on purpose. A token expires and is tied to"
+            echo "a person, so it brings this same failure back later without warning."
+            echo ""
+            echo "This job fails rather than building without content, because an empty"
+            echo "collection set makes every gate below pass for the wrong reason."
+            exit 1
+          fi
+          mkdir -p ~/.ssh
+          chmod 700 ~/.ssh
+          # printf rather than echo, because a key is worthless if its final newline is lost.
+          printf '%s\n' "$CONTENT_DEPLOY_KEY" > ~/.ssh/id_ed25519
+          chmod 600 ~/.ssh/id_ed25519
+          ssh-keyscan -t rsa,ecdsa,ed25519 github.com >> ~/.ssh/known_hosts 2>/dev/null
+          git submodule update --init --depth 1 src/content
+          if [ ! -f src/content/content.config.ts ]; then
+            echo "::error::src/content was cloned but content.config.ts is not in it."
+            exit 1
+          fi
+          echo "src/content present, $(find src/content -name '*.md' | wc -l) markdown files."
+
+      - uses: pnpm/action-setup@v6
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+
+      # Fails if a generated artifact was hand edited. themes.css, the font CSS, the
+      # taxonomy map and _redirects are all outputs, never inputs.
+      - name: Generated artifacts are in sync
+        run: pnpm gen:check
+
+      - name: Unit and redirect tests
+        run: pnpm test
+
+      # The baseline was trimmed to the two legacy tables v2 actually reads, so a
+      # migration leaning on something that went would only fail on a db push against
+      # a fresh project, which is the worst place to find out.
+      - name: Migration chain is self contained
+        run: pnpm check:migrations
+
+      # Catches the class of mistake that a build will happily ship: a Supabase column
+      # that changed shape under a query, a nullable view column read as if it were not.
+      - name: Types
+        run: pnpm check
+
+      - name: Build
+        run: pnpm build
+
+      # The step above is the first thing in this job that produces dist, and four tests
+      # in redirects.build.test.mjs need it. They were only in the run above, before the
+      # build, so they skipped on every run and reported green while asserting nothing.
+      # Run again here, where dist exists. REQUIRE_DIST turns the skip into a failure, so
+      # this cannot quietly stop working again if the steps are ever reordered.
+      - name: Redirect tests against the real build
+        run: pnpm test
+        env:
+          REQUIRE_DIST: '1'
+
+      # Reads the built output rather than the source, because the sitemap and the
+      # Pagefind index are generated and so are never reviewed by a person. Catches a
+      # parked route that still ships, and any page listed in the sitemap whose own
+      # markup says noindex.
+      - name: Shipped output
+        run: pnpm check:dist
+
+      # In this job rather than the browser one because it needs no browser, and it reads
+      # source as well as dist. /report/ is prerender = false, so it writes no file and
+      # every gate that works from the built output is blind to it. a11y is the exception,
+      # since it starts a dev server for exactly that reason.
+      - name: Published addresses
+        run: pnpm check:emails
+
+      # Both browser gates need dist, and a build is slow enough that handing it over
+      # beats building it three times.
+      - name: Upload dist
+        uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist
+          retention-days: 3
+
+  a11y:
+    name: Accessibility and layout
+    runs-on: ubuntu-latest
+    needs: build
+    timeout-minutes: 30
+
+    steps:
+      - uses: actions/checkout@v7
+      - uses: pnpm/action-setup@v6
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 24
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist
+
+      - run: pnpm exec playwright install --with-deps chromium
+      - run: pnpm a11y
+
+      # Rides along in this job because it is the only one that pays for a browser, and
+      # installing chromium twice to run a second thirty second check is not worth it.
+      # Different question from accessibility, same requirement: a laid out page.
+      - name: Layout geometry
+        run: pnpm check:layout
+
+      # Counts intents rather than measuring anything, so it is its own step: a doubled
+      # count has no visible symptom, and a failure here should not read as a layout one.
+      - name: Share intents
+        run: pnpm check:share
+
+      # Separate from the accessibility job on purpose. axe only reports a missing id when
+      # the element needed a name to be usable, so this catches a class that job is right
+      # to stay quiet about, and a failure here should not read as an axe one.
+      - name: Id references
+        run: pnpm check:aria
+
+      # Rides along here because it needs a browser and a built dist. Sixteen themes times
+      # five heading levels is 96 computed colors, and the failure being guarded is a
+      # heading that reads as body text or as a link rather than one that looks broken.
+      - name: Prose heading color
+        run: pnpm check:headings
+
+  perf:
+    name: Performance budget
+    runs-on: ubuntu-latest
+    needs: build
+    timeout-minutes: 30
+
+    steps:
+      - uses: actions/checkout@v7
+      - uses: pnpm/action-setup@v6
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist
+
+      - run: pnpm exec playwright install --with-deps chromium
+      - run: pnpm perf

.gitignore

@@ -1,8 +1,13 @@
 # build output
 dist/
+.netlify/
 # generated types
 .astro/
 
+# Copied out of Fontsource by scripts/gen-fonts.mjs on every build. Fontsource is the
+# source of truth, so a committed copy could only ever drift away from it.
+public/fonts/
+
 # dependencies
 node_modules/
 
@@ -14,11 +19,41 @@ pnpm-debug.log*
 
 
 # environment variables
-.env
-.env.production
+#
+# Ignore every .env variant and name the exceptions, rather than naming the variants.
+# This rule used to be the two files that happened to exist the day it was written, which
+# meant .env.local, .env.audit-bak or anything else a debugging session leaves behind was
+# untracked AND unignored, so one git add -A stages real credentials into a public repo.
+# Now an unknown .env file is ignored by default and only an explicitly allowed one is
+# tracked. tests/secrets.test.mjs asserts nothing env shaped is ever left visible.
+.env*
+!.env-sample
+!.env.example
+
+# The same thing without the leading dot. env.local and env.backup get created by mistake
+# often enough to be worth a rule, and tests/secrets.test.mjs proved this case was still
+# open after the rule above was widened. Anchored to the root with a leading slash so it
+# cannot reach src/env.d.ts, which is tracked source and must stay visible.
+/env*
+
+# Screenshot output from the theme and state passes. Large, binary, and superseded on
+# every run, so it belongs in the session files rather than in history.
+#
+# The harnesses that produce them are deliberately NOT ignored. They have to sit in the
+# repo root to resolve their imports, and they are meant to be deleted once the pass is
+# done. Left visible in git status, a leftover harness nags until it is removed. Ignored,
+# it would quietly accumulate.
+shots-*/
 
 # macOS-specific files
 .DS_Store
 
 # jetbrains setting folder
 .idea/
+
+# Supabase CLI scratch, holds the linked project ref
+supabase/.temp/
+
+# Resumable transcript cache and Supabase import files. These are large backfill artifacts,
+# not application source, and can be regenerated from the video catalogue.
+/backfill/