feat(cli): track which registry items add installs - #3099

What

Emits one registry_item_added event per registry item hyperframes add writes into a project, so the catalog can be ranked by what people actually install.

Why

cli_command records that add ran and nothing about what it installed:

trackEvent("cli_command", { command, ...runIdField(runId) })

And the registry is served from raw.githubusercontent.com, so there is no server-side counter either. The result is that "which block or component is most installed" is unanswerable today — which also means there is no signal for what is worth building more of, or what is dead weight in a 50+ item catalog.

How

The event is emitted from runAdd, immediately after installAll returns. That is the single choke point for an item reaching a project:

• The bulk add <tag> path re-enters runAdd once per item rather than installing separately, so tag installs are covered without a second call site.
• Every failure — unknown item, wrong type, compatibility gate, a write that fails — throws before this line, so a refused install is never counted as a download.

requested distinguishes the item the user named from the transitive registryDependencies pulled in behind it. Collapsing the two would rank a popular dependency above everything that depends on it, which inverts exactly the question the event exists to answer.

Properties are item, item_type, requested.

Privacy

Item names are public registry identifiers — never project names, paths, or file content. The event goes through trackEvent, which returns early unless shouldTrack(), so an install that opted out via hyperframes telemetry disable, HYPERFRAMES_NO_TELEMETRY, or DO_NOT_TRACK sends nothing. No new opt-out surface, and none needed. The telemetry docs section is updated to name what is now collected.

Test plan

• Unit tests added/updated
• Manual testing performed
• Documentation updated (if applicable) — the CLI telemetry section is updated; no new page

Two assertions in add.test.ts, both against the emitted payload rather than the transport (shouldTrack() is already false under test, so a real call and no call are indistinguishable):

• Installing dep-block, which depends on base-component, emits both, with requested true only for the item that was asked for.
• A compatibility-refused install emits nothing, folded into the existing gate test so the setup is not duplicated.

packages/cli suite green (315 tests across add + telemetry).

Verified end to end through the built CLI, with globalThis.fetch wrapped to capture the PostHog batch instead of sending it. Running from source proves nothing here: isDevMode() is true for a .ts entry, so shouldTrack() short-circuits and a real call looks exactly like no call. Faking a 200 in the hook keeps it off production analytics, since only a failed flush leaves events queued for the detached flushSync child that would bypass it.

• add code-snippet-visual-studio-dark emitted {"item":"code-snippet-visual-studio-dark","item_type":"hyperframes:block","requested":true}.
• add captions installed 16/16 and emitted exactly 16 events, one per item, item_type correct across 15 components and 1 block. This is the case worth seeing, since the tag path re-enters runAdd per item instead of having its own call site.
• HYPERFRAMES_NO_TELEMETRY=1 and DO_NOT_TRACK=1: zero batches captured, not merely zero registry_item_added — no HTTP request at all.
• An unknown item emitted nothing, exercising the refused-install branch in production code rather than a mock.

Not covered: no registry item declares registryDependencies today (grep -rl registryDependencies registry/ is empty), so requested: false cannot be exercised against the real registry and rests on the fixture-based unit test. Worth watching that the first item to take a dependency produces the expected split.

Also here: run in add.ts carries a bare fallow-ignore-next-line complexity. It is 28 cyclomatic, predates this change, and is untouched by it — Fallow scores it as new only because the file changed. Splitting its tag-fallback branch into a helper would fix it honestly, and is worth a follow-up, but not inside a telemetry change.