seriesoftubes/.claude/skills/github-pages/SKILL.md
Frederic Jung 7cbe0ec09b
Regenerate published weekly puzzles when a release's prices break them
--check now re-solves every week not over yet and, when its budget no longer
verifies, regenerates it deterministically: the same puzzle with a new budget
if that works, else a fresh one for the key. A regenerated file carries rev 2,
3...; the game keeps stars per revision, so only that week's stars reset.
Past weeks are left alone unless the game rejects them. release.yml runs it
before the tests on every deploy, weekly-puzzle.yml before making the new
week; either fails only if a week cannot be regenerated.
2026-10-29 10:03:20 +01:00

3.9 KiB

name description
github-pages Series of Tubes is hosted on GitHub Pages and nowhere else, non-negotiably. Use before any change to hosting, deploys, the build output, caching, the service worker, new runtime requests or anything that would need a server, and whenever someone suggests another host.

GitHub Pages, always

Series of Tubes is served by GitHub Pages at https://seriesoftub.es and only there. This is settled (docs/adr/0001-github-pages-only.md) and not up for discussion: do not propose, prepare or "keep the door open" for another host, a CDN in front, a backend or server-side rendering, even when asked to evaluate options. If a feature seems to need one, redesign the feature.

What that means for a change

  • The output is static files. npm run build writes _site/: the assembled page, site/'s files, version.json. No server code, no runtime secrets: everything there is public.
  • No HTTP headers, redirects or rewrites. Pages ignores _headers, _redirects, .htaccess, vercel.json, netlify.toml. Need a policy? Use a <meta> tag. Need a different URL? Add a static file there.
  • Caching is Pages' (short, the same for every file) plus the service worker's. Offline play and updates are site/sw.js's job; its cache name carries the version. When you add a file the game needs offline, add it to CORE there.
  • Same origin. The page, dictionaries, icons and data come from seriesoftub.es. Do not add CDN libraries or third-party APIs the game needs to work; the web fonts and the analytics counter are the only exceptions and the game runs without them.
  • More files are fine, from the same origin. Pages serves many small files well over HTTP/2. Still: the game page itself stays one assembled index.html (see ADR 0002), and anything the first frame needs must not add a round trip.
  • Limits: about 1 GB for the whole site, 100 MB per file.
  • Paths: the site lives at the domain root (site/CNAME), so / paths are fine; unknown paths get 404.html.

How it deploys

Only releases deploy. Bumping version in package.json on main runs auto-release.yml, which tags, publishes the GitHub release and starts release.yml: test, REQUIRE_NOTES=1 npm run build, actions/upload-pages-artifact with ./_site, actions/deploy-pages. That job is the only one with pages: write. Pushes to main and pull requests build but never deploy. The release skill has the steps.

The one exception: the weekly puzzle. Every Sunday at 03:37 UTC weekly-puzzle.yml commits the new site/puzzles/weekly/<key>.json to main (data only, no version bump) and starts release.yml for the live release tag with weekly=true. That run rebuilds exactly the live release, with every weekly file from main added, checks them with scripts/weekly-puzzle.js --check, and deploys it in the same pages concurrency group. Players get no update banner (the version does not change). Every release build also copies all weekly files from main, so a release never drops a published week, and regenerates (in the build, deterministically) any week not over yet that the release's prices no longer fit. Weekly files are plain JSON the game fetches only when the Puzzles list opens and never trusts; the service worker serves them network-first. See docs/ARCHITECTURE.md.

Before you hand back a change that touches the build, deploy or loading

npm run build && npm run serve      # the production build, served as static files
npm test -- tests/pages.test.js     # static-only, all references resolve, Pages-only deploy

tests/pages.test.js fails on host configuration files, files over the limits, local references that do not exist in _site/, scripts loaded from other origins, and any workflow that deploys anywhere else. Do not weaken it to make a change pass; change the change.