@kaelio/ktx 0.0.0 → 0.1.0-rc.0

package/dist/commands/connection-notion-tui.test.js

@@ -0,0 +1,237 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/* @jsxImportSource react */
+import { render as renderInkTest } from 'ink-testing-library';
+import { act } from 'react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { buildInitialState, buildPickerTree } from './connection-notion-tree.js';
+import { NotionPickerApp, notionPickerCommandForInkInput, renderNotionPickerTui, resolveNotionPickerWidth, sanitizeNotionPickerTuiError, windowItems, windowOffset, } from './connection-notion-tui.js';
+const IDS = {
+    engineering: '11111111-1111-1111-1111-111111111111',
+    architecture: '22222222-2222-2222-2222-222222222222',
+    marketing: '33333333-3333-3333-3333-333333333333',
+    finance: '44444444-4444-4444-4444-444444444444',
+    ops: '55555555-5555-5555-5555-555555555555',
+    sales: '66666666-6666-6666-6666-666666666666',
+    support: '77777777-7777-7777-7777-777777777777',
+    product: '88888888-8888-8888-8888-888888888888',
+    design: '99999999-9999-9999-9999-999999999999',
+};
+function pages() {
+    return [
+        { id: IDS.engineering, title: 'Engineering Docs', archived: false, parentId: null },
+        { id: IDS.architecture, title: 'Architecture', archived: false, parentId: IDS.engineering },
+        { id: IDS.marketing, title: 'Marketing', archived: false, parentId: null },
+    ];
+}
+function manyPages() {
+    return [
+        { id: IDS.engineering, title: 'Engineering Docs', archived: false, parentId: null },
+        { id: IDS.architecture, title: 'Architecture', archived: false, parentId: IDS.engineering },
+        { id: IDS.marketing, title: 'Marketing', archived: false, parentId: null },
+        { id: IDS.finance, title: 'Finance', archived: false, parentId: null },
+        { id: IDS.ops, title: 'Operations', archived: false, parentId: null },
+        { id: IDS.sales, title: 'Sales', archived: false, parentId: null },
+        { id: IDS.support, title: 'Support', archived: false, parentId: null },
+        { id: IDS.product, title: 'Product', archived: false, parentId: null },
+        { id: IDS.design, title: 'Design', archived: false, parentId: null },
+    ];
+}
+function state(mode = 'selected_roots') {
+    return buildInitialState({
+        tree: buildPickerTree(pages()),
+        existingRootPageIds: [],
+        currentCrawlMode: mode,
+    });
+}
+async function waitForInkInput() {
+    await new Promise((resolve) => setTimeout(resolve, 10));
+}
+function fakeInkInstance() {
+    return {
+        rerender: vi.fn(),
+        unmount: vi.fn(),
+        waitUntilExit: vi.fn(async () => undefined),
+    };
+}
+function normalizeFrameWrap(frame) {
+    return frame?.replace(/\n/g, ' ') ?? '';
+}
+afterEach(() => {
+    vi.useRealTimers();
+});
+describe('notionPickerCommandForInkInput', () => {
+    it('maps browse, search, and confirm input to reducer commands', () => {
+        expect(notionPickerCommandForInkInput('', { downArrow: true }, state().search, null)).toBe('cursor-down');
+        expect(notionPickerCommandForInkInput('', { upArrow: true }, state().search, null)).toBe('cursor-up');
+        expect(notionPickerCommandForInkInput('', { rightArrow: true }, state().search, null)).toBe('cursor-right');
+        expect(notionPickerCommandForInkInput('', { leftArrow: true }, state().search, null)).toBe('cursor-left');
+        expect(notionPickerCommandForInkInput(' ', {}, state().search, null)).toBe('toggle-check');
+        expect(notionPickerCommandForInkInput('/', {}, state().search, null)).toBe('search-start');
+        expect(notionPickerCommandForInkInput('a', {}, state().search, null)).toBe('select-all-visible');
+        expect(notionPickerCommandForInkInput('n', {}, state().search, null)).toBe('select-none');
+        expect(notionPickerCommandForInkInput('s', {}, state().search, null)).toBe('save-request');
+        expect(notionPickerCommandForInkInput('q', {}, state().search, null)).toBe('quit');
+        expect(notionPickerCommandForInkInput('c', { ctrl: true }, state().search, null)).toBe('quit');
+        expect(notionPickerCommandForInkInput('x', {}, { editing: true, query: '' }, null)).toEqual({
+            type: 'search-input',
+            value: 'x',
+        });
+        expect(notionPickerCommandForInkInput('', { backspace: true }, { editing: true, query: 'x' }, null)).toBe('search-backspace');
+        expect(notionPickerCommandForInkInput('', { return: true }, { editing: true, query: 'x' }, null)).toBe('search-submit');
+        expect(notionPickerCommandForInkInput('', { escape: true }, { editing: true, query: 'x' }, null)).toBe('search-cancel');
+        expect(notionPickerCommandForInkInput('y', {}, state().search, 'mode-switch')).toBe('save-confirm');
+        expect(notionPickerCommandForInkInput('', { return: true }, state().search, 'mode-switch')).toBe('save-confirm');
+        expect(notionPickerCommandForInkInput('n', {}, state().search, 'mode-switch')).toBe('save-cancel');
+    });
+});
+describe('window helpers', () => {
+    it('centers the selected row and returns the visible slice', () => {
+        expect(windowOffset(20, 10, 5)).toBe(8);
+        expect(windowItems(['a', 'b', 'c', 'd', 'e'], 3, 3)).toEqual({ items: ['c', 'd', 'e'], offset: 2 });
+    });
+    it('clamps picker width to the design rule', () => {
+        expect(resolveNotionPickerWidth(200)).toBe(120);
+        expect(resolveNotionPickerWidth(100)).toBe(96);
+        expect(resolveNotionPickerWidth(50)).toBe(60);
+        expect(resolveNotionPickerWidth(undefined)).toBe(96);
+    });
+});
+describe('NotionPickerApp', () => {
+    it('renders spec banners, row glyphs, search visibility, and hint text', () => {
+        const initialState = {
+            ...state('all_accessible'),
+            preLoadWarnings: ['1 stored root_page_ids no longer visible'],
+        };
+        const { lastFrame } = renderInkTest(_jsx(NotionPickerApp, { initialState: initialState, connectionId: "notion-main", workspaceLabel: "Design Workspace", cappedAtCount: 5000, currentCrawlMode: "all_accessible", terminalRows: 24, terminalWidth: 100, onExit: vi.fn() }));
+        const frame = lastFrame() ?? '';
+        expect(frame).toContain('Notion pages visible to integration "Design Workspace"');
+        expect(frame).toContain('5000-page cap reached - some pages not shown');
+        expect(frame).toContain('1 stored root_page_ids no longer visible - they will be removed if you save');
+        expect(frame).toContain('▸ [ ] Engineering Docs ▸ (1)');
+        expect(frame).toContain('  [ ] Marketing');
+        expect(frame).not.toContain('Search ready: -');
+        expect(frame).toContain('space toggle · enter expand · / search · a all · n none · s save & exit · q quit');
+    });
+    it('renders partial discovery warnings without stale-root save suffix', () => {
+        const initialState = {
+            ...state(),
+            preLoadWarnings: ['Notion search stopped early: rate limit after first page'],
+        };
+        const { lastFrame } = renderInkTest(_jsx(NotionPickerApp, { initialState: initialState, connectionId: "notion-main", workspaceLabel: "Design Workspace", cappedAtCount: null, currentCrawlMode: "selected_roots", terminalRows: 24, terminalWidth: 100, onExit: vi.fn() }));
+        const frame = lastFrame() ?? '';
+        expect(frame).toContain('Notion search stopped early: rate limit after first page');
+        expect(frame).not.toContain('Notion search stopped early: rate limit after first page - they will be removed if you save');
+    });
+    it('renders checked parents and locked descendants with the locked design glyphs', () => {
+        const initialState = {
+            ...state(),
+            checked: new Set([IDS.engineering]),
+            expanded: new Set([IDS.engineering]),
+        };
+        const { lastFrame } = renderInkTest(_jsx(NotionPickerApp, { initialState: initialState, connectionId: "notion-main", workspaceLabel: "Design Workspace", cappedAtCount: null, currentCrawlMode: "selected_roots", terminalRows: 24, terminalWidth: 100, onExit: vi.fn() }));
+        const frame = lastFrame() ?? '';
+        expect(frame).toContain('▸ [×] Engineering Docs ▾');
+        expect(frame).toContain('  [~]   Architecture');
+    });
+    it('supports keyboard selection, all_accessible confirmation, and save callback', async () => {
+        const onExit = vi.fn();
+        const { stdin, lastFrame } = renderInkTest(_jsx(NotionPickerApp, { initialState: state('all_accessible'), connectionId: "notion-main", workspaceLabel: "Design Workspace", cappedAtCount: null, currentCrawlMode: "all_accessible", terminalRows: 24, terminalWidth: 100, onExit: onExit }));
+        stdin.write(' ');
+        await waitForInkInput();
+        expect(lastFrame()).toContain('[×] Engineering Docs');
+        stdin.write('s');
+        await waitForInkInput();
+        expect(normalizeFrameWrap(lastFrame())).toContain('Save will switch crawl_mode all_accessible -> selected_roots and limit ingest to 1 selected page. [y] confirm  [esc] back');
+        stdin.write('y');
+        await waitForInkInput();
+        expect(onExit).toHaveBeenCalledWith({ kind: 'save', rootPageIds: [IDS.engineering] });
+    });
+    it('removes transient hints after their expiry time', async () => {
+        vi.useFakeTimers();
+        const onExit = vi.fn();
+        const { stdin, lastFrame } = renderInkTest(_jsx(NotionPickerApp, { initialState: state(), connectionId: "notion-main", workspaceLabel: "Design Workspace", cappedAtCount: null, currentCrawlMode: "selected_roots", terminalRows: 24, terminalWidth: 100, onExit: onExit }));
+        await act(async () => {
+            stdin.write('s');
+            await vi.advanceTimersByTimeAsync(10);
+        });
+        expect(lastFrame()).toContain('Select at least one page or press q to quit');
+        await act(async () => {
+            await vi.advanceTimersByTimeAsync(2500);
+        });
+        expect(lastFrame()).not.toContain('Select at least one page or press q to quit');
+        expect(onExit).not.toHaveBeenCalled();
+    });
+    it('renders row-window overflow indicators when the visible list is clipped', async () => {
+        const onExit = vi.fn();
+        const initialState = buildInitialState({
+            tree: buildPickerTree(manyPages()),
+            existingRootPageIds: [],
+            currentCrawlMode: 'selected_roots',
+        });
+        initialState.expanded = new Set([IDS.engineering]);
+        const { stdin, lastFrame } = renderInkTest(_jsx(NotionPickerApp, { initialState: initialState, connectionId: "notion-main", workspaceLabel: "Design Workspace", cappedAtCount: null, currentCrawlMode: "selected_roots", terminalRows: 13, terminalWidth: 100, onExit: onExit }));
+        expect(lastFrame()).toContain('↓ 4 more');
+        stdin.write('\u001B[B');
+        stdin.write('\u001B[B');
+        stdin.write('\u001B[B');
+        stdin.write('\u001B[B');
+        await waitForInkInput();
+        const frame = lastFrame() ?? '';
+        expect(frame).toContain('↑ ');
+        expect(frame).toContain('↓ ');
+        expect(onExit).not.toHaveBeenCalled();
+    });
+    it('returns quit without saving', async () => {
+        const onExit = vi.fn();
+        const { stdin } = renderInkTest(_jsx(NotionPickerApp, { initialState: state(), connectionId: "notion-main", workspaceLabel: "Design Workspace", cappedAtCount: null, currentCrawlMode: "selected_roots", terminalRows: 24, terminalWidth: 100, onExit: onExit }));
+        stdin.write('q');
+        await waitForInkInput();
+        expect(onExit).toHaveBeenCalledWith({ kind: 'quit' });
+    });
+});
+describe('renderNotionPickerTui', () => {
+    it('returns the app result from the Ink runtime', async () => {
+        const io = {
+            stdin: { isTTY: true, setRawMode: vi.fn() },
+            stdout: { isTTY: true, columns: 100, rows: 24, write: vi.fn() },
+            stderr: { write: vi.fn() },
+        };
+        const renderInk = vi.fn((_tree, _options) => fakeInkInstance());
+        await expect(renderNotionPickerTui({
+            initialState: state(),
+            connectionId: 'notion-main',
+            workspaceLabel: 'Design Workspace',
+            cappedAtCount: null,
+            currentCrawlMode: 'selected_roots',
+        }, io, { renderInk })).resolves.toEqual({ kind: 'quit' });
+        expect(renderInk).toHaveBeenCalledOnce();
+    });
+    it('sanitizes render errors and tells the user to use no-input mode', async () => {
+        expect(sanitizeNotionPickerTuiError(new Error('token=secret https://api.notion.com/v1/search'))).toBe('[redacted] [redacted-url]');
+    });
+    it('falls back to quit with a scripted-mode hint when Ink cannot initialize', async () => {
+        let stderr = '';
+        const io = {
+            stdin: { isTTY: false, setRawMode: vi.fn() },
+            stdout: { isTTY: false, columns: 100, rows: 24, write: vi.fn() },
+            stderr: {
+                write(chunk) {
+                    stderr += chunk;
+                },
+            },
+        };
+        await expect(renderNotionPickerTui({
+            initialState: state(),
+            connectionId: 'notion-main',
+            workspaceLabel: 'Design Workspace',
+            cappedAtCount: null,
+            currentCrawlMode: 'selected_roots',
+        }, io, {
+            renderInk: vi.fn(() => {
+                throw new Error('token=secret');
+            }),
+        })).resolves.toEqual({ kind: 'quit' });
+        expect(stderr).toContain('Use --no-input --root-page-id <UUID> for scripted mode');
+        expect(stderr).not.toContain('secret');
+    });
+});

