@kaelio/ktx 0.4.0 → 0.5.0

package/dist/telemetry/events.js

@@ -0,0 +1,347 @@
+import { arch, platform, release } from 'node:os';
+import { z } from 'zod';
+const telemetryCommonEnvelopeSchema = z
+    .object({
+    cliVersion: z.string(),
+    nodeVersion: z.string(),
+    osPlatform: z.string(),
+    osRelease: z.string(),
+    arch: z.string(),
+    runtime: z.enum(['node', 'daemon-py']),
+    isCi: z.boolean(),
+})
+    .strict();
+const installFirstRunSchema = telemetryCommonEnvelopeSchema.strict();
+const commandSchema = telemetryCommonEnvelopeSchema
+    .extend({
+    commandPath: z.array(z.string()).min(1),
+    durationMs: z.number().nonnegative(),
+    outcome: z.enum(['ok', 'error', 'aborted']),
+    errorClass: z.string().optional(),
+    flagsPresent: z.record(z.string(), z.boolean()),
+    hasProject: z.boolean(),
+    projectGroupAttached: z.boolean(),
+})
+    .strict();
+const outcomeSchema = z.enum(['ok', 'error']);
+const setupStepSchema = telemetryCommonEnvelopeSchema
+    .extend({
+    step: z.enum([
+        'project',
+        'runtime',
+        'models',
+        'embeddings',
+        'secrets',
+        'databases',
+        'database-context-depth',
+        'sources',
+        'context',
+        'agents',
+        'demo-tour',
+    ]),
+    outcome: z.enum(['completed', 'skipped', 'abandoned']),
+    durationMs: z.number().nonnegative(),
+})
+    .strict();
+const connectionAddedSchema = telemetryCommonEnvelopeSchema
+    .extend({
+    driver: z.string(),
+    isDemoConnection: z.boolean(),
+})
+    .strict();
+const connectionTestSchema = telemetryCommonEnvelopeSchema
+    .extend({
+    driver: z.string(),
+    isDemoConnection: z.boolean(),
+    outcome: outcomeSchema,
+    errorClass: z.string().optional(),
+    durationMs: z.number().nonnegative(),
+    serverVersion: z.string().optional(),
+})
+    .strict();
+const projectStackSnapshotSchema = telemetryCommonEnvelopeSchema
+    .extend({
+    connectors: z.array(z.object({ driver: z.string(), isDemo: z.boolean() }).strict()),
+    connectionCount: z.number().int().nonnegative(),
+    hasSl: z.boolean(),
+    hasWiki: z.boolean(),
+    hasMcp: z.boolean(),
+    hasManagedRuntime: z.boolean(),
+})
+    .strict();
+const rowsBucketSchema = z.enum(['<10k', '<100k', '<1M', '<10M', '>=10M']);
+const ingestCompletedSchema = telemetryCommonEnvelopeSchema
+    .extend({
+    driver: z.string(),
+    isDemoConnection: z.boolean(),
+    schemaCount: z.number().int().nonnegative(),
+    tableCount: z.number().int().nonnegative(),
+    columnCount: z.number().int().nonnegative(),
+    rowsBucket: rowsBucketSchema,
+    durationMs: z.number().nonnegative(),
+    outcome: outcomeSchema,
+    errorClass: z.string().optional(),
+})
+    .strict();
+const scanCompletedSchema = telemetryCommonEnvelopeSchema
+    .extend({
+    driver: z.string(),
+    tableCount: z.number().int().nonnegative(),
+    columnCount: z.number().int().nonnegative(),
+    inferredFkCount: z.number().int().nonnegative(),
+    declaredFkCount: z.number().int().nonnegative(),
+    durationMs: z.number().nonnegative(),
+    outcome: outcomeSchema,
+    errorClass: z.string().optional(),
+})
+    .strict();
+const slValidateCompletedSchema = telemetryCommonEnvelopeSchema
+    .extend({
+    sourceCount: z.number().int().nonnegative(),
+    modelCount: z.number().int().nonnegative(),
+    validationErrorCount: z.number().int().nonnegative(),
+    outcome: outcomeSchema,
+    errorClass: z.string().optional(),
+    durationMs: z.number().nonnegative(),
+})
+    .strict();
+const slQueryCompletedSchema = telemetryCommonEnvelopeSchema
+    .extend({
+    mode: z.enum(['compile', 'execute']),
+    referencedSourceCount: z.number().int().nonnegative(),
+    referencedDimensionCount: z.number().int().nonnegative(),
+    referencedMeasureCount: z.number().int().nonnegative(),
+    durationMs: z.number().nonnegative(),
+    outcome: outcomeSchema,
+    errorClass: z.string().optional(),
+})
+    .strict();
+const sqlCompletedSchema = telemetryCommonEnvelopeSchema
+    .extend({
+    driver: z.string(),
+    isDemoConnection: z.boolean(),
+    queryVerb: z.enum(['select', 'explain', 'show', 'with', 'other']),
+    referencedTableCount: z.number().int().nonnegative(),
+    durationMs: z.number().nonnegative(),
+    outcome: outcomeSchema,
+    errorClass: z.string().optional(),
+})
+    .strict();
+const wikiQueryCompletedSchema = telemetryCommonEnvelopeSchema
+    .extend({
+    queryLength: z.number().int().nonnegative(),
+    resultCount: z.number().int().nonnegative(),
+    durationMs: z.number().nonnegative(),
+    outcome: outcomeSchema,
+})
+    .strict();
+const mcpRequestCompletedSchema = telemetryCommonEnvelopeSchema
+    .extend({
+    toolName: z.string(),
+    outcome: outcomeSchema,
+    durationMs: z.number().nonnegative(),
+    errorClass: z.string().optional(),
+    sampleRate: z.literal(0.1),
+})
+    .strict();
+const daemonStartedSchema = telemetryCommonEnvelopeSchema
+    .extend({
+    daemonVersion: z.string(),
+    pythonVersion: z.string(),
+    runtimeVersion: z.string(),
+    startupDurationMs: z.number().nonnegative(),
+})
+    .strict();
+const daemonStoppedSchema = telemetryCommonEnvelopeSchema
+    .extend({
+    reason: z.enum(['signal', 'request', 'crash']),
+    uptimeMs: z.number().nonnegative(),
+})
+    .strict();
+const slPlanCompletedSchema = telemetryCommonEnvelopeSchema
+    .extend({
+    outcome: z.enum(['ok', 'error']),
+    stage: z.enum(['parse', 'resolve', 'compile', 'transpile']),
+    errorClass: z.string().optional(),
+    durationMs: z.number().nonnegative(),
+    sourceCount: z.number().int().nonnegative(),
+    joinCount: z.number().int().nonnegative(),
+})
+    .strict();
+const sqlGenCompletedSchema = telemetryCommonEnvelopeSchema
+    .extend({
+    outcome: z.enum(['ok', 'error']),
+    dialect: z.string(),
+    errorClass: z.string().optional(),
+    durationMs: z.number().nonnegative(),
+})
+    .strict();
+/** @internal */
+export const telemetryEventSchemas = {
+    install_first_run: installFirstRunSchema,
+    command: commandSchema,
+    setup_step: setupStepSchema,
+    connection_added: connectionAddedSchema,
+    connection_test: connectionTestSchema,
+    project_stack_snapshot: projectStackSnapshotSchema,
+    ingest_completed: ingestCompletedSchema,
+    scan_completed: scanCompletedSchema,
+    sl_validate_completed: slValidateCompletedSchema,
+    sl_query_completed: slQueryCompletedSchema,
+    sql_completed: sqlCompletedSchema,
+    wiki_query_completed: wikiQueryCompletedSchema,
+    mcp_request_completed: mcpRequestCompletedSchema,
+    daemon_started: daemonStartedSchema,
+    daemon_stopped: daemonStoppedSchema,
+    sl_plan_completed: slPlanCompletedSchema,
+    sql_gen_completed: sqlGenCompletedSchema,
+};
+/** @internal */
+export const telemetryEventCatalog = [
+    {
+        name: 'install_first_run',
+        description: 'Emitted once when ~/.ktx/telemetry.json is created.',
+        fields: [],
+    },
+    {
+        name: 'command',
+        description: 'Emitted once for each Commander action that reaches preAction.',
+        fields: [
+            'commandPath',
+            'durationMs',
+            'outcome',
+            'errorClass',
+            'flagsPresent',
+            'hasProject',
+            'projectGroupAttached',
+        ],
+    },
+    {
+        name: 'setup_step',
+        description: 'Emitted after an interactive setup step completes, skips, or aborts.',
+        fields: ['step', 'outcome', 'durationMs'],
+    },
+    {
+        name: 'connection_added',
+        description: 'Emitted when setup writes a database, source, or demo connection.',
+        fields: ['driver', 'isDemoConnection'],
+    },
+    {
+        name: 'connection_test',
+        description: 'Emitted after ktx connection test completes.',
+        fields: ['driver', 'isDemoConnection', 'outcome', 'errorClass', 'durationMs', 'serverVersion'],
+    },
+    {
+        name: 'project_stack_snapshot',
+        description: 'Emitted after commands that can summarize the local project stack.',
+        fields: ['connectors', 'connectionCount', 'hasSl', 'hasWiki', 'hasMcp', 'hasManagedRuntime'],
+    },
+    {
+        name: 'ingest_completed',
+        description: 'Emitted after a public ingest target completes.',
+        fields: [
+            'driver',
+            'isDemoConnection',
+            'schemaCount',
+            'tableCount',
+            'columnCount',
+            'rowsBucket',
+            'durationMs',
+            'outcome',
+            'errorClass',
+        ],
+    },
+    {
+        name: 'scan_completed',
+        description: 'Emitted after schema scan or relationship inference completes.',
+        fields: [
+            'driver',
+            'tableCount',
+            'columnCount',
+            'inferredFkCount',
+            'declaredFkCount',
+            'durationMs',
+            'outcome',
+            'errorClass',
+        ],
+    },
+    {
+        name: 'sl_validate_completed',
+        description: 'Emitted after ktx sl validate completes.',
+        fields: ['sourceCount', 'modelCount', 'validationErrorCount', 'outcome', 'errorClass', 'durationMs'],
+    },
+    {
+        name: 'sl_query_completed',
+        description: 'Emitted after ktx sl query compiles or executes.',
+        fields: [
+            'mode',
+            'referencedSourceCount',
+            'referencedDimensionCount',
+            'referencedMeasureCount',
+            'durationMs',
+            'outcome',
+            'errorClass',
+        ],
+    },
+    {
+        name: 'sql_completed',
+        description: 'Emitted after ktx sql completes validation and execution.',
+        fields: [
+            'driver',
+            'isDemoConnection',
+            'queryVerb',
+            'referencedTableCount',
+            'durationMs',
+            'outcome',
+            'errorClass',
+        ],
+    },
+    {
+        name: 'wiki_query_completed',
+        description: 'Emitted after a wiki query completes.',
+        fields: ['queryLength', 'resultCount', 'durationMs', 'outcome'],
+    },
+    {
+        name: 'mcp_request_completed',
+        description: 'Emitted for sampled MCP tool requests.',
+        fields: ['toolName', 'outcome', 'durationMs', 'errorClass', 'sampleRate'],
+    },
+    {
+        name: 'daemon_started',
+        description: 'Emitted when the long-lived ktx-daemon HTTP server starts.',
+        fields: ['daemonVersion', 'pythonVersion', 'runtimeVersion', 'startupDurationMs'],
+    },
+    {
+        name: 'daemon_stopped',
+        description: 'Emitted when the long-lived ktx-daemon HTTP server shuts down.',
+        fields: ['reason', 'uptimeMs'],
+    },
+    {
+        name: 'sl_plan_completed',
+        description: 'Emitted after a daemon semantic-layer planning pass completes.',
+        fields: ['outcome', 'stage', 'errorClass', 'durationMs', 'sourceCount', 'joinCount'],
+    },
+    {
+        name: 'sql_gen_completed',
+        description: 'Emitted after daemon SQL generation completes.',
+        fields: ['outcome', 'dialect', 'errorClass', 'durationMs'],
+    },
+];
+export function buildCommonEnvelope(input) {
+    return {
+        cliVersion: input.cliVersion,
+        nodeVersion: process.version,
+        osPlatform: platform(),
+        osRelease: release(),
+        arch: arch(),
+        runtime: 'node',
+        isCi: input.isCi,
+    };
+}
+export function buildTelemetryEvent(name, envelope, fields) {
+    const schema = telemetryEventSchemas[name];
+    return {
+        name,
+        properties: schema.parse({ ...envelope, ...fields }),
+    };
+}

