@kaelio/ktx 0.4.1 → 0.6.0

package/dist/admin-reindex.d.ts

@@ -1,4 +1,4 @@
-import { type ReindexSummary } from '@ktx/context/index-sync';
+import type { ReindexSummary } from './context/index-sync/types.js';
 import { type Command } from '@commander-js/extra-typings';
 import type { KtxCliCommandContext } from './cli-program.js';
 import type { KtxCliIo } from './cli-runtime.js';
@@ -10,6 +10,9 @@ export interface KtxAdminReindexArgs {
     cliVersion: string;
 }
 export declare function registerAdminReindexCommand(admin: Command, context: KtxCliCommandContext): void;
+/** @internal */
 export declare function reindexHasErrors(summary: ReindexSummary): boolean;
+/** @internal */
 export declare function renderReindexPlain(summary: ReindexSummary, io: KtxCliIo): void;
+/** @internal */
 export declare function renderReindexJson(summary: ReindexSummary, io: KtxCliIo): void;

package/dist/admin-reindex.js

@@ -1,6 +1,6 @@
-import { KtxIngestEmbeddingPortAdapter } from '@ktx/context';
-import { reindexLocalIndexes } from '@ktx/context/index-sync';
-import { loadKtxProject } from '@ktx/context/project';
+import { KtxIngestEmbeddingPortAdapter } from './context/llm/embedding-port.js';
+import { reindexLocalIndexes } from './context/index-sync/reindex.js';
+import { loadKtxProject } from './context/project/project.js';
 import { Option } from '@commander-js/extra-typings';
 import { cancel, intro, log, note, outro } from '@clack/prompts';
 import { resolveProjectEmbeddingProvider } from './embedding-resolution.js';
