Initial open-source release

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

@@ -0,0 +1,28 @@
+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',
+  'POSTHOG',
+  'MYSQL',
+  'CLICKHOUSE',
+  'PLAIN',
+  'BETTERSTACK',
+]);
+
+export type ConnectionType = z.infer<typeof connectionTypeSchema>;

packages/context/src/connections/index.ts

@@ -0,0 +1,27 @@
+export type {
+  KloSqlQueryExecutionInput,
+  KloSqlQueryExecutionResult,
+  KloSqlQueryExecutorPort,
+} from './query-executor.js';
+export { createDefaultLocalQueryExecutor, type DefaultLocalQueryExecutorOptions } from './local-query-executor.js';
+export { normalizeQueryRows } from './query-executor.js';
+export { createPostgresQueryExecutor } from './postgres-query-executor.js';
+export { assertReadOnlySql, limitSqlForExecution } from './read-only-sql.js';
+export { createSqliteQueryExecutor, sqliteDatabasePathFromConnection } from './sqlite-query-executor.js';
+export { connectionTypeSchema, type ConnectionType } from './connection-type.js';
+export {
+  localConnectionInfoFromConfig,
+  localConnectionToWarehouseDescriptor,
+  localConnectionTypeForConfig,
+  type LocalConnectionInfo,
+  type LocalWarehouseDescriptor,
+} from './local-warehouse-descriptor.js';
+export {
+  KLO_NOTION_ORG_KNOWLEDGE_WARNING,
+  notionConnectionToPullConfig,
+  parseNotionConnectionConfig,
+  redactNotionConnectionConfig,
+  resolveNotionAuthToken,
+  type KloNotionConnectionConfig,
+  type RedactedKloNotionConnectionConfig,
+} from './notion-config.js';

packages/context/src/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', readonly: true },
+        sql: 'select 1',
+      }),
+    ).resolves.toMatchObject({ headers: ['pg'] });
+    await expect(
+      executor.execute({
+        connectionId: 'local',
+        connection: { driver: 'sqlite', readonly: true },
+        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', readonly: true },
+        sql: 'select 1',
+      }),
+    ).rejects.toThrow('No local query executor is configured for driver "snowflake".');
+  });
+});

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

@@ -0,0 +1,34 @@
+import { createPostgresQueryExecutor } from './postgres-query-executor.js';
+import type {
+  KloSqlQueryExecutionInput,
+  KloSqlQueryExecutionResult,
+  KloSqlQueryExecutorPort,
+} from './query-executor.js';
+import { createSqliteQueryExecutor } from './sqlite-query-executor.js';
+
+export interface DefaultLocalQueryExecutorOptions {
+  postgres?: KloSqlQueryExecutorPort;
+  sqlite?: KloSqlQueryExecutorPort;
+}
+
+function driverFor(input: KloSqlQueryExecutionInput): string {
+  return String(input.connection?.driver ?? '').toLowerCase();
+}
+
+export function createDefaultLocalQueryExecutor(options: DefaultLocalQueryExecutorOptions = {}): KloSqlQueryExecutorPort {
+  const postgres = options.postgres ?? createPostgresQueryExecutor();
+  const sqlite = options.sqlite ?? createSqliteQueryExecutor();
+
+  return {
+    async execute(input: KloSqlQueryExecutionInput): Promise<KloSqlQueryExecutionResult> {
+      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/context/src/connections/local-warehouse-descriptor.test.ts

@@ -0,0 +1,63 @@
+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' })).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' })).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/context/src/connections/local-warehouse-descriptor.ts

@@ -0,0 +1,102 @@
+import type { KloProjectConnectionConfig } 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: KloProjectConnectionConfig | 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: KloProjectConnectionConfig | 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: KloProjectConnectionConfig | 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/context/src/connections/notion-config.test.ts

@@ -0,0 +1,120 @@
+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(), 'klo-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_AUTH_TOKEN',
+      crawl_mode: 'selected_roots',
+      root_page_ids: ['page-1'],
+    });
+
+    expect(parsed).toEqual({
+      driver: 'notion',
+      auth_token_ref: 'env:NOTION_AUTH_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: 5,
+      max_knowledge_updates_per_run: 20,
+      last_successful_cursor: null,
+    });
+  });
+
+  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: 5,
+      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_AUTH_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_AUTH_TOKEN', {
+        env: { NOTION_AUTH_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_AUTH_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_AUTH_TOKEN: 'ntn_env_token' } },
+    );
+
+    expect(pullConfig).toEqual({
+      authToken: 'ntn_env_token',
+      crawlMode: 'all_accessible',
+      rootPageIds: [],
+      rootDatabaseIds: [],
+      rootDataSourceIds: [],
+      maxPagesPerRun: 12,
+      maxKnowledgeCreatesPerRun: 2,
+      maxKnowledgeUpdatesPerRun: 7,
+      lastSuccessfulCursor: '{"phase":"all_accessible_pages","cursor":"cursor-1"}',
+    });
+  });
+});

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

