feat(telemetry): anonymous posthog usage telemetry across node cli and python daemon (#205)

* feat: add telemetry phase 1

* feat: add node telemetry event catalog

* feat: add telemetry event helpers

* feat: emit setup and connection telemetry

* feat: emit connection and stack telemetry

* feat: emit ingest and scan telemetry

* feat: emit query telemetry

* feat: emit sampled mcp telemetry

* docs: expand telemetry event catalog

* feat: add telemetry schema sync artifact

* feat: pass telemetry project id to semantic daemon

* feat: add daemon telemetry foundation

* feat: emit semantic daemon telemetry

* feat: emit daemon lifecycle telemetry

* docs: document full telemetry event catalog

* feat(telemetry): dim first-run notice

* feat(telemetry): show first-run notice before command output

* feat(telemetry): wire ktx PostHog project for live ingestion

* docs(telemetry): drop posthog project name and host from storage section

* docs(telemetry): trim to general overview and disclaimer

* docs(agents): add short telemetry guidelines

* feat(telemetry): enable posthog geoip enrichment

* docs(telemetry): drop ip-geoip note from public overview

* refactor(telemetry): drop no-op groupIdentify, rely on capture groups field

* fix(telemetry): respect CI kill switch in python daemon identity

* fix(sql): route table-count analysis to existing analyze-batch endpoint

* fix(telemetry): emit install_first_run from notice path and derive flagsPresent from commander

* fix(telemetry): read package info via getKtxCliPackageInfo to satisfy boundary check

* fix(telemetry): make python identity env={} bypass os.environ and unset CI in tests

* fix(telemetry): unset CI kill switch in cli-program-telemetry tests

packages/cli/src/telemetry/emitter.test.ts

@@ -0,0 +1,123 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  __resetTelemetryEmitterForTests,
+  shutdownTelemetryEmitter,
+  trackTelemetryEvent,
+} from './emitter.js';
+import type { BuiltTelemetryEvent } from './events.js';
+
+const captures: unknown[] = [];
+const shutdown = vi.fn(async () => {});
+
+function liveConfigId(): string {
+  return 'fixture';
+}
+
+vi.mock('posthog-node', () => ({
+  PostHog: vi.fn().mockImplementation(function () {
+    return {
+      capture: (event: unknown) => captures.push(event),
+      shutdown,
+    };
+  }),
+}));
+
+function commandEvent(): BuiltTelemetryEvent<'command'> {
+  return {
+    name: 'command',
+    properties: {
+      cliVersion: '0.4.1',
+      nodeVersion: 'v22.0.0',
+      osPlatform: 'darwin',
+      osRelease: '25.0.0',
+      arch: 'arm64',
+      runtime: 'node',
+      isCi: false,
+      commandPath: ['ktx', 'status'],
+      durationMs: 1,
+      outcome: 'ok',
+      flagsPresent: {},
+      hasProject: true,
+      projectGroupAttached: true,
+    },
+  };
+}
+
+describe('telemetry emitter', () => {
+  beforeEach(() => {
+    captures.length = 0;
+    shutdown.mockClear();
+    __resetTelemetryEmitterForTests();
+  });
+
+  it('prints debug payloads without importing or sending to PostHog', async () => {
+    const stderr: string[] = [];
+
+    await trackTelemetryEvent({
+      event: commandEvent(),
+      distinctId: 'install-1',
+      projectId: 'project-1',
+      env: { KTX_TELEMETRY_DEBUG: '1' },
+      stderr: { write: (chunk) => stderr.push(chunk) },
+    });
+
+    expect(stderr.join('')).toContain('[telemetry]');
+    expect(stderr.join('')).toContain('"event":"command"');
+    expect(captures).toEqual([]);
+  });
+
+  it('sends to PostHog by default once config constants are populated', async () => {
+    await trackTelemetryEvent({
+      event: commandEvent(),
+      distinctId: 'install-1',
+      projectId: 'project-1',
+      env: {},
+      stderr: { write: () => {} },
+    });
+
+    expect(captures).toHaveLength(1);
+    expect(captures[0]).toMatchObject({
+      distinctId: 'install-1',
+      event: 'command',
+      groups: { project: 'project-1' },
+    });
+  });
+
+  it('captures with distinctId, properties, and groups when live config is supplied', async () => {
+    await trackTelemetryEvent({
+      event: commandEvent(),
+      distinctId: 'install-1',
+      projectId: 'project-1',
+      projectApiKey: liveConfigId(),
+      host: 'https://us.i.posthog.com',
+      env: {},
+      stderr: { write: () => {} },
+    });
+
+    expect(captures).toHaveLength(1);
+    expect(captures[0]).toMatchObject({
+      distinctId: 'install-1',
+      event: 'command',
+      groups: { project: 'project-1' },
+      properties: {
+        cliVersion: '0.4.1',
+        commandPath: ['ktx', 'status'],
+      },
+    });
+  });
+
+  it('shuts down the client without throwing', async () => {
+    await trackTelemetryEvent({
+      event: commandEvent(),
+      distinctId: 'install-1',
+      projectApiKey: liveConfigId(),
+      host: 'https://us.i.posthog.com',
+      env: {},
+      stderr: { write: () => {} },
+    });
+
+    await expect(shutdownTelemetryEmitter()).resolves.toBeUndefined();
+    expect(shutdown).toHaveBeenCalledTimes(1);
+  });
+});