@@ -34,9 +34,11 @@ function scopeKey(scope) {
 function quotePlainValue(value) {
     return `"${value.replaceAll('\\', '\\\\').replaceAll('"', '\\"')}"`;
 }
+/** @internal */
 export function reindexHasErrors(summary) {
     return summary.scopes.some((scope) => scope.error);
 }
+/** @internal */
 export function renderReindexPlain(summary, io) {
     const updateKey = summary.force ? 'rebuilt' : 'updated';
     for (const scope of summary.scopes) {
@@ -63,6 +65,7 @@ export function renderReindexPlain(summary, io) {
         ...(failed > 0 ? [`failed=${failed}`] : []),
     ].join('\t') + '\n');
 }
+/** @internal */
 export function renderReindexJson(summary, io) {
     io.stdout.write(`${JSON.stringify({ kind: 'reindex', data: summary, meta: { command: 'admin reindex' } }, null, 2)}\n`);
 }

package/dist/admin.js

@@ -32,7 +32,8 @@ export function registerAdminCommands(program, context) {
         .description('Print a JSON Schema describing ktx.yaml (for editors and LLM agents)')
         .option('--output <file>', 'Write the schema to a file instead of stdout')
         .action(async (options) => {
-        const { generateKtxProjectConfigJsonSchema } = await import('@ktx/context/project');
+        const { generateKtxProjectConfigJsonSchema } = await import('./context/project/config.js');
+        ;
         const json = `${JSON.stringify(generateKtxProjectConfigJsonSchema(), null, 2)}\n`;
         if (options.output) {
             const { writeFile } = await import('node:fs/promises');

package/dist/clack.d.ts

@@ -1,3 +1,11 @@
+import type { KtxCliIo } from './cli-runtime.js';
+export interface RailBufferedSource {
+    stdoutText(): string;
+    stderrText(): string;
+}
+export declare function errorMessage(error: unknown): string;
+export declare function writePrefixedLines(write: (chunk: string) => void, output: string): void;
+export declare function flushPrefixedBufferedCommandOutput(io: KtxCliIo, buffered: RailBufferedSource): void;
 export interface KtxCliSpinner {
     start(message: string): void;
     message(message: string): void;
@@ -24,9 +32,6 @@ export interface KtxCliPromptAdapter {
     };
     spinner(): KtxCliSpinner;
 }
-export declare class KtxCliPromptCancelledError extends Error {
-    constructor(message?: string);
-}
 export declare function createClackSpinner(): KtxCliSpinner;
 export declare function createStaticCliSpinner(io: KtxCliSpinnerIo): KtxCliSpinner;
 export declare function createClackPromptAdapter(): KtxCliPromptAdapter;

package/dist/clack.js

@@ -1,6 +1,20 @@
 import { cancel, confirm, isCancel, log, spinner } from '@clack/prompts';
 const ESC = String.fromCharCode(0x1b);
-export class KtxCliPromptCancelledError extends Error {
+export function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function writePrefixedLines(write, output) {
+    for (const line of output.split(/\r?\n/)) {
+        if (line.length > 0) {
+            write(`│  ${line}\n`);
+        }
+    }
+}
+export function flushPrefixedBufferedCommandOutput(io, buffered) {
+    writePrefixedLines((chunk) => io.stdout.write(chunk), buffered.stdoutText());
+    writePrefixedLines((chunk) => io.stderr.write(chunk), buffered.stderrText());
+}
+class KtxCliPromptCancelledError extends Error {
     constructor(message = 'Operation cancelled.') {
         super(message);
         this.name = 'KtxCliPromptCancelledError';

package/dist/claude-code-prompt-caching.d.ts

@@ -1,4 +1,4 @@
-import type { KtxProjectLlmConfig } from '@ktx/context/project';
+import type { KtxProjectLlmConfig } from './context/project/config.js';
 export declare function ignoredClaudeCodePromptCachingFields(config: KtxProjectLlmConfig): string[];
 export declare function formatClaudeCodePromptCachingWarning(fields: string[]): string | null;
 export declare function formatClaudeCodePromptCachingFix(): string;

package/dist/cli-program.d.ts

@@ -1,4 +1,4 @@
-import { Command } from '@commander-js/extra-typings';
+import { Command, type CommandUnknownOpts } from '@commander-js/extra-typings';
 import type { KtxCliDeps, KtxCliIo, KtxCliPackageInfo } from './cli-runtime.js';
 export interface KtxCliCommandContext {
     io: KtxCliIo;
@@ -32,6 +32,8 @@ export interface BuildKtxProgramOptions {
         force: boolean;
     }, io: KtxCliIo) => Promise<number>;
     setExitCode?: (code: number) => void;
+    argv?: string[];
+    setTelemetryModule?: (telemetry: typeof import('./telemetry/index.js')) => void;
 }
 export interface CommandWithGlobalOptions {
     opts: () => object;
@@ -48,6 +50,8 @@ export declare function parseNonEmptyAssignmentOption(value: string): {
 };
 export declare function resolveCommandProjectDir(command: CommandWithGlobalOptions): string;
 export declare function resolveCommandProjectDirOverride(command: CommandWithGlobalOptions): string | undefined;
+/** @internal */
+export declare function collectCommandFlagsPresent(command: CommandUnknownOpts): Record<string, boolean>;
 export declare function buildKtxProgram(options: BuildKtxProgramOptions): Command;
 export declare function runCommanderKtxCli(argv: string[], io: KtxCliIo, deps: KtxCliDeps, info: KtxCliPackageInfo, options: KtxCommanderProgramOptions): Promise<number>;
 export {};

package/dist/cli-program.js

@@ -235,6 +235,21 @@ function ensureProjectAvailable(io, command) {
 function formatCliError(error) {
     return error instanceof Error ? error.message : String(error);
 }
+function commandOutcomeForParseResult(error, exitCode) {
+    if (error) {
+        return isKtxProjectMissingAbortError(error) ? 'aborted' : 'error';
+    }
+    return exitCode === 0 ? 'ok' : 'error';
+}
+function shouldAttachCommandProjectGroup(path, hasProject) {
+    if (hasProject) {
+        return true;
+    }
+    const rootCommand = path[1];
+    const pathKey = path.join(' ');
+    return ((rootCommand !== undefined && COMMANDS_THAT_CREATE_PROJECT.has(rootCommand)) ||
+        COMMANDS_THAT_CREATE_PROJECT.has(pathKey));
+}
 function firstTopLevelCommandToken(argv) {
     for (let index = 0; index < argv.length; index += 1) {
         const arg = argv[index];
@@ -286,11 +301,42 @@ async function runBareInteractiveCommand(program, io, context) {
     program.outputHelp();
     return 0;
 }
+/** @internal */
+export function collectCommandFlagsPresent(command) {
+    const flags = {};
+    let current = command;
+    while (current) {
+        for (const option of current.options) {
+            const key = option.attributeName();
+            if (current.getOptionValueSource(key) === 'cli') {
+                flags[key] = true;
+            }
+        }
+        current = current.parent;
+    }
+    return flags;
+}
 export function buildKtxProgram(options) {
     const program = createBaseProgram(options.packageInfo, options.io);
-    program.hook('preAction', (_thisCommand, actionCommand) => {
-        writeProjectDir(options.io, actionCommand);
-        ensureProjectAvailable(options.io, actionCommand);
+    program.hook('preAction', async (_thisCommand, actionCommand) => {
+        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);
+        const attachProjectGroup = shouldAttachCommandProjectGroup(path, hasProject);
+        telemetry.beginCommandSpan({
+            commandPath: path,
+            flagsPresent: collectCommandFlagsPresent(commandNode),
+            projectDir: attachProjectGroup ? projectDir : undefined,
+            hasProject,
+            attachProjectGroup,
+            startedAt: performance.now(),
+        });
+        writeProjectDir(options.io, commandNode);
+        ensureProjectAvailable(options.io, commandNode);
     });
     const context = {
         io: options.io,
@@ -321,14 +367,19 @@ export function buildKtxProgram(options) {
 export async function runCommanderKtxCli(argv, io, deps, info, options) {
     profileMark('commander:entry');
     let exitCode = 0;
+    let telemetryModule;
     const program = buildKtxProgram({
         io,
         deps,
         packageInfo: info,
         runInit: options.runInit,
+        argv,
         setExitCode: (code) => {
             exitCode = code;
         },
+        setTelemetryModule: (telemetry) => {
+            telemetryModule = telemetry;
+        },
     });
     profileMark('commander:program-built');
     const context = {
@@ -361,18 +412,33 @@ export async function runCommanderKtxCli(argv, io, deps, info, options) {
         io.stderr.write(`error: unknown command '${topLevelCommand}'\n`);
         return 1;
     }
+    let parseError;
     try {
         await profileSpan('commander:parseAsync', () => program.parseAsync(argv, { from: 'user' }));
     }
     catch (error) {
+        parseError = error;
         if (isKtxProjectMissingAbortError(error)) {
-            return 1;
+            exitCode = 1;
         }
-        if (isCommanderExit(error)) {
-            return error.exitCode === 0 ? 0 : 1;
+        else if (isCommanderExit(error)) {
+            exitCode = error.exitCode === 0 ? 0 : 1;
+        }
+        else {
+            io.stderr.write(`${formatCliError(error)}\n`);
+            exitCode = 1;
+        }
+    }
+    finally {
+        if (telemetryModule) {
+            const completed = telemetryModule.completeCommandSpan({
+                completedAt: performance.now(),
+                outcome: commandOutcomeForParseResult(parseError, exitCode),
+                error: parseError,
+            });
+            await telemetryModule.emitCompletedCommand({ completed, packageInfo: info, io });
+            await telemetryModule.shutdownTelemetryEmitter();
         }
-        io.stderr.write(`${formatCliError(error)}\n`);
-        return 1;
     }
     return exitCode;
 }

package/dist/cli-runtime.d.ts

@@ -11,7 +11,6 @@ import type { KtxTextIngestArgs } from './text-ingest.js';
 export interface KtxCliPackageInfo {
     name: string;
     version: string;
-    contextPackageName: '@ktx/context';
 }
 export interface KtxCliIo {
     stdout: {

package/dist/cli-runtime.js

@@ -18,11 +18,11 @@ export function packageInfoFromJson(packageJson) {
     return {
         name: packageJson.name,
         version: assertCliVersion(packageJson.version, `${packageJson.name}/package.json`),
-        contextPackageName: '@ktx/context',
     };
 }
 async function runInit(args, io) {
-    const { initKtxProject } = await import('@ktx/context/project');
+    const { initKtxProject } = await import('./context/project/project.js');
+    ;
     const result = await initKtxProject({
         projectDir: args.projectDir,
         force: args.force,

package/dist/command-schemas.d.ts

@@ -20,15 +20,15 @@ export declare const slQueryCommandSchema: z.ZodObject<{
     }, z.core.$strip>>;
     queryFile: z.ZodOptional<z.ZodString>;
     format: z.ZodEnum<{
-        json: "json";
         sql: "sql";
+        json: "json";
     }>;
     execute: z.ZodBoolean;
     cliVersion: z.ZodString;
     runtimeInstallPolicy: z.ZodEnum<{
         never: "never";
-        prompt: "prompt";
         auto: "auto";
+        prompt: "prompt";
     }>;
     maxRows: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;

package/dist/commands/status-commands.js

@@ -1,5 +1,6 @@
 import { resolveCommandProjectDir, resolveCommandProjectDirOverride } from '../cli-program.js';
 import { findNearestKtxProjectDir } from '../project-resolver.js';
+import { emitProjectStackSnapshot } from '../telemetry/index.js';
 function outputMode(options) {
     return options.json === true ? 'json' : 'plain';
 }
@@ -13,6 +14,7 @@ export function registerStatusCommands(program, context) {
         .option('--json', 'Print JSON output', false)
         .option('-v, --verbose', 'Show every check, including passing ones', false)
         .option('--validate', 'Only validate the ktx.yaml schema; skip readiness checks', false)
+        .option('--fast', 'Skip checks that require external communication (DB probes, auth probes)', false)
         .option('--no-input', 'Disable interactive terminal input')
         .action(async (options, command) => {
         const runner = context.deps.doctor ?? (await import('../doctor.js')).runKtxDoctor;
@@ -36,12 +38,19 @@ export function registerStatusCommands(program, context) {
             }, context.io));
             return;
         }
+        const projectDir = resolveCommandProjectDir(command);
         context.setExitCode(await runner({
             command: 'project',
-            projectDir: resolveCommandProjectDir(command),
+            projectDir,
             outputMode: outputMode(options),
             verbose: options.verbose === true,
+            fast: options.fast === true,
             ...inputMode(options),
         }, context.io));
+        await emitProjectStackSnapshot({
+            projectDir,
+            io: context.io,
+            packageInfo: context.packageInfo,
+        });
     });
 }

package/dist/connection.d.ts

@@ -1,5 +1,8 @@
-import { type LookerClient, type MetabaseRuntimeClient, NotionClient, testRepoConnection } from '@ktx/context/ingest';
-import { type KtxLocalProject } from '@ktx/context/project';
+import type { LookerClient } from './context/ingest/adapters/looker/client.js';
+import type { MetabaseRuntimeClient } from './context/ingest/adapters/metabase/client-port.js';
+import { NotionClient } from './context/ingest/adapters/notion/notion-client.js';
+import { testRepoConnection } from './context/ingest/repo-fetch.js';
+import { type KtxLocalProject } from './context/project/project.js';
 import type { KtxCliIo } from './index.js';
 import { createKtxCliScanConnector } from './local-scan-connectors.js';
 export type KtxConnectionArgs = {

package/dist/connection.js

@@ -1,10 +1,19 @@
-import { DEFAULT_METABASE_CLIENT_CONFIG, DefaultLookerConnectionClientFactory, DefaultMetabaseConnectionClientFactory, NotionClient, createLocalLookerCredentialResolver, metabaseRuntimeConfigFromLocalConnection, testRepoConnection, } from '@ktx/context/ingest';
-import { parseNotionConnectionConfig, resolveNotionConnectionAuthToken } from '@ktx/context/connections';
-import { resolveKtxConfigReference } from '@ktx/context/core';
-import { loadKtxProject } from '@ktx/context/project';
+import { DEFAULT_METABASE_CLIENT_CONFIG, DefaultMetabaseConnectionClientFactory } from './context/ingest/adapters/metabase/client.js';
+import { DefaultLookerConnectionClientFactory } from './context/ingest/adapters/looker/factory.js';
+import { NotionClient } from './context/ingest/adapters/notion/notion-client.js';
+import { createLocalLookerCredentialResolver } from './context/ingest/adapters/looker/local-looker.adapter.js';
+import { metabaseRuntimeConfigFromLocalConnection } from './context/ingest/adapters/metabase/local-metabase.adapter.js';
+import { testRepoConnection } from './context/ingest/repo-fetch.js';
+import { getDriverRegistration } from './context/connections/drivers.js';
+import { parseNotionConnectionConfig, resolveNotionConnectionAuthToken } from './context/connections/notion-config.js';
+import { resolveKtxConfigReference } from './context/core/config-reference.js';
+import { loadKtxProject } from './context/project/project.js';
 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';
 profileMark('module:connection');
 const SUPPORTED_TEST_DRIVERS = [
     'sqlite',
@@ -151,20 +160,27 @@ async function testConnectionByDriver(project, connectionId, deps) {
         const result = await testGitRepoConnection(project, connectionId, driver, deps.testRepoConnection ?? testRepoConnection);
         return { driver, detailKey: 'Repo', detailValue: result.repoUrl };
     }
-    if (driver === 'sqlite' ||
-        driver === 'sqlite3' ||
-        driver === 'postgres' ||
-        driver === 'postgresql' ||
-        driver === 'mysql' ||
-        driver === 'clickhouse' ||
-        driver === 'sqlserver' ||
-        driver === 'bigquery' ||
-        driver === 'snowflake') {
+    if (getDriverRegistration(driver)) {
         const result = await testNativeConnection(project, connectionId, deps.createScanConnector ?? createKtxCliScanConnector);
         return { driver: result.driver, detailKey: 'Status', detailValue: 'ok' };
     }
     throw new Error(`Connection "${connectionId}" uses driver "${driver}", which has no test implementation in ktx. Supported: ${SUPPORTED_TEST_DRIVERS.join(', ')}.`);
 }
+async function emitConnectionTest(input) {
+    const errorClass = input.error ? scrubErrorClass(input.error) : undefined;
+    await emitTelemetryEvent({
+        name: 'connection_test',
+        projectDir: input.project.projectDir,
+        io: input.io,
+        fields: {
+            driver: input.driver,
+            isDemoConnection: isDemoConnection(input.connectionId, input.project.config.connections[input.connectionId]),
+            outcome: input.outcome,
+            durationMs: input.durationMs,
+            ...(errorClass ? { errorClass } : {}),
+        },
+    });
+}
 function visualWidth(text) {
     // styleText wraps content in ANSI escape sequences; strip them before measuring.
     return text.replace(/\[[0-9;]*m/g, '').length;
@@ -204,8 +220,17 @@ async function runTestAll(project, io, deps) {
     const entries = Object.entries(project.config.connections).sort(([a], [b]) => a.localeCompare(b));
     const rows = await Promise.all(entries.map(async ([connectionId, connection]) => {
         const declaredDriver = String(connection.driver ?? '').trim().toLowerCase() || 'unknown';
+        const startedAt = performance.now();
         try {
             const outcome = await testConnectionByDriver(project, connectionId, deps);
+            await emitConnectionTest({
+                project,
+                connectionId,
+                driver: outcome.driver || declaredDriver,
+                outcome: 'ok',
+                durationMs: Math.max(0, performance.now() - startedAt),
+                io,
+            });
             return {
                 connectionId,
                 driver: outcome.driver || declaredDriver,
@@ -214,6 +239,15 @@ async function runTestAll(project, io, deps) {
             };
         }
         catch (error) {
+            await emitConnectionTest({
+                project,
+                connectionId,
+                driver: declaredDriver,
+                outcome: 'error',
+                durationMs: Math.max(0, performance.now() - startedAt),
+                error,
+                io,
+            });
             return {
                 connectionId,
                 driver: declaredDriver,
@@ -245,7 +279,36 @@ export async function runKtxConnection(args, io = process, deps = {}) {
         if (args.command === 'test-all') {
             return await runTestAll(project, io, deps);
         }
-        const { driver, detailKey, detailValue } = await testConnectionByDriver(project, args.connectionId, deps);
+        const startedAt = performance.now();
+        let driver = normalizedConnectionDriver(project, args.connectionId) || 'unknown';
+        let detailKey;
+        let detailValue;
+        try {
+            const outcome = await testConnectionByDriver(project, args.connectionId, deps);
+            driver = outcome.driver;
+            detailKey = outcome.detailKey;
+            detailValue = outcome.detailValue;
+            await emitConnectionTest({
+                project,
+                connectionId: args.connectionId,
+                driver,
+                outcome: 'ok',
+                durationMs: Math.max(0, performance.now() - startedAt),
+                io,
+            });
+        }
+        catch (error) {
+            await emitConnectionTest({
+                project,
+                connectionId: args.connectionId,
+                driver,
+                outcome: 'error',
+                durationMs: Math.max(0, performance.now() - startedAt),
+                error,
+                io,
+            });
+            throw error;
+        }
         io.stdout.write(`Connection test passed: ${args.connectionId}\n`);
         io.stdout.write(`Driver: ${driver}\n`);
         io.stdout.write(`${detailKey}: ${detailValue}\n`);

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

@@ -0,0 +1,151 @@
+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';
+export interface KtxBigQueryConnectionConfig {
+    driver?: string;
+    dataset_id?: string;
+    dataset_ids?: string[];
+    credentials_json?: string;
+    location?: string;
+    max_bytes_billed?: number | string;
+    job_timeout_ms?: number;
+    [key: string]: unknown;
+}
+export interface KtxBigQueryResolvedConnectionConfig {
+    projectId: string;
+    credentials: Record<string, unknown>;
+    datasetIds: string[];
+    location?: string;
+}
+export interface KtxBigQueryReadOnlyQueryInput extends KtxReadOnlyQueryInput {
+    params?: Record<string, unknown>;
+}
+export interface KtxBigQueryColumnDistinctValuesOptions {
+    maxCardinality: number;
+    limit: number;
+    sampleSize?: number;
+}
+export interface KtxBigQueryColumnDistinctValuesResult {
+    values: string[] | null;
+    cardinality: number;
+}
+/** @internal */
+export interface KtxBigQueryQueryJob {
+    getQueryResults(): Promise<[
+        Array<Record<string, unknown>>,
+        unknown,
+        {
+            schema?: {
+                fields?: TableField[];
+            };
+        }?,
+        ...unknown[]
+    ]>;
+}
+/** @internal */
+export interface KtxBigQueryTableRef {
+    id?: string;
+    metadata?: {
+        type?: string;
+    };
+    get(): Promise<[
+        {
+            metadata: {
+                type?: string;
+                numRows?: string | number;
+                description?: string;
+                schema?: {
+                    fields?: TableField[];
+                };
+            };
+        },
+        ...unknown[]
+    ]>;
+}
+/** @internal */
+export interface KtxBigQueryDataset {
+    get(): Promise<unknown>;
+    getTables(): Promise<[KtxBigQueryTableRef[], ...unknown[]]>;
+}
+export interface KtxBigQueryClient {
+    getDatasets(input?: {
+        maxResults?: number;
+    }): Promise<[Array<{
+        id?: string;
+    }>, ...unknown[]]>;
+    dataset(datasetId: string): KtxBigQueryDataset;
+    createQueryJob(input: {
+        query: string;
+        location?: string;
+        params?: Record<string, unknown>;
+        maximumBytesBilled?: string;
+        jobTimeoutMs?: number;
+    }): Promise<[KtxBigQueryQueryJob, ...unknown[]]>;
+}
+export interface KtxBigQueryClientFactory {
+    createClient(input: {
+        projectId: string;
+        credentials: Record<string, unknown>;
+    }): KtxBigQueryClient;
+}
+export interface KtxBigQueryScanConnectorOptions {
+    connectionId: string;
+    connection: KtxBigQueryConnectionConfig | undefined;
+    clientFactory?: KtxBigQueryClientFactory;
+    env?: NodeJS.ProcessEnv;
+    now?: () => Date;
+    maxBytesBilled?: number | string;
+    queryTimeoutMs?: number;
+}
+/** @internal */
+export declare function prepareBigQueryReadOnlyQuery(sql: string, params?: Record<string, unknown>): {
+    sql: string;
+    params?: Record<string, unknown>;
+};
+export declare function isKtxBigQueryConnectionConfig(connection: KtxBigQueryConnectionConfig | undefined): connection is KtxBigQueryConnectionConfig;
+/** @internal */
+export declare function bigQueryConnectionConfigFromConfig(input: {
+    connectionId: string;
+    connection: KtxBigQueryConnectionConfig | undefined;
+    env?: NodeJS.ProcessEnv;
+}): KtxBigQueryResolvedConnectionConfig;
+export declare class KtxBigQueryScanConnector implements KtxScanConnector {
+    readonly id: string;
+    readonly driver: "bigquery";
+    readonly capabilities: import("../../context/scan/types.js").KtxConnectorCapabilities;
+    private readonly connectionId;
+    private readonly resolved;
+    private readonly clientFactory;
+    private readonly now;
+    private readonly maxBytesBilled?;
+    private readonly queryTimeoutMs?;
+    private readonly dialect;
+    private client;
+    constructor(options: KtxBigQueryScanConnectorOptions);
+    testConnection(): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    introspect(input: KtxScanInput, _ctx: KtxScanContext): Promise<KtxSchemaSnapshot>;
+    sampleTable(input: KtxTableSampleInput, _ctx: KtxScanContext): Promise<KtxTableSampleResult & {
+        headerTypes?: string[];
+    }>;
+    sampleColumn(input: KtxColumnSampleInput, _ctx: KtxScanContext): Promise<KtxColumnSampleResult>;
+    columnStats(_input: KtxColumnStatsInput, _ctx: KtxScanContext): Promise<KtxColumnStatsResult | null>;
+    executeReadOnly(input: KtxBigQueryReadOnlyQueryInput, _ctx: KtxScanContext): Promise<KtxQueryResult>;
+    getColumnDistinctValues(table: KtxTableRef, columnName: string, options: KtxBigQueryColumnDistinctValuesOptions): Promise<KtxBigQueryColumnDistinctValuesResult | null>;
+    getTableRowCount(tableName: string, datasetId?: string): Promise<number>;
+    qTableName(table: Pick<KtxTableRef, 'name'> & Partial<Pick<KtxTableRef, 'catalog' | 'db'>>): string;
+    quoteIdentifier(identifier: string): string;
+    listSchemas(): Promise<string[]>;
+    listTables(datasetIds?: string[]): Promise<KtxTableListEntry[]>;
+    cleanup(): Promise<void>;
+    private getClient;
+    private requireDatasetIdsForScan;
+    private query;
+    private queryRaw;
+    private singleNumber;
+    private introspectDataset;
+    private primaryKeys;
+    private toSchemaColumn;
+    private assertConnection;
+}