Add CI to validate contributor runner archives

[Kyome22]

Type of Change

• Add a new runner
• Fix or improve an existing runner
• Other (site, docs, tooling)

Summary

Runner zips are committed by contributors and handed to RunCat Neo users as-is from the gallery download link. Today the only thing between the two is a maintainer reading a checklist. This adds a check that runs automatically on every pull request and reports a pass/fail verdict.

Adds .github/workflows/validate-runners.yml and .github/scripts/validate_runners.py. Only runners touched by the PR are validated; manifest/directory correspondence is always checked in full, since a manifest edit can drop an entry for a runner the PR never touched.

What it actually guarantees

The core property is that a frame archive may contain nothing but PNG files, and that every PNG consists entirely of CRC-valid chunks ending at IEND with no trailing bytes. Together those leave nowhere in the archive for a payload to hide — a stronger guarantee than scanning for known signatures, which is why there is no ClamAV step here. On top of that:

• Rejects symlinks, executables, setuid bits, encrypted entries, zip-slip paths (.., absolute paths, drive letters), zip bombs, archive comments, and data appended before or after the archive.
• Fully decodes every frame through zlib/libpng, then checks height is exactly 36px, width is 10–100px, and all frames share one size, numbered 0..N-1.
• Checks metadata.json shape, that preview.png is a real APNG, and that manifest.json and the runner directories agree in both directions — a name listed with a broken directory is silently dropped from the gallery by script.js, which is the failure this is most worth catching.

Interlaced PNGs are rejected. Adam7 is pointless at 36px tall, and Pillow cannot decode the frames of an interlaced APNG at all (load_prepare appends to decoderconfig on every seek, so frame 1 raises TypeError), so accepting one would mean giving up the full-decode check for exactly the files that are unusual.

Security posture

Runs on pull_request, not pull_request_target. This job feeds untrusted binaries to zlib, libpng, and Pillow's C decoders, so it is the last thing in this repository that should hold a writable token or secrets — the read-only fork sandbox is the actual control. That costs the ability to post a PR comment, so results land as inline annotations on the offending file plus a job summary.

There is deliberately no paths: filter: once this is a required check, a filtered-out PR would never report it and could never merge. The job takes well under a second.

Verification

Passes on all 18 existing runners in 0.13s. Verified against deliberately hostile inputs — payload appended to the zip, an MZ executable appended after a frame's IEND, a symlink entry, zip-slip, an ELF disguised as .png, a 9KB payload hidden in a tEXt chunk, Finder junk, frame gaps — each is caught with an actionable message.

Calibrated against the currently open runner PRs, which is where the real value shows:

PR	Result
#4 takibi-guruguru	passes
#8 huang-dachui	passes
#9 penguin	passes
#5 chihuahua	preview.gif instead of preview.png, 8 AppleDouble files in the zip, escapement/linkage listed twice in the manifest
#10 spamton	frames at the archive root with no spamton-frames/ directory, interlaced preview, preview is 64x76

Notes

• record-player-frames.zip is rebuilt in its own commit. It was the one runner that named frames record-player-<N>.png instead of record-player-frame-<N>.png, so it was the only existing violation. The frame images are byte-for-byte unchanged; only the zip entry names differ.
• Once merged, the check to require on main is named Validate runner assets.
• The open PRs need a close/reopen (or "Update branch") to pick the workflow up.

🤖 Generated with Claude Code