package/dist/commands/connection-notion.d.ts

@@ -0,0 +1,37 @@
+import { type NotionApi } from '@ktx/context/ingest';
+import { type KtxLocalProject, loadKtxProject } from '@ktx/context/project';
+import type { KtxCliIo } from '../index.js';
+import { type NotionPickerPageInput } from './connection-notion-tree.js';
+import { type NotionPickerTuiIo, type PickerRenderInput, type PickerRenderResult } from './connection-notion-tui.js';
+export type KtxConnectionNotionArgs = {
+    command: 'pick';
+    projectDir: string;
+    connectionId: string;
+    mode: 'interactive';
+} | {
+    command: 'pick';
+    projectDir: string;
+    connectionId: string;
+    mode: 'non-interactive';
+    rootPageIds: string[];
+};
+export type NotionPickerApi = Pick<NotionApi, 'search' | 'retrieveBotUser'>;
+export type { PickerRenderInput, PickerRenderResult };
+interface KtxConnectionNotionDeps {
+    env?: Record<string, string | undefined>;
+    loadProject?: typeof loadKtxProject;
+    createNotionApi?: (authToken: string) => NotionPickerApi;
+    renderPicker?: (input: PickerRenderInput, io: NotionPickerTuiIo) => Promise<PickerRenderResult>;
+}
+export declare function normalizeNotionPageId(value: string): string;
+export declare function notionPickerPageFromSearchResult(result: Record<string, unknown>): NotionPickerPageInput;
+export declare function discoverNotionPickerPages(api: NotionPickerApi, options?: {
+    cap?: number;
+}): Promise<{
+    pages: NotionPickerPageInput[];
+    cappedAtCount: number | null;
+    warnings: string[];
+}>;
+export declare function resolveNotionWorkspaceLabel(api: NotionPickerApi, connectionId: string): Promise<string>;
+export declare function applyNotionPickerWriteback(project: KtxLocalProject, connectionId: string, rootPageIds: string[]): Promise<void>;
+export declare function runKtxConnectionNotion(args: KtxConnectionNotionArgs, io?: KtxCliIo, deps?: KtxConnectionNotionDeps): Promise<number>;