@@ -0,0 +1,196 @@
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+import { type NotionPullConfig, notionPullConfigSchema } from '../ingest/adapters/notion/types.js';
+import type { KloProjectConnectionConfig } from '../project/config.js';
+
+export const KLO_NOTION_ORG_KNOWLEDGE_WARNING =
+  'Anything accessible to this Notion integration can become organization knowledge.';
+
+type KloNotionCrawlMode = 'all_accessible' | 'selected_roots';
+
+export interface KloNotionConnectionConfig extends KloProjectConnectionConfig {
+  driver: 'notion';
+  auth_token_ref: string;
+  crawl_mode: KloNotionCrawlMode;
+  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;
+  last_successful_cursor: string | null;
+}
+
+export interface RedactedKloNotionConnectionConfig {
+  driver: 'notion';
+  hasAuthToken: boolean;
+  crawlMode: KloNotionCrawlMode;
+  rootPageIds: string[];
+  rootDatabaseIds: string[];
+  rootDataSourceIds: string[];
+  maxPagesPerRun: number;
+  maxKnowledgeCreatesPerRun: number;
+  maxKnowledgeUpdatesPerRun: number;
+  warning: typeof KLO_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): KloNotionConnectionConfig {
+  const input = record(raw);
+  if (input.driver !== 'notion') {
+    throw new Error('Notion connection config requires driver: notion');
+  }
+  const authTokenRef = stringValue(input.auth_token_ref, '');
+  if (!authTokenRef) {
+    throw new Error('Notion connection config requires auth_token_ref');
+  }
+  if (!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 {
+    ...input,
+    driver: 'notion',
+    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,
+      5,
+      '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,
+    ),
+    last_successful_cursor: optionalString(input.last_successful_cursor),
+  };
+}
+
+export function redactNotionConnectionConfig(config: KloNotionConnectionConfig): RedactedKloNotionConnectionConfig {
+  return {
+    driver: 'notion',
+    hasAuthToken: Boolean(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: KLO_NOTION_ORG_KNOWLEDGE_WARNING,
+  };
+}
+
+function expandHome(path: string): string {
+  return path === '~' || path.startsWith('~/') ? resolve(homedir(), path.slice(2)) : path;
+}
+
+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 notionConnectionToPullConfig(
+  config: KloNotionConnectionConfig,
+  options: ResolveNotionTokenOptions = {},
+): Promise<NotionPullConfig> {
+  return notionPullConfigSchema.parse({
+    authToken: await resolveNotionAuthToken(config.auth_token_ref, options),
+    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: config.last_successful_cursor,
+  });
+}

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

@@ -0,0 +1,111 @@
+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', readonly: true },
+      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 klo_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', readonly: true },
+        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 and read-only connection config', async () => {
+    const executor = createPostgresQueryExecutor({ clientFactory: vi.fn() });
+
+    await expect(
+      executor.execute({
+        connectionId: 'warehouse',
+        connection: { driver: 'postgres', readonly: true },
+        sql: 'select 1',
+      }),
+    ).rejects.toThrow('Local Postgres execution requires connections.warehouse.url');
+
+    await expect(
+      executor.execute({
+        connectionId: 'warehouse',
+        connection: { driver: 'postgres', url: 'postgres://example/db', readonly: false },
+        sql: 'select 1',
+      }),
+    ).rejects.toThrow('Local query execution requires connections.warehouse.readonly: true');
+  });
+});

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

