@kaelio/ktx 0.0.0 → 0.1.0-rc.0

package/dist/setup-project.js

@@ -0,0 +1,274 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, join, resolve } from 'node:path';
+import { cancel, isCancel, select, text } from '@clack/prompts';
+import { initKtxProject, loadKtxProject, markKtxSetupStepComplete, mergeKtxSetupGitignoreEntries, serializeKtxProjectConfig, } from '@ktx/context/project';
+import { withMenuOptionsSpacing, withTextInputNavigation } from './prompt-navigation.js';
+import { withSetupInterruptConfirmation } from './setup-interrupt.js';
+const DEFAULT_NEW_PROJECT_FOLDER_NAME = 'ktx-project';
+function createClackSetupProjectPromptAdapter() {
+    return {
+        async select(options) {
+            const value = await withSetupInterruptConfirmation(() => select(withMenuOptionsSpacing(options)));
+            if (isCancel(value)) {
+                cancel('Setup cancelled.');
+                return 'exit';
+            }
+            return value;
+        },
+        async text(options) {
+            const value = await withSetupInterruptConfirmation(() => text({ ...options, message: withTextInputNavigation(options.message) }));
+            if (isCancel(value)) {
+                return undefined;
+            }
+            return value;
+        },
+        cancel(message) {
+            cancel(message);
+        },
+    };
+}
+function hasProjectConfig(projectDir) {
+    return existsSync(join(projectDir, 'ktx.yaml'));
+}
+function resolveFromProjectDir(projectDir, input, homeDir) {
+    if (input === '~') {
+        return resolve(homeDir);
+    }
+    if (input.startsWith('~/') || input.startsWith('~\\')) {
+        return resolve(homeDir, input.slice(2));
+    }
+    return resolve(projectDir, input);
+}
+async function existingFolderState(projectDir) {
+    try {
+        const projectDirStat = await stat(projectDir);
+        if (!projectDirStat.isDirectory()) {
+            return 'not-directory';
+        }
+        return (await readdir(projectDir)).length === 0 ? 'empty-directory' : 'non-empty-directory';
+    }
+    catch (error) {
+        if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
+            return 'missing';
+        }
+        throw error;
+    }
+}
+async function normalizeSetupGitignore(projectDir) {
+    const gitignorePath = join(projectDir, '.ktx/.gitignore');
+    await mkdir(join(projectDir, '.ktx'), { recursive: true });
+    const current = existsSync(gitignorePath) ? await readFile(gitignorePath, 'utf-8') : '';
+    await writeFile(gitignorePath, mergeKtxSetupGitignoreEntries(current), 'utf-8');
+}
+async function persistProjectStep(project) {
+    const config = markKtxSetupStepComplete(project.config, 'project');
+    await writeFile(project.configPath, serializeKtxProjectConfig(config), 'utf-8');
+    await normalizeSetupGitignore(project.projectDir);
+    return await loadKtxProject({ projectDir: project.projectDir });
+}
+async function createProject(projectDir, deps) {
+    const initProject = deps.initProject ?? initKtxProject;
+    const initialized = await initProject({ projectDir, projectName: basename(projectDir) || 'ktx-project' });
+    return await persistProjectStep(initialized);
+}
+async function loadExistingProject(projectDir, deps) {
+    const loadProject = deps.loadProject ?? loadKtxProject;
+    const project = await loadProject({ projectDir });
+    return await persistProjectStep(project);
+}
+function printProjectSummary(io, projectDir) {
+    io.stdout.write(`Project: ${projectDir}\n`);
+}
+async function promptForNewProjectDir(projectDir, homeDir, io, prompts) {
+    const defaultProjectDir = join(projectDir, DEFAULT_NEW_PROJECT_FOLDER_NAME);
+    while (true) {
+        io.stdout.write(`Relative paths are resolved from:\n  ${projectDir}\n`);
+        io.stdout.write(`Home paths are resolved from:\n  ${homeDir}\n`);
+        const destinationChoice = await prompts.select({
+            message: 'Where should KTX create the project?',
+            options: [
+                { value: 'default', label: `Create the default project folder: ${defaultProjectDir}` },
+                { value: 'custom', label: 'Enter a custom path' },
+                { value: 'back', label: 'Back' },
+            ],
+        });
+        let selectedDir;
+        if (destinationChoice === 'back') {
+            return { status: 'back', projectDir };
+        }
+        if (destinationChoice === 'default') {
+            selectedDir = defaultProjectDir;
+        }
+        else if (destinationChoice === 'custom') {
+            const rawSelectedDir = await prompts.text({
+                message: withTextInputNavigation('Project folder path'),
+                placeholder: './analytics-ktx, ~/analytics-ktx, or /Users/you/projects/analytics-ktx',
+            });
+            if (rawSelectedDir === undefined) {
+                continue;
+            }
+            const trimmedSelectedDir = rawSelectedDir.trim();
+            if (trimmedSelectedDir.length === 0) {
+                io.stderr.write('Enter a relative path like ./analytics-ktx, a home path like ~/analytics-ktx, or an absolute path.\n');
+                return { status: 'missing-input', projectDir };
+            }
+            selectedDir = resolveFromProjectDir(projectDir, trimmedSelectedDir, homeDir);
+        }
+        else {
+            return { status: 'cancelled', projectDir };
+        }
+        const state = await existingFolderState(selectedDir);
+        let confirmedCreation = false;
+        if (state === 'not-directory') {
+            io.stderr.write(`Project folder path exists and is not a directory: ${selectedDir}\n`);
+            return { status: 'missing-input', projectDir };
+        }
+        if (state === 'non-empty-directory') {
+            const existingAction = await prompts.select({
+                message: `That folder already exists and is not empty: ${selectedDir}`,
+                options: [
+                    { value: 'use-existing', label: 'Yes, create KTX files there' },
+                    { value: 'choose-another', label: 'Choose another folder' },
+                    { value: 'back', label: 'Back' },
+                ],
+            });
+            if (existingAction === 'choose-another') {
+                continue;
+            }
+            if (existingAction === 'back') {
+                return { status: 'back', projectDir };
+            }
+            if (existingAction !== 'use-existing') {
+                return { status: 'cancelled', projectDir };
+            }
+            confirmedCreation = true;
+        }
+        io.stdout.write(`KTX will create:\n  ${selectedDir}\n`);
+        if (state !== 'non-empty-directory') {
+            const createAction = await prompts.select({
+                message: `Create KTX project at ${selectedDir}?`,
+                options: [
+                    { value: 'create', label: 'Create project' },
+                    { value: 'choose-another', label: 'Choose another folder' },
+                    { value: 'back', label: 'Back' },
+                ],
+            });
+            if (createAction === 'choose-another') {
+                continue;
+            }
+            if (createAction === 'back') {
+                return { status: 'back', projectDir };
+            }
+            if (createAction !== 'create') {
+                return { status: 'cancelled', projectDir };
+            }
+            confirmedCreation = true;
+        }
+        return { status: 'selected', projectDir: selectedDir, confirmedCreation };
+    }
+}
+export async function runKtxSetupProjectStep(args, io, deps = {}) {
+    const projectDir = resolve(args.projectDir);
+    const homeDir = deps.homeDir ?? homedir();
+    const exists = hasProjectConfig(projectDir);
+    if (args.mode === 'existing') {
+        if (!exists) {
+            io.stderr.write(`No existing KTX project found at ${projectDir}. Pass --new to create it.\n`);
+            return { status: 'missing-input', projectDir };
+        }
+        const project = await loadExistingProject(projectDir, deps);
+        printProjectSummary(io, projectDir);
+        return { status: 'ready', projectDir, project };
+    }
+    if (args.mode === 'new') {
+        const project = await createProject(projectDir, deps);
+        printProjectSummary(io, projectDir);
+        return { status: 'ready', projectDir, project };
+    }
+    if (args.mode === 'prompt-new') {
+        if (args.inputMode === 'disabled') {
+            io.stderr.write('Missing new project folder: pass --new --project-dir to create a project without prompts.\n');
+            return { status: 'missing-input', projectDir };
+        }
+        if (!io.stdout.isTTY && !deps.prompts) {
+            io.stderr.write('Missing new project folder: pass --new --project-dir to create a project outside an interactive terminal.\n');
+            return { status: 'missing-input', projectDir };
+        }
+        const prompts = deps.prompts ?? createClackSetupProjectPromptAdapter();
+        const selected = await promptForNewProjectDir(projectDir, homeDir, io, prompts);
+        if (selected.status === 'back') {
+            return args.allowBack ? { status: 'back', projectDir } : { status: 'cancelled', projectDir };
+        }
+        if (selected.status !== 'selected') {
+            return selected;
+        }
+        const project = await createProject(selected.projectDir, deps);
+        printProjectSummary(io, selected.projectDir);
+        return {
+            status: 'ready',
+            projectDir: selected.projectDir,
+            project,
+            confirmedCreation: selected.confirmedCreation,
+        };
+    }
+    if (exists) {
+        const project = await loadExistingProject(projectDir, deps);
+        printProjectSummary(io, projectDir);
+        return { status: 'ready', projectDir, project };
+    }
+    if (args.inputMode === 'disabled') {
+        if (!args.yes) {
+            io.stderr.write('Missing setup choice: pass --new or --yes to create a project in non-interactive setup.\n');
+            return { status: 'missing-input', projectDir };
+        }
+        const project = await createProject(projectDir, deps);
+        printProjectSummary(io, projectDir);
+        return { status: 'ready', projectDir, project };
+    }
+    if (!io.stdout.isTTY && !deps.prompts) {
+        io.stderr.write('Missing setup choice: pass --new or --yes to create a project outside an interactive terminal.\n');
+        return { status: 'missing-input', projectDir };
+    }
+    const prompts = deps.prompts ?? createClackSetupProjectPromptAdapter();
+    io.stdout.write('Use Up/Down to move, Enter to confirm the current selection, choose Back to return to the previous step, Ctrl+C to exit.\n');
+    while (true) {
+        const choice = await prompts.select({
+            message: 'Which KTX project should setup use?',
+            options: [
+                { value: 'current', label: 'Use current directory' },
+                { value: 'new', label: 'Create a new project folder' },
+                ...(args.allowBack ? [{ value: 'back', label: 'Back' }] : []),
+                ...(args.allowBack ? [] : [{ value: 'exit', label: 'Exit' }]),
+            ],
+        });
+        if (choice === 'back') {
+            return args.allowBack ? { status: 'back', projectDir } : { status: 'cancelled', projectDir };
+        }
+        if (choice === 'exit') {
+            prompts.cancel('Setup cancelled.');
+            return { status: 'cancelled', projectDir };
+        }
+        let selectedDir = projectDir;
+        let confirmedCreation = false;
+        if (choice === 'new') {
+            const selected = await promptForNewProjectDir(projectDir, homeDir, io, prompts);
+            if (selected.status === 'back') {
+                continue;
+            }
+            if (selected.status !== 'selected') {
+                return selected;
+            }
+            selectedDir = selected.projectDir;
+            confirmedCreation = selected.confirmedCreation;
+        }
+        if (choice !== 'current' && choice !== 'new') {
+            prompts.cancel('Setup cancelled.');
+            return { status: 'cancelled', projectDir };
+        }
+        const project = await createProject(selectedDir, deps);
+        printProjectSummary(io, selectedDir);
+        return { status: 'ready', projectDir: selectedDir, project, confirmedCreation };
+    }
+}

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

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

