chore(workspace): gate dead-code with knip production mode (#196)

* refactor(workspace): relocate @ktx/llm source into packages/cli/src/llm

* refactor(workspace): rewrite @ktx/llm imports to relative paths

* refactor(workspace): fold internal packages into cli

* chore(workspace): gate dead-code with knip production mode

Turn on production-mode knip plus an autofix run in pre-commit and the
`pnpm dead-code` script, document the `/** @internal */` convention for
test-only exports in AGENTS.md, annotate test-only exports across the
CLI with that JSDoc, and drop dead exports/wrappers the new gate
surfaced (e.g. `cli-project.ts`, `lookerRuntimeSourceToFileAdapterSource`,
`createLocalScanEnrichmentProvidersFromConfig`,
`PGLITE_OWNER_PROCESS_BACKEND_CAPABILITIES`, stale type re-exports).
Replace the loose `ignoreIssues` allowlist in `knip.json` with explicit
production entries so cross-package barrel leaks are caught.

* refactor(cli): delete internal barrel index.ts files

The 34 `index.ts` re-export barrels inside `packages/cli/src/` were
holdovers from the pre-fold multi-workspace structure. Post-fold-in they
served no production purpose: external consumers go through the single
package main entry, and in-repo callers mostly imported through them
only because the path was short. Internally, knip flagged most barrel
re-exports as production-dead (only reached via tests).

This change:
- Deletes every internal barrel except `packages/cli/src/index.ts`
  (the published package entry).
- Rewrites ~270 source/test files to import each name directly from
  the file that defines it.
- Moves `tools/warehouse-verification/index.ts` to
  `create-warehouse-verification-tools.ts` (the function it defined
  locally) and updates its single consumer.
- Renames `search/backend-conformance.ts` → `.test-utils.ts` to match
  the existing test-helper file convention.
- Deletes 13 dead test-only chains (dbt-descriptions/*,
  live-database/extracted-schema, live-database/structural-sync,
  relationship-* feedback/review chain) plus their tests and a
  cascading orphan integration test.
- Updates test mocks that pointed at deleted barrel paths
  (notion-client, connector barrels in scan/local-scan-connectors
  tests) to mock the source files instead.
- Points the maintainer benchmark script
  (`scripts/relationship-benchmark-report.mjs`) at source files
  instead of `dist/context/scan/index.js`.
- Drops the barrel `!` entries from `knip.json`; adds explicit
  production entries only for the benchmark code reached via dist by
  the maintainer script.

Net: 413 files changed, ~1.2k insertions, ~9.4k deletions.

`pnpm run dead-code` (Biome + knip default + knip production) and
`pnpm run type-check` are clean; 2277 tests pass.

* refactor(workspace): rename @ktx/cli to @kaelio/ktx and pack it directly

Promote the CLI workspace package to the public name `@kaelio/ktx` and
drop the separate `scripts/build-public-npm-package.mjs` wrapper. The
CLI package is now publishable in place (`publishConfig.access: public`,
`provenance: true`), so artifact packing uses `pnpm pack` against
`packages/cli/` instead of assembling a parallel package tree.

Updates all workspace filter invocations, docs, tests, and release
readiness checks to reference the new package name, and folds the
tarball-name helper into `scripts/public-npm-release-metadata.mjs`.

* docs: align "agent clients" and "data agents" terminology

Replace "client agents" with "agent clients" and "database agents" with
"data agents" across AGENTS.md, README.md, the docs-site copy, and the
matching setup-agents test description, matching the canonical
vocabulary in docs/terminology.md.

Also moves packages/cli/tsconfig.json's tsBuildInfoFile from
node_modules/.cache/ to dist/.tsbuildinfo so incremental builds survive
node_modules reinstalls.

* refactor(release): single source of truth for package version

Make packages/cli/package.json the single source of truth for the
@kaelio/ktx version. publicNpmPackageVersion() now reads it directly,
so artifact filenames, release-readiness checks, and the Python wheel
version all derive from one field. The duplicate
release-policy.json.publicNpmPackageVersion is removed.

Previously the two fields could drift: tarballs were named
kaelio-ktx-0.4.1.tgz while internally containing
@kaelio/ktx@0.0.0-private.

- update-public-release-version.mjs rewrites both Python pyproject.toml
  files (ktx-daemon, ktx-sl) alongside the npm package.jsons,
  normalizing the version for PEP 440 (e.g. 0.1.0-rc.2 -> 0.1.0rc2).
- semantic-release-config.cjs adds the two pyproject.toml files to
  @semantic-release/git assets so the release commit back to main
  carries every version source in lockstep.
- The six "?? '0.0.0-private'" fallback literals across the CLI are
  replaced with "?? getKtxCliPackageInfo().version", and
  createDefaultKtxMcpServer makes its version arg required.
- docs/release.md describes the actual commit-back model: the dev tree
  always reflects the most recent release; no sentinel pin to
  maintain.

Verified: pnpm run artifacts:build now produces
kaelio-ktx-0.4.1.tgz and kaelio_ktx-0.4.1-py3-none-any.whl with
@kaelio/ktx@0.4.1 inside. Full type-check, dead-code, and
2287 vitests + 173 script tests pass.

* refactor(cli): inject embedding provider resolution and detect sentence-transformers runtime

Make resolveProjectEmbeddingProvider and runtimeIo injectable in ingest and
scan command entrypoints so tests can stub them, and teach
resolvePublicIngestRuntimeRequirements to flag the local-embeddings runtime
feature when ktx.yaml selects sentence-transformers.

* chore(cli): mark buildLocalStatsStatus and LocalStatsStatus as @internal

Both symbols are consumed only by status-project.test.ts. Annotating with
/** @internal */ keeps knip's production-mode check clean without changing
runtime behavior.

* fix(cli): use real package metadata in print-command-tree

The stubbed package name embedded a forbidden product identifier that
tripped the boundary check in CI. Read the metadata from package.json
instead — keeps the rendered tree unchanged and removes a duplicate
source of truth.

* feat(cli): show embedding coverage in `ktx status`, drop duplicate disk counts

Inline `(N embedded)` next to the Wiki scope counts and Semantic-layer
source counts, computed with `SUM(embedding_json IS NOT NULL)` over
`knowledge_pages` and `local_sl_sources`. Rename the "Knowledge" label to
"Wiki" (canonical per `docs/terminology.md`) and rename the matching
`localStats.knowledgePages` field to `localStats.wikiPages`.

Drop `wiki=N md` and `semantic-layer=N yaml` from the Disk row — those
duplicated the per-surface rows above. Disk now reports only actual byte
usage (db, cache, raw-sources). The unused `wikiGlobalMarkdownCount` /
`semanticLayerYamlCount` fields, the `isMarkdownEntry` / `isYamlEntry`
helpers, and the `filter` arg on `summarizeDir` are removed.

packages/cli/src/context/connections/connection-type.ts

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+
+export const connectionTypeSchema = z.enum([
+  'POSTGRESQL',
+  'SQLITE',
+  'SQLSERVER',
+  'BIGQUERY',
+  'SNOWFLAKE',
+  'CENTRALREACH',
+  'EPIC',
+  'CERNER',
+  'ATHENA',
+  'QUICKBOOKS',
+  'WORKDAY',
+  'REST',
+  'S3',
+  'SLACK',
+  'METABASE',
+  'LOOKER',
+  'NOTION',
+  'MYSQL',
+  'CLICKHOUSE',
+  'PLAIN',
+  'BETTERSTACK',
+]);
+
+export type ConnectionType = z.infer<typeof connectionTypeSchema>;

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

@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest';
+import { getDialectForDriver } from './dialects.js';
+
+describe('getDialectForDriver', () => {
+  it.each([
+    ['postgres', '"public"."orders"'],
+    ['postgresql', '"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, postgresql, sqlite, sqlite3, snowflake, sqlserver',
+    );
+  });
+});

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

@@ -0,0 +1,102 @@
+import type { KtxSchemaDimensionType, KtxTableRef } from '../scan/types.js';
+
+type SupportedDriver =
+  | 'postgres'
+  | 'postgresql'
+  | 'mysql'
+  | 'sqlserver'
+  | 'snowflake'
+  | 'bigquery'
+  | 'clickhouse'
+  | 'sqlite'
+  | 'sqlite3';
+
+export interface KtxDialect {
+  readonly type: SupportedDriver;
+  quoteIdentifier(identifier: string): string;
+  formatTableName(table: KtxTableRef): string;
+  mapToDimensionType(nativeType: string): KtxSchemaDimensionType;
+}
+
+const supportedDrivers: SupportedDriver[] = [
+  'bigquery',
+  'clickhouse',
+  'mysql',
+  'postgres',
+  'postgresql',
+  'sqlite',
+  'sqlite3',
+  'snowflake',
+  '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),
+  postgresql: createDialect('postgresql', doubleQuoted),
+  mysql: createDialect('mysql', backtickQuoted),
+  clickhouse: createDialect('clickhouse', backtickQuoted),
+  sqlite: createDialect('sqlite', doubleQuoted, true),
+  sqlite3: createDialect('sqlite3', doubleQuoted, true),
+  snowflake: createDialect('snowflake', doubleQuoted),
+  bigquery: createDialect('bigquery', bigQueryQuoted),
+  sqlserver: createDialect('sqlserver', bracketQuoted),
+};
+
+export function getDialectForDriver(driver: string): KtxDialect {
+  const normalized = driver.toLowerCase().trim();
+  if (normalized in dialects) {
+    return dialects[normalized as SupportedDriver];
+  }
+  throw new Error(`Unsupported warehouse driver "${driver}". Supported drivers: ${supportedDrivers.join(', ')}`);
+}

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

@@ -0,0 +1,59 @@
+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

@@ -0,0 +1,34 @@
+import { createPostgresQueryExecutor } from './postgres-query-executor.js';
+import type {
+  KtxSqlQueryExecutionInput,
+  KtxSqlQueryExecutionResult,
+  KtxSqlQueryExecutorPort,
+} from './query-executor.js';
+import { createSqliteQueryExecutor } from './sqlite-query-executor.js';
+
+export interface DefaultLocalQueryExecutorOptions {
+  postgres?: KtxSqlQueryExecutorPort;
+  sqlite?: KtxSqlQueryExecutorPort;
+}
+
+function driverFor(input: KtxSqlQueryExecutionInput): string {
+  return String(input.connection?.driver ?? '').toLowerCase();
+}
+
+export function createDefaultLocalQueryExecutor(options: DefaultLocalQueryExecutorOptions = {}): KtxSqlQueryExecutorPort {
+  const postgres = options.postgres ?? createPostgresQueryExecutor();
+  const sqlite = options.sqlite ?? createSqliteQueryExecutor();
+
+  return {
+    async execute(input: KtxSqlQueryExecutionInput): Promise<KtxSqlQueryExecutionResult> {
+      const driver = driverFor(input);
+      if (driver === 'postgres' || driver === 'postgresql') {
+        return postgres.execute(input);
+      }
+      if (driver === 'sqlite' || driver === 'sqlite3') {
+        return sqlite.execute(input);
+      }
+      throw new Error(`No local query executor is configured for driver "${input.connection?.driver ?? 'unknown'}".`);
+    },
+  };
+}

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

@@ -0,0 +1,71 @@
+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 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/local-warehouse-descriptor.ts

@@ -0,0 +1,102 @@
+import type { KtxProjectConnectionConfig } from '../project/config.js';
+import type { ConnectionType } from './connection-type.js';
+
+export interface LocalWarehouseDescriptor {
+  id: string;
+  connection_type: ConnectionType;
+  host?: string | null;
+  database?: string | null;
+  account?: string | null;
+  project_id?: string | null;
+  dataset_id?: string | null;
+  connection_params: Record<string, unknown>;
+}
+
+export interface LocalConnectionInfo {
+  id: string;
+  name: string;
+  connectionType: string;
+}
+
+const DRIVER_TO_CONNECTION_TYPE: Record<string, ConnectionType> = {
+  postgres: 'POSTGRESQL',
+  postgresql: 'POSTGRESQL',
+  sqlite: 'SQLITE',
+  sqlserver: 'SQLSERVER',
+  mssql: 'SQLSERVER',
+  mysql: 'MYSQL',
+  clickhouse: 'CLICKHOUSE',
+  snowflake: 'SNOWFLAKE',
+  bigquery: 'BIGQUERY',
+};
+
+export function localConnectionToWarehouseDescriptor(
+  id: string,
+  connection: KtxProjectConnectionConfig | undefined,
+): LocalWarehouseDescriptor | null {
+  if (!connection) {
+    return null;
+  }
+  const connectionType = DRIVER_TO_CONNECTION_TYPE[String(connection.driver ?? '').toLowerCase()];
+  if (!connectionType) {
+    return null;
+  }
+
+  const info: LocalWarehouseDescriptor = {
+    id,
+    connection_type: connectionType,
+    connection_params: { ...connection },
+  };
+  const url = typeof connection.url === 'string' ? connection.url : null;
+  if (url && !url.startsWith('env:') && !url.startsWith('file:')) {
+    try {
+      const parsed = new URL(url);
+      info.host = parsed.hostname || null;
+      if (parsed.pathname.length > 1) {
+        const [first, second] = parsed.pathname.slice(1).split('/');
+        if (connectionType === 'BIGQUERY') {
+          info.project_id = stringField(connection.project_id) ?? parsed.hostname ?? first ?? null;
+          info.dataset_id = stringField(connection.dataset_id) ?? second ?? null;
+        } else {
+          info.database = first ?? null;
+        }
+      }
+    } catch {
+      info.host = stringField(connection.host);
+    }
+  }
+
+  info.host = stringField(connection.host) ?? info.host ?? null;
+  info.database = stringField(connection.database) ?? info.database ?? null;
+  info.account = stringField(connection.account) ?? null;
+  info.project_id = stringField(connection.project_id) ?? info.project_id ?? null;
+  info.dataset_id = stringField(connection.dataset_id) ?? info.dataset_id ?? null;
+  return info;
+}
+
+export function localConnectionTypeForConfig(id: string, connection: KtxProjectConnectionConfig | undefined): string {
+  const descriptor = localConnectionToWarehouseDescriptor(id, connection);
+  if (descriptor) {
+    return descriptor.connection_type;
+  }
+  const driver = typeof connection?.driver === 'string' ? connection.driver.trim() : '';
+  return driver.length > 0 ? driver : 'unknown';
+}
+
+export function localConnectionInfoFromConfig(
+  id: string,
+  connection: KtxProjectConnectionConfig | undefined,
+): LocalConnectionInfo | null {
+  if (!connection) {
+    return null;
+  }
+  return {
+    id,
+    name: id,
+    connectionType: localConnectionTypeForConfig(id, connection),
+  };
+}
+
+function stringField(value: unknown): string | null {
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
+}

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

@@ -0,0 +1,157 @@
+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/notion-config.ts

@@ -0,0 +1,224 @@
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+import {
+  NOTION_DEFAULT_MAX_KNOWLEDGE_CREATES_PER_RUN,
+  type NotionPullConfig,
+  notionPullConfigSchema,
+} from '../ingest/adapters/notion/types.js';
+import type { KtxProjectConnectionConfig } from '../project/config.js';
+
+const KTX_NOTION_ORG_KNOWLEDGE_WARNING =
+  'Anything accessible to this Notion integration can become organization knowledge.';
+
+type KtxNotionCrawlMode = 'all_accessible' | 'selected_roots';
+
+type RawKtxNotionConnectionConfig = Extract<KtxProjectConnectionConfig, { driver: 'notion' }>;
+
+export type KtxNotionConnectionConfig = Omit<
+  RawKtxNotionConnectionConfig,
+  | 'auth_token'
+  | 'auth_token_ref'
+  | 'crawl_mode'
+  | 'root_page_ids'
+  | 'root_database_ids'
+  | 'root_data_source_ids'
+  | 'max_pages_per_run'
+  | 'max_knowledge_creates_per_run'
+  | 'max_knowledge_updates_per_run'
+> & {
+  driver: 'notion';
+  auth_token: string | null;
+  auth_token_ref: string | null;
+  crawl_mode: KtxNotionCrawlMode;
+  root_page_ids: string[];
+  root_database_ids: string[];
+  root_data_source_ids: string[];
+  max_pages_per_run: number;
+  max_knowledge_creates_per_run: number;
+  max_knowledge_updates_per_run: number;
+};
+
+/** @internal */
+export interface RedactedKtxNotionConnectionConfig {
+  driver: 'notion';
+  hasAuthToken: boolean;
+  crawlMode: KtxNotionCrawlMode;
+  rootPageIds: string[];
+  rootDatabaseIds: string[];
+  rootDataSourceIds: string[];
+  maxPagesPerRun: number;
+  maxKnowledgeCreatesPerRun: number;
+  maxKnowledgeUpdatesPerRun: number;
+  warning: typeof KTX_NOTION_ORG_KNOWLEDGE_WARNING;
+}
+
+interface ResolveNotionTokenOptions {
+  env?: Record<string, string | undefined>;
+  readTextFile?: (path: string) => Promise<string>;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function record(value: unknown): Record<string, unknown> {
+  if (!isRecord(value)) {
+    throw new Error('Notion connection config must be an object');
+  }
+  return value;
+}
+
+function stringValue(value: unknown, fallback: string): string {
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : fallback;
+}
+
+function optionalString(value: unknown): string | null {
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
+}
+
+function stringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.filter((item): item is string => typeof item === 'string' && item.trim().length > 0);
+}
+
+function integerWithFallback(value: unknown, fallback: number, name: string): number {
+  if (value === undefined || value === null) {
+    return fallback;
+  }
+  if (typeof value !== 'number' || !Number.isInteger(value)) {
+    throw new Error(`${name} must be an integer`);
+  }
+  return value;
+}
+
+function boundedInteger(value: unknown, fallback: number, name: string, min: number, max: number): number {
+  const parsed = integerWithFallback(value, fallback, name);
+  if (parsed < min || parsed > max) {
+    throw new Error(`${name} must be between ${min} and ${max}`);
+  }
+  return parsed;
+}
+
+export function parseNotionConnectionConfig(raw: unknown): KtxNotionConnectionConfig {
+  const input = record(raw);
+  if (input.driver !== 'notion') {
+    throw new Error('Notion connection config requires driver: notion');
+  }
+  const authToken = optionalString(input.auth_token);
+  const authTokenRef = optionalString(input.auth_token_ref);
+  if (!authToken && !authTokenRef) {
+    throw new Error('Notion connection config requires auth_token or auth_token_ref');
+  }
+  if (authTokenRef && !authTokenRef.startsWith('env:') && !authTokenRef.startsWith('file:')) {
+    throw new Error('Notion auth_token_ref must use env:NAME or file:/path');
+  }
+
+  const crawlMode = stringValue(input.crawl_mode, 'selected_roots');
+  if (crawlMode !== 'selected_roots' && crawlMode !== 'all_accessible') {
+    throw new Error(`Unsupported Notion crawl_mode: ${crawlMode}`);
+  }
+  const rootPageIds = stringArray(input.root_page_ids);
+  const rootDatabaseIds = stringArray(input.root_database_ids);
+  const rootDataSourceIds = stringArray(input.root_data_source_ids);
+  if (crawlMode === 'selected_roots' && rootPageIds.length + rootDatabaseIds.length + rootDataSourceIds.length === 0) {
+    throw new Error('selected_roots requires at least one root page, database, or data source id');
+  }
+
+  return {
+    driver: 'notion',
+    auth_token: authToken,
+    auth_token_ref: authTokenRef,
+    crawl_mode: crawlMode,
+    root_page_ids: rootPageIds,
+    root_database_ids: rootDatabaseIds,
+    root_data_source_ids: rootDataSourceIds,
+    max_pages_per_run: boundedInteger(input.max_pages_per_run, 1000, 'max_pages_per_run', 1, 10_000),
+    max_knowledge_creates_per_run: boundedInteger(
+      input.max_knowledge_creates_per_run,
+      NOTION_DEFAULT_MAX_KNOWLEDGE_CREATES_PER_RUN,
+      'max_knowledge_creates_per_run',
+      0,
+      25,
+    ),
+    max_knowledge_updates_per_run: boundedInteger(
+      input.max_knowledge_updates_per_run,
+      20,
+      'max_knowledge_updates_per_run',
+      0,
+      100,
+    ),
+  };
+}
+
+/** @internal */
+export function redactNotionConnectionConfig(config: KtxNotionConnectionConfig): RedactedKtxNotionConnectionConfig {
+  return {
+    driver: 'notion',
+    hasAuthToken: Boolean(config.auth_token ?? config.auth_token_ref),
+    crawlMode: config.crawl_mode,
+    rootPageIds: config.root_page_ids,
+    rootDatabaseIds: config.root_database_ids,
+    rootDataSourceIds: config.root_data_source_ids,
+    maxPagesPerRun: config.max_pages_per_run,
+    maxKnowledgeCreatesPerRun: config.max_knowledge_creates_per_run,
+    maxKnowledgeUpdatesPerRun: config.max_knowledge_updates_per_run,
+    warning: KTX_NOTION_ORG_KNOWLEDGE_WARNING,
+  };
+}
+
+function expandHome(path: string): string {
+  return path === '~' || path.startsWith('~/') ? resolve(homedir(), path.slice(2)) : path;
+}
+
+/** @internal */
+export async function resolveNotionAuthToken(
+  authTokenRef: string,
+  options: ResolveNotionTokenOptions = {},
+): Promise<string> {
+  if (authTokenRef.startsWith('env:')) {
+    const envName = authTokenRef.slice('env:'.length);
+    const value = (options.env ?? process.env)[envName];
+    if (!value) {
+      throw new Error(`Notion token environment variable ${envName} is not set`);
+    }
+    return value.trim();
+  }
+  if (authTokenRef.startsWith('file:')) {
+    const path = expandHome(authTokenRef.slice('file:'.length));
+    const readTextFile = options.readTextFile ?? ((filePath: string) => readFile(filePath, 'utf-8'));
+    const value = (await readTextFile(path)).trim();
+    if (!value) {
+      throw new Error(`Notion token file is empty: ${path}`);
+    }
+    return value;
+  }
+  throw new Error('Notion auth_token_ref must use env:NAME or file:/path');
+}
+
+export async function resolveNotionConnectionAuthToken(
+  config: Pick<KtxNotionConnectionConfig, 'auth_token' | 'auth_token_ref'>,
+  options: ResolveNotionTokenOptions = {},
+): Promise<string> {
+  return config.auth_token ?? (await resolveNotionAuthToken(config.auth_token_ref ?? '', options));
+}
+
+export async function notionConnectionToPullConfig(
+  config: KtxNotionConnectionConfig,
+  options: ResolveNotionTokenOptions = {},
+): Promise<NotionPullConfig> {
+  const authToken = await resolveNotionConnectionAuthToken(config, options);
+  return notionPullConfigSchema.parse({
+    authToken,
+    crawlMode: config.crawl_mode,
+    rootPageIds: config.root_page_ids,
+    rootDatabaseIds: config.root_database_ids,
+    rootDataSourceIds: config.root_data_source_ids,
+    maxPagesPerRun: config.max_pages_per_run,
+    maxKnowledgeCreatesPerRun: config.max_knowledge_creates_per_run,
+    maxKnowledgeUpdatesPerRun: config.max_knowledge_updates_per_run,
+    lastSuccessfulCursor: null,
+  });
+}

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

@@ -0,0 +1,103 @@
+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/postgres-query-executor.ts

@@ -0,0 +1,78 @@
+import { Client, type ClientConfig } from 'pg';
+import type {
+  KtxSqlQueryExecutionInput,
+  KtxSqlQueryExecutionResult,
+  KtxSqlQueryExecutorPort,
+} from './query-executor.js';
+import { limitSqlForExecution } from './read-only-sql.js';
+
+interface PgClientLike {
+  connect(): Promise<unknown>;
+  query(input: string | { text: string; rowMode: 'array' }): Promise<{
+    fields: Array<{ name: string }>;
+    rows: unknown[][];
+    command: string;
+    rowCount: number | null;
+  }>;
+  end(): Promise<void>;
+}
+
+interface PostgresQueryExecutorOptions {
+  statementTimeoutMs?: number;
+  queryTimeoutMs?: number;
+  connectionTimeoutMs?: number;
+  clientFactory?: (config: ClientConfig) => PgClientLike;
+}
+
+function connectionDriver(input: KtxSqlQueryExecutionInput): string {
+  return String(input.connection?.driver ?? '').toLowerCase();
+}
+
+function createDefaultClient(config: ClientConfig): PgClientLike {
+  return new Client(config);
+}
+
+export function createPostgresQueryExecutor(options: PostgresQueryExecutorOptions = {}): KtxSqlQueryExecutorPort {
+  const clientFactory = options.clientFactory ?? createDefaultClient;
+  return {
+    async execute(input: KtxSqlQueryExecutionInput): Promise<KtxSqlQueryExecutionResult> {
+      const driver = connectionDriver(input);
+      const connection = input.connection;
+      if (driver !== 'postgres' && driver !== 'postgresql') {
+        throw new Error(`Local Postgres execution cannot run driver "${connection?.driver ?? 'unknown'}".`);
+      }
+      if (typeof connection?.url !== 'string' || connection.url.trim().length === 0) {
+        throw new Error(`Local Postgres execution requires connections.${input.connectionId}.url.`);
+      }
+
+      const client = clientFactory({
+        connectionString: connection.url,
+        statement_timeout: options.statementTimeoutMs ?? 30_000,
+        query_timeout: options.queryTimeoutMs ?? 35_000,
+        connectionTimeoutMillis: options.connectionTimeoutMs ?? 5_000,
+        application_name: 'ktx-local-query',
+      });
+      await client.connect();
+      try {
+        await client.query('BEGIN READ ONLY');
+        const result = await client.query({
+          text: limitSqlForExecution(input.sql, input.maxRows),
+          rowMode: 'array',
+        });
+        await client.query('COMMIT');
+        return {
+          headers: result.fields.map((field) => field.name),
+          rows: result.rows,
+          totalRows: result.rows.length,
+          command: result.command,
+          rowCount: result.rowCount,
+        };
+      } catch (error) {
+        await client.query('ROLLBACK').catch(() => undefined);
+        throw error;
+      } finally {
+        await client.end();
+      }
+    },
+  };
+}

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

@@ -0,0 +1,25 @@
+import type { KtxProjectConnectionConfig } from '../../context/project/config.js';
+
+export interface KtxSqlQueryExecutionInput {
+  connectionId: string;
+  projectDir?: string;
+  connection: KtxProjectConnectionConfig | undefined;
+  sql: string;
+  maxRows?: number;
+}
+
+export interface KtxSqlQueryExecutionResult {
+  headers: string[];
+  rows: unknown[][];
+  totalRows: number;
+  command: string;
+  rowCount: number | null;
+}
+
+export interface KtxSqlQueryExecutorPort {
+  execute(input: KtxSqlQueryExecutionInput): Promise<KtxSqlQueryExecutionResult>;
+}
+
+export function normalizeQueryRows(rows: unknown[]): unknown[][] {
+  return rows.map((row) => (Array.isArray(row) ? row : Object.values(row as Record<string, unknown>)));
+}

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

@@ -0,0 +1,30 @@
+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/read-only-sql.ts

@@ -0,0 +1,22 @@
+const MUTATING_SQL =
+  /^\s*(insert|update|delete|merge|alter|drop|create|truncate|grant|revoke|copy|call|do|vacuum|analyze|refresh)\b/i;
+const READ_SQL = /^\s*(select|with)\b/i;
+
+export function assertReadOnlySql(sql: string): string {
+  const trimmed = sql.trim();
+  if (!READ_SQL.test(trimmed) || MUTATING_SQL.test(trimmed)) {
+    throw new Error('Only read-only SELECT/WITH queries can be executed locally.');
+  }
+  return trimmed;
+}
+
+export function limitSqlForExecution(sql: string, maxRows: number | undefined): string {
+  const trimmed = assertReadOnlySql(sql).replace(/;+\s*$/, '');
+  if (!maxRows) {
+    return trimmed;
+  }
+  if (!Number.isInteger(maxRows) || maxRows <= 0) {
+    throw new Error('maxRows must be a positive integer.');
+  }
+  return `select * from (${trimmed}) as ktx_query_result limit ${maxRows}`;
+}

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

@@ -0,0 +1,139 @@
+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');
+  });
+});

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

