@kaelio/ktx 0.5.0 → 0.6.0

package/dist/cli-program-telemetry.test.js

@@ -1,89 +0,0 @@
-import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { runCommanderKtxCli } from './cli-program.js';
-function makeIo(stdoutIsTTY = true) {
-    let stdout = '';
-    let stderr = '';
-    return {
-        io: {
-            stdout: {
-                isTTY: stdoutIsTTY,
-                write: (chunk) => {
-                    stdout += chunk;
-                },
-            },
-            stderr: {
-                write: (chunk) => {
-                    stderr += chunk;
-                },
-            },
-        },
-        stdout: () => stdout,
-        stderr: () => stderr,
-    };
-}
-const info = { name: '@kaelio/ktx', version: '0.4.1' };
-describe('runCommanderKtxCli telemetry', () => {
-    let tempDir;
-    const originalEnv = process.env;
-    beforeEach(async () => {
-        tempDir = await mkdtemp(join(tmpdir(), 'ktx-cli-telemetry-'));
-        await writeFile(join(tempDir, 'ktx.yaml'), '{}\n', 'utf-8');
-        vi.stubEnv('KTX_TELEMETRY_DEBUG', '1');
-        vi.stubEnv('HOME', tempDir);
-        vi.stubEnv('CI', '');
-        vi.stubEnv('KTX_TELEMETRY_DISABLED', '');
-        vi.stubEnv('DO_NOT_TRACK', '');
-    });
-    afterEach(async () => {
-        vi.unstubAllEnvs();
-        process.env = originalEnv;
-        await rm(tempDir, { recursive: true, force: true });
-    });
-    it('emits debug command telemetry for registered actions', async () => {
-        const io = makeIo(true);
-        await expect(runCommanderKtxCli(['--project-dir', tempDir, 'status', '--help'], io.io, {}, info, { runInit: async () => 0 })).resolves.toBe(0);
-        expect(io.stderr()).not.toContain('[telemetry]');
-        const statusIo = makeIo(true);
-        const deps = { doctor: async () => 0 };
-        await expect(runCommanderKtxCli(['--project-dir', tempDir, 'status', '--json'], statusIo.io, deps, info, { runInit: async () => 0 })).resolves.toBe(0);
-        expect(statusIo.stderr()).toContain('[telemetry]');
-        expect(statusIo.stderr()).toContain('"event":"install_first_run"');
-        expect(statusIo.stderr()).toContain('"event":"command"');
-        expect(statusIo.stderr()).toContain('"commandPath":["ktx","status"]');
-        expect(statusIo.stderr()).toContain('"event":"project_stack_snapshot"');
-        expect(statusIo.stderr()).toContain('"connectionCount"');
-        expect(statusIo.stderr()).not.toContain(tempDir);
-        const noticeIndex = statusIo.stderr().indexOf('ktx collects anonymous usage data');
-        const firstTelemetryIndex = statusIo.stderr().indexOf('[telemetry]');
-        expect(noticeIndex).toBeGreaterThanOrEqual(0);
-        expect(firstTelemetryIndex).toBeGreaterThan(noticeIndex);
-    });
-    it('emits aborted telemetry when project validation aborts after preAction starts', async () => {
-        const missingProjectDir = join(tempDir, 'missing');
-        await mkdir(missingProjectDir, { recursive: true });
-        const io = makeIo(true);
-        await expect(runCommanderKtxCli(['--project-dir', missingProjectDir, 'connection'], io.io, {}, info, { runInit: async () => 0 })).resolves.toBe(1);
-        expect(io.stderr()).toContain('[telemetry]');
-        expect(io.stderr()).toContain('"outcome":"aborted"');
-        expect(io.stderr()).toContain('"hasProject":false');
-        expect(io.stderr()).toContain('"projectGroupAttached":false');
-        expect(io.stderr()).not.toContain(missingProjectDir);
-    });
-    it('does not import or emit telemetry for help, version, bare non-TTY, or unknown top-level command', async () => {
-        const helpIo = makeIo(true);
-        await expect(runCommanderKtxCli(['--help'], helpIo.io, {}, info, { runInit: async () => 0 })).resolves.toBe(0);
-        expect(helpIo.stderr()).not.toContain('[telemetry]');
-        const versionIo = makeIo(true);
-        await expect(runCommanderKtxCli(['--version'], versionIo.io, {}, info, { runInit: async () => 0 })).resolves.toBe(0);
-        expect(versionIo.stderr()).not.toContain('[telemetry]');
-        const bareIo = makeIo(false);
-        await expect(runCommanderKtxCli([], bareIo.io, {}, info, { runInit: async () => 0 })).resolves.toBe(0);
-        expect(bareIo.stderr()).not.toContain('[telemetry]');
-        const unknownIo = makeIo(true);
-        await expect(runCommanderKtxCli(['unknown'], unknownIo.io, {}, info, { runInit: async () => 0 })).resolves.toBe(1);
-        expect(unknownIo.stderr()).not.toContain('[telemetry]');
-    });
-});

