@kaelio/ktx 0.0.0 → 0.1.0-rc.1

package/dist/memory-flow-hud.js

@@ -0,0 +1,219 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import { buildDemoMetrics, formatCost, formatDuration } from './demo-metrics.js';
+import { formatNextStepLines } from './next-steps.js';
+import { profileMark } from './startup-profile.js';
+profileMark('module:memory-flow-hud');
+const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+function spinner(frame) {
+    return SPINNER_FRAMES[frame % SPINNER_FRAMES.length] ?? '⠋';
+}
+function counterValue(target, frame, framesToFill = 12) {
+    if (target <= 0 || frame <= 0)
+        return 0;
+    if (frame >= framesToFill)
+        return target;
+    return Math.round((frame / framesToFill) * target);
+}
+function hasWorkStarted(input) {
+    return input.events.some((e) => e.type === 'work_unit_started');
+}
+function isPrepopulatedDemoReplay(input) {
+    return input.metadata?.origin === 'packaged' || input.metadata?.timing === 'prebuilt';
+}
+function progressBarOverall(finishedCount, activeCount, totalCount, width, frame) {
+    if (totalCount === 0)
+        return '░'.repeat(width);
+    const finishedWidth = Math.round((finishedCount / totalCount) * width);
+    const activeWidth = Math.max(activeCount > 0 ? 1 : 0, Math.round((activeCount / totalCount) * width));
+    const queuedWidth = Math.max(0, width - finishedWidth - activeWidth);
+    const finished = '█'.repeat(finishedWidth);
+    const pulse = ['░', '▒', '▓', '█', '▓', '▒'];
+    const pulseLen = pulse.length;
+    const offset = (frame * 2) % (activeWidth + pulseLen);
+    const activeChars = [];
+    for (let i = 0; i < activeWidth; i += 1) {
+        const p = i - offset + pulseLen;
+        activeChars.push(p >= 0 && p < pulseLen ? (pulse[p] ?? '▒') : '▒');
+    }
+    return finished + activeChars.join('') + '░'.repeat(queuedWidth);
+}
+function topicName(key) {
+    return (key.split('/').pop()?.replace(/\.md$/, '') ?? key).replace(/[_-]/g, ' ');
+}
+function tableName(key) {
+    return key.split('.').pop()?.replace(/[_-]/g, ' ') ?? key;
+}
+function humanizeInsight(key, target, summary) {
+    if (summary)
+        return summary;
+    const name = target === 'sl' ? tableName(key) : topicName(key);
+    return target === 'sl' ? `Query definition: ${name}` : `Wiki page: ${name}`;
+}
+const INTERNAL_DEMO_CONNECTION_ID = 'orbit_demo';
+const PUBLIC_DEMO_SOURCE_LABEL = 'Orbit Demo';
+const ADAPTER_LABELS = {
+    'live-database': { type: 'Database', plural: 'tables', verb: 'Reading', description: 'Reading table schemas, understanding relationships, creating query definitions' },
+    metricflow: { type: 'dbt project', plural: 'models', verb: 'Parsing', description: 'Parsing dbt models, extracting metric definitions, mapping dependencies' },
+    looker: { type: 'Looker', plural: 'explores', verb: 'Analyzing', description: 'Analyzing explores, extracting dimensions and measures, mapping joins' },
+    lookml: { type: 'LookML', plural: 'views', verb: 'Parsing', description: 'Parsing LookML views, extracting field definitions, mapping relationships' },
+    metabase: { type: 'Metabase', plural: 'questions', verb: 'Analyzing', description: 'Analyzing saved questions, extracting query patterns, understanding dashboards' },
+    notion: { type: 'Notion', plural: 'pages', verb: 'Reading', description: 'Reading pages, extracting structure, understanding your documentation' },
+    'historic-sql': { type: 'SQL history', plural: 'queries', verb: 'Analyzing', description: 'Analyzing query patterns, identifying common joins, learning access patterns' },
+    'dbt-descriptions': { type: 'dbt schema', plural: 'models', verb: 'Parsing', description: 'Parsing schema definitions, extracting descriptions, mapping lineage' },
+    dbt_descriptions: { type: 'dbt', plural: 'models', verb: 'Parsing', description: 'Parsing schema definitions, extracting descriptions, mapping lineage' },
+};
+function sourceDescription(input) {
+    const adapter = input.adapter ?? 'source';
+    const conn = input.connectionId ?? '';
+    const sourceEvents = input.events.filter((e) => e.type === 'source_acquired');
+    const isDemoSource = conn === INTERNAL_DEMO_CONNECTION_ID || isPrepopulatedDemoReplay(input);
+    if (isDemoSource && sourceEvents.length <= 1) {
+        const count = sourceEvents[0] ? String(sourceEvents[0].fileCount) : '?';
+        return {
+            type: PUBLIC_DEMO_SOURCE_LABEL,
+            name: '',
+            sourceCount: count,
+            itemNounPlural: 'sources',
+            readingVerb: 'Ingesting',
+            ingestDescription: 'Ingesting warehouse, dbt, BI, and docs into a unified context layer',
+        };
+    }
+    if (sourceEvents.length > 1) {
+        const totalFiles = sourceEvents.reduce((sum, s) => sum + s.fileCount, 0);
+        const labels = [...new Set(sourceEvents.map((s) => ADAPTER_LABELS[s.adapter]?.type ?? s.adapter))];
+        return {
+            type: labels.join(' + '),
+            name: conn,
+            sourceCount: String(totalFiles),
+            itemNounPlural: 'sources',
+            readingVerb: 'Ingesting',
+            ingestDescription: 'Ingesting warehouse, dbt, BI, and docs into a unified context layer',
+        };
+    }
+    const count = sourceEvents[0] ? String(sourceEvents[0].fileCount) : '?';
+    const info = ADAPTER_LABELS[adapter] ?? { type: adapter, plural: 'sources', verb: 'Reading', description: 'Reading sources, understanding structure, creating definitions' };
+    return { type: info.type, name: conn, sourceCount: count, itemNounPlural: info.plural, readingVerb: info.verb, ingestDescription: info.description };
+}
+function activeWorkUnits(input) {
+    const finishedKeys = new Set();
+    const unitMap = new Map();
+    for (const e of input.events) {
+        if (e.type === 'work_unit_started') {
+            unitMap.set(e.unitKey, { stepIndex: 0, stepBudget: e.stepBudget });
+        }
+        if (e.type === 'work_unit_step') {
+            const existing = unitMap.get(e.unitKey);
+            if (existing) {
+                existing.stepIndex = e.stepIndex;
+                existing.stepBudget = e.stepBudget;
+            }
+        }
+        if (e.type === 'work_unit_finished')
+            finishedKeys.add(e.unitKey);
+    }
+    const result = [];
+    for (const [unitKey, data] of unitMap) {
+        if (!finishedKeys.has(unitKey))
+            result.push({ unitKey, ...data });
+    }
+    return result;
+}
+function queuedWorkUnits(input) {
+    const startedKeys = new Set();
+    for (const e of input.events) {
+        if (e.type === 'work_unit_started')
+            startedKeys.add(e.unitKey);
+    }
+    return input.plannedWorkUnits.filter((u) => !startedKeys.has(u.unitKey)).map((u) => u.unitKey);
+}
+function buildInsights(input) {
+    return input.events
+        .filter((e) => e.type === 'candidate_action')
+        .map((e) => {
+        const ca = e;
+        const detail = input.details.actions.find((a) => a.key === ca.key && a.unitKey === ca.unitKey);
+        return {
+            icon: ca.target === 'sl' ? '📊' : '📝',
+            text: humanizeInsight(ca.key, ca.target, detail?.summary),
+            unitKey: ca.unitKey,
+            hasSummary: !!detail?.summary,
+        };
+    });
+}
+function finishedUnits(input) {
+    const units = [];
+    for (const e of input.events) {
+        if (e.type === 'work_unit_finished' && e.status === 'success') {
+            const count = input.events.filter((a) => a.type === 'candidate_action' && a.unitKey === e.unitKey).length;
+            units.push({ unitKey: e.unitKey, artifactCount: count });
+        }
+    }
+    return units;
+}
+const KTX_LOGO_SMALL = [
+    '██╗  ██╗████████╗██╗  ██╗',
+    '██║ ██╔╝╚══██╔══╝╚██╗██╔╝',
+    '█████╔╝    ██║    ╚███╔╝ ',
+    '██╔═██╗    ██║    ██╔██╗ ',
+    '██║  ██╗   ██║   ██╔╝ ██╗',
+    '╚═╝  ╚═╝   ╚═╝   ╚═╝  ╚═╝',
+];
+export function Logo(props) {
+    const color = props.done ? props.theme.complete : props.theme.active;
+    return (_jsx(Box, { flexDirection: "column", marginBottom: 1, paddingLeft: 2, children: KTX_LOGO_SMALL.map((line, idx) => (_jsx(Text, { color: color, children: line }, idx))) }));
+}
+export function Hud(props) {
+    const src = sourceDescription(props.input);
+    const metrics = buildDemoMetrics(props.input, props.now ? { now: props.now } : {});
+    const workStarted = hasWorkStarted(props.input);
+    const sourceEvents = props.input.events.filter((e) => e.type === 'source_acquired');
+    const col1Content = sourceEvents.length > 1 || !src.name ? src.type : `${src.type} (${src.name})`;
+    const innerWidth = Math.max(60, props.width - 6);
+    const hLine = '─'.repeat(innerWidth);
+    const elapsed = formatDuration(metrics.elapsedMs);
+    let eta = '';
+    if (metrics.status === 'running' && metrics.etaMs !== null)
+        eta = `~${formatDuration(metrics.etaMs)} left`;
+    else if (metrics.status !== 'running')
+        eta = 'done';
+    const cost = workStarted ? formatCost(metrics.estimatedCostUsd) : '';
+    const statsParts = [`⏱ ${elapsed}`, eta, cost].filter(Boolean).join('    ');
+    const prepopulatedCostDisclaimer = cost && isPrepopulatedDemoReplay(props.input)
+        ? 'Pre-run demo: $ shown is illustrative; no money is being spent now.'
+        : null;
+    return (_jsxs(Box, { flexDirection: "column", marginBottom: 1, children: [_jsxs(Text, { color: props.theme.border, children: [" \u256D", hLine, "\u256E"] }), _jsxs(Text, { children: [_jsx(Text, { color: props.theme.border, children: " \u2502 " }), _jsx(Text, { color: props.theme.text, children: col1Content }), _jsxs(Text, { color: props.theme.muted, children: [" \u2014 ", src.sourceCount, " ", src.itemNounPlural] })] }), _jsxs(Text, { children: [_jsx(Text, { color: props.theme.border, children: " \u2502 " }), _jsx(Text, { color: "#b8860b", children: statsParts })] }), prepopulatedCostDisclaimer && (_jsxs(Text, { children: [_jsx(Text, { color: props.theme.border, children: " \u2502 " }), _jsx(Text, { color: props.theme.muted, children: prepopulatedCostDisclaimer })] })), _jsxs(Text, { color: props.theme.border, children: [" \u2570", hLine, "\u256F"] })] }));
+}
+export function ActivityFeed(props) {
+    const actives = activeWorkUnits(props.input);
+    const queued = queuedWorkUnits(props.input);
+    const finished = finishedUnits(props.input);
+    const insights = buildInsights(props.input);
+    const src = sourceDescription(props.input);
+    const isDone = props.input.status === 'done';
+    const isError = props.input.status === 'error';
+    const diffEvent = props.input.events.find((e) => e.type === 'diff_computed');
+    const planEvent = props.input.events.find((e) => e.type === 'chunks_planned');
+    const reconEvent = props.input.events.find((e) => e.type === 'reconciliation_finished');
+    const savedEvent = props.input.events.find((e) => e.type === 'saved');
+    const workStarted = hasWorkStarted(props.input);
+    const totalChunks = planEvent?.chunkCount ?? 0;
+    const finishedAreas = totalChunks > 0 ? Math.min(finished.length, totalChunks) : finished.length;
+    const allWorkDone = workStarted && actives.length === 0 && queued.length === 0;
+    const isReconciling = allWorkDone && !reconEvent && !isDone && !isError;
+    const isSaving = reconEvent && !savedEvent && !isDone && !isError;
+    const isIncremental = diffEvent && (diffEvent.modified > 0 || diffEvent.deleted > 0 || diffEvent.unchanged > 0);
+    const barWidth = Math.min(40, props.width - 20);
+    return (_jsxs(Box, { flexDirection: "column", paddingLeft: 2, children: [!diffEvent && !workStarted && (_jsxs(Text, { color: props.theme.active, children: [spinner(props.frame), " Connecting to ", src.type.toLowerCase(), "..."] })), diffEvent && (_jsxs(Text, { color: props.theme.complete, children: ["\u2713 Connected \u2014 found ", src.sourceCount, " ", src.itemNounPlural, " to ingest"] })), diffEvent && isIncremental && (_jsx(Text, { color: props.theme.complete, children: "\u2713 Compared with last sync \u2014 only re-analyzing what changed" })), diffEvent && !planEvent && !workStarted && (_jsxs(Text, { color: props.theme.active, children: [spinner(props.frame), " Grouping related ", src.itemNounPlural, " together for deeper analysis..."] })), planEvent && (_jsxs(Text, { color: props.theme.complete, children: ["\u2713 Grouped into ", planEvent.chunkCount, " business area", planEvent.chunkCount === 1 ? '' : 's'] })), workStarted && !allWorkDone && (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsxs(Text, { color: props.theme.active, children: [spinner(props.frame), " Ingesting \u2014 ", finishedAreas, "/", totalChunks || '?', " business area", totalChunks === 1 ? '' : 's', " done"] }), _jsxs(Text, { color: props.theme.muted, children: ['  ', src.ingestDescription] }), totalChunks > 0 && (_jsxs(Text, { color: props.theme.active, children: ['  ', progressBarOverall(finishedAreas, actives.length, totalChunks, barWidth, props.frame)] }))] })), insights.length > 0 && (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsx(Text, { color: props.theme.text, children: "  Created so far:" }), insights.map((insight, idx) => (_jsxs(Text, { color: props.theme.muted, children: ['    ', insight.icon, " ", insight.text] }, `result-${idx}`)))] })), isReconciling && (_jsxs(Text, { color: props.theme.active, children: [spinner(props.frame), " Deduplicating \u2014 removing overlaps between business areas and checking for conflicts..."] })), reconEvent && (_jsxs(Text, { color: props.theme.complete, children: ["\u2713 Deduplicated", reconEvent.conflictCount > 0
+                        ? ` — ${reconEvent.conflictCount} conflict${reconEvent.conflictCount === 1 ? '' : 's'} resolved`
+                        : ' — no conflicts'] })), isSaving && (_jsxs(Text, { color: props.theme.active, children: [spinner(props.frame), " Saving to context layer..."] })), savedEvent && (_jsx(Text, { color: props.theme.complete, children: "\u2713 Saved \u2014 your agents can now use the KTX context layer" })), props.showCompletion && (isDone || isError) && (_jsx(CompletionSummary, { input: props.input, theme: props.theme, frame: props.completionFrame, holdComplete: props.holdComplete }))] }));
+}
+function CompletionSummary(props) {
+    const saved = [...props.input.events].reverse().find((e) => e.type === 'saved');
+    const wikiCount = saved?.wikiCount ?? 0;
+    const slCount = saved?.slCount ?? 0;
+    const isError = props.input.status === 'error';
+    const sl = counterValue(slCount, props.frame);
+    const wiki = counterValue(wikiCount, props.frame);
+    return (_jsx(Box, { flexDirection: "column", marginTop: 1, children: isError ? (_jsx(Text, { bold: true, color: props.theme.failed, children: "\u2717 Something went wrong \u2014 review the errors above." })) : (_jsxs(_Fragment, { children: [_jsx(Text, { color: props.theme.border, children: '─'.repeat(60) }), _jsx(Text, { bold: true, color: props.theme.complete, children: "\u2605 KTX finished ingesting your data" }), (sl > 0 || wiki > 0) && (_jsxs(_Fragment, { children: [_jsx(Text, {}), _jsx(Text, { color: props.theme.text, children: "KTX created:" }), sl > 0 && (_jsxs(Text, { color: props.theme.active, children: ['  ', "\uD83D\uDCCA ", sl, " query definition", sl === 1 ? '' : 's', " \u2014 so agents can write accurate SQL for your data"] })), wiki > 0 && (_jsxs(Text, { color: props.theme.complete, children: ['  ', "\uD83D\uDCDD ", wiki, " wiki page", wiki === 1 ? '' : 's', " \u2014 so agents understand your business context"] }))] })), _jsx(Text, {}), _jsx(Text, { color: props.theme.text, children: "What to do next:" }), formatNextStepLines().map((line) => (_jsx(Text, { color: props.theme.active, children: line }, line))), props.holdComplete && (_jsxs(_Fragment, { children: [_jsx(Text, {}), _jsx(Text, { color: props.theme.muted, children: "Press q to exit" })] }))] })) }));
+}

