@kaelio/ktx 0.0.0 → 0.1.0-rc.1

package/dist/next-steps.js

@@ -0,0 +1,67 @@
+export const KTX_CONTEXT_BUILD_COMMANDS = [
+    {
+        command: 'ktx ingest --all',
+        description: 'Build or refresh agent-ready context from configured connections',
+    },
+    {
+        command: 'ktx status',
+        description: 'Check setup and context readiness',
+    },
+];
+export const KTX_NEXT_STEP_DIRECT_COMMANDS = [
+    {
+        command: 'ktx status --json',
+        description: 'Verify project setup and context readiness',
+    },
+    {
+        command: 'ktx sl list',
+        description: 'Inspect generated semantic-layer sources',
+    },
+    {
+        command: 'ktx wiki list',
+        description: 'Inspect generated wiki pages',
+    },
+];
+export const KTX_NEXT_STEP_COMMANDS = [...KTX_NEXT_STEP_DIRECT_COMMANDS];
+export const KTX_NEXT_STEP_COMMAND_WIDTH = Math.max(...[...KTX_CONTEXT_BUILD_COMMANDS, ...KTX_NEXT_STEP_COMMANDS].map((step) => step.command.length));
+function commandLines(commands, indent) {
+    return commands.map((step) => `${indent}$ ${step.command.padEnd(KTX_NEXT_STEP_COMMAND_WIDTH)}  ${step.description}`);
+}
+export function formatNextStepLines(indent = '  ') {
+    return [
+        `${indent}KTX context is ready for agents. Open your coding agent in this directory and ask a data question.`,
+        `${indent}Verify with:`,
+        ...commandLines(KTX_NEXT_STEP_DIRECT_COMMANDS, indent),
+    ];
+}
+export function formatSetupNextStepLines(state, indent = '  ') {
+    if (!state.setupReady) {
+        return [
+            `${indent}Finish setup first.`,
+            `${indent}$ ${'ktx setup'.padEnd(KTX_NEXT_STEP_COMMAND_WIDTH)}  Resume configuration and validation`,
+            `${indent}$ ${'ktx status'.padEnd(KTX_NEXT_STEP_COMMAND_WIDTH)}  Check which setup steps still need attention`,
+        ];
+    }
+    if (!state.hasContextTargets) {
+        return [
+            `${indent}Connect data, then build context.`,
+            `${indent}$ ${'ktx setup'.padEnd(KTX_NEXT_STEP_COMMAND_WIDTH)}  Add primary or context sources`,
+            `${indent}$ ${'ktx status'.padEnd(KTX_NEXT_STEP_COMMAND_WIDTH)}  Check setup and context readiness`,
+        ];
+    }
+    if (!state.contextReady) {
+        return [
+            `${indent}Build KTX context next.`,
+            `${indent}Run ingest to build database schema context before context-source ingest.`,
+            ...commandLines(KTX_CONTEXT_BUILD_COMMANDS, indent),
+        ];
+    }
+    if (!state.agentIntegrationReady) {
+        return [
+            `${indent}KTX context is built. Install agent rules when you want your coding agent to use it.`,
+            `${indent}$ ${'ktx setup --agents'.padEnd(KTX_NEXT_STEP_COMMAND_WIDTH)}  Install CLI-based agent rules`,
+            `${indent}$ ${'ktx status'.padEnd(KTX_NEXT_STEP_COMMAND_WIDTH)}  Check setup and context readiness`,
+        ];
+    }
+    return formatNextStepLines(indent);
+}

package/dist/next-steps.test.d.ts

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

package/dist/next-steps.test.js

