README's link, the export-ignore beside CHANGELOG.md's, the watch-paths
note in DEPLOYMENT.md, and a CLAUDE.md rule for where release notes go
and how a release moves [Unreleased] into its own file.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
README: a Qodana badge and the workflow in the list of scanners.
DEPLOYMENT: what qodana.yml runs, the three secrets, the gate, and what
to remove if the licence ends. CLAUDE.md: the setup and the traps the
first runs found (no interpreter in native Python, the Rust image's
missing linker and libraries, plugins only in Docker, the lucide import
false positive). CHANGELOG [Unreleased]: the Qodana entry.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The scan job now runs both suites with coverage before scanning:
pytest --cov (pyproject.toml: scripts/ without its tests, relative
paths, coverage.xml) and `npm run test:coverage` (vite.config.ts: v8,
lcov with projectRoot "..", so paths start web/). sonar-project.properties
names both reports and drops sonar.coverage.exclusions.
requirements-test.txt gains pytest-cov 7.1.0 and coverage 7.16.2 with
every file's hash (uv pip compile --universal --generate-hashes
--python-version 3.15; the existing pins are unchanged). web gains
@vitest/coverage-v8 5.0.5, matching vitest; none of its packages has an
install script. Coverage stays off for a plain `npm test`.
The token check is its own job, so the scan steps no longer each repeat
the condition; the workflow grants nothing at the top and the scan job
contents: read. `npm run build:admin` replaces the bare `svelte-kit
sync`: it syncs too, and writes the admin bundle the Worker's tests load.
Locally: 576 vitest tests at 58.35% of lines, 299 pytest tests at 57.7%.
Against main's new-code lines (SonarCloud's isNew), the reports cover
92 of 114 coverable lines, 80.7%: the 80% gate is borderline.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A sonarcloud.yml workflow runs SonarSource/sonarqube-scan-action (pinned to
the v8.3.0 commit) on pull requests and main, with full history for blame.
Commits that touch only what the data jobs write are skipped, and a run
without SONAR_TOKEN (forks, Dependabot) passes without scanning.
.sonarcloud.properties becomes sonar-project.properties, now naming the
organization and project key; its scope settings are unchanged. The
toolchain test, Web CI's paths, CLAUDE.md and docs follow the rename.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- docs/plan/16-toolchain-2026.md: the assessment - what each release
changes, what was measured here, the decisions, how to move each runtime
next time, and what was left.
- docs/plan/17-typescript-7.1.md: the springboard for dropping TypeScript 6
once 7.1 ships - start conditions and how to check them, the steps, the
planted-error table and the baselines to compare against.
- CLAUDE.md: "TypeScript is two packages, on purpose" and "One version of
each runtime"; the uv compile line says 3.15.
- dev_env (EN/VI), README, AUTHORS, TAURI.md, web/README, THIRD_PARTY,
DEPLOYMENT (Workers Builds' NODE_VERSION=26, the Checks paragraph),
ACKNOWLEDGEMENTs and the About page's stack list ("TypeScript 7 + 6").
- CHANGELOG: the Tooling entry.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
.sonarcloud.properties tells SonarCloud what is code, what is test code and
what to skip. Both start at the root and are split by patterns:
- tests: scripts/tests, every *.test.ts, and what only tests and the admin's
dev server use (lib/testing, worker/testing, admin/mock) - analysed with
the test rules, out of duplication and coverage;
- not analysed: the dataset and pipeline-written files (data/, games/,
*.jsonl), the D1 migrations (SQLite, which the PL/SQL analyser parsed as
Oracle), web/src/app.html (SvelteKit's template; its <title> arrives via
%sveltekit.head%), and what the Tauri CLI generated and nobody edits
(Android res/, buildSrc/, the icon set). The manifest, Gradle build files
and MainActivity.kt stay in.
Simulated on the tracked files: 219 code, 84 tests, 16 excluded, none
indexed twice. Takes effect once on main. Also an [Unreleased] CHANGELOG
entry for this and the updater-json job, and the rule in CLAUDE.md.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The previous commit said SonarCloud's automatic analysis covers main only.
That was read from an empty pull-request list at a moment when no PR was
open; this PR got its own "SonarCloud Code Analysis" check (quality gate
passed, no new issues). DEPLOYMENT.md and the CHANGELOG entry now say that
CodeQL and SonarCloud both check pull requests and main.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- CLAUDE.md: the parser worker's origin check and why `e.origin &&` must
stay; CI installs only what is pinned (action SHAs, --ignore-scripts, no
npx, hashed Python requirements and how to add a package); the Android
app's Auto Backup opt-out and why the policy is not the thing to change.
- docs/DEPLOYMENT.md: what web-ci and python-tests run now; CodeQL analyses
pull requests, SonarCloud only main.
- docs/dev_env.md (and docs/i18n/vi): run the pipeline from the repo root
with the hashed installs - `cd scripts` left data/ out of reach.
- docs/THIRD_PARTY.md: requirements-dev.txt goes in a pip call of its own.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The previous commit said documentation AND data commits no longer deploy.
Documentation commits do not; data commits still did: 3f9e8cff ("Refresh store
data [2026-10-02]", four files under data/) carries a Workers Builds check
with a new Version ID, 712b4ab8, at 16:54Z. DEPLOYMENT.md and CLAUDE.md now
state the rule rather than claim it is in force, keep the configuration that
stops both, and say how to verify it: the next bot data commit must have no
Workers Builds check.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- DEPLOYMENT: documentation and data commits no longer deploy (watch paths,
2026-10-02) - except that the legal documents are build inputs
(build/legal-versions.ts, lib/server/markdown.ts), so a commit that
changes only them must still trigger a build, or the consent gate keeps
the old text and hash. Gives a watch-path configuration that does both
(excludes are applied before includes) and how to check it.
- CLAUDE.md: the same, plus how static/_headers caches by path and why
pages, sw.js and version.json must keep revalidating.
- CHANGELOG [Unreleased]: the static cache rules (PR #160) and the above.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- CHANGELOG [Unreleased]: AVIF art minted into R2, the packed catalogue,
themed and hideable scrollbars, the prerender 404 noise, uncompressed
shards, the Tailwind scrollbar-thin collision, the thumbnail probe, the
data-commit redeploy, and the /cdn-cgi/image billing hole.
- SECURITY_SETUP §5: zone Transformations are OFF (every /cdn-cgi/image/
request answers 404) and the cron kept minting with them off, so the
Images binding does not need them.
- DEPLOYMENT: shard compression depends on the `ndjson-shards` Compression
Rule, a dashboard setting; packed files are deliberately not .jsonl.
- CLAUDE.md: the scrollbar rules (scrollbar-slim, never Tailwind's core
scrollbar-thin; panel/page markers; the stored key), and Transformations
must stay off.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
/img/* used to pass Steam's JPEG straight through (median 36 KB; every
header is 460x215). Thumbnails and the detail hero are now AVIF for every
browser that accepts it: measured locally, 6.9 KB for the 460 px hero and
2.7 KB for the 230 px thumbnail of Counter-Strike 2, against a 34.3 KB JPEG.
How it is split:
- worker/lib/img-mint.ts (cron, every 15 min) is the ONLY place a billed
transformation happens. It builds the source list from shards that hash
to data/index.json (a lagging raw.githubusercontent shard would otherwise
freeze a stale list under the new generation), most-played first, encodes
`s` 230 px q55 and `d` 460 px q60 with the Images binding and writes them
to R2 `f2p-media` under img/v1/<w>/<path>@<t>.avif. The list is kept in a
marker object, so a backfill does not re-download the shards every tick.
- worker/routes/img.ts only READS: Cache API -> R2 -> Steam's JPEG. No
request (unknown appid, forged ?t=, HEAD) can create a transformation or
an R2 object. The old cf.image WebP branch is gone.
- Budget: Images Paid has no spend cap, so IMG_TRANSFORM_MONTHLY_CAP (20,000,
at most $7.50 against the agreed $15/month) is enforced by an atomic D1
counter (locks.ts bumpCounter), counted before each call, fail closed.
Error 9422 stops every isolate until the month turns.
Variants: s/d are negotiated on Accept with Vary: Accept. An AVIF browser
gets the JPEG only as a provisional answer (one day, no X-Img-Final) and the
service worker now caches only X-Img-Final responses, because CacheFirst
ignores Cache-Control. t and d2 stay JPEG: released apps request them and d2
is og:image. Cache keys are normalised, so stray query strings no longer
fork the edge cache, and the t capsule probe no longer runs on hashed paths
where it was two guaranteed 404s.
Client: thumbnails use s, the hero uses d with fetchpriority="high". The
Steam URL parser moves to shared/steam-image.ts so the client, route and
cron cannot disagree. worker-configuration.d.ts regenerated (runtime types
unchanged). Bucket f2p-media already exists (created 2026-10-02).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Legal (both reopen the consent gate for returning visitors, showing only
the changed lines - edited line-locally so that diff stays small):
- PRIVACY_POLICY: a section on the website's Turnstile check - after
acceptance, at most daily, what challenges.cloudflare.com reads (IP,
User-Agent, TLS fingerprint, page signals), that Cloudflare is processor
for the site and controller where it improves its bot detection (the
Turnstile Privacy Addendum), that the Worker forwards the token and IP
and keeps neither; the f2p:human_check storage row. "The only third
party", "the verification step" and "No fingerprinting" are corrected.
- ToS section 9: the check exists; /api/data/*, /img/* and the apps stay
excluded from both human checks.
SECURITY_SETUP:
- section 10 rewritten. It said the apps survived Hotlink Protection only
because their webview sent no Referer (untrue since WebView2 started
sending tauri.localhost), recommended switching the protection off, and
said no allowlist could express the apps' origin - a Configuration Rule
on http.referer can. Now: the per-<img> fix and its test, the rule for
2.0.0 installs, and the check, with the results measured today.
- new section 12: widget settings (hostname, Managed, pre-clearance off),
the TURNSTILE_SECRET secret and rotation, what the check is not, local
testing with Cloudflare's test keys, the optional rate-limit expression.
- the CSP block, the script-src/frame-src prose, "no form posts", the
rule budget (Configuration Rules 1/10), and two stale paths.
CLAUDE.md gains the human-check and <img> invariants and says "after
consent and the human check" where the service worker, analytics and
/welcome used to say "after consent". README, web/README, DEPLOYMENT,
ACKNOWLEDGEMENTs, SECURITY (bypassing the client-side gate is out of
scope), TAURI troubleshooting and the changelog follow. _headers and
worker/lib/http.ts: comments only - why images override Referrer-Policy,
what X-Frame-Options does and does not govern, and the public/_headers
and SITE_ORIGIN references that were stale.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
THE TWO WAF RULES EXIST NOW. `human-check-pages` (Managed Challenge) and
`blocked-countries` (Block) went live 2026-09-20, so SECURITY_SETUP no
longer reads as instructions for something that has not been done. Section
4 says what is deployed and when, and carries what was measured afterwards:
a plain curl with no browser User-Agent is still served `/`, `/games`,
`/legal/tos`, `/.well-known/security.txt`, `/sitemap.xml` and `/robots.txt`,
the challenge rate has stayed at 0%, and a real browser loads a game page,
the service worker and the beacon uninterrupted. Section 9 records the
analytics beacon returning 200 and its reports 204 on the live site, and
that "Enable with JS Snippet installation" is the only mode this CSP can
ever accept. "Still open" now names the Free-plan rule budget - 1/1 rate
limiting, 2/5 custom - because that is the next thing to run out.
THE DEPENDENCY LIST WAS THE REACT APP'S. ACKNOWLEDGEMENTs credited React 18,
react-router, i18next, Zustand, TanStack Query, Radix, shadcn/ui, cmdk,
OpenPGP.js, Tailwind 3, TypeScript 5 and PostCSS - none of which has
shipped since the v4 rewrite - while omitting Svelte, SvelteKit, Bits UI,
unified and the typefaces that actually do. Rewritten from package.json and
Cargo.toml, with every licence read out of node_modules rather than
remembered: echarts-wordcloud is ISC, not BSD-3-Clause. The claim that
/about carries a "full SPDX list" is gone; it is a curated subset and says
so now.
THIRD_PARTY.md gains svelte-check and vitest, which the pre-publish suite
has been running unlisted, and drops "the TypeScript SPA".
web/README.md documents the two analytics CSP hosts, why automatic
injection can never be used, the navigateFallback fix, and the consent
hashing and diff mechanism - none of which existed when its CSP and PWA
sections were written. Its file tree lists the four new modules.
DEPLOYMENT.md records that a zero-duration "Workers Builds" failure on a PR
branch is a preview-build artefact: it happened twice on PR #130 while the
identical commits deployed from main minutes later, and the GitHub Actions
`check` job already runs the same build, verify-dist and wrangler dry-run.
Also fixes a pre-existing broken curl snippet in section 10, whose
`%{http_code}\n` had been saved with a literal newline in it.
The dead relative links the link checker finds in CHANGELOG.md are left
alone: they are in released sections and name files that existed at the
time. A changelog is a record, not documentation.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The two Worker-rendered admin pages (admin-ui.ts, edit-ui.ts: 1,400 lines of
HTML and script inside template literals) are replaced by a Svelte 5 app in
web/admin/. It is built on its own and embedded in the Worker as the gitignored
worker/generated/admin-bundle.ts, so no admin code ever reaches dist/, the
service worker's precache or the packaged apps. worker/routes/admin-spa.ts
serves the shell with a per-response nonce CSP after the existing Access checks,
serves hashed assets immutably, and 404s any other path under /admin.
Queue
- Rows that are decided (approved, committed, rejected) or whose game is already
published have no checkbox, show a lock and are skipped by select-all. The
rules come from shared/queue-rules.ts, the same module the Worker enforces.
- Decisions confirm every row first and report skipped rows with their reasons.
- Tabs with counts, cross-status search, sort, page size, all kept in the URL.
- Keyboard: j/k, x, a, r, d, e, /, Esc, ?. Ignored while typing or composing.
- Details dialog: payload, durable decision, other rows for the game, Reopen for
a rejected row with the reason when it cannot be reopened.
- Phone layout as cards.
Edit
- One game: every change reviewed in a diff dialog before the commit; retire;
delete a settled override file; unsaved-change guard.
- Several games: any field, set or retire, selection kept across pages and
genres (up to 10), each game shown in the review.
Jobs, Audit and Health get their own paged, filterable pages. Health draws its
table on a 503 too, and Test write proves the write path.
An expired Access session reloads the page once; a refusal that survives the
reload is reported instead of looping. A non-JSON response is a server error,
never "session expired".
Local development: npm run dev:admin runs the real handlers against an in-memory
D1 with demo data, and npm run preview:admin serves the built bundle through the
real serveAdmin with the production CSP. Nothing in worker/ or admin/src imports
the mock, and the Worker has no authentication switch.
Also: design tokens move to src/styles/theme.css, shared by both builds;
verify-dist fails if admin code reaches dist/; vite-plugin-pwa is declared, as
src/app.d.ts references its types; docs/ADMIN.md, DEPLOYMENT.md and CLAUDE.md
describe the new admin.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
/games/<appid> was client-rendered only, so the 3,650 pages that describe the
actual catalogue were invisible to search. On the web build each one is now a
real document with its own title, description, social image, JSON-LD
VideoGame record and sitemap entry. The Tauri build prerenders none.
Two constraints shaped how:
- A crawler never accepts the terms, so it never loads the catalogue. The page
must render from data baked in at build time. build/game-seeds.ts reads
../data once in the SSR build and inlines a seed per game - slow-changing
fields only. Players, peak, reviews and metacritic are never baked: data
commits do not rebuild the site, so they always come from /api/data/*.
- It is a UNIVERSAL load, not a server load. With +page.server.ts every client
navigation fetches /games/<appid>/__data.json, and for a game added after the
deploy that is index.html at 200 - parsing fails and the page errors. The
browser half of the load reads the same seed back out of the page's
#game-seed block, so hydration matches, and returns null after a client-side
navigation, where the live catalogue renders.
fallback-route.ts previously re-rendered /games/* on every cold load, which a
prerendered page must not get. Pages that may arrive as the dashboard shell now
announce themselves with markRouteRendered(); recovery runs only when that did
not happen (new games, Tauri, studio pages). A page for a game removed since the
deploy shows "Game not found" with noindex once the catalogue loads, with the
removal reason when there is one.
Measured: 3,649 pages, build 16 s -> 30 s, dist 143 MB, ~38 KB a page. The
service-worker precache ignores them, the crawler ignores 404s for Worker-only
/img/ and /api/ paths and nothing else, and verify-dist.mjs --web checks every
game page carries its seed and JSON-LD and that no __data.json exists.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Completes the human side of the ingest pipeline. 646 discovered games were
sitting in D1 with no way to act on them except wrangler d1 execute.
/admin review screen, served BY THE WORKER
POST /api/admin/decide approve / reject / defer / requeue, in bulk
POST /api/admin/reconcile run the reconciler now
GET /api/admin/stats per-status counts for the tabs
worker/lib/git-commit.ts GraphQL createCommitOnBranch -> temp_info.jsonl
worker/lib/reconcile.ts promotes 'approved' only after seeing data/
scheduled() the same pass, every 15 minutes
The page is served by the Worker rather than added to the SPA. The public app
has no sign-in and no editing — that was removed deliberately — so admin markup
and endpoint names have no business in a bundle every visitor downloads, and
/admin cannot fall through to the public shell if a route changes. It ships its
own CSP with a per-response nonce; every value from Steam or D1 is written with
textContent.
The three actions are deliberately asymmetric:
reject final and local. Writes ingest_decisions('rejected'), which is what
actually stops tomorrow's sweep re-offering the game — the partial
unique index only covers OPEN rows.
defer parks the row while keeping the appid blocked.
approve does NOT publish. It appends to scripts/temp_info.jsonl and stops.
Approve stopping there is the whole design. ingest_new.py still decides whether
a game is real, free and reachable, so a commit is a REQUEST, not an outcome.
Only reconcile.ts, after observing the appid in data/, may write
ingest_decisions('approved') — because /api/ingest/known feeds decided appids
back to the discovery sweep, and marking something decided that never got
published makes it invisible to every future sweep.
Commits use createCommitOnBranch so GitHub signs them (Verified), carry
expectedHeadOid so a concurrent pipeline commit is retried against the newer
file rather than overwritten, and APPEND — the issue workflow and Telegram bot
write to that file too. Because the App installation token is not GITHUB_TOKEN,
the push triggers Ingest New Game Links on its own.
Verified before committing: the page was rendered and driven in a real browser
against a stubbed API (Access makes /admin unreachable to anything but the
owner's login). That caught three bugs a read-through did not — the commit
confirmation being wiped by the reload that followed it, the master checkbox
staying ticked with nothing selected, and unsequenced loads letting a stale
response paint under the wrong tab.
An adversarial review of this code found more, of which the serious ones:
- A game could be lost permanently and silently. ingest_new.py SKIPS an entry
that hits a network error, writes nothing to removed_games.jsonl, then clears
temp_info.jsonl regardless — so the request is gone and the game is in
neither file. The row would sit in 'approved' forever, and since
/api/ingest/known counts 'approved' as known, no future sweep would ever
offer that appid again. No UI action could reach it either: 'approved' is not
in DECIDABLE. Approvals unobserved after 12h now age out to 'failed', which
is decidable, and re-approving re-commits the link. 12h, not less: ingest-new
shares the data-write concurrency group with ~115-minute jobs.
- removed_games.jsonl is unpruned history going back to March. Matching on
appid alone marked a fresh approval 'failed' on the strength of a months-old
entry, so a game that stopped being free and later became free again could
never be re-added. Now requires removed_at > decided_at.
- 'failed' is outside uq_queue_open_appid, so a failed row can coexist with a
new pending row for the same appid. Approving both violated the index inside
a D1 batch AFTER the commit had landed. Rival open rows are now stood down in
the same batch, before the promotion, and a desync is reported rather than
swallowed.
- appendLinks deduplicates its input; approving two rows sharing an appid wrote
the link twice.
- A no-op approval returned the branch head as its commit sha, so commit_jobs
and audit_log attributed an unrelated commit to the approval.
- "Select all on this page" ignored the active filter: filtering to one game
and ticking it selected all 60 loaded rows, 59 of them invisible, and the
next click would have approved them.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The docs had drifted badly from the code. This makes them true.
LICENCE SPLIT. Code stays MIT; the dataset moves to CC BY 4.0 in a new
LICENSE-DATA, which is explicit about what the project cannot license: the
`description` field is the publisher's own store blurb stored verbatim (median
213 characters), `header_image` is a URL to publisher artwork, and game names
are trademarks used nominatively. Blanket-MIT over that material was a claim
the project was never entitled to make. Facts — player counts, review
percentages, platform support — are noted as unownable; the CC BY grant covers
the compilation and the project's own derived fields.
PRIVACY POLICY, rewritten rather than patched. The previous one said "no
backend, no server-side log, no cookies, no server other than GitHub's CDN".
Every clause of that is now false: the site runs on a Cloudflare Worker that
processes IP and User-Agent and keeps operational logs. It also documents the
one honest exception — the Activity page still calls api.github.com and loads
GitHub avatars from the browser, so GitHub sees a visitor's IP there while no
other page does — and lists every localStorage, IndexedDB and Cache Storage key
with why it exists.
SECURITY.md, rewritten. The old one claimed "no executable code, no
dependencies, no backend, no user data" and said there was no contact address,
while four other files publish one. It also told people to report
vulnerabilities in public issues. There is now a real scope (the Worker, the
proxies, D1, Actions secrets, the Tauri signing key), a private channel via
GitHub's vulnerability reporting, and specific things worth probing.
EULA corrected on two counts: it asserted a single MIT licence over everything,
and claimed there is "no installable software" despite the signed desktop and
Android builds. ToS and DISCLAIMER updated for the licence split, the new
domain, and the removal of in-browser editing and GPG signing — the disclaimer
described a signing flow that no longer exists.
README contradictions fixed: 1.2k games -> 3,424 across 5 shards not 2, 11
workflows -> 24, two scripts listed that were never in the tree, a TanStack
Table dependency the project does not use, and nine links to the old Pages URL.
New: docs/DEPLOYMENT.md (how a push becomes a deploy, the two wrangler.jsonc
fields that silently break it, and the stale-service-worker trap when verifying)
and docs/ADMIN.md (Cloudflare Access plus the GitHub App, with the exact
permission set — Contents write and Metadata only, and why Actions and
Workflows are deliberately withheld).
Two live fixes came out of writing this. GitHub Pages was serving a blank page:
it had the new index.html, which references assets at `/`, while Pages serves
under /free-steam-games-list/, so every asset 404'd — and deploy-pages.yml kept
redeploying it. That workflow now publishes a redirect that preserves the #/
fragment, since Pages cannot issue a 301. And CI pinned Python at 3.11, 3.12
and 3.14 across different workflows while the docs claimed 3.12 was pinned;
all fourteen references are now 3.12, which makes the claim true.
TERMS_VERSION 1 -> 2, so everyone re-consents. A privacy policy that now
discloses edge logging where it previously promised none is not a change to
apply silently.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>