@kaelio/ktx 0.11.0 → 0.13.0

package/dist/connectors/duckdb/federated-executor.js

@@ -0,0 +1,59 @@
+import { DuckDBInstance } from '@duckdb/node-api';
+import { federatedAttachTarget } from './federated-attach.js';
+import { normalizeQueryRows } from '../../context/connections/query-executor.js';
+import { assertReadOnlySql, limitSqlForExecution } from '../../context/connections/read-only-sql.js';
+import { attachTypeForDriver } from '../../context/connections/federation.js';
+function quoteDuckdbIdentifier(id) {
+    return `"${id.replaceAll('"', '""')}"`;
+}
+const MIN_SAFE_BIGINT = BigInt(Number.MIN_SAFE_INTEGER);
+const MAX_SAFE_BIGINT = BigInt(Number.MAX_SAFE_INTEGER);
+// DuckDB returns integer columns as JS bigint (unserializable by JSON). Values
+// in Number's safe range become Number; larger magnitudes become strings so a
+// BIGINT beyond 2^53 keeps its exact value instead of silently rounding.
+function jsonSafeBigint(value) {
+    return value >= MIN_SAFE_BIGINT && value <= MAX_SAFE_BIGINT ? Number(value) : value.toString();
+}
+function toJsonSafeRows(rows) {
+    return rows.map((row) => row.map((cell) => (typeof cell === 'bigint' ? jsonSafeBigint(cell) : cell)));
+}
+/** @internal */
+export function buildAttachStatements(members, env) {
+    const attachments = members.map((member) => ({
+        type: attachTypeForDriver(member.driver),
+        url: federatedAttachTarget(member, env),
+        alias: member.connectionId,
+    }));
+    const loadStatements = [...new Set(attachments.map((a) => a.type))].map((type) => `INSTALL ${type}; LOAD ${type};`);
+    const attachStatements = attachments.map(({ type, url, alias }) => `ATTACH '${url.replaceAll("'", "''")}' AS ${quoteDuckdbIdentifier(alias)} (TYPE ${type}, READ_ONLY);`);
+    return [...loadStatements, ...attachStatements];
+}
+export async function executeFederatedQuery(members, input, env = process.env) {
+    const sql = limitSqlForExecution(assertReadOnlySql(input.sql), input.maxRows);
+    const attachStatements = buildAttachStatements(members, env);
+    const instance = await DuckDBInstance.create(':memory:');
+    try {
+        const connection = await instance.connect();
+        try {
+            for (const statement of attachStatements) {
+                await connection.run(statement);
+            }
+            const reader = await connection.runAndReadAll(sql);
+            const rows = toJsonSafeRows(normalizeQueryRows(reader.getRows()));
+            const headers = reader.columnNames();
+            return {
+                headers,
+                rows,
+                totalRows: rows.length,
+                command: 'SELECT',
+                rowCount: rows.length,
+            };
+        }
+        finally {
+            connection.closeSync();
+        }
+    }
+    finally {
+        instance.closeSync();
+    }
+}

package/dist/connectors/mysql/connector.js

@@ -1,8 +1,6 @@
 import mysql from 'mysql2/promise';
