@kaelio/ktx 0.0.0 → 0.1.0-rc.1

package/dist/text-ingest.d.ts

@@ -0,0 +1,29 @@
+import { type MemoryAgentInput, type MemoryCaptureStatus } from '@ktx/context/memory';
+import { type KtxLocalProject } from '@ktx/context/project';
+import type { KtxCliIo } from './cli-runtime.js';
+export interface KtxTextIngestArgs {
+    projectDir: string;
+    texts: string[];
+    files: string[];
+    connectionId?: string;
+    userId: string;
+    json: boolean;
+    failFast: boolean;
+}
+export interface TextMemoryCapturePort {
+    capture(input: MemoryAgentInput): Promise<{
+        runId: string;
+    }>;
+    waitForRun(runId: string): Promise<void>;
+    status(runId: string): Promise<MemoryCaptureStatus | null>;
+}
+export interface KtxTextIngestDeps {
+    loadProject?: (options: {
+        projectDir: string;
+    }) => Promise<KtxLocalProject>;
+    createMemoryCapture?: (project: KtxLocalProject) => TextMemoryCapturePort;
+    readFile?: (path: string) => Promise<string>;
+    readStdin?: () => Promise<string>;
+    now?: () => number;
+}
+export declare function runKtxTextIngest(args: KtxTextIngestArgs, io: KtxCliIo, deps?: KtxTextIngestDeps): Promise<number>;

package/dist/text-ingest.js

