@kaelio/ktx 0.0.0 → 0.1.0-rc.0

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

@@ -0,0 +1,237 @@
+import { describe, expect, it } from 'vitest';
+import { buildInitialState, buildPickerTree, canToggle, clearExpiredTransientHint, filterTree, flattenSelection, moveCursor, reducer, selectAllVisible, selectNone, toggleChecked, TRANSIENT_HINT_DURATION_MS, visibleNodeIds, } from './connection-notion-tree.js';
+const IDS = {
+    engineering: '11111111-1111-1111-1111-111111111111',
+    architecture: '22222222-2222-2222-2222-222222222222',
+    onboarding: '33333333-3333-3333-3333-333333333333',
+    marketing: '44444444-4444-4444-4444-444444444444',
+    journal: '55555555-5555-5555-5555-555555555555',
+    orphan: '66666666-6666-6666-6666-666666666666',
+    duplicate: '77777777-7777-7777-7777-777777777777',
+    cycleA: '88888888-8888-8888-8888-888888888888',
+    cycleB: '99999999-9999-9999-9999-999999999999',
+};
+function pages() {
+    return [
+        { id: IDS.marketing, title: 'Marketing', archived: false, parentId: null },
+        { id: IDS.onboarding, title: 'Onboarding', archived: false, parentId: IDS.engineering },
+        { id: IDS.engineering, title: 'Engineering Docs', archived: false, parentId: null },
+        { id: IDS.architecture, title: 'Architecture', archived: false, parentId: IDS.engineering },
+        { id: IDS.journal, title: 'Daily journal', archived: true, parentId: IDS.marketing },
+        { id: IDS.orphan, title: '', archived: false, parentId: 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa' },
+        { id: IDS.duplicate, title: 'Original duplicate', archived: false, parentId: null },
+        { id: IDS.duplicate, title: 'Ignored duplicate', archived: true, parentId: IDS.marketing },
+        { id: IDS.cycleA, title: 'Cycle A', archived: false, parentId: IDS.cycleB },
+        { id: IDS.cycleB, title: 'Cycle B', archived: false, parentId: IDS.cycleA },
+    ];
+}
+describe('buildPickerTree', () => {
+    it('deduplicates pages, sorts siblings, preserves archived flags, roots orphans, and breaks cycles', () => {
+        const tree = buildPickerTree(pages());
+        const byId = new Map(tree.map((node) => [node.id, node]));
+        expect(tree.map((node) => node.title)).toEqual([
+            'Cycle A',
+            'Cycle B',
+            'Engineering Docs',
+            'Architecture',
+            'Onboarding',
+            'Marketing',
+            'Daily journal',
+            'Original duplicate',
+            'Untitled',
+        ]);
+        expect(byId.get(IDS.engineering)?.childIds).toEqual([IDS.architecture, IDS.onboarding]);
+        expect(byId.get(IDS.architecture)).toMatchObject({
+            depth: 1,
+            parentId: IDS.engineering,
+            path: 'Engineering Docs / Architecture',
+        });
+        expect(byId.get(IDS.journal)).toMatchObject({
+            archived: true,
+            depth: 1,
+            path: 'Marketing / Daily journal',
+        });
+        expect(byId.get(IDS.orphan)).toMatchObject({
+            title: 'Untitled',
+            parentId: null,
+            depth: 0,
+            path: 'Untitled',
+        });
+        expect(byId.get(IDS.duplicate)).toMatchObject({
+            title: 'Original duplicate',
+            archived: false,
+            parentId: null,
+        });
+        expect(byId.get(IDS.cycleA)?.parentId).toBeNull();
+        expect(byId.get(IDS.cycleB)?.parentId).toBe(IDS.cycleA);
+    });
+});
+describe('selection invariants', () => {
+    it('checking a parent locks descendants and keeps checked ids minimal', () => {
+        const state = buildInitialState({
+            tree: buildPickerTree(pages()),
+            existingRootPageIds: [],
+            currentCrawlMode: 'selected_roots',
+        });
+        const checkedParent = toggleChecked(state, IDS.engineering, 1000);
+        expect([...checkedParent.checked]).toEqual([IDS.engineering]);
+        expect(canToggle(IDS.architecture, checkedParent)).toEqual({
+            ok: false,
+            reason: "Locked by 'Engineering Docs' - uncheck parent first",
+        });
+        const lockedChildAttempt = toggleChecked(checkedParent, IDS.architecture, 2000);
+        expect([...lockedChildAttempt.checked]).toEqual([IDS.engineering]);
+        expect(lockedChildAttempt.transientHint).toEqual({
+            text: "Locked by 'Engineering Docs' - uncheck parent first",
+            expiresAt: 4500,
+        });
+        const uncheckedParent = toggleChecked(lockedChildAttempt, IDS.engineering, 3000);
+        expect([...uncheckedParent.checked]).toEqual([]);
+        expect(canToggle(IDS.architecture, uncheckedParent)).toEqual({ ok: true });
+    });
+    it('normalizes stored roots, reports stale roots, expands checked ancestors, and flattens descendants', () => {
+        const state = buildInitialState({
+            tree: buildPickerTree(pages()),
+            existingRootPageIds: [
+                IDS.engineering.replaceAll('-', ''),
+                IDS.architecture,
+                'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa',
+            ],
+            currentCrawlMode: 'selected_roots',
+        });
+        expect([...state.checked]).toEqual([IDS.engineering]);
+        expect([...state.expanded]).toEqual([]);
+        expect(state.cursorId).toBe(IDS.cycleA);
+        expect(state.preLoadWarnings).toEqual(['1 stored root_page_ids no longer visible']);
+        expect(flattenSelection(new Set([IDS.engineering, IDS.architecture]), state.byId)).toEqual([IDS.engineering]);
+    });
+});
+describe('search and cursor movement', () => {
+    it('filters by title and path while deriving auto-expanded ancestors', () => {
+        const state = buildInitialState({
+            tree: buildPickerTree(pages()),
+            existingRootPageIds: [],
+            currentCrawlMode: 'selected_roots',
+        });
+        const searching = {
+            ...state,
+            search: { editing: false, query: 'architecture' },
+        };
+        expect(filterTree(searching)).toEqual({
+            visibleIds: new Set([IDS.engineering, IDS.architecture]),
+            autoExpand: new Set([IDS.engineering]),
+        });
+        expect(visibleNodeIds(searching)).toEqual([IDS.engineering, IDS.architecture]);
+    });
+    it('moves the cursor through visible nodes and implements left/right tree semantics', () => {
+        const state = buildInitialState({
+            tree: buildPickerTree(pages()),
+            existingRootPageIds: [],
+            currentCrawlMode: 'selected_roots',
+        });
+        const atEngineering = {
+            ...state,
+            cursorId: IDS.engineering,
+            expanded: new Set([IDS.engineering]),
+        };
+        expect(moveCursor(atEngineering, 'down').cursorId).toBe(IDS.architecture);
+        expect(moveCursor({ ...atEngineering, cursorId: IDS.architecture }, 'up').cursorId).toBe(IDS.engineering);
+        expect(moveCursor(atEngineering, 'right').cursorId).toBe(IDS.architecture);
+        expect(moveCursor({ ...atEngineering, cursorId: IDS.architecture }, 'left').cursorId).toBe(IDS.engineering);
+        expect([...moveCursor(atEngineering, 'left').expanded]).toEqual([]);
+        expect([...moveCursor({ ...state, cursorId: IDS.marketing }, 'right').expanded]).toContain(IDS.marketing);
+    });
+});
+describe('bulk actions and reducer effects', () => {
+    it('selects only matching visible roots under search and clears selection', () => {
+        const state = buildInitialState({
+            tree: buildPickerTree(pages()),
+            existingRootPageIds: [IDS.marketing],
+            currentCrawlMode: 'selected_roots',
+        });
+        const searching = {
+            ...state,
+            search: { editing: false, query: 'architecture' },
+        };
+        const selected = selectAllVisible(searching);
+        expect(flattenSelection(selected.checked, selected.byId)).toEqual([IDS.architecture, IDS.marketing]);
+        expect([...selectNone(selected).checked]).toEqual([]);
+    });
+    it('returns save immediately for selected_roots and requires confirmation for all_accessible', () => {
+        const selectedRoots = toggleChecked(buildInitialState({
+            tree: buildPickerTree(pages()),
+            existingRootPageIds: [],
+            currentCrawlMode: 'selected_roots',
+        }), IDS.marketing, 1000);
+        expect(reducer(selectedRoots, 'save-request')).toEqual({
+            next: selectedRoots,
+            effect: 'save',
+        });
+        const allAccessible = {
+            ...selectedRoots,
+            currentCrawlMode: 'all_accessible',
+        };
+        const confirm = reducer(allAccessible, 'save-request');
+        expect(confirm).toEqual({
+            next: { ...allAccessible, pendingConfirm: 'mode-switch' },
+            effect: null,
+        });
+        expect(reducer(confirm.next, 'save-cancel')).toEqual({
+            next: { ...allAccessible, pendingConfirm: null },
+            effect: null,
+        });
+        expect(reducer(confirm.next, 'save-confirm')).toEqual({
+            next: { ...allAccessible, pendingConfirm: null },
+            effect: 'save',
+        });
+    });
+    it('blocks empty saves, updates search state, and quits without saving', () => {
+        const state = buildInitialState({
+            tree: buildPickerTree(pages()),
+            existingRootPageIds: [],
+            currentCrawlMode: 'selected_roots',
+        });
+        const blockedSave = reducer(state, 'save-request', 9000);
+        expect(blockedSave).toEqual({
+            next: {
+                ...state,
+                transientHint: {
+                    text: 'Select at least one page or press q to quit',
+                    expiresAt: 9000 + TRANSIENT_HINT_DURATION_MS,
+                },
+            },
+            effect: null,
+        });
+        expect(reducer(reducer(reducer(state, 'search-start').next, { type: 'search-input', value: 'a' }).next, 'search-submit').next.search).toEqual({ editing: false, query: 'a' });
+        expect(reducer(state, 'quit')).toEqual({
+            next: state,
+            effect: 'quit-without-save',
+        });
+    });
+    it('clears transient hints only when their expiry time has passed', () => {
+        const state = buildInitialState({
+            tree: buildPickerTree(pages()),
+            existingRootPageIds: [],
+            currentCrawlMode: 'selected_roots',
+        });
+        const withHint = {
+            ...state,
+            transientHint: {
+                text: 'Select at least one page or press q to quit',
+                expiresAt: 11500,
+            },
+        };
+        expect(clearExpiredTransientHint(withHint, 11499)).toBe(withHint);
+        expect(clearExpiredTransientHint(withHint, 11500)).toEqual({
+            ...withHint,
+            transientHint: null,
+        });
+        expect(reducer(withHint, 'clear-transient-hint', 11501)).toEqual({
+            next: {
+                ...withHint,
+                transientHint: null,
+            },
+            effect: null,
+        });
+    });
+});

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

@@ -0,0 +1,71 @@
+import { type ReactNode } from 'react';
+import { type PickerCommand, type PickerState } from './connection-notion-tree.js';
+import type { KtxCliIo } from '../index.js';
+export interface NotionPickerTuiIo extends KtxCliIo {
+    stdin?: {
+        isTTY?: boolean;
+        setRawMode?(value: boolean): void;
+    };
+    stdout: KtxCliIo['stdout'] & {
+        isTTY?: boolean;
+        columns?: number;
+        rows?: number;
+    };
+}
+interface InkKey {
+    leftArrow?: boolean;
+    rightArrow?: boolean;
+    upArrow?: boolean;
+    downArrow?: boolean;
+    return?: boolean;
+    escape?: boolean;
+    ctrl?: boolean;
+    backspace?: boolean;
+    delete?: boolean;
+}
+export type PickerRenderResult = {
+    kind: 'save';
+    rootPageIds: string[];
+} | {
+    kind: 'quit';
+};
+export interface PickerRenderInput {
+    initialState: PickerState;
+    connectionId: string;
+    workspaceLabel: string;
+    cappedAtCount: number | null;
+    currentCrawlMode: 'all_accessible' | 'selected_roots';
+}
+interface NotionPickerAppProps extends PickerRenderInput {
+    terminalRows?: number;
+    terminalWidth?: number;
+    env?: NodeJS.ProcessEnv;
+    onExit(result: PickerRenderResult): void;
+}
+export interface NotionPickerInkInstance {
+    rerender(tree: ReactNode): void;
+    unmount(): void;
+    waitUntilExit(): Promise<void>;
+}
+export interface NotionPickerInkRenderOptions {
+    stdin?: NotionPickerTuiIo['stdin'];
+    stdout: NotionPickerTuiIo['stdout'];
+    stderr: NotionPickerTuiIo['stderr'];
+    exitOnCtrlC: boolean;
+    patchConsole: boolean;
+    maxFps: number;
+    alternateScreen: boolean;
+}
+export declare function resolveNotionPickerWidth(columns: number | undefined): number;
+export declare function sanitizeNotionPickerTuiError(error: unknown): string;
+export declare function windowOffset(count: number, selected: number, visible: number): number;
+export declare function windowItems<T>(items: T[], selected: number, visible: number): {
+    items: T[];
+    offset: number;
+};
+export declare function notionPickerCommandForInkInput(input: string, key: InkKey, search: PickerState['search'], pendingConfirm: PickerState['pendingConfirm']): PickerCommand | null;
+export declare function NotionPickerApp(props: NotionPickerAppProps): ReactNode;
+export declare function renderNotionPickerTui(input: PickerRenderInput, io: NotionPickerTuiIo, options?: {
+    renderInk?: (tree: ReactNode, options: NotionPickerInkRenderOptions) => NotionPickerInkInstance;
+}): Promise<PickerRenderResult>;
+export {};

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

@@ -0,0 +1,224 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/* @jsxImportSource react */
+import { Box, Text, render as renderInkRuntime, useApp, useInput } from 'ink';
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { filterTree, flattenSelection, isAncestorChecked, reducer, visibleNodeIds, } from './connection-notion-tree.js';
+const COLOR_THEME = {
+    text: 'white',
+    muted: 'gray',
+    active: 'cyan',
+    warning: 'yellow',
+};
+const NO_COLOR_THEME = {
+    text: 'white',
+    muted: 'white',
+    active: 'white',
+    warning: 'white',
+};
+function resolveTheme(env = process.env) {
+    return env.NO_COLOR || env.TERM === 'dumb' ? NO_COLOR_THEME : COLOR_THEME;
+}
+export function resolveNotionPickerWidth(columns) {
+    const resolvedColumns = columns ?? 100;
+    return Math.max(60, Math.min(120, resolvedColumns - 4));
+}
+function staleWarningText(warning) {
+    return warning.includes('stored root_page_ids no longer visible')
+        ? `${warning} - they will be removed if you save`
+        : warning;
+}
+function selectedPageCountText(count) {
+    return `${count} selected ${count === 1 ? 'page' : 'pages'}`;
+}
+function rowMatchesSearch(state, nodeId) {
+    const query = state.search.query.trim().toLocaleLowerCase();
+    if (!query) {
+        return false;
+    }
+    const node = state.byId.get(nodeId);
+    if (!node) {
+        return false;
+    }
+    return node.title.toLocaleLowerCase().includes(query) || node.path.toLocaleLowerCase().includes(query);
+}
+export function sanitizeNotionPickerTuiError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message
+        .replace(/[a-z][a-z0-9+.-]*:\/\/[^\s]+/gi, '[redacted-url]')
+        .replace(/\b(api[_-]?key|password|token|secret)=\S+/gi, '[redacted]');
+}
+export function windowOffset(count, selected, visible) {
+    if (count <= visible)
+        return 0;
+    return Math.max(0, Math.min(count - visible, selected - Math.floor(visible / 2)));
+}
+export function windowItems(items, selected, visible) {
+    const offset = windowOffset(items.length, selected, visible);
+    return { items: items.slice(offset, offset + visible), offset };
+}
+function truncateText(value, width) {
+    if (value.length <= width)
+        return value;
+    if (width <= 3)
+        return value.slice(0, width);
+    return `${value.slice(0, width - 3)}...`;
+}
+export function notionPickerCommandForInkInput(input, key, search, pendingConfirm) {
+    if (pendingConfirm) {
+        if (input === 'y' || key.return)
+            return 'save-confirm';
+        if (input === 'n' || key.escape)
+            return 'save-cancel';
+        if (key.ctrl === true && input === 'c')
+            return 'quit';
+        return null;
+    }
+    if (search.editing) {
+        if (key.escape)
+            return 'search-cancel';
+        if (key.return)
+            return 'search-submit';
+        if (key.backspace || key.delete)
+            return 'search-backspace';
+        if (key.downArrow)
+            return 'cursor-down';
+        if (key.upArrow)
+            return 'cursor-up';
+        if (input.length === 1 && input >= ' ' && input !== '\u007f')
+            return { type: 'search-input', value: input };
+        return null;
+    }
+    if (key.ctrl === true && input === 'c')
+        return 'quit';
+    if (key.upArrow)
+        return 'cursor-up';
+    if (key.downArrow)
+        return 'cursor-down';
+    if (key.leftArrow)
+        return 'cursor-left';
+    if (key.rightArrow)
+        return 'cursor-right';
+    if (key.return)
+        return 'expand';
+    if (input === ' ')
+        return 'toggle-check';
+    if (input === '/')
+        return 'search-start';
+    if (input === 'a')
+        return 'select-all-visible';
+    if (input === 'n')
+        return 'select-none';
+    if (input === 's')
+        return 'save-request';
+    if (input === 'q' || key.escape)
+        return 'quit';
+    return null;
+}
+function PickerRow(props) {
+    const node = props.state.byId.get(props.nodeId);
+    if (!node)
+        return null;
+    const focused = props.state.cursorId === node.id;
+    const locked = isAncestorChecked(node.id, props.state.checked, props.state.byId);
+    const checked = props.state.checked.has(node.id);
+    const glyph = locked ? '[~]' : checked ? '[×]' : '[ ]';
+    const children = node.childIds.length > 0 ? (props.state.expanded.has(node.id) ? ' ▾' : ` ▸ (${node.childIds.length})`) : '';
+    const prefix = `${focused ? '▸' : ' '} ${glyph} ${' '.repeat(node.depth * 2)}`;
+    const color = focused ? props.theme.active : locked || node.archived ? props.theme.muted : props.theme.text;
+    const title = truncateText(`${node.title}${children}`, Math.max(10, props.width - prefix.length));
+    const inverse = rowMatchesSearch(props.state, node.id);
+    return (_jsxs(Text, { color: color, strikethrough: node.archived, children: [prefix, _jsx(Text, { inverse: inverse, children: title })] }));
+}
+export function NotionPickerApp(props) {
+    const app = useApp();
+    const [state, setState] = useState(props.initialState);
+    const stateRef = useRef(state);
+    const theme = useMemo(() => resolveTheme(props.env), [props.env]);
+    const visibleIds = visibleNodeIds(state);
+    const selectedIndex = Math.max(0, visibleIds.indexOf(state.cursorId));
+    const reservedRows = state.pendingConfirm === 'mode-switch' ? 9 : 8;
+    const visibleRows = Math.max(5, Math.min(20, (props.terminalRows ?? 24) - reservedRows));
+    const rows = windowItems(visibleIds, selectedIndex, visibleRows);
+    const hiddenAbove = rows.offset;
+    const hiddenBelow = Math.max(0, visibleIds.length - rows.offset - rows.items.length);
+    const searchMatchCount = filterTree(state).visibleIds.size;
+    const width = resolveNotionPickerWidth(props.terminalWidth);
+    const showSearch = state.search.editing || state.search.query.trim().length > 0;
+    const selectedCount = flattenSelection(state.checked, state.byId).length;
+    stateRef.current = state;
+    useEffect(() => {
+        const hint = state.transientHint;
+        if (!hint) {
+            return;
+        }
+        const clearHint = () => {
+            setState((current) => {
+                const { next } = reducer(current, 'clear-transient-hint');
+                stateRef.current = next;
+                return next;
+            });
+        };
+        const delay = hint.expiresAt - Date.now();
+        if (delay <= 0) {
+            clearHint();
+            return;
+        }
+        const timeout = setTimeout(clearHint, delay);
+        return () => clearTimeout(timeout);
+    }, [state.transientHint?.expiresAt]);
+    useInput((input, key) => {
+        const command = notionPickerCommandForInkInput(input, key, stateRef.current.search, stateRef.current.pendingConfirm);
+        if (!command) {
+            return;
+        }
+        const { next, effect } = reducer(stateRef.current, command);
+        stateRef.current = next;
+        setState(next);
+        if (effect === 'save') {
+            props.onExit({ kind: 'save', rootPageIds: flattenSelection(next.checked, next.byId) });
+            app.exit();
+            return;
+        }
+        if (effect === 'quit-without-save') {
+            props.onExit({ kind: 'quit' });
+            app.exit();
+        }
+    });
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { color: theme.active, children: ["Notion pages visible to integration \"", props.workspaceLabel, "\""] }), props.cappedAtCount ? _jsxs(Text, { color: theme.warning, children: [props.cappedAtCount, "-page cap reached - some pages not shown"] }) : null, state.preLoadWarnings.map((warning) => (_jsx(Text, { color: theme.warning, children: staleWarningText(warning) }, warning))), showSearch ? (_jsxs(Text, { color: theme.muted, children: ["/ ", state.search.query, state.search.editing ? '█' : '', " (", searchMatchCount, " matches)"] })) : null, _jsxs(Box, { flexDirection: "column", children: [hiddenAbove > 0 ? _jsxs(Text, { color: theme.muted, children: ["\u2191 ", hiddenAbove, " more"] }) : null, rows.items.map((nodeId) => (_jsx(PickerRow, { state: state, nodeId: nodeId, width: width, theme: theme }, nodeId))), hiddenBelow > 0 ? _jsxs(Text, { color: theme.muted, children: ["\u2193 ", hiddenBelow, " more"] }) : null] }), state.pendingConfirm === 'mode-switch' ? (_jsxs(Text, { color: theme.warning, children: ["Save will switch crawl_mode all_accessible -> selected_roots and limit ingest to", ' ', selectedPageCountText(selectedCount), ". [y] confirm  [esc] back"] })) : null, state.transientHint ? _jsx(Text, { color: theme.warning, children: state.transientHint.text }) : null, _jsx(Text, { color: theme.muted, children: "space toggle \u00B7 enter expand \u00B7 / search \u00B7 a all \u00B7 n none \u00B7 s save & exit \u00B7 q quit" })] }));
+}
+function renderInk(tree, options) {
+    return renderInkRuntime(tree, {
+        stdin: options.stdin,
+        stdout: options.stdout,
+        stderr: options.stderr,
+        exitOnCtrlC: options.exitOnCtrlC,
+        patchConsole: options.patchConsole,
+        maxFps: options.maxFps,
+        alternateScreen: options.alternateScreen,
+    });
+}
+export async function renderNotionPickerTui(input, io, options = {}) {
+    let result = { kind: 'quit' };
+    let instance = null;
+    try {
+        instance = (options.renderInk ?? renderInk)(_jsx(NotionPickerApp, { ...input, terminalRows: io.stdout.rows ?? process.stdout.rows ?? 24, terminalWidth: io.stdout.columns ?? process.stdout.columns, onExit: (next) => {
+                result = next;
+                instance?.unmount();
+            } }), {
+            stdin: io.stdin,
+            stdout: io.stdout,
+            stderr: io.stderr,
+            exitOnCtrlC: false,
+            patchConsole: false,
+            maxFps: 30,
+            alternateScreen: true,
+        });
+        await instance.waitUntilExit();
+        instance.unmount();
+        return result;
+    }
+    catch (error) {
+        io.stderr.write(`Notion picker requires a TTY. Use --no-input --root-page-id <UUID> for scripted mode. ${sanitizeNotionPickerTuiError(error)}\n`);
+        return { kind: 'quit' };
+    }
+}

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

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