package/dist/setup-project.test.js

@@ -0,0 +1,221 @@
+import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { initKtxProject, parseKtxProjectConfig } from '@ktx/context/project';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { runKtxSetupProjectStep } from './setup-project.js';
+function makeIo(options = {}) {
+    let stdout = '';
+    let stderr = '';
+    return {
+        io: {
+            stdout: {
+                isTTY: options.stdoutIsTty,
+                write: (chunk) => {
+                    stdout += chunk;
+                },
+            },
+            stderr: {
+                write: (chunk) => {
+                    stderr += chunk;
+                },
+            },
+        },
+        stdout: () => stdout,
+        stderr: () => stderr,
+    };
+}
+function makePromptAdapter(options) {
+    const choices = [...(options.choices ?? (options.choice ? [options.choice] : []))];
+    const textValues = [...(options.textValues ?? (options.textValue !== undefined ? [options.textValue] : []))];
+    return {
+        select: vi.fn(async () => choices.shift() ?? 'exit'),
+        text: vi.fn(async () => textValues.shift() ?? ''),
+        cancel: vi.fn(),
+    };
+}
+describe('setup project step', () => {
+    let tempDir;
+    beforeEach(async () => {
+        tempDir = await mkdtemp(join(tmpdir(), 'ktx-setup-project-'));
+    });
+    afterEach(async () => {
+        await rm(tempDir, { recursive: true, force: true });
+    });
+    it('creates a new project with --new and marks the project step complete', async () => {
+        const projectDir = join(tempDir, 'warehouse');
+        const testIo = makeIo();
+        const result = await runKtxSetupProjectStep({ projectDir, mode: 'new', inputMode: 'disabled', yes: false }, testIo.io);
+        expect(result.status).toBe('ready');
+        expect(result.projectDir).toBe(projectDir);
+        const config = parseKtxProjectConfig(await readFile(join(projectDir, 'ktx.yaml'), 'utf-8'));
+        expect(config.setup?.completed_steps).toEqual(['project']);
+        await expect(stat(join(projectDir, '.git'))).resolves.toBeDefined();
+        await expect(readFile(join(projectDir, '.ktx/.gitignore'), 'utf-8')).resolves.toContain('secrets/');
+        expect(testIo.stdout()).toContain(`Project: ${projectDir}`);
+        expect(testIo.stderr()).toBe('');
+    });
+    it('loads an existing project with --existing and preserves existing setup metadata', async () => {
+        const projectDir = join(tempDir, 'warehouse');
+        await initKtxProject({ projectDir, projectName: 'warehouse' });
+        await writeFile(join(projectDir, 'ktx.yaml'), [
+            'project: warehouse',
+            'setup:',
+            '  database_connection_ids:',
+            '    - warehouse',
+            '  completed_steps:',
+            '    - llm',
+            'connections: {}',
+        ].join('\n'), 'utf-8');
+        const result = await runKtxSetupProjectStep({ projectDir, mode: 'existing', inputMode: 'disabled', yes: false }, makeIo().io);
+        expect(result.status).toBe('ready');
+        const config = parseKtxProjectConfig(await readFile(join(projectDir, 'ktx.yaml'), 'utf-8'));
+        expect(config.setup).toEqual({
+            database_connection_ids: ['warehouse'],
+            completed_steps: ['llm', 'project'],
+        });
+    });
+    it('creates a missing auto-mode project only when --yes is present in no-input mode', async () => {
+        const projectDir = join(tempDir, 'warehouse');
+        const rejectedIo = makeIo();
+        const acceptedIo = makeIo();
+        await expect(runKtxSetupProjectStep({ projectDir, mode: 'auto', inputMode: 'disabled', yes: false }, rejectedIo.io)).resolves.toMatchObject({ status: 'missing-input' });
+        expect(rejectedIo.stderr()).toContain('Missing setup choice: pass --new or --yes');
+        await expect(stat(join(projectDir, 'ktx.yaml'))).rejects.toThrow();
+        await expect(runKtxSetupProjectStep({ projectDir, mode: 'auto', inputMode: 'disabled', yes: true }, acceptedIo.io)).resolves.toMatchObject({ status: 'ready', projectDir });
+        await expect(stat(join(projectDir, 'ktx.yaml'))).resolves.toBeDefined();
+    });
+    it('fails --existing clearly when ktx.yaml is missing', async () => {
+        const projectDir = join(tempDir, 'warehouse');
+        const testIo = makeIo();
+        await expect(runKtxSetupProjectStep({ projectDir, mode: 'existing', inputMode: 'disabled', yes: false }, testIo.io)).resolves.toMatchObject({ status: 'missing-input' });
+        expect(testIo.stderr()).toContain(`No existing KTX project found at ${projectDir}`);
+    });
+    it('prompts to use the current directory and creates a project in interactive auto mode', async () => {
+        const projectDir = join(tempDir, 'warehouse');
+        const prompts = makePromptAdapter({ choice: 'current' });
+        const testIo = makeIo({ stdoutIsTty: true });
+        const result = await runKtxSetupProjectStep({ projectDir, mode: 'auto', inputMode: 'auto', yes: false }, testIo.io, { prompts });
+        expect(result.status).toBe('ready');
+        expect(result.projectDir).toBe(projectDir);
+        expect(prompts.select).toHaveBeenCalledWith(expect.objectContaining({
+            message: 'Which KTX project should setup use?',
+            options: [
+                expect.objectContaining({ value: 'current', label: 'Use current directory' }),
+                expect.objectContaining({ value: 'new', label: 'Create a new project folder' }),
+                expect.objectContaining({ value: 'exit', label: 'Exit' }),
+            ],
+        }));
+        expect(prompts.text).not.toHaveBeenCalled();
+        const config = parseKtxProjectConfig(await readFile(join(projectDir, 'ktx.yaml'), 'utf-8'));
+        expect(config.setup?.completed_steps).toEqual(['project']);
+    });
+    it('offers an absolute default destination for a new project folder', async () => {
+        const startDir = join(tempDir, 'start');
+        const projectDir = join(startDir, 'ktx-project');
+        const prompts = makePromptAdapter({ choices: ['new', 'default', 'create'] });
+        const testIo = makeIo({ stdoutIsTty: true });
+        const result = await runKtxSetupProjectStep({ projectDir: startDir, mode: 'auto', inputMode: 'auto', yes: false }, testIo.io, { prompts });
+        expect(result.status).toBe('ready');
+        expect(result.projectDir).toBe(projectDir);
+        expect(prompts.select).toHaveBeenNthCalledWith(2, expect.objectContaining({
+            message: 'Where should KTX create the project?',
+            options: [
+                expect.objectContaining({
+                    value: 'default',
+                    label: `Create the default project folder: ${projectDir}`,
+                }),
+                expect.objectContaining({ value: 'custom', label: 'Enter a custom path' }),
+                expect.objectContaining({ value: 'back', label: 'Back' }),
+            ],
+        }));
+        expect(prompts.select).toHaveBeenNthCalledWith(3, expect.objectContaining({ message: `Create KTX project at ${projectDir}?` }));
+        expect(prompts.text).not.toHaveBeenCalled();
+        expect(result.status === 'ready' ? result.project.config.project : '').toBe('ktx-project');
+        expect(testIo.stdout()).toContain(`KTX will create:\n  ${projectDir}`);
+        await expect(stat(join(projectDir, 'ktx.yaml'))).resolves.toBeDefined();
+    });
+    it('prompts for a custom path and resolves it inside the current setup directory', async () => {
+        const startDir = join(tempDir, 'start');
+        const projectDir = join(startDir, 'analytics-ktx');
+        const prompts = makePromptAdapter({ choices: ['new', 'custom', 'create'], textValue: 'analytics-ktx' });
+        const result = await runKtxSetupProjectStep({ projectDir: startDir, mode: 'auto', inputMode: 'auto', yes: false }, makeIo({ stdoutIsTty: true }).io, { prompts });
+        expect(result.status).toBe('ready');
+        expect(result.projectDir).toBe(projectDir);
+        expect(prompts.text).toHaveBeenCalledWith(expect.objectContaining({
+            message: 'Project folder path\nPress Escape to go back.\n',
+            placeholder: './analytics-ktx, ~/analytics-ktx, or /Users/you/projects/analytics-ktx',
+        }));
+        await expect(stat(join(projectDir, 'ktx.yaml'))).resolves.toBeDefined();
+    });
+    it('expands a custom home-directory path before creating a new project', async () => {
+        const startDir = join(tempDir, 'start');
+        const homeDir = join(tempDir, 'home');
+        const projectDir = join(homeDir, 'analytics-ktx');
+        const prompts = makePromptAdapter({ choices: ['new', 'custom', 'create'], textValue: '~/analytics-ktx' });
+        const result = await runKtxSetupProjectStep({ projectDir: startDir, mode: 'auto', inputMode: 'auto', yes: false }, makeIo({ stdoutIsTty: true }).io, { prompts, homeDir });
+        expect(result.status).toBe('ready');
+        expect(result.projectDir).toBe(projectDir);
+        await expect(stat(join(projectDir, 'ktx.yaml'))).resolves.toBeDefined();
+    });
+    it('confirms a custom new project path and lets Back return to the project choice', async () => {
+        const startDir = join(tempDir, 'start');
+        const homeDir = join(tempDir, 'home');
+        const customProjectDir = join(homeDir, 'analytics-ktx');
+        const prompts = makePromptAdapter({
+            choices: ['new', 'custom', 'back', 'exit'],
+            textValue: '~/analytics-ktx',
+        });
+        const result = await runKtxSetupProjectStep({ projectDir: startDir, mode: 'auto', inputMode: 'auto', yes: false }, makeIo({ stdoutIsTty: true }).io, { prompts, homeDir });
+        expect(result.status).toBe('cancelled');
+        expect(result.projectDir).toBe(startDir);
+        expect(prompts.select).toHaveBeenNthCalledWith(3, expect.objectContaining({
+            message: `Create KTX project at ${customProjectDir}?`,
+            options: [
+                expect.objectContaining({ value: 'create', label: 'Create project' }),
+                expect.objectContaining({ value: 'choose-another', label: 'Choose another folder' }),
+                expect.objectContaining({ value: 'back', label: 'Back' }),
+            ],
+        }));
+        expect(prompts.select).toHaveBeenNthCalledWith(4, expect.objectContaining({ message: 'Which KTX project should setup use?' }));
+        await expect(stat(join(customProjectDir, 'ktx.yaml'))).rejects.toThrow();
+    });
+    it('rejects an empty new folder path without creating a project in the process cwd', async () => {
+        const startDir = join(tempDir, 'start');
+        const prompts = makePromptAdapter({ choices: ['new', 'custom'], textValue: '   ' });
+        const initProject = vi.fn(async () => {
+            throw new Error('initProject should not run for an empty path');
+        });
+        const testIo = makeIo({ stdoutIsTty: true });
+        await expect(runKtxSetupProjectStep({ projectDir: startDir, mode: 'auto', inputMode: 'auto', yes: false }, testIo.io, { prompts, initProject })).resolves.toMatchObject({ status: 'missing-input', projectDir: startDir });
+        expect(initProject).not.toHaveBeenCalled();
+        expect(testIo.stderr()).toContain('Enter a relative path like ./analytics-ktx, a home path like ~/analytics-ktx, or an absolute path.');
+    });
+    it('confirms before creating KTX files inside an existing non-empty folder', async () => {
+        const startDir = join(tempDir, 'start');
+        const projectDir = join(startDir, 'analytics-ktx');
+        await mkdir(projectDir, { recursive: true });
+        await writeFile(join(projectDir, 'README.md'), 'Existing project notes\n', 'utf-8');
+        const prompts = makePromptAdapter({ choices: ['new', 'custom', 'use-existing'], textValue: 'analytics-ktx' });
+        const result = await runKtxSetupProjectStep({ projectDir: startDir, mode: 'auto', inputMode: 'auto', yes: false }, makeIo({ stdoutIsTty: true }).io, { prompts });
+        expect(result.status).toBe('ready');
+        expect(result.projectDir).toBe(projectDir);
+        expect(prompts.select).toHaveBeenNthCalledWith(3, expect.objectContaining({
+            message: `That folder already exists and is not empty: ${projectDir}`,
+            options: expect.arrayContaining([
+                expect.objectContaining({ value: 'use-existing', label: 'Yes, create KTX files there' }),
+                expect.objectContaining({ value: 'choose-another', label: 'Choose another folder' }),
+            ]),
+        }));
+        await expect(readFile(join(projectDir, 'README.md'), 'utf-8')).resolves.toBe('Existing project notes\n');
+        await expect(stat(join(projectDir, 'ktx.yaml'))).resolves.toBeDefined();
+    });
+    it('prompts to exit and returns cancelled in interactive auto mode', async () => {
+        const projectDir = join(tempDir, 'warehouse');
+        const prompts = makePromptAdapter({ choice: 'exit' });
+        await expect(runKtxSetupProjectStep({ projectDir, mode: 'auto', inputMode: 'auto', yes: false }, makeIo({ stdoutIsTty: true }).io, { prompts })).resolves.toMatchObject({ status: 'cancelled', projectDir });
+        expect(prompts.cancel).toHaveBeenCalledWith('Setup cancelled.');
+        expect(prompts.text).not.toHaveBeenCalled();
+        await expect(stat(join(projectDir, 'ktx.yaml'))).rejects.toThrow();
+    });
+});

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

