test: split cli tests from source tree (#216)

* feat(cli): define full warehouse dialect contract

* test(cli): keep dialect edge tests focused

* fix(cli): stabilize dialect contract foundation

* refactor(connectors): own read-only query preparation

* refactor(connectors): resolve dialects through registry

* refactor(connectors): keep concrete dialect classes internal

* chore(workspace): enforce dialect import boundary

* refactor(cli): resolve relationship dialect at scan boundary

* refactor(cli): use dialect display parsing for entity details

* refactor(cli): use dialect display parsing for warehouse catalog

* refactor(cli): use dialect SQL in relationship workflows

* test(cli): verify solid dialect scan workflow closure

* test: split cli tests from source tree

* refactor(cli): standardize BigQuery scope listing

* feat(sqlite): implement connector scope listing

* test(connectors): cover required table listing

* feat(cli): add warehouse driver registry

* refactor(setup): route scope discovery through driver registry

* refactor(cli): route local query execution through driver registry

* refactor(historic-sql): route dialect support through driver registry

* refactor(cli): test warehouse connections through driver registry

* fix(cli): close driver registry type export gaps

* Improve setup daemon diagnostics

* refactor(setup): centralize rail-prefixed diagnostics + query-history fallback

Extract errorMessage, writePrefixedLines, and flushPrefixedBufferedCommandOutput
into clack.ts so the setup wizard, managed daemons, and embedding/agent steps
share one rail-formatted writer. setup-databases.ts also adds a
"disable query history and retry" option when the schema-context build fails
and query history is the likely culprit, surfaced via a new
failed-query-history-unavailable status.

* fix(cli): carry catalog through the picker so BigQuery/Snowflake/SQL Server scope filters match

The setup picker's KtxTableListEntry was a 2-level { schema, name }, so
qualifiedTableId always wrote db.name into enabled_tables. When BigQuery,
Snowflake, or SQL Server later ran fast ingest, their introspect step filtered
the scope set with scopedTableNames(scope, { catalog: projectId|database, db })
— catalog was non-null on the introspect side but null in the scope refs, so
every entry was rejected, the live-database adapter staged zero table files,
and detect() failed with 'Adapter "live-database" did not recognize fetched
source output'.

Align the picker boundary with the canonical 3-level KtxTableRef:

- Add catalog: string | null to KtxTableListEntry.
- BigQuery/Snowflake/SQL Server listTables populate catalog from the
  resolved projectId / database; Postgres/MySQL/ClickHouse/SQLite set null.
- qualifiedTableId emits catalog.schema.name when catalog is non-null
  (resolveEnabledTables already accepts the 3-part shape) and
  schemasFromEnabledTables now goes through parseDottedTableEntry so it
  recovers the schema correctly from both 2-part and 3-part entries.
- Export parseDottedTableEntry from enabled-tables.ts (@internal) for picker
  reuse.

Update listTables expectations in all seven connector tests and the setup /
picker test fixtures. Add a picker regression test that covers the
catalog-bearing round-trip (save + refine).

* fix(cli): allow debug telemetry under opt-out env

packages/cli/src/context/connections/bigquery-identifiers.test.ts

@@ -1,19 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { normalizeBigQueryProjectId, normalizeBigQueryRegion } from './bigquery-identifiers.js';
-
-describe('BigQuery identifier normalization', () => {
-  it('normalizes project ids and regions for information schema paths', () => {
-    expect(normalizeBigQueryProjectId('project-1')).toBe('project-1');
-    expect(normalizeBigQueryRegion('US')).toBe('us');
-    expect(normalizeBigQueryRegion('region-eu')).toBe('eu');
-  });
-
-  it('rejects malformed project ids and regions with caller-specific context', () => {
-    expect(() => normalizeBigQueryProjectId('project`1', 'table discovery')).toThrow(
-      'Invalid BigQuery project id for table discovery: project`1',
-    );
-    expect(() => normalizeBigQueryRegion('US;DROP', 'table discovery')).toThrow(
-      'Invalid BigQuery region for table discovery: US;DROP',
-    );
-  });
-});

packages/cli/src/context/connections/dialect-helpers.ts

@@ -0,0 +1,87 @@
+import type { KtxTableRef } from '../scan/types.js';
+
+export type KtxDialectIdentifierShape = 'ansi' | 'sqlite' | 'three-part';
+
+export type KtxDialectTableRef = Pick<KtxTableRef, 'name'> & Partial<Pick<KtxTableRef, 'catalog' | 'db'>>;
+
+export function safeSqlLimit(limit: number): number {
+  return Math.max(1, Math.floor(limit));
+}
+
+function safeSqlOffset(offset: number | undefined): number | null {
+  if (offset === undefined) {
+    return null;
+  }
+  const normalized = Math.floor(offset);
+  return normalized > 0 ? normalized : null;
+}
+
+function cleanIdentifierPart(part: string): string {
+  return part.trim().replace(/^["'`\[]|["'`\]]$/g, '');
+}
+
+function splitDisplay(display: string): string[] {
+  return display.trim().split('.').map(cleanIdentifierPart).filter(Boolean);
+}
+
+function tableParts(table: KtxDialectTableRef, shape: KtxDialectIdentifierShape): string[] {
+  if (shape === 'sqlite') {
+    return [table.name];
+  }
+  return [table.catalog ?? null, table.db ?? null, table.name].filter((part): part is string => Boolean(part));
+}
+
+function acceptedDisplayPartCounts(shape: KtxDialectIdentifierShape): readonly number[] {
+  if (shape === 'sqlite') {
+    return [1];
+  }
+  if (shape === 'three-part') {
+    return [3];
+  }
+  return [2, 3];
+}
+
+export function formatDialectTableName(
+  table: KtxDialectTableRef,
+  quoteIdentifier: (identifier: string) => string,
+  shape: KtxDialectIdentifierShape,
+): string {
+  return tableParts(table, shape).map(quoteIdentifier).join('.');
+}
+
+export function formatDialectDisplayRef(table: KtxDialectTableRef, shape: KtxDialectIdentifierShape): string {
+  return tableParts(table, shape).join('.');
+}
+
+export function parseDialectDisplayRef(display: string, shape: KtxDialectIdentifierShape): KtxTableRef | null {
+  const parts = splitDisplay(display);
+  if (!acceptedDisplayPartCounts(shape).includes(parts.length)) {
+    return null;
+  }
+  if (parts.length === 1) {
+    return { catalog: null, db: null, name: parts[0]! };
+  }
+  if (parts.length === 2) {
+    return { catalog: null, db: parts[0]!, name: parts[1]! };
+  }
+  if (parts.length === 3) {
+    return { catalog: parts[0]!, db: parts[1]!, name: parts[2]! };
+  }
+  return null;
+}
+
+export function columnDisplayPartCount(shape: KtxDialectIdentifierShape): 1 | 2 | 3 {
+  if (shape === 'sqlite') {
+    return 1;
+  }
+  if (shape === 'three-part') {
+    return 3;
+  }
+  return 2;
+}
+
+export function limitOffsetClause(limit: number, offset?: number): string {
+  const safeLimit = safeSqlLimit(limit);
+  const safeOffset = safeSqlOffset(offset);
+  return safeOffset === null ? `LIMIT ${safeLimit}` : `LIMIT ${safeLimit} OFFSET ${safeOffset}`;
+}

packages/cli/src/context/connections/dialects.test.ts

@@ -1,34 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { getDialectForDriver } from './dialects.js';
-
-describe('getDialectForDriver', () => {
-  it.each([
-    ['postgres', '"public"."orders"'],
-    ['mysql', '`public`.`orders`'],
-    ['clickhouse', '`public`.`orders`'],
-    ['sqlite', '"orders"'],
-    ['snowflake', '"analytics"."public"."orders"'],
-    ['bigquery', '`analytics`.`public`.`orders`'],
-    ['sqlserver', '[analytics].[public].[orders]'],
-  ] as const)('formats table names for %s', (driver, expected) => {
-    const dialect = getDialectForDriver(driver);
-    expect(
-      dialect.formatTableName({
-        catalog: driver === 'snowflake' || driver === 'bigquery' || driver === 'sqlserver' ? 'analytics' : null,
-        db: driver === 'sqlite' ? null : 'public',
-        name: 'orders',
-      }),
-    ).toBe(expected);
-  });
-
-  it('throws with a supported-driver list for unknown drivers', () => {
-    expect(() => getDialectForDriver('oracle')).toThrow(
-      'Unsupported warehouse driver "oracle". Supported drivers: bigquery, clickhouse, mysql, postgres, sqlite, snowflake, sqlserver',
-    );
-  });
-
-  it('rejects legacy driver aliases', () => {
-    expect(() => getDialectForDriver('postgresql')).toThrow('Unsupported warehouse driver "postgresql"');
-    expect(() => getDialectForDriver('sqlite3')).toThrow('Unsupported warehouse driver "sqlite3"');
-  });
-});

packages/cli/src/context/connections/dialects.ts

@@ -1,22 +1,40 @@
-import type { KtxSchemaDimensionType, KtxTableRef } from '../scan/types.js';
-
-type SupportedDriver =
-  | 'postgres'
-  | 'mysql'
-  | 'sqlserver'
-  | 'snowflake'
-  | 'bigquery'
-  | 'clickhouse'
-  | 'sqlite';
+import { KtxBigQueryDialect } from '../../connectors/bigquery/dialect.js';
+import { KtxClickHouseDialect } from '../../connectors/clickhouse/dialect.js';
+import { KtxMysqlDialect } from '../../connectors/mysql/dialect.js';
+import { KtxPostgresDialect } from '../../connectors/postgres/dialect.js';
+import { KtxSqliteDialect } from '../../connectors/sqlite/dialect.js';
+import { KtxSnowflakeDialect } from '../../connectors/snowflake/dialect.js';
+import { KtxSqlServerDialect } from '../../connectors/sqlserver/dialect.js';
+import type { KtxConnectionDriver, KtxSchemaDimensionType, KtxTableRef } from '../scan/types.js';
+import type { KtxDialectTableRef } from './dialect-helpers.js';
 
 export interface KtxDialect {
-  readonly type: SupportedDriver;
+  readonly type: KtxConnectionDriver;
   quoteIdentifier(identifier: string): string;
-  formatTableName(table: KtxTableRef): string;
+  formatTableName(table: KtxDialectTableRef): string;
+  formatDisplayRef(table: KtxDialectTableRef): string;
+  parseDisplayRef(display: string): KtxTableRef | null;
+  columnDisplayTablePartCount(): 1 | 2 | 3;
+  getLimitOffsetClause(limit: number, offset?: number): string;
+  getTopClause(limit: number): string;
+  getRandomSampleFilter(samplePct: number): string;
+  getTableSampleClause(samplePct: number): string;
+  generateSampleQuery(tableName: string, limit: number, columns?: string[]): string;
+  generateColumnSampleQuery(tableName: string, columnName: string, limit: number): string;
+  getSampleValueAggregation(innerSql: string): string;
+  generateCardinalitySampleQuery(tableName: string, columnName: string, sampleSize: number): string;
+  generateRandomizedCardinalitySampleQuery(tableName: string, columnName: string, sampleSize: number): string;
+  generateDistinctValuesQuery(tableName: string, columnName: string, limit: number): string;
+  generateColumnStatisticsQuery(schemaName: string, tableName: string): string | null;
+  getNullCountExpression(column: string): string;
+  getDistinctCountExpression(column: string): string;
+  textLengthExpression(columnSql: string): string;
+  castToText(columnSql: string): string;
   mapToDimensionType(nativeType: string): KtxSchemaDimensionType;
+  mapDataType(nativeType: string): string;
 }
 
-const supportedDrivers: SupportedDriver[] = [
+const supportedDrivers: KtxConnectionDriver[] = [
   'bigquery',
   'clickhouse',
   'mysql',
@@ -26,71 +44,21 @@ const supportedDrivers: SupportedDriver[] = [
   'sqlserver',
 ];
 
-function doubleQuoted(identifier: string): string {
-  return `"${identifier.replace(/"/g, '""')}"`;
-}
-
-function backtickQuoted(identifier: string): string {
-  return `\`${identifier.replace(/`/g, '``')}\``;
-}
-
-function bigQueryQuoted(identifier: string): string {
-  return `\`${identifier.replace(/`/g, '\\`')}\``;
-}
-
-function bracketQuoted(identifier: string): string {
-  return `[${identifier.replace(/\]/g, ']]')}]`;
-}
-
-function inferDimensionType(nativeType: string): KtxSchemaDimensionType {
-  const normalized = nativeType.toLowerCase().trim();
-  if (normalized.includes('date') || normalized.includes('time')) {
-    return 'time';
-  }
-  if (
-    normalized.includes('int') ||
-    normalized.includes('num') ||
-    normalized.includes('dec') ||
-    normalized.includes('float') ||
-    normalized.includes('double') ||
-    normalized.includes('real')
-  ) {
-    return 'number';
-  }
-  if (normalized.includes('bool') || normalized === 'bit') {
-    return 'boolean';
-  }
-  return 'string';
-}
-
-function formatWithParts(table: KtxTableRef, quote: (identifier: string) => string, sqlite = false): string {
-  const parts = sqlite ? [table.name] : [table.catalog, table.db, table.name].filter((part): part is string => !!part);
-  return parts.map(quote).join('.');
-}
-
-function createDialect(type: SupportedDriver, quote: (identifier: string) => string, sqlite = false): KtxDialect {
-  return {
-    type,
-    quoteIdentifier: quote,
-    formatTableName: (table) => formatWithParts(table, quote, sqlite),
-    mapToDimensionType: inferDimensionType,
-  };
-}
-
-const dialects: Record<SupportedDriver, KtxDialect> = {
-  postgres: createDialect('postgres', doubleQuoted),
-  mysql: createDialect('mysql', backtickQuoted),
-  clickhouse: createDialect('clickhouse', backtickQuoted),
-  sqlite: createDialect('sqlite', doubleQuoted, true),
-  snowflake: createDialect('snowflake', doubleQuoted),
-  bigquery: createDialect('bigquery', bigQueryQuoted),
-  sqlserver: createDialect('sqlserver', bracketQuoted),
+const dialectFactories: Record<KtxConnectionDriver, () => KtxDialect> = {
+  bigquery: () => new KtxBigQueryDialect(),
+  clickhouse: () => new KtxClickHouseDialect(),
+  mysql: () => new KtxMysqlDialect(),
+  postgres: () => new KtxPostgresDialect(),
+  sqlite: () => new KtxSqliteDialect(),
+  snowflake: () => new KtxSnowflakeDialect(),
+  sqlserver: () => new KtxSqlServerDialect(),
 };
 
 export function getDialectForDriver(driver: string): KtxDialect {
   const normalized = driver.toLowerCase().trim();
-  if (normalized in dialects) {
-    return dialects[normalized as SupportedDriver];
+  const factory = dialectFactories[normalized as KtxConnectionDriver];
+  if (factory) {
+    return factory();
   }
   throw new Error(`Unsupported warehouse driver "${driver}". Supported drivers: ${supportedDrivers.join(', ')}`);
 }

packages/cli/src/context/connections/drivers.ts

@@ -0,0 +1,199 @@
+import type { KtxConnectionDriver, KtxScanConnector } from '../scan/types.js';
+
+/** @internal */
+export type KtxScopeConfigKey = 'dataset_ids' | 'databases' | 'schemas' | 'schema_names';
+
+/** @internal */
+export interface KtxDriverConnectorModule {
+  isConnectionConfig(connection: unknown): boolean;
+  createScanConnector(args: {
+    connectionId: string;
+    connection: unknown;
+    projectDir: string;
+  }): KtxScanConnector;
+}
+
+export interface KtxDriverRegistration {
+  readonly driver: KtxConnectionDriver;
+  readonly scopeConfigKey: KtxScopeConfigKey | null;
+  readonly hasHistoricSqlReader: boolean;
+  readonly hasLocalQueryExecutor: boolean;
+  load(): Promise<KtxDriverConnectorModule>;
+}
+
+function invalidConnectionConfig(driver: KtxConnectionDriver): Error {
+  return new Error(`Connection config does not match warehouse driver "${driver}".`);
+}
+
+/** @internal */
+export const driverRegistrations: Record<KtxConnectionDriver, KtxDriverRegistration> = {
+  bigquery: {
+    driver: 'bigquery',
+    scopeConfigKey: 'dataset_ids',
+    hasHistoricSqlReader: true,
+    hasLocalQueryExecutor: false,
+    load: async () => {
+      const m = await import('../../connectors/bigquery/connector.js');
+      return {
+        isConnectionConfig: (connection) => {
+          const typedConnection = connection as Parameters<typeof m.isKtxBigQueryConnectionConfig>[0];
+          return m.isKtxBigQueryConnectionConfig(typedConnection);
+        },
+        createScanConnector: ({ connectionId, connection }) => {
+          const typedConnection = connection as Parameters<typeof m.isKtxBigQueryConnectionConfig>[0];
+          if (!m.isKtxBigQueryConnectionConfig(typedConnection)) {
+            throw invalidConnectionConfig('bigquery');
+          }
+          return new m.KtxBigQueryScanConnector({ connectionId, connection: typedConnection });
+        },
+      };
+    },
+  },
+  clickhouse: {
+    driver: 'clickhouse',
+    scopeConfigKey: 'databases',
+    hasHistoricSqlReader: false,
+    hasLocalQueryExecutor: false,
+    load: async () => {
+      const m = await import('../../connectors/clickhouse/connector.js');
+      return {
+        isConnectionConfig: (connection) => {
+          const typedConnection = connection as Parameters<typeof m.isKtxClickHouseConnectionConfig>[0];
+          return m.isKtxClickHouseConnectionConfig(typedConnection);
+        },
+        createScanConnector: ({ connectionId, connection }) => {
+          const typedConnection = connection as Parameters<typeof m.isKtxClickHouseConnectionConfig>[0];
+          if (!m.isKtxClickHouseConnectionConfig(typedConnection)) {
+            throw invalidConnectionConfig('clickhouse');
+          }
+          return new m.KtxClickHouseScanConnector({ connectionId, connection: typedConnection });
+        },
+      };
+    },
+  },
+  mysql: {
+    driver: 'mysql',
+    scopeConfigKey: 'schemas',
+    hasHistoricSqlReader: false,
+    hasLocalQueryExecutor: false,
+    load: async () => {
+      const m = await import('../../connectors/mysql/connector.js');
+      return {
+        isConnectionConfig: (connection) => {
+          const typedConnection = connection as Parameters<typeof m.isKtxMysqlConnectionConfig>[0];
+          return m.isKtxMysqlConnectionConfig(typedConnection);
+        },
+        createScanConnector: ({ connectionId, connection }) => {
+          const typedConnection = connection as Parameters<typeof m.isKtxMysqlConnectionConfig>[0];
+          if (!m.isKtxMysqlConnectionConfig(typedConnection)) {
+            throw invalidConnectionConfig('mysql');
+          }
+          return new m.KtxMysqlScanConnector({ connectionId, connection: typedConnection });
+        },
+      };
+    },
+  },
+  postgres: {
+    driver: 'postgres',
+    scopeConfigKey: 'schemas',
+    hasHistoricSqlReader: true,
+    hasLocalQueryExecutor: true,
+    load: async () => {
+      const m = await import('../../connectors/postgres/connector.js');
+      return {
+        isConnectionConfig: (connection) => {
+          const typedConnection = connection as Parameters<typeof m.isKtxPostgresConnectionConfig>[0];
+          return m.isKtxPostgresConnectionConfig(typedConnection);
+        },
+        createScanConnector: ({ connectionId, connection }) => {
+          const typedConnection = connection as Parameters<typeof m.isKtxPostgresConnectionConfig>[0];
+          if (!m.isKtxPostgresConnectionConfig(typedConnection)) {
+            throw invalidConnectionConfig('postgres');
+          }
+          return new m.KtxPostgresScanConnector({ connectionId, connection: typedConnection });
+        },
+      };
+    },
+  },
+  sqlite: {
+    driver: 'sqlite',
+    scopeConfigKey: null,
+    hasHistoricSqlReader: false,
+    hasLocalQueryExecutor: true,
+    load: async () => {
+      const m = await import('../../connectors/sqlite/connector.js');
+      return {
+        isConnectionConfig: (connection) => {
+          const typedConnection = connection as Parameters<typeof m.isKtxSqliteConnectionConfig>[0];
+          return m.isKtxSqliteConnectionConfig(typedConnection);
+        },
+        createScanConnector: ({ connectionId, connection, projectDir }) => {
+          const typedConnection = connection as Parameters<typeof m.isKtxSqliteConnectionConfig>[0];
+          if (!m.isKtxSqliteConnectionConfig(typedConnection)) {
+            throw invalidConnectionConfig('sqlite');
+          }
+          return new m.KtxSqliteScanConnector({ connectionId, connection: typedConnection, projectDir });
+        },
+      };
+    },
+  },
+  snowflake: {
+    driver: 'snowflake',
+    scopeConfigKey: 'schema_names',
+    hasHistoricSqlReader: true,
+    hasLocalQueryExecutor: false,
+    load: async () => {
+      const m = await import('../../connectors/snowflake/connector.js');
+      return {
+        isConnectionConfig: (connection) => {
+          const typedConnection = connection as Parameters<typeof m.isKtxSnowflakeConnectionConfig>[0];
+          return m.isKtxSnowflakeConnectionConfig(typedConnection);
+        },
+        createScanConnector: ({ connectionId, connection, projectDir }) => {
+          const typedConnection = connection as Parameters<typeof m.isKtxSnowflakeConnectionConfig>[0];
+          if (!m.isKtxSnowflakeConnectionConfig(typedConnection)) {
+            throw invalidConnectionConfig('snowflake');
+          }
+          return new m.KtxSnowflakeScanConnector({ connectionId, connection: typedConnection, projectDir });
+        },
+      };
+    },
+  },
+  sqlserver: {
+    driver: 'sqlserver',
+    scopeConfigKey: 'schemas',
+    hasHistoricSqlReader: false,
+    hasLocalQueryExecutor: false,
+    load: async () => {
+      const m = await import('../../connectors/sqlserver/connector.js');
+      return {
+        isConnectionConfig: (connection) => {
+          const typedConnection = connection as Parameters<typeof m.isKtxSqlServerConnectionConfig>[0];
+          return m.isKtxSqlServerConnectionConfig(typedConnection);
+        },
+        createScanConnector: ({ connectionId, connection }) => {
+          const typedConnection = connection as Parameters<typeof m.isKtxSqlServerConnectionConfig>[0];
+          if (!m.isKtxSqlServerConnectionConfig(typedConnection)) {
+            throw invalidConnectionConfig('sqlserver');
+          }
+          return new m.KtxSqlServerScanConnector({ connectionId, connection: typedConnection });
+        },
+      };
+    },
+  },
+};
+
+const supportedDrivers = Object.keys(driverRegistrations).sort() as KtxConnectionDriver[];
+
+function isRegisteredDriver(driver: string): driver is KtxConnectionDriver {
+  return Object.prototype.hasOwnProperty.call(driverRegistrations, driver);
+}
+
+export function getDriverRegistration(driver: string): KtxDriverRegistration | undefined {
+  const normalized = driver.toLowerCase().trim();
+  return isRegisteredDriver(normalized) ? driverRegistrations[normalized] : undefined;
+}
+
+export function listSupportedDrivers(): KtxConnectionDriver[] {
+  return [...supportedDrivers];
+}

packages/cli/src/context/connections/local-query-executor.test.ts

@@ -1,59 +0,0 @@
-import { describe, expect, it, vi } from 'vitest';
-import { createDefaultLocalQueryExecutor } from './local-query-executor.js';
-
-describe('createDefaultLocalQueryExecutor', () => {
-  it('dispatches postgres and sqlite drivers to their executors', async () => {
-    const postgres = {
-      execute: vi.fn(async () => ({
-        headers: ['pg'],
-        rows: [[1]],
-        totalRows: 1,
-        command: 'SELECT',
-        rowCount: 1,
-      })),
-    };
-    const sqlite = {
-      execute: vi.fn(async () => ({
-        headers: ['sqlite'],
-        rows: [[2]],
-        totalRows: 1,
-        command: 'SELECT',
-        rowCount: 1,
-      })),
-    };
-    const executor = createDefaultLocalQueryExecutor({ postgres, sqlite });
-
-    await expect(
-      executor.execute({
-        connectionId: 'pg',
-        connection: { driver: 'postgres' },
-        sql: 'select 1',
-      }),
-    ).resolves.toMatchObject({ headers: ['pg'] });
-    await expect(
-      executor.execute({
-        connectionId: 'local',
-        connection: { driver: 'sqlite' },
-        sql: 'select 1',
-      }),
-    ).resolves.toMatchObject({ headers: ['sqlite'] });
-
-    expect(postgres.execute).toHaveBeenCalledTimes(1);
-    expect(sqlite.execute).toHaveBeenCalledTimes(1);
-  });
-
-  it('rejects unsupported local execution drivers', async () => {
-    const executor = createDefaultLocalQueryExecutor({
-      postgres: { execute: vi.fn() },
-      sqlite: { execute: vi.fn() },
-    });
-
-    await expect(
-      executor.execute({
-        connectionId: 'warehouse',
-        connection: { driver: 'snowflake' },
-        sql: 'select 1',
-      }),
-    ).rejects.toThrow('No local query executor is configured for driver "snowflake".');
-  });
-});

packages/cli/src/context/connections/local-query-executor.ts

@@ -1,3 +1,4 @@
+import { driverRegistrations, getDriverRegistration } from './drivers.js';
 import { createPostgresQueryExecutor } from './postgres-query-executor.js';
 import type {
   KtxSqlQueryExecutionInput,
@@ -5,6 +6,7 @@ import type {
   KtxSqlQueryExecutorPort,
 } from './query-executor.js';
 import { createSqliteQueryExecutor } from './sqlite-query-executor.js';
+import type { KtxConnectionDriver } from '../scan/types.js';
 
 export interface DefaultLocalQueryExecutorOptions {
   postgres?: KtxSqlQueryExecutorPort;
@@ -15,20 +17,43 @@ function driverFor(input: KtxSqlQueryExecutionInput): string {
   return String(input.connection?.driver ?? '').toLowerCase();
 }
 
+function localExecutorMap(
+  options: DefaultLocalQueryExecutorOptions,
+): Partial<Record<KtxConnectionDriver, KtxSqlQueryExecutorPort>> {
+  const wiredExecutors: Partial<Record<KtxConnectionDriver, KtxSqlQueryExecutorPort>> = {
+    postgres: options.postgres ?? createPostgresQueryExecutor(),
+    sqlite: options.sqlite ?? createSqliteQueryExecutor(),
+  };
+
+  const executors: Partial<Record<KtxConnectionDriver, KtxSqlQueryExecutorPort>> = {};
+  for (const registration of Object.values(driverRegistrations)) {
+    if (!registration.hasLocalQueryExecutor) continue;
+    const executor = wiredExecutors[registration.driver];
+    if (executor) {
+      executors[registration.driver] = executor;
+    }
+  }
+  return executors;
+}
+
 export function createDefaultLocalQueryExecutor(options: DefaultLocalQueryExecutorOptions = {}): KtxSqlQueryExecutorPort {
-  const postgres = options.postgres ?? createPostgresQueryExecutor();
-  const sqlite = options.sqlite ?? createSqliteQueryExecutor();
+  const executors = localExecutorMap(options);
 
   return {
     async execute(input: KtxSqlQueryExecutionInput): Promise<KtxSqlQueryExecutionResult> {
       const driver = driverFor(input);
-      if (driver === 'postgres') {
-        return postgres.execute(input);
+      const registration = getDriverRegistration(driver);
+      if (!registration?.hasLocalQueryExecutor) {
+        throw new Error(`No local query executor is configured for driver "${input.connection?.driver ?? 'unknown'}".`);
       }
-      if (driver === 'sqlite') {
-        return sqlite.execute(input);
+
+      const executor = executors[registration.driver];
+      if (!executor) {
+        throw new Error(
+          `Local query executor flag is enabled for driver "${registration.driver}", but no executor factory is wired.`,
+        );
       }
-      throw new Error(`No local query executor is configured for driver "${input.connection?.driver ?? 'unknown'}".`);
+      return executor.execute(input);
     },
   };
 }

packages/cli/src/context/connections/local-warehouse-descriptor.test.ts

@@ -1,76 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import {
-  localConnectionInfoFromConfig,
-  localConnectionToWarehouseDescriptor,
-  localConnectionTypeForConfig,
-} from './local-warehouse-descriptor.js';
-
-describe('localConnectionToWarehouseDescriptor', () => {
-  it('maps local Postgres URLs to canonical warehouse descriptors', () => {
-    expect(
-      localConnectionToWarehouseDescriptor('warehouse', {
-        driver: 'postgres',
-        url: 'postgresql://readonly@db.example.test/analytics',
-      }),
-    ).toMatchObject({
-      id: 'warehouse',
-      connection_type: 'POSTGRESQL',
-      host: 'db.example.test',
-      database: 'analytics',
-    });
-  });
-
-  it('maps BigQuery project and dataset from explicit fields', () => {
-    expect(
-      localConnectionToWarehouseDescriptor('bq', {
-        driver: 'bigquery',
-        project_id: 'acme',
-        dataset_id: 'warehouse',
-      }),
-    ).toMatchObject({
-      id: 'bq',
-      connection_type: 'BIGQUERY',
-      project_id: 'acme',
-      dataset_id: 'warehouse',
-    });
-  });
-
-  it('returns null for non-warehouse adapters', () => {
-    expect(
-      localConnectionToWarehouseDescriptor('looker', {
-        driver: 'looker',
-        base_url: 'https://looker.example.com',
-        client_id: 'client',
-      }),
-    ).toBeNull();
-  });
-});
-
-describe('local connection info helpers', () => {
-  it('returns canonical warehouse connection types for local catalogs', () => {
-    expect(localConnectionTypeForConfig('warehouse', { driver: 'postgres' })).toBe('POSTGRESQL');
-    expect(localConnectionTypeForConfig('bq', { driver: 'bigquery', project_id: 'acme' })).toBe('BIGQUERY');
-    expect(localConnectionTypeForConfig('snowflake', { driver: 'snowflake' })).toBe('SNOWFLAKE');
-  });
-
-  it('keeps removed driver aliases as display-only labels', () => {
-    expect(localConnectionTypeForConfig('warehouse', { driver: 'postgresql' } as never)).toBe('postgresql');
-    expect(localConnectionTypeForConfig('warehouse', { driver: 'mssql' } as never)).toBe('mssql');
-  });
-
-  it('keeps non-warehouse adapter labels for display-only local connection surfaces', () => {
-    expect(localConnectionTypeForConfig('prod-metabase', { driver: 'metabase', api_url: 'https://metabase.example.com' })).toBe(
-      'metabase',
-    );
-    expect(localConnectionTypeForConfig('missing-driver', {} as never)).toBe('unknown');
-  });
-
-  it('builds nullable local connection info records', () => {
-    expect(localConnectionInfoFromConfig('warehouse', { driver: 'postgres' })).toEqual({
-      id: 'warehouse',
-      name: 'warehouse',
-      connectionType: 'POSTGRESQL',
-    });
-    expect(localConnectionInfoFromConfig('missing', undefined)).toBeNull();
-  });
-});

packages/cli/src/context/connections/notion-config.test.ts

@@ -1,157 +0,0 @@
-import { mkdtemp, rm, writeFile } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-import {
-  notionConnectionToPullConfig,
-  parseNotionConnectionConfig,
-  redactNotionConnectionConfig,
-  resolveNotionAuthToken,
-} from './notion-config.js';
-
-describe('standalone Notion connection config', () => {
-  let tempDir: string;
-
-  beforeEach(async () => {
-    tempDir = await mkdtemp(join(tmpdir(), 'ktx-notion-config-'));
-  });
-
-  afterEach(async () => {
-    await rm(tempDir, { recursive: true, force: true });
-  });
-
-  it('parses selected-root Notion config with safe defaults', () => {
-    const parsed = parseNotionConnectionConfig({
-      driver: 'notion',
-      auth_token_ref: 'env:NOTION_TOKEN',
-      crawl_mode: 'selected_roots',
-      root_page_ids: ['page-1'],
-    });
-
-    expect(parsed).toEqual({
-      driver: 'notion',
-      auth_token: null,
-      auth_token_ref: 'env:NOTION_TOKEN',
-      crawl_mode: 'selected_roots',
-      root_page_ids: ['page-1'],
-      root_database_ids: [],
-      root_data_source_ids: [],
-      max_pages_per_run: 1000,
-      max_knowledge_creates_per_run: 25,
-      max_knowledge_updates_per_run: 20,
-    });
-    expect(parsed).not.toHaveProperty('last_successful_cursor');
-  });
-
-  it('parses inline Notion auth tokens without requiring auth_token_ref', () => {
-    const parsed = parseNotionConnectionConfig({
-      driver: 'notion',
-      auth_token: '  ntn_inline_token  ',
-      crawl_mode: 'selected_roots',
-      root_page_ids: ['page-1'],
-    });
-
-    expect(parsed).toMatchObject({
-      driver: 'notion',
-      auth_token: 'ntn_inline_token',
-      auth_token_ref: null,
-      crawl_mode: 'selected_roots',
-      root_page_ids: ['page-1'],
-    });
-  });
-
-  it('redacts token references from display output', () => {
-    expect(
-      redactNotionConnectionConfig(
-        parseNotionConnectionConfig({
-          driver: 'notion',
-          auth_token_ref: 'file:/Users/example/.config/notion-token',
-          crawl_mode: 'all_accessible',
-          max_pages_per_run: 80,
-        }),
-      ),
-    ).toEqual({
-      driver: 'notion',
-      hasAuthToken: true,
-      crawlMode: 'all_accessible',
-      rootPageIds: [],
-      rootDatabaseIds: [],
-      rootDataSourceIds: [],
-      maxPagesPerRun: 80,
-      maxKnowledgeCreatesPerRun: 25,
-      maxKnowledgeUpdatesPerRun: 20,
-      warning: 'Anything accessible to this Notion integration can become organization knowledge.',
-    });
-  });
-
-  it('requires at least one selected root in selected_roots mode', () => {
-    expect(() =>
-      parseNotionConnectionConfig({
-        driver: 'notion',
-        auth_token_ref: 'env:NOTION_TOKEN',
-        crawl_mode: 'selected_roots',
-      }),
-    ).toThrow('selected_roots requires at least one root page, database, or data source id');
-  });
-
-  it('resolves env and file token references without exposing the reference in errors', async () => {
-    const tokenPath = join(tempDir, 'notion-token.txt');
-    await writeFile(tokenPath, 'ntn_file_token\n', 'utf-8');
-
-    await expect(
-      resolveNotionAuthToken('env:NOTION_TOKEN', {
-        env: { NOTION_TOKEN: 'ntn_env_token' },
-      }),
-    ).resolves.toBe('ntn_env_token');
-    await expect(resolveNotionAuthToken(`file:${tokenPath}`)).resolves.toBe('ntn_file_token');
-    await expect(resolveNotionAuthToken('env:MISSING_NOTION_TOKEN', { env: {} })).rejects.toThrow(
-      'Notion token environment variable MISSING_NOTION_TOKEN is not set',
-    );
-  });
-
-  it('converts standalone config into adapter pull config', async () => {
-    const pullConfig = await notionConnectionToPullConfig(
-      parseNotionConnectionConfig({
-        driver: 'notion',
-        auth_token_ref: 'env:NOTION_TOKEN',
-        crawl_mode: 'all_accessible',
-        max_pages_per_run: 12,
-        max_knowledge_creates_per_run: 2,
-        max_knowledge_updates_per_run: 7,
-        last_successful_cursor: '{"phase":"all_accessible_pages","cursor":"cursor-1"}',
-      }),
-      { env: { NOTION_TOKEN: 'ntn_env_token' } },
-    );
-
-    expect(pullConfig).toEqual({
-      authToken: 'ntn_env_token',
-      crawlMode: 'all_accessible',
-      rootPageIds: [],
-      rootDatabaseIds: [],
-      rootDataSourceIds: [],
-      maxPagesPerRun: 12,
-      maxKnowledgeCreatesPerRun: 2,
-      maxKnowledgeUpdatesPerRun: 7,
-      lastSuccessfulCursor: null,
-    });
-  });
-
-  it('uses inline Notion auth_token when building adapter pull config', async () => {
-    const pullConfig = await notionConnectionToPullConfig(
-      parseNotionConnectionConfig({
-        driver: 'notion',
-        auth_token: 'ntn_inline_token',
-        auth_token_ref: 'env:STALE_NOTION_TOKEN',
-        crawl_mode: 'all_accessible',
-      }),
-      {
-        env: {},
-        readTextFile: async () => {
-          throw new Error('readTextFile should not be called for inline auth_token');
-        },
-      },
-    );
-
-    expect(pullConfig.authToken).toBe('ntn_inline_token');
-  });
-});

packages/cli/src/context/connections/postgres-query-executor.test.ts

@@ -1,103 +0,0 @@
-import { describe, expect, it, vi } from 'vitest';
-import { createPostgresQueryExecutor } from './postgres-query-executor.js';
-
-function makeClient() {
-  const calls: unknown[] = [];
-  const client = {
-    connect: vi.fn(async () => undefined),
-    query: vi.fn(async (input: unknown) => {
-      calls.push(input);
-      if (input === 'BEGIN READ ONLY') {
-        return { rows: [], fields: [], rowCount: null, command: 'BEGIN' };
-      }
-      if (input === 'COMMIT') {
-        return { rows: [], fields: [], rowCount: null, command: 'COMMIT' };
-      }
-      return {
-        rows: [
-          ['paid', 2],
-          ['open', 1],
-        ],
-        fields: [{ name: 'status' }, { name: 'order_count' }],
-        rowCount: 2,
-        command: 'SELECT',
-      };
-    }),
-    end: vi.fn(async () => undefined),
-  };
-  return { client, calls };
-}
-
-describe('createPostgresQueryExecutor', () => {
-  it('runs a read-only transaction in array row mode and closes the client', async () => {
-    const { client, calls } = makeClient();
-    const executor = createPostgresQueryExecutor({
-      clientFactory: vi.fn(() => client),
-    });
-
-    const result = await executor.execute({
-      connectionId: 'warehouse',
-      connection: { driver: 'postgres', url: 'postgres://example/db' },
-      sql: 'select status, count(*) as order_count from public.orders group by status',
-      maxRows: 50,
-    });
-
-    expect(client.connect).toHaveBeenCalledTimes(1);
-    expect(calls[0]).toBe('BEGIN READ ONLY');
-    expect(calls[1]).toEqual({
-      text: 'select * from (select status, count(*) as order_count from public.orders group by status) as ktx_query_result limit 50',
-      rowMode: 'array',
-    });
-    expect(calls[2]).toBe('COMMIT');
-    expect(client.end).toHaveBeenCalledTimes(1);
-    expect(result).toEqual({
-      headers: ['status', 'order_count'],
-      rows: [
-        ['paid', 2],
-        ['open', 1],
-      ],
-      totalRows: 2,
-      command: 'SELECT',
-      rowCount: 2,
-    });
-  });
-
-  it('rolls back and closes the client when query execution fails', async () => {
-    const client = {
-      connect: vi.fn(async () => undefined),
-      query: vi.fn(async (input: unknown) => {
-        if (input === 'BEGIN READ ONLY' || input === 'ROLLBACK') {
-          return { rows: [], fields: [], rowCount: null, command: String(input) };
-        }
-        throw new Error('syntax error');
-      }),
-      end: vi.fn(async () => undefined),
-    };
-    const executor = createPostgresQueryExecutor({
-      clientFactory: vi.fn(() => client),
-    });
-
-    await expect(
-      executor.execute({
-        connectionId: 'warehouse',
-        connection: { driver: 'postgres', url: 'postgres://example/db' },
-        sql: 'select * from broken',
-        maxRows: 10,
-      }),
-    ).rejects.toThrow('syntax error');
-    expect(client.query).toHaveBeenCalledWith('ROLLBACK');
-    expect(client.end).toHaveBeenCalledTimes(1);
-  });
-
-  it('requires a Postgres url', async () => {
-    const executor = createPostgresQueryExecutor({ clientFactory: vi.fn() });
-
-    await expect(
-      executor.execute({
-        connectionId: 'warehouse',
-        connection: { driver: 'postgres' },
-        sql: 'select 1',
-      }),
-    ).rejects.toThrow('Local Postgres execution requires connections.warehouse.url');
-  });
-});

packages/cli/src/context/connections/read-only-sql.test.ts

@@ -1,30 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { assertReadOnlySql, limitSqlForExecution } from './read-only-sql.js';
-
-describe('assertReadOnlySql', () => {
-  it('allows select and with queries', () => {
-    expect(assertReadOnlySql('select * from orders')).toBe('select * from orders');
-    expect(assertReadOnlySql('with paid as (select * from orders) select * from paid')).toContain('with paid');
-  });
-
-  it('rejects mutating statements before opening a database connection', () => {
-    expect(() => assertReadOnlySql('delete from orders')).toThrow(
-      'Only read-only SELECT/WITH queries can be executed locally',
-    );
-    expect(() => assertReadOnlySql('create table x(id int)')).toThrow(
-      'Only read-only SELECT/WITH queries can be executed locally',
-    );
-  });
-});
-
-describe('limitSqlForExecution', () => {
-  it('wraps compiled SQL and strips trailing semicolons', () => {
-    expect(limitSqlForExecution('select * from public.orders; ', 25)).toBe(
-      'select * from (select * from public.orders) as ktx_query_result limit 25',
-    );
-  });
-
-  it('returns the trimmed SQL when no maxRows value is provided', () => {
-    expect(limitSqlForExecution('select * from orders; ', undefined)).toBe('select * from orders');
-  });
-});

packages/cli/src/context/connections/sqlite-query-executor.test.ts

@@ -1,139 +0,0 @@
-import { mkdtemp, rm } from 'node:fs/promises';
-import { writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import Database from 'better-sqlite3';
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-import { createSqliteQueryExecutor, sqliteDatabasePathFromConnection } from './sqlite-query-executor.js';
-
-describe('createSqliteQueryExecutor', () => {
-  let tempDir: string;
-  let dbPath: string;
-
-  beforeEach(async () => {
-    tempDir = await mkdtemp(join(tmpdir(), 'ktx-sqlite-query-'));
-    dbPath = join(tempDir, 'warehouse.db');
-    const db = new Database(dbPath);
-    db.exec(`
-      CREATE TABLE orders (
-        id INTEGER PRIMARY KEY,
-        status TEXT NOT NULL,
-        amount INTEGER NOT NULL
-      );
-      INSERT INTO orders (status, amount) VALUES
-        ('paid', 20),
-        ('paid', 30),
-        ('open', 10);
-    `);
-    db.close();
-  });
-
-  afterEach(async () => {
-    await rm(tempDir, { recursive: true, force: true });
-  });
-
-  it('executes read-only SELECT SQL against a relative SQLite path', async () => {
-    const executor = createSqliteQueryExecutor();
-
-    const result = await executor.execute({
-      connectionId: 'warehouse',
-      projectDir: tempDir,
-      connection: { driver: 'sqlite', path: 'warehouse.db' },
-      sql: 'select status, count(*) as order_count from orders group by status order by status',
-      maxRows: 10,
-    });
-
-    expect(result).toEqual({
-      headers: ['status', 'order_count'],
-      rows: [
-        ['open', 1],
-        ['paid', 2],
-      ],
-      totalRows: 2,
-      command: 'SELECT',
-      rowCount: 2,
-    });
-  });
-
-  it('supports file urls for SQLite database paths', async () => {
-    expect(
-      sqliteDatabasePathFromConnection({
-        connectionId: 'warehouse',
-        projectDir: tempDir,
-        connection: { driver: 'sqlite', url: `file://${dbPath}` },
-        sql: 'select 1',
-      }),
-    ).toBe(dbPath);
-  });
-
-  it('resolves file references for SQLite path fields', async () => {
-    const pointerPath = join(tempDir, 'sqlite-path.txt');
-    writeFileSync(pointerPath, dbPath, 'utf-8');
-
-    expect(
-      sqliteDatabasePathFromConnection({
-        connectionId: 'warehouse',
-        projectDir: tempDir,
-        connection: { driver: 'sqlite', path: `file:${pointerPath}` },
-        sql: 'select 1',
-      }),
-    ).toBe(dbPath);
-  });
-
-  it('resolves env references for SQLite database urls', async () => {
-    const originalDatabaseUrl = process.env.KTX_SQLITE_TEST_URL;
-    process.env.KTX_SQLITE_TEST_URL = `sqlite:${dbPath}`;
-
-    try {
-      expect(
-        sqliteDatabasePathFromConnection({
-          connectionId: 'warehouse',
-          projectDir: tempDir,
-          connection: { driver: 'sqlite', url: 'env:KTX_SQLITE_TEST_URL' },
-          sql: 'select 1',
-        }),
-      ).toBe(dbPath);
-    } finally {
-      if (originalDatabaseUrl === undefined) {
-        delete process.env.KTX_SQLITE_TEST_URL;
-      } else {
-        process.env.KTX_SQLITE_TEST_URL = originalDatabaseUrl;
-      }
-    }
-  });
-
-  it('rejects mutating SQL before opening the database', async () => {
-    const executor = createSqliteQueryExecutor();
-
-    await expect(
-      executor.execute({
-        connectionId: 'warehouse',
-        projectDir: tempDir,
-        connection: { driver: 'sqlite', path: 'warehouse.db' },
-        sql: 'delete from orders',
-      }),
-    ).rejects.toThrow('Only read-only SELECT/WITH queries can be executed locally');
-  });
-
-  it('requires a SQLite driver and a database path', async () => {
-    const executor = createSqliteQueryExecutor();
-
-    await expect(
-      executor.execute({
-        connectionId: 'warehouse',
-        projectDir: tempDir,
-        connection: { driver: 'postgres', path: 'warehouse.db' },
-        sql: 'select 1',
-      }),
-    ).rejects.toThrow('Local SQLite execution cannot run driver "postgres"');
-
-    await expect(
-      executor.execute({
-        connectionId: 'warehouse',
-        projectDir: tempDir,
-        connection: { driver: 'sqlite' },
-        sql: 'select 1',
-      }),
-    ).rejects.toThrow('Local SQLite execution requires connections.warehouse.path or connections.warehouse.url');
-  });
-});