@@ -0,0 +1,270 @@
+import { readFile as fsReadFile } from 'node:fs/promises';
+import { basename, resolve } from 'node:path';
+import { createLocalProjectMemoryCapture } from '@ktx/context/memory';
+import { loadKtxProject } from '@ktx/context/project';
+import { createRepainter, initViewState, renderContextBuildView } from './context-build-view.js';
+import { formatDuration } from './demo-metrics.js';
+const INLINE_TEXT_LABEL_MAX_LENGTH = 50;
+const ANSI_ESCAPE_PATTERN = /\x1B\[[0-?]*[ -/]*[@-~]/g;
+function defaultCreateMemoryCapture(project) {
+    return createLocalProjectMemoryCapture(project);
+}
+async function defaultReadStdin() {
+    const chunks = [];
+    process.stdin.setEncoding('utf-8');
+    for await (const chunk of process.stdin) {
+        chunks.push(String(chunk));
+    }
+    return chunks.join('');
+}
+async function defaultReadFile(path) {
+    return await fsReadFile(path, 'utf-8');
+}
+function emptyCaptured() {
+    return { wiki: [], sl: [], xrefs: [] };
+}
+function normalizedTextPreview(content) {
+    return content
+        .replace(ANSI_ESCAPE_PATTERN, '')
+        .replace(/[\u0000-\u001f\u007f-\u009f]/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+function truncateLabel(label, maxLength = INLINE_TEXT_LABEL_MAX_LENGTH) {
+    const chars = Array.from(label);
+    if (chars.length <= maxLength) {
+        return label;
+    }
+    return `${chars.slice(0, maxLength - 3).join('').trimEnd()}...`;
+}
+function quoteInlineTextLabel(label) {
+    return JSON.stringify(label);
+}
+function makeUniqueLabel(label, usedLabels) {
+    if (!usedLabels.has(label)) {
+        return label;
+    }
+    for (let index = 2;; index++) {
+        const suffix = ` (${index})`;
+        const candidate = `${truncateLabel(label, INLINE_TEXT_LABEL_MAX_LENGTH - suffix.length)}${suffix}`;
+        if (!usedLabels.has(candidate)) {
+            return candidate;
+        }
+    }
+}
+function textLabel(content, index, usedLabels) {
+    const preview = normalizedTextPreview(content);
+    const baseLabel = preview.length > 0 ? quoteInlineTextLabel(truncateLabel(preview)) : `text-${index + 1}`;
+    return makeUniqueLabel(baseLabel, usedLabels);
+}
+function artifactReference(label) {
+    return label.startsWith('"') ? label : `"${label}"`;
+}
+function stdinLabel(items) {
+    if (!items.some((item) => item.label === 'stdin')) {
+        return 'stdin';
+    }
+    return `stdin-${items.filter((item) => item.label.startsWith('stdin')).length + 1}`;
+}
+async function loadItems(args, deps) {
+    const items = [];
+    const usedTextLabels = new Set();
+    args.texts.forEach((content, index) => {
+        const label = textLabel(content, index, usedTextLabels);
+        usedTextLabels.add(label);
+        items.push({ label, content });
+    });
+    const readFile = deps.readFile ?? defaultReadFile;
+    const readStdin = deps.readStdin ?? defaultReadStdin;
+    for (const file of args.files) {
+        if (file === '-') {
+            items.push({ label: stdinLabel(items), content: await readStdin() });
+        }
+        else {
+            const path = resolve(file);
+            items.push({ label: basename(path), content: await readFile(path) });
+        }
+    }
+    return items;
+}
+function validateItems(items, io) {
+    if (items.length === 0) {
+        io.stderr.write('Provide at least one text item with --text, a file path, or - for stdin.\n');
+        return false;
+    }
+    for (const item of items) {
+        if (item.content.trim().length === 0) {
+            io.stderr.write(`Text item "${item.label}" is empty.\n`);
+            return false;
+        }
+    }
+    return true;
+}
+function makeTarget(label) {
+    return {
+        connectionId: label,
+        driver: 'text',
+        operation: 'source-ingest',
+        debugCommand: '',
+        steps: ['memory-update'],
+    };
+}
+function allTargets(state) {
+    return [...state.primarySources, ...state.contextSources];
+}
+function renderTextIngestView(state, styled) {
+    return renderContextBuildView(state, {
+        styled,
+        title: 'Ingesting text memory',
+        contextGroupLabel: 'Texts',
+        sourceIngestRunningText: 'capturing...',
+        completedItemName: { singular: 'text', plural: 'texts' },
+    });
+}
+function summarizeCaptured(captured) {
+    const parts = [
+        `wiki=${captured.wiki.length}`,
+        `sl=${captured.sl.length}`,
+        `xrefs=${captured.xrefs.length}`,
+    ];
+    return parts.join(', ');
+}
+function resultFromStatus(label, status) {
+    return {
+        label,
+        runId: status.runId,
+        status: status.status === 'done' ? 'done' : 'error',
+        captured: status.captured,
+        commitHash: status.commitHash,
+        error: status.error,
+    };
+}
+function errorResult(label, runId, error) {
+    return {
+        label,
+        runId,
+        status: 'error',
+        captured: emptyCaptured(),
+        commitHash: null,
+        error: error instanceof Error ? error.message : String(error),
+    };
+}
+function writeJsonResult(args, results, io) {
+    io.stdout.write(`${JSON.stringify({
+        status: results.some((result) => result.status === 'error') ? 'failed' : 'done',
+        projectDir: args.projectDir,
+        connectionId: args.connectionId ?? null,
+        results,
+    }, null, 2)}\n`);
+}
+function writePlainFailures(results, io) {
+    const failures = results.filter((result) => result.status === 'error');
+    if (failures.length === 0) {
+        return;
+    }
+    io.stdout.write('\nFailed text items:\n');
+    for (const result of failures) {
+        io.stdout.write(`  ${result.label}: ${result.error ?? 'failed'}\n`);
+    }
+}
+export async function runKtxTextIngest(args, io, deps = {}) {
+    const items = await loadItems(args, deps);
+    if (!validateItems(items, io)) {
+        return 1;
+    }
+    const project = await (deps.loadProject ?? loadKtxProject)({ projectDir: args.projectDir });
+    const memoryCapture = (deps.createMemoryCapture ?? defaultCreateMemoryCapture)(project);
+    const now = deps.now ?? (() => Date.now());
+    const batchId = now();
+    const state = initViewState(items.map((item) => makeTarget(item.label)));
+    const targets = allTargets(state);
+    const isTTY = io.stdout.isTTY === true && args.json !== true;
+    const repainter = isTTY ? createRepainter(io) : null;
+    const results = [];
+    state.startedAt = now();
+    const paint = () => repainter?.paint(renderTextIngestView(state, true));
+    paint();
+    let spinnerInterval = null;
+    if (repainter) {
+        spinnerInterval = setInterval(() => {
+            const current = now();
+            state.frame++;
+            state.totalElapsedMs = state.startedAt === null ? 0 : current - state.startedAt;
+            for (const target of targets) {
+                if (target.status === 'running' && target.startedAt !== null) {
+                    target.elapsedMs = current - target.startedAt;
+                }
+            }
+            paint();
+        }, 140);
+    }
+    try {
+        for (let index = 0; index < items.length; index++) {
+            const item = items[index];
+            const target = targets[index];
+            target.status = 'running';
+            target.startedAt = now();
+            target.detailLine = 'capturing...';
+            target.progressUpdatedAtMs = target.startedAt;
+            paint();
+            let runId = null;
+            let result;
+            try {
+                const captureInput = {
+                    userId: args.userId,
+                    chatId: `cli-text-ingest-${batchId}-${index + 1}`,
+                    userMessage: `Ingest external text artifact ${artifactReference(item.label)} into KTX memory.`,
+                    assistantMessage: item.content.trim(),
+                    ...(args.connectionId ? { connectionId: args.connectionId } : {}),
+                    sourceType: 'external_ingest',
+                };
+                const capture = await memoryCapture.capture(captureInput);
+                runId = capture.runId;
+                await memoryCapture.waitForRun(runId);
+                const status = await memoryCapture.status(runId);
+                if (!status) {
+                    throw new Error(`Memory capture run "${runId}" was not found.`);
+                }
+                result = resultFromStatus(item.label, status);
+            }
+            catch (error) {
+                result = errorResult(item.label, runId, error);
+            }
+            results.push(result);
+            target.elapsedMs = now() - (target.startedAt ?? now());
+            target.detailLine = null;
+            target.status = result.status === 'done' ? 'done' : 'failed';
+            target.summaryText = result.status === 'done' ? summarizeCaptured(result.captured) : null;
+            target.failureText = result.status === 'error' ? result.error : null;
+            paint();
+            if (result.status === 'error' && args.failFast) {
+                break;
+            }
+        }
+    }
+    finally {
+        if (spinnerInterval) {
+            clearInterval(spinnerInterval);
+        }
+    }
+    if (state.startedAt !== null) {
+        state.totalElapsedMs = now() - state.startedAt;
+    }
+    if (args.json) {
+        writeJsonResult(args, results, io);
+    }
+    else if (repainter) {
+        repainter.paint(renderTextIngestView(state, true));
+        writePlainFailures(results, io);
+    }
+    else {
+        io.stdout.write(renderTextIngestView(state, false));
+        writePlainFailures(results, io);
+    }
+    if (!args.json && results.length > 0) {
+        const duration = state.totalElapsedMs > 0 ? ` in ${formatDuration(state.totalElapsedMs)}` : '';
+        const outcome = results.some((result) => result.status === 'error') ? 'finished with failures' : 'finished';
+        io.stdout.write(`Text memory ingest ${outcome}${duration}.\n`);
+    }
+    return results.some((result) => result.status === 'error') ? 1 : 0;
+}

package/dist/text-ingest.test.d.ts

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

package/dist/text-ingest.test.js

@@ -0,0 +1,247 @@
+import { describe, expect, it, vi } from 'vitest';
+import { runKtxTextIngest } from './text-ingest.js';
+function makeIo(options = {}) {
+    let stdout = '';
+    let stderr = '';
+    return {
+        io: {
+            stdout: {
+                isTTY: options.isTTY,
+                write: (chunk) => {
+                    stdout += chunk;
+                },
+            },
+            stderr: {
+                write: (chunk) => {
+                    stderr += chunk;
+                },
+            },
+        },
+        stdout: () => stdout,
+        stderr: () => stderr,
+    };
+}
+function fakeCapture(options = {}) {
+    let next = 1;
+    return {
+        capture: vi.fn(async () => {
+            const runId = `run-${next++}`;
+            options.events?.push(`capture:${runId}`);
+            return { runId };
+        }),
+        waitForRun: vi.fn(async (runId) => {
+            options.events?.push(`wait:${runId}`);
+        }),
+        status: vi.fn(async (runId) => {
+            options.events?.push(`status:${runId}`);
+            if (options.missingStatusRunIds?.has(runId)) {
+                return null;
+            }
+            if (options.failRunIds?.has(runId)) {
+                return {
+                    runId,
+                    status: 'error',
+                    stage: 'capturing',
+                    done: true,
+                    captured: { wiki: [], sl: [], xrefs: [] },
+                    error: `${runId} failed`,
+                    commitHash: null,
+                    skillsLoaded: [],
+                    signalDetected: false,
+                };
+            }
+            return {
+                runId,
+                status: 'done',
+                stage: 'capturing',
+                done: true,
+                captured: { wiki: [`wiki-${runId}`], sl: [`sl-${runId}`], xrefs: [] },
+                error: null,
+                commitHash: `commit-${runId}`,
+                skillsLoaded: ['wiki_capture', 'sl'],
+                signalDetected: true,
+            };
+        }),
+    };
+}
+function fakeProject(projectDir = '/tmp/project') {
+    return { projectDir };
+}
+describe('runKtxTextIngest', () => {
+    it('captures repeated inline text sequentially with generated internal chat ids', async () => {
+        const io = makeIo();
+        const events = [];
+        const capture = fakeCapture({ events });
+        const createMemoryCapture = vi.fn(() => capture);
+        await expect(runKtxTextIngest({
+            projectDir: '/tmp/project',
+            texts: ['Revenue means gross receipts.', 'Orders are completed purchases.'],
+            files: [],
+            userId: 'local-cli',
+            json: true,
+            failFast: false,
+        }, io.io, {
+            loadProject: vi.fn(async () => fakeProject()),
+            createMemoryCapture,
+            now: () => 1_700_000_000_000,
+        })).resolves.toBe(0);
+        expect(createMemoryCapture).toHaveBeenCalledWith({ projectDir: '/tmp/project' });
+        expect(capture.capture).toHaveBeenNthCalledWith(1, expect.objectContaining({
+            userId: 'local-cli',
+            chatId: 'cli-text-ingest-1700000000000-1',
+            userMessage: 'Ingest external text artifact "Revenue means gross receipts." into KTX memory.',
+            assistantMessage: 'Revenue means gross receipts.',
+            sourceType: 'external_ingest',
+        }));
+        expect(capture.capture).toHaveBeenNthCalledWith(2, expect.objectContaining({
+            chatId: 'cli-text-ingest-1700000000000-2',
+            userMessage: 'Ingest external text artifact "Orders are completed purchases." into KTX memory.',
+            assistantMessage: 'Orders are completed purchases.',
+        }));
+        expect(capture.capture).not.toHaveBeenCalledWith(expect.objectContaining({ connectionId: expect.anything() }));
+        expect(events).toEqual(['capture:run-1', 'wait:run-1', 'status:run-1', 'capture:run-2', 'wait:run-2', 'status:run-2']);
+        expect(JSON.parse(io.stdout())).toMatchObject({
+            status: 'done',
+            results: [
+                {
+                    label: '"Revenue means gross receipts."',
+                    runId: 'run-1',
+                    status: 'done',
+                    captured: { wiki: ['wiki-run-1'], sl: ['sl-run-1'] },
+                },
+                {
+                    label: '"Orders are completed purchases."',
+                    runId: 'run-2',
+                    status: 'done',
+                    captured: { wiki: ['wiki-run-2'], sl: ['sl-run-2'] },
+                },
+            ],
+        });
+    });
+    it('loads files and stdin as batch items and passes a global connection id', async () => {
+        const io = makeIo();
+        const capture = fakeCapture();
+        await expect(runKtxTextIngest({
+            projectDir: '/tmp/project',
+            texts: [],
+            files: ['/tmp/docs/revenue.md', '-'],
+            connectionId: 'warehouse',
+            userId: 'agent',
+            json: false,
+            failFast: false,
+        }, io.io, {
+            loadProject: vi.fn(async () => fakeProject()),
+            createMemoryCapture: vi.fn(() => capture),
+            readFile: vi.fn(async (path) => `file:${path}`),
+            readStdin: vi.fn(async () => 'stdin content'),
+            now: () => 10,
+        })).resolves.toBe(0);
+        expect(capture.capture).toHaveBeenNthCalledWith(1, expect.objectContaining({
+            connectionId: 'warehouse',
+            userId: 'agent',
+            userMessage: 'Ingest external text artifact "revenue.md" into KTX memory.',
+            assistantMessage: 'file:/tmp/docs/revenue.md',
+        }));
+        expect(capture.capture).toHaveBeenNthCalledWith(2, expect.objectContaining({
+            connectionId: 'warehouse',
+            userMessage: 'Ingest external text artifact "stdin" into KTX memory.',
+            assistantMessage: 'stdin content',
+        }));
+        expect(io.stdout()).toContain('Ingesting text memory');
+        expect(io.stdout()).toContain('Texts:');
+        expect(io.stdout()).toContain('revenue.md');
+        expect(io.stdout()).toContain('stdin');
+    });
+    it('uses bounded inline text previews as labels in plain output and capture metadata', async () => {
+        const io = makeIo();
+        const capture = fakeCapture();
+        const longText = `This inline note is intentionally long ${'x'.repeat(120)}`;
+        await expect(runKtxTextIngest({
+            projectDir: '/tmp/project',
+            texts: ['remember to call me Andrey', '  first line\n\tsecond line  ', longText],
+            files: [],
+            userId: 'local-cli',
+            json: false,
+            failFast: false,
+        }, io.io, {
+            loadProject: vi.fn(async () => fakeProject()),
+            createMemoryCapture: vi.fn(() => capture),
+            now: () => 10,
+        })).resolves.toBe(0);
+        const output = io.stdout();
+        expect(output).toContain('"remember to call me Andrey"');
+        expect(output).toContain('"first line second line"');
+        expect(output).toContain('"This inline note is intentionally long xxxxxxxx..."');
+        expect(output).not.toContain('text-1');
+        expect(output).not.toContain(longText);
+        expect(capture.capture).toHaveBeenNthCalledWith(1, expect.objectContaining({
+            userMessage: 'Ingest external text artifact "remember to call me Andrey" into KTX memory.',
+        }));
+        expect(capture.capture).toHaveBeenNthCalledWith(2, expect.objectContaining({
+            userMessage: 'Ingest external text artifact "first line second line" into KTX memory.',
+        }));
+        expect(capture.capture).toHaveBeenNthCalledWith(3, expect.objectContaining({
+            userMessage: 'Ingest external text artifact "This inline note is intentionally long xxxxxxxx..." into KTX memory.',
+        }));
+    });
+    it('continues after an item failure by default and stops when failFast is set', async () => {
+        const continueIo = makeIo();
+        const continueCapture = fakeCapture({ failRunIds: new Set(['run-1']) });
+        await expect(runKtxTextIngest({
+            projectDir: '/tmp/project',
+            texts: ['bad', 'good'],
+            files: [],
+            userId: 'local-cli',
+            json: true,
+            failFast: false,
+        }, continueIo.io, {
+            loadProject: vi.fn(async () => fakeProject()),
+            createMemoryCapture: vi.fn(() => continueCapture),
+        })).resolves.toBe(1);
+        expect(continueCapture.capture).toHaveBeenCalledTimes(2);
+        expect(JSON.parse(continueIo.stdout())).toMatchObject({
+            status: 'failed',
+            results: [
+                { label: '"bad"', status: 'error', error: 'run-1 failed' },
+                { label: '"good"', status: 'done' },
+            ],
+        });
+        const failFastIo = makeIo();
+        const failFastCapture = fakeCapture({ failRunIds: new Set(['run-1']) });
+        await expect(runKtxTextIngest({
+            projectDir: '/tmp/project',
+            texts: ['bad', 'skipped'],
+            files: [],
+            userId: 'local-cli',
+            json: true,
+            failFast: true,
+        }, failFastIo.io, {
+            loadProject: vi.fn(async () => fakeProject()),
+            createMemoryCapture: vi.fn(() => failFastCapture),
+        })).resolves.toBe(1);
+        expect(failFastCapture.capture).toHaveBeenCalledTimes(1);
+        expect(JSON.parse(failFastIo.stdout()).results).toHaveLength(1);
+    });
+    it('rejects empty batches and empty text items', async () => {
+        const noInputIo = makeIo();
+        await expect(runKtxTextIngest({
+            projectDir: '/tmp/project',
+            texts: [],
+            files: [],
+            userId: 'local-cli',
+            json: false,
+            failFast: false,
+        }, noInputIo.io, { loadProject: vi.fn(), createMemoryCapture: vi.fn() })).resolves.toBe(1);
+        expect(noInputIo.stderr()).toContain('Provide at least one text item');
+        const emptyIo = makeIo();
+        await expect(runKtxTextIngest({
+            projectDir: '/tmp/project',
+            texts: ['   '],
+            files: [],
+            userId: 'local-cli',
+            json: false,
+            failFast: false,
+        }, emptyIo.io, { loadProject: vi.fn(), createMemoryCapture: vi.fn() })).resolves.toBe(1);
+        expect(emptyIo.stderr()).toContain('Text item "text-1" is empty');
+    });
+});

package/dist/tree-picker-state.d.ts

@@ -0,0 +1,73 @@
+export interface TreePickerNodeInput {
+    id: string;
+    title?: string | null;
+    archived?: boolean;
+    parentId?: string | null;
+}
+export interface TreePickerNode {
+    id: string;
+    title: string;
+    archived: boolean;
+    parentId: string | null;
+    depth: number;
+    childIds: string[];
+    path: string;
+}
+type PendingConfirmKind = 'save-confirm' | 'skip-empty';
+export type SkipEmptyAction = 'quit' | 'save-empty';
+export interface PickerState {
+    tree: TreePickerNode[];
+    byId: Map<string, TreePickerNode>;
+    expanded: Set<string>;
+    checked: Set<string>;
+    cursorId: string;
+    search: {
+        editing: boolean;
+        query: string;
+    };
+    pendingConfirm: PendingConfirmKind | null;
+    preLoadWarnings: string[];
+    transientHint: {
+        text: string;
+        expiresAt: number;
+    } | null;
+    requireConfirmOnSave: boolean;
+    skipEmptyAction: SkipEmptyAction;
+}
+export type PickerCommand = 'cursor-up' | 'cursor-down' | 'cursor-left' | 'cursor-right' | 'expand' | 'collapse' | 'expand-all' | 'collapse-all' | 'toggle-check' | 'select-all-visible' | 'toggle-select-all-visible' | 'select-none' | 'clear-transient-hint' | 'search-start' | 'search-cancel' | 'search-submit' | 'search-backspace' | {
+    type: 'search-input';
+    value: string;
+} | 'save-request' | 'save-confirm' | 'save-cancel' | 'quit';
+type PickerEffect = null | 'save' | 'quit-without-save';
+export declare function clearExpiredTransientHint(state: PickerState, now?: number): PickerState;
+export declare function buildPickerTree(inputs: TreePickerNodeInput[]): TreePickerNode[];
+export declare function isAncestorChecked(nodeId: string, checked: Set<string>, byId: Map<string, TreePickerNode>): boolean;
+export declare function hasPartialChildren(nodeId: string, checked: Set<string>, byId: Map<string, TreePickerNode>): boolean;
+export declare function canToggle(nodeId: string, state: PickerState): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function toggleChecked(state: PickerState, nodeId: string, now?: number): PickerState;
+export declare function flattenSelection(checked: Set<string>, byId: Map<string, TreePickerNode>): string[];
+export declare function filterTree(state: PickerState): {
+    visibleIds: Set<string>;
+    autoExpand: Set<string>;
+};
+export declare function visibleNodeIds(state: PickerState): string[];
+export declare function selectAllVisible(state: PickerState): PickerState;
+export declare function selectNone(state: PickerState): PickerState;
+export declare function moveCursor(state: PickerState, dir: 'up' | 'down' | 'left' | 'right'): PickerState;
+export declare function buildInitialState(args: {
+    tree: TreePickerNode[];
+    existingSelectedIds: string[];
+    requireConfirmOnSave?: boolean;
+    skipEmptyAction?: SkipEmptyAction;
+    staleWarning?: (staleCount: number) => string;
+}): PickerState;
+export declare function reducer(state: PickerState, cmd: PickerCommand, now?: number): {
+    next: PickerState;
+    effect: PickerEffect;
+};
+export {};