package/dist/cli-program.test.d.ts

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

package/dist/cli-program.test.js

@@ -1,71 +0,0 @@
-import { Command } from '@commander-js/extra-typings';
-import { describe, expect, it } from 'vitest';
-import { buildKtxProgram, collectCommandFlagsPresent } from './cli-program.js';
-function stubIo() {
-    return {
-        stdout: { isTTY: false, columns: 80, write: () => { } },
-        stderr: { write: () => { } },
-    };
-}
-function stubPackageInfo() {
-    return {
-        name: '@kaelio/ktx',
-        version: '0.0.0-test',
-    };
-}
-describe('buildKtxProgram', () => {
-    it('returns a Command named "ktx" with all registered top-level subcommands', () => {
-        const program = buildKtxProgram({
-            io: stubIo(),
-            deps: {},
-            packageInfo: stubPackageInfo(),
-            runInit: async () => 0,
-        });
-        expect(program.name()).toBe('ktx');
-        const topLevel = program.commands.map((command) => command.name()).sort();
-        for (const expected of ['setup', 'connection', 'ingest', 'sl', 'admin']) {
-            expect(topLevel).toContain(expected);
-        }
-    });
-    it('does not parse argv or invoke action handlers', () => {
-        let wrote = '';
-        const io = {
-            stdout: {
-                isTTY: false,
-                columns: 80,
-                write: (chunk) => {
-                    wrote += chunk;
-                },
-            },
-            stderr: {
-                write: (chunk) => {
-                    wrote += chunk;
-                },
-            },
-        };
-        buildKtxProgram({ io, deps: {}, packageInfo: stubPackageInfo(), runInit: async () => 0 });
-        expect(wrote).toBe('');
-    });
-});
-describe('collectCommandFlagsPresent', () => {
-    it('records only CLI-sourced flags and ignores positional content that looks like a flag', async () => {
-        let captured;
-        const program = new Command()
-            .name('ktx')
-            .option('--project-dir <dir>', 'project directory')
-            .option('--json', 'json output', false);
-        program
-            .command('sql')
-            .argument('<sql...>')
-            .requiredOption('-c, --connection <id>', 'connection id')
-            .option('--max-rows <n>', 'cap rows')
-            .action(function () {
-            captured = collectCommandFlagsPresent(this);
-        });
-        await program.parseAsync(['--project-dir', '/tmp/p', 'sql', '-c', 'warehouse', '--', '--customer_table', 'SELECT', '1'], { from: 'user' });
-        expect(captured).toEqual({ projectDir: true, connection: true });
-        expect(captured).not.toHaveProperty('customer_table');
-        expect(captured).not.toHaveProperty('json');
-        expect(captured).not.toHaveProperty('maxRows');
-    });
-});

package/dist/command-tree.test.d.ts

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

package/dist/command-tree.test.js

