feat(wizard): send analytics straight to PostHog (#71)

The funnel events landed in #68 posting to a Seam endpoint that would
forward them to PostHog, on the reasoning that a published CLI cannot
hold a PostHog key. The proxy bought nothing — a PostHog project key is
write-only — and it did not exist yet, so every batch a wizard run sent
was a 404 it silently dropped.

Report through the PostHog Node SDK instead, to the same project and the
same host the Console reports to (`https://e.seam.co`, Seam's PostHog
proxy). The SDK owns batching, gzip, retries and the `/batch/` wire
format; `flushAnalytics` becomes its `shutdown()`, still the only
analytics a developer waits for, still bounded.

The key stays out of this repository. `analytics-key.ts` ships an empty
placeholder that `prepack.ts` fills in from SEAM_WIZARD_POSTHOG_KEY when
the package is packed — the mechanism `version.ts` already uses for the
version — and the publish workflow passes it from a repository secret.
A build without one reports nothing at all rather than reporting
somewhere unintended, which also keeps a clone and a pull request build
silent. **The secret has to exist before the next publish**, or the
published wizard reports nothing.

The public surface of analytics.ts is unchanged, so app.tsx keeps its
call sites: what changed is the transport underneath. Two things the
Seam side used to do move here, since nothing sits between the CLI and
PostHog now:

  - `distinct_id` is namespaced `wizard_cli_<uuid>` — a Console person's
    distinct_id is a UUID too, and a run is an install, not a person;
  - the workspace group comes from the SDK's own `groups` argument
    rather than a hand-set `$groups` property.

`postWizardEvents` and its wire types are deleted with the proxy.

The SDK sets `$geoip_disable`, so the events still carry no location.
Tests assert against the real gzipped `/batch/` payload rather than a
shape of our own, which is what a local ingest server was used to verify.

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: itelo

.github/workflows/_build.yml

@@ -9,6 +9,13 @@ on:
         type: string
         required: false
         default: '24'
+    secrets:
+      posthog_project_key:
+        description: >-
+          Seam's PostHog project key, injected into the package when it is
+          packed. Without it the packed wizard reports no analytics, which is
+          what a pull request build should do.
+        required: false
     outputs:
       artifact_name:
         description: The artifact name.
@@ -30,6 +37,8 @@ jobs:
         run: npm run build
       - name: Package
         run: npm pack
+        env:
+          SEAM_WIZARD_POSTHOG_KEY: ${{ secrets.posthog_project_key }}
       - name: Upload artifact
         uses: actions/upload-artifact@v7
         with:

.github/workflows/publish.yml

@@ -12,6 +12,8 @@ jobs:
   build:
     name: Build
     uses: ./.github/workflows/_build.yml
+    secrets:
+      posthog_project_key: ${{ secrets.SEAM_WIZARD_POSTHOG_KEY }}
   release:
     name: GitHub Releases
     runs-on: ubuntu-latest

README.md

@@ -108,6 +108,14 @@ await wizard({
 - `SEAM_CONSOLE_URL`: Points the browser connection flow at a
   non-production Console.
   Defaults to `https://console.seam.co`.
+- `SEAM_WIZARD_POSTHOG_KEY`: The PostHog project
+  [analytics](#analytics) report to.
+  A packed package carries the one injected at pack time;
+  set this to report from a checkout, or to report elsewhere.
+  Without it the wizard reports nothing.
+- `SEAM_WIZARD_POSTHOG_HOST`: Points analytics at another PostHog host,
+  e.g. a local instance.
+  Defaults to `https://e.seam.co`, the host the Console reports to.
 
 ## Development and Testing
 
@@ -159,7 +167,9 @@ The wizard is an [Ink] application under `src/lib`:
 - `app.tsx` is the state machine driving the run,
   one phase per step, and holds all of the rendering.
 - `steps/` holds the logic for each step, with no UI in it.
-- `analytics.ts` reports how far a run got (see [Analytics](#analytics)).
+- `analytics.ts` reports how far a run got (see [Analytics](#analytics)),
+  with `analytics-key.ts` holding the project key the package is packed
+  with.
 - `version.ts` holds the package version reported by `--version`.
   It ships a `0.0.0` placeholder that `prepack.ts` replaces with the
   version from `package.json` when the package is packed,
@@ -192,25 +202,29 @@ and `wizard_run_finished` closes the run with the screen it ended on —
 including `outcome: 'abandoned'` for a run left with Ctrl-C
 or a closed terminal.
 
-Events are queued and posted in batches to Seam,
-which forwards them to PostHog:
-a published CLI cannot hold a PostHog key,
-so the key, sampling, and rate limiting all stay server side.
-The endpoint is unauthenticated,
-because the earliest and most interesting events happen before the
-developer has connected a key at all:
-
-```
-POST {endpoint}/seam/wizard/v1/events
-{ "events": [{ "event": "…", "distinct_id": "…", "timestamp": "…", "properties": {} }] }
-```
-
-Events are in PostHog's own capture shape so a batch can be forwarded
-straight through.
-`distinct_id` is an anonymous install id
-kept in the host CLI's settings — it identifies an install, not a
-developer — and `properties.workspace_id` is present once a run has
-connected.
+Events go to Seam's PostHog project through the
+[PostHog Node SDK][posthog-node], reported to `https://e.seam.co` —
+Seam's PostHog proxy, the same host the Console reports to.
+The SDK batches events and the wizard flushes once on the way out.
+
+The PostHog project key is not in this repository.
+`analytics-key.ts` ships an empty placeholder that `prepack.ts` fills in
+from `SEAM_WIZARD_POSTHOG_KEY` when the package is packed,
+the same way `version.ts` gets the version,
+and the publish workflow takes it from a repository secret.
+A build without one — a clone, or a pull request build — reports nothing
+at all rather than reporting somewhere unintended,
+so a run from a checkout needs `SEAM_WIZARD_POSTHOG_KEY` in the
+environment to report anywhere.
+
+`distinct_id` is an anonymous install id kept in the host CLI's
+settings, namespaced as `wizard_cli_<uuid>`:
+a Console person's `distinct_id` is a UUID too, and a run is an install,
+not a person.
+Once a run connects, its events carry `workspace_id` and join that
+workspace's PostHog group.
+
+[posthog-node]: https://posthog.com/docs/libraries/node
 
 Reporting is best effort and never affects a run:
 `track` does not throw or block the render,

package-lock.json

@@ -90,7 +90,8 @@
     "ink-text-input": "^6.0.0",
     "minimist": "^1.2.8",
     "open": "^11.0.0",
-    "pi-mcp-adapter": "^2.27.0"
+    "pi-mcp-adapter": "^2.27.0",
+    "posthog-node": "^5.51.6"
   },
   "devDependencies": {
     "@seamapi/cli": "^0.34.0",

package.json

@@ -4,12 +4,21 @@ import { fileURLToPath } from 'node:url'
 import { $ } from 'execa'
 
 const versionFile = './src/lib/version.ts'
+const analyticsKeyFile = './src/lib/analytics-key.ts'
 
 const main = async (): Promise<void> => {
   const version = await injectVersion(resolveFile(versionFile))
   // eslint-disable-next-line no-console
   console.log(`✓ Version ${version} injected into ${versionFile}`)
 
+  const injected = await injectPostHogProjectKey(resolveFile(analyticsKeyFile))
+  // eslint-disable-next-line no-console
+  console.log(
+    injected
+      ? `✓ PostHog project key injected into ${analyticsKeyFile}`
+      : `▲ No SEAM_WIZARD_POSTHOG_KEY set — this package reports no analytics`,
+  )
+
   const { command } = await $`tsc --project tsconfig.prepack.json`
   // eslint-disable-next-line no-console
   console.log(`✓ Rebuilt with '${command}'`)
@@ -31,6 +40,23 @@ const injectVersion = async (path: string): Promise<string> => {
   return version
 }
 
+// The key is a build input, not a checked-in constant: it comes from the
+// environment (a repository secret in the publish workflow). A pack without it
+// still succeeds — the package simply reports nothing — because a missing
+// analytics key must never be what stops a release.
+const injectPostHogProjectKey = async (path: string): Promise<boolean> => {
+  const key = process.env['SEAM_WIZARD_POSTHOG_KEY']
+  if (key == null || key.length === 0) return false
+
+  await replaceInFile(
+    path,
+    "const seamPostHogProjectKey = ''",
+    `const seamPostHogProjectKey = '${key}'`,
+  )
+
+  return true
+}
+
 const replaceInFile = async (
   path: string,
   placeholder: string,

prepack.ts

@@ -0,0 +1,7 @@
+// Replaced with Seam's PostHog project key when the package is packed, the same
+// way version.ts gets the version. Empty in a clone — and in any package built
+// without the key — which leaves analytics off rather than reporting somewhere
+// unintended.
+const seamPostHogProjectKey = ''
+
+export default seamPostHogProjectKey