@kaelio/ktx 0.0.0 → 0.1.0-rc.1

package/dist/setup-prompts.js

@@ -0,0 +1,88 @@
+import { cancel, confirm, intro, isCancel, log, multiselect, note, password, select, text, } from '@clack/prompts';
+import { withMenuOptionsSpacing, withTextInputNavigation } from './prompt-navigation.js';
+import { withSetupInterruptConfirmation } from './setup-interrupt.js';
+const DEFAULT_SETUP_CANCEL_MESSAGE = 'Setup cancelled.';
+export function createKtxSetupPromptAdapter(options) {
+    const cancelMessage = options.cancelMessage ?? DEFAULT_SETUP_CANCEL_MESSAGE;
+    const cancelOnSelectCancel = options.cancelOnSelectCancel ?? true;
+    const cancelOnMultiselectCancel = options.cancelOnMultiselectCancel ?? true;
+    const multiselectCancelValue = options.multiselectCancelValue ?? 'back';
+    return {
+        async select(promptOptions) {
+            const value = await withSetupInterruptConfirmation(() => select(withMenuOptionsSpacing(promptOptions)));
+            if (isCancel(value)) {
+                if (cancelOnSelectCancel) {
+                    cancel(cancelMessage);
+                }
+                return options.selectCancelValue;
+            }
+            return String(value);
+        },
+        async multiselect(promptOptions) {
+            while (true) {
+                const value = await withSetupInterruptConfirmation(() => multiselect(withMenuOptionsSpacing(promptOptions)));
+                if (isCancel(value)) {
+                    if (cancelOnMultiselectCancel) {
+                        cancel(cancelMessage);
+                    }
+                    return [multiselectCancelValue];
+                }
+                const selected = [...value].map(String);
+                if (selected.length === 0 &&
+                    !promptOptions.required &&
+                    options.confirmEmptyOptionalMultiselect === true) {
+                    const skipConfirmed = await confirm({
+                        message: 'Nothing selected. Skip this step?',
+                        initialValue: false,
+                    });
+                    if (isCancel(skipConfirmed)) {
+                        cancel(cancelMessage);
+                        return [multiselectCancelValue];
+                    }
+                    if (!skipConfirmed) {
+                        continue;
+                    }
+                }
+                return selected;
+            }
+        },
+        async text(promptOptions) {
+            const value = await withSetupInterruptConfirmation(() => text({ ...promptOptions, message: withTextInputNavigation(promptOptions.message) }));
+            return isCancel(value) ? undefined : String(value);
+        },
+        async password(promptOptions) {
+            const value = await withSetupInterruptConfirmation(() => password({ ...promptOptions, message: withTextInputNavigation(promptOptions.message) }));
+            return isCancel(value) ? undefined : String(value);
+        },
+        cancel(message) {
+            cancel(message);
+        },
+        log(message) {
+            log.info(message);
+        },
+    };
+}
+function isWritableTtyOutput(output) {
+    return (output.isTTY === true &&
+        typeof output.on === 'function' &&
+        typeof output.columns !== 'undefined');
+}
+export function createKtxSetupUiAdapter() {
+    return {
+        intro(title, io) {
+            if (isWritableTtyOutput(io.stdout)) {
+                intro(title, { output: io.stdout });
+                return;
+            }
+            io.stdout.write(`${title}\n`);
+        },
+        note(message, title, io) {
+            if (isWritableTtyOutput(io.stdout)) {
+                note(message, title, { output: io.stdout });
+                return;
+            }
+            io.stdout.write(`\n${title}:\n`);
+            io.stdout.write(`${message}\n`);
+        },
+    };
+}

package/dist/setup-prompts.test.d.ts

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

package/dist/setup-prompts.test.js

