* feat(pipeline): rotating refresh + patch/apply pipeline, drop lists/
Replace check_paid / check_alive / update_reviews / update_status: each
crawled all 2,600+ pages sequentially, overran its job timeout, saved
only at the end and has lost every run since late June (unreported:
timeouts end as "cancelled").
- scripts/refresh.py: daily slice of ~1/7 of the catalog (pending
strikes first, then least recently checked), one GET per game for
alive / paid / rating / status (+ release_date, thumbnail, updated_at
backfill). Removal needs the same 404/410 or paid strike on two
different UTC days. Paced requests, capped Retry-After back-off, stop
after 3x 429, checkpoints and an in-script deadline. --full replaces
force_update.py (rotating batches, editable fields preserved).
- Scanners emit a URL-keyed patch (patch.py); apply_patch.py applies it
to the latest main and runs validate.py; bash/commit_push.sh fetches,
re-applies and retries pushes, so concurrent writers never clobber
each other.
- update_info.py: canonical URLs (canonical.py), skip games in the
deleted log, keep transient failures queued (max 3 runs, tracked in
scripts/state/), stamp added_at, never drop links queued meanwhile.
- data_store.py: games stay in their chunk, re-slice only past
thresholds, write only changed bytes; index/count_history change only
with data (no more no-op commits).
- validate.py (schema, enums, canonical/unique URLs, index consistency)
+ normalize one invalid safe_virus ("y" -> "Yes").
- tests/: 85 network-free pytest cases, HTML fixtures (from sample/),
shared URL vectors and golden chunk/serialization fixtures for the
future Worker port.
- Workflows: refresh.yml (scan -> apply -> notify), update.yml (runs on
queue change), force_update.yml (refresh.yml full mode),
notify-failure.yml (Discord on failure/cancel/rate limit),
python-ci.yml, webapp-ci.yml, deploy-status.yml; draft-first release
with one create-release job and tauri-action v1, no caches in release
builds; SHA-pinned actions, permissions: {} defaults, reusable
workflows pinned with explicit secrets, injection fixes; dependabot.yml.
- Remove lists/, generate_md, generate_table, log_deleted,
deleted_games.txt, the Telegram bot-ingest path and old bash wrappers;
update README (EN/VI), CONTRIBUTING, templates, CLAUDE.md, CHANGELOG
and mark the retired Telegram path in the policies.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* fix(pipeline): review findings on the refresh / ingest rewrite
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
alerts (mass_change). Withheld games are marked withheld_at and stay
withheld in later (even single-URL or rate-limited) runs until a healthy
check clears them or a run is dispatched with allow_mass_removal.
- Checkpoints never carry removals, so a scan that dies before its guard
cannot delete games; apply_patch re-checks the per-run limit and caps
any patch at max(25, 5%) of the catalog (ALLOW_MASS_REMOVAL=1 overrides).
- Strikes mature by time, not calendar day: a second sighting must come
>= 20 h after the first (strike_at), so two checks around midnight UTC no
longer remove a game.
- Overlapping scans can't undo each other: refresh_state merges keep the
newest check and the newest full stamp in either apply order, and a
removal is skipped when a newer check has landed since.
- A corrupt count_history.json fails the apply instead of being replaced
by a one-row history.
Ingest
- A second spelling of a queued game no longer drops the first copy
before it reaches a final outcome.
- A dispatched url is processed first and kept in temp_link.json
(queue_add) until it finishes, so a retry, deadline or rate-limit stop
keeps it.
- Failures count as an attempt only >= 6 h apart and a 429 counts as none,
so a burst of queued runs can't burn a link's three attempts.
- Non-string queue entries are cleaned on every apply instead of crashing
it; {"url": ...} objects are unwrapped.
CI
- queue: max on the ingest, refresh-apply and force-update concurrency
groups: the default queue replaced (and silently dropped) pending runs.
- Seed scripts/state/*.json and mkdir -p before git add (the pathspec
failed on an empty patch until the directory existed on main).
- Cancelling a refresh / force-update / desktop release really stops it
(!cancelled() instead of always()).
- deploy-status.yml becomes an hourly check of main's latest finished
"Workers Builds: free-games-itchio-list" run (bash/cf_build_status.sh):
GitHub never starts check_run workflows for GITHUB_TOKEN data commits.
- The reusable release notifiers still take their script from
poli0981/.github@main; the caller comments now say so.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* fix(pipeline): close the remaining mass-removal and monitor gaps
From the second review round of the pipeline fixes:
- A strike spike now marks every strike of that run withheld_at (the
checkpoint of a run that dies mid-spike too), so a later short,
rate-limited or single-URL run can't remove them without an
allow_mass_removal dispatch.
- Withheld games take at most half of a run's budget (all of it for the
allow_mass_removal run that confirms them), and a withheld full-mode
game moves its `full` stamp, so neither rotation stalls on them.
- refresh.yml runs one scan -> apply pipeline at a time (workflow-level
concurrency refresh-pipeline, queue: max), so an older removal can't be
applied after a newer healthy check of the same game.
- deploy-status.yml alerts once per failed Cloudflare build, keyed on its
check-run id and marked only after the Discord post, instead of by age
(which could drop an alert after a missed run, or repeat it); the
monitor walks main's first-parent history so preview builds of merged
branch commits are never mistaken for the site's build.
- CLAUDE.md: merge PRs with squash or a merge commit, never by fast-forward.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
9.5 KiB
Terms of Use
Last updated: 2026-05-10
These Terms of Use ("Terms") govern Your use of the Repository, the Webapp, and the Desktop App. They are written in plain language with deliberate humor — but they apply.
TL;DR: Don't break things, don't spam, don't add malware, don't abuse the GitHub API or itch.io. Use the webapp's PAT feature responsibly. The Maintainer can remove anything for any reason.
1. Definitions
The defined terms in EULA §1 apply here as well: "The Repository", "The Webapp", "The Desktop App", "The Catalog", "The Maintainer", "You".
2. Acceptance
By viewing, cloning, forking, starring, contributing to, opening an issue against, deploying, running, or otherwise interacting with the Repository, the Webapp, or the Desktop App, You agree to these Terms. If You do not agree, do not use them.
3. Permitted uses
You are welcome to:
- Browse the Catalog, on GitHub or via the Webapp / Desktop App.
- Click through to itch.io pages and download games (subject to itch.io's terms and each developer's terms).
- Submit new game URLs via the [Add Games] issue template.
- Submit removal requests via [Remove Games].
- Report bugs, suggest features, give feedback via the corresponding templates.
- Open Pull Requests with code, data, or documentation improvements.
- Self-host the Webapp or build the Desktop App for personal, educational, or commercial use under the MIT License.
4. Contributor obligations
If You contribute to the Repository (issues, PRs, edits via the Webapp), You represent that:
- The content You submit (code, text, game URLs) is either Your own work or properly attributed and licensed for inclusion.
- Game URLs You submit point to genuinely free-to-play games on itch.io. Demos of paid games, "name your own price (minimum > 0)" titles, and timed-free promos do not qualify.
- The submission contains no malware, no phishing, no doxxing, no copyright infringement, and nothing that would embarrass the Maintainer's poor mother.
- You grant the Maintainer the right to incorporate Your contribution into the Repository under the MIT License.
5. Prohibited activities
You agree not to:
5.1 Catalog & content
- Submit games that are not free, that are scams, that distribute malware, or that violate itch.io's terms.
- Spam the issue tracker with low-effort, duplicate, or off-topic posts.
- Submit removal requests for games You do not own (use Bug Report or Feedback templates instead).
- Post personal information about the Maintainer or any contributor.
5.2 Webapp
- Use the Webapp's PAT (Personal Access Token) feature with a token granting access to repositories You are not authorized to write to.
- Attempt to extract another user's PAT from a shared device by exploiting browser-storage access (this is also a violation of GitHub's terms).
- Bypass or attempt to bypass the AES-GCM encryption applied to PATs in
localStorageto gain unauthorized access. - Use the Webapp as a relay to perform automated, large-scale GitHub API calls against repositories or organizations You are not authorized to interact with.
5.3 itch.io and scraping
- Repeatedly trigger the
update.ymlworkflow against URLs in a way that produces unreasonable load on itch.io (the Webapp's Add page rate-limits client-side; do not script around it). - Fork the scraper, remove the rate-limiting (
scraper.pyalready pauses 2.5–5 s between requests + 15–30 s every 20), and run it at high frequency. Itch.io's terms govern automated access; the Maintainer disclaims responsibility for forks that violate them.
5.4 Desktop App
- Repackage the signed installers and redistribute them as if they were produced by a different vendor.
- Strip the About page or attribution before redistributing the Desktop App publicly.
5.5 General
- Use the Repository, Webapp, or Desktop App for any unlawful purpose under the laws of Your jurisdiction or the Maintainer's (Vietnam).
- Harass, threaten, or impersonate others through any channel related to this project (issues, PRs, Discord servers, social media).
6. Personal Access Tokens (PAT) — Your responsibility
The Webapp's optional write features require a GitHub fine-grained PAT. You are solely responsible for:
- Choosing a PAT scope that is no broader than what You actually need (typically
Contents: Read & write+Actions: Read & write, scoped to a single repository). - Choosing a strong passphrase for AES-GCM encryption at rest.
- Locking the PAT (Settings → Lock) when stepping away from a shared device.
- Removing the PAT (Settings → Remove saved PAT) when no longer needed.
- Rotating the PAT if You suspect compromise.
The Maintainer never sees, transmits, or stores Your PAT. See Privacy Policy and Security Policy for details on the PAT lifecycle.
7. Intellectual property
- The code, data structures, scripts, generated tables, webapp source, and documentation are © the Maintainer (poli0981 / SkullMute), licensed under the MIT License.
- Games and game metadata (names, descriptions, screenshots, tags) belong to their respective developers and itch.io. See DISCLAIMER §4.
- Third-party open-source dependencies are governed by their own licenses; see the Third-party software section of the About page.
8. Termination
The Maintainer may, at any time and without notice:
- Remove or modify any content (game entries, documentation, code).
- Reject, close, or hide issues, PRs, or comments that violate these Terms.
- Block users who repeatedly violate these Terms.
- Take down or archive the Repository, the Webapp deployment, or the Desktop App releases.
Tagged releases (vX.Y.Z) are intended to remain available, but no SLA is offered.
9. Changes to these Terms
The Maintainer may update these Terms. The Last updated date at the top reflects the most recent change. Continued use after a change constitutes acceptance. Material changes will additionally be noted in CHANGELOG.md.
10. Governing law and disputes
These Terms are governed by the laws of the Socialist Republic of Vietnam, without regard to conflict-of-law principles.
Disputes are to be resolved as follows, in order:
- Informal first: open a
[Feedback]or[General]issue or DM via any channel listed on the About page. Most disagreements end here. - Mediation: if informal contact fails, the parties may attempt mediation by mutual agreement.
- Court: if all else fails, the competent courts of Vietnam have exclusive jurisdiction.
11. Severability
If any provision of these Terms is held invalid or unenforceable, the remaining provisions remain in full force.
12. Not legal advice
These Terms are a hobby-project document drafted by a non-lawyer with AI assistance. They are not a substitute for professional legal advice.
13. Final vibes
This is still a list of free games + a webapp + a desktop app, built by a tired dev and two LLMs. Be cool, don't break things, have fun, and we all get along.
Questions? Open an issue. Or DM via any channel on the About page. The Maintainer will try not to ghost.
14. Telegram bot — optional contribution path
Retired (September 2026). The Telegram bot path is discontinued and no longer accepts submissions; the
bot-ingest.ymlworkflow was removed. This section is kept to describe how data was handled while it ran and will be dropped in the next full revision of this document.
CONTRIBUTING.md describes an optional flow for submitting
games via the Telegram bot @my_skull_bot. Using
this path is purely opt-in. By choosing to use it:
- You voluntarily share Your Telegram numeric ID with the Maintainer (operator: poli0981) for the sole purpose of being added to the bot's runtime whitelist.
- The whitelist lives on the operator's local machine (or a Docker volume), is not committed to this Repository, not synchronized to any server controlled by the Maintainer, and not forwarded to any third-party log aggregator, analytics service, or other repository.
- The bot does not collect message contents beyond what is needed to parse
the itch.io URLs You submit. itch.io URLs You submit become public — they
are committed to this Repository under
scripts/temp_link.jsonby thebot-ingest.ymlworkflow (since removed) and rendered into the catalog by the daily scraper. - You may request removal at any time by DMing the Maintainer ("remove me from whitelist"). Removal takes effect at the next bot start.
- You agree not to share another contributor's Telegram ID without that contributor's explicit permission. Doing so is a Code of Conduct violation and grounds for removal under §8.
- You agree not to post Your own (or anyone else's) Telegram numeric ID to public channels associated with this project (Discord, X, GitHub issues, GitHub comments). DM only.
Bot behavior, source code, and operational guarantees live in the bot's own repo: poli0981/telegram-scraper-bot (USER_GUIDE.md).
The Telegram-ID lifecycle is also described in Privacy Policy §15.
15. Final final vibes
Built with boredom, zero budget, and two AI buddies who actually read the EULA. 🚀