package/dist/telemetry/events.snapshot.test.js

@@ -0,0 +1,135 @@
+import { describe, expect, it } from 'vitest';
+import { buildTelemetryEvent } from './events.js';
+const BLACKLIST = [
+    '/Users/',
+    '/home/',
+    'C:\\',
+    'localhost',
+    '.local',
+    'kaelio.com',
+    'select ',
+    'SELECT ',
+    'INSERT',
+    'CREATE',
+    '@',
+    'password',
+    'secret',
+    'token',
+    'key',
+];
+const envelope = {
+    cliVersion: '0.4.1',
+    nodeVersion: 'v22.0.0',
+    osPlatform: 'darwin',
+    osRelease: '25.0.0',
+    arch: 'arm64',
+    runtime: 'node',
+    isCi: false,
+};
+describe('telemetry privacy snapshot', () => {
+    it('does not emit known private substrings from phase 1 event payloads', () => {
+        const events = [
+            buildTelemetryEvent('install_first_run', envelope, {}),
+            buildTelemetryEvent('command', envelope, {
+                commandPath: ['ktx', 'sql'],
+                durationMs: 10,
+                outcome: 'error',
+                errorClass: 'KtxProjectMissingAbortError',
+                flagsPresent: {
+                    'project-dir': true,
+                    connection: true,
+                    c: true,
+                },
+                hasProject: false,
+                projectGroupAttached: false,
+            }),
+            buildTelemetryEvent('setup_step', envelope, {
+                step: 'databases',
+                outcome: 'completed',
+                durationMs: 42,
+            }),
+            buildTelemetryEvent('connection_added', envelope, {
+                driver: 'postgres',
+                isDemoConnection: false,
+            }),
+            buildTelemetryEvent('connection_test', envelope, {
+                driver: 'postgres',
+                isDemoConnection: false,
+                outcome: 'error',
+                errorClass: 'KtxConnectionTestAbortError',
+                durationMs: 34,
+                serverVersion: '16',
+            }),
+            buildTelemetryEvent('project_stack_snapshot', envelope, {
+                connectors: [
+                    { driver: 'sqlite', isDemo: true },
+                    { driver: 'postgres', isDemo: false },
+                ],
+                connectionCount: 2,
+                hasSl: true,
+                hasWiki: true,
+                hasMcp: true,
+                hasManagedRuntime: true,
+            }),
+            buildTelemetryEvent('ingest_completed', envelope, {
+                driver: 'postgres',
+                isDemoConnection: false,
+                schemaCount: 2,
+                tableCount: 4,
+                columnCount: 20,
+                rowsBucket: '<100k',
+                durationMs: 100,
+                outcome: 'ok',
+            }),
+            buildTelemetryEvent('scan_completed', envelope, {
+                driver: 'postgres',
+                tableCount: 4,
+                columnCount: 20,
+                inferredFkCount: 2,
+                declaredFkCount: 1,
+                durationMs: 70,
+                outcome: 'ok',
+            }),
+            buildTelemetryEvent('sl_validate_completed', envelope, {
+                sourceCount: 1,
+                modelCount: 3,
+                validationErrorCount: 0,
+                outcome: 'ok',
+                durationMs: 15,
+            }),
+            buildTelemetryEvent('sl_query_completed', envelope, {
+                mode: 'compile',
+                referencedSourceCount: 1,
+                referencedDimensionCount: 2,
+                referencedMeasureCount: 1,
+                durationMs: 18,
+                outcome: 'ok',
+            }),
+            buildTelemetryEvent('sql_completed', envelope, {
+                driver: 'postgres',
+                isDemoConnection: false,
+                queryVerb: 'select',
+                referencedTableCount: 3,
+                durationMs: 20,
+                outcome: 'ok',
+            }),
+            buildTelemetryEvent('wiki_query_completed', envelope, {
+                queryLength: 'select private_table from /Users/alice'.length,
+                resultCount: 2,
+                durationMs: 8,
+                outcome: 'ok',
+            }),
+            buildTelemetryEvent('mcp_request_completed', envelope, {
+                toolName: 'sl_query',
+                outcome: 'error',
+                errorClass: 'KtxProjectMissingAbortError',
+                durationMs: 12,
+                sampleRate: 0.1,
+            }),
+        ];
+        const payload = JSON.stringify(events);
+        for (const forbidden of BLACKLIST) {
+            expect(payload).not.toContain(forbidden);
+        }
+    });
+});