@@ -0,0 +1,170 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { createKtxSetupPromptAdapter, } from './setup-prompts.js';
+const mocks = vi.hoisted(() => {
+    const cancelSymbol = Symbol('cancel');
+    return {
+        cancelSymbol,
+        cancel: vi.fn(),
+        confirm: vi.fn(),
+        intro: vi.fn(),
+        isCancel: vi.fn((value) => value === cancelSymbol),
+        log: { info: vi.fn() },
+        multiselect: vi.fn(),
+        note: vi.fn(),
+        password: vi.fn(),
+        select: vi.fn(),
+        text: vi.fn(),
+        withSetupInterruptConfirmation: vi.fn((prompt) => prompt()),
+    };
+});
+vi.mock('@clack/prompts', () => ({
+    cancel: mocks.cancel,
+    confirm: mocks.confirm,
+    intro: mocks.intro,
+    isCancel: mocks.isCancel,
+    log: mocks.log,
+    multiselect: mocks.multiselect,
+    note: mocks.note,
+    password: mocks.password,
+    select: mocks.select,
+    text: mocks.text,
+}));
+vi.mock('./setup-interrupt.js', () => ({
+    withSetupInterruptConfirmation: mocks.withSetupInterruptConfirmation,
+}));
+describe('setup prompt adapter', () => {
+    beforeEach(() => {
+        mocks.cancel.mockReset();
+        mocks.confirm.mockReset();
+        mocks.intro.mockReset();
+        mocks.isCancel.mockClear();
+        mocks.log.info.mockReset();
+        mocks.multiselect.mockReset();
+        mocks.note.mockReset();
+        mocks.password.mockReset();
+        mocks.select.mockReset();
+        mocks.text.mockReset();
+        mocks.withSetupInterruptConfirmation.mockClear();
+    });
+    it('passes select hint and disabled options through Clack and delegates cancellation handling', async () => {
+        mocks.select.mockResolvedValueOnce('openai');
+        const adapter = createKtxSetupPromptAdapter({ selectCancelValue: 'back' });
+        const options = [
+            { value: 'local', label: 'Local embeddings', disabled: true },
+            { value: 'openai', label: 'OpenAI embeddings', hint: 'recommended' },
+        ];
+        await expect(adapter.select({
+            message: 'Which embedding option should KTX use?\n\nKTX uses embeddings for search.',
+            options,
+        })).resolves.toBe('openai');
+        expect(mocks.withSetupInterruptConfirmation).toHaveBeenCalledTimes(1);
+        expect(mocks.select).toHaveBeenCalledWith({
+            message: 'Which embedding option should KTX use?\n\nKTX uses embeddings for search.\n',
+            options,
+        });
+    });
+    it('maps select cancellation to the configured sentinel', async () => {
+        mocks.select.mockResolvedValueOnce(mocks.cancelSymbol);
+        const adapter = createKtxSetupPromptAdapter({
+            selectCancelValue: 'exit',
+            cancelOnSelectCancel: false,
+        });
+        await expect(adapter.select({ message: 'What do you want to do?', options: [] })).resolves.toBe('exit');
+        expect(mocks.cancel).not.toHaveBeenCalled();
+    });
+    it('decorates text and password prompts with setup navigation copy', async () => {
+        mocks.text.mockResolvedValueOnce('analytics-ktx');
+        mocks.password.mockResolvedValueOnce('secret');
+        const adapter = createKtxSetupPromptAdapter({ selectCancelValue: 'back' });
+        await expect(adapter.text({ message: 'Project folder path', placeholder: './analytics-ktx' })).resolves.toBe('analytics-ktx');
+        await expect(adapter.password({ message: 'Anthropic API key' })).resolves.toBe('secret');
+        expect(mocks.text).toHaveBeenCalledWith({
+            message: 'Project folder path\n│  Press Escape to go back.\n│',
+            placeholder: './analytics-ktx',
+        });
+        expect(mocks.password).toHaveBeenCalledWith({
+            message: 'Anthropic API key\n│  Press Escape to go back.\n│',
+        });
+    });
+    it('passes multiselect hint and disabled options through Clack', async () => {
+        mocks.multiselect.mockResolvedValueOnce(['postgres']);
+        const adapter = createKtxSetupPromptAdapter({
+            selectCancelValue: 'back',
+            multiselectCancelValue: 'back',
+            confirmEmptyOptionalMultiselect: true,
+        });
+        const options = [
+            { value: 'postgres', label: 'PostgreSQL', hint: 'recommended' },
+            { value: 'snowflake', label: 'Snowflake', disabled: true },
+        ];
+        await expect(adapter.multiselect({ message: 'Which primary sources?', options, required: true })).resolves.toEqual([
+            'postgres',
+        ]);
+        expect(mocks.multiselect).toHaveBeenCalledWith({
+            message: 'Which primary sources?',
+            options,
+            required: true,
+        });
+    });
+    it('confirms an empty optional multiselect and retries when skip is declined', async () => {
+        mocks.multiselect.mockResolvedValueOnce([]).mockResolvedValueOnce(['postgres']);
+        mocks.confirm.mockResolvedValueOnce(false);
+        const adapter = createKtxSetupPromptAdapter({
+            selectCancelValue: 'back',
+            multiselectCancelValue: 'back',
+            confirmEmptyOptionalMultiselect: true,
+        });
+        await expect(adapter.multiselect({ message: 'Which primary sources?', options: [], required: false })).resolves.toEqual([
+            'postgres',
+        ]);
+        expect(mocks.confirm).toHaveBeenCalledWith({ message: 'Nothing selected. Skip this step?', initialValue: false });
+        expect(mocks.multiselect).toHaveBeenCalledTimes(2);
+    });
+    it('maps multiselect cancellation to the configured back value', async () => {
+        mocks.multiselect.mockResolvedValueOnce(mocks.cancelSymbol);
+        const adapter = createKtxSetupPromptAdapter({
+            selectCancelValue: 'back',
+            multiselectCancelValue: 'back',
+            confirmEmptyOptionalMultiselect: true,
+        });
+        await expect(adapter.multiselect({ message: 'Which primary sources?', options: [] })).resolves.toEqual(['back']);
+        expect(mocks.cancel).toHaveBeenCalledWith('Setup cancelled.');
+    });
+    it('keeps setup intro and note plain for non-stream output', async () => {
+        const { createKtxSetupUiAdapter } = await import('./setup-prompts.js');
+        const chunks = [];
+        const io = {
+            stdout: {
+                isTTY: true,
+                write(chunk) {
+                    chunks.push(chunk);
+                },
+            },
+            stderr: { write: vi.fn() },
+        };
+        const ui = createKtxSetupUiAdapter();
+        ui.intro('KTX setup', io);
+        ui.note('  $ ktx status', 'What you can do next', io);
+        expect(chunks.join('')).toBe('KTX setup\n\nWhat you can do next:\n  $ ktx status\n');
+        expect(mocks.intro).not.toHaveBeenCalled();
+        expect(mocks.note).not.toHaveBeenCalled();
+    });
+    it('uses Clack intro and note for writable TTY output', async () => {
+        const { createKtxSetupUiAdapter } = await import('./setup-prompts.js');
+        const output = {
+            columns: 80,
+            isTTY: true,
+            on: vi.fn(),
+            write: vi.fn(),
+        };
+        const io = {
+            stdout: output,
+            stderr: { write: vi.fn() },
+        };
+        const ui = createKtxSetupUiAdapter();
+        ui.intro('KTX setup', io);
+        ui.note('  $ ktx status', 'What you can do next', io);
+        expect(mocks.intro).toHaveBeenCalledWith('KTX setup', { output });
+        expect(mocks.note).toHaveBeenCalledWith('  $ ktx status', 'What you can do next', { output });
+    });
+});