@@ -1,126 +0,0 @@
-import { Command } from '@commander-js/extra-typings';
-import { describe, expect, it } from 'vitest';
-import { formatCommandTree, walkCommandTree } from './command-tree.js';
-describe('walkCommandTree', () => {
-    it('captures name, description, aliases, and nested children', () => {
-        const root = new Command('root').description('the root');
-        const child = new Command('child').description('a child').alias('c').alias('ch');
-        const grandchild = new Command('grand').description('a grandchild');
-        child.addCommand(grandchild);
-        root.addCommand(child);
-        const tree = walkCommandTree(root);
-        expect(tree).toEqual({
-            name: 'root',
-            description: 'the root',
-            aliases: [],
-            arguments: [],
-            children: [
-                {
-                    name: 'child',
-                    description: 'a child',
-                    aliases: ['c', 'ch'],
-                    arguments: [],
-                    children: [{ name: 'grand', description: 'a grandchild', aliases: [], arguments: [], children: [] }],
-                },
-            ],
-        });
-    });
-    it('returns an empty children array when there are no subcommands', () => {
-        const leaf = new Command('leaf').description('alone');
-        expect(walkCommandTree(leaf)).toEqual({
-            name: 'leaf',
-            description: 'alone',
-            aliases: [],
-            arguments: [],
-            children: [],
-        });
-    });
-    it('uses an empty string when description is unset', () => {
-        const command = new Command('bare');
-        expect(walkCommandTree(command).description).toBe('');
-    });
-    it('captures required, optional, and variadic arguments', () => {
-        const command = new Command('scan')
-            .argument('<connectionId>', 'KTX connection id')
-            .argument('[schemas...]', 'Schemas');
-        expect(walkCommandTree(command).arguments).toEqual(['<connectionId>', '[schemas...]']);
-    });
-    it('walks registered commands without applying hidden-command policy', () => {
-        const root = new Command('ktx');
-        root.command('scan', { hidden: true }).description('Run a standalone connection scan');
-        const ingest = root.command('ingest').description('Build or inspect KTX context');
-        ingest.command('run', { hidden: true }).description('Run local ingest by adapter');
-        ingest.command('watch', { hidden: true }).description('Open a stored visual report');
-        ingest.command('status').description('Print status');
-        root.command('status').description('Check readiness');
-        const tree = walkCommandTree(root);
-        expect(tree.children.map((child) => child.name)).toEqual(['scan', 'ingest', 'status']);
-        expect(tree.children[0]).toMatchObject({
-            name: 'scan',
-            description: 'Run a standalone connection scan',
-            children: [],
-        });
-        expect(tree.children[1]).toMatchObject({
-            name: 'ingest',
-            children: [
-                { name: 'run', description: 'Run local ingest by adapter', aliases: [], arguments: [], children: [] },
-                { name: 'watch', description: 'Open a stored visual report', aliases: [], arguments: [], children: [] },
-                { name: 'status', description: 'Print status', aliases: [], arguments: [], children: [] },
-            ],
-        });
-    });
-});
-describe('formatCommandTree', () => {
-    it('renders a single node with no children', () => {
-        const node = { name: 'solo', description: 'just me', aliases: [], arguments: [], children: [] };
-        expect(formatCommandTree(node)).toMatch(/^solo\s+just me\n$/);
-    });
-    it('renders aliases in parentheses before the description', () => {
-        const node = { name: 'cmd', description: 'does things', aliases: ['c', 'co'], arguments: [], children: [] };
-        expect(formatCommandTree(node)).toMatch(/^cmd \(c, co\)\s+does things\n$/);
-    });
-    it('renders command arguments after the command name', () => {
-        const node = {
-            name: 'test',
-            description: 'Test a configured connection',
-            aliases: [],
-            arguments: ['<connectionId>'],
-            children: [],
-        };
-        expect(formatCommandTree(node)).toMatch(/^test <connectionId>\s+Test a configured connection\n$/);
-    });
-    it('omits the dash when description is empty', () => {
-        const node = { name: 'bare', description: '', aliases: [], arguments: [], children: [] };
-        expect(formatCommandTree(node)).toBe('bare\n');
-    });
-    it('renders tree connectors and preserves sibling registration order', () => {
-        const tree = {
-            name: 'root',
-            description: 'top',
-            aliases: [],
-            arguments: [],
-            children: [
-                {
-                    name: 'beta',
-                    description: 'b',
-                    aliases: [],
-                    arguments: [],
-                    children: [{ name: 'leaf', description: 'l', aliases: [], arguments: [], children: [] }],
-                },
-                {
-                    name: 'alpha',
-                    description: 'a',
-                    aliases: ['al'],
-                    arguments: ['<id>'],
-                    children: [{ name: 'inner', description: 'i', aliases: [], arguments: [], children: [] }],
-                },
-            ],
-        };
-        const lines = formatCommandTree(tree).trimEnd().split('\n');
-        expect(lines[0]).toMatch(/^root\s+top$/);
-        expect(lines[1]).toMatch(/^  ├── beta\s+b$/);
-        expect(lines[2]).toMatch(/^  │   └── leaf\s+l$/);
-        expect(lines[3]).toMatch(/^  └── alpha <id> \(al\)\s+a$/);
-        expect(lines[4]).toMatch(/^      └── inner\s+i$/);
-    });
-});

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

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

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

