@kaelio/ktx 0.12.0 → 0.13.1

package/dist/setup-databases.js

@@ -3,6 +3,7 @@ import { readFile, writeFile } from 'node:fs/promises';
 import { delimiter, dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { promisify } from 'node:util';
+import { deriveFederatedConnection, FEDERATED_CONNECTION_ID } from './context/connections/federation.js';
 import { getDriverRegistration } from './context/connections/drivers.js';
 import { createLocalKtxLlmRuntimeFromConfig } from './context/llm/local-config.js';
 import { queryHistoryDialectForConnection } from './context/ingest/adapters/historic-sql/connection-dialect.js';
@@ -845,6 +846,21 @@ async function writeConnectionConfig(input) {
     if (queryHistory?.enabled === true) {
         await ensureHistoricSqlIngestDefaults(input.projectDir);
     }
+    if (input.io) {
+        const federationNotice = federationNoticeFor(config.connections, input.projectDir);
+        if (federationNotice) {
+            writeSetupSection(input.io, 'Federated connection available', [federationNotice]);
+        }
+    }
+}
+/** @internal */
+export function federationNoticeFor(connections, projectDir) {
+    const descriptor = deriveFederatedConnection(connections, projectDir);
+    if (!descriptor) {
+        return null;
+    }
+    const names = descriptor.members.map((m) => m.connectionId).join(', ');
+    return `Detected ${descriptor.members.length} attach-compatible databases (${names}). Run a cross-database join as read-only SQL against \`${FEDERATED_CONNECTION_ID}\` (ktx sql -c ${FEDERATED_CONNECTION_ID} "SELECT ..."), using catalog-qualified table names.`;
 }
 async function disableConnectionQueryHistory(projectDir, connectionId) {
     const project = await loadKtxProject({ projectDir });

package/dist/setup-sources.js

@@ -19,6 +19,7 @@ import { markKtxSetupStateStepComplete } from './context/project/setup-config.js
 import { createCliSpinner, errorMessage, writePrefixedLines } from './clack.js';
 import { pickNotionRootPages } from './notion-page-picker.js';
 import { runKtxSourceMapping } from './source-mapping.js';
+import { assertSafeConnectionId } from './context/sl/source-files.js';
 import { runConnectionSetupWithRecovery, } from './connection-recovery.js';
 import { withMultiselectNavigation, withTextInputNavigation } from './prompt-navigation.js';
 import { runKtxPublicIngest } from './public-ingest.js';
@@ -100,11 +101,6 @@ async function findDbtProjectSubpaths(rootDir) {
 async function promptText(prompts, options) {
     return await prompts.text({ ...options, message: withTextInputNavigation(options.message) });
 }
-function assertSafeConnectionId(connectionId) {
-    if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(connectionId)) {
-        throw new Error(`Unsafe connection id: ${connectionId}`);
-    }
-}
 function credentialRef(value, label) {
     const ref = value?.trim();
     if (!ref) {

package/dist/setup.d.ts

@@ -57,6 +57,7 @@ export type KtxSetupArgs = {
     agents: boolean;
     target?: KtxAgentTarget;
     agentScope?: KtxAgentScope;
+    installRoot?: string;
     skipAgents?: boolean;
     inputMode: 'auto' | 'disabled';
     debug?: boolean;

package/dist/setup.js

@@ -624,6 +624,7 @@ async function runKtxSetupInner(args, io, deps = {}) {
                     agents: true,
                     ...(args.target ? { target: args.target } : {}),
                     scope: args.agentScope ?? 'project',
+                    ...(args.installRoot ? { installRoot: args.installRoot } : {}),
                     mode: 'mcp',
                     skipAgents: false,
                     showNextActions: agentsRequested,

package/dist/sql.d.ts

@@ -1,3 +1,4 @@
+import { executeFederatedQuery } from './connectors/duckdb/federated-executor.js';
 import { loadKtxProject } from './context/project/project.js';
 import type { SqlAnalysisPort } from './context/sql-analysis/ports.js';
 import type { KtxCliIo } from './cli-runtime.js';
@@ -18,6 +19,7 @@ export interface KtxSqlDeps {
     loadProject?: typeof loadKtxProject;
     createSqlAnalysis?: () => SqlAnalysisPort;
     createScanConnector?: typeof createKtxCliScanConnector;
+    executeFederated?: typeof executeFederatedQuery;
 }
 export declare function runKtxSql(args: KtxSqlArgs, io?: KtxCliIo, deps?: KtxSqlDeps): Promise<number>;
 export {};

package/dist/sql.js

@@ -1,4 +1,8 @@
+import { FEDERATED_CONNECTION_ID } from './context/connections/federation.js';
+import { executeProjectReadOnlySql } from './context/connections/project-sql-executor.js';
+import { resolveConfiguredConnection } from './context/connections/resolve-connection.js';
 import { loadKtxProject } from './context/project/project.js';
+import { sqlAnalysisDialectForDriver } from './context/sql-analysis/dialect.js';
 import { resolveOutputMode } from './io/mode.js';
 import { createKtxCliScanConnector } from './local-scan-connectors.js';
 import { createManagedDaemonSqlAnalysisPort } from './managed-python-http.js';
@@ -8,19 +12,6 @@ import { emitTelemetryEvent, reportException } from './telemetry/index.js';
 import { collectTelemetryRedactionSecrets } from './telemetry/redaction-secrets.js';
 import { scrubErrorClass } from './telemetry/scrubber.js';
 profileMark('module:sql');
-function sqlAnalysisDialectForDriver(driver) {
-    const normalized = String(driver ?? '').trim().toLowerCase();
-    const map = {
-        postgres: 'postgres',
-        bigquery: 'bigquery',
-        snowflake: 'snowflake',
-        mysql: 'mysql',
-        sqlserver: 'tsql',
-        sqlite: 'sqlite',
-        clickhouse: 'clickhouse',
-    };
-    return map[normalized] ?? 'postgres';
-}
 function queryVerb(sql) {
     const first = sql.trim().split(/\s+/, 1)[0]?.toLowerCase();
     if (first === 'select' || first === 'explain' || first === 'show' || first === 'with') {
@@ -79,11 +70,6 @@ function printSqlResult(output, mode, io) {
     }
     printPretty(output, io);
 }
-async function cleanupConnector(connector) {
-    if (connector?.cleanup) {
-        await connector.cleanup();
-    }
-}
 function resultOutput(connectionId, result) {
     return {
         connectionId,
@@ -100,12 +86,10 @@ export async function runKtxSql(args, io = process, deps = {}) {
     let project;
     try {
         project = await (deps.loadProject ?? loadKtxProject)({ projectDir: args.projectDir });
-        const connection = project.config.connections[args.connectionId];
-        if (!connection) {
-            throw new Error(`Connection "${args.connectionId}" is not configured in ktx.yaml`);
-        }
-        driver = String(connection.driver ?? 'unknown').toLowerCase();
-        demoConnection = isDemoConnection(args.connectionId, connection);
+        const isFederated = args.connectionId === FEDERATED_CONNECTION_ID;
+        const connection = isFederated ? undefined : resolveConfiguredConnection(project.config, args.connectionId);
+        driver = isFederated ? 'duckdb' : String(connection?.driver ?? 'unknown').toLowerCase();
+        demoConnection = isFederated ? false : isDemoConnection(args.connectionId, connection);
         const createSqlAnalysis = deps.createSqlAnalysis ??
             (() => createManagedDaemonSqlAnalysisPort({
                 cliVersion: args.cliVersion,
@@ -114,44 +98,42 @@ export async function runKtxSql(args, io = process, deps = {}) {
                 io,
             }));
         const analysisPort = createSqlAnalysis();
-        const dialect = sqlAnalysisDialectForDriver(connection.driver);
+        const dialect = isFederated ? 'duckdb' : sqlAnalysisDialectForDriver(connection?.driver);
         const validation = await analysisPort.validateReadOnly(args.sql, dialect);
         if (!validation.ok) {
             throw new Error(validation.error ?? 'SQL is not read-only.');
         }
         const referencedTableCount = await safeReferencedTableCount(analysisPort, args.sql, dialect);
         const createScanConnector = deps.createScanConnector ?? createKtxCliScanConnector;
-        let connector = null;
-        try {
-            connector = await createScanConnector(project, args.connectionId);
-            if (!connector.capabilities.readOnlySql || !connector.executeReadOnly) {
-                throw new Error(`Connection "${args.connectionId}" does not support read-only SQL execution.`);
-            }
-            const result = await connector.executeReadOnly({
+        const result = await executeProjectReadOnlySql({
+            project,
+            input: {
                 connectionId: args.connectionId,
+                projectDir: args.projectDir,
+                connection,
                 sql: args.sql,
                 maxRows: args.maxRows,
-            }, { runId: 'cli-sql' });
-            const mode = resolveOutputMode({ explicit: args.output, json: args.json, io });
-            printSqlResult(resultOutput(args.connectionId, result), mode, io);
-            await emitTelemetryEvent({
-                name: 'sql_completed',
-                projectDir: args.projectDir,
-                io,
-                fields: {
-                    driver,
-                    isDemoConnection: demoConnection,
-                    queryVerb: queryVerb(args.sql),
-                    referencedTableCount,
-                    durationMs: Math.max(0, performance.now() - startedAt),
-                    outcome: 'ok',
-                },
-            });
-            return 0;
-        }
-        finally {
-            await cleanupConnector(connector);
-        }
+            },
+            createConnector: (connectionId) => createScanConnector(project, connectionId),
+            executeFederated: deps.executeFederated,
+            runId: 'cli-sql',
+        });
+        const mode = resolveOutputMode({ explicit: args.output, json: args.json, io });
+        printSqlResult(resultOutput(args.connectionId, result), mode, io);
+        await emitTelemetryEvent({
+            name: 'sql_completed',
+            projectDir: args.projectDir,
+            io,
+            fields: {
+                driver,
+                isDemoConnection: demoConnection,
+                queryVerb: queryVerb(args.sql),
+                referencedTableCount,
+                durationMs: Math.max(0, performance.now() - startedAt),
+                outcome: 'ok',
+            },
+        });
+        return 0;
     }
     catch (error) {
         const errorClass = scrubErrorClass(error);

package/dist/telemetry/events.d.ts

@@ -303,6 +303,7 @@ export declare const telemetryEventSchemas: {
         }>;
         durationMs: z.ZodNumber;
         errorClass: z.ZodOptional<z.ZodString>;
+        errorDetail: z.ZodOptional<z.ZodString>;
         sampleRate: z.ZodLiteral<1>;
         mcpClientName: z.ZodOptional<z.ZodString>;
         mcpClientVersion: z.ZodOptional<z.ZodString>;
@@ -459,7 +460,7 @@ export declare const telemetryEventCatalog: readonly [{
 }, {
     readonly name: "mcp_request_completed";
     readonly description: "Emitted for sampled MCP tool requests.";
-    readonly fields: readonly ["toolName", "outcome", "durationMs", "errorClass", "sampleRate", "mcpClientName", "mcpClientVersion"];
+    readonly fields: readonly ["toolName", "outcome", "durationMs", "errorClass", "errorDetail", "sampleRate", "mcpClientName", "mcpClientVersion"];
 }, {
     readonly name: "daemon_started";
     readonly description: "Emitted when the long-lived ktx-daemon HTTP server starts.";

package/dist/telemetry/events.js

@@ -145,6 +145,7 @@ const mcpRequestCompletedSchema = telemetryCommonEnvelopeSchema
     outcome: outcomeSchema,
     durationMs: z.number().nonnegative(),
     errorClass: z.string().optional(),
+    errorDetail: z.string().max(1000).optional(),
     sampleRate: z.literal(1),
     // Raw, client-tool-controlled identity from the MCP initialize handshake
     // (clientInfo.name/version). Optional: clients may omit clientInfo. Stored
@@ -326,7 +327,16 @@ export const telemetryEventCatalog = [
     {
         name: 'mcp_request_completed',
         description: 'Emitted for sampled MCP tool requests.',
-        fields: ['toolName', 'outcome', 'durationMs', 'errorClass', 'sampleRate', 'mcpClientName', 'mcpClientVersion'],
+        fields: [
+            'toolName',
+            'outcome',
+            'durationMs',
+            'errorClass',
+            'errorDetail',
+            'sampleRate',
+            'mcpClientName',
+            'mcpClientVersion',
+        ],
     },
     {
         name: 'daemon_started',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaelio/ktx",
-  "version": "0.12.0",
+  "version": "0.13.1",
   "description": "Standalone ktx context layer for data agents",
   "author": {
     "name": "Kaelio",
@@ -40,6 +40,7 @@
     "@clack/prompts": "1.4.0",
     "@clickhouse/client": "^1.18.5",
     "@commander-js/extra-typings": "14.0.0",
+    "@duckdb/node-api": "1.5.3-r.3",
     "@google-cloud/bigquery": "^8.3.1",
     "@looker/sdk": "^26.8.0",
     "@looker/sdk-node": "^26.8.0",