Brew-browser

brew-browser v0.4.0 — Velocity scoring + Star-History for Homebrew

Signed + notarized. macOS 13+, Apple Silicon. Auto-updates from v0.3.1 via the in-app updater.

Highlights

Trending now sorts by velocity, not raw count. The old Trending tab was a leaderboard of dep-pulled packages — ca-certificates, openssl@3, git always on top because everything depends on them. v0.4.0 fixes that by computing a per-package velocity index from the three rolling-window install counts Homebrew publishes (30d, 90d, 365d). The math is "this month's installs vs the prior eleven months' average month" — 1.0 is steady, 1.5+ is surging, 0.5 or below is cooling. The Trending tab defaults to sorting by velocity desc with 🔥 / ❄️ badges on each row. The result is what's actually accelerating right now, not what's already big — and packages with zero prior history are filtered out so a brand-new tap doesn't auto-pole-position the leaderboard.

install-on-request signal. The Trending tab now fetches Homebrew's install-on-request analytics endpoint in parallel with the primary install endpoint. The first counts installs users explicitly typed brew install <foo> for; the second includes everything pulled in as dependencies. Both numbers are available on each row internally, with the leaderboard-dominator metric (install) staying as the visible Installs column and the user-intent metric feeding the velocity computation underneath. Together they de-noise the trending signal dramatically.

Star-History for Homebrew (opt-in). When you enable Enhanced Trending History in Settings → Network, you get:

• Inline mini-sparklines on every Trending tab row, showing each package's install trajectory at a glance
• A full install-trend chart on each package's detail panel
• Server-precomputed velocity index that updates nightly (independent from the per-window-fetch computation)

This data comes from a new project-operated endpoint at brew-browser.zerologic.com/trending-history/*. It's the first outbound path in brew-browser's history that goes to infrastructure we control (rather than upstream Homebrew or GitHub), so it gets an explicit opt-in toggle and lives in its own section of the disclosure list at the bottom of Settings → Network. Off by default. Offline Mode hard-locks it off regardless. Only the package name you're viewing is sent (one HTTP GET per package); no IP is logged, no cookies, no fingerprinting. The Caddy log-redaction config that makes the privacy claim auditable is published in memory-bank/security.md §16.

The day-zero seed trick. When you opt in on day one, the historical chart isn't empty — the collector that runs on brew-browser.zerologic.com bootstraps three historical "buckets" per package from rolling-window subtraction (last 30 days, days 31–90, days 91–365). From that point forward, the nightly collector accumulates real daily snapshots; after ~30 days you have clean per-day install estimates. The historical bars fade into the background as the real daily resolution builds up on the right edge of every chart.

Settings → Network reorganization

New disclosure entry (10th in the list, was 9):

brew-browser.zerologic.com/trending-history
Enhanced trending history — opt-in, off by default

New nested subsection at the bottom of Network alongside the existing Updates panel. Single toggle, clear hint copy explaining what's sent, what's logged (nothing identifiable), what's not. Disabled with a "locked off" indicator when Offline Mode is on.

What's NOT changed

• Without opting in, nothing changes about your outbound posture. Velocity sorting and the 🔥/❄️ badges work entirely from the always-on Homebrew analytics endpoints. The only new behavior is "Trending sorts differently by default" — and you can still pick any other sort key from the column headers.
• The previous nine outbound paths are unchanged. README's disclosure section has been updated to enumerate all ten (path j = the new endpoint).

Under the hood

• +33 backend tests (473 → 506). Pin the new gates exhaustively: toggle off → FeatureDisabled (distinct from ParanoidModeBlocked so toasts route correctly), paranoid on → ParanoidModeBlocked regardless of the per-feature toggle, FirstLaunch → FeatureDisabled (opt-in posture preserved), Corrupt settings → ParanoidModeBlocked (fail-closed via inner gate), URL builder for the per-package fetch rejects path traversal exhaustively (../, spaces, ;, etc.).
• One new dependency on the backend: none. Velocity math is pure Rust in src-tauri/src/trending/velocity.rs; the parallel install + install-on-request fetch reuses the existing reqwest client. The history endpoint client is a thin GET wrapper.
• One new dependency on the collector: better-sqlite3. The collector is a separate Node 20+ ESM project at tools/trending-collector/ that ONLY runs on brew-browser.zerologic.com — the brew-browser app itself doesn't pull this in.
• New error variant feature_disabled in the BrewError union, mirrored in BrewErrorPayload with a friendly message that routes the user to Settings → Network rather than the master Offline Mode switch.

Acknowledgements

Velocity-as-the-Trending-sort idea came from a user observation: "Trending needs more algo though. It's straight from the brew APIs. We need velocity, right?" The seed-from-rolling-windows bootstrap trick followed from "Use A to create B's first debut. Then we can watch with real data from then on?" — using the same three windows we already fetch to give the historical chart something to show on day zero.

Star-History inline-row sparkline aesthetic borrowed from star-history.com's trending repo list.

Issues & feedback

github.com/msitarzewski/brew-browser/issues. Every error toast in the app has a "Report" button that pre-fills the issue with your context. Use it liberally — it's literally what the button is for.