package/dist/memory-flow-interactive.d.ts

@@ -0,0 +1,29 @@
+import { type MemoryFlowInteractionCommand, type MemoryFlowInteractionState, type MemoryFlowReplayInput } from '@ktx/context/ingest';
+interface KtxMemoryFlowKey {
+    name?: string;
+    ctrl?: boolean;
+}
+export interface KtxMemoryFlowStdin {
+    isTTY?: boolean;
+    isRaw?: boolean;
+    setRawMode?(value: boolean): void;
+    resume?(): void;
+    pause?(): void;
+    on(event: 'keypress', listener: (chunk: string, key: KtxMemoryFlowKey) => void): this;
+    off?(event: 'keypress', listener: (chunk: string, key: KtxMemoryFlowKey) => void): this;
+    removeListener?(event: 'keypress', listener: (chunk: string, key: KtxMemoryFlowKey) => void): this;
+}
+interface KtxMemoryFlowInteractiveIo {
+    stdin?: KtxMemoryFlowStdin;
+    stdout: {
+        isTTY?: boolean;
+        columns?: number;
+        write(chunk: string): void;
+    };
+}
+interface RenderMemoryFlowInteractiveOptions {
+    prepareKeypressEvents?(stdin: KtxMemoryFlowStdin): void;
+}
+export declare function memoryFlowCommandForKey(chunk: string, search: MemoryFlowInteractionState['search'], key: KtxMemoryFlowKey): MemoryFlowInteractionCommand | null;
+export declare function renderMemoryFlowInteractively(input: MemoryFlowReplayInput, io: KtxMemoryFlowInteractiveIo, options?: RenderMemoryFlowInteractiveOptions): Promise<void>;
+export {};

