From 6f4a95685592d18d09d04b81c2938b3fb089d8e9 Mon Sep 17 00:00:00 2001 From: poli0981 <127664709+poli0981@users.noreply.github.com> Date: Fri, 18 Sep 2026 16:23:24 +0700 Subject: [PATCH] docs: v4.0.0 licenses, policies and documentation (v4 Phase 5) Licenses - Code stays MIT (LICENSE: 2025-2026 poli0981 (SkullMute)). The catalog data (data_game/LICENSE.md) and the documentation are CC BY 4.0 (full legal code in LICENSES/CC-BY-4.0.txt); creators' descriptions, cover images, names and trademarks are excluded. NOTICE.md: license map and non-affiliation with itch.io. Policies (English + Vietnamese mirrors, dated 2026-09-18, applying from 4.0.0) - Terms of Use now cover the website and the public data, with the content-removal / copyright process, prohibited uses (bulk scraping, /img abuse, /admin and ingest access, Suggest spam), 18+ opt-in and Vietnamese law with the consumer-rights reservation. - Privacy Policy rewritten for Cloudflare as processor: exact browser storage, cookies, Turnstile, D1 retention (Suggest notes 180 days, idempotency 7 days), rights under Law No. 91/2025/QH15 and the GDPR. - EULA covers only the desktop and Android apps (also the installer RTF). - Disclaimer, Security Policy (private reporting, scope, safe harbor) and Code of Conduct (Contributor Covenant 2.1) rewritten; PAT, GPG and Telegram-bot material removed. Docs and templates - README / CONTRIBUTING (EN + VI), webapp/README, TAURI.md, dev_env (EN + VI), THIRD_PARTY, ACKNOWLEDGEMENTS; new docs/operations.md (Cloudflare + GitHub setup, v4 release order, routine tasks). - CLAUDE.md rewritten for the v4 architecture; CHANGELOG [4.0.0]. - Issue templates: config.yml (Suggest page + private security reports), "Add games" points to /suggest, "Remove a game" gained a rights-holder section; PR templates updated; CODEOWNERS. - Dependabot npm version updates resume with the v4 merge (limit 5). Co-Authored-By: Claude Opus 5 --- .github/CODEOWNERS | 5 + .github/ISSUE_TEMPLATE/add_games.yml | 27 +- .github/ISSUE_TEMPLATE/bug_report.yml | 70 +++- .github/ISSUE_TEMPLATE/config.yml | 8 + .github/ISSUE_TEMPLATE/remove_game.yml | 63 ++- .github/PULL_REQUEST_TEMPLATE/add_games.md | 19 +- .github/PULL_REQUEST_TEMPLATE/bug_fix.md | 16 +- .../PULL_REQUEST_TEMPLATE/documentation.md | 8 +- .github/PULL_REQUEST_TEMPLATE/new_features.md | 18 +- .github/dependabot.yml | 5 +- CHANGELOG.md | 125 ++++-- CLAUDE.md | 145 +++---- CODE_OF_CONDUCT.md | 97 +++-- CONTRIBUTING.md | 149 ++++--- LICENSE | 2 +- LICENSES/CC-BY-4.0.txt | 396 ++++++++++++++++++ NOTICE.md | 89 ++++ README.md | 380 +++++++++++------ README.vi.md | 304 ++++++++++---- SECURITY.md | 110 +++-- data_game/LICENSE.md | 136 ++++++ docs/ACKNOWLEDGEMENTS.md | 39 +- docs/DISCLAIMER.md | 121 ++++-- docs/EULA.md | 128 ++++-- docs/My_Stuff.md | 5 + docs/PrivacyPolicy.md | 280 ++++++++----- docs/THIRD_PARTY.md | 169 ++++++-- docs/ToS.md | 241 ++++++----- docs/dev_env.md | 202 +++++++-- docs/i18n/vi/CODE_OF_CONDUCT.md | 92 ++-- docs/i18n/vi/CONTRIBUTING.md | 169 +++++--- docs/i18n/vi/DISCLAIMER.md | 123 ++++-- docs/i18n/vi/EULA.md | 140 +++++-- docs/i18n/vi/PrivacyPolicy.md | 282 ++++++++----- docs/i18n/vi/SECURITY.md | 109 +++-- docs/i18n/vi/ToS.md | 237 ++++++----- docs/i18n/vi/dev_env.md | 219 ++++++++-- docs/operations.md | 118 ++++++ webapp/README.md | 270 ++++++++---- webapp/TAURI.md | 132 ++++-- webapp/src-tauri/installer/EULA.rtf | 120 ++++-- webapp/src/lib/about.ts | 4 +- webapp/src/lib/i18n/en.ts | 2 +- webapp/src/lib/i18n/vi.ts | 2 +- 44 files changed, 3905 insertions(+), 1471 deletions(-) create mode 100644 .github/CODEOWNERS create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 LICENSES/CC-BY-4.0.txt create mode 100644 NOTICE.md create mode 100644 data_game/LICENSE.md create mode 100644 docs/operations.md diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..04347f8 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,5 @@ +# Code owners: automatically requested as reviewers on pull requests. +# Solo-maintained project, so the Maintainer owns everything. +# Syntax: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners + +* @poli0981 diff --git a/.github/ISSUE_TEMPLATE/add_games.yml b/.github/ISSUE_TEMPLATE/add_games.yml index 3673c92..5e95694 100644 --- a/.github/ISSUE_TEMPLATE/add_games.yml +++ b/.github/ISSUE_TEMPLATE/add_games.yml @@ -1,12 +1,17 @@ -name: 🎮 Add Games -description: Suggest new free itch.io games (max 15 per issue pls) +name: 🎮 Add Games (bulk list) +description: Got a whole list of free itch.io games? Use this. For one game, the Suggest page is faster. title: "[Add Games] " labels: ["contribution", "games"] body: - type: markdown attributes: value: | - Thanks bro! This repo lives on additions because I'm too lazy to hunt alone :D Only free-to-play itch.io games. + Thanks bro! This catalog lives on additions because I'm too lazy to hunt alone :D Only free-to-play itch.io games. + + **Just one game? Use the Suggest page instead: https://freeitchgames.win/suggest** — no GitHub account needed, and it goes straight into the review queue. + This issue form is the fallback for **bulk lists** (several games at once). + + How it works either way: every link lands in a review queue, and nothing enters the catalog until the Maintainer approves it. Approved links are scraped by the data pipeline; paid games and games already in the catalog are skipped. - type: dropdown id: count @@ -25,7 +30,7 @@ body: attributes: label: Game Links (one per line!) description: | - I'll check (no guarantee perfect). One link per line — two on same line? Your loss :v + itch.io game page links only (like `https://creator.itch.io/game`). One link per line — two on the same line? Your loss :v placeholder: | https://example.itch.io/game1 https://example.itch.io/game2 @@ -41,8 +46,16 @@ body: - type: textarea id: notes attributes: - label: Notes for table? (optional) - description: Personal rating, warnings, etc. — I'll add to "Notes" column + label: Anything the Maintainer should know? (optional) + description: Warnings (adult content, suspicious download, needs an account...), your personal take, etc. The Maintainer may use it for the game's `notes`, `nsfw` or `safe_virus` fields. + + - type: checkboxes + id: checks + attributes: + label: Quick checks (optional) + options: + - label: I searched https://freeitchgames.win/games and these games aren't listed yet + - label: These games are free to play on itch.io (not paid) - type: checkboxes id: agreement @@ -50,4 +63,4 @@ body: label: Agreement (required) options: - label: I agree — if this issue is off-topic, spam, or violates repo policy, it may be ignored/closed without response. - required: true \ No newline at end of file + required: true diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index b01aaa2..bf8e8a6 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -1,12 +1,46 @@ -name: 🐛 Bug Report -description: Report a bug in the list, tables, scripts, or anything broken +name: 🐛 Bug Report +description: Report a bug on the website, in the desktop/Android app, in the game data, or in the scripts title: "[Bug] " labels: ["bug"] body: - type: markdown attributes: value: | - Thanks for reporting! I'm a lazy unemployed dev, so bugs happen a lot :D Grok fixes most, but your help is gold. + Thanks for reporting! I'm a lazy unemployed dev, so bugs happen a lot :D My AI buddies fix most, but your help is gold. + + **Found a security vulnerability?** Please don't file it here — report it privately via https://github.com/poli0981/free-games-itchio-list/security/advisories/new or security@freeitchgames.win. + Want a game removed (or you're its creator)? Use the "Remove a Game" template instead. + + - type: dropdown + id: where + attributes: + label: Where did it happen? + description: Pick all that apply. + multiple: true + options: + - Website (freeitchgames.win) + - Desktop app — Windows + - Desktop app — macOS + - Desktop app — Linux + - Android app + - Game data itself (wrong info, same everywhere) + - Data pipeline / GitHub Actions / scripts + - Not sure + validations: + required: true + + - type: input + id: version + attributes: + label: Version + description: Shown on the About page (website and apps). For the desktop/Android app, the release you installed. + placeholder: e.g. 4.0.0 + + - type: input + id: environment + attributes: + label: Browser / device / OS (if relevant) + placeholder: e.g. Firefox on Windows 11, Safari on macOS 15, Android 13 phone - type: checkboxes id: bug_types @@ -14,13 +48,15 @@ body: label: What kind of bug(s)? (check all that apply) options: - label: Broken/dead link (game page 404 or not loading) - - label: Thumbnail not showing or wrong - - label: Table missing columns or broken format - - label: Wrong game name or dev name - - label: Wrong game count in tables - - label: Wrong genre classification + - label: Cover image not showing or wrong + - label: Wrong game name or developer name + - label: Wrong genre, tags, platforms or other game info - label: Wrong or outdated description - - label: NSFW/Safe flag wrong + - label: NSFW flag or safety note (safe_virus) wrong + - label: Game count or charts look wrong + - label: Page/app crashes, won't load, or layout broken + - label: Search, filters or sorting not working + - label: Suggest page not working - label: Other (must describe below) - type: textarea @@ -28,7 +64,7 @@ body: attributes: label: Details (Game name(s)/URL(s), what happened?) description: | - If "Other" checked, or multiple games — explain here. The more specific, the faster I fix (or Grok does). + What did you do, what did you expect, what happened instead? If "Other" is checked, or multiple games — explain here. The more specific, the faster it gets fixed. validations: required: true @@ -36,17 +72,17 @@ body: id: screenshots attributes: label: Screenshots/Proof (optional but super helpful) - description: Paste links or describe — I believe you, but visuals make me less lazy :D + description: Paste images or links, or describe — I believe you, but visuals make me less lazy :D Please hide any personal info. - - type: checkboxes + - type: dropdown id: urgency attributes: label: Urgency level? options: - - label: Low (annoying but not critical) - - label: Medium (affects some games) - - label: High (breaks tables or many games) - - label: Critical (whole repo broken) + - Low (annoying but not critical) + - Medium (affects some games or one page) + - High (breaks a whole page or many games) + - Critical (website or app unusable) - type: checkboxes id: agreement @@ -55,4 +91,4 @@ body: description: I gotta cover my lazy ass :D options: - label: I agree — if this issue is off-topic, spam, or violates repo policy, it may be ignored/closed without response. - required: true \ No newline at end of file + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..4936c30 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: 🎮 Suggest a game (fastest way) + url: https://freeitchgames.win/suggest + about: Suggest one free itch.io game right on the website, no GitHub account needed. Every suggestion is reviewed by the Maintainer before it enters the catalog. + - name: 🔒 Report a security vulnerability (private) + url: https://github.com/poli0981/free-games-itchio-list/security/advisories/new + about: Please report vulnerabilities privately here (or email security@freeitchgames.win), never in a public issue. diff --git a/.github/ISSUE_TEMPLATE/remove_game.yml b/.github/ISSUE_TEMPLATE/remove_game.yml index 243d630..3251913 100644 --- a/.github/ISSUE_TEMPLATE/remove_game.yml +++ b/.github/ISSUE_TEMPLATE/remove_game.yml @@ -1,12 +1,17 @@ -name: 🚫 Remove Games -description: Request to remove games from the list (max 10 per issue) +name: 🚫 Remove a Game (or copyright request) +description: Ask to remove games from the catalog or correct their data, including requests from creators and rights holders (max 10 per issue) title: "[Remove Games] " labels: ["removal"] body: - type: markdown attributes: value: | - Sad to see them go, but ok! Max 10 because I'm lazy :D + Sad to see them go, but ok! Max 10 per issue because I'm lazy :D + + **This issue is public.** Don't post private contact details or anything confidential here. + Prefer to keep it private? Email **takedown@freeitchgames.win** instead, with the game URL, who you are (creator, rights holder, or someone authorized to act for them) and the reason. + + What happens next (for a removal): the Maintainer removes the record from the catalog (the removal and its reason are logged in the public list of removed games at https://freeitchgames.win/removed), deletes the resized cover copies the website stores, and cached copies expire from Cloudflare's cache. Older versions stay in the public git history. Target: within 7 days; urgent legal requests sooner. - type: dropdown id: count @@ -22,8 +27,11 @@ body: - type: textarea id: games attributes: - label: Game Name(s) or Link(s) - description: List them — one per line or clear + label: Game Link(s) + description: itch.io links work best (game names are ok too). One per line. + placeholder: | + https://example.itch.io/game1 + https://example.itch.io/game2 validations: required: true @@ -38,6 +46,8 @@ body: - label: Don't like it anymore - label: Potential malware/virus - label: I'm the dev and don't want it listed + - label: I'm the dev and the data shown is wrong (please correct it instead of removing) + - label: Copyright / rights-holder request (fill in the section below) - label: Other (describe below) validations: required: true @@ -45,7 +55,46 @@ body: - type: textarea id: other_reason attributes: - label: If "Other" — explain here + label: Details / if "Other" — explain here + description: For a correction, say which field is wrong and what it should be. + + - type: markdown + attributes: + value: | + --- + ### Copyright / rights-holder section (optional) + Fill this in only if you are the creator or rights holder of the listed game (or authorized to act for them), for example when your description text or cover image is shown here and you want it removed. + Game descriptions and cover images remain the property of their creators; the catalog only copies what is on the public itch.io page. + + - type: input + id: rights_holder + attributes: + label: Your name, studio or itch.io account, and your role + description: e.g. "Creator, itch.io account example" or "Publisher, authorized by the developer". Public — no private contact details please. + + - type: checkboxes + id: affected + attributes: + label: Which content is affected? + options: + - label: The whole listing + - label: Description text + - label: Cover image / thumbnail + - label: Game name, logo or trademark + - label: Something else (explain below) + + - type: textarea + id: claim + attributes: + label: Details of the request + description: Where the original work lives (e.g. your itch.io page) and what you want done. + + - type: checkboxes + id: rights_confirmation + attributes: + label: Confirmation (copyright requests only) + options: + - label: I am the creator or rights holder of the content above, or authorized to act for them, and the information in this issue is accurate. - type: checkboxes id: agreement @@ -53,4 +102,4 @@ body: label: Agreement (required) options: - label: I agree — if this issue is off-topic, spam, or violates repo policy, it may be ignored/closed without response. - required: true \ No newline at end of file + required: true diff --git a/.github/PULL_REQUEST_TEMPLATE/add_games.md b/.github/PULL_REQUEST_TEMPLATE/add_games.md index d2669c4..f4f0f45 100644 --- a/.github/PULL_REQUEST_TEMPLATE/add_games.md +++ b/.github/PULL_REQUEST_TEMPLATE/add_games.md @@ -1,20 +1,19 @@ **🎮 Add New Games** -Thanks for feeding the list! (Normally I prefer the "Add Games" issue template so Actions auto-scrape, but PR direct to game_info.json also works if you wanna be extra :D) +Thanks for feeding the list! Easiest ways first: one game → the Suggest page (https://freeitchgames.win/suggest, no GitHub needed); a bulk list → the "Add Games" issue template. A PR also works if you wanna be extra :D + +**How to add games in a PR:** put the itch.io game URLs in `scripts/temp_link.json` (a JSON array of URL strings). Please don't edit `data_game/` by hand — the pipeline writes it. Merging the PR is the Maintainer's approval; the ingest workflow (`update.yml`) then scrapes each link and adds the free ones. Paid games and games already in the catalog are skipped. ### Games Added List the itch.io URLs (free-to-play only!): ### Why these games? -Optional: short notes, why they rock, NSFW/safe concerns. - -### Description -How you added them (manual edit game_info.json? scraped yourself?). Keep format consistent! +Optional: short notes, why they rock, NSFW/safety concerns (the Maintainer sets the `nsfw`, `safe_virus` and `notes` fields). ### Checklist -- [ ] All links are free itch.io games -- [ ] No duplicates (check existing) -- [ ] Format correct (json valid, fields match) -- [ ] `python scripts/validate.py` passes +- [ ] All links are free itch.io game pages +- [ ] No duplicates (searched https://freeitchgames.win/games) +- [ ] Only `scripts/temp_link.json` changed, and it's still valid JSON +- [ ] I agree my contribution is licensed under CC BY 4.0, like the rest of the catalog data (`data_game/LICENSE.md`) -You're making this boredom project bigger — legend status unlocked! 🚀 \ No newline at end of file +You're making this boredom project bigger — legend status unlocked! 🚀 diff --git a/.github/PULL_REQUEST_TEMPLATE/bug_fix.md b/.github/PULL_REQUEST_TEMPLATE/bug_fix.md index d5cd6ea..230451b 100644 --- a/.github/PULL_REQUEST_TEMPLATE/bug_fix.md +++ b/.github/PULL_REQUEST_TEMPLATE/bug_fix.md @@ -3,12 +3,12 @@ Thanks for fixing my mediocre code! I'm just an unemployed noob dev, so bugs are my specialty :D ### What bug did you fix? -- [ ] Broken link / wrong info in list -- [ ] Wrong NSFW/Safe flag -- [ ] Genre classification error +- [ ] Wrong game info or NSFW/safety flag (usually easier as a Bug Report issue — please don't hand-edit `data_game/`, the pipeline writes it) - [ ] Scraping failure (itch.io changed HTML again) -- [ ] Generate MD tables broken (split/part wrong) -- [ ] GitHub Actions fail +- [ ] Data pipeline / GitHub Actions fail +- [ ] Website bug (`webapp/src/`) +- [ ] Worker bug (`webapp/worker/` — image proxy, Suggest API, admin API) +- [ ] Desktop/Android app (Tauri) bug - [ ] Other (describe below) ### Description @@ -18,8 +18,10 @@ Explain the bug and how your fix works. Bonus points if you tested locally! Closes # (link issue number if any) ### Checklist -- [ ] Tested locally (`pytest`, `python scripts/validate.py`) +- [ ] Tested locally — Python: `pytest`, `ruff check scripts tests webapp/scripts`, `python scripts/validate.py`; webapp: `npm test`, `npm run lint`, `npx tsc -b` - [ ] No new bugs introduced (hopefully) +- [ ] No secrets, tokens or personal data in the diff +- [ ] I agree my contribution is licensed under the MIT License (see `LICENSE`) - [ ] Followed the vibe (chill, no drama) -Grok approved? (just kidding, but thanks legend!) 🚀 \ No newline at end of file +Grok approved? (just kidding, but thanks legend!) 🚀 diff --git a/.github/PULL_REQUEST_TEMPLATE/documentation.md b/.github/PULL_REQUEST_TEMPLATE/documentation.md index ce4b5f0..bc39926 100644 --- a/.github/PULL_REQUEST_TEMPLATE/documentation.md +++ b/.github/PULL_REQUEST_TEMPLATE/documentation.md @@ -4,7 +4,8 @@ Not code or games? Fix my bad English, typos, or update legal docs — still sup ### What did you update? - [ ] Fix typo/grammar in README/docs -- [ ] Update DISCLAIMER/PRIVACY/TERMS/etc. +- [ ] Update DISCLAIMER/PRIVACY/TERMS/EULA/SECURITY/etc. +- [ ] Update the Vietnamese mirror (`README.vi.md`, `docs/i18n/vi/`) - [ ] Improve MY_STUFF or ACKNOWLEDGEMENTS - [ ] Add badges/screenshots - [ ] Other small polish @@ -17,6 +18,9 @@ References # (if any) ### Checklist - [ ] No breaking changes +- [ ] Relative links still resolve; website links use `https://freeitchgames.win/` +- [ ] If I changed an English doc that has a Vietnamese mirror, I updated the mirror too (or said so above so someone else can) +- [ ] I agree my contribution is licensed under CC BY 4.0, like the rest of the documentation - [ ] Keeps the self-deprecating vibe :D -Even small fixes make this repo look less noob — thanks bro! 🚀 \ No newline at end of file +Even small fixes make this repo look less noob — thanks bro! 🚀 diff --git a/.github/PULL_REQUEST_TEMPLATE/new_features.md b/.github/PULL_REQUEST_TEMPLATE/new_features.md index 75e2ddd..b17d5c6 100644 --- a/.github/PULL_REQUEST_TEMPLATE/new_features.md +++ b/.github/PULL_REQUEST_TEMPLATE/new_features.md @@ -2,11 +2,14 @@ Yo legend! My code is "kinda works" level, so any upgrade is huge. Grok helps me, but real humans are better :D +Heads-up: the website and apps are read-only for visitors on purpose — no accounts, no ads, no profiling, no telemetry in the apps. Features that would add those (or new cookies, or a new third-party service) need a chat in an issue first, since the Privacy Policy would have to change. + ### What feature/improvement? - [ ] Better scraping (more info, rating, etc.) -- [ ] Prettier tables (new columns, better split) -- [ ] Auto stuff (badge, index README, search?) -- [ ] Performance fix (faster Actions) +- [ ] Website/app UI (new page, filter, chart, better mobile layout) +- [ ] Desktop/Android app (Tauri) +- [ ] Automation (pipeline, GitHub Actions) +- [ ] Performance fix (faster pages, faster Actions) - [ ] Refactor my messy code - [ ] Other (describe) @@ -17,8 +20,11 @@ Explain what it does and why it's cool. Include code snippets if needed. References # (link if any) ### Checklist -- [ ] Tested locally -- [ ] Doesn't break daily update +- [ ] Tested locally (Python: `pytest`, `ruff check scripts tests webapp/scripts`; webapp: `npm test`, `npm run lint`, `npm run knip`, `npx tsc -b`) +- [ ] Doesn't break the daily refresh or the ingest workflow +- [ ] New npm dependency? Added it to `webapp/src/lib/about.ts` so the About page lists it +- [ ] Edited `webapp/wrangler.jsonc`? Ran `npm run cf:types` +- [ ] I agree my contribution is licensed under the MIT License (see `LICENSE`) - [ ] Keeps the noob vibe intact -If this makes the repo less mediocre — you're the MVP. 🚀 \ No newline at end of file +If this makes the repo less mediocre — you're the MVP. 🚀 diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 56735af..12eeb49 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -11,10 +11,7 @@ updates: timezone: Asia/Ho_Chi_Minh cooldown: default-days: 3 - # The v4 rewrite of webapp/ is in progress on its own branch: routine - # version bumps on main would only conflict with it. Security updates still - # arrive. After go-live, raise this limit again. - open-pull-requests-limit: 0 + open-pull-requests-limit: 5 groups: react: patterns: ['react', 'react-dom', '@types/react*', 'react-router*'] diff --git a/CHANGELOG.md b/CHANGELOG.md index 9ed060b..9e6fe4f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,14 +2,74 @@ All notable changes to this project will be documented here. -## [Unreleased] +## [4.0.0] - Unreleased (freeitchgames.win on Cloudflare: read-only site, review queue, new pipeline) + +Version 4 moves the website to **https://freeitchgames.win** on Cloudflare, makes it read-only for +everyone (no sign-in), adds a maintainer-only admin with a review queue for new games, replaces the +failing data crawls with a rotating refresh, and splits the licenses (code MIT, data and docs +CC BY 4.0). + +### Upgrade notes + +- **The web app no longer signs in or edits.** The GitHub-token (PAT) sign-in, in-app editing, the + Add / Workflows pages and GPG commit signing are gone; on first load the app deletes the + encrypted token and key it stored before. Suggest games at https://freeitchgames.win/suggest. +- **Old links keep working**: `…github.io/free-games-itchio-list/#/x` redirects to the new site, + and `#/x` links become `/x`. +- **Desktop and Android apps** are read-only viewers too; they read the catalog from + freeitchgames.win. Install 4.0.0 over 3.x as usual. +- **New legal terms** (ToS, Privacy Policy, EULA for the apps only, Disclaimer): the site asks you to + accept them again once. + +### Website & Worker + +- The site is served by a Cloudflare Worker with static assets ([`webapp/wrangler.jsonc`](webapp/wrangler.jsonc), + [`webapp/worker/`](webapp/worker)) and the catalog JSON is bundled into every build (`/data/*`, + plus a sitemap), so each data commit republishes the site; the desktop/Android apps read the same + files. Real URL paths instead of `#/` routes, per-page canonical URLs, and real 404s for unknown + pages and missing files (a stale script after a deploy can no longer be cached as HTML). +- **Cover images** are resized once to small WebP copies (Cloudflare Image Transformations + R2) + and served from `/img/…` — about 4 KB instead of up to 3 MB per cover. Only catalog covers are + served. +- **18+ games are hidden by default**; a visitor can show them in Settings after confirming they + are 18 or older (stored only in their browser). The removed-games page is now `/removed` + (`/deleted` redirects there). Aggregate, cookieless Cloudflare Web Analytics. +- Enforced Content-Security-Policy and security headers; faster first load (~195 KB gzip, charts + load only when opened); browser floor Safari/iOS 15.4. +- React Router 8, React 19.3, Vite 8 (rolldown), vitest; unused sign-in dependencies (Octokit, + OpenPGP.js) removed; Tauri drops its HTTP plugin and `Cargo.lock` is committed. + +### Adding games: review queue + +- **Suggest page** (`/suggest`): anyone can send an itch.io link (+ optional note); protected by + Cloudflare Turnstile and a rate limit. +- **Browser extension API** (`POST /api/ingest`, Cloudflare Access service token, idempotent) — + the extension no longer needs a GitHub token. +- **RSS discovery**: every 4 hours the Worker reads one itch.io "new & popular free" feed. +- Everything lands in a **review queue** (Cloudflare D1). The maintainer approves or rejects it in + the new **admin** (`/admin`, Cloudflare Access), which also edits the three maintainer fields, + removes games with a public reason (deleting their resized covers) and restores removed games. + Approved games are committed by a GitHub App (verified commits) and scraped by the pipeline. + +### Licenses & legal + +- Code stays **MIT** (`LICENSE`, now "2025-2026 poli0981 (SkullMute)"); the catalog data + ([`data_game/LICENSE.md`](data_game/LICENSE.md)) and the documentation are **CC BY 4.0** + ([`LICENSES/CC-BY-4.0.txt`](LICENSES/CC-BY-4.0.txt)); creators' descriptions, cover images and + trademarks are excluded. [`NOTICE.md`](NOTICE.md) sums it up: not affiliated with itch.io. +- Rewritten Terms of Use (with a content-removal process), Privacy Policy (Cloudflare as + processor, exact browser storage, retention, rights under Vietnam's Law No. 91/2025/QH15 and the + GDPR), Disclaimer, Security Policy and Code of Conduct, in English and Vietnamese. The EULA now + covers only the desktop and Android apps. Contact addresses: legal@, privacy@, security@ and + takedown@freeitchgames.win. +- Issue templates: "Add games" points to the Suggest page, "Remove a game" gained a + rights-holder section; `CODEOWNERS` added. ### Fixed - **freeitchgames.win served the unbuilt `webapp/` source tree** (blank page; `/package.json`, - `/src/*` publicly readable). Added [`webapp/wrangler.jsonc`](webapp/wrangler.jsonc) (Workers - static assets, SPA fallback, `workers_dev`/`preview_urls` off) and moved the Vite web build to - `webapp/dist` so Cloudflare Workers Builds deploys the real build. + `/src/*` publicly readable). The Vite web build now goes to `webapp/dist`, which + [`webapp/wrangler.jsonc`](webapp/wrangler.jsonc) deploys (`workers_dev`/`preview_urls` off). - **All 15 Dependabot alerts / npm audit** — lockfile refreshed in-range (vite 8.3.0, react-router-dom 7.18.4, postcss 8.5.28, patched transitive deps); `npm audit` reports 0. - **Android release workflow** moved off Node 20 actions (setup-java v6, upload-artifact v7, @@ -59,8 +119,10 @@ All notable changes to this project will be documented here. - `lists/*.md` genre tables, `generate_md.py`, `generate_table.yml`, `deleted_games.txt`, `log_deleted.*` — the catalog is web-only (freeitchgames.win). -- Telegram bot ingest (`bot-ingest.yml`, `game_via_bot` issue template); the policies mark that - path as retired. +- Telegram bot ingest (`bot-ingest.yml`, `game_via_bot` issue template) — retired. +- The web app's sign-in, editing, Add and Workflows pages, GPG signing, and the GitHub Pages + deployment (`deploy_webapp.yml`, `notify-deploy.yml`, `pages-redirect/`; Pages keeps serving the + redirect stub it last published). - `notify-ci-failure.yml` (replaced by in-workflow notifications) and the old per-task bash wrappers. ### CI / security @@ -81,16 +143,11 @@ All notable changes to this project will be documented here. ### Changed -- GitHub Pages now only publishes a redirect stub ([`pages-redirect/`](pages-redirect)) that - forwards to freeitchgames.win (keeping `#/` routes) and deletes the old app's PAT/GPG keys from - that origin. `notify-deploy.yml` removed. -- Static-asset security headers in [`webapp/public/_headers`](webapp/public/_headers) - (Referrer-Policy, frame denial, Permissions-Policy, COOP; CSP in report-only mode for now) and - immutable caching for hashed `/assets/*`. -- Scraper workflows print unbuffered UTF-8 logs. The schedules of `check_paid`, `check_alive`, - `update_reviews` and `update_status` are paused (manual dispatch only): full passes over 2,600+ - games exceed their timeouts and lose all work. A rotating refresh replaces them next. -- Privacy Policy: interim Cloudflare hosting notice (§3a); dead `…/app/` links repointed. +- The old GitHub Pages address serves a redirect stub that forwards to freeitchgames.win + (keeping `#/` routes) and deletes the old app's token and key storage on that origin. +- Security headers in [`webapp/public/_headers`](webapp/public/_headers) (CSP, Referrer-Policy, + frame denial, Permissions-Policy, COOP) and immutable caching for hashed `/assets/*`. +- Pipeline logs are unbuffered UTF-8. ## [3.9.0] - 2026-06-15 (Android minSdk → 11 / API 30) @@ -271,7 +328,7 @@ All notable changes to this project will be documented here. - a route-level **ErrorBoundary** that detects stale-chunk failures after a redeploy and offers a one-click reload ("New version available"), - a hidden `/#/errors/:code` preview route, - - a static [`webapp/public/404.html`](webapp/public/404.html) served by + - a static `webapp/public/404.html` served by GitHub Pages for bad path URLs (bilingual, dark-mode aware, zero JS). ### Changed @@ -360,7 +417,7 @@ All notable changes to this project will be documented here. ### Added - **Six new charts on `/charts`.** - - **Game count over time** — a `LineChart` of the catalog size by day, backed by a new `data_game/count_history.json` (date-keyed `{date, total}` series). [`scripts/data_store.py`](scripts/data_store.py) `_append_count_history()` upserts today's total on every catalog write (last-write-wins per UTC day). [`scripts/backfill_count_history.py`](scripts/backfill_count_history.py) is a one-time dev tool that reconstructs the series from git history (`data_game/index.json`, plus the pre-refactor `scripts/game_info.json`). The webapp loads it via `loadCountHistory` / `useCountHistory`. + - **Game count over time** — a `LineChart` of the catalog size by day, backed by a new `data_game/count_history.json` (date-keyed `{date, total}` series). [`scripts/data_store.py`](scripts/data_store.py) `_append_count_history()` upserts today's total on every catalog write (last-write-wins per UTC day). `scripts/backfill_count_history.py` is a one-time dev tool that reconstructs the series from git history (`data_game/index.json`, plus the pre-refactor `scripts/game_info.json`). The webapp loads it via `loadCountHistory` / `useCountHistory`. - **Genre treemap** — a Recharts `Treemap` with a custom cell renderer that hides labels on rectangles too small to fit them, so it stays legible on mobile. - **KPI summary cards** — total games / online / NSFW / deleted / average rating, above the Overview grid. - **Deletions over time** (bar, by month), **Deletion reasons** (pie: became-paid vs page-removed), and **Most rated games** (top 10 by `rating_count`). @@ -407,14 +464,14 @@ All notable changes to this project will be documented here. ### Added -- **Update reviews — bi-weekly workflow.** New [`scripts/update_reviews.py`](scripts/update_reviews.py), wrapper [`bash/update_reviews.sh`](bash/update_reviews.sh), and [`.github/workflows/update_reviews.yml`](.github/workflows/update_reviews.yml) re-scrape every existing game's itch.io page on the 1st and 15th of each month (05:00 UTC) and write fresh `rating` + `rating_count`. Network errors / 404 keep the old values. Touches only those two fields — everything else (annotations, metadata) is left alone. -- **Update status — monthly workflow.** New [`scripts/update_status.py`](scripts/update_status.py), [`bash/update_status.sh`](bash/update_status.sh), and [`.github/workflows/update_status.yml`](.github/workflows/update_status.yml) refresh the `status` field on the 1st of each month (06:00 UTC). Same skip-on-error semantics. -- **Force update — manual emergency button.** New [`scripts/force_update.py`](scripts/force_update.py), [`bash/force_update.sh`](bash/force_update.sh), and [`.github/workflows/force_update.yml`](.github/workflows/force_update.yml) accept an optional `url` input. Empty input re-scrapes every game; a single URL targets just that one. `workflow_dispatch` only — no schedule. Every run preserves the three user-editable annotations (`safe_virus`, `notes`, `nsfw`) per the read/write field convention in [CLAUDE.md](CLAUDE.md). Doubles as the canonical repair tool for mojibake left by older webapp commits — re-scrape pulls clean UTF-8 from itch.io. +- **Update reviews — bi-weekly workflow.** New `scripts/update_reviews.py`, wrapper `bash/update_reviews.sh`, and `.github/workflows/update_reviews.yml` re-scrape every existing game's itch.io page on the 1st and 15th of each month (05:00 UTC) and write fresh `rating` + `rating_count`. Network errors / 404 keep the old values. Touches only those two fields — everything else (annotations, metadata) is left alone. +- **Update status — monthly workflow.** New `scripts/update_status.py`, `bash/update_status.sh`, and `.github/workflows/update_status.yml` refresh the `status` field on the 1st of each month (06:00 UTC). Same skip-on-error semantics. +- **Force update — manual emergency button.** New `scripts/force_update.py`, `bash/force_update.sh`, and [`.github/workflows/force_update.yml`](.github/workflows/force_update.yml) accept an optional `url` input. Empty input re-scrapes every game; a single URL targets just that one. `workflow_dispatch` only — no schedule. Every run preserves the three user-editable annotations (`safe_virus`, `notes`, `nsfw`) per the read/write field convention in [CLAUDE.md](CLAUDE.md). Doubles as the canonical repair tool for mojibake left by older webapp commits — re-scrape pulls clean UTF-8 from itch.io. - **`generate_table.yml` chained on the three new workflows** so `lists/*.md` stay in sync after any data mutation. ### Fixed -- **UTF-8 mojibake on webapp commits.** [`webapp/src/lib/github/contents.ts`](webapp/src/lib/github/contents.ts) `readFileWithSha` and [`webapp/src/lib/github/git-data.ts`](webapp/src/lib/github/git-data.ts) `bulkDeleteGames` were decoding GitHub's base64 content with `atob` alone, producing a Latin-1 binary string. Multi-byte UTF-8 sequences (e.g. Vietnamese `ã` = `0xC3 0xA3`) became two Latin-1 code points (`ã`); the next write re-encoded them as UTF-8 bytes, double-corrupting on every edit. Confirmed live damage in `data_game/game_info_002.json` (`BotÃÂão Esquerdo` was originally `Botão Esquerdo`). Extracted a shared helper [`webapp/src/lib/github/encoding.ts`](webapp/src/lib/github/encoding.ts) (`base64ToUtf8` / `utf8ToBase64`) that uses `TextDecoder('utf-8')` / `TextEncoder` and routes both call sites through it. Write path was already correct. +- **UTF-8 mojibake on webapp commits.** `webapp/src/lib/github/contents.ts` `readFileWithSha` and `webapp/src/lib/github/git-data.ts` `bulkDeleteGames` were decoding GitHub's base64 content with `atob` alone, producing a Latin-1 binary string. Multi-byte UTF-8 sequences (e.g. Vietnamese `ã` = `0xC3 0xA3`) became two Latin-1 code points (`ã`); the next write re-encoded them as UTF-8 bytes, double-corrupting on every edit. Confirmed live damage in `data_game/game_info_002.json` (`BotÃÂão Esquerdo` was originally `Botão Esquerdo`). Extracted a shared helper `webapp/src/lib/github/encoding.ts` (`base64ToUtf8` / `utf8ToBase64`) that uses `TextDecoder('utf-8')` / `TextEncoder` and routes both call sites through it. Write path was already correct. ### Notes @@ -428,15 +485,15 @@ All notable changes to this project will be documented here. ### Added -- **In-browser GPG commit signing.** Every write the webapp makes (single-file edits, bulk edit/delete, queueing URLs) can now be GPG-signed client-side. New `webapp/src/lib/gpg/` module: [`canonicalize.ts`](webapp/src/lib/gpg/canonicalize.ts) builds the exact byte string Git would hash, [`sign.ts`](webapp/src/lib/gpg/sign.ts) lazy-imports `openpgp` and exposes `loadPrivateKey` / `signCommit` / `verifyDetached`, [`storage.ts`](webapp/src/lib/gpg/storage.ts) wraps localStorage helpers. Verified byte-for-byte against `git cat-file commit ` so the signed canonical exactly matches what GitHub will recompute (no trailing-newline drift). Private keys are decrypted once at import and re-encrypted with the webapp passphrase (AES-GCM, same scheme as the PAT) — `openpgp` is loaded only when the Commit Signing card is opened or a commit is being signed (`vendor-openpgp` chunk, ~129 KB gz, lazy). -- **Settings → Commit signing card.** New [`webapp/src/components/settings/gpg-card.tsx`](webapp/src/components/settings/gpg-card.tsx) — three states (not configured / locked / unlocked) with Import (paste armored or upload `.asc`), Unlock, Test sign (round-trip verify), Copy public key, Lock, Remove. Shows the imported key's UIDs as badges and flags a clear mismatch warning if the configured commit-author email isn't in the key's UID list (the most common cause of GitHub's "Someone may be trying to trick you" warning). After import, primary UID email auto-populates Commit author so commits Verify on the first try. -- **Settings Phase A — Appearance / Session / Commit author / Notifications cards.** [`webapp/src/routes/settings.tsx`](webapp/src/routes/settings.tsx) gained four new cards backed by extended preferences in [`webapp/src/stores/prefs.ts`](webapp/src/stores/prefs.ts): theme picker (Light / Dark / System), layout density (Normal / Compact), sidebar collapse mirror, idle-timeout slider (5 / 15 / 30 / 60 / 120 min — replaces the hard-coded 30-min constant in [`auth.ts`](webapp/src/stores/auth.ts)), commit-author name/email override, toast enable + duration. Density applies via `html[data-density='compact']` rules in [`index.css`](webapp/src/index.css); toasts are gated through a new [`AppToaster`](webapp/src/components/app-toaster.tsx) wrapper that reads prefs. +- **In-browser GPG commit signing.** Every write the webapp makes (single-file edits, bulk edit/delete, queueing URLs) can now be GPG-signed client-side. New `webapp/src/lib/gpg/` module: `canonicalize.ts` builds the exact byte string Git would hash, `sign.ts` lazy-imports `openpgp` and exposes `loadPrivateKey` / `signCommit` / `verifyDetached`, `storage.ts` wraps localStorage helpers. Verified byte-for-byte against `git cat-file commit ` so the signed canonical exactly matches what GitHub will recompute (no trailing-newline drift). Private keys are decrypted once at import and re-encrypted with the webapp passphrase (AES-GCM, same scheme as the PAT) — `openpgp` is loaded only when the Commit Signing card is opened or a commit is being signed (`vendor-openpgp` chunk, ~129 KB gz, lazy). +- **Settings → Commit signing card.** New `webapp/src/components/settings/gpg-card.tsx` — three states (not configured / locked / unlocked) with Import (paste armored or upload `.asc`), Unlock, Test sign (round-trip verify), Copy public key, Lock, Remove. Shows the imported key's UIDs as badges and flags a clear mismatch warning if the configured commit-author email isn't in the key's UID list (the most common cause of GitHub's "Someone may be trying to trick you" warning). After import, primary UID email auto-populates Commit author so commits Verify on the first try. +- **Settings Phase A — Appearance / Session / Commit author / Notifications cards.** [`webapp/src/routes/settings.tsx`](webapp/src/routes/settings.tsx) gained four new cards backed by extended preferences in [`webapp/src/stores/prefs.ts`](webapp/src/stores/prefs.ts): theme picker (Light / Dark / System), layout density (Normal / Compact), sidebar collapse mirror, idle-timeout slider (5 / 15 / 30 / 60 / 120 min — replaces the hard-coded 30-min constant in `auth.ts`), commit-author name/email override, toast enable + duration. Density applies via `html[data-density='compact']` rules in [`index.css`](webapp/src/index.css); toasts are gated through a new [`AppToaster`](webapp/src/components/app-toaster.tsx) wrapper that reads prefs. - **Mobile card view for the games table.** New [`webapp/src/lib/use-is-mobile.ts`](webapp/src/lib/use-is-mobile.ts) (`matchMedia('(max-width: 767px)')`) and [`webapp/src/components/data-table/mobile-card-list.tsx`](webapp/src/components/data-table/mobile-card-list.tsx). Below the `md` breakpoint, [`DataTable`](webapp/src/components/data-table/data-table.tsx) renders a stacked card list (thumbnail + name + dev + genre/status/NSFW/safe badges, tap-to-detail, selection checkbox) instead of the 9-column virtualized table that overflowed at 430 px. Pagination is shared between both views. -- **Workflows route mobile fallback.** [`workflows.tsx`](webapp/src/routes/workflows.tsx) now dual-renders the action picker — a `` dropdown below `md`, the existing `TabsList` at `md` and above. Fixes the overflow from five `whitespace-nowrap` triggers in an `inline-flex` TabsList at 430 px viewport. ### Changed -- **All write paths route through the Git Data API.** [`webapp/src/lib/github/contents.ts`](webapp/src/lib/github/contents.ts) `putFile` (`PUT /repos/.../contents/{path}`) is gone — that endpoint authors commits as the PAT and never accepts a `signature` field. Replaced with `commitSingleFile` which delegates to [`atomicCommit`](webapp/src/lib/github/git-data.ts) so single-file edits (game annotations, `temp_link.json` queue) get the same signer plumbing as bulk operations. `atomicCommit` gained an optional `signer` parameter (defaulting to [`getSignerIfEnabled()`](webapp/src/lib/github/signer.ts)) that, when present, builds the canonical commit object, signs detached binary-mode via openpgp, and passes `author` / `committer` / `signature` to `git.createCommit`. Commit author identity falls back through prefs override → imported key's primary UID email → GitHub user. +- **All write paths route through the Git Data API.** `webapp/src/lib/github/contents.ts` `putFile` (`PUT /repos/.../contents/{path}`) is gone — that endpoint authors commits as the PAT and never accepts a `signature` field. Replaced with `commitSingleFile` which delegates to `atomicCommit` so single-file edits (game annotations, `temp_link.json` queue) get the same signer plumbing as bulk operations. `atomicCommit` gained an optional `signer` parameter (defaulting to `getSignerIfEnabled()`) that, when present, builds the canonical commit object, signs detached binary-mode via openpgp, and passes `author` / `committer` / `signature` to `git.createCommit`. Commit author identity falls back through prefs override → imported key's primary UID email → GitHub user. - **About page** lists `OpenPGP.js` 6.3 under Data dependencies; the [`webapp/vite.config.ts`](webapp/vite.config.ts) `manualChunks` rule emits a dedicated `vendor-openpgp` chunk so the cost is only paid when a user opens the signing card. - **README + README.vi badges** bumped to `3.3.0`. @@ -467,20 +524,20 @@ All notable changes to this project will be documented here. - **Mobile drawer navigation.** New [`webapp/src/components/ui/sheet.tsx`](webapp/src/components/ui/sheet.tsx) (shadcn pattern over the existing `@radix-ui/react-dialog`) and a `MobileTopBar` in [`webapp/src/components/sidebar.tsx`](webapp/src/components/sidebar.tsx). Below `md`, the sidebar collapses behind a hamburger; above, the desktop sidebar behaves as before. Touch targets in the nav now meet the 44pt iOS HIG minimum on small screens. - **DataTable column priorities.** Each column declares `meta.priority: 1 | 2 | 3` in [`columns.tsx`](webapp/src/components/data-table/columns.tsx). [`data-table.tsx`](webapp/src/components/data-table/data-table.tsx) hides priority 2 below `md` and priority 3 below `lg`, so the table is usable on a phone without horizontal scrolling through every column. - **PWA manifest + icons.** [`webapp/public/manifest.webmanifest`](webapp/public/manifest.webmanifest), [`icon-192.png`](webapp/public/icon-192.png), [`icon-512.png`](webapp/public/icon-512.png) — Add to Home Screen on iOS without a service worker. Generator script: [`webapp/scripts/gen_assets.py`](webapp/scripts/gen_assets.py). -- **SEO infrastructure.** [`webapp/index.html`](webapp/index.html) now ships description, theme-color (per scheme), Open Graph (title/description/image/url/type/locale), Twitter card (`summary_large_image`), `canonical`, `apple-touch-icon`, `manifest`, and `preconnect` to `img.itch.zone` + `raw.githubusercontent.com`. [`robots.txt`](webapp/public/robots.txt) and [`sitemap.xml`](webapp/public/sitemap.xml) added under `webapp/public/`. +- **SEO infrastructure.** [`webapp/index.html`](webapp/index.html) now ships description, theme-color (per scheme), Open Graph (title/description/image/url/type/locale), Twitter card (`summary_large_image`), `canonical`, `apple-touch-icon`, `manifest`, and `preconnect` to `img.itch.zone` + `raw.githubusercontent.com`. [`robots.txt`](webapp/public/robots.txt) and `sitemap.xml` added under `webapp/public/`. - **OG image.** [`webapp/public/og.png`](webapp/public/og.png) (1200×630) + [`og.webp`](webapp/public/og.webp) generated by `gen_assets.py`. Brand-coloured (`#863bff` purple, cyan accent) with project name, tagline, and URL. - **Per-route titles.** New [`useDocumentTitle`](webapp/src/hooks/useDocumentTitle.ts) hook (no `react-helmet-async` dependency). Each route now sets a contextual title (`Charts — Itch.io Free Games Database`, etc.); game-detail uses the game name. - **Hash-anchor scroll.** [`App.tsx`](webapp/src/App.tsx) now wires a `ScrollToHash` listener so links like `/about#support` scroll to the matching element under HashRouter. - **About page Telegram entries.** New `messaging` social group with **Telegram (DM)** and **Telegram bot (game submission)** plus a privacy reminder to never paste a numeric ID into public channels. About also surfaces all five FUNDING.yml destinations (GitHub Sponsors, Patreon, Ko-fi, Buy Me a Coffee, PayPal) with a footnote on PayPal explaining the legal-name receipt. - **Sidebar Support link.** Persistent heart-icon link from the sidebar (collapsed and expanded) to `/about#support`. -- **Telegram bot contribution flow.** [`CONTRIBUTING.md §1b`](CONTRIBUTING.md#1b-add-games-via-telegram-bot-my_skull_bot--alternative-to-issues) describes the bot path (DM owner → numeric ID added to local whitelist → bot dispatches `bot-ingest.yml`). Cross-linked from [README.md](README.md), [README.vi.md](README.vi.md), and the new [issue template `game_via_bot.yml`](.github/ISSUE_TEMPLATE/game_via_bot.yml). Vietnamese mirror in [`docs/i18n/vi/CONTRIBUTING.md`](docs/i18n/vi/CONTRIBUTING.md). +- **Telegram bot contribution flow.** `CONTRIBUTING.md §1b` describes the bot path (DM owner → numeric ID added to local whitelist → bot dispatches `bot-ingest.yml`). Cross-linked from [README.md](README.md), [README.vi.md](README.vi.md), and the new issue template `game_via_bot.yml`. Vietnamese mirror in [`docs/i18n/vi/CONTRIBUTING.md`](docs/i18n/vi/CONTRIBUTING.md). - **Privacy + ToS clauses for the bot path.** [`docs/ToS.md §14`](docs/ToS.md) and [`docs/PrivacyPolicy.md §15`](docs/PrivacyPolicy.md) (plus VI mirrors) document Telegram-ID handling: opt-in, operator-side whitelist only, never committed to this repo, removable on DM. - **`docs/pc_spec.md` + `docs/dev_env.md` (EN + VI).** Maintainer hardware spec, mobile test devices (iPhone 14 Pro / 13 Pro Max, iOS 26.x on Chrome + Brave), and dev-env toolchain (Python 3.12, Node ≥ 22, Rust stable, JetBrains 2026.x). Cross-linked from README and CONTRIBUTING. - **Auto-create GitHub Discussion workflow.** [`announce-discussion.yml`](.github/workflows/announce-discussion.yml) — on `release: published` posts to the **Announcements** category; on push to `docs/**` / `CHANGELOG.md` / `README*.md` posts to **General**, gated by `[skip-discuss]` in the head-commit message and a quiet skip on `bot-ingest:` commits. Uses `gh api graphql` directly (no third-party action). Setup: configure repo variables `DISCUSSION_REPO_ID`, `DISCUSSION_ANNOUNCEMENTS_CATEGORY_ID`, `DISCUSSION_GENERAL_CATEGORY_ID` (run the GraphQL pre-flight query in the workflow header to fetch them). ### Changed -- **CI notify wrappers.** [`notify-ci-failure.yml`](.github/workflows/notify-ci-failure.yml), [`notify-deploy.yml`](.github/workflows/notify-deploy.yml), and [`notify-release-pipeline.yml`](.github/workflows/notify-release-pipeline.yml) replace `workflows: ["*"]` with explicit allowlists. Every workflow run no longer fans out to all three wrappers; the Actions tab is much quieter and the per-event reusable filtering is what it always should have been. +- **CI notify wrappers.** `notify-ci-failure.yml`, `notify-deploy.yml`, and [`notify-release-pipeline.yml`](.github/workflows/notify-release-pipeline.yml) replace `workflows: ["*"]` with explicit allowlists. Every workflow run no longer fans out to all three wrappers; the Actions tab is much quieter and the per-event reusable filtering is what it always should have been. - **`bot-ingest.yml` cleanup.** Removed a dead final step that referenced a non-existent `${{ secrets.BOT_TOKEN }}` and a `result.txt` file. The Python `success`/`failure` Telegram callback steps above already handle both outcomes. - **Image hints.** Game thumbnails in [`columns.tsx`](webapp/src/components/data-table/columns.tsx) and the hero in [`game-detail.tsx`](webapp/src/routes/game-detail.tsx) now declare `width`/`height` (CLS), `decoding="async"`, and `fetchPriority` (high for hero, low for table rows). itch.io thumbnails remain external — full WebP recompression is intentionally deferred (would require an image proxy). - **About support card** mirrors `.github/FUNDING.yml` exactly: 5 entries (GitHub Sponsors, Patreon, Ko-fi, BMC, PayPal). @@ -693,9 +750,9 @@ The Python pipeline from 2.0.0 is untouched and still drives the daily data upda Added 33 games. See [#22](https://github.com/poli0981/free-games-itchio-list/issues/22) and [#23](https://github.com/poli0981/free-games-itchio-list/issues/23). ### New Features -- Delete game with correct link in [`delete_game.py`](/scripts/delete_game.py). See [#20](https://github.com/poli0981/free-games-itchio-list/issues/20). -- Export JSON → `.csv`/`.xlsx` in [`export_csv.py`](/scripts/export_csv.py). See [#21](https://github.com/poli0981/free-games-itchio-list/issues/21). -- Check duplicate data in JSON file in [`check_duplicate.py`](/scripts/check_duplicate.py). See [#19](https://github.com/poli0981/free-games-itchio-list/issues/19). +- Delete game with correct link in `delete_game.py`. See [#20](https://github.com/poli0981/free-games-itchio-list/issues/20). +- Export JSON → `.csv`/`.xlsx` in `export_csv.py`. See [#21](https://github.com/poli0981/free-games-itchio-list/issues/21). +- Check duplicate data in JSON file in `check_duplicate.py`. See [#19](https://github.com/poli0981/free-games-itchio-list/issues/19). ## [1.0.3] - Date unknown (Improvements ⚙️) @@ -718,7 +775,7 @@ Added 33 games. See [#22](https://github.com/poli0981/free-games-itchio-list/iss ### Added - Full curated list of free itch.io games with auto-daily updates via GitHub Actions. - Scraping script ([`update_info.py`](scripts/update_info.py)): add links → scrape title, dev, genre, description, NSFW flag, thumbnail. -- MD table generator ([`generate_md.py`](scripts/generate_md.py)): split by genre, 300 max per file, in `/lists/`. +- MD table generator (`generate_md.py`): split by genre, 300 max per file, in `/lists/`. - Columns: No | Thumb | Name | Dev | Short Desc | Link | Safe | Notes | NSFW. - [`temp_link.json`](/scripts/temp_link.json) for easy manual adds (Actions process daily). - Full docs: [DISCLAIMER](/docs/DISCLAIMER.md), [PRIVACY](/docs/PrivacyPolicy.md), [TERMS](/docs/ToS.md), [EULA](/docs/EULA.md), [SECURITY](SECURITY.md), [CODE_OF_CONDUCT](CODE_OF_CONDUCT.md), [CONTRIBUTING](CONTRIBUTING.md), [ACKNOWLEDGEMENTS](/docs/ACKNOWLEDGEMENTS.md). diff --git a/CLAUDE.md b/CLAUDE.md index 80d4750..1ef08c9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,71 +4,80 @@ Quick context so future Claude sessions don't have to re-derive it. ## What this repo is -Two layers stacked on the same JSON catalog of free itch.io games: +A curated, auto-updating catalog of free itch.io games, published at **https://freeitchgames.win** (read-only for +everyone; the old github.io URL only redirects). Three layers share one JSON catalog: -1. **Python pipeline** — the data layer. - - `data_game/game_info_NNN.json` — chunked records, max 500 per file, 2,681 games as of Sept 2026. Serialization is fixed: `json.dumps(..., ensure_ascii=False, indent=4)`, no trailing newline (`json_io.dumps`) — the Worker port must emit identical bytes (`tests/fixtures/golden/`). - - `data_game/index.json` — chunk manifest (total + per-file counts). `data_game/count_history.json` — date-keyed `{date,total}` series powering the "games over time" chart. - - `scripts/` — scanners never write the catalog: `update_info.py` (queued URLs) and `refresh.py` (rotating 1/7-per-day check; `--full` re-scrape) emit a URL-keyed **patch** (`patch.py`); `apply_patch.py` applies it to the latest `main` and runs `validate.py`; `bash/commit_push.sh` does fetch → reset → apply → commit → push with retries. Shared: `scraper.py` (session, `Pacer` + 429 back-off, parsing), `data_store.py` (chunks stay in place, rebalance only past thresholds, write-if-changed), `json_io.py`, `canonical.py` (canonical itch.io URL; vectors in `tests/fixtures/url_vectors.json`). Pipeline bookkeeping lives in `scripts/state/` (not published). Tests: `pytest` (network blocked). Lint: `ruff check scripts tests webapp/scripts`, `ruff format`, `vulture` (config in root `pyproject.toml`). Local env: `python -m venv .venv && .venv/Scripts/pip install -r requirements-dev.txt`. - - The per-genre `lists/*.md` tables and `deleted_games.txt` were removed (Sept 2026): the catalog is web-only. -2. **Webapp** — `webapp/` (React 19 + TypeScript 6 + Vite 8 + Tailwind v3 + shadcn/ui, Tauri 2 desktop **and Android** wrapper in `webapp/src-tauri/`). Reads from `raw.githubusercontent.com`; writes via GitHub API with an encrypted PAT. +1. **Python pipeline** — the data layer (GitHub Actions). + - `data_game/game_info_NNN.json` — chunked records, max 500 per file, 2,681 games as of Sept 2026. Serialization is fixed: `json.dumps(..., ensure_ascii=False, indent=4)`, no trailing newline (`json_io.dumps`) — the Worker port (`webapp/worker/catalog.ts`) emits identical bytes (`tests/fixtures/golden/`). + - `data_game/index.json` — chunk manifest (total + per-file counts). `data_game/count_history.json` — date-keyed `{date,total}` series ("games over time" chart). `scripts/deleted_games.json` — removal log (public "Removed" page). `scripts/temp_link.json` — ingest queue. + - `scripts/` — scanners never write the catalog: `update_info.py` (queued URLs) and `refresh.py` (rotating 1/7-per-day check; `--full` re-scrape) emit a URL-keyed **patch** (`patch.py`); `apply_patch.py` applies it to the latest `main` and runs `validate.py`; `bash/commit_push.sh` does fetch → reset → apply → commit → push with retries. Shared: `scraper.py` (session, `Pacer` + 429 back-off, parsing), `data_store.py` (chunks stay in place, rebalance only past thresholds, write-if-changed), `json_io.py`, `canonical.py` (canonical itch.io URL; vectors in `tests/fixtures/url_vectors.json`, shared with the Worker). Pipeline bookkeeping lives in `scripts/state/` (not published). Tests: `pytest` (network blocked). Lint: `ruff check scripts tests webapp/scripts`, `ruff format`, `vulture` (config in root `pyproject.toml`). Local env: `python -m venv .venv && .venv/Scripts/pip install -r requirements-dev.txt` (Windows: run with `PYTHONUTF8=1`). +2. **Cloudflare Worker + static assets** — `webapp/worker/` + `webapp/wrangler.jsonc`, deployed by **Cloudflare Workers Builds** from `main` (root dir `webapp`, build `npm run build`, deploy `npx wrangler deploy`; no deploy workflow). The catalog JSON is bundled into the site at build time (`vite-plugins/catalog-data.ts` → `dist/data/*`, plus `data/urls.json` and `sitemap.xml`), so every data commit rebuilds the site. +3. **Web app + Tauri apps** — `webapp/src/` (React 19.3 + TypeScript 6.0 + Vite 8/rolldown + Tailwind + shadcn/ui + React Router 8), and the **Tauri 2 desktop + Android** read-only viewers in `webapp/src-tauri/` (same code; they fetch `https://freeitchgames.win/data` and load covers straight from img.itch.zone). Plus `webapp/admin/` — the maintainer-only admin app (second Vite entry, served at `/admin/`). + +Adding games: the public **Suggest** page (`/suggest`, Turnstile), the maintainer's browser extension (`POST /api/ingest`, Access service token; repo `poli0981/itch-f2p-extension`), and RSS discovery (Worker cron) all feed a **D1 review queue**; approving in `/admin` commits the URLs to `scripts/temp_link.json` as a GitHub App, which triggers `update.yml`. ## How to work in webapp/ ```sh cd webapp -npm install -npm run dev # http://localhost:5173 -npm run build # writes to webapp/dist/ (web → Cloudflare Workers Builds; Tauri uses the same dir) +npm ci +npm run dev # Vite on http://localhost:5173 (proxies /api and /img to wrangler dev on :8787) +npx wrangler dev # the Worker + built assets (run `npm run build` first); .dev.vars holds local secrets +npm run build # → webapp/dist/ (public app + /admin/ + /data + sitemap); Tauri builds use the same dir +npm test # vitest (worker/, src/lib); worker/test/* D1 tests spawn a local workerd via getPlatformProxy +npm run lint && npm run knip && npx tsc -b +npm run cf:types # after editing wrangler.jsonc (ignores .dev.vars via types.env; CI runs it with --check) +npx wrangler d1 migrations apply freeitchgames --local # local D1 (use --remote by hand for production) npm run tauri:dev # native window; needs Rust toolchain npm run tauri:build # native installers npm run tauri icon -- path/to/source-1024.png # regenerate src-tauri/icons/ npm run tauri -- android init # generate src-tauri/gen/android (gitignored) -npm run tauri -- android dev # live-reload on device/emulator npm run tauri -- android build --apk --target aarch64 # arm64-v8a release APK (unsigned; CI post-signs) ``` -Android details (env vars, signing, CI secrets, gotchas) live in `webapp/TAURI.md` → **Android APK**. +Local admin without Access: put `DEV_ADMIN_EMAIL=you@example.com` in `webapp/.dev.vars` — honoured only when the host is localhost. Turnstile test keys work locally (`TURNSTILE_SITEKEY=1x00000000000000000000AA`, `TURNSTILE_SECRET=1x0000000000000000000000000000000AA`, `SITE_ORIGIN=http://localhost:` in `.dev.vars`). Android details live in `webapp/TAURI.md` → **Android APK**. Path alias: `@/*` → `webapp/src/*`. -Path alias: `@/*` → `webapp/src/*`. Vite `define`s `__BUILD_DATE__` so About page shows the build date. +## Worker (`webapp/worker/`) -## Code-split layout +- `index.ts` routes: `/img/*` (img.ts), `/api/health`, `/api/suggest` (suggest.ts), `/api/ingest` (ingest.ts), `/api/admin/*` + `/admin*` (admin.ts), everything else that misses an asset → `spa.ts`. `scheduled()` (cron `23 */4 * * *`): `discover.ts` (one itch.io RSS feed per run, 6 h back-off on 429) → `QueueStore.reconcile` (queued → ingested / failed after 3 days) → `purge` (idempotency 7 d, Suggest notes 180 d). +- `img.ts`: `/img/<160|640>/` — allow-listed against `data/urls.json`, edge cache → R2 `THUMBS` (`w{w}/.webp`) → `cf.image` transform (stored once) → fallback streams the original with a 1-day cache (quota error 9422). Upstream errors → controlled 502. +- `spa.ts`: `not_found_handling` is `"none"`, so misses reach the Worker: `/assets/*`, `/data/*` and file-like paths get a real 404 (`no-store`); app routes get the shell with 200; unknown paths and game slugs not in the catalog get the shell with **404**. Keep its `ROUTES` in sync with `src/App.tsx` and `src/hooks/useSeoHead.ts`. +- `access.ts`: verifies `Cf-Access-Jwt-Assertion` with jose (issuer + AUD). Maintainer = email in secret `ADMIN_EMAILS` + same-origin writes; ingest = service-token `common_name`. +- `admin.ts`: API (queue list / approve / reject / add / edit the 3 fields / delete with reason + R2 cleanup / restore) and the `/admin` shell with its own CSP. The maintainer's email goes only to the D1 audit log, never into a commit (the repo is public). +- `repo.ts` + `github.ts` + `catalog.ts`: writes as a **GitHub App** (installation token, cached per isolate) with GraphQL `createCommitOnBranch` + `expectedHeadOid` (verified commits; `commitWithRetry` rebuilds from the new head on a race). Reads use the raw media type (no base64/UTF-8 mojibake). `catalog.ts` ports `data_store.py` byte-for-byte (golden fixtures). +- `queue.ts`: URL classification (catalog → blocklist → pending → previously deleted) + the D1 store (`worker/migrations/`, additive only — never edit an applied migration). `data.ts`: catalog facts read from the site's own `/data` via `env.ASSETS`, cached per isolate (loaded values only — see gotchas). +- Configuration: non-secret settings are `vars` in `wrangler.jsonc` (empty until setup); secrets (`GH_APP_PRIVATE_KEY` PKCS#8, `ADMIN_EMAILS`, `TURNSTILE_SECRET`) via `wrangler secret put`, typed in `worker/env.ts` as optional. A feature whose settings are missing answers **503**; the public site needs none of them. `env.staging` = Worker `free-games-itchio-list-staging` on `staging.freeitchgames.win` (no cron, own R2/D1/rate-limit namespaces). -`vite.config.ts` `manualChunks` splits node_modules into `vendor-react` / `vendor-query` / `vendor-ui` / `vendor-charts` (Recharts, ~380 KB) / `vendor-github` (Octokit, ~100 KB) / `vendor-openpgp` (OpenPGP.js, ~387 KB — lazy, only touched when Settings → Commit Signing is opened or a commit is being signed). Routes `/charts`, `/add`, `/workflows`, `/settings`, `/about`, `/games/:slug` are `React.lazy` so the initial bundle stays ~163 KB gzip. +## Web app structure (`webapp/src/`) -## Webapp structure - -- `src/routes/*.tsx` — one file per route; `App.tsx` wires `react-router-dom` HashRouter. -- `src/components/data-table/*` — `DataTable` (TanStack Table + Virtual + pagination), `data-table-toolbar`, `data-table-pagination`, `faceted-filter`, `columns`. Row keys are URL-based (`getRowId: g => g.url`) so selection survives sort/filter/page changes. -- `src/components/ui/*` — shadcn primitives (Button, Card, Input, Label, Badge, Skeleton, Separator, Tabs, Popover, Checkbox, Select, Switch, Textarea, Dialog). -- `src/components/charts/` — chart module (one file per chart, shared `chart-card.tsx` with `ChartCard` + `PALETTE`). 16 charts across 4 tabs. Each tab is a `React.lazy` default export under `charts/tabs/{overview,reach,quality,discovery}-tab.tsx`, wrapped in `` from `routes/charts.tsx`. **Tabs import chart components directly (no `index.ts` barrel — it was removed in v3.7.0)** so the bundler keeps each tab's components in its own chunk; a barrel re-exporting all 16 would collapse them into one shared chunk and defeat the split. Radix unmounts inactive `TabsContent`, so a non-default tab's component code downloads only on first activation. Recharts (`vendor-charts`) still loads with the default Overview tab. -- `src/components/legal-gate.tsx` — full-screen, non-dismissible first-launch legal-acceptance gate (raw Radix Dialog, no close-X, Esc/outside-click disabled). Wraps the shell in `App.tsx`; renders instead of the shell until `prefs.acceptedLegalVersion === LEGAL_VERSION`. Reuses `LEGAL_LINKS` from `about.ts`; persists via `prefs.acceptLegal()`. -- `src/lib/github/` — `client.ts` (Octokit factory), `data-store.ts` (TS port of `scripts/data_store.py`), `contents.ts` (single-file commits — routed through Git Data API so they can be signed), `git-data.ts` (atomic multi-file commit; optional signer for GPG), `signer.ts` (builds a `CommitSigner` from gpg store + auth + prefs), `workflow.ts` (dispatch + poll). -- `src/lib/gpg/` — `canonicalize.ts` (pure: builds the byte string Git would hash for a commit), `sign.ts` (lazy-imports `openpgp`, exports `loadPrivateKey` / `signCommit` / `verifyDetached`), `storage.ts` (encrypted-key + metadata in localStorage). -- `src/lib/crypto.ts` — AES-GCM 256 + PBKDF2-SHA256 100k rounds. **Uint8Array generic must be ``** under TS 6, not `` — Web Crypto rejects the latter. -- `src/lib/use-is-mobile.ts` — `useIsMobile()` hook based on `matchMedia('(max-width: 767px)')`. Use it for branches that need a distinct mobile layout (e.g. card view instead of a wide table). -- `src/lib/i18n/` — minimal typed i18n. `en.ts` is the source of truth (`MessageKey = keyof typeof en`); `vi.ts` must **never** be static-imported — it stays a lazy chunk via `import('./vi')` in `index.ts` only. `t()` imperative, `useT()` reactive hook; language pref lives in the `prefs` store. -- `src/main.tsx` — react-query cache persisted to IndexedDB via `idb-keyval` (`PersistQueryClientProvider`). Only public catalog queries (`db` / `deleted` / `count-history`) are dehydrated, never PAT-gated data. `buster = APP.version`, so bumping `about.ts` invalidates the cache. **`gcTime` must stay >= persist `maxAge`** or restored queries are garbage-collected right after hydration. -- Error handling — `src/lib/http-error.ts` (`HttpError`), `src/components/error-page.tsx` + `route-error.tsx` + `error-boundary.tsx`. Hidden preview route `/errors/:code` (not linked from nav). `webapp/public/404.html` serves as the GitHub Pages custom 404. -- `src/stores/` — Zustand stores: `auth` (in-memory PAT + GitHub user; idle timeout pulled from `prefs`), `theme`, `prefs` (sidebar collapsed + density + idle timeout + author override + notification settings + language + `acceptedLegalVersion` — re-prompts the legal gate when the exported `LEGAL_VERSION` constant bumps), `gpg` (in-memory PrivateKey + fingerprint + uid + enabled), `undo` (20-entry FIFO of reverse ops). -- `src/lib/about.ts` — keep the `THIRD_PARTY` array up to date when adding npm deps; About page reads it. +- `routes/*.tsx` — one file per route (`/`, `/games`, `/games/:slug`, `/charts`, `/removed` (`/deleted` redirects), `/suggest`, `/settings`, `/about`, `/errors/:code`); `App.tsx` wires them; `components/app-router.tsx` picks **BrowserRouter on the web, HashRouter in Tauri**. `lib/legacy.ts` rewrites v3 `#/x` links to `/x` (crafted hashes go home) and deletes v3 PAT/GPG storage keys. +- Data: `lib/config.ts` (`DATA_BASE` = `/data` on the web, `https://freeitchgames.win/data` in Tauri), `lib/data/*`, `hooks/useGames.ts`. react-query cache persisted to IndexedDB (`webapp.query-cache`, 7 days); `CACHE_BUSTER = ${APP.version}:data-v1`. **`gcTime` must stay >= persist `maxAge`.** +- `components/data-table/*` (TanStack Table v8 + Virtual; row ids are URLs), `components/charts/` (16 charts, 4 lazy tabs, **no barrel `index.ts`**), `components/game-thumb.tsx` (`lib/thumbnail.ts` → `/img/160|640/...` on the web, the original URL in Tauri), `components/legal-gate.tsx` (links flagged `inGate` in `lib/about.ts`; re-prompts when `LEGAL_VERSION` in `stores/prefs.ts` changes). +- `hooks/useSeoHead.ts` sets canonical + robots per route (index.html has no static canonical/og:url on purpose). +- `lib/i18n/` — `en.ts` is the source of truth; `vi.ts` is `Record` and must never be static-imported (lazy chunk). +- `stores/` — Zustand: `prefs` (`webapp.prefs`: language, density, legal acceptance…), `theme` (`webapp.theme`). +- `lib/about.ts` — keep `THIRD_PARTY` up to date when adding npm deps; `LEGAL_LINKS`; `APP.version`. +- Code split (`vite.config.ts` rolldown `codeSplitting.groups`): `vendor-react` (priority 100 — must claim React first), `vendor-query`, `vendor-ui`. There is deliberately **no vendor-charts group** (it pulled React/clsx in and put Recharts on the first load); Recharts stays in the lazy chart chunks. Initial load ≈ 195 KB gzip. Web build `target` is Safari/iOS 15.4 (Radix class static blocks otherwise break iOS 15); Tauri uses the default. ## Editable vs read-only fields -Each game has **20** fields (plus optional `added_at` / `updated_at`, appended by the pipeline — schema changes are additive only, installed v3 apps still read the raw JSON). Only **3** are user-editable: `safe_virus`, `notes`, `nsfw`. The other 17 are scraper output; no scrape (not even `--full`) overwrites the 3 editable fields. +Each game has **20** fields (plus optional `added_at` / `updated_at`, appended by the pipeline — schema changes are additive only, installed v3 apps may still read the raw JSON). Only **3** are maintainer-editable: `safe_virus` (`?|Yes|No|Caution`), `notes`, `nsfw` (`Yes|No`) — via `/admin`. The other 17 are scraper output; no scrape (not even `--full`) overwrites the 3 editable fields. ## GitHub Actions | Workflow | Trigger | Notes | |---|---|---| -| `update.yml` | Push to `main` touching `scripts/temp_link.json` + daily 01:23 UTC + `workflow_dispatch` (`url`) | Ingest queue → patch → `commit_push.sh`. Workflow-level `concurrency: ingest` with **`queue: max`** (the default queue replaces a pending run, which would drop its dispatched `url`). A dispatched `url` is processed first and written to `temp_link.json` (`queue_add`) until it reaches a final outcome. Failed fetches count as an attempt only ≥ 6 h apart (`last_attempt`; 3 → given up), and a 429 counts as none, so a burst of queued runs can't burn a link's retries. GitHub-App pushes (extension, admin Worker) trigger it; its own `GITHUB_TOKEN` push does not (no loop). Keep the filename: apps dispatch it by name. | -| `refresh.yml` | Daily 02:47 UTC + `workflow_dispatch` (`budget`, `url`) + `workflow_call` | scan (read-only, 55-min step timeout, patch artifact uploaded `if: always()`) → apply (`!cancelled()`: a failed / timed-out scan's checkpoint is applied, a cancelled run's is not) → notify. Workflow-level `concurrency: refresh-pipeline` + `queue: max` runs one whole scan → apply at a time (also for force-update's call; the group name must differ from the caller's or GitHub cancels it as a deadlock). Removal needs the same 404/410 or paid strike seen again ≥ 20 h after the first sighting (`strike_at`). Checkpoints never carry removals. **Mass-change guard:** a run whose removals or new strikes exceed max(10, 10 %) of the games it checked withholds all its removals and marks them — and, on a strike spike, all its strikes — `withheld_at`; later runs keep withholding those (they take at most half a run's budget) until a healthy check clears them, and alert (`mass_change`) — that pattern means itch.io markup changed; dispatch with `allow_mass_removal` only after checking on itch.io. `apply_patch.py` re-checks the same per-run limit and max(25, 5 %) of the catalog unless `ALLOW_MASS_REMOVAL=1`. | -| `force_update.yml` | `workflow_dispatch` ONLY (`url`, `budget`, `allow_mass_removal`) | `queue: max` (a pending dispatch is never replaced). Calls `refresh.yml` with `full: true`: re-scrapes every scraper field for one URL or the next batch (rotates on `full` timestamps). Always preserves `safe_virus` / `notes` / `nsfw`. Canonical tool for repairing mojibake. | +| `update.yml` | Push to `main` touching `scripts/temp_link.json` + daily 01:23 UTC + `workflow_dispatch` (`url`) | Ingest queue → patch → `commit_push.sh`. Workflow-level `concurrency: ingest` with **`queue: max`** (the default queue replaces a pending run, which would drop its dispatched `url`). A dispatched `url` is processed first and written to `temp_link.json` (`queue_add`) until it reaches a final outcome. Failed fetches count as an attempt only ≥ 6 h apart (`last_attempt`; 3 → given up), and a 429 counts as none. GitHub-App pushes (extension, admin Worker) trigger it; its own `GITHUB_TOKEN` push does not (no loop). Keep the filename. | +| `refresh.yml` | Daily 02:47 UTC + `workflow_dispatch` (`budget`, `url`, `allow_mass_removal`) + `workflow_call` | scan (read-only, 55-min step timeout, patch artifact uploaded `if: always()`) → apply (`!cancelled()`: a failed / timed-out scan's checkpoint is applied, a cancelled run's is not) → notify. Workflow-level `concurrency: refresh-pipeline` + `queue: max` runs one whole scan → apply at a time (also for force-update's call; the group name must differ from the caller's or GitHub cancels it as a deadlock). Removal needs the same 404/410 or paid strike seen again ≥ 20 h after the first sighting (`strike_at`). Checkpoints never carry removals. **Mass-change guard:** a run whose removals or new strikes exceed max(10, 10 %) of the games it checked withholds all its removals and marks them — and, on a strike spike, all its strikes — `withheld_at`; later runs keep withholding those (they take at most half a run's budget) until a healthy check clears them, and alert (`mass_change`) — that pattern means itch.io markup changed; dispatch with `allow_mass_removal` only after checking on itch.io. `apply_patch.py` re-checks the same per-run limit and max(25, 5 %) of the catalog unless `ALLOW_MASS_REMOVAL=1`. | +| `force_update.yml` | `workflow_dispatch` ONLY (`url`, `budget`, `allow_mass_removal`) | `queue: max`. Calls `refresh.yml` with `full: true`: re-scrapes every scraper field for one URL or the next batch (rotates on `full` timestamps). Always preserves `safe_virus` / `notes` / `nsfw`. Canonical tool for repairing mojibake. | | `notify-failure.yml` | `workflow_call` | Discord (`DISCORD_CI_WEBHOOK`) on failure / **cancelled** (job-level timeouts end as cancelled) / rate-limited / mass change / failed Cloudflare build. | -| `python-ci.yml` / `webapp-ci.yml` | PRs (+ pushes for Python) | ruff + format + vulture + pytest + `validate.py` / lint + knip + build + `wrangler deploy --dry-run`. | +| `python-ci.yml` / `webapp-ci.yml` | PRs (+ pushes for Python) | ruff + format + vulture + pytest + `validate.py` / `npm run cf:types -- --check` + lint + knip + vitest + build + `wrangler deploy --dry-run --env=""`. | | `deploy-status.yml` | Hourly + manual | Not a deploy. `bash/cf_build_status.sh` walks main's first-parent history to the latest finished `Workers Builds: free-games-itchio-list` check run (Cloudflare posts it only when a build ends; branch commits carry preview builds under the same name) and alerts once per failed build (cache key per check-run id, saved after the Discord post). Scheduled because GitHub never starts `check_run` workflows for `GITHUB_TOKEN` pushes (the data commits). | -| `release_desktop.yml` | Tag `v*` push, or manual | `create-release` makes the single draft (id passed to tauri-action v1 `releaseId`); release builds use **no** npm/cargo caches (cache-poisoning). Tauri build for Win + macOS aarch64 + macOS x86_64 (cross-compile) + Linux. Uploads `.dmg` / `.app.tar.gz` / `.pkg` (macOS), `.msi` / `.exe` (Windows), `.deb` / `.AppImage` (Linux). macOS `.pkg` `--identifier` reads `tauri.conf.json` so it never drifts from the bundle ID. | -| `release_android.yml` | Tag `v*` push, or manual | Tauri **Android** build → arm64-v8a APK, **post-signed** with `zipalign`+`apksigner` (gen/ stays gitignored). Tag → attaches to the same draft Release; manual dispatch → uploads as a workflow artifact. Secrets: `ANDROID_KEYSTORE_BASE64` / `ANDROID_KEYSTORE_PASSWORD` / `ANDROID_KEY_ALIAS`. | +| `release_desktop.yml` | Tag `v*` push, or manual | `create-release` makes the single draft (id passed to tauri-action v1 `releaseId`); release builds use **no** npm/cargo caches (cache-poisoning). Win + macOS aarch64 + macOS x86_64 (cross-compile) + Linux (`ubuntu-22.04` for a low glibc floor). Uploads `.dmg` / `.app.tar.gz` / `.pkg` (macOS), `.msi` / `.exe` (Windows), `.deb` / `.AppImage` (Linux). macOS `.pkg` `--identifier` reads `tauri.conf.json`. | +| `release_android.yml` | Tag `v*` push, or manual | Tauri **Android** build → arm64-v8a APK, **post-signed** with `zipalign`+`apksigner` (gen/ stays gitignored). Tag → attaches to the same draft Release; manual dispatch → workflow artifact. Secrets: `ANDROID_KEYSTORE_BASE64` / `ANDROID_KEYSTORE_PASSWORD` / `ANDROID_KEY_ALIAS`. | +| `announce-*.yml`, `notify-release-pipeline.yml` | Release published / pipeline runs | Reusable workflows from `poli0981/.github`, SHA-pinned — but at that pin they still check out their notifier script from that repo's `main`. | + +All workflows: `permissions: {}` at the top, per-job grants, actions pinned by commit SHA. ## Release / tag process @@ -81,46 +90,42 @@ git push origin vX.Y.Z gh release edit vX.Y.Z --draft=false ``` -Draft-first: **never** `gh release create` by hand before CI — tauri-action v1 refuses to upload into a published release, and announcements would go out before installers exist. Merge PRs into `main` with squash or a merge commit, never by fast-forward pushing a branch: its commits' preview-build check runs would then sit on main's own line and confuse `deploy-status.yml`. Tag from `main` only (forking from a feature branch and force-moving on rebase makes a mess). GPG signing is wired through gpg-agent (`commit.gpgsign=true`, so `git tag -s` and `git commit` both sign; the pinentry must be answered — in unattended sessions commits fail rather than going unsigned). The historical key `03F965C2E2DB5C6B` was exposed in the browser extension's storage (Sept 2026) and is being replaced — use the maintainer's current key. +Draft-first: **never** `gh release create` by hand before CI — tauri-action v1 refuses to upload into a published release, and announcements would go out before installers exist. Merge PRs into `main` with squash or a merge commit, never by fast-forward pushing a branch: its commits' preview-build check runs would then sit on main's own line and confuse `deploy-status.yml`. Tag from `main` only. Versions live in `webapp/src/lib/about.ts` (`APP.version`), `webapp/package.json`, `webapp/src-tauri/tauri.conf.json` and `Cargo.toml` (+ `Cargo.lock`) — keep them equal. GPG signing is wired through gpg-agent (`commit.gpgsign=true`, so `git tag -s` and `git commit` both sign; the pinentry must be answered — in unattended sessions commits fail rather than going unsigned). The historical key `03F965C2E2DB5C6B` was exposed in the browser extension's storage (Sept 2026) and is being replaced — use the maintainer's current key. -## Required PAT permissions for the webapp +## Licenses & policies -Fine-grained PAT scoped to **only this repo** with: - -- **Contents: Read and write** — edits, deletes, queueing URLs. -- **Actions: Read and write** — dispatching the scraper workflow. - -`workflow:write` is **not** what we need (that's for editing `.github/workflows/*.yml` files, which the webapp doesn't do). Classic PATs with the `workflow` scope happen to cover both. +Code **MIT** (`LICENSE`); catalog data **CC BY 4.0** for the maintainer's contribution — excluding creators' descriptions, cover images, names/trademarks (`data_game/LICENSE.md`, `LICENSES/CC-BY-4.0.txt`); docs **CC BY 4.0**; map + non-affiliation in `NOTICE.md`. Policies (EN in `docs/`, VI mirrors in `docs/i18n/vi/`, English controls): ToS (website + data + content removal), EULA (desktop/Android binaries only; also `webapp/src-tauri/installer/EULA.rtf`), Privacy Policy, Disclaimer, `SECURITY.md`, `CODE_OF_CONDUCT.md`. When a policy changes, bump `LEGAL_VERSION` (`webapp/src/stores/prefs.ts`) and the dates in `about.legal.desc` (EN/VI) so the legal gate asks again. Contact addresses `legal@ / privacy@ / security@ / takedown@freeitchgames.win` are Cloudflare Email Routing forwards. ## Known gotchas (cost a release each — don't relearn) -1. **`universal-apple-darwin` + `bundle_dmg.sh` is fragile** in headless CI. Use per-arch (`aarch64-apple-darwin`, `x86_64-apple-darwin`) instead. -2. **`macos-13` is retired** from free GitHub-hosted runners (late 2024). Cross-compile x86_64 from `macos-latest` (Apple Silicon). -3. **Tauri icons must exist before build.** Generate via `npm run tauri icon -- path/to/source.png`. The 1024×1024 source is gitignored; generated icons are committed. -4. **Tauri doesn't ship `.pkg`.** We build it with `pkgbuild` after `tauri-action` and upload via `gh release upload`. Step uses `if: ${{ !cancelled() && … }}` so a DMG flake doesn't drop the PKG while a cancelled run still stops (it used to be `always()`). -5. **Vite v8 `base`** only accepts `'./'`, an absolute URL, or an empty string. Anything else warns and silently breaks asset paths. -6. **TS 6** deprecates `baseUrl`. Use `paths` alone. -7. **lucide-react v1+** removed/renamed brand icons (`Github` → not available). Use `Library`, `Database`, etc. for repo icons. -8. **`/repos/.../contents` `content` is base64 with newlines AND base64-decoded data is UTF-8.** Strip newlines first, but `atob` alone returns a Latin-1 binary string — multi-byte UTF-8 sequences become mojibake. Go through `TextDecoder('utf-8')` via the `base64ToUtf8` helper in `webapp/src/lib/github/encoding.ts`. The matching `utf8ToBase64` is correct as-is. -9. **`createWorkflowDispatch` returns 204 with no run id.** To track the run, list runs filtered by `event=workflow_dispatch` and a dispatch timestamp from a few seconds before. -10. **`webapp/dist/` is gitignored.** Cloudflare Workers Builds (root dir `webapp`, `npm run build`, `npx wrangler deploy`) builds and deploys it. Never point `assets.directory` at a source dir — in Sept 2026 a config-less deploy served the raw `webapp/` tree. -11. **PUT `/repos/.../contents/{path}` can never be "Verified".** GitHub authors that commit itself from the PAT; there is no `signature` field. All webapp writes must go through the Git Data API (blob → tree → commit → updateRef) to allow GPG signing. `contents.ts` `putFile` was removed for this reason — use `commitSingleFile` (wraps `atomicCommit`). -12. **GPG signing must use binary mode in openpgp.js.** `openpgp.createMessage({ text })` normalizes line endings before hashing → signature won't verify against the LF-only Git commit object. Use `createMessage({ binary: TextEncoder.encode(canonical) })`. -13. **Commit object canonical timestamp must match Octokit's `author.date` exactly.** GitHub re-derives ` <±HHMM>` from the ISO date and recomputes the SHA. Use a single `ts + tzOffsetMin` source for both, derive `author.date` via `isoFromTs(ts, tzOffsetMin)`. -14. **TabsList primitive is `inline-flex` with `whitespace-nowrap` triggers.** Many tabs + narrow viewport → overflow. The fix in `/workflows` is dual-render: `