@kaelio/ktx 0.12.0 → 0.13.1

package/dist/commands/setup-commands.js

@@ -84,6 +84,7 @@ function shouldShowSetupEntryMenu(options, command) {
         'target',
         'global',
         'local',
+        'installDir',
         'skipAgents',
         'yes',
         'input',
@@ -139,6 +140,7 @@ export function registerSetupCommands(program, context) {
     ]))
         .option('--global', 'Install agent integration into the global target scope', false)
         .option('--local', 'Install Claude Code MCP config into the private per-project ~/.claude.json scope', false)
+        .option('--install-dir <path>', 'Directory to install project-scoped agent config into (defaults to the ktx project directory)')
         .addOption(new Option('--skip-agents', 'Leave agent integration incomplete for now').hideHelp().default(false))
         .option('--yes', 'Accept project creation and runtime install defaults where setup confirms', false)
         .option('--no-input', 'Disable interactive terminal input')
@@ -264,6 +266,16 @@ export function registerSetupCommands(program, context) {
             context.setExitCode(1);
             return;
         }
+        if (options.installDir && (options.global || options.local)) {
+            context.io.stderr.write('Choose either --install-dir or a scope flag (--global / --local), not both.\n');
+            context.setExitCode(1);
+            return;
+        }
+        if (options.installDir && options.target === 'claude-desktop') {
+            context.io.stderr.write('--install-dir does not apply to --target claude-desktop, which is always global.\n');
+            context.setExitCode(1);
+            return;
+        }
         const creatingDatabaseConnection = options.database.length > 0 || options.databaseUrl !== undefined;
         if (creatingDatabaseConnection && options.databaseConnectionId.length > 1) {
             context.io.stderr.write('Choose only one new database connection id when configuring a database.\n');
@@ -279,6 +291,7 @@ export function registerSetupCommands(program, context) {
             agents: options.agents === true,
             ...(options.target ? { target: options.target } : {}),
             agentScope: resolvedAgentScope,
+            ...(options.installDir ? { installRoot: options.installDir } : {}),
             skipAgents: options.skipAgents === true,
             inputMode: options.input === false ? 'disabled' : 'auto',
             ...(debugEnabled ? { debug: true } : {}),

package/dist/connection.js

@@ -4,6 +4,7 @@ import { NotionClient } from './context/ingest/adapters/notion/notion-client.js'
 import { createLocalLookerCredentialResolver } from './context/ingest/adapters/looker/local-looker.adapter.js';
 import { metabaseRuntimeConfigFromLocalConnection } from './context/ingest/adapters/metabase/local-metabase.adapter.js';
 import { testRepoConnection } from './context/ingest/repo-fetch.js';
+import { federatedConnectionListing } from './context/connections/federation.js';
 import { getDriverRegistration } from './context/connections/drivers.js';
 import { parseNotionConnectionConfig, resolveNotionConnectionAuthToken } from './context/connections/notion-config.js';
 import { resolveKtxConfigReference } from './context/core/config-reference.js';
@@ -292,12 +293,23 @@ export async function runKtxConnection(args, io = process, deps = {}) {
                 io.stdout.write('No connections configured. Run `ktx setup` to add one.\n');
                 return 0;
             }
-            const idWidth = Math.max('ID'.length, ...entries.map(([id]) => id.length));
-            const driverWidth = Math.max('DRIVER'.length, ...entries.map(([, c]) => (c.driver ?? 'unknown').length));
+            const federated = federatedConnectionListing(project.config.connections, args.projectDir);
+            const idCandidates = [...entries.map(([id]) => id), ...(federated ? [federated.id] : [])];
+            const driverLengths = [
+                ...entries.map(([, c]) => (c.driver ?? 'unknown').length),
+                ...(federated ? [federated.driver.length] : []),
+            ];
+            const idWidth = Math.max('ID'.length, ...idCandidates.map((id) => id.length));
+            const driverWidth = Math.max('DRIVER'.length, ...driverLengths);
             io.stdout.write(`${'ID'.padEnd(idWidth)}  ${'DRIVER'.padEnd(driverWidth)}\n`);
             for (const [id, connection] of entries) {
                 io.stdout.write(`${id.padEnd(idWidth)}  ${(connection.driver ?? 'unknown').padEnd(driverWidth)}\n`);
             }
+            if (federated) {
+                io.stdout.write(`${federated.id.padEnd(idWidth)}  ${federated.driver.padEnd(driverWidth)}\n`);
+                io.stdout.write(`  federates: ${federated.members.join(', ')}\n`);
+                io.stdout.write(`  ${federated.hint}\n`);
+            }
             return 0;
         }
         if (args.command === 'test-all') {

package/dist/connectors/bigquery/connector.js

@@ -5,9 +5,7 @@ import { assertReadOnlySql, limitSqlForExecution } from '../../context/connectio
 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 { resolveStringReference } from '../shared/string-reference.js';
 class DefaultBigQueryClientFactory {
     createClient(input) {
         const client = new BigQuery(input);
@@ -24,17 +22,6 @@ class DefaultBigQueryClientFactory {
         };
     }
 }
-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/clickhouse/connector.js

@@ -3,10 +3,8 @@ import { getDialectForDriver } from '../../context/connections/dialects.js';
 import { assertReadOnlySql, limitSqlForExecution } from '../../context/connections/read-only-sql.js';
 import { connectorTestFailure, createKtxConnectorCapabilities } from '../../context/scan/types.js';
 import { scopedTableNames } from '../../context/scan/table-ref.js';
-import { readFileSync } from 'node:fs';
+import { resolveStringReference } from '../shared/string-reference.js';
 import { Agent as HttpsAgent } from 'node:https';
-import { homedir } from 'node:os';
-import { resolve } from 'node:path';
 class DefaultClickHouseClientFactory {
     createClient(config) {
         return createClient(config);
@@ -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;
 }

package/dist/connectors/duckdb/federated-attach.d.ts

@@ -0,0 +1,7 @@
+import type { FederatedMember } from '../../context/connections/federation.js';
+/**
+ * Resolves a federated member's ktx.yaml config into the connection target
+ * DuckDB's ATTACH wants for that driver, reusing each connector's canonical
+ * resolver so federation and standalone scans agree on config interpretation.
+ */
+export declare function federatedAttachTarget(member: FederatedMember, env: NodeJS.ProcessEnv): string;

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

@@ -0,0 +1,86 @@
+import { sqliteDatabasePathFromConfig } from '../sqlite/connector.js';
+import { postgresPoolConfigFromConfig } from '../postgres/connector.js';
+import { mysqlConnectionPoolConfigFromConfig, } from '../mysql/connector.js';
+function kvKeyword(value) {
+    // libpq/DuckDB key-value values quote with single quotes and backslash-escape.
+    return /[\s'\\]/.test(value) ? `'${value.replaceAll('\\', '\\\\').replaceAll("'", "\\'")}'` : value;
+}
+function withRequiredSslMode(connectionString) {
+    // DuckDB passes this libpq URL straight to the server, so an ssl:true member
+    // must carry sslmode in the URL itself; keep a stronger mode the URL already pins.
+    const url = new URL(connectionString);
+    if (url.searchParams.has('sslmode')) {
+        return connectionString;
+    }
+    url.searchParams.set('sslmode', 'require');
+    return url.toString();
+}
+function postgresAttachString(member, env) {
+    const cfg = postgresPoolConfigFromConfig({
+        connectionId: member.connectionId,
+        connection: member.connection,
+        env,
+    });
+    if (cfg.connectionString) {
+        return cfg.ssl ? withRequiredSslMode(cfg.connectionString) : cfg.connectionString;
+    }
+    const parts = [];
+    if (cfg.host)
+        parts.push(`host=${kvKeyword(cfg.host)}`);
+    if (cfg.port)
+        parts.push(`port=${cfg.port}`);
+    if (cfg.database)
+        parts.push(`dbname=${kvKeyword(cfg.database)}`);
+    if (cfg.user)
+        parts.push(`user=${kvKeyword(cfg.user)}`);
+    if (cfg.password)
+        parts.push(`password=${kvKeyword(cfg.password)}`);
+    if (cfg.ssl) {
+        parts.push('sslmode=require');
+    }
+    if (cfg.options) {
+        parts.push(`options=${kvKeyword(cfg.options)}`);
+    }
+    return parts.join(' ');
+}
+function mysqlAttachString(member, env) {
+    const cfg = mysqlConnectionPoolConfigFromConfig({
+        connectionId: member.connectionId,
+        connection: member.connection,
+        env,
+    });
+    const parts = [
+        `host=${kvKeyword(cfg.host)}`,
+        `port=${cfg.port}`,
+        `database=${kvKeyword(cfg.database)}`,
+        `user=${kvKeyword(cfg.user)}`,
+    ];
+    if (cfg.password) {
+        parts.push(`password=${kvKeyword(cfg.password)}`);
+    }
+    if (cfg.ssl) {
+        parts.push('ssl_mode=REQUIRED');
+    }
+    return parts.join(' ');
+}
+/**
+ * Resolves a federated member's ktx.yaml config into the connection target
+ * DuckDB's ATTACH wants for that driver, reusing each connector's canonical
+ * resolver so federation and standalone scans agree on config interpretation.
+ */
+export function federatedAttachTarget(member, env) {
+    switch (member.driver.toLowerCase()) {
+        case 'sqlite':
+            return sqliteDatabasePathFromConfig({
+                connectionId: member.connectionId,
+                projectDir: member.projectDir,
+                connection: member.connection,
+            });
+        case 'postgres':
+            return postgresAttachString(member, env);
+        case 'mysql':
+            return mysqlAttachString(member, env);
+        default:
+            throw new Error(`Driver "${member.driver}" cannot be attached by DuckDB federation.`);
+    }
+}

package/dist/connectors/duckdb/federated-executor.d.ts

@@ -0,0 +1,5 @@
+import type { KtxSqlQueryExecutionInput, KtxSqlQueryExecutionResult } from '../../context/connections/query-executor.js';
+import { type FederatedMember } from '../../context/connections/federation.js';
+/** @internal */
+export declare function buildAttachStatements(members: FederatedMember[], env: NodeJS.ProcessEnv): string[];
+export declare function executeFederatedQuery(members: FederatedMember[], input: KtxSqlQueryExecutionInput, env?: NodeJS.ProcessEnv): Promise<KtxSqlQueryExecutionResult>;

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;
 }

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.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/sqlserver/connector.js

@@ -1,12 +1,10 @@
-import { assertReadOnlySql, stripTrailingSqlNoise } from '../../context/connections/read-only-sql.js';
+import { assertReadOnlySql, hoistLeadingCte, 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 {
@@ -149,7 +136,8 @@ function limitSqlForSqlServerExecution(sqlText, maxRows) {
     if (!Number.isInteger(maxRows) || maxRows <= 0) {
         throw new Error('maxRows must be a positive integer.');
     }
-    return `SELECT TOP ${maxRows} * FROM (${trimmed}) AS ktx_query_result`;
+    const { withPrefix, body } = hoistLeadingCte(trimmed);
+    return `${withPrefix}SELECT TOP ${maxRows} * FROM (${body}) AS ktx_query_result`;
 }
 export function isKtxSqlServerConnectionConfig(connection) {
     return String(connection?.driver ?? '').toLowerCase() === 'sqlserver';

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,3 +1,8 @@
 export declare function assertReadOnlySql(sql: string): string;
+/** @internal */
+export declare function hoistLeadingCte(sql: string): {
+    withPrefix: string;
+    body: string;
+};
 export declare function stripTrailingSqlNoise(sql: string): string;
 export declare function limitSqlForExecution(sql: string, maxRows: number | undefined): string;