@kaelio/ktx 0.12.0 → 0.13.0

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.0",
   "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",