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

@@ -6,6 +6,9 @@ import { type KtxOutputMode, resolveOutputMode } from './io/mode.js';
 import { createKtxCliScanConnector } from './local-scan-connectors.js';
 import { createManagedDaemonSqlAnalysisPort } from './managed-python-http.js';
 import { profileMark } from './startup-profile.js';
+import { isDemoConnection } from './telemetry/demo-detect.js';
+import { emitTelemetryEvent } from './telemetry/index.js';
+import { scrubErrorClass } from './telemetry/scrubber.js';
 
 profileMark('module:sql');
 
@@ -54,6 +57,27 @@ function sqlAnalysisDialectForDriver(driver: string | undefined): SqlAnalysisDia
   return map[normalized] ?? 'postgres';
 }
 
+function queryVerb(sql: string): 'select' | 'explain' | 'show' | 'with' | 'other' {
+  const first = sql.trim().split(/\s+/, 1)[0]?.toLowerCase();
+  if (first === 'select' || first === 'explain' || first === 'show' || first === 'with') {
+    return first;
+  }
+  return 'other';
+}
+
+async function safeReferencedTableCount(
+  port: SqlAnalysisPort,
+  sql: string,
+  dialect: SqlAnalysisDialect,
+): Promise<number> {
+  try {
+    const results = await port.analyzeBatch([{ id: 'cli-sql', sql }], dialect);
+    return results.get('cli-sql')?.tablesTouched.length ?? 0;
+  } catch {
+    return 0;
+  }
+}
+
 function formatValue(value: unknown): string {
   if (value === null || value === undefined) return '';
   if (typeof value === 'string') return value;
@@ -119,14 +143,19 @@ function resultOutput(connectionId: string, result: KtxQueryResult): SqlExecutio
 }
 
 export async function runKtxSql(args: KtxSqlArgs, io: KtxCliIo = process, deps: KtxSqlDeps = {}): Promise<number> {
+  const startedAt = performance.now();
+  let driver = 'unknown';
+  let demoConnection = false;
   try {
     const project = await (deps.loadProject ?? loadKtxProject)({ projectDir: args.projectDir });
     const connection = project.config.connections[args.connectionId];
     if (!connection) {
       throw new Error(`Connection "${args.connectionId}" is not configured in ktx.yaml`);
     }
+    driver = String(connection.driver ?? 'unknown').toLowerCase();
+    demoConnection = isDemoConnection(args.connectionId, connection);
 
-    const sqlAnalysis =
+    const createSqlAnalysis =
       deps.createSqlAnalysis ??
       (() =>
         createManagedDaemonSqlAnalysisPort({
@@ -135,10 +164,13 @@ export async function runKtxSql(args: KtxSqlArgs, io: KtxCliIo = process, deps:
           installPolicy: 'auto',
           io,
         }));
-    const validation = await sqlAnalysis().validateReadOnly(args.sql, sqlAnalysisDialectForDriver(connection.driver));
+    const analysisPort = createSqlAnalysis();
+    const dialect = sqlAnalysisDialectForDriver(connection.driver);
+    const validation = await analysisPort.validateReadOnly(args.sql, dialect);
     if (!validation.ok) {
       throw new Error(validation.error ?? 'SQL is not read-only.');
     }
+    const referencedTableCount = await safeReferencedTableCount(analysisPort, args.sql, dialect);
 
     const createScanConnector = deps.createScanConnector ?? createKtxCliScanConnector;
     let connector: KtxScanConnector | null = null;
@@ -157,11 +189,39 @@ export async function runKtxSql(args: KtxSqlArgs, io: KtxCliIo = process, deps:
       );
       const mode = resolveOutputMode({ explicit: args.output, json: args.json, io });
       printSqlResult(resultOutput(args.connectionId, result), mode, io);
+      await emitTelemetryEvent({
+        name: 'sql_completed',
+        projectDir: args.projectDir,
+        io,
+        fields: {
+          driver,
+          isDemoConnection: demoConnection,
+          queryVerb: queryVerb(args.sql),
+          referencedTableCount,
+          durationMs: Math.max(0, performance.now() - startedAt),
+          outcome: 'ok',
+        },
+      });
       return 0;
     } finally {
       await cleanupConnector(connector);
     }
   } catch (error) {
+    const errorClass = scrubErrorClass(error);
+    await emitTelemetryEvent({
+      name: 'sql_completed',
+      projectDir: args.projectDir,
+      io,
+      fields: {
+        driver,
+        isDemoConnection: demoConnection,
+        queryVerb: queryVerb(args.sql),
+        referencedTableCount: 0,
+        durationMs: Math.max(0, performance.now() - startedAt),
+        outcome: 'error',
+        ...(errorClass ? { errorClass } : {}),
+      },
+    });
     io.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
     return 1;
   }