@kaelio/ktx 0.1.0-rc.5 → 0.1.0

package/dist/setup.test.js

@@ -8,7 +8,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { localFakeBundleReport, persistLocalBundleReport } from './ingest.test-utils.js';
 import { contextBuildCommands, writeKtxSetupContextState } from './setup-context.js';
 import { runDemoTour } from './setup-demo-tour.js';
-import { formatKtxSetupStatus, readKtxSetupStatus, runKtxSetup } from './setup.js';
+import { formatKtxSetupCompletionSummary, formatKtxSetupStatus, readKtxSetupStatus, runKtxSetup } from './setup.js';
 vi.mock('./setup-demo-tour.js', () => ({
     runDemoTour: vi.fn(async () => 0),
 }));
@@ -33,6 +33,41 @@ function makeIo() {
         stderr: () => stderr,
     };
 }
+function runtimeReady(projectDir) {
+    return { status: 'ready', projectDir, requirements: { features: ['core'], requirements: [] } };
+}
+async function writeReadyRuntime(rootDir, cliVersion = '0.2.0') {
+    const runtimeRoot = join(rootDir, '.runtime');
+    const versionDir = join(runtimeRoot, cliVersion);
+    const pythonPath = join(versionDir, '.venv', 'bin', 'python');
+    const daemonPath = join(versionDir, '.venv', 'bin', 'ktx-daemon');
+    await mkdir(join(versionDir, '.venv', 'bin'), { recursive: true });
+    await writeFile(pythonPath, '', 'utf-8');
+    await writeFile(daemonPath, '', 'utf-8');
+    await writeFile(join(versionDir, 'manifest.json'), `${JSON.stringify({
+        schemaVersion: 1,
+        cliVersion,
+        installedAt: '2026-05-09T10:02:00.000Z',
+        asset: {
+            schemaVersion: 1,
+            distributionName: 'kaelio-ktx',
+            normalizedName: 'kaelio_ktx',
+            version: '0.1.0',
+            wheel: {
+                file: 'kaelio_ktx-0.1.0-py3-none-any.whl',
+                sha256: '0'.repeat(64),
+                bytes: 0,
+            },
+        },
+        features: ['core'],
+        python: {
+            executable: pythonPath,
+            daemonExecutable: daemonPath,
+        },
+        installLog: join(versionDir, 'install.log'),
+    }, null, 2)}\n`, 'utf-8');
+    return runtimeRoot;
+}
 describe('setup status', () => {
     let tempDir;
     beforeEach(async () => {
@@ -302,6 +337,98 @@ describe('setup status', () => {
         expect(rendered).toContain('KTX context built: no');
         expect(rendered).not.toContain('No KTX project found.');
     });
+    it('formats a concise ready summary for completed agent setup', () => {
+        const rendered = formatKtxSetupCompletionSummary({
+            project: { path: tempDir, ready: true },
+            llm: { ready: true, model: 'sonnet' },
+            embeddings: { ready: true, model: 'text-embedding-3-small' },
+            databases: [{ connectionId: 'postgres-warehouse', ready: true }],
+            sources: [{ connectionId: 'dbt-main', type: 'dbt', ready: true }],
+            runtime: { required: true, ready: true, features: ['core'] },
+            context: { ready: true, status: 'completed' },
+            agents: [
+                { target: 'claude-code', scope: 'project', ready: true },
+                { target: 'claude-desktop', scope: 'global', ready: true },
+            ],
+        }, {
+            agentNextActions: [
+                '1. Start MCP',
+                '  Run this command before using Claude Code:',
+                '',
+                '  RUN:',
+                `  ktx mcp start --project-dir ${tempDir}`,
+                '',
+                '  If you need to stop MCP later:',
+                `  ktx mcp stop --project-dir ${tempDir}`,
+                '',
+                '2. Open Claude Code',
+                '  Open Claude Code from the KTX project directory:',
+                '',
+                '  RUN:',
+                `  cd '${tempDir}'`,
+                '  claude',
+            ].join('\n'),
+        });
+        expect(rendered).toContain(`Project\n  ${tempDir}`);
+        expect(rendered).toContain('Context\n  built');
+        expect(rendered).toContain('Agents configured\n  Claude Code, Claude Desktop');
+        expect(rendered).toContain('REQUIRED BEFORE USING AGENTS\n\n  1. Start MCP');
+        expect(rendered).toContain('    Run this command before using Claude Code:');
+        expect(rendered).toContain('    RUN:');
+        expect(rendered).toContain('    If you need to stop MCP later:');
+        expect(rendered).toContain(`ktx mcp stop --project-dir ${tempDir}`);
+        expect(rendered).toContain('After that, try\n  Ask your agent: "Use KTX to show me the available tables."');
+        expect(rendered).not.toContain('Verify');
+        expect(rendered).not.toContain('Project ready: yes');
+        expect(rendered).not.toContain('What you can do next');
+    });
+    it('prints agent next actions inside the final ready summary during full setup', async () => {
+        const testIo = makeIo();
+        await expect(runKtxSetup({
+            command: 'run',
+            projectDir: tempDir,
+            mode: 'new',
+            agents: false,
+            target: 'claude-code',
+            skipAgents: false,
+            inputMode: 'disabled',
+            yes: true,
+            cliVersion: '0.2.0',
+            skipLlm: true,
+            skipEmbeddings: true,
+            skipDatabases: true,
+            skipSources: true,
+            databaseSchemas: [],
+        }, testIo.io, {
+            runtime: async () => runtimeReady(tempDir),
+            context: async () => {
+                await writeKtxSetupContextState(tempDir, {
+                    runId: 'setup-context-local-test',
+                    status: 'completed',
+                    primarySourceConnectionIds: [],
+                    contextSourceConnectionIds: [],
+                    reportIds: [],
+                    artifactPaths: [],
+                    retryableFailedTargets: [],
+                    commands: contextBuildCommands(tempDir, 'setup-context-local-test'),
+                });
+                await writeKtxSetupState(tempDir, { completed_steps: ['project', 'context'] });
+                return { status: 'ready', projectDir: tempDir, runId: 'setup-context-local-test' };
+            },
+        })).resolves.toBe(0);
+        const output = testIo.stdout();
+        expect(output).toContain('Claude Code · Project scope');
+        expect(output).toContain(join(tempDir, '.mcp.json'));
+        expect(output).toContain('Requires MCP to be started.');
+        expect(output).toContain('Analytics skill installed.');
+        expect(output).not.toContain('Agent integration complete');
+        expect(output).toContain('Finish KTX agent setup');
+        expect(output).not.toContain('KTX project ready');
+        expect(output).toContain('REQUIRED BEFORE USING AGENTS');
+        expect(output).toContain('Run this command before using Claude Code:');
+        expect(output).toContain(`ktx mcp start --project-dir ${tempDir}`);
+        expect(output).not.toContain('Finish agent setup');
+    });
     it('prints the setup shell intro for auto-created run mode', async () => {
         const testIo = makeIo();
         await expect(runKtxSetup({
@@ -805,7 +932,7 @@ describe('setup status', () => {
             runtimeInstallPolicy: 'never',
         }), io.io);
     });
-    it('auto-installs the managed runtime by default during setup', async () => {
+    it('prompts before installing the managed runtime by default during setup', async () => {
         const io = makeIo();
         const embeddings = vi.fn(async () => ({ status: 'ready', projectDir: tempDir }));
         const context = vi.fn(async () => ({ status: 'failed', projectDir: tempDir }));
@@ -830,11 +957,11 @@ describe('setup status', () => {
         })).resolves.toBe(1);
         expect(embeddings).toHaveBeenCalledWith(expect.objectContaining({
             cliVersion: '0.2.0',
-            runtimeInstallPolicy: 'auto',
+            runtimeInstallPolicy: 'prompt',
         }), io.io);
         expect(context).toHaveBeenCalledWith(expect.objectContaining({
             cliVersion: '0.2.0',
-            runtimeInstallPolicy: 'auto',
+            runtimeInstallPolicy: 'prompt',
         }), io.io);
     });
     it('lets Back from embedding setup return to the model step instead of exiting', async () => {
@@ -1164,6 +1291,10 @@ describe('setup status', () => {
                 calls.push('sources');
                 return { status: 'skipped', projectDir: tempDir };
             },
+            runtime: async () => {
+                calls.push('runtime');
+                return runtimeReady(tempDir);
+            },
             context: async () => {
                 calls.push('context');
                 return { status: 'ready', projectDir: tempDir, runId: 'setup-context-local-test' };
@@ -1177,7 +1308,7 @@ describe('setup status', () => {
                 };
             },
         })).resolves.toBe(0);
-        expect(calls).toEqual(['model', 'embeddings', 'databases', 'sources', 'context', 'agents']);
+        expect(calls).toEqual(['model', 'embeddings', 'databases', 'sources', 'runtime', 'context', 'agents']);
     });
     it('commits setup config changes written by later setup steps', async () => {
         const io = makeIo();
@@ -1205,6 +1336,7 @@ describe('setup status', () => {
                 return { status: 'skipped', projectDir: tempDir };
             },
             sources: async () => ({ status: 'skipped', projectDir: tempDir }),
+            runtime: async () => runtimeReady(tempDir),
             context: async () => ({ status: 'ready', projectDir: tempDir, runId: 'setup-context-local-test' }),
             agents: async () => ({
                 status: 'ready',
@@ -1217,7 +1349,7 @@ describe('setup status', () => {
         const committedConfig = await execFileAsync('git', ['-C', tempDir, 'show', 'HEAD:ktx.yaml']);
         expect(committedConfig.stdout).toContain('warehouse:');
     });
-    it('runs agent setup after context succeeds in --agents mode', async () => {
+    it('runs agent setup without runtime or context in --agents mode', async () => {
         const calls = [];
         const io = makeIo();
         await writeFile(join(tempDir, 'ktx.yaml'), ['connections: {}', ''].join('\n'), 'utf-8');
@@ -1242,9 +1374,13 @@ describe('setup status', () => {
             embeddings: async () => ({ status: 'skipped', projectDir: tempDir }),
             databases: async () => ({ status: 'skipped', projectDir: tempDir }),
             sources: async () => ({ status: 'skipped', projectDir: tempDir }),
+            runtime: async () => {
+                calls.push('runtime');
+                throw new Error('runtime should not run');
+            },
             context: async () => {
                 calls.push('context');
-                return { status: 'ready', projectDir: tempDir, runId: 'setup-context-local-test' };
+                throw new Error('context should not run');
             },
             agents: async () => {
                 calls.push('agents');
@@ -1255,10 +1391,12 @@ describe('setup status', () => {
                 };
             },
         })).resolves.toBe(0);
-        expect(calls).toEqual(['context', 'agents']);
+        expect(calls).toEqual(['agents']);
     });
-    it('does not install agents when non-interactive --agents finds context incomplete', async () => {
+    it('installs agents when non-interactive --agents finds context incomplete', async () => {
         const io = makeIo();
+        const runtime = vi.fn(async () => runtimeReady(tempDir));
+        const context = vi.fn(async () => ({ status: 'skipped', projectDir: tempDir }));
         const agents = vi.fn(async () => ({
             status: 'ready',
             projectDir: tempDir,
@@ -1282,11 +1420,14 @@ describe('setup status', () => {
             skipAgents: false,
             databaseSchemas: [],
         }, io.io, {
-            context: async () => ({ status: 'skipped', projectDir: tempDir }),
+            runtime,
+            context,
             agents,
-        })).resolves.toBe(1);
-        expect(agents).not.toHaveBeenCalled();
-        expect(io.stderr()).toContain('KTX context is not ready for agents.');
+        })).resolves.toBe(0);
+        expect(runtime).not.toHaveBeenCalled();
+        expect(context).not.toHaveBeenCalled();
+        expect(agents).toHaveBeenCalledTimes(1);
+        expect(io.stderr()).not.toContain('KTX context is not ready for agents.');
     });
     it('routes a ready project menu selection to agent setup', async () => {
         const calls = [];
@@ -1309,7 +1450,7 @@ describe('setup status', () => {
             '',
         ].join('\n'), 'utf-8');
         await writeKtxSetupState(tempDir, {
-            completed_steps: ['project', 'llm', 'embeddings', 'sources', 'context', 'agents'],
+            completed_steps: ['project', 'llm', 'embeddings', 'sources', 'runtime', 'context', 'agents'],
         });
         await writeFile(join(tempDir, '.ktx/agents/install-manifest.json'), JSON.stringify({
             version: 1,
@@ -1331,47 +1472,63 @@ describe('setup status', () => {
             retryableFailedTargets: [],
             commands: contextBuildCommands(tempDir, 'setup-context-local-ready'),
         });
-        await expect(runKtxSetup({
-            command: 'run',
-            projectDir: tempDir,
-            mode: 'existing',
-            agents: false,
-            inputMode: 'auto',
-            yes: false,
-            cliVersion: '0.2.0',
-            skipLlm: false,
-            skipEmbeddings: false,
-            skipDatabases: false,
-            skipSources: false,
-            skipAgents: false,
-            databaseSchemas: [],
-        }, io.io, {
-            readyMenuDeps: { prompts: { select: vi.fn(async () => 'agents'), cancel: vi.fn() } },
-            model: async (args) => {
-                expect(args.skipLlm).toBe(true);
-                return { status: 'skipped', projectDir: tempDir };
-            },
-            embeddings: async (args) => {
-                expect(args.skipEmbeddings).toBe(true);
-                return { status: 'skipped', projectDir: tempDir };
-            },
-            databases: async (args) => {
-                expect(args.skipDatabases).toBe(true);
-                return { status: 'skipped', projectDir: tempDir };
-            },
-            sources: async (args) => {
-                expect(args.skipSources).toBe(true);
-                return { status: 'skipped', projectDir: tempDir };
-            },
-            agents: async () => {
-                calls.push('agents');
-                return {
-                    status: 'ready',
-                    projectDir: tempDir,
-                    installs: [{ target: 'codex', scope: 'project', mode: 'mcp-cli' }],
-                };
-            },
-        })).resolves.toBe(0);
+        const previousRuntimeRoot = process.env.KTX_RUNTIME_ROOT;
+        process.env.KTX_RUNTIME_ROOT = await writeReadyRuntime(tempDir);
+        try {
+            await expect(runKtxSetup({
+                command: 'run',
+                projectDir: tempDir,
+                mode: 'existing',
+                agents: false,
+                inputMode: 'auto',
+                yes: false,
+                cliVersion: '0.2.0',
+                skipLlm: false,
+                skipEmbeddings: false,
+                skipDatabases: false,
+                skipSources: false,
+                skipAgents: false,
+                databaseSchemas: [],
+            }, io.io, {
+                readyMenuDeps: { prompts: { select: vi.fn(async () => 'agents'), cancel: vi.fn() } },
+                model: async (args) => {
+                    expect(args.skipLlm).toBe(true);
+                    return { status: 'skipped', projectDir: tempDir };
+                },
+                embeddings: async (args) => {
+                    expect(args.skipEmbeddings).toBe(true);
+                    return { status: 'skipped', projectDir: tempDir };
+                },
+                databases: async (args) => {
+                    expect(args.skipDatabases).toBe(true);
+                    return { status: 'skipped', projectDir: tempDir };
+                },
+                sources: async (args) => {
+                    expect(args.skipSources).toBe(true);
+                    return { status: 'skipped', projectDir: tempDir };
+                },
+                runtime: async () => {
+                    calls.push('runtime');
+                    return runtimeReady(tempDir);
+                },
+                agents: async () => {
+                    calls.push('agents');
+                    return {
+                        status: 'ready',
+                        projectDir: tempDir,
+                        installs: [{ target: 'codex', scope: 'project', mode: 'mcp-cli' }],
+                    };
+                },
+            })).resolves.toBe(0);
+        }
+        finally {
+            if (previousRuntimeRoot === undefined) {
+                delete process.env.KTX_RUNTIME_ROOT;
+            }
+            else {
+                process.env.KTX_RUNTIME_ROOT = previousRuntimeRoot;
+            }
+        }
         expect(calls).toEqual(['agents']);
     });
     it('skips to agent setup when context is ready but agents are not configured', async () => {
@@ -1442,6 +1599,10 @@ describe('setup status', () => {
                 expect(args.skipSources).toBe(true);
                 return { status: 'skipped', projectDir: tempDir };
             },
+            runtime: async () => {
+                calls.push('runtime');
+                return runtimeReady(tempDir);
+            },
             agents: async () => {
                 calls.push('agents');
                 return {
@@ -1454,8 +1615,9 @@ describe('setup status', () => {
         expect(readyMenuSelect).not.toHaveBeenCalled();
         expect(calls).toEqual(['agents']);
     });
-    it('runs only project resolution, context gate, and agent setup in --agents mode', async () => {
+    it('runs only project resolution and agent setup in --agents mode', async () => {
         const io = makeIo();
+        const runtime = vi.fn(async () => runtimeReady(tempDir));
         const context = vi.fn(async () => ({ status: 'ready', projectDir: tempDir, runId: 'setup-context-local-test' }));
         const agents = vi.fn(async () => ({
             status: 'ready',
@@ -1482,10 +1644,12 @@ describe('setup status', () => {
             model: async () => {
                 throw new Error('model should not run');
             },
+            runtime,
             context,
             agents,
         })).resolves.toBe(0);
-        expect(context).toHaveBeenCalledTimes(1);
+        expect(runtime).not.toHaveBeenCalled();
+        expect(context).not.toHaveBeenCalled();
         expect(agents).toHaveBeenCalledTimes(1);
     });
     it('does not run embedding setup when the model step fails', async () => {

package/dist/sl.js

@@ -15,7 +15,7 @@ function slSearchEmbeddingService(project, deps) {
 }
 async function printSlSources(input) {
     const { resolveOutputMode } = await import('./io/mode.js');
-    const { printList } = await import('./io/print-list.js');
+    const { createRankBadgeFormatter, printList } = await import('./io/print-list.js');
     const mode = resolveOutputMode({ explicit: input.output, json: input.json, io: input.io });
     if (input.command === 'sl search') {
         const searchColumns = [
@@ -24,7 +24,7 @@ async function printSlSources(input) {
                 label: 'SCORE',
                 plain: 'score=',
                 role: 'badge',
-                prettyFormat: (value) => `${Math.round(Number(value) * 100)}%`,
+                prettyFormat: createRankBadgeFormatter(input.rows),
                 dim: true,
             },
             { key: 'connectionId', label: 'CONNECTION', plain: '' },

package/dist/sl.test.js

@@ -1,6 +1,7 @@
 import { mkdtemp, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { stripVTControlCharacters } from 'node:util';
 import Database from 'better-sqlite3';
 import { initKtxProject } from '@ktx/context/project';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
@@ -72,6 +73,15 @@ describe('runKtxSl', () => {
             meta: { command: 'sl search' },
         });
     });
+    it('prints semantic-layer search rank badges in pretty output', async () => {
+        const projectDir = join(tempDir, 'rank-project');
+        await seedSlSource({ projectDir });
+        const searchIo = makeIo();
+        await expect(runKtxSl({ command: 'search', projectDir, connectionId: 'warehouse', query: 'order', output: 'pretty' }, searchIo.io)).resolves.toBe(0);
+        const stdout = stripVTControlCharacters(searchIo.stdout());
+        expect(stdout).toMatch(/#1\s+orders/);
+        expect(stdout).not.toContain('%');
+    });
     it('prints semantic-layer list and search as public JSON envelopes', async () => {
         const projectDir = join(tempDir, 'project');
         await seedSlSource({

package/dist/source-mapping.js

@@ -1,5 +1,5 @@
 import { localConnectionToWarehouseDescriptor } from '@ktx/context/connections';
-import { DEFAULT_METABASE_CLIENT_CONFIG, DefaultLookerConnectionClientFactory, DefaultMetabaseConnectionClientFactory, KtxYamlMetabaseSourceStateReader, LocalLookerRuntimeStore, LocalMetabaseDiscoveryCache, computeLookerMappingDrift, computeMetabaseMappingDrift, discoverLookerConnections, discoverMetabaseDatabases, lookerCredentialsFromLocalConnection, metabaseRuntimeConfigFromLocalConnection, seedLocalMappingStateFromKtxYaml, validateLookerMappings, validateMappingPhysicalMatch, } from '@ktx/context/ingest';
+import { DEFAULT_METABASE_CLIENT_CONFIG, DefaultLookerConnectionClientFactory, DefaultMetabaseConnectionClientFactory, KtxYamlMetabaseSourceStateReader, LocalLookerRuntimeStore, LocalMetabaseDiscoveryCache, computeLookerMappingDrift, computeMetabaseMappingDrift, discoverLookerConnections, discoverMetabaseDatabases, lookerCredentialsFromLocalConnection, metabaseRuntimeConfigFromLocalConnection, planMetabaseFanoutChildren, seedLocalMappingStateFromKtxYaml, validateLookerMappings, validateMappingPhysicalMatch, } from '@ktx/context/ingest';
 import { ktxLocalStateDbPath, loadKtxProject } from '@ktx/context/project';
 import { profileMark } from './startup-profile.js';
 profileMark('module:source-mapping');
@@ -126,6 +126,14 @@ export async function runKtxSourceMapping(args, io = process, deps = {}) {
             }
         }
         const rows = await store.listDatabaseMappings(args.connectionId);
+        planMetabaseFanoutChildren({
+            metabaseConnectionId: args.connectionId,
+            mappings: rows.map((row) => ({
+                metabaseDatabaseId: row.metabaseDatabaseId,
+                targetConnectionId: row.targetConnectionId,
+                syncEnabled: row.syncEnabled,
+            })),
+        });
         const failures = rows.flatMap((row) => {
             if (!row.targetConnectionId) {
                 return [];

package/dist/source-mapping.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/source-mapping.test.js

@@ -0,0 +1,65 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { runKtxSourceMapping } from './source-mapping.js';
+function makeIo() {
+    let stdout = '';
+    let stderr = '';
+    return {
+        io: {
+            stdout: {
+                write: (chunk) => {
+                    stdout += chunk;
+                },
+            },
+            stderr: {
+                write: (chunk) => {
+                    stderr += chunk;
+                },
+            },
+        },
+        stdout: () => stdout,
+        stderr: () => stderr,
+    };
+}
+describe('source mapping commands', () => {
+    let tempDir;
+    beforeEach(async () => {
+        tempDir = await mkdtemp(join(tmpdir(), 'ktx-source-mapping-'));
+    });
+    afterEach(async () => {
+        await rm(tempDir, { recursive: true, force: true });
+    });
+    async function writeConfig(metabaseMappings) {
+        await writeFile(join(tempDir, 'ktx.yaml'), [
+            'connections:',
+            '  warehouse:',
+            '    driver: postgres',
+            '    url: env:DATABASE_URL',
+            '  metabase:',
+            '    driver: metabase',
+            '    api_url: https://metabase.example.com',
+            ...metabaseMappings,
+            '',
+        ].join('\n'), 'utf-8');
+    }
+    it('fails Metabase validation when no sync-enabled target mapping exists', async () => {
+        await writeConfig([]);
+        const io = makeIo();
+        await expect(runKtxSourceMapping({ command: 'validate', projectDir: tempDir, connectionId: 'metabase' }, io.io)).resolves.toBe(1);
+        expect(io.stderr()).toContain('no sync-enabled mappings with a target connection for Metabase connection metabase');
+    });
+    it('passes Metabase validation when a sync-enabled target mapping exists', async () => {
+        await writeConfig([
+            '    mappings:',
+            '      databaseMappings:',
+            '        "3": warehouse',
+            '      syncEnabled:',
+            '        "3": true',
+        ]);
+        const io = makeIo();
+        await expect(runKtxSourceMapping({ command: 'validate', projectDir: tempDir, connectionId: 'metabase' }, io.io)).resolves.toBe(0);
+        expect(io.stdout()).toContain('Mapping validation passed: metabase');
+    });
+});

package/dist/sql.d.ts

@@ -0,0 +1,22 @@
+import { loadKtxProject } from '@ktx/context/project';
+import type { SqlAnalysisPort } from '@ktx/context/sql-analysis';
+import type { KtxCliIo } from './cli-runtime.js';
+import { createKtxCliScanConnector } from './local-scan-connectors.js';
+type KtxSqlOutputMode = 'pretty' | 'plain' | 'json';
+export type KtxSqlArgs = {
+    command: 'execute';
+    projectDir: string;
+    connectionId: string;
+    sql: string;
+    maxRows: number;
+    output?: KtxSqlOutputMode;
+    json?: boolean;
+    cliVersion: string;
+};
+export interface KtxSqlDeps {
+    loadProject?: typeof loadKtxProject;
+    createSqlAnalysis?: () => SqlAnalysisPort;
+    createScanConnector?: typeof createKtxCliScanConnector;
+}
+export declare function runKtxSql(args: KtxSqlArgs, io?: KtxCliIo, deps?: KtxSqlDeps): Promise<number>;
+export {};