@@ -0,0 +1,80 @@
+import { Client, type ClientConfig } from 'pg';
+import type {
+  KloSqlQueryExecutionInput,
+  KloSqlQueryExecutionResult,
+  KloSqlQueryExecutorPort,
+} 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: KloSqlQueryExecutionInput): string {
+  return String(input.connection?.driver ?? '').toLowerCase();
+}
+
+function createDefaultClient(config: ClientConfig): PgClientLike {
+  return new Client(config);
+}
+
+export function createPostgresQueryExecutor(options: PostgresQueryExecutorOptions = {}): KloSqlQueryExecutorPort {
+  const clientFactory = options.clientFactory ?? createDefaultClient;
+  return {
+    async execute(input: KloSqlQueryExecutionInput): Promise<KloSqlQueryExecutionResult> {
+      const driver = connectionDriver(input);
+      if (driver !== 'postgres' && driver !== 'postgresql') {
+        throw new Error(`Local Postgres execution cannot run driver "${input.connection?.driver ?? 'unknown'}".`);
+      }
+      if (input.connection?.readonly !== true) {
+        throw new Error(`Local query execution requires connections.${input.connectionId}.readonly: true.`);
+      }
+      if (typeof input.connection.url !== 'string' || input.connection.url.trim().length === 0) {
+        throw new Error(`Local Postgres execution requires connections.${input.connectionId}.url.`);
+      }
+
+      const client = clientFactory({
+        connectionString: input.connection.url,
+        statement_timeout: options.statementTimeoutMs ?? 30_000,
+        query_timeout: options.queryTimeoutMs ?? 35_000,
+        connectionTimeoutMillis: options.connectionTimeoutMs ?? 5_000,
+        application_name: 'klo-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/context/src/connections/query-executor.ts

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

packages/context/src/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 klo_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/context/src/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 klo_query_result limit ${maxRows}`;
+}

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

@@ -0,0 +1,148 @@
+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(), 'klo-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', readonly: true },
+      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}`, readonly: true },
+        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}`, readonly: true },
+        sql: 'select 1',
+      }),
+    ).toBe(dbPath);
+  });
+
+  it('resolves env references for SQLite database urls', async () => {
+    const originalDatabaseUrl = process.env.KLO_SQLITE_TEST_URL;
+    process.env.KLO_SQLITE_TEST_URL = `sqlite:${dbPath}`;
+
+    try {
+      expect(
+        sqliteDatabasePathFromConnection({
+          connectionId: 'warehouse',
+          projectDir: tempDir,
+          connection: { driver: 'sqlite', url: 'env:KLO_SQLITE_TEST_URL', readonly: true },
+          sql: 'select 1',
+        }),
+      ).toBe(dbPath);
+    } finally {
+      if (originalDatabaseUrl === undefined) {
+        delete process.env.KLO_SQLITE_TEST_URL;
+      } else {
+        process.env.KLO_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', readonly: true },
+        sql: 'delete from orders',
+      }),
+    ).rejects.toThrow('Only read-only SELECT/WITH queries can be executed locally');
+  });
+
+  it('requires a SQLite driver, read-only config, and a database path', async () => {
+    const executor = createSqliteQueryExecutor();
+
+    await expect(
+      executor.execute({
+        connectionId: 'warehouse',
+        projectDir: tempDir,
+        connection: { driver: 'postgres', path: 'warehouse.db', readonly: true },
+        sql: 'select 1',
+      }),
+    ).rejects.toThrow('Local SQLite execution cannot run driver "postgres"');
+
+    await expect(
+      executor.execute({
+        connectionId: 'warehouse',
+        projectDir: tempDir,
+        connection: { driver: 'sqlite', path: 'warehouse.db', readonly: false },
+        sql: 'select 1',
+      }),
+    ).rejects.toThrow('Local query execution requires connections.warehouse.readonly: true');
+
+    await expect(
+      executor.execute({
+        connectionId: 'warehouse',
+        projectDir: tempDir,
+        connection: { driver: 'sqlite', readonly: true },
+        sql: 'select 1',
+      }),
+    ).rejects.toThrow('Local SQLite execution requires connections.warehouse.path or connections.warehouse.url');
+  });
+});

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

@@ -0,0 +1,94 @@
+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 {
+  KloSqlQueryExecutionInput,
+  KloSqlQueryExecutionResult,
+  KloSqlQueryExecutorPort,
+} 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: KloSqlQueryExecutionInput): 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;
+}
+
+export function sqliteDatabasePathFromConnection(input: KloSqlQueryExecutionInput): string {
+  const driver = connectionDriver(input);
+  if (driver !== 'sqlite' && driver !== 'sqlite3') {
+    throw new Error(`Local SQLite execution cannot run driver "${input.connection?.driver ?? 'unknown'}".`);
+  }
+  if (input.connection?.readonly !== true) {
+    throw new Error(`Local query execution requires connections.${input.connectionId}.readonly: true.`);
+  }
+
+  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(): KloSqlQueryExecutorPort {
+  return {
+    async execute(input: KloSqlQueryExecutionInput): Promise<KloSqlQueryExecutionResult> {
+      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();
+      }
+    },
+  };
+}