package/dist/setup-ready-menu.d.ts

@@ -0,0 +1,18 @@
+import { type KtxSetupPromptOption } from './setup-prompts.js';
+import type { KtxSetupStatus } from './setup.js';
+export type KtxSetupReadyAction = 'models' | 'embeddings' | 'databases' | 'sources' | 'context' | 'agents' | 'exit';
+export interface KtxSetupReadyMenuPromptAdapter {
+    select(options: {
+        message: string;
+        options: KtxSetupPromptOption[];
+    }): Promise<string>;
+    cancel(message: string): void;
+}
+export interface KtxSetupReadyMenuDeps {
+    prompts?: KtxSetupReadyMenuPromptAdapter;
+}
+export declare function isKtxPreAgentSetupReady(status: KtxSetupStatus): boolean;
+export declare function isKtxSetupReady(status: KtxSetupStatus): boolean;
+export declare function runKtxSetupReadyChangeMenu(status: KtxSetupStatus, deps?: KtxSetupReadyMenuDeps): Promise<{
+    action: KtxSetupReadyAction;
+}>;

package/dist/setup-ready-menu.js

@@ -0,0 +1,31 @@
+import { createKtxSetupPromptAdapter, } from './setup-prompts.js';
+export function isKtxPreAgentSetupReady(status) {
+    return (status.project.ready &&
+        status.llm.ready &&
+        status.embeddings.ready &&
+        status.databases.every((database) => database.ready) &&
+        status.sources.every((source) => source.ready) &&
+        status.context.ready);
+}
+export function isKtxSetupReady(status) {
+    return isKtxPreAgentSetupReady(status) && status.agents.some((agent) => agent.ready);
+}
+function createPromptAdapter() {
+    return createKtxSetupPromptAdapter({ selectCancelValue: 'exit' });
+}
+export async function runKtxSetupReadyChangeMenu(status, deps = {}) {
+    const prompts = deps.prompts ?? createPromptAdapter();
+    const action = (await prompts.select({
+        message: `KTX is already set up for ${status.project.name ?? status.project.path}. What would you like to change?`,
+        options: [
+            { value: 'models', label: 'Models' },
+            { value: 'embeddings', label: 'Embeddings' },
+            { value: 'databases', label: 'Databases' },
+            { value: 'sources', label: 'Context sources' },
+            { value: 'context', label: 'Rebuild KTX context' },
+            { value: 'agents', label: 'Agent integration' },
+            { value: 'exit', label: 'Exit' },
+        ],
+    }));
+    return { action };
+}