@@ -1,111 +0,0 @@
-import { Command } from '@commander-js/extra-typings';
-import { describe, expect, it, vi } from 'vitest';
-import { registerMcpCommands } from './mcp-commands.js';
-function makeContext(overrides = {}) {
-    let exitCode = 0;
-    return {
-        io: {
-            stdout: { write: vi.fn() },
-            stderr: { write: vi.fn() },
-        },
-        deps: {},
-        packageInfo: { name: '@kaelio/ktx', version: '0.0.0-test' },
-        setExitCode: (code) => {
-            exitCode = code;
-        },
-        runInit: vi.fn(),
-        writeDebug: vi.fn(),
-        ...overrides,
-        get exitCode() {
-            return exitCode;
-        },
-    };
-}
-describe('registerMcpCommands', () => {
-    it('registers the public mcp lifecycle commands', () => {
-        const program = new Command().exitOverride();
-        registerMcpCommands(program, makeContext());
-        const mcp = program.commands.find((command) => command.name() === 'mcp');
-        expect(mcp?.commands.map((command) => command.name()).sort()).toEqual([
-            'logs',
-            'serve-internal',
-            'start',
-            'status',
-            'stdio',
-            'stop',
-        ]);
-        expect(mcp?.commands.find((command) => command.name() === 'serve-internal')
-            ?._hidden).toBe(true);
-    });
-    it('rejects non-loopback start without token before spawning', async () => {
-        const program = new Command().exitOverride();
-        const startDaemon = vi.fn();
-        const context = makeContext({ deps: { mcp: { startDaemon } } });
-        registerMcpCommands(program, context);
-        await expect(program.parseAsync(['mcp', 'start', '--host', '0.0.0.0'], { from: 'user' })).rejects.toThrow('Binding KTX MCP to 0.0.0.0 requires --token or KTX_MCP_TOKEN');
-        expect(startDaemon).not.toHaveBeenCalled();
-    });
-    it('prints "already running" when startDaemon reports already-running', async () => {
-        const program = new Command().exitOverride().option('--project-dir <path>');
-        const startDaemon = vi.fn().mockResolvedValue({
-            status: 'already-running',
-            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-already',
-                startedAt: '2026-05-14T00:00:00.000Z',
-                logPath: '/tmp/ktx-already/.ktx/logs/mcp.log',
-            },
-        });
-        const context = makeContext({ deps: { mcp: { startDaemon } } });
-        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',
-            '',
-            '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>');
-        const runStdioServer = vi.fn().mockResolvedValue(undefined);
-        const context = makeContext({ deps: { mcp: { runStdioServer } } });
-        registerMcpCommands(program, context);
-        await expect(program.parseAsync(['--project-dir', '/tmp/ktx6', 'mcp', 'stdio'], { from: 'user' })).resolves.toBe(program);
-        expect(runStdioServer).toHaveBeenCalledWith({
-            projectDir: '/tmp/ktx6',
-            cliVersion: '0.0.0-test',
-            io: context.io,
-        });
-    });
-});

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

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

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

@@ -1,68 +0,0 @@
-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: '@kaelio/ktx', version: '0.0.0-test' },
-        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/connection.test.d.ts

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