@kaelio/ktx 0.4.0 → 0.5.0

package/dist/connectors/sqlserver/connector.test.js

@@ -0,0 +1,313 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createSqlServerLiveDatabaseIntrospection } from '../../connectors/sqlserver/live-database-introspection.js';
+import { isKtxSqlServerConnectionConfig, KtxSqlServerScanConnector, sqlServerConnectionPoolConfigFromConfig } from '../../connectors/sqlserver/connector.js';
+import { tableRefSet } from '../../context/scan/table-ref.js';
+function recordset(rows, columnNames) {
+    const withColumns = rows;
+    withColumns.columns = Object.fromEntries(columnNames.map((name) => [name, { type: { declaration: 'nvarchar' } }]));
+    return withColumns;
+}
+function result(rows, columnNames) {
+    return { recordset: recordset(rows, columnNames) };
+}
+function fakePoolFactory() {
+    const query = vi.fn(async (sql) => {
+        if (sql.includes('INFORMATION_SCHEMA.TABLES')) {
+            return result([
+                { table_name: 'customers', table_type: 'BASE TABLE' },
+                { table_name: 'orders', table_type: 'BASE TABLE' },
+                { table_name: 'order_summary', table_type: 'VIEW' },
+            ], ['table_name', 'table_type']);
+        }
+        if (sql.includes("ep.name = 'MS_Description'") && sql.includes('ep.minor_id = 0')) {
+            return result([{ table_name: 'customers', table_comment: 'Customer table' }], [
+                'table_name',
+                'table_comment',
+            ]);
+        }
+        if (sql.includes("ep.name = 'MS_Description'") && sql.includes('ep.minor_id = c.column_id')) {
+            return result([{ table_name: 'customers', column_name: 'id', column_comment: 'PK' }], [
+                'table_name',
+                'column_name',
+                'column_comment',
+            ]);
+        }
+        if (sql.includes('INFORMATION_SCHEMA.COLUMNS')) {
+            return result([
+                { table_name: 'customers', column_name: 'id', data_type: 'int', is_nullable: 'NO' },
+                { table_name: 'customers', column_name: 'name', data_type: 'nvarchar', is_nullable: 'NO' },
+                { table_name: 'orders', column_name: 'id', data_type: 'int', is_nullable: 'NO' },
+                { table_name: 'orders', column_name: 'customer_id', data_type: 'int', is_nullable: 'NO' },
+                { table_name: 'orders', column_name: 'status', data_type: 'nvarchar', is_nullable: 'YES' },
+                { table_name: 'order_summary', column_name: 'status', data_type: 'nvarchar', is_nullable: 'YES' },
+            ], ['table_name', 'column_name', 'data_type', 'is_nullable']);
+        }
+        if (sql.includes("CONSTRAINT_TYPE = 'PRIMARY KEY'")) {
+            return result([
+                { table_name: 'customers', column_name: 'id' },
+                { table_name: 'orders', column_name: 'id' },
+            ], ['table_name', 'column_name']);
+        }
+        if (sql.includes('REFERENTIAL_CONSTRAINTS')) {
+            return result([
+                {
+                    table_name: 'orders',
+                    column_name: 'customer_id',
+                    referenced_table_schema: 'dbo',
+                    referenced_table_name: 'customers',
+                    referenced_column_name: 'id',
+                    constraint_name: 'orders_customer_id_fk',
+                },
+            ], [
+                'table_name',
+                'column_name',
+                'referenced_table_schema',
+                'referenced_table_name',
+                'referenced_column_name',
+                'constraint_name',
+            ]);
+        }
+        if (sql.includes('sys.partitions') && sql.includes('GROUP BY t.name')) {
+            return result([
+                { table_name: 'customers', row_count: 2 },
+                { table_name: 'orders', row_count: 2 },
+            ], ['table_name', 'row_count']);
+        }
+        if (sql.includes('SELECT TOP 1 [id], [status] FROM [dbo].[orders]')) {
+            return result([{ id: 10, status: 'paid' }], ['id', 'status']);
+        }
+        if (sql.includes('SELECT TOP 1 * FROM (select id, status from dbo.orders) AS ktx_query_result')) {
+            return result([{ id: 10, status: 'paid' }], ['id', 'status']);
+        }
+        if (sql.includes('SELECT TOP 5 [status] FROM [dbo].[orders]')) {
+            return result([{ status: 'paid' }, { status: 'open' }], ['status']);
+        }
+        if (sql.includes('COUNT(DISTINCT val)')) {
+            return result([{ cardinality: 2 }], ['cardinality']);
+        }
+        if (sql.includes('SELECT TOP 10 val')) {
+            return result([{ val: 'open' }, { val: 'paid' }], ['val']);
+        }
+        if (sql.includes('SUM(p.rows) AS row_count') && sql.includes('t.name = @tableName')) {
+            return result([{ row_count: 2 }], ['row_count']);
+        }
+        if (sql.includes('SELECT s.name AS schema_name')) {
+            return result([{ schema_name: 'dbo' }, { schema_name: 'sales' }], ['schema_name']);
+        }
+        if (sql.trim() === 'SELECT 1') {
+            return result([{ ok: 1 }], ['ok']);
+        }
+        throw new Error(`Unexpected SQL: ${sql}`);
+    });
+    const request = {
+        input: vi.fn((_key, _value) => request),
+        query,
+    };
+    const close = vi.fn(async () => undefined);
+    return {
+        createPool: vi.fn(async () => ({
+            request: () => request,
+            close,
+        })),
+    };
+}
+describe('KtxSqlServerScanConnector', () => {
+    it('resolves SQL Server connection configuration safely', () => {
+        expect(isKtxSqlServerConnectionConfig({
+            driver: 'sqlserver',
+            host: 'localhost',
+            database: 'analytics',
+        })).toBe(true);
+        expect(isKtxSqlServerConnectionConfig({ driver: 'mysql', host: 'localhost', database: 'analytics' })).toBe(false);
+        expect(sqlServerConnectionPoolConfigFromConfig({
+            connectionId: 'warehouse',
+            connection: {
+                driver: 'sqlserver',
+                host: 'db.example.test',
+                port: 14330,
+                database: 'analytics',
+                username: 'reader',
+                trustServerCertificate: false,
+            },
+        })).toMatchObject({
+            server: 'db.example.test',
+            port: 14330,
+            database: 'analytics',
+            user: 'reader',
+            options: { encrypt: true, trustServerCertificate: false },
+        });
+    });
+    it('introspects schema, primary keys, comments, row counts, views, and foreign keys', async () => {
+        const connector = new KtxSqlServerScanConnector({
+            connectionId: 'warehouse',
+            connection: {
+                driver: 'sqlserver',
+                host: 'db.example.test',
+                database: 'analytics',
+                username: 'reader',
+                schema: 'dbo',
+            },
+            poolFactory: fakePoolFactory(),
+            now: () => new Date('2026-04-29T16:00:00.000Z'),
+        });
+        const snapshot = await connector.introspect({ connectionId: 'warehouse', driver: 'sqlserver' }, { runId: 'scan-run-1' });
+        expect(snapshot).toMatchObject({
+            connectionId: 'warehouse',
+            driver: 'sqlserver',
+            extractedAt: '2026-04-29T16:00:00.000Z',
+            scope: { catalogs: ['analytics'], schemas: ['dbo'] },
+            metadata: {
+                database: 'analytics',
+                host: 'db.example.test',
+                schemas: ['dbo'],
+                table_count: 3,
+                total_columns: 6,
+            },
+        });
+        expect(snapshot.tables.map((table) => [table.name, table.kind, table.estimatedRows, table.comment])).toEqual([
+            ['customers', 'table', 2, 'Customer table'],
+            ['orders', 'table', 2, null],
+            ['order_summary', 'view', null, null],
+        ]);
+        expect(snapshot.tables.find((table) => table.name === 'customers')?.columns[0]).toMatchObject({
+            name: 'id',
+            nativeType: 'int',
+            normalizedType: 'int',
+            dimensionType: 'number',
+            nullable: false,
+            primaryKey: true,
+            comment: 'PK',
+        });
+        expect(snapshot.tables.find((table) => table.name === 'orders')?.foreignKeys).toEqual([
+            {
+                fromColumn: 'customer_id',
+                toCatalog: 'analytics',
+                toDb: 'dbo',
+                toTable: 'customers',
+                toColumn: 'id',
+                constraintName: 'orders_customer_id_fk',
+            },
+        ]);
+    });
+    it('runs samples, distinct values, read-only SQL, row count, schema list, and cleanup', async () => {
+        const poolFactory = fakePoolFactory();
+        const connector = new KtxSqlServerScanConnector({
+            connectionId: 'warehouse',
+            connection: {
+                driver: 'sqlserver',
+                host: 'db.example.test',
+                database: 'analytics',
+                username: 'reader',
+                schema: 'dbo',
+            },
+            poolFactory,
+        });
+        await expect(connector.sampleTable({
+            connectionId: 'warehouse',
+            table: { catalog: 'analytics', db: 'dbo', name: 'orders' },
+            columns: ['id', 'status'],
+            limit: 1,
+        }, { runId: 'scan-run-1' })).resolves.toEqual({
+            headers: ['id', 'status'],
+            headerTypes: ['nvarchar', 'nvarchar'],
+            rows: [[10, 'paid']],
+            totalRows: 1,
+        });
+        await expect(connector.sampleColumn({ connectionId: 'warehouse', table: { catalog: 'analytics', db: 'dbo', name: 'orders' }, column: 'status', limit: 5 }, { runId: 'scan-run-1' })).resolves.toMatchObject({ values: ['paid', 'open'], nullCount: null, distinctCount: null });
+        await expect(connector.getColumnDistinctValues({ catalog: 'analytics', db: 'dbo', name: 'orders' }, 'status', { maxCardinality: 5, limit: 10, sampleSize: 100 })).resolves.toEqual({ values: ['open', 'paid'], cardinality: 2 });
+        await expect(connector.executeReadOnly({ connectionId: 'warehouse', sql: 'select id, status from dbo.orders', maxRows: 1 }, { runId: 'scan-run-1' })).resolves.toMatchObject({ headers: ['id', 'status'], rows: [[10, 'paid']], totalRows: 1, rowCount: 1 });
+        await expect(connector.executeReadOnly({ connectionId: 'warehouse', sql: 'delete from orders' }, { runId: 'scan-run-1' })).rejects.toThrow('Only read-only SELECT/WITH queries can be executed locally');
+        await expect(connector.getTableRowCount('orders')).resolves.toBe(2);
+        await expect(connector.listSchemas()).resolves.toEqual(['dbo', 'sales']);
+        await expect(connector.columnStats({ connectionId: 'warehouse', table: { catalog: 'analytics', db: 'dbo', name: 'orders' }, column: 'status' }, { runId: 'scan-run-1' })).resolves.toBeNull();
+        await connector.cleanup();
+    });
+    it('limits introspection to tables in tableScope', async () => {
+        const queries = [];
+        const inputs = [];
+        const request = {
+            input: vi.fn((name, value) => {
+                inputs.push({ name, value });
+                return request;
+            }),
+            query: vi.fn(async (sql) => {
+                queries.push(sql);
+                if (sql.includes('INFORMATION_SCHEMA.TABLES')) {
+                    return result([{ table_name: 'orders', table_type: 'BASE TABLE' }], ['table_name', 'table_type']);
+                }
+                if (sql.includes('INFORMATION_SCHEMA.COLUMNS')) {
+                    return result([{ table_name: 'orders', column_name: 'id', data_type: 'int', is_nullable: 'NO' }], ['table_name', 'column_name', 'data_type', 'is_nullable']);
+                }
+                return result([], []);
+            }),
+        };
+        const poolFactory = {
+            createPool: vi.fn(async () => ({
+                request: () => request,
+                close: vi.fn(async () => undefined),
+            })),
+        };
+        const connector = new KtxSqlServerScanConnector({
+            connectionId: 'warehouse',
+            connection: {
+                driver: 'sqlserver',
+                host: 'db.example.test',
+                database: 'analytics',
+                username: 'reader',
+                schema: 'dbo',
+            },
+            poolFactory,
+        });
+        const scope = tableRefSet([{ catalog: 'analytics', db: 'dbo', name: 'orders' }]);
+        const snapshot = await connector.introspect({ connectionId: 'warehouse', driver: 'sqlserver', tableScope: scope }, { runId: 'scope-test' });
+        expect(snapshot.tables.map((table) => table.name)).toEqual(['orders']);
+        expect(queries.find((query) => query.includes('INFORMATION_SCHEMA.TABLES'))).toMatch(/TABLE_NAME IN \(@table_0\)/);
+        expect(inputs).toEqual(expect.arrayContaining([{ name: 'table_0', value: 'orders' }]));
+    });
+    it('adapts native SQL Server snapshots to live-database introspection for local ingest', async () => {
+        const introspection = createSqlServerLiveDatabaseIntrospection({
+            connections: {
+                warehouse: {
+                    driver: 'sqlserver',
+                    host: 'db.example.test',
+                    database: 'analytics',
+                    username: 'reader',
+                    schema: 'dbo',
+                },
+            },
+            poolFactory: fakePoolFactory(),
+            now: () => new Date('2026-04-29T16:00:00.000Z'),
+        });
+        const snapshot = await introspection.extractSchema('warehouse');
+        expect(snapshot).toMatchObject({
+            connectionId: 'warehouse',
+            extractedAt: '2026-04-29T16:00:00.000Z',
+        });
+        expect(snapshot.tables.find((table) => table.name === 'customers')).toMatchObject({
+            name: 'customers',
+            catalog: 'analytics',
+            db: 'dbo',
+            columns: [
+                {
+                    name: 'id',
+                    nativeType: 'int',
+                    normalizedType: 'int',
+                    dimensionType: 'number',
+                    nullable: false,
+                    primaryKey: true,
+                    comment: 'PK',
+                },
+                {
+                    name: 'name',
+                    nativeType: 'nvarchar',
+                    normalizedType: 'nvarchar',
+                    dimensionType: 'string',
+                    nullable: false,
+                    primaryKey: false,
+                    comment: null,
+                },
+            ],
+            foreignKeys: [],
+        });
+    });
+});