-import { readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { resolve } from 'node:path';
 import { getDialectForDriver } from '../../context/connections/dialects.js';
+import { resolveStringReference } from '../shared/string-reference.js';
 import { assertReadOnlySql, limitSqlForExecution } from '../../context/connections/read-only-sql.js';
 import { constraintDiscoveryWarning, tryConstraintQuery, } from '../../context/scan/constraint-discovery.js';
 import { scopedTableNames } from '../../context/scan/table-ref.js';
@@ -16,18 +14,6 @@ function stringConfigValue(connection, key, env) {
     const value = connection?.[key];
     return typeof value === 'string' && value.trim().length > 0 ? resolveStringReference(value.trim(), env) : undefined;
 }
-function resolveStringReference(value, env) {
-    if (value.startsWith('env:')) {
-        const envName = value.slice('env:'.length);
-        return env[envName] ?? '';
-    }
-    if (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 maybeNumber(value) {
     return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
 }
@@ -508,7 +494,7 @@ export class KtxMysqlScanConnector {
     }
     assertConnection(connectionId) {
         if (connectionId !== this.connectionId) {
-            throw new Error(`KTX MySQL connector ${this.id} cannot serve connection ${connectionId}`);
+            throw new Error(`ktx MySQL connector ${this.id} cannot serve connection ${connectionId}`);
         }
     }
 }

package/dist/connectors/postgres/connector.js

@@ -1,6 +1,4 @@
-import { readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { resolve } from 'node:path';
+import { resolveStringReference } from '../shared/string-reference.js';
 import { getDialectForDriver } from '../../context/connections/dialects.js';
 import { assertReadOnlySql, limitSqlForExecution } from '../../context/connections/read-only-sql.js';
 import { tryConstraintQuery } from '../../context/scan/constraint-discovery.js';
@@ -88,17 +86,6 @@ function stringConfigValue(connection, key, env) {
     const value = connection?.[key];
     return typeof value === 'string' && value.trim().length > 0 ? resolveStringReference(value.trim(), env) : undefined;
 }
-function resolveStringReference(value, env) {
-    if (value.startsWith('env:')) {
-        return env[value.slice('env:'.length)] ?? '';
-    }
-    if (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 numberValue(value) {
     return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
 }

package/dist/connectors/shared/string-reference.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Resolves a config string that may reference an environment variable
+ * (`env:NAME`) or a file (`file:/path`, `~` expands to the home dir).
+ * Plain values pass through unchanged.
+ */
+export declare function resolveStringReference(value: string, env: NodeJS.ProcessEnv): string;

package/dist/connectors/shared/string-reference.js

@@ -0,0 +1,19 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+/**
+ * Resolves a config string that may reference an environment variable
+ * (`env:NAME`) or a file (`file:/path`, `~` expands to the home dir).
+ * Plain values pass through unchanged.
+ */
+export function resolveStringReference(value, env) {
+    if (value.startsWith('env:')) {
+        return env[value.slice('env:'.length)] ?? '';
+    }
+    if (value.startsWith('file:')) {
+        const rawPath = value.slice('file:'.length);
+        const path = rawPath.startsWith('~') ? resolve(homedir(), rawPath.slice(rawPath[1] === '/' ? 2 : 1)) : rawPath;
+        return readFileSync(path, 'utf-8').trim();
+    }
+    return value;
+}

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

@@ -72,7 +72,7 @@ export interface KtxSnowflakeScanConnectorOptions {
     connectionId: string;
     connection: KtxSnowflakeConnectionConfig | undefined;
     /**
-     * KTX project directory. When provided, snowflake-sdk's logger is redirected to
+     * ktx project directory. When provided, snowflake-sdk's logger is redirected to
      * `<projectDir>/.ktx/logs/snowflake.log` so its JSON output does not bleed into
      * the CLI's TTY. Tests that use a fake driverFactory can leave this undefined.
      */

package/dist/connectors/snowflake/connector.js

@@ -1,8 +1,6 @@
 import { createPrivateKey } from 'node:crypto';
-import { readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { resolve } from 'node:path';
 import { getDialectForDriver } from '../../context/connections/dialects.js';
+import { resolveStringReference } from '../shared/string-reference.js';
 import { assertReadOnlySql, limitSqlForExecution } from '../../context/connections/read-only-sql.js';
 import { tryConstraintQuery } from '../../context/scan/constraint-discovery.js';
 import { scopedTableNames } from '../../context/scan/table-ref.js';
@@ -11,17 +9,6 @@ import snowflake from 'snowflake-sdk';
 import { assertSafeSnowflakeIdentifier, quoteSnowflakeIdentifier } from './identifiers.js';
 import { configureSnowflakeSdkLogger } from './sdk-logger.js';
 const DATE_TYPES = ['DATE', 'TIMESTAMP', 'TIMESTAMP_LTZ', 'TIMESTAMP_NTZ', 'TIMESTAMP_TZ', 'TIME'];
-function resolveStringReference(value, env) {
-    if (value.startsWith('env:')) {
-        return env[value.slice('env:'.length)] ?? '';
-    }
-    if (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 stringConfigValue(connection, key, env) {
     const value = connection?.[key];
     return typeof value === 'string' && value.trim().length > 0 ? resolveStringReference(value.trim(), env) : undefined;

package/dist/connectors/sqlite/connector.js

@@ -35,29 +35,6 @@ function sqlitePathFromUrl(url) {
     }
     return url;
 }
-function stripLeadingSqlComments(sql) {
-    let index = 0;
-    while (index < sql.length) {
-        while (/\s/.test(sql[index] ?? '')) {
-            index += 1;
-        }
-        if (sql.startsWith('--', index)) {
-            const end = sql.indexOf('\n', index + 2);
-            index = end === -1 ? sql.length : end + 1;
-            continue;
-        }
-        if (sql.startsWith('/*', index)) {
-            const end = sql.indexOf('*/', index + 2);
-            if (end === -1) {
-                return sql.slice(index);
-            }
-            index = end + 2;
-            continue;
-        }
-        break;
-    }
-    return sql.slice(index);
-}
 export function isKtxSqliteConnectionConfig(connection) {
     const driver = String(connection?.driver ?? '').toLowerCase();
     return driver === 'sqlite';
@@ -171,7 +148,7 @@ export class KtxSqliteScanConnector {
     }
     async executeReadOnly(input, _ctx) {
         this.assertConnection(input.connectionId);
-        const result = this.query(limitSqlForExecution(stripLeadingSqlComments(input.sql), input.maxRows), input.params);
+        const result = this.query(limitSqlForExecution(input.sql, input.maxRows), input.params);
         return { ...result, rowCount: result.rows.length };
     }
     async getColumnDistinctValues(table, columnName, options) {
@@ -274,7 +251,7 @@ export class KtxSqliteScanConnector {
     }
     assertConnection(connectionId) {
         if (connectionId !== this.connectionId) {
-            throw new Error(`KTX SQLite connector ${this.id} cannot serve connection ${connectionId}`);
+            throw new Error(`ktx SQLite connector ${this.id} cannot serve connection ${connectionId}`);
         }
     }
 }

package/dist/connectors/sqlserver/connector.js

@@ -1,12 +1,10 @@
-import { assertReadOnlySql } from '../../context/connections/read-only-sql.js';
+import { assertReadOnlySql, stripTrailingSqlNoise } from '../../context/connections/read-only-sql.js';
 import { getDialectForDriver } from '../../context/connections/dialects.js';
 import { tryConstraintQuery } from '../../context/scan/constraint-discovery.js';
 import { scopedTableNames } from '../../context/scan/table-ref.js';
 import { connectorTestFailure, createKtxConnectorCapabilities, } from '../../context/scan/types.js';
-import { readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { resolve } from 'node:path';
 import sql from 'mssql';
+import { resolveStringReference } from '../shared/string-reference.js';
 function sqlTypeDeclaration(type) {
     if (typeof type === 'function') {
         try {
@@ -79,17 +77,6 @@ function stringConfigValue(connection, key, env) {
     const value = connection?.[key];
     return typeof value === 'string' && value.trim().length > 0 ? resolveStringReference(value.trim(), env) : undefined;
 }
-function resolveStringReference(value, env) {
-    if (value.startsWith('env:')) {
-        return env[value.slice('env:'.length)] ?? '';
-    }
-    if (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 parseSqlServerUrl(url) {
     const parsed = new URL(url);
     return {
@@ -142,7 +129,7 @@ function isDeniedError(error) {
     return number === 229 || number === 230 || number === 297;
 }
 function limitSqlForSqlServerExecution(sqlText, maxRows) {
-    const trimmed = assertReadOnlySql(sqlText).replace(/;+\s*$/, '');
+    const trimmed = stripTrailingSqlNoise(assertReadOnlySql(sqlText));
     if (!maxRows) {
         return trimmed;
     }
@@ -575,7 +562,7 @@ export class KtxSqlServerScanConnector {
     }
     assertConnection(connectionId) {
         if (connectionId !== this.connectionId) {
-            throw new Error(`KTX SQL Server connector ${this.id} cannot serve connection ${connectionId}`);
+            throw new Error(`ktx SQL Server connector ${this.id} cannot serve connection ${connectionId}`);
         }
     }
 }

package/dist/context/connections/connection-type.d.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 export declare const connectionTypeSchema: z.ZodEnum<{
+    PLAIN: "PLAIN";
     BIGQUERY: "BIGQUERY";
     SNOWFLAKE: "SNOWFLAKE";
     MYSQL: "MYSQL";
@@ -19,7 +20,6 @@ export declare const connectionTypeSchema: z.ZodEnum<{
     METABASE: "METABASE";
     LOOKER: "LOOKER";
     NOTION: "NOTION";
-    PLAIN: "PLAIN";
     BETTERSTACK: "BETTERSTACK";
 }>;
 export type ConnectionType = z.infer<typeof connectionTypeSchema>;

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

@@ -0,0 +1,33 @@
+import type { KtxProjectConnectionConfig } from '../project/config.js';
+/** Stable id for the runtime-derived federated connection. Never written to ktx.yaml. */
+export declare const FEDERATED_CONNECTION_ID = "_ktx_federated";
+export declare function attachTypeForDriver(driver: string): string;
+export interface FederatedMember {
+    connectionId: string;
+    driver: string;
+    projectDir: string;
+    connection: KtxProjectConnectionConfig;
+}
+export interface FederatedConnectionDescriptor {
+    id: typeof FEDERATED_CONNECTION_ID;
+    driver: 'duckdb';
+    members: FederatedMember[];
+}
+/**
+ * Derives a virtual federated connection when a project declares 2+
+ * attach-compatible databases. Returns null otherwise — single-DB and
+ * incompatible projects are unaffected.
+ */
+export declare function deriveFederatedConnection(connections: Record<string, KtxProjectConnectionConfig>, projectDir: string): FederatedConnectionDescriptor | null;
+export interface FederatedConnectionListing {
+    id: typeof FEDERATED_CONNECTION_ID;
+    driver: 'duckdb';
+    members: string[];
+    hint: string;
+}
+/**
+ * Listing-facing view of the virtual federated connection for `ktx connection`
+ * and MCP `connection_list`. Derived from the same declared state as
+ * deriveFederatedConnection, so both surfaces describe one connection.
+ */
+export declare function federatedConnectionListing(connections: Record<string, KtxProjectConnectionConfig>, projectDir: string): FederatedConnectionListing | null;

package/dist/context/connections/federation.js

@@ -0,0 +1,51 @@
+/** Stable id for the runtime-derived federated connection. Never written to ktx.yaml. */
+export const FEDERATED_CONNECTION_ID = '_ktx_federated';
+/**
+ * Drivers DuckDB can ATTACH for federation. The driver name doubles as the
+ * DuckDB extension/TYPE name, so this set is the single source of truth for
+ * both membership (a driver participates iff it appears here) and attach type.
+ */
+const ATTACH_COMPATIBLE_DRIVERS = new Set(['postgres', 'mysql', 'sqlite']);
+export function attachTypeForDriver(driver) {
+    const normalized = driver.toLowerCase();
+    if (!ATTACH_COMPATIBLE_DRIVERS.has(normalized)) {
+        throw new Error(`Driver "${driver}" cannot be attached by DuckDB federation.`);
+    }
+    return normalized;
+}
+/**
+ * Derives a virtual federated connection when a project declares 2+
+ * attach-compatible databases. Returns null otherwise — single-DB and
+ * incompatible projects are unaffected.
+ */
+export function deriveFederatedConnection(connections, projectDir) {
+    const members = Object.entries(connections)
+        .filter(([, config]) => ATTACH_COMPATIBLE_DRIVERS.has(config.driver.toLowerCase()))
+        .map(([connectionId, config]) => ({
+        connectionId,
+        driver: config.driver.toLowerCase(),
+        projectDir,
+        connection: config,
+    }));
+    if (members.length < 2) {
+        return null;
+    }
+    return { id: FEDERATED_CONNECTION_ID, driver: 'duckdb', members };
+}
+/**
+ * Listing-facing view of the virtual federated connection for `ktx connection`
+ * and MCP `connection_list`. Derived from the same declared state as
+ * deriveFederatedConnection, so both surfaces describe one connection.
+ */
+export function federatedConnectionListing(connections, projectDir) {
+    const descriptor = deriveFederatedConnection(connections, projectDir);
+    if (!descriptor) {
+        return null;
+    }
+    return {
+        id: FEDERATED_CONNECTION_ID,
+        driver: 'duckdb',
+        members: descriptor.members.map((member) => member.connectionId),
+        hint: 'Cross-database queries run here. Name tables connectionId.schema.table (or connectionId.table for sqlite); double-quote any id that is not a bare SQL identifier, e.g. "books-db".public.books.',
+    };
+}

package/dist/context/connections/local-warehouse-descriptor.d.ts

@@ -14,6 +14,8 @@ export interface LocalConnectionInfo {
     id: string;
     name: string;
     connectionType: string;
+    members?: string[];
+    hint?: string;
 }
 export declare function localConnectionToWarehouseDescriptor(id: string, connection: KtxProjectConnectionConfig | undefined): LocalWarehouseDescriptor | null;
 export declare function localConnectionTypeForConfig(id: string, connection: KtxProjectConnectionConfig | undefined): string;

package/dist/context/connections/project-sql-executor.d.ts

@@ -0,0 +1,18 @@
+import { executeFederatedQuery } from '../../connectors/duckdb/federated-executor.js';
+import type { KtxLocalProject } from '../project/project.js';
+import type { KtxScanConnector } from '../scan/types.js';
+import type { KtxSqlQueryExecutionInput, KtxSqlQueryExecutionResult } from './query-executor.js';
+export interface ExecuteProjectReadOnlySqlDeps {
+    project: KtxLocalProject;
+    input: KtxSqlQueryExecutionInput;
+    createConnector: (connectionId: string) => Promise<KtxScanConnector> | KtxScanConnector;
+    executeFederated?: typeof executeFederatedQuery;
+    runId?: string;
+}
+/**
+ * Single resolve-and-execute path for project read-only SQL. The federated
+ * connection is derived from declared state here so every executor entry point
+ * routes `_ktx_federated` identically; standard connections go through the
+ * scan connector.
+ */
+export declare function executeProjectReadOnlySql(deps: ExecuteProjectReadOnlySqlDeps): Promise<KtxSqlQueryExecutionResult>;

package/dist/context/connections/project-sql-executor.js

@@ -0,0 +1,39 @@
+import { executeFederatedQuery } from '../../connectors/duckdb/federated-executor.js';
+import { deriveFederatedConnection, FEDERATED_CONNECTION_ID } from './federation.js';
+/**
+ * Single resolve-and-execute path for project read-only SQL. The federated
+ * connection is derived from declared state here so every executor entry point
+ * routes `_ktx_federated` identically; standard connections go through the
+ * scan connector.
+ */
+export async function executeProjectReadOnlySql(deps) {
+    const { project, input } = deps;
+    if (input.connectionId === FEDERATED_CONNECTION_ID) {
+        const descriptor = deriveFederatedConnection(project.config.connections, project.projectDir);
+        if (!descriptor) {
+            throw new Error('Federated execution requested but fewer than 2 attach-compatible connections exist.');
+        }
+        const runFederated = deps.executeFederated ?? executeFederatedQuery;
+        return runFederated(descriptor.members, input);
+    }
+    let connector = null;
+    try {
+        connector = await deps.createConnector(input.connectionId);
+        if (!connector.capabilities.readOnlySql || !connector.executeReadOnly) {
+            throw new Error(`Connection "${input.connectionId}" driver "${connector.driver}" does not support read-only SQL execution.`);
+        }
+        const ctx = { runId: deps.runId ?? 'sql-execution' };
+        const result = await connector.executeReadOnly({ connectionId: input.connectionId, sql: input.sql, maxRows: input.maxRows }, ctx);
+        return {
+            headers: result.headers,
+            ...(result.headerTypes ? { headerTypes: result.headerTypes } : {}),
+            rows: result.rows,
+            totalRows: result.totalRows,
+            command: 'SELECT',
+            rowCount: result.rowCount,
+        };
+    }
+    finally {
+        await connector?.cleanup?.();
+    }
+}

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

@@ -6,8 +6,9 @@ export interface KtxSqlQueryExecutionInput {
     sql: string;
     maxRows?: number;
 }
-interface KtxSqlQueryExecutionResult {
+export interface KtxSqlQueryExecutionResult {
     headers: string[];
+    headerTypes?: string[];
     rows: unknown[][];
     totalRows: number;
     command: string;
@@ -17,4 +18,3 @@ export interface KtxSqlQueryExecutorPort {
     execute(input: KtxSqlQueryExecutionInput): Promise<KtxSqlQueryExecutionResult>;
 }
 export declare function normalizeQueryRows(rows: unknown[]): unknown[][];
-export {};

package/dist/context/connections/read-only-sql.d.ts

@@ -1,2 +1,3 @@
 export declare function assertReadOnlySql(sql: string): string;
+export declare function stripTrailingSqlNoise(sql: string): string;
 export declare function limitSqlForExecution(sql: string, maxRows: number | undefined): string;

package/dist/context/connections/read-only-sql.js

@@ -1,19 +1,134 @@
+import { KtxQueryError } from '../../errors.js';
 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;
+// Agents (and the daemon's sqlglot validator, which ignores comments) routinely
+// emit read-only queries prefixed with `-- ...` or `/* ... */`. Strip leading
+// comments so the prefix check sees the real statement; otherwise valid SELECT/WITH
+// SQL is rejected here while the parser-backed validator accepts it.
+function stripLeadingSqlComments(sql) {
+    let index = 0;
+    while (index < sql.length) {
+        while (/\s/.test(sql[index] ?? '')) {
+            index += 1;
+        }
+        if (sql.startsWith('--', index)) {
+            const end = sql.indexOf('\n', index + 2);
+            index = end === -1 ? sql.length : end + 1;
+            continue;
+        }
+        if (sql.startsWith('/*', index)) {
+            const end = sql.indexOf('*/', index + 2);
+            if (end === -1) {
+                return sql.slice(index);
+            }
+            index = end + 2;
+            continue;
+        }
+        break;
+    }
+    return sql.slice(index);
+}
+// Lexes past one string literal, quoted identifier, or comment starting at
+// `index`, using standard-SQL rules ('' and "" escapes; no dialect extensions
+// such as backslash escapes or dollar quoting). Returns the index after the
+// token, or `index` unchanged when no quoted/comment token starts there.
+function skipQuotedOrComment(sql, index) {
+    const quote = sql[index];
+    if (quote === "'" || quote === '"') {
+        let i = index + 1;
+        while (i < sql.length) {
+            if (sql[i] === quote) {
+                if (sql[i + 1] === quote) {
+                    i += 2;
+                    continue;
+                }
+                return i + 1;
+            }
+            i += 1;
+        }
+        return sql.length;
+    }
+    if (sql.startsWith('--', index)) {
+        const end = sql.indexOf('\n', index + 2);
+        return end === -1 ? sql.length : end + 1;
+    }
+    if (sql.startsWith('/*', index)) {
+        const end = sql.indexOf('*/', index + 2);
+        return end === -1 ? sql.length : end + 2;
+    }
+    return index;
+}
+// Backstop against statement smuggling (`select 1; drop table x`): reject any
+// semicolon that is followed by real content. Semicolons inside string
+// literals, quoted identifiers, and comments are fine, as are trailing
+// semicolons (optionally followed by whitespace and comments). This deliberately
+// lexes standard SQL only, so dialect-specific escapes can cause a false
+// reject — never a false accept; the canonical gate is the daemon's
+// sqlglot-backed validateReadOnly.
+function assertSingleSqlStatement(sql) {
+    let index = 0;
+    let sawSemicolon = false;
+    while (index < sql.length) {
+        const skipped = skipQuotedOrComment(sql, index);
+        if (skipped > index) {
+            index = skipped;
+            continue;
+        }
+        if (sql[index] === ';') {
+            sawSemicolon = true;
+        }
+        else if (sawSemicolon && !/\s/.test(sql[index])) {
+            throw new KtxQueryError('Only one SQL statement can be executed.');
+        }
+        index += 1;
+    }
+}
 export function assertReadOnlySql(sql) {
-    const trimmed = sql.trim();
+    const trimmed = stripLeadingSqlComments(sql).trim();
     if (!READ_SQL.test(trimmed) || MUTATING_SQL.test(trimmed)) {
-        throw new Error('Only read-only SELECT/WITH queries can be executed locally.');
+        throw new KtxQueryError('Only read-only SELECT/WITH queries can be executed locally.');
     }
+    assertSingleSqlStatement(trimmed);
     return trimmed;
 }
+// `assertReadOnlySql` deliberately keeps trailing semicolons, comments, and
+// whitespace (e.g. `select 1; -- done`) — harmless for direct single-statement
+// execution. A row-limit subquery wrapper needs a bare expression instead: a
+// trailing `;` would sit illegally inside the subquery, and a trailing line
+// comment would comment out the closing paren and limit clause. Lex forward with
+// the same standard-SQL rules as the single-statement gate and truncate at the
+// end of the last meaningful token, dropping trailing semicolons, comments, and
+// whitespace. Characters inside string literals and quoted identifiers stay
+// meaningful, so a `;` or `--` within a literal is never mistaken for a
+// terminator (a plain regex cannot make that distinction).
+export function stripTrailingSqlNoise(sql) {
+    let index = 0;
+    let meaningfulEnd = 0;
+    while (index < sql.length) {
+        if (sql.startsWith('--', index) || sql.startsWith('/*', index)) {
+            index = skipQuotedOrComment(sql, index);
+            continue;
+        }
+        const afterQuoted = skipQuotedOrComment(sql, index);
+        if (afterQuoted > index) {
+            meaningfulEnd = afterQuoted;
+            index = afterQuoted;
+            continue;
+        }
+        if (sql[index] !== ';' && !/\s/.test(sql[index] ?? '')) {
+            meaningfulEnd = index + 1;
+        }
+        index += 1;
+    }
+    return sql.slice(0, meaningfulEnd);
+}
 export function limitSqlForExecution(sql, maxRows) {
-    const trimmed = assertReadOnlySql(sql).replace(/;+\s*$/, '');
+    const trimmed = stripTrailingSqlNoise(assertReadOnlySql(sql));
     if (!maxRows) {
         return trimmed;
     }
     if (!Number.isInteger(maxRows) || maxRows <= 0) {
-        throw new Error('maxRows must be a positive integer.');
+        throw new KtxQueryError('maxRows must be a positive integer.');
     }
     return `select * from (${trimmed}) as ktx_query_result limit ${maxRows}`;
 }

package/dist/context/connections/resolve-connection.d.ts

@@ -0,0 +1,12 @@
+import type { KtxProjectConfig, KtxProjectConnectionConfig } from '../project/config.js';
+/**
+ * Look up a connection by id, throwing an expected (caller-driven) error that
+ * names the configured connections so an agent or CLI user can self-correct.
+ */
+export declare function resolveConfiguredConnection(config: KtxProjectConfig, connectionId: string): KtxProjectConnectionConfig;
+/**
+ * Resolve the connection id to run against: validate a requested id against the
+ * configured connections, or default to the sole connection when none is given.
+ * Throws an expected error that lists the configured connections otherwise.
+ */
+export declare function resolveRequiredConnectionId(config: KtxProjectConfig, requested: string | undefined): string;