package/dist/setup-ready-menu.test.d.ts

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

package/dist/setup-ready-menu.test.js

@@ -0,0 +1,41 @@
+import { describe, expect, it, vi } from 'vitest';
+import { isKtxPreAgentSetupReady, isKtxSetupReady, runKtxSetupReadyChangeMenu } from './setup-ready-menu.js';
+const readyStatus = {
+    project: { path: '/tmp/revenue', ready: true },
+    llm: { backend: 'anthropic', ready: true, model: 'claude-sonnet-4-6' },
+    embeddings: { backend: 'openai', ready: true, model: 'text-embedding-3-small', dimensions: 1536 },
+    databases: [{ connectionId: 'warehouse', ready: true }],
+    sources: [],
+    context: { ready: true, status: 'completed' },
+    agents: [{ target: 'codex', scope: 'project', ready: true }],
+};
+describe('setup ready menu', () => {
+    it('recognizes a ready setup only when required sections are ready', () => {
+        expect(isKtxSetupReady(readyStatus)).toBe(true);
+        expect(isKtxSetupReady({ ...readyStatus, embeddings: { ready: false } })).toBe(false);
+        expect(isKtxSetupReady({ ...readyStatus, context: { ready: false, status: 'not_started' } })).toBe(false);
+        expect(isKtxSetupReady({ ...readyStatus, agents: [] })).toBe(false);
+    });
+    it('recognizes pre-agent readiness without requiring agents', () => {
+        expect(isKtxPreAgentSetupReady(readyStatus)).toBe(true);
+        expect(isKtxPreAgentSetupReady({ ...readyStatus, agents: [] })).toBe(true);
+        expect(isKtxPreAgentSetupReady({ ...readyStatus, embeddings: { ready: false } })).toBe(false);
+        expect(isKtxPreAgentSetupReady({ ...readyStatus, context: { ready: false, status: 'not_started' } })).toBe(false);
+    });
+    it('maps ready-project menu choices to setup sections', async () => {
+        const prompts = { select: vi.fn(async () => 'agents'), cancel: vi.fn() };
+        await expect(runKtxSetupReadyChangeMenu(readyStatus, { prompts })).resolves.toEqual({ action: 'agents' });
+        expect(prompts.select).toHaveBeenCalledWith({
+            message: 'KTX is already set up for /tmp/revenue. What would you like to change?',
+            options: [
+                { value: 'models', label: 'Models' },
+                { value: 'embeddings', label: 'Embeddings' },
+                { value: 'databases', label: 'Databases' },
+                { value: 'sources', label: 'Context sources' },
+                { value: 'context', label: 'Rebuild KTX context' },
+                { value: 'agents', label: 'Agent integration' },
+                { value: 'exit', label: 'Exit' },
+            ],
+        });
+    });
+});