package/dist/memory-flow-interactive.js

@@ -0,0 +1,94 @@
+import { emitKeypressEvents } from 'node:readline';
+import { buildMemoryFlowViewModel, createInitialMemoryFlowInteractionState, reduceMemoryFlowInteractionState, renderMemoryFlowInteractive, } from '@ktx/context/ingest';
+function defaultPrepareKeypressEvents(stdin) {
+    emitKeypressEvents(stdin);
+}
+export function memoryFlowCommandForKey(chunk, search, key) {
+    if (search.editing) {
+        if (key.name === 'escape')
+            return 'search-clear';
+        if (key.name === 'return' || key.name === 'enter')
+            return 'search-submit';
+        if (key.name === 'backspace')
+            return 'search-backspace';
+        if (chunk.length === 1 && chunk >= ' ' && chunk !== '\u007f') {
+            return { type: 'search-input', value: chunk };
+        }
+        return null;
+    }
+    if (key.ctrl === true && key.name === 'c') {
+        return 'quit';
+    }
+    if (key.name === '/')
+        return 'search-start';
+    if (key.name === 'left')
+        return 'left';
+    if (key.name === 'right')
+        return 'right';
+    if (key.name === 'up')
+        return 'up';
+    if (key.name === 'down')
+        return 'down';
+    if (key.name === 'return' || key.name === 'enter')
+        return 'enter';
+    if (key.name === 'tab')
+        return 'tab';
+    if (key.name === 'f')
+        return 'filter';
+    if (key.name === 'p')
+        return 'provenance';
+    if (key.name === 't')
+        return 'transcript';
+    if (key.name === 'q' || key.name === 'escape')
+        return 'quit';
+    return null;
+}
+function removeKeypressListener(stdin, handler) {
+    if (stdin.off) {
+        stdin.off('keypress', handler);
+        return;
+    }
+    stdin.removeListener?.('keypress', handler);
+}
+function repaint(input, state, io) {
+    const view = buildMemoryFlowViewModel(input);
+    io.stdout.write('\u001b[2J\u001b[H');
+    io.stdout.write(renderMemoryFlowInteractive(view, state, { terminalWidth: io.stdout.columns }));
+}
+export async function renderMemoryFlowInteractively(input, io, options = {}) {
+    const stdin = io.stdin;
+    if (stdin?.isTTY !== true) {
+        const view = buildMemoryFlowViewModel(input);
+        io.stdout.write(renderMemoryFlowInteractive(view, createInitialMemoryFlowInteractionState(view), {
+            terminalWidth: io.stdout.columns,
+        }));
+        return;
+    }
+    const view = buildMemoryFlowViewModel(input);
+    let state = createInitialMemoryFlowInteractionState(view);
+    const previousRawMode = stdin.isRaw === true;
+    return new Promise((resolve) => {
+        const cleanup = () => {
+            removeKeypressListener(stdin, handleKeypress);
+            stdin.setRawMode?.(previousRawMode);
+            stdin.pause?.();
+        };
+        const handleKeypress = (_chunk, key) => {
+            const command = memoryFlowCommandForKey(_chunk, state.search, key);
+            if (!command) {
+                return;
+            }
+            state = reduceMemoryFlowInteractionState(state, command, view);
+            repaint(input, state, io);
+            if (state.shouldQuit) {
+                cleanup();
+                resolve();
+            }
+        };
+        (options.prepareKeypressEvents ?? defaultPrepareKeypressEvents)(stdin);
+        stdin.setRawMode?.(true);
+        stdin.resume?.();
+        stdin.on('keypress', handleKeypress);
+        repaint(input, state, io);
+    });
+}