package/dist/connectors/sqlserver/dialect.d.ts

@@ -0,0 +1,30 @@
+import type { KtxSchemaDimensionType, KtxTableRef } from '../../context/scan/types.js';
+type SqlServerTableNameRef = Pick<KtxTableRef, 'name'> & Partial<Pick<KtxTableRef, 'catalog' | 'db'>>;
+export declare class KtxSqlServerDialect {
+    readonly type = "sqlserver";
+    private readonly typeMappings;
+    quoteIdentifier(identifier: string): string;
+    formatTableName(table: SqlServerTableNameRef): string;
+    mapDataType(nativeType: string): string;
+    mapToDimensionType(nativeType: string): KtxSchemaDimensionType;
+    generateSampleQuery(tableName: string, limit: number, columns?: string[]): string;
+    generateColumnSampleQuery(tableName: string, columnName: string, limit: number): string;
+    prepareQuery(sql: string, params?: Record<string, unknown>): {
+        sql: string;
+        params?: Record<string, unknown>;
+    };
+    getRandomSampleFilter(samplePct: number): string;
+    getTableSampleClause(samplePct: number): string;
+    getLimitOffsetClause(limit: number, offset?: number): string;
+    getTopClause(limit: number): string;
+    getNullCountExpression(column: string): string;
+    getDistinctCountExpression(column: string): string;
+    generateCardinalitySampleQuery(tableName: string, columnName: string, sampleSize: number): string;
+    generateDistinctValuesQuery(tableName: string, columnName: string, limit: number): string;
+    generateColumnStatisticsQuery(_schemaName: string, _tableName: string): string | null;
+    generateRandomizedCardinalitySampleQuery(tableName: string, columnName: string, sampleSize: number): string;
+    getTimeTruncExpression(column: string, granularity: 'day' | 'week' | 'month' | 'quarter' | 'year', timezone?: string): string;
+    getCustomTimeTruncExpression(column: string, interval: string, origin?: string, timezone?: string): string;
+    parseIntervalToSql(interval: string): string;
+}
+export {};

