feat: release-awareness — update banner + changelog page

[vhervatin]

What

Adds two related, opt-in features around Paca releases:

• Update banner on the home screen — appears when a newer release exists.
• "What's New" changelog page (under Administration) — lists recent releases with their notes.

Why

Self-hosters currently have no in-app way to know a new Paca version shipped, or what changed in it. This surfaces both without leaving the app.

Changes

• Backend: public GET /api/v1/version and GET /api/v1/releases, backed by a best-effort GitHub Releases client with Valkey caching. New ReleaseConfig, env-driven with safe defaults: PACA_VERSION (default dev), RELEASE_UPSTREAM_REPO (default Paca-AI/paca), RELEASE_FORK_REPO (default empty), plus cache TTL and timeout.
• Frontend: UpdateBanner on the home screen; a changelog page under Administration (sidebar item "What's New"); version-api / changelog-api query hooks.
• i18n: new keys (home.updateBanner, nav.changelog, admin.changelog) across all 9 locales.

Behavior / scope

• English stays the default; no change to existing flows.
• Best-effort: if the GitHub API is unreachable or rate-limited, the banner simply doesn't render and the page lists nothing — no errors are surfaced to the user.
• PACA_VERSION defaults to dev (unparseable), so the banner never shows on unversioned builds.
• The changelog page is a normal Administration route; it adds no new permission requirements.

Testing

• go build ./... passes; frontend tsc -b --noEmit passes.
• i18n feature keys have full parity across the 9 locales.
• Verified locally: banner shows when the running version is older than the latest release; the changelog page renders release notes and flags the running version; endpoints degrade gracefully (200 with empty payload) when GitHub is unreachable.

🤖 Generated with Claude Code

[pullfrog]

Important

Two things to address before merging: link URLs in the changelog renderer should be restricted to safe schemes, and the new release-check environment variables should be documented in services/api/.env.example.

Reviewed changes — adds a dismissible home-screen update banner and an Administration "What's New" changelog page, backed by new public /api/v1/version and /api/v1/releases endpoints that cache GitHub releases in Valkey.

• Add VersionHandler and public /api/v1/version + /api/v1/releases routes — queries GitHub releases for an upstream repo and optional fork, caches results, and performs lenient semver comparison for update detection.
• Add UpdateBanner to the home screen — conditionally rendered when an update is available and dismissible per release set via localStorage.
• Add /admin/changelog route and page — lists recent releases with a minimal custom Markdown renderer.
• Add ReleaseConfig with env-driven defaults — PACA_VERSION, RELEASE_UPSTREAM_REPO, RELEASE_FORK_REPO, RELEASE_CHECK_CACHE_TTL, RELEASE_CHECK_TIMEOUT.
• Add i18n keys across all 9 locales for the banner, navigation, and changelog page.

ℹ️ No automated tests for VersionHandler

The new handler owns version parsing, cache read/write paths, and two GitHub-dependent public endpoints, but it ships without unit or handler tests. A few small tests for parseVersion/isNewer and the cache-miss/cache-hit branches would guard against regressions once release-check behavior becomes load-bearing.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Kimi K2 (free via Pullfrog for OSS) ｜ 𝕏}

[pikann]

Thanks for the awesome PR! 🙌

Could you please fix the CI failures and resolve the problems that pullfrog raised? If you're busy, just let me know—I'd be happy to jump in and help out to get this merged. Thanks again!

[vhervatin]

I'm heading out on a trip early tomorrow morning and won't be back until the following Saturday! I'll have to look into it when I get back!

[pikann]

Enjoy your trip! No worries at all. If you'd like me to finish this up, just say the word!
Otherwise, if you handle it when you return, a quick tip: you might want to commit using your GitHub account so you get officially listed as a contributor. Have a wonderful time! ✨

[vhervatin]

Thanks @pikann! 🙌 Addressed both points pullfrog raised:

• Link safety: the changelog markdown renderer now only allows http(s)/mailto schemes — anything else (e.g. javascript:) renders as plain text instead of a link.
• Docs: documented the new release-check env vars (PACA_VERSION, RELEASE_UPSTREAM_REPO, RELEASE_FORK_REPO, RELEASE_CHECK_CACHE_TTL, RELEASE_CHECK_TIMEOUT) in services/api/.env.example.

Also fixed the lint failures (import ordering + array-index key) and re-committed under my GitHub account per your tip. CI should be green now — let me know if anything else is needed!

[pullfrog]

✅ No new issues found.

Reviewed changes — the new commits address both prior review items: URL scheme validation in the changelog page's Markdown renderer, and documentation of the new release-check environment variables.

• Added safeHref URL validation to the changelog renderer — the custom Markdown parser now restricts rendered links to http:, https:, and mailto: schemes via new URL() parsing; non-whitelisted URLs fall back to plain text.
• Added release-check env vars to services/api/.env.example — PACA_VERSION, RELEASE_UPSTREAM_REPO, RELEASE_FORK_REPO, RELEASE_CHECK_CACHE_TTL, and RELEASE_CHECK_TIMEOUT are now documented with inline comments.

  ^{｜ View workflow run ｜ Using DeepSeek Pro (free via Pullfrog for OSS) (Kimi K2 not used — the program covers this model; add its provider key to run your pick) ｜ 𝕏}

[vhervatin]

Good morning! I'm back! I finished up here and followed your suggestion! Thanks a lot. Em seg., 20 de jul. de 2026 às 03:25, Hải Huỳnh ***@***.***> escreveu:

…

*pikann* left a comment (Paca-AI/paca#294) <#294 (comment)> Enjoy your trip! No worries at all. If you'd like me to finish this up, just say the word! Otherwise, if you handle it when you return, a quick tip: you might want to commit using your GitHub account so you get officially listed as a contributor. Have a wonderful time! ✨ — Reply to this email directly, view it on GitHub <#294?email_source=notifications&email_token=ANA4ZVVABE34KGG7IHSRBID5FW3ONA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMBRHEZTONRZHAZKM4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2KYZTPN52GK4S7MNWGSY3L#issuecomment-5019376982>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ANA4ZVRVRG6UA7OPQXRCYBT5FW3ONAVCNFSNUABGKJSXA33TNF2G64TZHMYTCOBWHA2DENRSGI5US43TOVSTWNBZGIZTANBSG4ZDPILWAI> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[vhervatin]

Hi @pikann! 👋 All set on my side:

• ✅ Changelog link renderer now restricts URLs to http/https/mailto (via a safeHref helper using new URL()); anything else falls back to plain text.
• ✅ Release-check env vars documented in services/api/.env.example (PACA_VERSION, RELEASE_UPSTREAM_REPO, RELEASE_FORK_REPO, RELEASE_CHECK_CACHE_TTL, RELEASE_CHECK_TIMEOUT).
• ✅ Lint/CI fixed — all checks are green now.
• ✅ Rebased onto latest master, no conflicts (MERGEABLE).

pullfrog's latest pass reports "No new issues found." Ready for your review whenever you have a moment — thanks again for the guidance! 🙌

[pikann]

LGTM! Thank you for the contribution! 🚀