package/dist/memory-flow-interactive.test.d.ts

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

package/dist/memory-flow-interactive.test.js

@@ -0,0 +1,109 @@
+import { EventEmitter } from 'node:events';
+import { describe, expect, it, vi } from 'vitest';
+import { memoryFlowCommandForKey, renderMemoryFlowInteractively } from './memory-flow-interactive.js';
+class FakeStdin extends EventEmitter {
+    isTTY = true;
+    isRaw = false;
+    rawModes = [];
+    resume = vi.fn();
+    pause = vi.fn();
+    setRawMode(value) {
+        this.isRaw = value;
+        this.rawModes.push(value);
+    }
+}
+function replay() {
+    return {
+        runId: 'run-1',
+        connectionId: 'warehouse',
+        adapter: 'metricflow',
+        status: 'done',
+        sourceDir: '/tmp/source',
+        syncId: 'sync-1',
+        errors: [],
+        plannedWorkUnits: [
+            {
+                unitKey: 'orders',
+                rawFiles: ['models/orders.yml'],
+                peerFileCount: 0,
+                dependencyCount: 1,
+            },
+            {
+                unitKey: 'customers',
+                rawFiles: ['models/customers.yml'],
+                peerFileCount: 0,
+                dependencyCount: 0,
+            },
+        ],
+        details: { actions: [], provenance: [], transcripts: [] },
+        events: [
+            { type: 'source_acquired', adapter: 'metricflow', trigger: 'manual_resync', fileCount: 2 },
+            { type: 'scope_detected', fingerprint: null },
+            { type: 'raw_snapshot_written', syncId: 'sync-1', rawFileCount: 2 },
+            { type: 'diff_computed', added: 1, modified: 1, deleted: 0, unchanged: 0 },
+            { type: 'chunks_planned', chunkCount: 2, workUnitCount: 2, evictionCount: 0 },
+            { type: 'work_unit_started', unitKey: 'orders', skills: ['wiki_capture'], stepBudget: 4 },
+            { type: 'work_unit_finished', unitKey: 'orders', status: 'success' },
+            { type: 'work_unit_started', unitKey: 'customers', skills: ['wiki_capture'], stepBudget: 4 },
+            { type: 'work_unit_finished', unitKey: 'customers', status: 'failed', reason: 'validation reset' },
+            { type: 'reconciliation_finished', conflictCount: 0, fallbackCount: 1 },
+            { type: 'saved', commitSha: 'abc12345', wikiCount: 1, slCount: 1 },
+            { type: 'provenance_recorded', rowCount: 2 },
+            { type: 'report_created', runId: 'run-1', reportPath: 'report-1' },
+        ],
+    };
+}
+describe('memoryFlowCommandForKey', () => {
+    it('maps supported terminal key names to memory-flow commands', () => {
+        const idleSearch = { editing: false, query: '', matchIndex: 0 };
+        const editingSearch = { editing: true, query: 'c', matchIndex: 0 };
+        expect(memoryFlowCommandForKey('', idleSearch, { name: 'left' })).toBe('left');
+        expect(memoryFlowCommandForKey('', idleSearch, { name: 'right' })).toBe('right');
+        expect(memoryFlowCommandForKey('', idleSearch, { name: 'up' })).toBe('up');
+        expect(memoryFlowCommandForKey('', idleSearch, { name: 'down' })).toBe('down');
+        expect(memoryFlowCommandForKey('', idleSearch, { name: 'return' })).toBe('enter');
+        expect(memoryFlowCommandForKey('', idleSearch, { name: 'tab' })).toBe('tab');
+        expect(memoryFlowCommandForKey('', idleSearch, { name: 'f' })).toBe('filter');
+        expect(memoryFlowCommandForKey('', idleSearch, { name: 'p' })).toBe('provenance');
+        expect(memoryFlowCommandForKey('', idleSearch, { name: 't' })).toBe('transcript');
+        expect(memoryFlowCommandForKey('', idleSearch, { name: 'q' })).toBe('quit');
+        expect(memoryFlowCommandForKey('', idleSearch, { name: 'c', ctrl: true })).toBe('quit');
+        expect(memoryFlowCommandForKey('/', { editing: false, query: '', matchIndex: 0 }, { name: '/' })).toBe('search-start');
+        expect(memoryFlowCommandForKey('c', { editing: true, query: '', matchIndex: 0 }, { name: 'c' })).toEqual({
+            type: 'search-input',
+            value: 'c',
+        });
+        expect(memoryFlowCommandForKey('', editingSearch, { name: 'backspace' })).toBe('search-backspace');
+        expect(memoryFlowCommandForKey('', editingSearch, { name: 'return' })).toBe('search-submit');
+        expect(memoryFlowCommandForKey('', editingSearch, { name: 'escape' })).toBe('search-clear');
+        expect(memoryFlowCommandForKey('', idleSearch, { name: 'x' })).toBeNull();
+    });
+});
+describe('renderMemoryFlowInteractively', () => {
+    it('repaints on keypress and restores raw mode on quit', async () => {
+        let stdout = '';
+        const stdin = new FakeStdin();
+        const prepareKeypressEvents = vi.fn();
+        const promise = renderMemoryFlowInteractively(replay(), {
+            stdin,
+            stdout: {
+                isTTY: true,
+                columns: 120,
+                write: (chunk) => {
+                    stdout += chunk;
+                },
+            },
+        }, { prepareKeypressEvents });
+        stdin.emit('keypress', '', { name: 'right' });
+        stdin.emit('keypress', '', { name: 'tab' });
+        stdin.emit('keypress', '', { name: 'q' });
+        await expect(promise).resolves.toBeUndefined();
+        expect(prepareKeypressEvents).toHaveBeenCalledWith(stdin);
+        expect(stdin.rawModes).toEqual([true, false]);
+        expect(stdin.resume).toHaveBeenCalledTimes(1);
+        expect(stdin.pause).toHaveBeenCalledTimes(1);
+        expect(stdout).toContain('\u001b[2J\u001b[H');
+        expect(stdout).toContain('[ACTIONS]');
+        expect(stdout).toContain('Pane: trust');
+    });
+});