package/dist/telemetry/events.test.js

@@ -0,0 +1,136 @@
+import { describe, expect, it } from 'vitest';
+import { buildTelemetryEvent, telemetryEventCatalog, telemetryEventSchemas, } from './events.js';
+const envelope = {
+    cliVersion: '0.4.1',
+    nodeVersion: 'v22.0.0',
+    osPlatform: 'darwin',
+    osRelease: '25.0.0',
+    arch: 'arm64',
+    runtime: 'node',
+    isCi: false,
+};
+describe('telemetry event schemas', () => {
+    it('catalogs all v1 telemetry events', () => {
+        expect(telemetryEventCatalog.map((event) => event.name)).toEqual([
+            'install_first_run',
+            'command',
+            'setup_step',
+            'connection_added',
+            'connection_test',
+            'project_stack_snapshot',
+            'ingest_completed',
+            'scan_completed',
+            'sl_validate_completed',
+            'sl_query_completed',
+            'sql_completed',
+            'wiki_query_completed',
+            'mcp_request_completed',
+            'daemon_started',
+            'daemon_stopped',
+            'sl_plan_completed',
+            'sql_gen_completed',
+        ]);
+    });
+    it('builds strict daemon telemetry events', () => {
+        const daemonEnvelope = {
+            ...envelope,
+            runtime: 'daemon-py',
+            nodeVersion: '3.13.0',
+        };
+        expect(buildTelemetryEvent('sl_plan_completed', daemonEnvelope, {
+            outcome: 'ok',
+            stage: 'transpile',
+            durationMs: 25,
+            sourceCount: 2,
+            joinCount: 1,
+        })).toMatchObject({
+            name: 'sl_plan_completed',
+            properties: {
+                runtime: 'daemon-py',
+                outcome: 'ok',
+                stage: 'transpile',
+                sourceCount: 2,
+                joinCount: 1,
+            },
+        });
+        expect(() => telemetryEventSchemas.sql_gen_completed.parse({
+            ...daemonEnvelope,
+            outcome: 'ok',
+            dialect: 'postgres',
+            durationMs: 4,
+            sql: 'select * from private_table',
+        })).toThrow();
+    });
+    it('builds a strict install_first_run event', () => {
+        expect(buildTelemetryEvent('install_first_run', envelope, {})).toEqual({
+            name: 'install_first_run',
+            properties: envelope,
+        });
+    });
+    it('builds a strict command event with project grouping fields', () => {
+        expect(buildTelemetryEvent('command', envelope, {
+            commandPath: ['ktx', 'status'],
+            durationMs: 12,
+            outcome: 'ok',
+            flagsPresent: { json: true },
+            hasProject: true,
+            projectGroupAttached: true,
+        })).toEqual({
+            name: 'command',
+            properties: {
+                ...envelope,
+                commandPath: ['ktx', 'status'],
+                durationMs: 12,
+                outcome: 'ok',
+                flagsPresent: { json: true },
+                hasProject: true,
+                projectGroupAttached: true,
+            },
+        });
+    });
+    it('rejects unmodeled event properties', () => {
+        expect(() => telemetryEventSchemas.command.parse({
+            ...envelope,
+            commandPath: ['ktx', 'status'],
+            durationMs: 12,
+            outcome: 'ok',
+            flagsPresent: {},
+            hasProject: true,
+            projectGroupAttached: true,
+            tableName: 'private_table',
+        })).toThrow();
+    });
+    it('builds strict Phase 2 events without private names or text', () => {
+        expect(buildTelemetryEvent('connection_test', envelope, {
+            driver: 'postgres',
+            isDemoConnection: false,
+            outcome: 'ok',
+            durationMs: 34,
+            serverVersion: '16',
+        })).toMatchObject({
+            name: 'connection_test',
+            properties: {
+                driver: 'postgres',
+                isDemoConnection: false,
+                outcome: 'ok',
+                durationMs: 34,
+                serverVersion: '16',
+            },
+        });
+        expect(() => telemetryEventSchemas.sql_completed.parse({
+            ...envelope,
+            driver: 'postgres',
+            isDemoConnection: false,
+            queryVerb: 'select',
+            referencedTableCount: 1,
+            durationMs: 10,
+            outcome: 'ok',
+            sql: 'select * from private_table',
+        })).toThrow();
+    });
+    it('rejects raw private field names that are not in the telemetry schemas', () => {
+        expect(JSON.stringify(telemetryEventSchemas)).not.toContain('tableName');
+        expect(Object.keys(telemetryEventSchemas.sql_completed.shape)).not.toContain('sql');
+        expect(JSON.stringify(telemetryEventSchemas)).not.toContain('path');
+    });
+});

