@kaelio/ktx 0.4.0 → 0.5.0

package/dist/sl.d.ts

@@ -1,8 +1,10 @@
-import { type KtxSqlQueryExecutorPort } from '@ktx/context/connections';
-import { createLocalKtxEmbeddingProviderFromConfig, type KtxEmbeddingPort } from '@ktx/context';
-import type { KtxSemanticLayerComputePort } from '@ktx/context/daemon';
-import { loadKtxProject } from '@ktx/context/project';
-import { type SemanticLayerQueryInput } from '@ktx/context/sl';
+import type { KtxCliIo } from './cli-runtime.js';
+import type { KtxSqlQueryExecutorPort } from './context/connections/query-executor.js';
+import type { KtxSemanticLayerComputePort } from './context/daemon/semantic-layer-compute.js';
+import { loadKtxProject } from './context/project/project.js';
+import { searchLocalSlSources as defaultSearchLocalSlSources } from './context/sl/local-sl.js';
+import type { SemanticLayerQueryInput } from './context/sl/types.js';
+import { resolveProjectEmbeddingProvider } from './embedding-resolution.js';
 import { type KtxManagedPythonInstallPolicy } from './managed-python-command.js';
 type SlQueryFormat = 'json' | 'sql';
 export type KtxSlArgs = {
@@ -11,6 +13,7 @@ export type KtxSlArgs = {
     connectionId?: string;
     output?: string;
     json?: boolean;
+    cliVersion: string;
 } | {
     command: 'search';
     projectDir: string;
@@ -19,6 +22,7 @@ export type KtxSlArgs = {
     limit?: number;
     output?: string;
     json?: boolean;
+    cliVersion: string;
 } | {
     command: 'validate';
     projectDir: string;
@@ -36,23 +40,17 @@ export type KtxSlArgs = {
     cliVersion: string;
     runtimeInstallPolicy: KtxManagedPythonInstallPolicy;
 };
-interface KtxSlIo {
-    stdout: {
-        write(chunk: string): void;
-    };
-    stderr: {
-        write(chunk: string): void;
-    };
-}
+type KtxSlIo = KtxCliIo;
 interface KtxSlDeps {
     loadProject?: typeof loadKtxProject;
-    embeddingService?: KtxEmbeddingPort | null;
-    createEmbeddingProvider?: typeof createLocalKtxEmbeddingProviderFromConfig;
+    resolveEmbeddingProvider?: typeof resolveProjectEmbeddingProvider;
+    searchLocalSlSources?: typeof defaultSearchLocalSlSources;
     createSemanticLayerCompute?: () => KtxSemanticLayerComputePort;
     createManagedSemanticLayerCompute?: (options: {
         cliVersion: string;
         installPolicy: KtxManagedPythonInstallPolicy;
         io: KtxSlIo;
+        projectDir?: string;
     }) => Promise<KtxSemanticLayerComputePort>;
     createQueryExecutor?: () => KtxSqlQueryExecutorPort;
 }

package/dist/sl.js

@@ -1,17 +1,28 @@
 import { readFile } from 'node:fs/promises';
-import { createDefaultLocalQueryExecutor } from '@ktx/context/connections';
-import { createLocalKtxEmbeddingProviderFromConfig, KtxIngestEmbeddingPortAdapter, } from '@ktx/context';
-import { loadKtxProject } from '@ktx/context/project';
-import { compileLocalSlQuery, listLocalSlSources, readLocalSlSource, searchLocalSlSources, validateLocalSlSource, } from '@ktx/context/sl';
+import { createDefaultLocalQueryExecutor } from './context/connections/local-query-executor.js';
+import { KtxIngestEmbeddingPortAdapter } from './context/llm/embedding-port.js';
+import { loadKtxProject } from './context/project/project.js';
+import { compileLocalSlQuery } from './context/sl/local-query.js';
+import { listLocalSlSources, readLocalSlSource, searchLocalSlSources as defaultSearchLocalSlSources, validateLocalSlSource } from './context/sl/local-sl.js';
+import { resolveProjectEmbeddingProvider, } from './embedding-resolution.js';
 import { createManagedPythonSemanticLayerComputePort, } from './managed-python-command.js';
 import { profileMark } from './startup-profile.js';
+import { emitTelemetryEvent } from './telemetry/index.js';
+import { scrubErrorClass } from './telemetry/scrubber.js';
 profileMark('module:sl');
-function slSearchEmbeddingService(project, deps) {
-    if ('embeddingService' in deps) {
-        return deps.embeddingService ?? null;
+function resolutionToEmbeddingPort(resolution) {
+    if (resolution.kind === 'configured' ||
+        resolution.kind === 'managed-running' ||
+        resolution.kind === 'managed-started') {
+        return new KtxIngestEmbeddingPortAdapter(resolution.provider);
     }
-    const provider = (deps.createEmbeddingProvider ?? createLocalKtxEmbeddingProviderFromConfig)(project.config.ingest.embeddings);
-    return provider ? new KtxIngestEmbeddingPortAdapter(provider) : null;
+    return null;
+}
+function queryMeasureCount(query) {
+    return Array.isArray(query.measures) ? query.measures.length : 0;
+}
+function queryDimensionCount(query) {
+    return Array.isArray(query.dimensions) ? query.dimensions.length : 0;
 }
 async function printSlSources(input) {
     const { resolveOutputMode } = await import('./io/mode.js');
@@ -75,6 +86,8 @@ async function readSlQueryFile(path) {
     return parsed;
 }
 export async function runKtxSl(args, io = process, deps = {}) {
+    const startedAt = performance.now();
+    let queryForTelemetry;
     try {
         const project = await (deps.loadProject ?? loadKtxProject)({ projectDir: args.projectDir });
         if (args.command === 'list') {
@@ -90,12 +103,24 @@ export async function runKtxSl(args, io = process, deps = {}) {
             return 0;
         }
         if (args.command === 'search') {
-            const sources = await searchLocalSlSources(project, {
+            const resolver = deps.resolveEmbeddingProvider ?? resolveProjectEmbeddingProvider;
+            const resolution = await resolver(project, {
+                mode: 'use-if-running',
+                cliVersion: args.cliVersion,
+                io,
+            });
+            const embeddingService = resolutionToEmbeddingPort(resolution);
+            const search = deps.searchLocalSlSources ?? defaultSearchLocalSlSources;
+            const sources = await search(project, {
                 connectionId: args.connectionId,
                 query: args.query,
-                embeddingService: slSearchEmbeddingService(project, deps),
+                embeddingService,
                 limit: args.limit,
             });
+            if (sources.length === 0 && resolution.kind === 'managed-unavailable' && !args.json) {
+                const { SYMBOLS } = await import('./io/symbols.js');
+                io.stderr.write(`embeddings: unavailable ${SYMBOLS.emDash} ${resolution.reason}\n`);
+            }
             await printSlSources({
                 rows: sources,
                 emptyMessage: `No semantic-layer sources matched "${args.query}" in ${project.projectDir}`,
@@ -120,6 +145,18 @@ export async function runKtxSl(args, io = process, deps = {}) {
                 connectionId: args.connectionId,
                 sourceName: args.sourceName,
             });
+            await emitTelemetryEvent({
+                name: 'sl_validate_completed',
+                projectDir: args.projectDir,
+                io,
+                fields: {
+                    sourceCount: source ? 1 : 0,
+                    modelCount: 0,
+                    validationErrorCount: result.valid ? 0 : result.errors.length,
+                    outcome: result.valid ? 'ok' : 'error',
+                    durationMs: Math.max(0, performance.now() - startedAt),
+                },
+            });
             if (!result.valid) {
                 for (const error of result.errors) {
                     io.stderr.write(`${error}\n`);
@@ -134,12 +171,14 @@ export async function runKtxSl(args, io = process, deps = {}) {
             if (!query) {
                 throw new Error('sl query requires query input from --query-file or at least one --measure');
             }
+            queryForTelemetry = query;
             const compute = deps.createSemanticLayerCompute
                 ? deps.createSemanticLayerCompute()
                 : await (deps.createManagedSemanticLayerCompute ?? createManagedPythonSemanticLayerComputePort)({
                     cliVersion: args.cliVersion,
                     installPolicy: args.runtimeInstallPolicy,
                     io,
+                    projectDir: args.projectDir,
                 });
             const queryExecutor = args.execute ? (deps.createQueryExecutor ?? createDefaultLocalQueryExecutor)() : undefined;
             const result = await compileLocalSlQuery(project, {
@@ -150,6 +189,19 @@ export async function runKtxSl(args, io = process, deps = {}) {
                 maxRows: args.maxRows,
                 queryExecutor,
             });
+            await emitTelemetryEvent({
+                name: 'sl_query_completed',
+                projectDir: args.projectDir,
+                io,
+                fields: {
+                    mode: args.execute ? 'execute' : 'compile',
+                    referencedSourceCount: result.plan && typeof result.plan === 'object' ? 1 : 0,
+                    referencedDimensionCount: queryDimensionCount(query),
+                    referencedMeasureCount: queryMeasureCount(query),
+                    durationMs: Math.max(0, performance.now() - startedAt),
+                    outcome: 'ok',
+                },
+            });
             if (args.format === 'sql') {
                 io.stdout.write(`${result.sql}\n`);
                 return 0;
@@ -161,6 +213,39 @@ export async function runKtxSl(args, io = process, deps = {}) {
         throw new Error(`Unsupported sl command: ${JSON.stringify(_exhaustive)}`);
     }
     catch (error) {
+        if (args.command === 'validate') {
+            const errorClass = scrubErrorClass(error);
+            await emitTelemetryEvent({
+                name: 'sl_validate_completed',
+                projectDir: args.projectDir,
+                io,
+                fields: {
+                    sourceCount: 0,
+                    modelCount: 0,
+                    validationErrorCount: 0,
+                    outcome: 'error',
+                    ...(errorClass ? { errorClass } : {}),
+                    durationMs: Math.max(0, performance.now() - startedAt),
+                },
+            });
+        }
+        if (args.command === 'query') {
+            const errorClass = scrubErrorClass(error);
+            await emitTelemetryEvent({
+                name: 'sl_query_completed',
+                projectDir: args.projectDir,
+                io,
+                fields: {
+                    mode: args.execute ? 'execute' : 'compile',
+                    referencedSourceCount: 0,
+                    referencedDimensionCount: queryForTelemetry ? queryDimensionCount(queryForTelemetry) : 0,
+                    referencedMeasureCount: queryForTelemetry ? queryMeasureCount(queryForTelemetry) : 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;
     }

package/dist/sl.test.js

@@ -3,7 +3,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { stripVTControlCharacters } from 'node:util';
 import Database from 'better-sqlite3';
-import { initKtxProject } from '@ktx/context/project';
+import { initKtxProject } from './context/project/project.js';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { runKtxSl } from './sl.js';
 const ORDERS_YAML = [
@@ -16,12 +16,13 @@ const ORDERS_YAML = [
     '    type: string',
     '',
 ].join('\n');
-function makeIo() {
+function makeIo(options = {}) {
     let stdout = '';
     let stderr = '';
     return {
         io: {
             stdout: {
+                isTTY: options.isTTY,
                 write: (chunk) => {
                     stdout += chunk;
                 },
@@ -46,6 +47,7 @@ describe('runKtxSl', () => {
         tempDir = await mkdtemp(join(tmpdir(), 'ktx-cli-sl-'));
     });
     afterEach(async () => {
+        vi.unstubAllEnvs();
         await rm(tempDir, { recursive: true, force: true });
     });
     it('validates, lists, and searches semantic-layer sources', async () => {
@@ -55,10 +57,17 @@ describe('runKtxSl', () => {
         await expect(runKtxSl({ command: 'validate', projectDir, connectionId: 'warehouse', sourceName: 'orders' }, validateIo.io)).resolves.toBe(0);
         expect(validateIo.stdout()).toContain('Valid semantic-layer source: warehouse/orders');
         const listIo = makeIo();
-        await expect(runKtxSl({ command: 'list', projectDir, connectionId: 'warehouse' }, listIo.io)).resolves.toBe(0);
+        await expect(runKtxSl({ command: 'list', projectDir, connectionId: 'warehouse', cliVersion: '0.0.0-test' }, listIo.io)).resolves.toBe(0);
         expect(listIo.stdout()).toContain('warehouse\torders\tcolumns=1\tmeasures=0\tjoins=0');
         const searchIo = makeIo();
-        await expect(runKtxSl({ command: 'search', projectDir, connectionId: 'warehouse', query: 'order', json: true }, searchIo.io)).resolves.toBe(0);
+        await expect(runKtxSl({
+            command: 'search',
+            projectDir,
+            connectionId: 'warehouse',
+            query: 'order',
+            json: true,
+            cliVersion: '0.0.0-test',
+        }, searchIo.io)).resolves.toBe(0);
         expect(JSON.parse(searchIo.stdout())).toMatchObject({
             kind: 'list',
             data: {
@@ -77,7 +86,14 @@ describe('runKtxSl', () => {
         const projectDir = join(tempDir, 'rank-project');
         await seedSlSource({ projectDir });
         const searchIo = makeIo();
-        await expect(runKtxSl({ command: 'search', projectDir, connectionId: 'warehouse', query: 'order', output: 'pretty' }, searchIo.io)).resolves.toBe(0);
+        await expect(runKtxSl({
+            command: 'search',
+            projectDir,
+            connectionId: 'warehouse',
+            query: 'order',
+            output: 'pretty',
+            cliVersion: '0.0.0-test',
+        }, searchIo.io)).resolves.toBe(0);
         const stdout = stripVTControlCharacters(searchIo.stdout());
         expect(stdout).toMatch(/#1\s+orders/);
         expect(stdout).not.toContain('%');
@@ -99,7 +115,14 @@ describe('runKtxSl', () => {
             ].join('\n'),
         });
         const listIo = makeIo();
-        await expect(runKtxSl({ command: 'search', projectDir, connectionId: 'warehouse', query: 'paid', json: true }, listIo.io)).resolves.toBe(0);
+        await expect(runKtxSl({
+            command: 'search',
+            projectDir,
+            connectionId: 'warehouse',
+            query: 'paid',
+            json: true,
+            cliVersion: '0.0.0-test',
+        }, listIo.io)).resolves.toBe(0);
         expect(JSON.parse(listIo.stdout())).toMatchObject({
             kind: 'list',
             data: {
@@ -186,6 +209,36 @@ joins: []
         expect(stdout.write).toHaveBeenCalledWith('select count(*) as order_count from public.orders\n');
         expect(stderr.write).not.toHaveBeenCalled();
     });
+    it('emits debug telemetry for sl query without project paths', async () => {
+        vi.stubEnv('KTX_TELEMETRY_DEBUG', '1');
+        vi.stubEnv('CI', '');
+        const projectDir = join(tempDir, 'project');
+        await seedSlSource({ projectDir });
+        const io = makeIo({ isTTY: true });
+        const createSemanticLayerCompute = vi.fn(() => ({
+            query: vi.fn(async () => ({
+                sql: 'select count(*) as order_count from public.orders',
+                dialect: 'postgres',
+                columns: [{ name: 'orders.order_count' }],
+                plan: {},
+            })),
+            validateSources: vi.fn(),
+            generateSources: vi.fn(),
+        }));
+        const code = await runKtxSl({
+            command: 'query',
+            projectDir,
+            connectionId: 'warehouse',
+            query: { measures: ['orders.order_count'], dimensions: [] },
+            format: 'json',
+            execute: false,
+            cliVersion: '0.2.0',
+            runtimeInstallPolicy: 'auto',
+        }, io.io, { createSemanticLayerCompute });
+        expect(code).toBe(0);
+        expect(io.stderr()).toContain('"event":"sl_query_completed"');
+        expect(io.stderr()).not.toContain(projectDir);
+    });
     it('runs sl query from a JSON query file', async () => {
         const projectDir = join(tempDir, 'project');
         const project = await initKtxProject({ projectDir });
@@ -277,6 +330,7 @@ joins: []
             cliVersion: '0.2.0',
             installPolicy: 'auto',
             io: { stdout, stderr },
+            projectDir,
         });
         expect(stdout.write).toHaveBeenCalledWith('select count(*) as order_count from public.orders\n');
     });
@@ -425,7 +479,7 @@ joins: []
         const projectDir = join(tempDir, 'project');
         await seedSlSource({ projectDir });
         const listIo = makeIo();
-        const code = await runKtxSl({ command: 'list', projectDir, connectionId: 'warehouse', output: 'json' }, listIo.io);
+        const code = await runKtxSl({ command: 'list', projectDir, connectionId: 'warehouse', output: 'json', cliVersion: '0.0.0-test' }, listIo.io);
         expect(code).toBe(0);
         expect(listIo.stderr()).toBe('');
         const parsed = JSON.parse(listIo.stdout());
@@ -447,11 +501,61 @@ joins: []
             joinCount: 0,
         });
     });
+    it('search prints embeddings status when results are empty', async () => {
+        const stderr = [];
+        const io = {
+            stdout: { write: (_chunk) => { } },
+            stderr: {
+                write: (chunk) => {
+                    stderr.push(chunk);
+                },
+            },
+        };
+        const projectDir = join(tempDir, 'empty-status');
+        const project = await initKtxProject({ projectDir });
+        await expect(runKtxSl({
+            command: 'search',
+            projectDir: project.projectDir,
+            query: 'nope',
+            cliVersion: '0.5.0',
+        }, io, {
+            loadProject: async () => project,
+            resolveEmbeddingProvider: async () => ({
+                kind: 'managed-unavailable',
+                reason: 'managed embeddings daemon is not running',
+            }),
+            searchLocalSlSources: async () => [],
+        })).resolves.toBe(0);
+        expect(stderr.join('')).toMatch(/embeddings: unavailable/);
+        expect(stderr.join('')).toMatch(/managed embeddings daemon is not running/);
+    });
+    it('passes a managed-daemon-backed embedding service into the search', async () => {
+        const projectDir = join(tempDir, 'resolver-project');
+        const project = await initKtxProject({ projectDir });
+        const search = vi.fn(async () => []);
+        const searchIo = makeIo();
+        await expect(runKtxSl({
+            command: 'search',
+            projectDir: project.projectDir,
+            query: 'income',
+            cliVersion: '0.5.0',
+            json: true,
+        }, searchIo.io, {
+            loadProject: async () => project,
+            resolveEmbeddingProvider: async () => ({
+                kind: 'managed-running',
+                provider: { id: 'fake' },
+                baseUrl: 'http://127.0.0.1:51234',
+            }),
+            searchLocalSlSources: search,
+        })).resolves.toBe(0);
+        expect(search).toHaveBeenCalledWith(project, expect.objectContaining({ embeddingService: expect.any(Object) }));
+    });
     it('emits sl list with grouping and Clack-style framing when output=pretty', async () => {
         const projectDir = join(tempDir, 'project');
         await seedSlSource({ projectDir });
         const listIo = makeIo();
-        const code = await runKtxSl({ command: 'list', projectDir, connectionId: 'warehouse', output: 'pretty' }, listIo.io);
+        const code = await runKtxSl({ command: 'list', projectDir, connectionId: 'warehouse', output: 'pretty', cliVersion: '0.0.0-test' }, listIo.io);
         expect(code).toBe(0);
         const stripAnsi = (s) => s.replace(/\[[0-9;]*m/g, '');
         const out = stripAnsi(listIo.stdout());

package/dist/source-mapping.d.ts

@@ -1,5 +1,6 @@
-import { type LookerMappingClient, type MetabaseRuntimeClient } from '@ktx/context/ingest';
-import { type KtxLocalProject } from '@ktx/context/project';
+import { type LookerMappingClient } from './context/ingest/adapters/looker/mapping.js';
+import type { MetabaseRuntimeClient } from './context/ingest/adapters/metabase/client-port.js';
+import { type KtxLocalProject } from './context/project/project.js';
 import type { KtxCliIo } from './cli-runtime.js';
 export type KtxSourceMappingArgs = {
     command: 'list';

package/dist/source-mapping.js

@@ -1,6 +1,16 @@
-import { localConnectionToWarehouseDescriptor } from '@ktx/context/connections';
-import { DEFAULT_METABASE_CLIENT_CONFIG, DefaultLookerConnectionClientFactory, DefaultMetabaseConnectionClientFactory, KtxYamlMetabaseSourceStateReader, LocalLookerRuntimeStore, LocalMetabaseDiscoveryCache, computeLookerMappingDrift, computeMetabaseMappingDrift, discoverLookerConnections, discoverMetabaseDatabases, lookerCredentialsFromLocalConnection, metabaseRuntimeConfigFromLocalConnection, planMetabaseFanoutChildren, seedLocalMappingStateFromKtxYaml, validateLookerMappings, validateMappingPhysicalMatch, } from '@ktx/context/ingest';
-import { ktxLocalStateDbPath, loadKtxProject } from '@ktx/context/project';
+import { localConnectionToWarehouseDescriptor } from './context/connections/local-warehouse-descriptor.js';
+import { DEFAULT_METABASE_CLIENT_CONFIG, DefaultMetabaseConnectionClientFactory } from './context/ingest/adapters/metabase/client.js';
+import { DefaultLookerConnectionClientFactory } from './context/ingest/adapters/looker/factory.js';
+import { KtxYamlMetabaseSourceStateReader, LocalMetabaseDiscoveryCache } from './context/ingest/adapters/metabase/local-source-state-store.js';
+import { LocalLookerRuntimeStore } from './context/ingest/adapters/looker/local-runtime-store.js';
+import { computeLookerMappingDrift, discoverLookerConnections, validateLookerMappings } from './context/ingest/adapters/looker/mapping.js';
+import { computeMetabaseMappingDrift, discoverMetabaseDatabases, validateMappingPhysicalMatch } from './context/ingest/adapters/metabase/mapping.js';
+import { lookerCredentialsFromLocalConnection } from './context/ingest/adapters/looker/local-looker.adapter.js';
+import { metabaseRuntimeConfigFromLocalConnection } from './context/ingest/adapters/metabase/local-metabase.adapter.js';
+import { planMetabaseFanoutChildren } from './context/ingest/adapters/metabase/fanout-planner.js';
+import { seedLocalMappingStateFromKtxYaml } from './context/ingest/local-mapping-reconcile.js';
+import { loadKtxProject } from './context/project/project.js';
+import { ktxLocalStateDbPath } from './context/project/local-state-db.js';
 import { profileMark } from './startup-profile.js';
 profileMark('module:source-mapping');
 async function createDefaultMetabaseClient(project, connectionId) {

package/dist/sql.d.ts

@@ -1,8 +1,9 @@
-import { loadKtxProject } from '@ktx/context/project';
-import type { SqlAnalysisPort } from '@ktx/context/sql-analysis';
+import { loadKtxProject } from './context/project/project.js';
+import type { SqlAnalysisPort } from './context/sql-analysis/ports.js';
 import type { KtxCliIo } from './cli-runtime.js';
+import { type KtxOutputMode } from './io/mode.js';
 import { createKtxCliScanConnector } from './local-scan-connectors.js';
-type KtxSqlOutputMode = 'pretty' | 'plain' | 'json';
+type KtxSqlOutputMode = KtxOutputMode;
 export type KtxSqlArgs = {
     command: 'execute';
     projectDir: string;

package/dist/sql.js

@@ -1,7 +1,11 @@
-import { loadKtxProject } from '@ktx/context/project';
+import { loadKtxProject } from './context/project/project.js';
+import { 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');
 function sqlAnalysisDialectForDriver(driver) {
     const normalized = String(driver ?? '').trim().toLowerCase();
@@ -20,10 +24,21 @@ function sqlAnalysisDialectForDriver(driver) {
     };
     return map[normalized] ?? 'postgres';
 }
-function resolveOutputMode(args) {
-    if (args.json === true)
-        return 'json';
-    return args.output ?? 'pretty';
+function queryVerb(sql) {
+    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, sql, dialect) {
+    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) {
     if (value === null || value === undefined)
@@ -82,23 +97,31 @@ function resultOutput(connectionId, result) {
     };
 }
 export async function runKtxSql(args, io = process, deps = {}) {
+    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`);
         }
-        const sqlAnalysis = deps.createSqlAnalysis ??
+        driver = String(connection.driver ?? 'unknown').toLowerCase();
+        demoConnection = isDemoConnection(args.connectionId, connection);
+        const createSqlAnalysis = deps.createSqlAnalysis ??
             (() => createManagedDaemonSqlAnalysisPort({
                 cliVersion: args.cliVersion,
                 projectDir: args.projectDir,
                 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 = null;
         try {
@@ -111,7 +134,21 @@ export async function runKtxSql(args, io = process, deps = {}) {
                 sql: args.sql,
                 maxRows: args.maxRows,
             }, { runId: 'cli-sql' });
-            printSqlResult(resultOutput(args.connectionId, result), resolveOutputMode(args), io);
+            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 {
@@ -119,6 +156,21 @@ export async function runKtxSql(args, io = process, deps = {}) {
         }
     }
     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;
     }

package/dist/sql.test.js

@@ -1,15 +1,17 @@
 import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { initKtxProject, parseKtxProjectConfig, serializeKtxProjectConfig } from '@ktx/context/project';
+import { initKtxProject } from './context/project/project.js';
+import { parseKtxProjectConfig, serializeKtxProjectConfig } from './context/project/config.js';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { runKtxSql } from './sql.js';
-function makeIo() {
+function makeIo(options = {}) {
     let stdout = '';
     let stderr = '';
     return {
         io: {
             stdout: {
+                isTTY: options.isTTY,
                 write: (chunk) => {
                     stdout += chunk;
                 },
@@ -27,7 +29,7 @@ function makeIo() {
 function makeSqlAnalysis(result) {
     return {
         analyzeForFingerprint: vi.fn(),
-        analyzeBatch: vi.fn(),
+        analyzeBatch: vi.fn(async () => new Map([['cli-sql', { tablesTouched: ['orders'], columnsByClause: {} }]])),
         validateReadOnly: vi.fn(async () => result),
     };
 }
@@ -67,6 +69,7 @@ describe('runKtxSql', () => {
         tempDir = await mkdtemp(join(tmpdir(), 'ktx-cli-sql-'));
     });
     afterEach(async () => {
+        vi.unstubAllEnvs();
         await rm(tempDir, { recursive: true, force: true });
     });
     async function writeConnections(projectDir, connections) {
@@ -104,6 +107,30 @@ describe('runKtxSql', () => {
         expect(io.stdout()).toContain('2 rows');
         expect(io.stderr()).toBe('');
     });
+    it('emits debug telemetry for SQL without raw query text', async () => {
+        vi.stubEnv('KTX_TELEMETRY_DEBUG', '1');
+        vi.stubEnv('CI', '');
+        const projectDir = join(tempDir, 'project');
+        await initKtxProject({ projectDir });
+        await writeConnections(projectDir, { warehouse: { driver: 'sqlite', path: 'warehouse.db' } });
+        const io = makeIo({ isTTY: true });
+        await expect(runKtxSql({
+            command: 'execute',
+            projectDir,
+            connectionId: 'warehouse',
+            sql: 'select count(*) from orders',
+            maxRows: 10,
+            output: 'json',
+            json: true,
+            cliVersion: '0.0.0-test',
+        }, io.io, {
+            createSqlAnalysis: () => makeSqlAnalysis({ ok: true, error: null }),
+            createScanConnector: vi.fn(async () => makeConnector()),
+        })).resolves.toBe(0);
+        expect(io.stderr()).toContain('"event":"sql_completed"');
+        expect(io.stderr()).toContain('"queryVerb":"select"');
+        expect(io.stderr()).not.toContain('select count(*)');
+    });
     it('prints JSON output', async () => {
         const projectDir = join(tempDir, 'project');
         await initKtxProject({ projectDir });