[milnet01]

What

RetroDB checks GitHub Releases for a newer version. Admins see it on the dashboard and in Settings > System > Updates, with the release notes. Download fetches and verifies the release, and Install and restart applies it. If the new version does not come up, RetroDB rolls back to the old version by itself. Both source and standalone installs are covered.

This PR is built on #21's branch and targets main so that CI runs on it. Until #21 merges, this diff also shows #21's commits; merge #21 first.

Why

This is PASS-59-169, requested 2026-10-27. Your decisions:

• check for updates, plus a one-click install (never unattended);
• GitHub Releases as the source;
• source and standalone installs both;
• write the spec, then go straight to code, with the code as the review.

The spec is docs/specs/PASS-59-169-self-updater.md.

How

Checking. services/updater.py asks releases/latest at most once a day, or when you click Check now. Draft releases are invisible to that endpoint, so publishing the draft is what offers the update to users.

Downloading.

• It picks RetroDB-v{V}-{Platform}.zip with its line in SHA256SUMS.txt, or …-Standalone.zip with its .sha256.
• Download URLs must start with https://github.com/milnet01/RetroDB/releases/download/.
• Size caps: 3 GiB downloaded, 8 GiB unpacked.
• Extraction refuses absolute paths, .. and symlinks, and keeps Unix permission bits.

Installing.

• Install backs up the database to database/backups/pre_update_*.db, writes a plan, and starts the new version's helper. For source installs that is updater_apply.py; for standalone, retrodb --apply-update, which the top of app.py hands over before importing anything.
• The helper waits for the old process to exit, then swaps files with an undo record:
  • source: file by file, with a manifest so files a release dropped are removed;
  • standalone: the whole _internal/ folder plus the program.
• For source installs it runs the hash-locked dependency install when requirements.lock changed.
• It then restarts RetroDB and waits for /health to report the new version. Any failure restores the files and the database and restarts the old version. The outcome is written for the admin to see.

Never written: database/, logs/, data/ settings and tokens, scraped media. config.py holds only app constants, including APP_VERSION, so it is replaced from the new config.example.py. The old copy stays in the rollback folder.

Not one-click: git checkouts and LocalWebServerManager-managed installs see the notice and a link, but are not updated.

Threat model (spec §7): the checksum catches corruption and a file swapped in transit. Checking the cosign signatures release.yml already attaches is roadmap 59.170.

Mandatory-workflow checklist

• Version bumped: no, 3.33.0 is still open.
• Changelog entry: "RetroDB updates itself", in 3.33.0.
• CSS rebuilt: new features/updates.css, added to build_css.py.
• JS rebuilt: new page script updates.js, registered in build_js.py; the i18n manifest is regenerated.
• Tests run: 2309 passed, including 32 in tests/test_updater.py.
• Lockfile: not applicable.
• CLAUDE.md updated: updater contracts; .claude/rules/distribution.md notes that release asset names are now load-bearing.

Verification

End to end, on a real source install of this branch. A copy of the tree with no .git ran on port 5088. I ran the real helper exactly as Install does, using the installed version's own services/updater.py for the plan, backup and spawn:

• 3.33.0 → 3.33.1: done in 5 s. /health reports 3.33.1, config.py reads 3.33.1, the staging tree is cleaned up and rollback-3.33.0 is kept.
• 3.33.1 → a broken 3.33.2: a release whose app exits on start. Rolled back in 7 s. 3.33.1 is serving again with its own files and config.py, the new file the release added is removed, the database is restored from the backup, and the manifest is unchanged.
• Bug found by the first run, fixed: the restarted process loaded a stale config.pyc. Python checks a .pyc by the source's size and whole-second mtime, and copy2 carried over the staged mtime, so a same-size config.py edit was not recompiled. Files are now copied with a fresh mtime and __pycache__ is cleared. A regression test reproduces it.

Browser walk (Chromium, 1400px and 375px):

• the dashboard banner shows for admins;
• the Settings card shows the release notes as plain text (HTML in them stays text), and shows the git-checkout reason with no install buttons;
• Check now reached the real GitHub API: the latest published release is 3.32.0, so it reports "latest version";
• the daily-check toggle saves;
• /settings#updates opens the card;
• no page errors.

The walk also caught .btn overriding [hidden] on the buttons; fixed.

Not verified:

• a standalone (PyInstaller) update on a real bundle; only the swap logic is unit-tested, with a fake bundle;
• Windows and macOS;
• the Install button's restart overlay in a browser (this checkout is a git tree, so Install is refused);
• semgrep's registry rules (blocked locally; CI runs them).

Roadmap 59.169 lists trying it against the first real published release after this ships.

🤖 Generated with Claude Code

https://claude.ai/code/session_013s5ztLFVCcdTjjTeVcTnJr