@@ -0,0 +1,19 @@
+import type { KtxSetupStatus } from './setup.js';
+export type KtxSetupReadyAction = 'models' | 'embeddings' | 'databases' | 'sources' | 'context' | 'agents' | 'exit';
+export interface KtxSetupReadyMenuPromptAdapter {
+    select(options: {
+        message: string;
+        options: Array<{
+            value: string;
+            label: string;
+        }>;
+    }): Promise<string>;
+    cancel(message: string): void;
+}
+export interface KtxSetupReadyMenuDeps {
+    prompts?: KtxSetupReadyMenuPromptAdapter;
+}
+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,43 @@
+import { cancel, isCancel, select } from '@clack/prompts';
+import { withMenuOptionsSpacing } from './prompt-navigation.js';
+import { withSetupInterruptConfirmation } from './setup-interrupt.js';
+export function isKtxSetupReady(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 &&
+        status.agents.some((agent) => agent.ready));
+}
+function createPromptAdapter() {
+    return {
+        async select(options) {
+            const value = await withSetupInterruptConfirmation(() => select(withMenuOptionsSpacing(options)));
+            if (isCancel(value)) {
+                cancel('Setup cancelled.');
+                return 'exit';
+            }
+            return String(value);
+        },
+        cancel(message) {
+            cancel(message);
+        },
+    };
+}
+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: 'Primary sources' },
+            { 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,35 @@
+import { describe, expect, it, vi } from 'vitest';
+import { 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('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: 'Primary sources' },
+                { 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);
+        }
+    });
+});