Publish install counts as a stats.json sidecar

[andrewkchan]

What was wrong

BB servers have sent a plugin_installed telemetry event since the store shipped, but nothing ever read it back. The registry had no way to tell anyone how many people use a listing, and the store card had no popularity signal at all.

What changed

• scripts/build-stats.mjs (new, npm run build:stats) queries PostHog's HogQL API for count(DISTINCT distinct_id) of plugin_installed grouped by properties.plugin_id and writes dist/stats.json.
  • Distinct installations, not raw events: a reinstall loop must not inflate a listing.
  • Rows whose id fails the manifest's own id pattern, or whose count is not a non-negative safe integer, are dropped with a warning. Keys are emitted sorted, so an unchanged run republishes identical bytes and keeps its ETag.
  • A run that ends with no usable counts exits non-zero without writing, so an outage or a rotated key leaves the last published sidecar serving rather than zeroing every counter in the store.
  • --print writes to stdout for local inspection.
• .github/workflows/stats.yml (new) runs it daily plus on demand and uploads to bb-marketplace/stats.json in the same bucket as the manifest publish.
• README documents the format, the undercount caveat, and the required credentials.

Counts are a separate document rather than a field in marketplace.json on purpose: that schema is strict, so an unknown field there rejects the whole catalog on an older desktop, and the numbers move daily while the manifest sits unchanged behind a 304.

Deploy requirement: the production environment needs a new POSTHOG_API_KEY secret (a personal API key with project read access) and a POSTHOG_PROJECT_ID variable. Set POSTHOG_HOST if the project is not on US cloud. Until they exist the scheduled job fails and uploads nothing; the manifest publish is unaffected.

The consuming side is get-bb/bb: the server fetches this file on every catalog refresh and renders the number in the store, on mobile, and in bb plugin search.

How you verified

• Ran the script against a stub PostHog endpoint: confirmed the request carries the bearer key and the HogQL body, that a bad id and a non-numeric count are both dropped with a warning, and that the output has sorted keys and a stamped generatedAt.
• Fed that exact output through BB's own parseMarketplaceStatsJson in a scratch test in the bb checkout — it parses and reports the right count.
• Confirmed an empty result set exits 1 without writing dist/stats.json.
• npm run build still composes the manifest unchanged (63 entries).

Not run: the workflow itself, which needs the credentials above.

Fixes #

AGENT GENERATED