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/index.ts

@@ -0,0 +1,146 @@
+import { getKtxCliPackageInfo, type KtxCliIo, type KtxCliPackageInfo } from '../cli-runtime.js';
+import { loadKtxProject } from '../context/project/project.js';
+import {
+  beginCommandSpan,
+  completeCommandSpan,
+  type CommandOutcome,
+  type CompletedCommandSpan,
+} from './command-hook.js';
+import { shutdownTelemetryEmitter, trackTelemetryEvent } from './emitter.js';
+import {
+  buildCommonEnvelope,
+  buildTelemetryEvent,
+  type TelemetryCommonEnvelope,
+  type TelemetryEventName,
+  type TelemetryEventProperties,
+} from './events.js';
+import { computeTelemetryProjectId, loadTelemetryIdentity } from './identity.js';
+import { buildProjectStackSnapshotFields } from './project-snapshot.js';
+
+export { beginCommandSpan, completeCommandSpan, shutdownTelemetryEmitter };
+export type { CommandOutcome, CompletedCommandSpan };
+
+export async function showTelemetryNoticeIfNeeded(io: KtxCliIo, packageInfo: KtxCliPackageInfo): Promise<void> {
+  const identity = await loadTelemetryIdentity({
+    stdoutIsTTY: io.stdout.isTTY === true,
+    stderr: io.stderr,
+    env: process.env,
+  });
+
+  if (!identity.enabled || !identity.createdFile || !identity.installId) {
+    return;
+  }
+
+  await trackTelemetryEvent({
+    event: buildTelemetryEvent(
+      'install_first_run',
+      buildCommonEnvelope({
+        cliVersion: packageInfo.version,
+        isCi: Boolean(process.env.CI),
+      }),
+      {},
+    ),
+    distinctId: identity.installId,
+    env: process.env,
+    stderr: io.stderr,
+  });
+}
+
+type TelemetryEventFields<Name extends TelemetryEventName> = Omit<
+  TelemetryEventProperties<Name>,
+  keyof TelemetryCommonEnvelope
+>;
+
+const emittedProjectSnapshots = new Set<string>();
+const MCP_SAMPLE_RATE = 0.1 as const;
+let mcpSampled: boolean | undefined;
+
+export function shouldEmitMcpTelemetry(): boolean {
+  mcpSampled ??= Math.random() < MCP_SAMPLE_RATE;
+  return mcpSampled;
+}
+
+export function mcpTelemetrySampleRate(): 0.1 {
+  return MCP_SAMPLE_RATE;
+}
+
+export async function emitTelemetryEvent<Name extends TelemetryEventName>(input: {
+  name: Name;
+  fields: TelemetryEventFields<Name>;
+  io: KtxCliIo;
+  packageInfo?: KtxCliPackageInfo;
+  projectDir?: string;
+}): Promise<void> {
+  const identity = await loadTelemetryIdentity({
+    stdoutIsTTY: input.io.stdout.isTTY === true,
+    stderr: input.io.stderr,
+    env: process.env,
+  });
+
+  if (!identity.enabled || !identity.installId) {
+    return;
+  }
+
+  const packageInfo = input.packageInfo ?? getKtxCliPackageInfo();
+
+  const projectId = input.projectDir ? computeTelemetryProjectId(identity.installId, input.projectDir) : undefined;
+  await trackTelemetryEvent({
+    event: buildTelemetryEvent(
+      input.name,
+      buildCommonEnvelope({
+        cliVersion: packageInfo.version,
+        isCi: Boolean(process.env.CI),
+      }),
+      input.fields,
+    ),
+    distinctId: identity.installId,
+    projectId,
+    env: process.env,
+    stderr: input.io.stderr,
+  });
+}
+
+export async function emitProjectStackSnapshot(input: {
+  projectDir: string;
+  io: KtxCliIo;
+  packageInfo?: KtxCliPackageInfo;
+}): Promise<void> {
+  if (emittedProjectSnapshots.has(input.projectDir)) {
+    return;
+  }
+  emittedProjectSnapshots.add(input.projectDir);
+
+  let project: Awaited<ReturnType<typeof loadKtxProject>>;
+  try {
+    project = await loadKtxProject({ projectDir: input.projectDir });
+  } catch {
+    return;
+  }
+  await emitTelemetryEvent({
+    name: 'project_stack_snapshot',
+    fields: await buildProjectStackSnapshotFields(project),
+    projectDir: input.projectDir,
+    io: input.io,
+    packageInfo: input.packageInfo,
+  });
+}
+
+export async function emitCompletedCommand(input: {
+  completed: CompletedCommandSpan | undefined;
+  packageInfo: KtxCliPackageInfo;
+  io: KtxCliIo;
+}): Promise<void> {
+  if (!input.completed) {
+    return;
+  }
+
+  const projectDir = input.completed.projectGroupAttached ? input.completed.projectDir : undefined;
+  const { projectDir: _projectDir, ...eventFields } = input.completed;
+  await emitTelemetryEvent({
+    name: 'command',
+    fields: eventFields,
+    projectDir,
+    io: input.io,
+    packageInfo: input.packageInfo,
+  });
+}