@@ -0,0 +1,75 @@
+import { describe, expect, it } from 'vitest';
+import { KTX_CONTEXT_BUILD_COMMANDS, KTX_NEXT_STEP_COMMANDS, formatNextStepLines, formatSetupNextStepLines, } from './next-steps.js';
+describe('KTX demo next steps', () => {
+    it('uses supported context-build commands before agent usage', () => {
+        expect(KTX_CONTEXT_BUILD_COMMANDS).toEqual([
+            {
+                command: 'ktx ingest --all',
+                description: 'Build or refresh agent-ready context from configured connections',
+            },
+            {
+                command: 'ktx status',
+                description: 'Check setup and context readiness',
+            },
+        ]);
+    });
+    it('uses supported final public commands', () => {
+        expect(KTX_NEXT_STEP_COMMANDS).toEqual([
+            {
+                command: 'ktx status --json',
+                description: 'Verify project setup and context readiness',
+            },
+            {
+                command: 'ktx sl list',
+                description: 'Inspect generated semantic-layer sources',
+            },
+            {
+                command: 'ktx wiki list',
+                description: 'Inspect generated wiki pages',
+            },
+        ]);
+    });
+    it('uses only the direct CLI route for agent verification', () => {
+        const commands = KTX_NEXT_STEP_COMMANDS.map((step) => step.command);
+        expect(commands).not.toContain('ktx agent context --json');
+        expect(commands).toContain('ktx status --json');
+        expect(commands).not.toContain('ktx serve --mcp stdio --user-id local');
+    });
+    it('explains what the next-step commands are for', () => {
+        const rendered = formatNextStepLines().join('\n');
+        expect(rendered).toContain('KTX context is ready for agents.');
+        expect(rendered).toContain('ask a data question');
+        expect(rendered).toContain('Verify with:');
+        expect(rendered).not.toContain('Preferred route');
+        expect(rendered).not.toContain('Optional MCP:');
+    });
+    it('keeps setup next steps focused on building context when the build is not ready', () => {
+        const rendered = formatSetupNextStepLines({
+            setupReady: true,
+            hasContextTargets: true,
+            contextReady: false,
+            agentIntegrationReady: true,
+        }).join('\n');
+        expect(rendered).toContain('Build KTX context next.');
+        expect(rendered).toContain('Run ingest to build database schema context before context-source ingest.');
+        expect(rendered).toContain('ktx ingest --all');
+        expect(rendered).not.toContain('resume');
+        expect(rendered).not.toContain('scan');
+        expect(rendered).toContain('ktx status');
+        expect(rendered).not.toContain('ktx agent context --json');
+        expect(rendered).not.toContain('ktx serve --mcp');
+    });
+    it('shows agent commands only after setup and context build are ready', () => {
+        const rendered = formatSetupNextStepLines({
+            setupReady: true,
+            hasContextTargets: true,
+            contextReady: true,
+            agentIntegrationReady: true,
+        }).join('\n');
+        expect(rendered).toContain('KTX context is ready for agents.');
+        expect(rendered).toContain('ktx status --json');
+        expect(rendered).not.toContain('ktx agent');
+        expect(rendered).not.toContain('ktx serve --mcp stdio --user-id local');
+        expect(rendered).not.toContain('Build KTX context next.');
+    });
+});

package/dist/notion-page-picker.d.ts

@@ -0,0 +1,35 @@
+import { type NotionApi } from '@ktx/context/ingest';
+import type { KtxProjectConnectionConfig } from '@ktx/context/project';
+import type { KtxCliIo } from './cli-runtime.js';
+import { type PickerState, type TreePickerNodeInput } from './tree-picker-state.js';
+import { type TreePickerChrome, type TreePickerResult, type TreePickerTuiIo } from './tree-picker-tui.js';
+export interface PickNotionRootPagesArgs {
+    connectionId: string;
+    connection: KtxProjectConnectionConfig;
+}
+export type NotionPickerApi = Pick<NotionApi, 'search' | 'retrieveBotUser'>;
+export type NotionRootPagePickResult = {
+    kind: 'selected';
+    rootPageIds: string[];
+} | {
+    kind: 'back';
+} | {
+    kind: 'unavailable';
+    message: string;
+};
+export interface NotionRootPagePickerDeps {
+    env?: Record<string, string | undefined>;
+    createNotionApi?: (authToken: string) => NotionPickerApi;
+    renderPicker?: (chrome: TreePickerChrome, initialState: PickerState, io: TreePickerTuiIo) => Promise<TreePickerResult>;
+}
+export declare function normalizeNotionPageId(value: string): string;
+export declare function notionPickerPageFromSearchResult(result: Record<string, unknown>): TreePickerNodeInput;
+export declare function discoverNotionPickerPages(api: NotionPickerApi, options?: {
+    cap?: number;
+}): Promise<{
+    pages: TreePickerNodeInput[];
+    cappedAtCount: number | null;
+    warnings: string[];
+}>;
+export declare function resolveNotionWorkspaceLabel(api: NotionPickerApi, connectionId: string): Promise<string>;
+export declare function pickNotionRootPages(args: PickNotionRootPagesArgs, io?: KtxCliIo, deps?: NotionRootPagePickerDeps): Promise<NotionRootPagePickResult>;

