@kaelio/ktx 0.1.0-rc.5 → 0.1.0

package/assets/python/manifest.json

@@ -5,7 +5,7 @@
   "version": "0.1.0",
   "wheel": {
     "file": "kaelio_ktx-0.1.0-py3-none-any.whl",
-    "sha256": "1fd656c8a79c1222ea277b038a8ff915b2c5f88ecebc64d3ecc50c22c7fc9f0f",
-    "bytes": 80300
+    "sha256": "1145cf0c90879270dc335a8d0ca49a598f81e0f47a37fdf646fc6c6798fe3c8b",
+    "bytes": 80523
   }
 }

package/dist/clack.d.ts

@@ -4,6 +4,11 @@ export interface KtxCliSpinner {
     stop(message: string): void;
     error(message: string): void;
 }
+export interface KtxCliSpinnerIo {
+    stderr: {
+        write(chunk: string): void;
+    };
+}
 export interface KtxCliPromptAdapter {
     confirm(options: {
         message: string;
@@ -23,4 +28,5 @@ export declare class KtxCliPromptCancelledError extends Error {
     constructor(message?: string);
 }
 export declare function createClackSpinner(): KtxCliSpinner;
+export declare function createStaticCliSpinner(io: KtxCliSpinnerIo): KtxCliSpinner;
 export declare function createClackPromptAdapter(): KtxCliPromptAdapter;

package/dist/clack.js

@@ -1,4 +1,5 @@
 import { cancel, confirm, isCancel, log, spinner } from '@clack/prompts';
+const ESC = String.fromCharCode(0x1b);
 export class KtxCliPromptCancelledError extends Error {
     constructor(message = 'Operation cancelled.') {
         super(message);
@@ -8,6 +9,28 @@ export class KtxCliPromptCancelledError extends Error {
 export function createClackSpinner() {
     return spinner();
 }
+function magenta(text) {
+    return `${ESC}[35m${text}${ESC}[39m`;
+}
+function red(text) {
+    return `${ESC}[31m${text}${ESC}[39m`;
+}
+export function createStaticCliSpinner(io) {
+    return {
+        start(message) {
+            io.stderr.write(`${magenta('◐')}  ${message}\n`);
+        },
+        message(message) {
+            io.stderr.write(`${magenta('│')}  ${message}\n`);
+        },
+        stop(message) {
+            io.stderr.write(`${magenta('◇')}  ${message}\n`);
+        },
+        error(message) {
+            io.stderr.write(`${red('■')}  ${message}\n`);
+        },
+    };
+}
 export function createClackPromptAdapter() {
     return {
         async confirm(options) {

package/dist/cli-program.js

@@ -7,13 +7,15 @@ import { registerWikiCommands } from './commands/knowledge-commands.js';
 import { registerMcpCommands } from './commands/mcp-commands.js';
 import { registerSetupCommands } from './commands/setup-commands.js';
 import { registerSlCommands } from './commands/sl-commands.js';
+import { registerSqlCommands } from './commands/sql-commands.js';
 import { registerStatusCommands } from './commands/status-commands.js';
 import { registerDevCommands } from './dev.js';
 import { renderMissingProjectMessage } from './doctor.js';
 import { findNearestKtxProjectDir, resolveKtxProjectDir } from './project-resolver.js';
 import { profileMark, profileSpan } from './startup-profile.js';
 profileMark('module:cli-program');
-const PROJECT_AWARE_ROOT_COMMANDS = new Set(['setup', 'connection', 'ingest', 'wiki', 'sl', 'status', 'mcp']);
+const PROJECT_AWARE_ROOT_COMMANDS = new Set(['setup', 'connection', 'ingest', 'wiki', 'sl', 'sql', 'status', 'mcp']);
+const PROJECT_INDEPENDENT_DEV_COMMANDS = new Set(['runtime', 'schema']);
 const COMMANDS_THAT_CREATE_PROJECT = new Set(['setup', 'ktx dev init']);
 const COMMANDS_WITH_OWN_MISSING_PROJECT_HANDLING = new Set(['status']);
 const GLOBAL_OPTIONS_WITH_VALUE = new Set(['--project-dir']);
@@ -104,7 +106,7 @@ function isProjectAwareCommand(path) {
     }
     const rootCommand = path[1];
     if (rootCommand === 'dev') {
-        return path[2] !== undefined && path[2] !== 'runtime';
+        return path[2] !== undefined && !PROJECT_INDEPENDENT_DEV_COMMANDS.has(path[2]);
     }
     return rootCommand !== undefined && PROJECT_AWARE_ROOT_COMMANDS.has(rootCommand);
 }
@@ -310,6 +312,7 @@ export function buildKtxProgram(options) {
     });
     registerWikiCommands(program, context);
     registerSlCommands(program, context);
+    registerSqlCommands(program, context);
     registerStatusCommands(program, context);
     registerMcpCommands(program, context);
     registerDevCommands(program, context);

package/dist/cli-program.test.js

@@ -7,7 +7,13 @@ function stubIo() {
     };
 }
 function stubPackageInfo() {
-    return { name: '@ktx/cli', version: '0.0.0-test', contextPackageName: '@ktx/context' };
+    return {
+        name: '@ktx/cli',
+        version: '0.0.0-test',
+        packageVersion: '0.0.0-private',
+        runtimeVersion: '0.0.0-test',
+        contextPackageName: '@ktx/context',
+    };
 }
 describe('buildKtxProgram', () => {
     it('returns a Command named "ktx" with all registered top-level subcommands', () => {

package/dist/cli-runtime.d.ts

@@ -5,10 +5,13 @@ import type { KtxPublicIngestArgs } from './public-ingest.js';
 import type { KtxRuntimeArgs } from './runtime.js';
 import type { KtxSetupArgs } from './setup.js';
 import type { KtxSlArgs } from './sl.js';
+import type { KtxSqlArgs } from './sql.js';
 import type { KtxTextIngestArgs } from './text-ingest.js';
 export interface KtxCliPackageInfo {
     name: string;
     version: string;
+    packageVersion: string;
+    runtimeVersion: string;
     contextPackageName: '@ktx/context';
 }
 export interface KtxCliIo {
@@ -30,6 +33,7 @@ export interface KtxCliDeps {
     runtime?: (args: KtxRuntimeArgs, io: KtxCliIo) => Promise<number>;
     knowledge?: (args: KtxKnowledgeArgs, io: KtxCliIo) => Promise<number>;
     sl?: (args: KtxSlArgs, io: KtxCliIo) => Promise<number>;
+    sql?: (args: KtxSqlArgs, io: KtxCliIo) => Promise<number>;
     mcp?: {
         startDaemon?: typeof import('./managed-mcp-daemon.js').startKtxMcpDaemon;
         stopDaemon?: typeof import('./managed-mcp-daemon.js').stopKtxMcpDaemon;

package/dist/cli-runtime.js

@@ -1,5 +1,6 @@
 import { createRequire } from 'node:module';
 import { profileMark, profileSpan } from './startup-profile.js';
+import { resolveKtxRuntimeVersion } from './release-version.js';
 profileMark('module:cli-runtime');
 const requirePackageJson = createRequire(import.meta.url);
 export function getKtxCliPackageInfo() {
@@ -14,9 +15,15 @@ export function packageInfoFromJson(packageJson) {
         typeof packageJson.version !== 'string') {
         throw new Error('Invalid KTX CLI package metadata');
     }
+    const runtimeVersion = resolveKtxRuntimeVersion({
+        packageName: packageJson.name,
+        packageVersion: packageJson.version,
+    });
     return {
         name: packageJson.name,
-        version: packageJson.version,
+        version: runtimeVersion,
+        packageVersion: packageJson.version,
+        runtimeVersion,
         contextPackageName: '@ktx/context',
     };
 }

package/dist/command-schemas.d.ts

@@ -26,9 +26,9 @@ export declare const slQueryCommandSchema: z.ZodObject<{
     execute: z.ZodBoolean;
     cliVersion: z.ZodString;
     runtimeInstallPolicy: z.ZodEnum<{
-        auto: "auto";
         never: "never";
         prompt: "prompt";
+        auto: "auto";
     }>;
     maxRows: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;

package/dist/commands/ingest-commands.js

@@ -17,6 +17,7 @@ export function registerIngestCommands(program, context, commandOptions) {
         .option('--query-history-window-days <days>', 'Query-history lookback window for this run', parsePositiveIntegerOption)
         .addOption(new Option('--plain', 'Print plain text output').conflicts(['json']))
         .addOption(new Option('--json', 'Print JSON output').conflicts(['plain']))
+        .option('--yes', 'Install required managed runtime features without prompting')
         .option('--no-input', 'Disable interactive terminal input')
         .showHelpAfterError();
     ingest.action(async (connectionId, options, command) => {

package/dist/commands/knowledge-commands.js

@@ -6,6 +6,10 @@ async function runKnowledgeArgs(context, args) {
     const runner = context.deps.knowledge ?? (await import('../knowledge.js')).runKtxKnowledge;
     context.setExitCode(await runner(args, context.io));
 }
+function isDebugEnabled(command) {
+    const options = (command.optsWithGlobals ? command.optsWithGlobals() : command.opts());
+    return options.debug === true;
+}
 export function registerWikiCommands(program, context) {
     const wiki = program
         .command('wiki')
@@ -51,6 +55,7 @@ export function registerWikiCommands(program, context) {
             userId: options.userId,
             output: options.output,
             json: options.json,
+            ...(isDebugEnabled(command) ? { debug: true } : {}),
             ...(options.limit !== undefined ? { limit: options.limit } : {}),
         });
     });

package/dist/commands/mcp-commands.js

@@ -11,6 +11,16 @@ function tokenFromOption(value) {
 function binPath() {
     return fileURLToPath(new URL('../bin.js', import.meta.url));
 }
+function formatMcpStartResultMessage(input) {
+    return [
+        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."',
+        '',
+    ].join('\n');
+}
 export function registerMcpCommands(program, context) {
     const mcp = program.command('mcp').description('Run the KTX MCP HTTP server');
     mcp
@@ -66,9 +76,7 @@ export function registerMcpCommands(program, context) {
             allowedOrigins: options.allowedOrigin,
             binPath: binPath(),
         });
-        context.io.stdout.write(result.status === 'started'
-            ? `KTX MCP daemon started: ${result.url}\n`
-            : `KTX MCP daemon already running: ${result.url}\n`);
+        context.io.stdout.write(formatMcpStartResultMessage({ status: result.status, url: result.url }));
     });
     mcp
         .command('stop')

package/dist/commands/mcp-commands.test.js

@@ -65,7 +65,36 @@ describe('registerMcpCommands', () => {
         registerMcpCommands(program, context);
         await program.parseAsync(['--project-dir', '/tmp/ktx-already', 'mcp', 'start'], { from: 'user' });
         expect(startDaemon).toHaveBeenCalledTimes(1);
-        expect(context.io.stdout.write).toHaveBeenCalledWith('KTX MCP daemon already running: http://127.0.0.1:7878/mcp\n');
+        expect(context.io.stdout.write).toHaveBeenCalledWith([
+            'KTX MCP daemon already running: http://127.0.0.1:7878/mcp',
+            '',
+            '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'));
+    });
+    it('prints a friendly next step after starting the daemon', async () => {
+        const program = new Command().exitOverride().option('--project-dir <path>');
+        const startDaemon = vi.fn().mockResolvedValue({
+            status: 'started',
+            url: 'http://127.0.0.1:7878/mcp',
+            state: {
+                schemaVersion: 1,
+                pid: 4242,
+                host: '127.0.0.1',
+                port: 7878,
+                tokenAuth: false,
+                projectDir: '/tmp/ktx-started',
+                startedAt: '2026-05-14T00:00:00.000Z',
+                logPath: '/tmp/ktx-started/.ktx/logs/mcp.log',
+            },
+        });
+        const context = makeContext({ deps: { mcp: { startDaemon } } });
+        registerMcpCommands(program, context);
+        await program.parseAsync(['--project-dir', '/tmp/ktx-started', 'mcp', 'start'], { from: 'user' });
+        expect(context.io.stdout.write).toHaveBeenCalledWith(expect.stringContaining('KTX MCP daemon started: http://127.0.0.1:7878/mcp\n\nKTX is ready for configured agents.'));
+        expect(context.io.stdout.write).toHaveBeenCalledWith(expect.stringContaining('"Use KTX to show me the available tables and metrics."'));
     });
     it('runs the stdio server with the resolved project directory', async () => {
         const program = new Command().exitOverride().option('--project-dir <path>');

package/dist/commands/sql-commands.d.ts

@@ -0,0 +1,3 @@
+import { type Command } from '@commander-js/extra-typings';
+import { type KtxCliCommandContext } from '../cli-program.js';
+export declare function registerSqlCommands(program: Command, context: KtxCliCommandContext): void;

package/dist/commands/sql-commands.js

@@ -0,0 +1,43 @@
+import { InvalidArgumentError, Option } from '@commander-js/extra-typings';
+import { resolveCommandProjectDir } from '../cli-program.js';
+import { profileMark } from '../startup-profile.js';
+profileMark('module:commands/sql-commands');
+const DEFAULT_MAX_ROWS = 1000;
+const MAX_ROWS_CAP = 10_000;
+function parseSqlMaxRowsOption(value) {
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 1 || parsed > MAX_ROWS_CAP) {
+        throw new InvalidArgumentError(`must be an integer between 1 and ${MAX_ROWS_CAP}`);
+    }
+    return parsed;
+}
+async function runSqlArgs(context, args) {
+    const runner = context.deps.sql ?? (await import('../sql.js')).runKtxSql;
+    context.setExitCode(await runner(args, context.io));
+}
+export function registerSqlCommands(program, context) {
+    program
+        .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')
+        .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',
+        'plain',
+        'json',
+    ]))
+        .option('--json', 'Shortcut for --output=json (overrides --output)', false)
+        .action(async (sqlParts, options, command) => {
+        await runSqlArgs(context, {
+            command: 'execute',
+            projectDir: resolveCommandProjectDir(command),
+            connectionId: options.connection,
+            sql: sqlParts.join(' '),
+            maxRows: options.maxRows,
+            output: options.output,
+            json: options.json === true,
+            cliVersion: context.packageInfo.version,
+        });
+    });
+}

package/dist/commands/sql-commands.test.d.ts

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

package/dist/commands/sql-commands.test.js

@@ -0,0 +1,68 @@
+import { Command } from '@commander-js/extra-typings';
+import { describe, expect, it, vi } from 'vitest';
+import { registerSqlCommands } from './sql-commands.js';
+function makeContext(overrides = {}) {
+    let exitCode = 0;
+    return {
+        io: {
+            stdout: { write: vi.fn() },
+            stderr: { write: vi.fn() },
+        },
+        deps: {},
+        packageInfo: { name: '@ktx/cli', version: '0.0.0-test', contextPackageName: '@ktx/context' },
+        setExitCode: (code) => {
+            exitCode = code;
+        },
+        runInit: vi.fn(),
+        writeDebug: vi.fn(),
+        ...overrides,
+        get exitCode() {
+            return exitCode;
+        },
+    };
+}
+describe('registerSqlCommands', () => {
+    it('routes positional SQL through the sql runner', async () => {
+        const program = new Command().exitOverride().option('--project-dir <path>');
+        const sql = vi.fn(async () => 0);
+        const context = makeContext({ deps: { sql } });
+        registerSqlCommands(program, context);
+        await expect(program.parseAsync(['--project-dir', '/tmp/ktx-sql', 'sql', '--connection', 'warehouse', 'select', '1'], { from: 'user' })).resolves.toBe(program);
+        expect(sql).toHaveBeenCalledWith({
+            command: 'execute',
+            projectDir: '/tmp/ktx-sql',
+            connectionId: 'warehouse',
+            sql: 'select 1',
+            maxRows: 1000,
+            output: undefined,
+            json: false,
+            cliVersion: '0.0.0-test',
+        }, context.io);
+    });
+    it('supports the short connection flag', async () => {
+        const program = new Command().exitOverride().option('--project-dir <path>');
+        const sql = vi.fn(async () => 0);
+        const context = makeContext({ deps: { sql } });
+        registerSqlCommands(program, context);
+        await expect(program.parseAsync(['--project-dir', '/tmp/ktx-sql', 'sql', '-c', 'warehouse', 'select 1'], {
+            from: 'user',
+        })).resolves.toBe(program);
+        expect(sql).toHaveBeenCalledWith(expect.objectContaining({ connectionId: 'warehouse', sql: 'select 1' }), context.io);
+    });
+    it('rejects missing SQL before invoking the runner', async () => {
+        const program = new Command().exitOverride().option('--project-dir <path>');
+        const sql = vi.fn(async () => 0);
+        registerSqlCommands(program, makeContext({ deps: { sql } }));
+        await expect(program.parseAsync(['--project-dir', '/tmp/ktx-sql', 'sql', '--connection', 'warehouse'], {
+            from: 'user',
+        })).rejects.toThrow('missing required argument');
+        expect(sql).not.toHaveBeenCalled();
+    });
+    it('rejects maxRows above the CLI cap', async () => {
+        const program = new Command().exitOverride().option('--project-dir <path>');
+        const sql = vi.fn(async () => 0);
+        registerSqlCommands(program, makeContext({ deps: { sql } }));
+        await expect(program.parseAsync(['--project-dir', '/tmp/ktx-sql', 'sql', '--connection', 'warehouse', '--max-rows', '10001', 'select 1'], { from: 'user' })).rejects.toThrow('must be an integer between 1 and 10000');
+        expect(sql).not.toHaveBeenCalled();
+    });
+});

package/dist/context-build-view.js

@@ -533,6 +533,9 @@ function failedStepDetail(result) {
 }
 const INTERNAL_FAILURE_LINE_RE = /^(Report|Run|Job|Status|Adapter|Connection|Sync|Mode|Dry run|Diff|Tasks|Work units|Failed tasks|Saved memory|Provenance rows):\s*/;
 const ACTIONABLE_FAILURE_LINE_RE = /^(Missing bundled Python runtime manifest|KTX Python runtime is required|KTX managed daemon|Error:|Failed\b|Could not\b|Cannot\b)/;
+function trimErrorPrefix(line) {
+    return line.replace(/^Error:\s*/, '');
+}
 function firstCapturedFailureLine(output) {
     const lines = (output ?? '')
         .split(/\r?\n/)
@@ -540,7 +543,8 @@ function firstCapturedFailureLine(output) {
         .filter((candidate) => candidate.length > 0)
         .filter((candidate) => !candidate.startsWith('KTX scan completed'))
         .filter((candidate) => !INTERNAL_FAILURE_LINE_RE.test(candidate));
-    return lines.find((candidate) => ACTIONABLE_FAILURE_LINE_RE.test(candidate)) ?? lines.at(-1) ?? null;
+    const line = lines.find((candidate) => ACTIONABLE_FAILURE_LINE_RE.test(candidate)) ?? lines.at(-1) ?? null;
+    return line ? trimErrorPrefix(line) : null;
 }
 function isGenericFailedAtDetail(target, detail) {
     return new RegExp(`^${target.connectionId} failed at [a-z-]+\\.?(?: Retry: .*)?$`).test(detail ?? '');

package/dist/dev.test.js

@@ -88,6 +88,33 @@ describe('dev Commander tree', () => {
             await rm(tempDir, { recursive: true, force: true });
         }
     });
+    it('prints config schema without requiring a KTX project directory', async () => {
+        const { mkdtemp, rm } = await import('node:fs/promises');
+        const { tmpdir } = await import('node:os');
+        const { join } = await import('node:path');
+        const tempDir = await mkdtemp(join(tmpdir(), 'ktx-dev-schema-'));
+        const missingProjectDir = join(tempDir, 'missing-project');
+        const originalProjectDir = process.env.KTX_PROJECT_DIR;
+        const testIo = makeIo();
+        try {
+            process.env.KTX_PROJECT_DIR = missingProjectDir;
+            await expect(runKtxCli(['dev', 'schema'], testIo.io)).resolves.toBe(0);
+            expect(JSON.parse(testIo.stdout())).toMatchObject({
+                title: 'ktx.yaml',
+                type: 'object',
+            });
+            expect(testIo.stderr()).toBe('');
+        }
+        finally {
+            if (originalProjectDir === undefined) {
+                delete process.env.KTX_PROJECT_DIR;
+            }
+            else {
+                process.env.KTX_PROJECT_DIR = originalProjectDir;
+            }
+            await rm(tempDir, { recursive: true, force: true });
+        }
+    });
     it('rejects removed dev command groups', async () => {
         for (const argv of [
             ['dev', 'doctor', 'setup'],

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export { runKtxSetupEmbeddingsStep } from './setup-embeddings.js';
 export type { KtxSetupSourcesArgs, KtxSetupSourcesDeps, KtxSetupSourcesPromptAdapter, KtxSetupSourcesResult, KtxSetupSourceType, } from './setup-sources.js';
 export { runKtxSetupSourcesStep } from './setup-sources.js';
 export { runKtxRuntime, type KtxRuntimeArgs, type KtxRuntimeDeps } from './runtime.js';
+export { runKtxSql, type KtxSqlArgs, type KtxSqlDeps } from './sql.js';
 export { allocateDaemonPort, readManagedPythonDaemonStatus, stopAllManagedPythonDaemons, startManagedPythonDaemon, stopManagedPythonDaemon, } from './managed-python-daemon.js';
 export type { ManagedPythonDaemonProcessInfo, ManagedPythonDaemonStartResult, ManagedPythonDaemonState, ManagedPythonDaemonStatus, ManagedPythonDaemonStopAllEntry, ManagedPythonDaemonStopAllFailure, ManagedPythonDaemonStopAllResult, ManagedPythonDaemonStopResult, } from './managed-python-daemon.js';
 export { ensureManagedLocalEmbeddingsDaemon, managedLocalEmbeddingHealthConfig, managedLocalEmbeddingProjectConfig, type ManagedLocalEmbeddingsDaemon, type ManagedLocalEmbeddingsOptions, } from './managed-local-embeddings.js';

package/dist/index.js

@@ -5,6 +5,7 @@ export { runKtxSetupDatabasesStep } from './setup-databases.js';
 export { runKtxSetupEmbeddingsStep } from './setup-embeddings.js';
 export { runKtxSetupSourcesStep } from './setup-sources.js';
 export { runKtxRuntime } from './runtime.js';
+export { runKtxSql } from './sql.js';
 export { allocateDaemonPort, readManagedPythonDaemonStatus, stopAllManagedPythonDaemons, startManagedPythonDaemon, stopManagedPythonDaemon, } from './managed-python-daemon.js';
 export { ensureManagedLocalEmbeddingsDaemon, managedLocalEmbeddingHealthConfig, managedLocalEmbeddingProjectConfig, } from './managed-local-embeddings.js';
 export { renderMemoryFlowTui, sanitizeMemoryFlowTuiError, startLiveMemoryFlowTui, } from './memory-flow-tui.js';