@kaelio/ktx 0.9.0 → 0.10.0

package/dist/clack.d.ts

@@ -1,4 +1,10 @@
 import type { KtxCliIo } from './cli-runtime.js';
+export interface CliStyleEnv {
+    NO_COLOR?: string;
+    TERM?: string;
+}
+export declare function dim(text: string, env?: CliStyleEnv): string;
+export declare function cyan(text: string, env?: CliStyleEnv): string;
 export interface RailBufferedSource {
     stdoutText(): string;
     stderrText(): string;

package/dist/clack.js

@@ -1,5 +1,20 @@
 import { cancel, confirm, isCancel, log, spinner } from '@clack/prompts';
 const ESC = String.fromCharCode(0x1b);
+function ansiEnabled(env = process.env) {
+    return !env.NO_COLOR && env.TERM !== 'dumb';
+}
+function ansiColor(text, open, close, env) {
+    if (!ansiEnabled(env)) {
+        return text;
+    }
+    return `${ESC}[${open}m${text}${ESC}[${close}m`;
+}
+export function dim(text, env) {
+    return ansiColor(text, 2, 22, env);
+}
+export function cyan(text, env) {
+    return ansiColor(text, 36, 39, env);
+}
 export function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
@@ -24,10 +39,10 @@ export function createClackSpinner() {
     return spinner();
 }
 function magenta(text) {
-    return `${ESC}[35m${text}${ESC}[39m`;
+    return ansiColor(text, 35, 39);
 }
 function red(text) {
-    return `${ESC}[31m${text}${ESC}[39m`;
+    return ansiColor(text, 31, 39);
 }
 export function createStaticCliSpinner(io) {
     return {

package/dist/cli-program.d.ts

@@ -1,5 +1,6 @@
 import { Command, type CommandUnknownOpts } from '@commander-js/extra-typings';
 import type { KtxCliDeps, KtxCliIo, KtxCliPackageInfo } from './cli-runtime.js';
+import { type PrepareUpdateCheckNoticeOptions } from './update-check/update-check.js';
 export interface KtxCliCommandContext {
     io: KtxCliIo;
     deps: KtxCliDeps;
@@ -23,6 +24,7 @@ interface KtxCommanderProgramOptions {
         force: boolean;
     }, io: KtxCliIo) => Promise<number>;
 }
+type KtxCliUpdateCheckOptions = Pick<PrepareUpdateCheckNoticeOptions, 'env' | 'fetchDistTags' | 'homeDir' | 'now'>;
 export interface BuildKtxProgramOptions {
     io: KtxCliIo;
     deps: KtxCliDeps;
@@ -34,6 +36,7 @@ export interface BuildKtxProgramOptions {
     setExitCode?: (code: number) => void;
     argv?: string[];
     setTelemetryModule?: (telemetry: typeof import('./telemetry/index.js')) => void;
+    updateCheck?: KtxCliUpdateCheckOptions;
 }
 export interface CommandWithGlobalOptions {
     opts: () => object;

package/dist/cli-program.js

@@ -14,6 +14,7 @@ import { registerAdminCommands } from './admin.js';
 import { renderMissingProjectMessage } from './doctor.js';
 import { findNearestKtxProjectDir, resolveKtxProjectDir } from './project-resolver.js';
 import { profileMark, profileSpan } from './startup-profile.js';
+import { prepareUpdateCheckNotice } from './update-check/update-check.js';
 profileMark('module:cli-program');
 const PROJECT_AWARE_ROOT_COMMANDS = new Set(['setup', 'connection', 'ingest', 'wiki', 'sl', 'sql', 'status', 'mcp']);
 const PROJECT_INDEPENDENT_ADMIN_COMMANDS = new Set(['runtime', 'schema']);
@@ -319,16 +320,27 @@ export function collectCommandFlagsPresent(command) {
 }
 export function buildKtxProgram(options) {
     const program = createBaseProgram(options.packageInfo, options.io);
+    let pendingUpdateNotice = null;
     program.hook('preAction', async (_thisCommand, actionCommand) => {
         // The hidden completion command must stay silent and side-effect free: skip
-        // the telemetry notice, command span, and project checks entirely.
+        // the telemetry notice, command span, project checks, and update checks entirely.
         if (commandPath(actionCommand).includes('__complete')) {
             return;
         }
+        const commandNode = actionCommand;
+        const updateCheck = await prepareUpdateCheckNotice({
+            io: options.io,
+            env: options.updateCheck?.env,
+            fetchDistTags: options.updateCheck?.fetchDistTags,
+            homeDir: options.updateCheck?.homeDir,
+            installedVersion: options.packageInfo.version,
+            now: options.updateCheck?.now,
+            commandOptions: commandOptions(commandNode),
+        });
+        pendingUpdateNotice = updateCheck.notice;
         const telemetry = await import('./telemetry/index.js');
         options.setTelemetryModule?.(telemetry);
         await telemetry.showTelemetryNoticeIfNeeded(options.io, options.packageInfo);
-        const commandNode = actionCommand;
         const path = commandPath(commandNode);
         const projectDir = resolveCommandProjectDir(commandNode);
         const hasProject = ktxYamlExists(projectDir);
@@ -344,6 +356,12 @@ export function buildKtxProgram(options) {
         writeProjectDir(options.io, commandNode);
         ensureProjectAvailable(options.io, commandNode);
     });
+    program.hook('postAction', () => {
+        if (pendingUpdateNotice) {
+            options.io.stderr.write(pendingUpdateNotice);
+            pendingUpdateNotice = null;
+        }
+    });
     const context = {
         io: options.io,
         deps: options.deps,
@@ -407,6 +425,13 @@ export async function runCommanderKtxCli(argv, io, deps, info, options) {
                 return await runBareInteractiveCommand(program, io, context);
             }
             catch (error) {
+                const telemetry = await import('./telemetry/index.js');
+                await telemetry.reportException({
+                    error,
+                    context: { source: 'bare-interactive', handled: true, fatal: false },
+                    packageInfo: info,
+                    io,
+                });
                 io.stderr.write(`${formatCliError(error)}\n`);
                 return 1;
             }
@@ -443,6 +468,21 @@ export async function runCommanderKtxCli(argv, io, deps, info, options) {
                 outcome: commandOutcomeForParseResult(parseError, exitCode),
                 error: parseError,
             });
+            if (parseError &&
+                !isCommanderExit(parseError) &&
+                !isKtxProjectMissingAbortError(parseError)) {
+                await telemetryModule.reportException({
+                    error: parseError,
+                    context: {
+                        source: completed?.commandPath.join(' ') ?? 'commander parseAsync',
+                        handled: true,
+                        fatal: false,
+                    },
+                    projectDir: completed?.projectGroupAttached ? completed.projectDir : undefined,
+                    packageInfo: info,
+                    io,
+                });
+            }
             await telemetryModule.emitCompletedCommand({ completed, packageInfo: info, io });
             await telemetryModule.shutdownTelemetryEmitter();
         }

package/dist/cli-runtime.d.ts

@@ -47,4 +47,7 @@ export declare function runInitForCommander(args: {
     projectDir: string;
     force: boolean;
 }, io: KtxCliIo): Promise<number>;
+/** @internal */
+export declare function createGlobalExceptionReporter(io: KtxCliIo, info: KtxCliPackageInfo): (source: "uncaughtException" | "unhandledRejection", error: unknown) => Promise<void>;
+export declare function installGlobalExceptionHandlers(io: KtxCliIo, info: KtxCliPackageInfo): () => void;
 export declare function runKtxCli(argv?: string[], io?: KtxCliIo, deps?: KtxCliDeps): Promise<number>;

package/dist/cli-runtime.js

@@ -74,6 +74,48 @@ function installTelemetrySignalFlush(io, info) {
         process.off('SIGTERM', onSigterm);
     };
 }
+/** @internal */
+export function createGlobalExceptionReporter(io, info) {
+    return async (source, error) => {
+        const { reportException, shutdownTelemetryEmitter } = await import('./telemetry/index.js');
+        await reportException({
+            error,
+            context: { source, handled: false, fatal: true },
+            io,
+            packageInfo: info,
+            immediate: true,
+        });
+        await shutdownTelemetryEmitter();
+    };
+}
+export function installGlobalExceptionHandlers(io, info) {
+    const report = createGlobalExceptionReporter(io, info);
+    const handle = (source, error) => {
+        void (async () => {
+            try {
+                await report(source, error);
+            }
+            catch {
+                // Best-effort: preserve Node's process termination behavior.
+            }
+            if (error instanceof Error && error.stack) {
+                io.stderr.write(`${error.stack}\n`);
+            }
+            else {
+                io.stderr.write(`${String(error)}\n`);
+            }
+            process.exit(1);
+        })();
+    };
+    const onUncaught = (error) => handle('uncaughtException', error);
+    const onUnhandled = (reason) => handle('unhandledRejection', reason);
+    process.on('uncaughtException', onUncaught);
+    process.on('unhandledRejection', onUnhandled);
+    return () => {
+        process.off('uncaughtException', onUncaught);
+        process.off('unhandledRejection', onUnhandled);
+    };
+}
 export async function runKtxCli(argv = process.argv.slice(2), io = process, deps = {}) {
     const info = getKtxCliPackageInfo();
     profileMark('runtime:runKtxCli');
@@ -81,12 +123,14 @@ export async function runKtxCli(argv = process.argv.slice(2), io = process, deps
     // Real-process entry only: flush telemetry if interrupted. Test/programmatic
     // callers pass their own `io`, so they never install process-level handlers.
     const removeSignalFlush = io === process ? installTelemetrySignalFlush(io, info) : undefined;
+    const removeGlobalExceptionHandlers = io === process ? installGlobalExceptionHandlers(io, info) : undefined;
     try {
         return await runCommanderKtxCli(argv, io, deps, info, {
             runInit: runInitForCommander,
         });
     }
     finally {
+        removeGlobalExceptionHandlers?.();
         removeSignalFlush?.();
     }
 }

package/dist/commands/setup-commands.js

@@ -89,7 +89,6 @@ function shouldShowSetupEntryMenu(options, command) {
         'llmBackend',
         'anthropicApiKeyEnv',
         'anthropicApiKeyFile',
-        'llmModel',
         'vertexProject',
         'vertexLocation',
         'skipLlm',
@@ -145,7 +144,6 @@ export function registerSetupCommands(program, context) {
         .addOption(new Option('--llm-backend <backend>', 'LLM backend').argParser(llmBackend).hideHelp())
         .addOption(new Option('--anthropic-api-key-env <name>', 'Environment variable containing the Anthropic API key').hideHelp())
         .addOption(new Option('--anthropic-api-key-file <path>', 'File containing the Anthropic API key').hideHelp())
-        .addOption(new Option('--llm-model <model>', 'LLM model ID or backend model alias').hideHelp())
         .addOption(new Option('--vertex-project <project>', 'Google Vertex AI project ID, env:NAME, or file:/path').hideHelp())
         .addOption(new Option('--vertex-location <location>', 'Google Vertex AI location, env:NAME, or file:/path').hideHelp())
         .addOption(new Option('--skip-llm', 'Leave LLM setup incomplete for now').hideHelp().default(false))
@@ -272,6 +270,7 @@ export function registerSetupCommands(program, context) {
             return;
         }
         const resolvedAgentScope = options.local ? 'local' : options.global ? 'global' : 'project';
+        const debugEnabled = (command.optsWithGlobals ? command.optsWithGlobals() : command.opts()).debug === true;
         await runSetupArgs(context, {
             command: 'run',
             projectDir: resolveCommandProjectDir(command),
@@ -281,12 +280,12 @@ export function registerSetupCommands(program, context) {
             agentScope: resolvedAgentScope,
             skipAgents: options.skipAgents === true,
             inputMode: options.input === false ? 'disabled' : 'auto',
+            ...(debugEnabled ? { debug: true } : {}),
             yes: options.yes === true,
             cliVersion: context.packageInfo.version,
             ...(options.llmBackend ? { llmBackend: options.llmBackend } : {}),
             ...(options.anthropicApiKeyEnv ? { anthropicApiKeyEnv: options.anthropicApiKeyEnv } : {}),
             ...(options.anthropicApiKeyFile ? { anthropicApiKeyFile: options.anthropicApiKeyFile } : {}),
-            ...(options.llmModel ? { llmModel: options.llmModel } : {}),
             ...(options.vertexProject ? { vertexProject: options.vertexProject } : {}),
             ...(options.vertexLocation ? { vertexLocation: options.vertexLocation } : {}),
             skipLlm: options.skipLlm === true,

package/dist/connection.js

@@ -12,7 +12,8 @@ import { bold, dim, green, red, SYMBOLS } from './io/symbols.js';
 import { createKtxCliScanConnector } from './local-scan-connectors.js';
 import { profileMark } from './startup-profile.js';
 import { isDemoConnection } from './telemetry/demo-detect.js';
-import { emitTelemetryEvent } from './telemetry/index.js';
+import { emitTelemetryEvent, reportException } from './telemetry/index.js';
+import { collectTelemetryRedactionSecrets } from './telemetry/redaction-secrets.js';
 import { formatErrorDetail, scrubErrorClass } from './telemetry/scrubber.js';
 profileMark('module:connection');
 const SUPPORTED_TEST_DRIVERS = [
@@ -44,6 +45,12 @@ async function testNativeConnection(project, connectionId, createScanConnector)
         }
         const result = await connector.testConnection();
         if (!result.success) {
+            // Re-throw the driver's original error so connection_test telemetry records
+            // its real class (e.g. ConnectionError) and code (e.g. ELOGIN) instead of
+            // collapsing every native failure to a generic Error with no code.
+            if (result.cause instanceof Error) {
+                throw result.cause;
+            }
             throw new Error(result.error ?? 'connection test failed');
         }
         return { driver: connector.driver };
@@ -182,6 +189,21 @@ async function emitConnectionTest(input) {
             ...(errorDetail ? { errorDetail } : {}),
         },
     });
+    if (input.error) {
+        await reportException({
+            error: input.error,
+            context: { source: 'connection test', handled: true, fatal: false },
+            projectDir: input.project.projectDir,
+            io: input.io,
+            redactionSecrets: await collectTelemetryRedactionSecrets({
+                project: input.project,
+                connectionId: input.connectionId,
+                includeLlm: false,
+                includeEmbeddings: false,
+                env: process.env,
+            }),
+        });
+    }
 }
 function visualWidth(text) {
     // styleText wraps content in ANSI escape sequences; strip them before measuring.

package/dist/connectors/bigquery/connector.d.ts

@@ -1,5 +1,5 @@
 import { type TableField } from '@google-cloud/bigquery';
-import { type KtxColumnSampleInput, type KtxColumnSampleResult, type KtxColumnStatsInput, type KtxColumnStatsResult, type KtxQueryResult, type KtxReadOnlyQueryInput, type KtxScanConnector, type KtxScanContext, type KtxScanInput, type KtxSchemaSnapshot, type KtxTableListEntry, type KtxTableRef, type KtxTableSampleInput, type KtxTableSampleResult } from '../../context/scan/types.js';
+import { type KtxConnectorTestResult, type KtxColumnSampleInput, type KtxColumnSampleResult, type KtxColumnStatsInput, type KtxColumnStatsResult, type KtxQueryResult, type KtxReadOnlyQueryInput, type KtxScanConnector, type KtxScanContext, type KtxScanInput, type KtxSchemaSnapshot, type KtxTableListEntry, type KtxTableRef, type KtxTableSampleInput, type KtxTableSampleResult } from '../../context/scan/types.js';
 export interface KtxBigQueryConnectionConfig {
     driver?: string;
     dataset_id?: string;
@@ -121,10 +121,7 @@ export declare class KtxBigQueryScanConnector implements KtxScanConnector {
     private readonly dialect;
     private client;
     constructor(options: KtxBigQueryScanConnectorOptions);
-    testConnection(): Promise<{
-        success: boolean;
-        error?: string;
-    }>;
+    testConnection(): Promise<KtxConnectorTestResult>;
     introspect(input: KtxScanInput, _ctx: KtxScanContext): Promise<KtxSchemaSnapshot>;
     sampleTable(input: KtxTableSampleInput, _ctx: KtxScanContext): Promise<KtxTableSampleResult & {
         headerTypes?: string[];

package/dist/connectors/bigquery/connector.js

@@ -4,7 +4,7 @@ import { getDialectForDriver } from '../../context/connections/dialects.js';
 import { assertReadOnlySql, limitSqlForExecution } from '../../context/connections/read-only-sql.js';
 import { tryConstraintQuery } from '../../context/scan/constraint-discovery.js';
 import { scopedTableNames } from '../../context/scan/table-ref.js';
-import { createKtxConnectorCapabilities, } from '../../context/scan/types.js';
+import { connectorTestFailure, createKtxConnectorCapabilities, } from '../../context/scan/types.js';
 import { readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { resolve } from 'node:path';
@@ -185,7 +185,7 @@ export class KtxBigQueryScanConnector {
             return { success: true };
         }
         catch (error) {
-            return { success: false, error: error instanceof Error ? error.message : String(error) };
+            return connectorTestFailure(error);
         }
     }
     async introspect(input, _ctx) {

package/dist/connectors/clickhouse/connector.d.ts

@@ -1,5 +1,5 @@
 import { createClient } from '@clickhouse/client';
-import { type KtxColumnSampleInput, type KtxColumnSampleResult, type KtxColumnStatsInput, type KtxColumnStatsResult, type KtxQueryResult, type KtxReadOnlyQueryInput, type KtxScanConnector, type KtxScanContext, type KtxScanInput, type KtxSchemaSnapshot, type KtxTableRef, type KtxTableSampleInput, type KtxTableListEntry, type KtxTableSampleResult } from '../../context/scan/types.js';
+import { type KtxConnectorTestResult, type KtxColumnSampleInput, type KtxColumnSampleResult, type KtxColumnStatsInput, type KtxColumnStatsResult, type KtxQueryResult, type KtxReadOnlyQueryInput, type KtxScanConnector, type KtxScanContext, type KtxScanInput, type KtxSchemaSnapshot, type KtxTableRef, type KtxTableSampleInput, type KtxTableListEntry, type KtxTableSampleResult } from '../../context/scan/types.js';
 export interface KtxClickHouseConnectionConfig {
     driver?: string;
     host?: string;
@@ -94,10 +94,7 @@ export declare class KtxClickHouseScanConnector implements KtxScanConnector {
     private client;
     private resolvedEndpoint;
     constructor(options: KtxClickHouseScanConnectorOptions);
-    testConnection(): Promise<{
-        success: boolean;
-        error?: string;
-    }>;
+    testConnection(): Promise<KtxConnectorTestResult>;
     introspect(input: KtxScanInput, _ctx: KtxScanContext): Promise<KtxSchemaSnapshot>;
     private emptySnapshot;
     sampleTable(input: KtxTableSampleInput, _ctx: KtxScanContext): Promise<KtxTableSampleResult>;

package/dist/connectors/clickhouse/connector.js

@@ -1,7 +1,7 @@
 import { createClient } from '@clickhouse/client';
 import { getDialectForDriver } from '../../context/connections/dialects.js';
 import { assertReadOnlySql, limitSqlForExecution } from '../../context/connections/read-only-sql.js';
-import { createKtxConnectorCapabilities } from '../../context/scan/types.js';
+import { connectorTestFailure, createKtxConnectorCapabilities } from '../../context/scan/types.js';
 import { scopedTableNames } from '../../context/scan/table-ref.js';
 import { readFileSync } from 'node:fs';
 import { Agent as HttpsAgent } from 'node:https';
@@ -162,7 +162,7 @@ export class KtxClickHouseScanConnector {
             return { success: true };
         }
         catch (error) {
-            return { success: false, error: error instanceof Error ? error.message : String(error) };
+            return connectorTestFailure(error);
         }
     }
     async introspect(input, _ctx) {

package/dist/connectors/mysql/connector.d.ts

@@ -1,5 +1,5 @@
 import { type FieldPacket, type RowDataPacket } from 'mysql2/promise';
-import { type KtxColumnSampleInput, type KtxColumnSampleResult, type KtxColumnStatsInput, type KtxColumnStatsResult, type KtxQueryResult, type KtxReadOnlyQueryInput, type KtxScanConnector, type KtxScanContext, type KtxScanInput, type KtxSchemaSnapshot, type KtxTableListEntry, type KtxTableRef, type KtxTableSampleInput, type KtxTableSampleResult } from '../../context/scan/types.js';
+import { type KtxConnectorTestResult, type KtxColumnSampleInput, type KtxColumnSampleResult, type KtxColumnStatsInput, type KtxColumnStatsResult, type KtxQueryResult, type KtxReadOnlyQueryInput, type KtxScanConnector, type KtxScanContext, type KtxScanInput, type KtxSchemaSnapshot, type KtxTableListEntry, type KtxTableRef, type KtxTableSampleInput, type KtxTableSampleResult } from '../../context/scan/types.js';
 export interface KtxMysqlConnectionConfig {
     driver?: string;
     host?: string;
@@ -71,6 +71,9 @@ export interface KtxMysqlColumnDistinctValuesResult {
     values: string[] | null;
     cardinality: number;
 }
+export interface KtxMysqlColumnStatisticsResult {
+    cardinalityByColumn: Map<string, number>;
+}
 /** @internal */
 export declare function prepareMysqlReadOnlyQuery(sql: string, params?: Record<string, unknown>): {
     sql: string;
@@ -97,15 +100,13 @@ export declare class KtxMysqlScanConnector implements KtxScanConnector {
     private pool;
     private resolvedEndpoint;
     constructor(options: KtxMysqlScanConnectorOptions);
-    testConnection(): Promise<{
-        success: boolean;
-        error?: string;
-    }>;
+    testConnection(): Promise<KtxConnectorTestResult>;
     introspect(input: KtxScanInput, _ctx: KtxScanContext): Promise<KtxSchemaSnapshot>;
     private emptySnapshot;
     sampleTable(input: KtxTableSampleInput, _ctx: KtxScanContext): Promise<KtxTableSampleResult>;
     sampleColumn(input: KtxColumnSampleInput, _ctx: KtxScanContext): Promise<KtxColumnSampleResult>;
-    columnStats(_input: KtxColumnStatsInput, _ctx: KtxScanContext): Promise<KtxColumnStatsResult | null>;
+    columnStats(input: KtxColumnStatsInput, _ctx: KtxScanContext): Promise<KtxColumnStatsResult | null>;
+    getColumnStatistics(table: KtxTableRef): Promise<KtxMysqlColumnStatisticsResult | null>;
     executeReadOnly(input: KtxMysqlReadOnlyQueryInput, _ctx: KtxScanContext): Promise<KtxQueryResult>;
     getColumnDistinctValues(table: KtxTableRef, columnName: string, options: KtxMysqlColumnDistinctValuesOptions): Promise<KtxMysqlColumnDistinctValuesResult | null>;
     getTableRowCount(tableName: string): Promise<number>;

package/dist/connectors/mysql/connector.js

@@ -6,7 +6,7 @@ import { getDialectForDriver } from '../../context/connections/dialects.js';
 import { assertReadOnlySql, limitSqlForExecution } from '../../context/connections/read-only-sql.js';
 import { constraintDiscoveryWarning, tryConstraintQuery, } from '../../context/scan/constraint-discovery.js';
 import { scopedTableNames } from '../../context/scan/table-ref.js';
-import { createKtxConnectorCapabilities, } from '../../context/scan/types.js';
+import { connectorTestFailure, createKtxConnectorCapabilities, } from '../../context/scan/types.js';
 class DefaultMysqlPoolFactory {
     createPool(config) {
         return mysql.createPool(config);
@@ -185,7 +185,7 @@ export class KtxMysqlScanConnector {
     capabilities = createKtxConnectorCapabilities({
         tableSampling: true,
         columnSampling: true,
-        columnStats: false,
+        columnStats: true,
         readOnlySql: true,
         nestedAnalysis: true,
         formalForeignKeys: true,
@@ -219,7 +219,7 @@ export class KtxMysqlScanConnector {
             return { success: true };
         }
         catch (error) {
-            return { success: false, error: error instanceof Error ? error.message : String(error) };
+            return connectorTestFailure(error);
         }
     }
     async introspect(input, _ctx) {
@@ -324,8 +324,28 @@ export class KtxMysqlScanConnector {
         const values = result.rows.filter((row) => row.length > 0 && row[0] !== null).map((row) => row[0]);
         return { values, nullCount: null, distinctCount: null };
     }
-    async columnStats(_input, _ctx) {
-        return null;
+    async columnStats(input, _ctx) {
+        const stats = await this.getColumnStatistics(input.table);
+        const value = stats?.cardinalityByColumn.get(input.column);
+        return value === undefined
+            ? null
+            : { min: null, max: null, average: null, nullCount: null, distinctCount: value };
+    }
+    async getColumnStatistics(table) {
+        const schema = table.db ?? this.poolConfig.database;
+        const sql = this.dialect.generateColumnStatisticsQuery(schema, table.name);
+        if (!sql) {
+            return null;
+        }
+        const rows = await this.queryRaw(sql);
+        const cardinalityByColumn = new Map();
+        for (const row of rows) {
+            const cardinality = Number(row.estimated_cardinality);
+            if (Number.isFinite(cardinality) && cardinality >= 0) {
+                cardinalityByColumn.set(row.column_name, cardinality);
+            }
+        }
+        return cardinalityByColumn.size > 0 ? { cardinalityByColumn } : null;
     }
     async executeReadOnly(input, _ctx) {
         this.assertConnection(input.connectionId);

package/dist/connectors/mysql/dialect.d.ts

@@ -25,7 +25,7 @@ export declare class KtxMysqlDialect implements KtxDialect {
     getSampleValueAggregation(innerSql: string): string;
     generateCardinalitySampleQuery(tableName: string, columnName: string, sampleSize: number): string;
     generateDistinctValuesQuery(tableName: string, columnName: string, limit: number): string;
-    generateColumnStatisticsQuery(_schemaName: string, _tableName: string): string | null;
+    generateColumnStatisticsQuery(schemaName: string, tableName: string): string | null;
     generateRandomizedCardinalitySampleQuery(tableName: string, columnName: string, sampleSize: number): string;
 }
 export {};

package/dist/connectors/mysql/dialect.js

@@ -135,8 +135,18 @@ export class KtxMysqlDialect {
       LIMIT ${limit}
     `;
     }
-    generateColumnStatisticsQuery(_schemaName, _tableName) {
-        return null;
+    generateColumnStatisticsQuery(schemaName, tableName) {
+        return `
+      SELECT
+        COLUMN_NAME AS column_name,
+        MAX(CARDINALITY) AS estimated_cardinality
+      FROM INFORMATION_SCHEMA.STATISTICS
+      WHERE TABLE_SCHEMA = '${schemaName.replace(/'/g, "''")}'
+        AND TABLE_NAME = '${tableName.replace(/'/g, "''")}'
+        AND CARDINALITY IS NOT NULL
+        AND SEQ_IN_INDEX = 1
+      GROUP BY COLUMN_NAME
+    `;
     }
     generateRandomizedCardinalitySampleQuery(tableName, columnName, sampleSize) {
         return `

package/dist/connectors/postgres/connector.d.ts

@@ -1,4 +1,4 @@
-import { type KtxColumnSampleInput, type KtxColumnSampleResult, type KtxColumnStatsInput, type KtxColumnStatsResult, type KtxQueryResult, type KtxReadOnlyQueryInput, type KtxScanConnector, type KtxScanContext, type KtxScanInput, type KtxSchemaSnapshot, type KtxTableListEntry, type KtxTableRef, type KtxTableSampleInput, type KtxTableSampleResult } from '../../context/scan/types.js';
+import { type KtxConnectorTestResult, type KtxColumnSampleInput, type KtxColumnSampleResult, type KtxColumnStatsInput, type KtxColumnStatsResult, type KtxQueryResult, type KtxReadOnlyQueryInput, type KtxScanConnector, type KtxScanContext, type KtxScanInput, type KtxSchemaSnapshot, type KtxTableListEntry, type KtxTableRef, type KtxTableSampleInput, type KtxTableSampleResult } from '../../context/scan/types.js';
 export interface KtxPostgresConnectionConfig {
     driver?: string;
     host?: string;
@@ -117,10 +117,7 @@ export declare class KtxPostgresScanConnector implements KtxScanConnector {
     private lastIdlePoolError;
     private resolvedEndpoint;
     constructor(options: KtxPostgresScanConnectorOptions);
-    testConnection(): Promise<{
-        success: boolean;
-        error?: string;
-    }>;
+    testConnection(): Promise<KtxConnectorTestResult>;
     introspect(input: KtxScanInput, _ctx: KtxScanContext): Promise<KtxSchemaSnapshot>;
     sampleTable(input: KtxTableSampleInput, _ctx: KtxScanContext): Promise<KtxPostgresTableSampleResult>;
     sampleColumn(input: KtxColumnSampleInput, _ctx: KtxScanContext): Promise<KtxColumnSampleResult>;

package/dist/connectors/postgres/connector.js

@@ -5,7 +5,7 @@ import { getDialectForDriver } from '../../context/connections/dialects.js';
 import { assertReadOnlySql, limitSqlForExecution } from '../../context/connections/read-only-sql.js';
 import { tryConstraintQuery } from '../../context/scan/constraint-discovery.js';
 import { scopedTableNames } from '../../context/scan/table-ref.js';
-import { createKtxConnectorCapabilities, } from '../../context/scan/types.js';
+import { connectorTestFailure, createKtxConnectorCapabilities, } from '../../context/scan/types.js';
 import { Pool } from 'pg';
 const PG_OID_TYPE_MAP = {
     16: 'boolean',
@@ -231,7 +231,7 @@ export class KtxPostgresScanConnector {
             return { success: true };
         }
         catch (error) {
-            return { success: false, error: error instanceof Error ? error.message : String(error) };
+            return connectorTestFailure(error);
         }
     }
     async introspect(input, _ctx) {

package/dist/connectors/snowflake/connector.d.ts

@@ -1,4 +1,4 @@
-import { type KtxColumnSampleInput, type KtxColumnSampleResult, type KtxColumnStatsInput, type KtxColumnStatsResult, type KtxQueryResult, type KtxReadOnlyQueryInput, type KtxScanConnector, type KtxScanContext, type KtxScanInput, type KtxSchemaSnapshot, type KtxTableListEntry, type KtxTableRef, type KtxTableSampleInput, type KtxTableSampleResult } from '../../context/scan/types.js';
+import { type KtxConnectorTestResult, type KtxColumnSampleInput, type KtxColumnSampleResult, type KtxColumnStatsInput, type KtxColumnStatsResult, type KtxQueryResult, type KtxReadOnlyQueryInput, type KtxScanConnector, type KtxScanContext, type KtxScanInput, type KtxSchemaSnapshot, type KtxTableListEntry, type KtxTableRef, type KtxTableSampleInput, type KtxTableSampleResult } from '../../context/scan/types.js';
 export interface KtxSnowflakeConnectionConfig {
     driver?: string;
     authMethod?: 'password' | 'rsa';
@@ -117,10 +117,7 @@ export declare class KtxSnowflakeScanConnector implements KtxScanConnector {
     private readonly now;
     private driverInstance;
     constructor(options: KtxSnowflakeScanConnectorOptions);
-    testConnection(): Promise<{
-        success: boolean;
-        error?: string;
-    }>;
+    testConnection(): Promise<KtxConnectorTestResult>;
     introspect(input: KtxScanInput, _ctx: KtxScanContext): Promise<KtxSchemaSnapshot>;
     sampleTable(input: KtxTableSampleInput, _ctx: KtxScanContext): Promise<KtxTableSampleResult>;
     sampleColumn(input: KtxColumnSampleInput, _ctx: KtxScanContext): Promise<KtxColumnSampleResult>;

package/dist/connectors/snowflake/connector.js

@@ -6,7 +6,7 @@ import { getDialectForDriver } from '../../context/connections/dialects.js';
 import { assertReadOnlySql, limitSqlForExecution } from '../../context/connections/read-only-sql.js';
 import { tryConstraintQuery } from '../../context/scan/constraint-discovery.js';
 import { scopedTableNames } from '../../context/scan/table-ref.js';
-import { createKtxConnectorCapabilities, } from '../../context/scan/types.js';
+import { connectorTestFailure, createKtxConnectorCapabilities, } from '../../context/scan/types.js';
 import snowflake from 'snowflake-sdk';
 import { assertSafeSnowflakeIdentifier, quoteSnowflakeIdentifier } from './identifiers.js';
 import { configureSnowflakeSdkLogger } from './sdk-logger.js';
@@ -282,7 +282,7 @@ class SnowflakeSdkDriver {
             return { success: true };
         }
         catch (error) {
-            return { success: false, error: error instanceof Error ? error.message : String(error) };
+            return connectorTestFailure(error);
         }
     }
     async getPool() {

package/dist/connectors/sqlite/connector.d.ts

@@ -1,4 +1,4 @@
-import { type KtxColumnSampleInput, type KtxColumnSampleResult, type KtxColumnStatsInput, type KtxColumnStatsResult, type KtxQueryResult, type KtxReadOnlyQueryInput, type KtxScanConnector, type KtxScanContext, type KtxScanInput, type KtxSchemaSnapshot, type KtxTableListEntry, type KtxTableRef, type KtxTableSampleInput, type KtxTableSampleResult } from '../../context/scan/types.js';
+import { type KtxConnectorTestResult, type KtxColumnSampleInput, type KtxColumnSampleResult, type KtxColumnStatsInput, type KtxColumnStatsResult, type KtxQueryResult, type KtxReadOnlyQueryInput, type KtxScanConnector, type KtxScanContext, type KtxScanInput, type KtxSchemaSnapshot, type KtxTableListEntry, type KtxTableRef, type KtxTableSampleInput, type KtxTableSampleResult } from '../../context/scan/types.js';
 export interface KtxSqliteConnectionConfig {
     driver?: string;
     path?: string;
@@ -39,10 +39,7 @@ export declare class KtxSqliteScanConnector implements KtxScanConnector {
     private readonly dialect;
     private db;
     constructor(options: KtxSqliteScanConnectorOptions);
-    testConnection(): Promise<{
-        success: boolean;
-        error?: string;
-    }>;
+    testConnection(): Promise<KtxConnectorTestResult>;
     introspect(input: KtxScanInput, _ctx: KtxScanContext): Promise<KtxSchemaSnapshot>;
     listSchemas(): Promise<string[]>;
     listTables(_schemas?: string[]): Promise<KtxTableListEntry[]>;

package/dist/connectors/sqlite/connector.js

@@ -6,7 +6,7 @@ import { fileURLToPath } from 'node:url';
 import { getDialectForDriver } from '../../context/connections/dialects.js';
 import { assertReadOnlySql, limitSqlForExecution } from '../../context/connections/read-only-sql.js';
 import { normalizeQueryRows } from '../../context/connections/query-executor.js';
-import { createKtxConnectorCapabilities } from '../../context/scan/types.js';
+import { connectorTestFailure, createKtxConnectorCapabilities } from '../../context/scan/types.js';
 import { scopedTableNames } from '../../context/scan/table-ref.js';
 function stringConfigValue(connection, key) {
     const value = connection?.[key];
@@ -106,7 +106,7 @@ export class KtxSqliteScanConnector {
             return { success: true };
         }
         catch (error) {
-            return { success: false, error: error instanceof Error ? error.message : String(error) };
+            return connectorTestFailure(error);
         }
     }
     async introspect(input, _ctx) {