package/dist/notion-page-picker.js

@@ -0,0 +1,208 @@
+import { resolveNotionConnectionAuthToken } from '@ktx/context/connections';
+import { NotionClient } from '@ktx/context/ingest';
+import { profileMark } from './startup-profile.js';
+import { buildInitialState, buildPickerTree, flattenSelection, } from './tree-picker-state.js';
+import { renderTreePickerTui, } from './tree-picker-tui.js';
+profileMark('module:notion-page-picker');
+const NOTION_PICKER_PAGE_CAP = 5000;
+const NOTION_SCRIPTED_MODE_HINT = 'Notion picker requires a TTY. Use --no-input --notion-root-page-id <UUID> for scripted mode.';
+function assertSafeNotionPickerConnectionId(connectionId) {
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(connectionId)) {
+        throw new Error(`Unsafe connection id: ${connectionId}`);
+    }
+}
+export function normalizeNotionPageId(value) {
+    const trimmed = value.trim();
+    const compact = trimmed.includes('-') ? trimmed.replace(/-/g, '') : trimmed;
+    if (!/^[0-9a-fA-F]{32}$/.test(compact)) {
+        throw new Error(`Invalid Notion page UUID: ${value}`);
+    }
+    const lower = compact.toLowerCase();
+    return `${lower.slice(0, 8)}-${lower.slice(8, 12)}-${lower.slice(12, 16)}-${lower.slice(16, 20)}-${lower.slice(20)}`;
+}
+function tryNormalizeNotionPageId(value) {
+    try {
+        return normalizeNotionPageId(value);
+    }
+    catch {
+        return null;
+    }
+}
+function recordValue(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+function extractTitleFromNotionPage(page) {
+    const properties = recordValue(page.properties);
+    if (!properties) {
+        return 'Untitled';
+    }
+    for (const property of Object.values(properties)) {
+        const value = recordValue(property);
+        if (!value || value.type !== 'title' || !Array.isArray(value.title)) {
+            continue;
+        }
+        const text = value.title
+            .map((part) => {
+            const richText = recordValue(part);
+            return typeof richText?.plain_text === 'string' ? richText.plain_text : '';
+        })
+            .join('')
+            .trim();
+        if (text.length > 0) {
+            return text;
+        }
+    }
+    return 'Untitled';
+}
+function extractParentPageId(page) {
+    const parent = recordValue(page.parent);
+    if (!parent || parent.type !== 'page_id' || typeof parent.page_id !== 'string') {
+        return null;
+    }
+    return normalizeNotionPageId(parent.page_id);
+}
+export function notionPickerPageFromSearchResult(result) {
+    const id = typeof result.id === 'string' ? normalizeNotionPageId(result.id) : '';
+    if (!id) {
+        throw new Error('Notion page search result is missing id');
+    }
+    return {
+        id,
+        title: extractTitleFromNotionPage(result),
+        archived: result.archived === true,
+        parentId: extractParentPageId(result),
+    };
+}
+export async function discoverNotionPickerPages(api, options = {}) {
+    const cap = options.cap ?? NOTION_PICKER_PAGE_CAP;
+    const pages = [];
+    const warnings = [];
+    let cursor = null;
+    while (pages.length < cap) {
+        let response;
+        try {
+            response = await api.search('page', cursor, Math.min(100, cap - pages.length));
+        }
+        catch (error) {
+            if (pages.length === 0) {
+                throw error;
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            warnings.push(`Notion search stopped early: ${message}`);
+            return { pages, cappedAtCount: null, warnings };
+        }
+        for (const result of response.results) {
+            pages.push(notionPickerPageFromSearchResult(result));
+            if (pages.length >= cap) {
+                break;
+            }
+        }
+        if (!response.hasMore || !response.nextCursor || pages.length >= cap) {
+            return {
+                pages,
+                cappedAtCount: response.hasMore ? cap : null,
+                warnings,
+            };
+        }
+        cursor = response.nextCursor;
+    }
+    return { pages, cappedAtCount: cap, warnings };
+}
+export async function resolveNotionWorkspaceLabel(api, connectionId) {
+    try {
+        const bot = (await api.retrieveBotUser());
+        const workspaceName = typeof bot.bot?.workspace_name === 'string' ? bot.bot.workspace_name.trim() : '';
+        if (workspaceName.length > 0) {
+            return workspaceName;
+        }
+        const name = typeof bot.name === 'string' ? bot.name.trim() : '';
+        return name.length > 0 ? name : connectionId;
+    }
+    catch {
+        return connectionId;
+    }
+}
+function assertNotionConnection(connection, connectionId) {
+    if (connection.driver !== 'notion') {
+        throw new Error(`Connection "${connectionId}" is not a Notion connection`);
+    }
+}
+function stringArray(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === 'string' && item.trim().length > 0) : [];
+}
+function notionCrawlMode(connection) {
+    return connection.crawl_mode === 'all_accessible' ? 'all_accessible' : 'selected_roots';
+}
+function selectedPageCountText(count) {
+    return `${count} selected ${count === 1 ? 'page' : 'pages'}`;
+}
+function notionChrome(args) {
+    const warningLines = [];
+    if (args.cappedAtCount) {
+        warningLines.push(`${args.cappedAtCount}-page cap reached - some pages not shown`);
+    }
+    return {
+        title: 'Select Notion pages to ingest',
+        subtitleLines: [`Workspace: ${args.workspaceLabel}`],
+        warningLines,
+        confirmSaveMessage: args.currentCrawlMode === 'all_accessible'
+            ? (state) => `Switch crawl_mode from all_accessible to selected_roots? Will limit ingest to ${selectedPageCountText(flattenSelection(state.checked, state.byId).length)}. Press Enter to confirm or Escape to go back.`
+            : undefined,
+    };
+}
+export async function pickNotionRootPages(args, io = process, deps = {}) {
+    try {
+        assertSafeNotionPickerConnectionId(args.connectionId);
+        assertNotionConnection(args.connection, args.connectionId);
+        const crawlMode = notionCrawlMode(args.connection);
+        const authToken = await resolveNotionConnectionAuthToken({
+            auth_token: typeof args.connection.auth_token === 'string' ? args.connection.auth_token : null,
+            auth_token_ref: typeof args.connection.auth_token_ref === 'string' ? args.connection.auth_token_ref : null,
+        }, { env: deps.env });
+        const api = deps.createNotionApi ? deps.createNotionApi(authToken) : new NotionClient(authToken);
+        const discovery = await discoverNotionPickerPages(api);
+        const tree = buildPickerTree(discovery.pages);
+        const normalizedExistingIds = stringArray(args.connection.root_page_ids)
+            .map((raw) => tryNormalizeNotionPageId(raw))
+            .filter((id) => id !== null);
+        const initialState = buildInitialState({
+            tree,
+            existingSelectedIds: normalizedExistingIds,
+            requireConfirmOnSave: crawlMode === 'all_accessible',
+            staleWarning: (count) => `${count} stored root_page_ids no longer visible - they will be removed if you save`,
+        });
+        const preLoadWarnings = [...discovery.warnings, ...initialState.preLoadWarnings];
+        const renderState = preLoadWarnings.length > 0
+            ? {
+                ...initialState,
+                preLoadWarnings,
+            }
+            : initialState;
+        for (const warning of preLoadWarnings) {
+            io.stderr.write(`${warning}\n`);
+        }
+        const workspaceLabel = await resolveNotionWorkspaceLabel(api, args.connectionId);
+        const chrome = notionChrome({
+            workspaceLabel,
+            cappedAtCount: discovery.cappedAtCount,
+            currentCrawlMode: crawlMode,
+        });
+        const renderPicker = deps.renderPicker ??
+            ((chromeArg, state, ioArg) => renderTreePickerTui({ chrome: chromeArg, initialState: state }, ioArg, {
+                scriptedModeHint: NOTION_SCRIPTED_MODE_HINT,
+            }));
+        const result = await renderPicker(chrome, renderState, io);
+        if (result.kind === 'quit') {
+            return { kind: 'back' };
+        }
+        if (result.selectedIds.length === 0) {
+            return { kind: 'unavailable', message: 'Notion picker did not return any selected pages.' };
+        }
+        return { kind: 'selected', rootPageIds: result.selectedIds };
+    }
+    catch (error) {
+        return { kind: 'unavailable', message: error instanceof Error ? error.message : String(error) };
+    }
+}

package/dist/notion-page-picker.test.d.ts

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

package/dist/notion-page-picker.test.js

@@ -0,0 +1,244 @@
+import { describe, expect, it, vi } from 'vitest';
+import { discoverNotionPickerPages, notionPickerPageFromSearchResult, normalizeNotionPageId, pickNotionRootPages, resolveNotionWorkspaceLabel, } from './notion-page-picker.js';
+function makeIo() {
+    let stdout = '';
+    let stderr = '';
+    return {
+        io: {
+            stdout: {
+                isTTY: true,
+                write: (chunk) => {
+                    stdout += chunk;
+                },
+            },
+            stderr: {
+                write: (chunk) => {
+                    stderr += chunk;
+                },
+            },
+        },
+        stdout: () => stdout,
+        stderr: () => stderr,
+    };
+}
+const PAGE_IDS = {
+    engineering: '11111111-1111-1111-1111-111111111111',
+    architecture: '22222222-2222-2222-2222-222222222222',
+    stale: '99999999-9999-9999-9999-999999999999',
+};
+function notionPage(id, title, parentId = null) {
+    return {
+        object: 'page',
+        id,
+        archived: false,
+        parent: parentId ? { type: 'page_id', page_id: parentId } : { type: 'workspace', workspace: true },
+        properties: {
+            title: {
+                type: 'title',
+                title: [{ plain_text: title }],
+            },
+        },
+    };
+}
+function fakeNotionApi(pages) {
+    return {
+        search: vi.fn(async (_filterValue, startCursor) => {
+            if (startCursor === 'page-2') {
+                return { results: pages.slice(2), hasMore: false, nextCursor: null };
+            }
+            return {
+                results: pages.slice(0, 2),
+                hasMore: pages.length > 2,
+                nextCursor: pages.length > 2 ? 'page-2' : null,
+            };
+        }),
+        retrieveBotUser: vi.fn(async () => ({ name: 'Notion bot', bot: { workspace_name: 'Design Workspace' } })),
+    };
+}
+describe('normalizeNotionPageId', () => {
+    it('accepts dashed and compact UUIDs', () => {
+        expect(normalizeNotionPageId('11111111222233334444555555555555')).toBe('11111111-2222-3333-4444-555555555555');
+        expect(normalizeNotionPageId('AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE')).toBe('aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee');
+    });
+});
+describe('Notion page picker helpers', () => {
+    it('extracts picker page inputs from Notion search results', () => {
+        expect(notionPickerPageFromSearchResult(notionPage(PAGE_IDS.architecture, 'Architecture', PAGE_IDS.engineering)))
+            .toEqual({
+            id: PAGE_IDS.architecture,
+            title: 'Architecture',
+            archived: false,
+            parentId: PAGE_IDS.engineering,
+        });
+        expect(notionPickerPageFromSearchResult({
+            object: 'page',
+            id: PAGE_IDS.engineering.replaceAll('-', ''),
+            archived: true,
+            parent: { type: 'workspace', workspace: true },
+            properties: {},
+        })).toEqual({
+            id: PAGE_IDS.engineering,
+            title: 'Untitled',
+            archived: true,
+            parentId: null,
+        });
+    });
+    it('discovers visible pages up to the cap and reports cap state', async () => {
+        const api = fakeNotionApi([
+            notionPage(PAGE_IDS.engineering, 'Engineering'),
+            notionPage(PAGE_IDS.architecture, 'Architecture', PAGE_IDS.engineering),
+            notionPage('33333333-3333-3333-3333-333333333333', 'Onboarding', PAGE_IDS.engineering),
+        ]);
+        await expect(discoverNotionPickerPages(api, { cap: 2 })).resolves.toEqual({
+            pages: [
+                { id: PAGE_IDS.engineering, title: 'Engineering', archived: false, parentId: null },
+                { id: PAGE_IDS.architecture, title: 'Architecture', archived: false, parentId: PAGE_IDS.engineering },
+            ],
+            cappedAtCount: 2,
+            warnings: [],
+        });
+        expect(api.search).toHaveBeenCalledTimes(1);
+    });
+    it('keeps partial discovery results when Notion search fails after at least one page', async () => {
+        const api = {
+            search: vi
+                .fn()
+                .mockResolvedValueOnce({
+                results: [notionPage(PAGE_IDS.engineering, 'Engineering')],
+                hasMore: true,
+                nextCursor: 'cursor-2',
+            })
+                .mockRejectedValueOnce(new Error('rate limit after first page')),
+            retrieveBotUser: vi.fn(async () => ({ name: 'Notion bot' })),
+        };
+        await expect(discoverNotionPickerPages(api)).resolves.toEqual({
+            pages: [{ id: PAGE_IDS.engineering, title: 'Engineering', archived: false, parentId: null }],
+            cappedAtCount: null,
+            warnings: ['Notion search stopped early: rate limit after first page'],
+        });
+    });
+    it('uses the Notion workspace name when available and falls back to the connection id', async () => {
+        await expect(resolveNotionWorkspaceLabel(fakeNotionApi([]), 'notion-main')).resolves.toBe('Design Workspace');
+        await expect(resolveNotionWorkspaceLabel({
+            search: vi.fn(),
+            retrieveBotUser: vi.fn(async () => {
+                throw new Error('users.me unavailable');
+            }),
+        }, 'notion-main')).resolves.toBe('notion-main');
+    });
+});
+describe('pickNotionRootPages', () => {
+    it('discovers visible pages, warns about stale roots, renders the TUI, and returns selected roots', async () => {
+        const api = fakeNotionApi([
+            notionPage(PAGE_IDS.engineering, 'Engineering'),
+            notionPage(PAGE_IDS.architecture, 'Architecture', PAGE_IDS.engineering),
+        ]);
+        const renderPicker = vi.fn(async (chrome, state) => {
+            expect(chrome.title).toBe('Select Notion pages to ingest');
+            expect(chrome.subtitleLines).toEqual(['Workspace: Design Workspace']);
+            expect(chrome.warningLines ?? []).toEqual([]);
+            expect(chrome.confirmSaveMessage).toBeTypeOf('function');
+            expect(state.requireConfirmOnSave).toBe(true);
+            expect(state.preLoadWarnings).toEqual([
+                '1 stored root_page_ids no longer visible - they will be removed if you save',
+            ]);
+            return { kind: 'save', selectedIds: [PAGE_IDS.engineering] };
+        });
+        const io = makeIo();
+        await expect(pickNotionRootPages({
+            connectionId: 'notion-main',
+            connection: {
+                driver: 'notion',
+                auth_token_ref: 'env:NOTION_TOKEN',
+                crawl_mode: 'all_accessible',
+                root_page_ids: [PAGE_IDS.stale],
+            },
+        }, io.io, {
+            env: { NOTION_TOKEN: 'ntn_test_token' },
+            createNotionApi: vi.fn(() => api),
+            renderPicker,
+        })).resolves.toEqual({ kind: 'selected', rootPageIds: [PAGE_IDS.engineering] });
+        expect(io.stderr()).toContain('1 stored root_page_ids no longer visible');
+        expect(io.stdout()).toBe('');
+    });
+    it('uses inline Notion auth_token for discovery', async () => {
+        const api = fakeNotionApi([notionPage(PAGE_IDS.engineering, 'Engineering')]);
+        const createNotionApi = vi.fn((authToken) => {
+            expect(authToken).toBe('ntn_inline_token');
+            return api;
+        });
+        await expect(pickNotionRootPages({
+            connectionId: 'notion-main',
+            connection: {
+                driver: 'notion',
+                auth_token: 'ntn_inline_token',
+                crawl_mode: 'selected_roots',
+                root_page_ids: [PAGE_IDS.engineering],
+            },
+        }, makeIo().io, {
+            createNotionApi,
+            renderPicker: vi.fn(async () => ({ kind: 'quit' })),
+        })).resolves.toEqual({ kind: 'back' });
+        expect(createNotionApi).toHaveBeenCalledOnce();
+    });
+    it('passes partial-discovery warnings into the TUI banner state', async () => {
+        const api = {
+            search: vi
+                .fn()
+                .mockResolvedValueOnce({
+                results: [notionPage(PAGE_IDS.engineering, 'Engineering')],
+                hasMore: true,
+                nextCursor: 'cursor-2',
+            })
+                .mockRejectedValueOnce(new Error('rate limit after first page')),
+            retrieveBotUser: vi.fn(async () => ({ name: 'Notion bot', bot: { workspace_name: 'Design Workspace' } })),
+        };
+        let captured;
+        const renderPicker = vi.fn(async (chrome, state, io) => {
+            captured = [chrome, state, io];
+            return { kind: 'quit' };
+        });
+        const io = makeIo();
+        await expect(pickNotionRootPages({
+            connectionId: 'notion-main',
+            connection: {
+                driver: 'notion',
+                auth_token_ref: 'env:NOTION_TOKEN',
+                crawl_mode: 'selected_roots',
+                root_page_ids: [PAGE_IDS.engineering],
+            },
+        }, io.io, {
+            env: { NOTION_TOKEN: 'ntn_test_token' },
+            createNotionApi: vi.fn(() => api),
+            renderPicker,
+        })).resolves.toEqual({ kind: 'back' });
+        expect(renderPicker).toHaveBeenCalledOnce();
+        if (!captured) {
+            throw new Error('renderPicker was not called');
+        }
+        const [, state] = captured;
+        expect(state.preLoadWarnings).toEqual(['Notion search stopped early: rate limit after first page']);
+        expect(state.tree.map((node) => node.title)).toEqual(['Engineering']);
+        expect(io.stderr()).toContain('Notion search stopped early: rate limit after first page');
+    });
+    it('returns unavailable when discovery cannot load any pages', async () => {
+        await expect(pickNotionRootPages({
+            connectionId: 'notion-main',
+            connection: {
+                driver: 'notion',
+                auth_token_ref: 'env:NOTION_TOKEN',
+                crawl_mode: 'selected_roots',
+                root_page_ids: [],
+            },
+        }, makeIo().io, {
+            env: { NOTION_TOKEN: 'ntn_test_token' },
+            createNotionApi: vi.fn(() => ({
+                search: vi.fn(async () => {
+                    throw new Error('Notion API unavailable');
+                }),
+                retrieveBotUser: vi.fn(async () => ({ name: 'Notion bot' })),
+            })),
+            renderPicker: vi.fn(async () => ({ kind: 'quit' })),
+        })).resolves.toEqual({ kind: 'unavailable', message: 'Notion API unavailable' });
+    });
+});

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

@@ -0,0 +1,4 @@
+export declare function renderKtxCommandTree(): string;
+export declare function main(stdout: {
+    write(chunk: string): void;
+}): void;

package/dist/print-command-tree.js

@@ -0,0 +1,31 @@
+import { fileURLToPath } from 'node:url';
+import { buildKtxProgram } from './cli-program.js';
+import { formatCommandTree, walkCommandTree } from './command-tree.js';
+function silentIo() {
+    return {
+        stdout: { isTTY: false, columns: 80, write: () => { } },
+        stderr: { write: () => { } },
+    };
+}
+function stubPackageInfo() {
+    return { name: '@ktx/cli', version: '0.0.0-docs', contextPackageName: '@ktx/context' };
+}
+export function renderKtxCommandTree() {
+    const program = buildKtxProgram({
+        io: silentIo(),
+        deps: {},
+        packageInfo: stubPackageInfo(),
+        runInit: async () => 0,
+    });
+    return formatCommandTree(walkCommandTree(program));
+}
+export function main(stdout) {
+    stdout.write(renderKtxCommandTree());
+}
+const invokedAsScript = typeof process !== 'undefined' &&
+    Array.isArray(process.argv) &&
+    process.argv[1] !== undefined &&
+    fileURLToPath(import.meta.url) === process.argv[1];
+if (invokedAsScript) {
+    main(process.stdout);
+}

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

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