package/dist/connectors/sqlserver/live-database-introspection.d.ts

@@ -0,0 +1,11 @@
+import type { LiveDatabaseIntrospectionPort } from '../../context/ingest/adapters/live-database/types.js';
+import type { KtxProjectConnectionConfig } from '../../context/project/config.js';
+import { type KtxSqlServerEndpointResolver, type KtxSqlServerPoolFactory } from './connector.js';
+interface CreateSqlServerLiveDatabaseIntrospectionOptions {
+    connections: Record<string, KtxProjectConnectionConfig>;
+    poolFactory?: KtxSqlServerPoolFactory;
+    endpointResolver?: KtxSqlServerEndpointResolver;
+    now?: () => Date;
+}
+export declare function createSqlServerLiveDatabaseIntrospection(options: CreateSqlServerLiveDatabaseIntrospectionOptions): LiveDatabaseIntrospectionPort;
+export {};

package/dist/connectors/sqlserver/live-database-introspection.js

@@ -0,0 +1,25 @@
+import { KtxSqlServerScanConnector, } from './connector.js';
+export function createSqlServerLiveDatabaseIntrospection(options) {
+    return {
+        async extractSchema(connectionId, introspectionOptions) {
+            const connection = options.connections[connectionId];
+            const connector = new KtxSqlServerScanConnector({
+                connectionId,
+                connection,
+                poolFactory: options.poolFactory,
+                endpointResolver: options.endpointResolver,
+                now: options.now,
+            });
+            try {
+                return await connector.introspect({
+                    connectionId,
+                    driver: 'sqlserver',
+                    ...(introspectionOptions?.tableScope ? { tableScope: introspectionOptions.tableScope } : {}),
+                }, { runId: `sqlserver-${connectionId}` });
+            }
+            finally {
+                await connector.cleanup();
+            }
+        },
+    };
+}