package/dist/setup-secrets.d.ts

@@ -0,0 +1,7 @@
+export declare function envCredentialReference(envName: string): string;
+export interface WriteProjectLocalSecretReferenceOptions {
+    projectDir: string;
+    fileName: string;
+    value: string;
+}
+export declare function writeProjectLocalSecretReference(options: WriteProjectLocalSecretReferenceOptions): Promise<string>;

package/dist/setup-secrets.js

@@ -0,0 +1,15 @@
+import { chmod, mkdir, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+export function envCredentialReference(envName) {
+    return `env:${envName}`;
+}
+export async function writeProjectLocalSecretReference(options) {
+    const secretsDir = resolve(options.projectDir, '.ktx/secrets');
+    const secretPath = join(secretsDir, options.fileName);
+    await mkdir(secretsDir, { recursive: true });
+    await writeFile(secretPath, `${options.value.trim()}\n`, { encoding: 'utf-8', mode: 0o600 });
+    if (process.platform !== 'win32') {
+        await chmod(secretPath, 0o600);
+    }
+    return `file:${secretPath}`;
+}

package/dist/setup-secrets.test.d.ts

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

package/dist/setup-secrets.test.js

@@ -0,0 +1,30 @@
+import { mkdtemp, readFile, rm, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { envCredentialReference, writeProjectLocalSecretReference } from './setup-secrets.js';
+describe('setup secrets', () => {
+    let tempDir;
+    beforeEach(async () => {
+        tempDir = await mkdtemp(join(tmpdir(), 'ktx-setup-secrets-'));
+    });
+    afterEach(async () => {
+        await rm(tempDir, { recursive: true, force: true });
+    });
+    it('formats env credential references', () => {
+        expect(envCredentialReference('ANTHROPIC_API_KEY')).toBe('env:ANTHROPIC_API_KEY');
+    });
+    it('writes project-local secrets with restricted permissions and returns a file reference', async () => {
+        const result = await writeProjectLocalSecretReference({
+            projectDir: tempDir,
+            fileName: 'anthropic-api-key',
+            value: 'sk-ant-test',
+        });
+        expect(result).toBe(`file:${resolve(tempDir, '.ktx/secrets/anthropic-api-key')}`);
+        await expect(readFile(join(tempDir, '.ktx/secrets/anthropic-api-key'), 'utf-8')).resolves.toBe('sk-ant-test\n');
+        if (process.platform !== 'win32') {
+            const mode = (await stat(join(tempDir, '.ktx/secrets/anthropic-api-key'))).mode & 0o777;
+            expect(mode).toBe(0o600);
+        }
+    });
+});

package/dist/setup-sources.d.ts

@@ -0,0 +1,105 @@
+import { type DiscoveredMetabaseDatabase } from '@ktx/context/ingest';
+import { type KtxProjectConnectionConfig } from '@ktx/context/project';
+import type { KtxCliIo } from './cli-runtime.js';
+import { pickNotionRootPages } from './notion-page-picker.js';
+import { type KtxSetupPromptOption } from './setup-prompts.js';
+export type KtxSetupSourceType = 'dbt' | 'metricflow' | 'metabase' | 'looker' | 'lookml' | 'notion';
+export interface KtxSetupSourcesArgs {
+    projectDir: string;
+    inputMode: 'auto' | 'disabled';
+    source?: KtxSetupSourceType;
+    sourceConnectionId?: string;
+    sourcePath?: string;
+    sourceGitUrl?: string;
+    sourceBranch?: string;
+    sourceSubpath?: string;
+    sourceAuthTokenRef?: string;
+    sourceUrl?: string;
+    sourceApiKeyRef?: string;
+    sourceClientId?: string;
+    sourceClientSecretRef?: string;
+    sourceWarehouseConnectionId?: string;
+    sourceProjectName?: string;
+    sourceProfilesPath?: string;
+    sourceTarget?: string;
+    metabaseDatabaseId?: number;
+    notionCrawlMode?: 'all_accessible' | 'selected_roots';
+    notionRootPageIds?: string[];
+    runInitialSourceIngest: boolean;
+    skipSources: boolean;
+}
+export type KtxSetupSourcesResult = {
+    status: 'ready';
+    projectDir: string;
+    connectionIds: string[];
+} | {
+    status: 'skipped';
+    projectDir: string;
+} | {
+    status: 'back';
+    projectDir: string;
+} | {
+    status: 'missing-input';
+    projectDir: string;
+} | {
+    status: 'failed';
+    projectDir: string;
+};
+export interface KtxSetupSourcesPromptAdapter {
+    multiselect(options: {
+        message: string;
+        options: KtxSetupPromptOption[];
+        initialValues?: string[];
+        required?: boolean;
+    }): Promise<string[]>;
+    select(options: {
+        message: string;
+        options: KtxSetupPromptOption[];
+    }): Promise<string>;
+    text(options: {
+        message: string;
+        placeholder?: string;
+        initialValue?: string;
+    }): Promise<string | undefined>;
+    password(options: {
+        message: string;
+    }): Promise<string | undefined>;
+    cancel(message: string): void;
+    log?(message: string): void;
+}
+export type SourceValidationResult = {
+    ok: true;
+    detail?: string;
+} | {
+    ok: false;
+    message: string;
+};
+export interface KtxSetupSourcesDeps {
+    prompts?: KtxSetupSourcesPromptAdapter;
+    testGitRepo?: (args: {
+        repoUrl: string;
+        authToken?: string | null;
+    }) => Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+    validateDbt?: (connection: KtxProjectConnectionConfig) => Promise<SourceValidationResult>;
+    validateMetricflow?: (connection: KtxProjectConnectionConfig) => Promise<SourceValidationResult>;
+    validateMetabase?: (projectDir: string, connectionId: string) => Promise<SourceValidationResult>;
+    validateLooker?: (projectDir: string, connectionId: string) => Promise<SourceValidationResult>;
+    validateLookml?: (connection: KtxProjectConnectionConfig) => Promise<SourceValidationResult>;
+    validateNotion?: (connection: KtxProjectConnectionConfig) => Promise<SourceValidationResult>;
+    pickNotionRootPages?: typeof pickNotionRootPages;
+    discoverMetabaseDatabases?: (args: {
+        sourceUrl: string;
+        sourceApiKeyRef: string;
+        sourceConnectionId: string;
+    }) => Promise<DiscoveredMetabaseDatabase[]>;
+    runMapping?: (projectDir: string, connectionId: string, io: KtxCliIo) => Promise<number>;
+    runInitialIngest?: (projectDir: string, connectionId: string, io: KtxCliIo, options: {
+        inputMode: KtxSetupSourcesArgs['inputMode'];
+    }) => Promise<number>;
+}
+export declare function runKtxSetupSourcesStep(args: KtxSetupSourcesArgs, io: KtxCliIo, deps?: KtxSetupSourcesDeps): Promise<KtxSetupSourcesResult>;