package/dist/commands/connection-notion.js

@@ -0,0 +1,203 @@
+import { parseNotionConnectionConfig, resolveNotionAuthToken } from '@ktx/context/connections';
+import { NotionClient } from '@ktx/context/ingest';
+import { loadKtxProject, serializeKtxProjectConfig, } from '@ktx/context/project';
+import { profileMark } from '../startup-profile.js';
+import { buildInitialState, buildPickerTree } from './connection-notion-tree.js';
+import { renderNotionPickerTui, } from './connection-notion-tui.js';
+profileMark('module:commands/connection-notion');
+const NOTION_PICKER_PAGE_CAP = 5000;
+function assertSafeConnectionId(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 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 notionConnection(project, connectionId) {
+    const connection = project.config.connections[connectionId];
+    if (!connection) {
+        throw new Error(`Connection "${connectionId}" not found`);
+    }
+    if (connection.driver !== 'notion') {
+        throw new Error(`Connection "${connectionId}" is not a Notion connection`);
+    }
+    return connection;
+}
+export async function applyNotionPickerWriteback(project, connectionId, rootPageIds) {
+    if (rootPageIds.length === 0) {
+        throw new Error('connection notion pick requires at least one root page id');
+    }
+    const existing = notionConnection(project, connectionId);
+    const nextConfig = {
+        ...project.config,
+        connections: {
+            ...project.config.connections,
+            [connectionId]: {
+                ...existing,
+                crawl_mode: 'selected_roots',
+                root_page_ids: rootPageIds,
+            },
+        },
+    };
+    await project.fileStore.writeFile('ktx.yaml', serializeKtxProjectConfig(nextConfig), 'ktx', 'ktx@example.com', `Pick Notion roots: ${connectionId} (${rootPageIds.length} pages)`);
+}
+export async function runKtxConnectionNotion(args, io = process, deps = {}) {
+    try {
+        assertSafeConnectionId(args.connectionId);
+        const loadProject = deps.loadProject ?? loadKtxProject;
+        if (args.mode === 'interactive') {
+            const project = await loadProject({ projectDir: args.projectDir });
+            const rawConnection = notionConnection(project, args.connectionId);
+            const notion = parseNotionConnectionConfig(rawConnection);
+            const authToken = await resolveNotionAuthToken(notion.auth_token_ref, { env: deps.env });
+            const api = deps.createNotionApi ? deps.createNotionApi(authToken) : new NotionClient(authToken);
+            const discovery = await discoverNotionPickerPages(api);
+            const tree = buildPickerTree(discovery.pages);
+            const initialState = buildInitialState({
+                tree,
+                existingRootPageIds: notion.root_page_ids,
+                currentCrawlMode: notion.crawl_mode,
+            });
+            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 result = await (deps.renderPicker ?? renderNotionPickerTui)({
+                initialState: renderState,
+                connectionId: args.connectionId,
+                workspaceLabel,
+                cappedAtCount: discovery.cappedAtCount,
+                currentCrawlMode: notion.crawl_mode,
+            }, io);
+            if (result.kind === 'quit') {
+                io.stdout.write('No changes saved.\n');
+                return 0;
+            }
+            await applyNotionPickerWriteback(project, args.connectionId, result.rootPageIds);
+            io.stdout.write(`Connection: ${args.connectionId}\n`);
+            io.stdout.write(`rootPageIds: ${result.rootPageIds.length}\n`);
+            io.stdout.write('crawlMode: selected_roots\n');
+            return 0;
+        }
+        const project = await loadProject({ projectDir: args.projectDir });
+        await applyNotionPickerWriteback(project, args.connectionId, args.rootPageIds);
+        io.stdout.write(`Connection: ${args.connectionId}\n`);
+        io.stdout.write(`rootPageIds: ${args.rootPageIds.length}\n`);
+        io.stdout.write('crawlMode: selected_roots\n');
+        return 0;
+    }
+    catch (error) {
+        io.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+}

package/dist/commands/connection-notion.test.d.ts

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