package/dist/context/connections/bigquery-identifiers.d.ts

@@ -0,0 +1,2 @@
+export declare function normalizeBigQueryProjectId(value: string, context?: string): string;
+export declare function normalizeBigQueryRegion(value: string, context?: string): string;

package/dist/context/connections/bigquery-identifiers.js

@@ -0,0 +1,15 @@
+const BIGQUERY_PROJECT_ID_PATTERN = /^[A-Za-z0-9_-]+$/;
+const BIGQUERY_REGION_PATTERN = /^[a-z0-9-]+$/;
+export function normalizeBigQueryProjectId(value, context = 'historic-SQL ingest') {
+    if (!BIGQUERY_PROJECT_ID_PATTERN.test(value)) {
+        throw new Error(`Invalid BigQuery project id for ${context}: ${value}`);
+    }
+    return value;
+}
+export function normalizeBigQueryRegion(value, context = 'historic-SQL ingest') {
+    const normalized = value.trim().toLowerCase().replace(/^region-/, '');
+    if (!BIGQUERY_REGION_PATTERN.test(normalized)) {
+        throw new Error(`Invalid BigQuery region for ${context}: ${value}`);
+    }
+    return normalized;
+}

package/dist/context/connections/bigquery-identifiers.test.js

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

package/dist/context/connections/dialects.d.ts