package/dist/telemetry/identity.d.ts

@@ -0,0 +1,33 @@
+/** @internal */
+export declare const TELEMETRY_NOTICE = "ktx collects anonymous usage data to improve the product. Opt out: set KTX_TELEMETRY_DISABLED=1.";
+/** @internal */
+export interface TelemetryIdentityEnv {
+    KTX_TELEMETRY_DISABLED?: string;
+    DO_NOT_TRACK?: string;
+    CI?: string;
+    NO_COLOR?: string;
+    TERM?: string;
+}
+export interface LoadTelemetryIdentityOptions {
+    homeDir?: string;
+    env?: TelemetryIdentityEnv;
+    stdoutIsTTY: boolean;
+    stderr: {
+        write(chunk: string): void;
+    };
+    now?: () => Date;
+}
+export interface TelemetryIdentityState {
+    installId?: string;
+    enabled: boolean;
+    createdFile: boolean;
+    noticeShown: boolean;
+    path: string;
+}
+export declare function loadTelemetryIdentity(options: LoadTelemetryIdentityOptions): Promise<TelemetryIdentityState>;
+export declare function computeTelemetryProjectId(installId: string, projectDir: string): string;
+export declare function readExistingTelemetryProjectId(options: {
+    projectDir: string;
+    homeDir?: string;
+    env?: Pick<TelemetryIdentityEnv, 'KTX_TELEMETRY_DISABLED' | 'DO_NOT_TRACK'>;
+}): Promise<string | undefined>;