@kaelio/ktx 0.11.0 → 0.13.0

package/dist/admin.js

@@ -18,7 +18,7 @@ export function registerAdminCommands(program, context) {
     });
     admin
         .command('init')
-        .description('Initialize a Git-backed KTX project directory for maintenance scripts')
+        .description('Initialize a Git-backed ktx project directory for maintenance scripts')
         .argument('[directory]', 'Project directory')
         .option('--force', 'Rewrite ktx.yaml and scaffold files in an existing project', false)
         .action(async (projectDir, commandOptions, command) => {

package/dist/clack.d.ts

@@ -39,5 +39,21 @@ export interface KtxCliPromptAdapter {
     spinner(): KtxCliSpinner;
 }
 export declare function createClackSpinner(): KtxCliSpinner;
+/**
+ * Stderr-only, non-animated spinner. Use this instead of {@link createCliSpinner}
+ * when the next step reads stdin in raw mode (an Ink TUI or a keypress wait):
+ * the animated clack spinner seizes stdin via `@clack/core`'s `block()` and
+ * leaves it dirty, which the following raw-mode reader misreads as a stray key.
+ */
 export declare function createStaticCliSpinner(io: KtxCliSpinnerIo): KtxCliSpinner;
+/**
+ * Animated spinner in an interactive terminal, static `◐/◇/■` lines otherwise
+ * (scripts, CI, piped output) so logs stay clean and uncluttered by frames.
+ */
+export declare function createCliSpinner(io: KtxCliIo): KtxCliSpinner;
+export declare function runWithCliSpinner<T>(spinner: KtxCliSpinner, text: {
+    start: string;
+    success: string;
+    failure: string;
+}, run: () => Promise<T>): Promise<T>;
 export declare function createClackPromptAdapter(): KtxCliPromptAdapter;

package/dist/clack.js

@@ -36,30 +36,61 @@ class KtxCliPromptCancelledError extends Error {
     }
 }
 export function createClackSpinner() {
-    return spinner();
+    // clack colors the animated spinner frame magenta by default; styleFrame
+    // (typed in SpinnerOptions, absent from the README) recolors it ktx orange.
+    return spinner({ styleFrame: orange });
 }
-function magenta(text) {
-    return ansiColor(text, 35, 39);
+// ktx mascot orange (#FF8A4C) via 24-bit truecolor.
+function orange(text) {
+    if (!ansiEnabled()) {
+        return text;
+    }
+    return `${ESC}[38;2;255;138;76m${text}${ESC}[39m`;
 }
 function red(text) {
     return ansiColor(text, 31, 39);
 }
+/**
+ * Stderr-only, non-animated spinner. Use this instead of {@link createCliSpinner}
+ * when the next step reads stdin in raw mode (an Ink TUI or a keypress wait):
+ * the animated clack spinner seizes stdin via `@clack/core`'s `block()` and
+ * leaves it dirty, which the following raw-mode reader misreads as a stray key.
+ */
 export function createStaticCliSpinner(io) {
     return {
         start(message) {
-            io.stderr.write(`${magenta('◐')}  ${message}\n`);
+            io.stderr.write(`${orange('◐')}  ${message}\n`);
         },
         message(message) {
-            io.stderr.write(`${magenta('│')}  ${message}\n`);
+            io.stderr.write(`${orange('│')}  ${message}\n`);
         },
         stop(message) {
-            io.stderr.write(`${magenta('◇')}  ${message}\n`);
+            io.stderr.write(`${orange('◇')}  ${message}\n`);
         },
         error(message) {
             io.stderr.write(`${red('■')}  ${message}\n`);
         },
     };
 }
+/**
+ * Animated spinner in an interactive terminal, static `◐/◇/■` lines otherwise
+ * (scripts, CI, piped output) so logs stay clean and uncluttered by frames.
+ */
+export function createCliSpinner(io) {
+    return io.stdout.isTTY === true ? createClackSpinner() : createStaticCliSpinner(io);
+}
+export async function runWithCliSpinner(spinner, text, run) {
+    spinner.start(text.start);
+    try {
+        const value = await run();
+        spinner.stop(text.success);
+        return value;
+    }
+    catch (error) {
+        spinner.error(text.failure);
+        throw error;
+    }
+}
 export function createClackPromptAdapter() {
     return {
         async confirm(options) {

package/dist/claude-code-prompt-caching.js

@@ -15,7 +15,7 @@ export function formatClaudeCodePromptCachingWarning(fields) {
     if (fields.length === 0) {
         return null;
     }
-    return `claude-code ignores ${fields.join(', ')} because the Claude Agent SDK does not expose KTX prompt-cache TTL, tool, or history markers.`;
+    return `claude-code ignores ${fields.join(', ')} because the Claude Agent SDK does not expose ktx prompt-cache TTL, tool, or history markers.`;
 }
 export function formatClaudeCodePromptCachingFix() {
     return 'Remove those promptCaching fields or use anthropic, vertex, or gateway when those cache knobs are required.';

package/dist/cli-program.js

@@ -162,8 +162,8 @@ export function resolveCommandProjectDirOverride(command) {
 function createBaseProgram(info, io) {
     return new Command()
         .name('ktx')
-        .description('KTX data agent context layer CLI')
-        .option('--project-dir <path>', 'KTX project directory (default: KTX_PROJECT_DIR, nearest ktx.yaml, or cwd)')
+        .description('ktx data agent context layer CLI')
+        .option('--project-dir <path>', 'ktx project directory (default: KTX_PROJECT_DIR, nearest ktx.yaml, or cwd)')
         .option('--debug', 'Enable diagnostic logging to stderr')
         .version(`${info.name} ${info.version}`, '-v, --version', 'Show CLI version')
         .helpOption('-h, --help', 'Show this help text')
@@ -349,7 +349,7 @@ export function buildKtxProgram(options) {
         const attachProjectGroup = shouldAttachCommandProjectGroup(path, hasProject);
         telemetry.beginCommandSpan({
             commandPath: path,
-            flagsPresent: collectCommandFlagsPresent(commandNode),
+            flagsPresent: collectCommandFlagsPresent(actionCommand),
             projectDir: attachProjectGroup ? projectDir : undefined,
             hasProject,
             attachProjectGroup,

package/dist/cli-runtime.js

@@ -14,7 +14,7 @@ export function packageInfoFromJson(packageJson) {
         !('version' in packageJson) ||
         typeof packageJson.name !== 'string' ||
         typeof packageJson.version !== 'string') {
-        throw new Error('Invalid KTX CLI package metadata');
+        throw new Error('Invalid ktx CLI package metadata');
     }
     return {
         name: packageJson.name,
@@ -28,7 +28,7 @@ async function runInit(args, io) {
         projectDir: args.projectDir,
         force: args.force,
     });
-    io.stdout.write(`Initialized KTX project at ${result.projectDir}\n`);
+    io.stdout.write(`Initialized ktx project at ${result.projectDir}\n`);
     io.stdout.write(`Config: ${result.configPath}\n`);
     io.stdout.write(`Commit: ${result.commitHash ?? 'none'}\n`);
     return 0;

package/dist/commands/connection-commands.js

@@ -27,7 +27,7 @@ export function registerConnectionCommands(program, context, commandName = 'conn
     connection
         .command('test')
         .description('Test one or all configured connections (default: all)')
-        .argument('[connectionId]', 'KTX connection id to test (omit to test all)')
+        .argument('[connectionId]', 'ktx connection id to test (omit to test all)')
         .option('--all', 'Test every configured connection and print a summary list')
         .action(async (connectionId, options, command) => {
         if (options.all === true && connectionId !== undefined) {

package/dist/commands/ingest-commands.js

@@ -7,16 +7,16 @@ profileMark('module:commands/ingest-commands');
 export function registerIngestCommands(program, context, commandOptions) {
     const ingest = program
         .command('ingest')
-        .description('Build or inspect KTX context, or capture text into memory')
+        .description('Build or inspect ktx context, or capture text into memory')
         .usage('[options] [connectionId]')
         .argument('[connectionId]', 'Configured connection id to ingest (omit to ingest all)')
         .option('--all', 'Ingest all configured connections', false)
         .addOption(new Option('--query-history', 'Include database query-history usage patterns').conflicts('noQueryHistory'))
         .addOption(new Option('--no-query-history', 'Skip database query-history usage patterns'))
         .option('--query-history-window-days <days>', 'Query-history lookback window for this run', parsePositiveIntegerOption)
-        .option('--text <content>', 'Capture inline text into KTX memory; repeatable', collectOption, [])
-        .option('--file <path>', 'Capture a text file into KTX memory; use - for stdin; repeatable', collectOption, [])
-        .option('--connection-id <connectionId>', 'KTX connection id to tag captured text/file notes')
+        .option('--text <content>', 'Capture inline text into ktx memory; repeatable', collectOption, [])
+        .option('--file <path>', 'Capture a text file into ktx memory; use - for stdin; repeatable', collectOption, [])
+        .option('--connection-id <connectionId>', 'ktx connection id to tag captured text/file notes')
         .option('--user-id <id>', 'Memory user id for text/file capture attribution', 'local-cli')
         .option('--fail-fast', 'Stop after the first failed text/file item', false)
         .addOption(new Option('--plain', 'Print plain text output').conflicts(['json']))

package/dist/commands/mcp-commands.js

@@ -13,11 +13,11 @@ function binPath() {
 }
 function formatMcpStartResultMessage(input) {
     return [
-        input.status === 'started' ? `KTX MCP daemon started: ${input.url}` : `KTX MCP daemon already running: ${input.url}`,
+        input.status === 'started' ? `ktx MCP daemon started: ${input.url}` : `ktx MCP daemon already running: ${input.url}`,
         '',
-        'KTX is ready for configured agents.',
-        'Open your agent for this KTX project and ask a data question, for example:',
-        '  "Use KTX to show me the available tables and metrics."',
+        'ktx is ready for configured agents.',
+        'Open your agent for this ktx project and ask a data question, for example:',
+        '  "Use ktx to show me the available tables and metrics."',
         '',
     ].join('\n');
 }
@@ -34,13 +34,13 @@ async function printMcpStatus(context, projectDir) {
 export function registerMcpCommands(program, context) {
     const mcp = program
         .command('mcp')
-        .description('Manage the KTX MCP HTTP server (bare command: show status)')
+        .description('Manage the ktx MCP HTTP server (bare command: show status)')
         .action(async (_options, command) => {
         await printMcpStatus(context, resolveCommandProjectDir(command));
     });
     mcp
         .command('stdio')
-        .description('Run the KTX MCP server over stdio')
+        .description('Run the ktx MCP server over stdio')
         .action(async (_options, command) => {
         await (context.deps.mcp?.runStdioServer ?? runKtxMcpStdioServer)({
             projectDir: resolveCommandProjectDir(command),
@@ -50,7 +50,7 @@ export function registerMcpCommands(program, context) {
     });
     mcp
         .command('start')
-        .description('Start the KTX MCP HTTP server')
+        .description('Start the ktx MCP HTTP server')
         .option('--host <host>', 'Host to bind', '127.0.0.1')
         .option('--port <n>', 'Port to bind', parsePositiveIntegerOption, 7878)
         .option('--token <token>', 'Bearer token required for non-loopback binding')
@@ -78,7 +78,7 @@ export function registerMcpCommands(program, context) {
                 allowedOrigins: options.allowedOrigin,
                 io: context.io,
             });
-            context.io.stdout.write(`KTX MCP server listening at http://${options.host}:${options.port}/mcp\n`);
+            context.io.stdout.write(`ktx MCP server listening at http://${options.host}:${options.port}/mcp\n`);
             return;
         }
         const result = await (context.deps.mcp?.startDaemon ?? startKtxMcpDaemon)({
@@ -95,22 +95,22 @@ export function registerMcpCommands(program, context) {
     });
     mcp
         .command('stop')
-        .description('Stop the KTX MCP daemon')
+        .description('Stop the ktx MCP daemon')
         .action(async (_options, command) => {
         const result = await (context.deps.mcp?.stopDaemon ?? stopKtxMcpDaemon)({
             projectDir: resolveCommandProjectDir(command),
         });
-        context.io.stdout.write(result.status === 'stopped' ? 'KTX MCP daemon stopped.\n' : 'KTX MCP daemon is not running.\n');
+        context.io.stdout.write(result.status === 'stopped' ? 'ktx MCP daemon stopped.\n' : 'ktx MCP daemon is not running.\n');
     });
     mcp
         .command('status')
-        .description('Show KTX MCP daemon status')
+        .description('Show ktx MCP daemon status')
         .action(async (_options, command) => {
         await printMcpStatus(context, resolveCommandProjectDir(command));
     });
     mcp
         .command('logs')
-        .description('Print the KTX MCP daemon log')
+        .description('Print the ktx MCP daemon log')
         .option('--follow', 'Follow log output', false)
         .action(async (options, command) => {
         const logPath = mcpDaemonLayout(resolveCommandProjectDir(command)).logPath;

package/dist/commands/runtime-commands.js

@@ -12,7 +12,7 @@ async function runRuntimeArgs(context, args) {
 export function registerRuntimeCommands(program, context) {
     const runtime = program
         .command('runtime')
-        .description('Install, start, stop, and inspect the KTX-managed Python runtime')
+        .description('Install, start, stop, and inspect the ktx-managed Python runtime')
         .showHelpAfterError();
     runtime
         .command('install')
@@ -30,7 +30,7 @@ export function registerRuntimeCommands(program, context) {
     });
     runtime
         .command('start')
-        .description('Start the KTX daemon')
+        .description('Start the ktx daemon')
         .addOption(createRuntimeFeatureOption())
         .option('--force', 'Restart even when a matching daemon is already running', false)
         .action(async (options, command) => {
@@ -44,8 +44,8 @@ export function registerRuntimeCommands(program, context) {
     });
     runtime
         .command('stop')
-        .description('Stop the KTX daemon')
-        .option('--all', 'Stop all KTX daemon processes recorded or discoverable on this machine', false)
+        .description('Stop the ktx daemon')
+        .option('--all', 'Stop all ktx daemon processes recorded or discoverable on this machine', false)
         .action(async (options, command) => {
         await runRuntimeArgs(context, {
             command: 'stop',

package/dist/commands/setup-commands.js

@@ -1,5 +1,6 @@
 import { InvalidArgumentError, Option } from '@commander-js/extra-typings';
 import { resolveCommandProjectDir } from '../cli-program.js';
+import { isKtxSetupLlmBackend } from '../setup-models.js';
 async function runSetupArgs(context, args) {
     const runner = context.deps.setup ?? (await import('../setup.js')).runKtxSetup;
     context.setExitCode(await runner(args, context.io));
@@ -7,7 +8,7 @@ async function runSetupArgs(context, args) {
 function positiveInteger(value) {
     const parsed = Number.parseInt(value, 10);
     if (!Number.isInteger(parsed) || parsed <= 0) {
-        throw new Error(`Expected a positive integer, received ${value}`);
+        throw new InvalidArgumentError(`Expected a positive integer, received ${value}`);
     }
     return parsed;
 }
@@ -18,7 +19,7 @@ function embeddingBackend(value) {
     throw new InvalidArgumentError(`invalid choice '${value}'`);
 }
 function llmBackend(value) {
-    if (value === 'anthropic' || value === 'vertex' || value === 'claude-code' || value === 'codex') {
+    if (isKtxSetupLlmBackend(value)) {
         return value;
     }
     throw new InvalidArgumentError(`invalid choice '${value}'`);
@@ -83,6 +84,7 @@ function shouldShowSetupEntryMenu(options, command) {
         'target',
         'global',
         'local',
+        'installDir',
         'skipAgents',
         'yes',
         'input',
@@ -125,8 +127,8 @@ function shouldShowSetupEntryMenu(options, command) {
 export function registerSetupCommands(program, context) {
     const setup = program
         .command('setup')
-        .description('Set up or resume a local KTX project')
-        .addOption(new Option('--project-dir <path>', 'KTX project directory').hideHelp())
+        .description('Set up or resume a local ktx project')
+        .addOption(new Option('--project-dir <path>', 'ktx project directory').hideHelp())
         .option('--agents', 'Install agent integration only', false)
         .addOption(new Option('--target <target>', 'Agent target').choices([
         'claude-code',
@@ -138,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')
@@ -184,7 +187,7 @@ export function registerSetupCommands(program, context) {
         .argParser((value, previous) => [...previous, value])
         .default([])
         .hideHelp())
-        .addOption(new Option('--skip-databases', 'Leave database setup incomplete; KTX cannot work until a database is added')
+        .addOption(new Option('--skip-databases', 'Leave database setup incomplete; ktx cannot work until a database is added')
         .hideHelp()
         .default(false))
         .addOption(new Option('--source <type>', 'Source connector type').argParser(sourceType).hideHelp())
@@ -263,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');
@@ -278,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/commands/sl-commands.js

@@ -30,7 +30,7 @@ export function registerSlCommands(program, context, commandName = 'sl') {
         .description('List, search, validate, or query local semantic-layer sources')
         .usage('[options] [query...]')
         .argument('[query...]', 'Search query; omit to list all sources')
-        .option('--connection-id <id>', 'KTX connection id')
+        .option('--connection-id <id>', 'ktx connection id')
         .option('--limit <number>', 'Maximum search results (search mode only)', parsePositiveIntegerOption)
         .addOption(new Option('--output <mode>', 'Output mode: pretty (default in TTY), plain (TSV), or json').choices([
         'pretty',

package/dist/commands/sql-commands.js

@@ -20,7 +20,7 @@ export function registerSqlCommands(program, context) {
         .command('sql')
         .description('Execute parser-validated read-only SQL against a configured connection')
         .argument('<sql...>', 'SQL query to execute')
-        .requiredOption('-c, --connection <id>', 'KTX connection id')
+        .requiredOption('-c, --connection <id>', 'ktx connection id')
         .option('--max-rows <n>', 'Maximum rows to return', parseSqlMaxRowsOption, DEFAULT_MAX_ROWS)
         .addOption(new Option('--output <mode>', 'Output mode: pretty (default), plain (TSV), or json').choices([
         'pretty',

package/dist/commands/status-commands.js

@@ -10,7 +10,7 @@ function inputMode(options) {
 export function registerStatusCommands(program, context) {
     program
         .command('status')
-        .description('Check current KTX setup and project readiness')
+        .description('Check current ktx setup and project readiness')
         .option('--json', 'Print JSON output', false)
         .option('-v, --verbose', 'Show every check, including passing ones', false)
         .option('--validate', 'Only validate the ktx.yaml schema; skip readiness checks', false)

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';
@@ -86,7 +87,7 @@ async function testMetabaseConnection(project, connectionId, createClient) {
 }
 async function createDefaultLookerClient(project, connectionId) {
     const factory = new DefaultLookerConnectionClientFactory(createLocalLookerCredentialResolver(project));
-    return (await factory.createClient(connectionId));
+    return factory.createLookerClient(connectionId);
 }
 async function testLookerConnection(project, connectionId, createClient) {
     const client = await createClient(project, connectionId);
@@ -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;
 }
@@ -432,7 +418,7 @@ export class KtxClickHouseScanConnector {
     }
     assertConnection(connectionId) {
         if (connectionId !== this.connectionId) {
-            throw new Error(`KTX ClickHouse connector ${this.id} cannot serve connection ${connectionId}`);
+            throw new Error(`ktx ClickHouse connector ${this.id} cannot serve connection ${connectionId}`);
         }
     }
 }

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