@kaelio/ktx 0.8.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

@@ -35,11 +35,102 @@ async function runInit(args, io) {
 export async function runInitForCommander(args, io) {
     return await runInit(args, io);
 }
+function signalExitCode(signal) {
+    // 128 + signal number: SIGINT (2) -> 130, SIGTERM (15) -> 143.
+    return signal === 'SIGTERM' ? 143 : 130;
+}
+/**
+ * Flush telemetry on interrupt for the real CLI process. `capture()` is
+ * fire-and-forget and the only flush guarantee lives in a `finally` a signal
+ * skips, so Ctrl-C / `kill` of a long-running command (ingest, `mcp stdio`)
+ * would otherwise drop its `command` event and queued events. Installed only
+ * when driving the actual process; programmatic/test callers pass their own
+ * `io` and never reach here. Returns a disposer that removes the listeners.
+ */
+function installTelemetrySignalFlush(io, info) {
+    let handling = false;
+    const handle = (signal) => {
+        if (handling) {
+            process.exit(signalExitCode(signal));
+        }
+        handling = true;
+        void (async () => {
+            try {
+                const { emitAbortedCommandAndShutdown } = await import('./telemetry/index.js');
+                await emitAbortedCommandAndShutdown({ packageInfo: info, io });
+            }
+            catch {
+                // Best-effort: never let a telemetry hiccup block the interrupt exit.
+            }
+            process.exit(signalExitCode(signal));
+        })();
+    };
+    const onSigint = () => handle('SIGINT');
+    const onSigterm = () => handle('SIGTERM');
+    process.on('SIGINT', onSigint);
+    process.on('SIGTERM', onSigterm);
+    return () => {
+        process.off('SIGINT', onSigint);
+        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');
     const { runCommanderKtxCli } = await profileSpan('import ./cli-program.js', () => import('./cli-program.js'));
-    return await runCommanderKtxCli(argv, io, deps, info, {
-        runInit: runInitForCommander,
-    });
+    // 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

@@ -18,7 +18,7 @@ function embeddingBackend(value) {
     throw new InvalidArgumentError(`invalid choice '${value}'`);
 }
 function llmBackend(value) {
-    if (value === 'anthropic' || value === 'vertex' || value === 'claude-code') {
+    if (value === 'anthropic' || value === 'vertex' || value === 'claude-code' || value === 'codex') {
         return value;
     }
     throw new InvalidArgumentError(`invalid choice '${value}'`);
@@ -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-recovery.d.ts

@@ -0,0 +1,34 @@
+import type { KtxCliIo } from './cli-runtime.js';
+import type { KtxSetupPromptOption } from './setup-prompts.js';
+export type RecoveryOutcome = 'ready' | 'skip' | 'back' | 'failed';
+/** @internal */
+export interface RecoveryAction {
+    value: string;
+    label: string;
+    run: () => Promise<void>;
+}
+export type ConfigureResult = 'configured' | 'back' | 'cancelled';
+export type ValidateResult = {
+    status: 'ok';
+} | {
+    status: 'back';
+} | {
+    status: 'failed';
+    extraActions?: RecoveryAction[];
+};
+export interface ConnectionRecoveryInput {
+    label: string;
+    interactive: boolean;
+    allowSkip: boolean;
+    io: KtxCliIo;
+    prompts: {
+        select(options: {
+            message: string;
+            options: KtxSetupPromptOption[];
+        }): Promise<string>;
+    };
+    snapshot: () => Promise<() => Promise<void>>;
+    configure: () => Promise<ConfigureResult>;
+    validate: () => Promise<ValidateResult>;
+}
+export declare function runConnectionSetupWithRecovery(input: ConnectionRecoveryInput): Promise<RecoveryOutcome>;

package/dist/connection-recovery.js

@@ -0,0 +1,82 @@
+async function runRollbackOnce(input) {
+    if (input.state.rolledBack) {
+        return;
+    }
+    input.state.rolledBack = true;
+    await input.rollback();
+}
+function recoveryOptions(input) {
+    return [
+        { value: 'retry', label: 'Retry connection test' },
+        { value: 're-enter', label: 'Re-enter connection details' },
+        ...(input.extraActions ?? []).map((action) => ({
+            value: action.value,
+            label: action.label,
+        })),
+        ...(input.allowSkip ? [{ value: 'skip', label: 'Skip this connection' }] : []),
+        { value: 'back', label: 'Back' },
+    ];
+}
+export async function runConnectionSetupWithRecovery(input) {
+    const rollback = await input.snapshot();
+    const rollbackState = { rolledBack: false };
+    const firstConfig = await input.configure();
+    if (firstConfig === 'back') {
+        await runRollbackOnce({ rollback, state: rollbackState });
+        return 'back';
+    }
+    if (firstConfig === 'cancelled') {
+        await runRollbackOnce({ rollback, state: rollbackState });
+        return 'failed';
+    }
+    let validation = await input.validate();
+    while (validation.status !== 'ok') {
+        if (validation.status === 'back') {
+            await runRollbackOnce({ rollback, state: rollbackState });
+            return 'back';
+        }
+        if (!input.interactive) {
+            return 'failed';
+        }
+        const action = await input.prompts.select({
+            message: `Connection setup failed for ${input.label}`,
+            options: recoveryOptions({
+                allowSkip: input.allowSkip,
+                extraActions: validation.extraActions,
+            }),
+        });
+        if (action === 'back') {
+            await runRollbackOnce({ rollback, state: rollbackState });
+            return 'back';
+        }
+        if (action === 'skip' && input.allowSkip) {
+            await runRollbackOnce({ rollback, state: rollbackState });
+            return 'skip';
+        }
+        if (action === 're-enter') {
+            const nextConfig = await input.configure();
+            if (nextConfig === 'back') {
+                await runRollbackOnce({ rollback, state: rollbackState });
+                return 'back';
+            }
+            if (nextConfig === 'cancelled') {
+                await runRollbackOnce({ rollback, state: rollbackState });
+                return 'failed';
+            }
+            validation = await input.validate();
+            continue;
+        }
+        if (action === 'retry') {
+            validation = await input.validate();
+            continue;
+        }
+        const extraAction = validation.extraActions?.find((candidate) => candidate.value === action);
+        if (extraAction) {
+            await extraAction.run();
+            validation = await input.validate();
+            continue;
+        }
+        validation = await input.validate();
+    }
+    return 'ready';
+}

package/dist/connection.js

@@ -12,8 +12,9 @@ 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 { scrubErrorClass } from './telemetry/scrubber.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 = [
     'sqlite',
@@ -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 };
@@ -168,6 +175,7 @@ async function testConnectionByDriver(project, connectionId, deps) {
 }
 async function emitConnectionTest(input) {
     const errorClass = input.error ? scrubErrorClass(input.error) : undefined;
+    const errorDetail = input.error ? formatErrorDetail(input.error) : undefined;
     await emitTelemetryEvent({
         name: 'connection_test',
         projectDir: input.project.projectDir,
@@ -178,8 +186,24 @@ async function emitConnectionTest(input) {
             outcome: input.outcome,
             durationMs: input.durationMs,
             ...(errorClass ? { errorClass } : {}),
+            ...(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>;