feat: attach PostHog groups to wizard analytics events (#591)

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: ablaszkiewicz

src/lib/agent/agent-runner.ts

@@ -21,7 +21,7 @@ import {
   OutroKind,
 } from '@lib/wizard-session';
 import { getOrAskForProjectData } from '@utils/setup-utils';
-import { analytics } from '@utils/analytics';
+import { analytics, groupsFromUser } from '@utils/analytics';
 import { getUI } from '@ui';
 import {
   initializeAgent,
@@ -280,6 +280,8 @@ export async function runProgram(
   getUI().setRoleAtOrganization(roleAtOrganization);
   getUI().setApiUser(user);
 
+  analytics.setGroups(groupsFromUser(user, host));
+
   // 5. Skill install (if skillId provided)
   let skillPath: string | undefined;
   if (config.skillId) {

src/utils/__tests__/analytics.test.ts

@@ -1,7 +1,8 @@
-import { Analytics } from '@utils/analytics';
+import { Analytics, groupsFromUser } from '@utils/analytics';
 import { PostHog } from 'posthog-node';
 import { v4 as uuidv4 } from 'uuid';
 import { ANALYTICS_TEAM_TAG } from '@lib/constants';
+import type { ApiUser } from '@lib/api';
 
 jest.mock('posthog-node');
 jest.mock('uuid');
@@ -154,6 +155,120 @@ describe('Analytics', () => {
     });
   });
 
+  describe('groups (before_send injection)', () => {
+    type TestEvent = Record<string, unknown> & {
+      groups?: Record<string, string>;
+    };
+    type BeforeSendFn = (event: TestEvent | null) => TestEvent | null;
+
+    const getBeforeSend = (): BeforeSendFn =>
+      (MockedPostHog.mock.calls[0][1] as { before_send: BeforeSendFn })
+        .before_send;
+
+    it('does not attach groups before setGroups is called', () => {
+      const beforeSend = getBeforeSend();
+      const event = { event: 'x', distinctId: 'd', properties: {} };
+
+      expect(beforeSend(event)).toBe(event);
+      expect(event).not.toHaveProperty('groups');
+    });
+
+    it('injects the active group map into every event', () => {
+      analytics.setGroups({
+        instance: 'https://us.posthog.com',
+        organization: 'org-1',
+        project: 'team-uuid',
+      });
+      const beforeSend = getBeforeSend();
+
+      const result = beforeSend({
+        event: 'x',
+        distinctId: 'd',
+        properties: {},
+      });
+
+      expect(result?.groups).toEqual({
+        instance: 'https://us.posthog.com',
+        organization: 'org-1',
+        project: 'team-uuid',
+      });
+    });
+
+    it('lets per-event groups override the active map', () => {
+      analytics.setGroups({ instance: 'https://us.posthog.com', project: 'a' });
+      const beforeSend = getBeforeSend();
+
+      const result = beforeSend({
+        event: 'x',
+        distinctId: 'd',
+        properties: {},
+        groups: { project: 'override' },
+      });
+
+      expect(result?.groups).toEqual({
+        instance: 'https://us.posthog.com',
+        project: 'override',
+      });
+    });
+
+    it('passes null events through untouched', () => {
+      analytics.setGroups({ instance: 'https://us.posthog.com' });
+      const beforeSend = getBeforeSend();
+
+      expect(beforeSend(null)).toBeNull();
+    });
+  });
+
+  describe('groupsFromUser', () => {
+    const userWith = (overrides: Partial<ApiUser>): ApiUser =>
+      ({
+        distinct_id: 'd',
+        organization: { id: 'org-1' },
+        team: { id: 1, uuid: 'team-uuid', organization: 'org-1' },
+        organizations: [],
+        ...overrides,
+      } as unknown as ApiUser);
+
+    it('always includes the host as the instance group', () => {
+      expect(groupsFromUser(null, 'https://us.posthog.com')).toEqual({
+        instance: 'https://us.posthog.com',
+      });
+    });
+
+    it('maps org id, customer id, and team uuid (not numeric project id)', () => {
+      const user = userWith({
+        organization: {
+          id: 'org-uuid',
+          customer_id: 'cus_123',
+        } as ApiUser['organization'],
+        team: {
+          id: 42,
+          uuid: 'team-uuid',
+          organization: 'org-uuid',
+        } as ApiUser['team'],
+      });
+
+      expect(groupsFromUser(user, 'https://eu.posthog.com')).toEqual({
+        instance: 'https://eu.posthog.com',
+        organization: 'org-uuid',
+        customer: 'cus_123',
+        project: 'team-uuid',
+      });
+    });
+
+    it('omits optional keys that are absent', () => {
+      const user = userWith({
+        organization: { id: 'org-uuid' } as ApiUser['organization'],
+        team: { id: 42, organization: 'org-uuid' } as ApiUser['team'],
+      });
+
+      expect(groupsFromUser(user, 'https://us.posthog.com')).toEqual({
+        instance: 'https://us.posthog.com',
+        organization: 'org-uuid',
+      });
+    });
+  });
+
   describe('integration with other methods', () => {
     it('should work correctly with setTag and captureException', () => {
       const error = new Error('Test error');

src/utils/analytics.ts

@@ -5,6 +5,7 @@ import {
   ANALYTICS_TEAM_TAG,
 } from '@lib/constants';
 import type { WizardSession } from '@lib/wizard-session';
+import type { ApiUser } from '@lib/api';
 import { v4 as uuidv4 } from 'uuid';
 import { debug } from './debug';
 
@@ -25,6 +26,26 @@ export function sessionProperties(
     run_phase: session.runPhase,
   };
 }
+
+export function groupsFromUser(
+  user: ApiUser | null,
+  host: string,
+): Record<string, string> {
+  const groups: Record<string, string> = { instance: host };
+  if (!user) return groups;
+
+  const organizationId = user.organization?.id;
+  if (organizationId) groups.organization = organizationId;
+
+  const customerId = user.organization?.customer_id;
+  if (customerId) groups.customer = customerId;
+
+  const projectUuid = user.team?.uuid;
+  if (projectUuid) groups.project = projectUuid;
+
+  return groups;
+}
+
 export class Analytics {
   private client: PostHog;
   private tags: Record<string, string | boolean | number | null | undefined> =
@@ -33,13 +54,20 @@ export class Analytics {
   private anonymousId: string;
   private appName = 'wizard';
   private activeFlags: Record<string, string> | null = null;
+  private groups: Record<string, string> = {};
 
   constructor() {
     this.client = new PostHog(ANALYTICS_POSTHOG_PUBLIC_PROJECT_WRITE_KEY, {
       host: ANALYTICS_HOST_URL,
       flushAt: 1,
       flushInterval: 0,
       enableExceptionAutocapture: true,
+      before_send: (event) => {
+        if (event && Object.keys(this.groups).length > 0) {
+          event.groups = { ...this.groups, ...event.groups };
+        }
+        return event;
+      },
     });
 
     this.tags = { $app_name: this.appName };
@@ -61,6 +89,10 @@ export class Analytics {
     this.tags[key] = value;
   }
 
+  setGroups(groups: Record<string, string>) {
+    this.groups = groups;
+  }
+
   captureException(error: Error, properties: Record<string, unknown> = {}) {
     this.client.captureException(error, this.distinctId ?? this.anonymousId, {
       team: ANALYTICS_TEAM_TAG,