@@ -0,0 +1,10 @@
+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;
+}
+export declare function getDialectForDriver(driver: string): KtxDialect;
+export {};

package/dist/context/connections/notion-config.d.ts

@@ -0,0 +1,44 @@
+import { type NotionPullConfig } from '../ingest/adapters/notion/types.js';
+import type { KtxProjectConnectionConfig } from '../project/config.js';
+declare 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>;
+}
+export declare function parseNotionConnectionConfig(raw: unknown): KtxNotionConnectionConfig;
+/** @internal */
+export declare function redactNotionConnectionConfig(config: KtxNotionConnectionConfig): RedactedKtxNotionConnectionConfig;
+/** @internal */
+export declare function resolveNotionAuthToken(authTokenRef: string, options?: ResolveNotionTokenOptions): Promise<string>;
+export declare function resolveNotionConnectionAuthToken(config: Pick<KtxNotionConnectionConfig, 'auth_token' | 'auth_token_ref'>, options?: ResolveNotionTokenOptions): Promise<string>;
+export declare function notionConnectionToPullConfig(config: KtxNotionConnectionConfig, options?: ResolveNotionTokenOptions): Promise<NotionPullConfig>;
+export {};

package/dist/context/connections/notion-config.js

@@ -0,0 +1,134 @@
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+import { NOTION_DEFAULT_MAX_KNOWLEDGE_CREATES_PER_RUN, notionPullConfigSchema, } from '../ingest/adapters/notion/types.js';
+const KTX_NOTION_ORG_KNOWLEDGE_WARNING = 'Anything accessible to this Notion integration can become organization knowledge.';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function record(value) {
+    if (!isRecord(value)) {
+        throw new Error('Notion connection config must be an object');
+    }
+    return value;
+}
+function stringValue(value, fallback) {
+    return typeof value === 'string' && value.trim().length > 0 ? value.trim() : fallback;
+}
+function optionalString(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
+}
+function stringArray(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((item) => typeof item === 'string' && item.trim().length > 0);
+}
+function integerWithFallback(value, fallback, name) {
+    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, fallback, name, min, max) {
+    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) {
+    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) {
+    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) {
+    return path === '~' || path.startsWith('~/') ? resolve(homedir(), path.slice(2)) : path;
+}
+/** @internal */
+export async function resolveNotionAuthToken(authTokenRef, options = {}) {
+    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) => 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, options = {}) {
+    return config.auth_token ?? (await resolveNotionAuthToken(config.auth_token_ref ?? '', options));
+}
+export async function notionConnectionToPullConfig(config, options = {}) {
+    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,
+    });
+}

package/dist/context/connections/query-executor.d.ts

@@ -0,0 +1,19 @@
+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 declare function normalizeQueryRows(rows: unknown[]): unknown[][];

package/dist/context/connections/sqlite-query-executor.d.ts

@@ -0,0 +1,4 @@
+import type { KtxSqlQueryExecutionInput, KtxSqlQueryExecutorPort } from './query-executor.js';
+/** @internal */
+export declare function sqliteDatabasePathFromConnection(input: KtxSqlQueryExecutionInput): string;
+export declare function createSqliteQueryExecutor(): KtxSqlQueryExecutorPort;