package/dist/memory-flow-tui.d.ts

@@ -0,0 +1,76 @@
+import { type MemoryFlowInteractionCommand, type MemoryFlowInteractionState, type MemoryFlowReplayInput } from '@ktx/context/ingest';
+import { type ReactNode } from 'react';
+export interface KtxMemoryFlowTuiIo {
+    stdin?: {
+        isTTY?: boolean;
+        setRawMode?(value: boolean): void;
+    };
+    stdout: {
+        isTTY?: boolean;
+        columns?: number;
+        write(chunk: string): void;
+    };
+    stderr: {
+        write(chunk: string): void;
+    };
+}
+export interface MemoryFlowTuiLiveSession {
+    update(input: MemoryFlowReplayInput): void;
+    close(): void;
+    isClosed(): boolean;
+}
+export interface MemoryFlowInkInstance {
+    rerender(tree: ReactNode): void;
+    unmount(): void;
+    waitUntilExit(): Promise<void>;
+    clear?(): void;
+}
+export interface MemoryFlowInkRenderOptions {
+    stdin?: KtxMemoryFlowTuiIo['stdin'];
+    stdout: KtxMemoryFlowTuiIo['stdout'];
+    stderr: KtxMemoryFlowTuiIo['stderr'];
+    exitOnCtrlC: boolean;
+    patchConsole: boolean;
+    maxFps: number;
+    alternateScreen: boolean;
+}
+interface RenderMemoryFlowTuiOptions {
+    renderInk?: (tree: ReactNode, options: MemoryFlowInkRenderOptions) => MemoryFlowInkInstance;
+    paceEvents?: boolean;
+    paceMsPerEvent?: number;
+    speedMultiplier?: number;
+}
+interface StartLiveMemoryFlowTuiOptions {
+    renderInk?: (tree: ReactNode, options: MemoryFlowInkRenderOptions) => MemoryFlowInkInstance;
+}
+interface InkKey {
+    leftArrow?: boolean;
+    rightArrow?: boolean;
+    upArrow?: boolean;
+    downArrow?: boolean;
+    return?: boolean;
+    escape?: boolean;
+    ctrl?: boolean;
+    shift?: boolean;
+    tab?: boolean;
+    backspace?: boolean;
+    delete?: boolean;
+}
+interface MemoryFlowTuiAppProps {
+    input: MemoryFlowReplayInput;
+    terminalWidth?: number;
+    env?: NodeJS.ProcessEnv;
+    onExit(): void;
+    paceEvents?: boolean;
+    paceMsPerEvent?: number;
+    frameMs?: number;
+    completionFrameMs?: number;
+    completionHoldMs?: number;
+    showBoot?: boolean;
+}
+export declare function sanitizeMemoryFlowTuiError(error: unknown): string;
+export declare function memoryFlowCommandForInkInput(input: string, key: InkKey, search?: MemoryFlowInteractionState['search']): MemoryFlowInteractionCommand | null;
+export declare function MemoryFlowTuiApp(props: MemoryFlowTuiAppProps): ReactNode;
+export declare function renderMemoryFlowTui(input: MemoryFlowReplayInput, io: KtxMemoryFlowTuiIo, options?: RenderMemoryFlowTuiOptions): Promise<boolean>;
+export declare function startLiveMemoryFlowTui(input: MemoryFlowReplayInput, io: KtxMemoryFlowTuiIo, options?: StartLiveMemoryFlowTuiOptions): Promise<MemoryFlowTuiLiveSession | null>;
+export {};