@@ -0,0 +1,92 @@
+import { isAbsolute, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import Database from 'better-sqlite3';
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import type {
+  KtxSqlQueryExecutionInput,
+  KtxSqlQueryExecutionResult,
+  KtxSqlQueryExecutorPort,
+} from './query-executor.js';
+import { normalizeQueryRows } from './query-executor.js';
+import { limitSqlForExecution } from './read-only-sql.js';
+
+type SqliteConnectionConfig = Record<string, unknown> | undefined;
+
+function connectionDriver(input: KtxSqlQueryExecutionInput): string {
+  return String(input.connection?.driver ?? '').toLowerCase();
+}
+
+function stringConfigValue(connection: SqliteConnectionConfig, key: string): string | undefined {
+  const value = connection?.[key];
+  return typeof value === 'string' && value.trim().length > 0 ? resolveStringReference(key, value.trim()) : undefined;
+}
+
+function resolveStringReference(key: string, value: string): string {
+  if (value.startsWith('env:')) {
+    return process.env[value.slice('env:'.length)] ?? '';
+  }
+  if (key !== 'url' && value.startsWith('file:')) {
+    const rawPath = value.slice('file:'.length);
+    const path = rawPath.startsWith('~') ? resolve(homedir(), rawPath.slice(1)) : rawPath;
+    return readFileSync(path, 'utf-8').trim();
+  }
+  return value;
+}
+
+function sqlitePathFromUrl(url: string): string {
+  if (url.startsWith('file:')) {
+    return fileURLToPath(url);
+  }
+
+  if (url.startsWith('sqlite:')) {
+    const parsed = new URL(url);
+    if (parsed.pathname.length > 0) {
+      return decodeURIComponent(parsed.pathname);
+    }
+  }
+
+  return url;
+}
+
+/** @internal */
+export function sqliteDatabasePathFromConnection(input: KtxSqlQueryExecutionInput): string {
+  const driver = connectionDriver(input);
+  if (driver !== 'sqlite' && driver !== 'sqlite3') {
+    throw new Error(`Local SQLite execution cannot run driver "${input.connection?.driver ?? 'unknown'}".`);
+  }
+
+  const pathValue = stringConfigValue(input.connection, 'path');
+  const urlValue = stringConfigValue(input.connection, 'url');
+  if (!pathValue && !urlValue) {
+    throw new Error(
+      `Local SQLite execution requires connections.${input.connectionId}.path or connections.${input.connectionId}.url.`,
+    );
+  }
+
+  const candidate = pathValue ?? sqlitePathFromUrl(urlValue as string);
+  return isAbsolute(candidate) ? candidate : resolve(input.projectDir ?? process.cwd(), candidate);
+}
+
+export function createSqliteQueryExecutor(): KtxSqlQueryExecutorPort {
+  return {
+    async execute(input: KtxSqlQueryExecutionInput): Promise<KtxSqlQueryExecutionResult> {
+      const sql = limitSqlForExecution(input.sql, input.maxRows);
+      const dbPath = sqliteDatabasePathFromConnection(input);
+      const db = new Database(dbPath, { readonly: true, fileMustExist: true });
+      try {
+        const statement = db.prepare(sql);
+        const rows = statement.all() as unknown[];
+        return {
+          headers: statement.columns().map((column) => column.name),
+          rows: normalizeQueryRows(rows),
+          totalRows: rows.length,
+          command: 'SELECT',
+          rowCount: rows.length,
+        };
+      } finally {
+        db.close();
+      }
+    },
+  };
+}