@kaelio/ktx 0.0.0 → 0.1.0-rc.0

package/dist/demo-metrics.test.js

@@ -0,0 +1,108 @@
+import { describe, expect, it } from 'vitest';
+import { buildDemoMetrics, formatCost, formatDuration, formatEta, formatTokens, formatTokensPerSec, progressBar, } from './demo-metrics.js';
+function snapshot(events, overrides = {}) {
+    return {
+        runId: 'run-1',
+        connectionId: 'orbit_demo',
+        adapter: 'live-database',
+        status: 'running',
+        sourceDir: null,
+        syncId: 'sync-1',
+        errors: [],
+        events,
+        plannedWorkUnits: [],
+        details: { actions: [], provenance: [], transcripts: [] },
+        ...overrides,
+    };
+}
+describe('buildDemoMetrics', () => {
+    it('estimates elapsed, agent steps, tool calls, and cost from event stream', () => {
+        const start = Date.UTC(2026, 0, 1, 0, 0, 0);
+        const input = snapshot([
+            { type: 'source_acquired', adapter: 'live-database', trigger: 'demo_full', fileCount: 5, emittedAt: new Date(start).toISOString() },
+            { type: 'work_unit_started', unitKey: 'orders', skills: [], stepBudget: 40, emittedAt: new Date(start + 1000).toISOString() },
+            { type: 'work_unit_step', unitKey: 'orders', stepIndex: 6, stepBudget: 40, emittedAt: new Date(start + 6000).toISOString() },
+        ], {
+            plannedWorkUnits: [
+                { unitKey: 'orders', rawFiles: [], peerFileCount: 0, dependencyCount: 0 },
+                { unitKey: 'customers', rawFiles: [], peerFileCount: 0, dependencyCount: 0 },
+            ],
+            details: {
+                actions: [],
+                provenance: [],
+                transcripts: [{ unitKey: 'orders', path: '/tmp/orders.jsonl', toolCallCount: 3, errorCount: 0, toolNames: ['x'] }],
+            },
+        });
+        const metrics = buildDemoMetrics(input, { now: () => start + 10_000 });
+        expect(metrics.elapsedMs).toBe(10_000);
+        expect(metrics.agentSteps).toBe(6);
+        expect(metrics.agentStepBudget).toBe(40);
+        expect(metrics.toolCalls).toBe(3);
+        expect(metrics.workUnitsTotal).toBe(2);
+        expect(metrics.estimatedTokens).toBeGreaterThan(0);
+        expect(metrics.estimatedCostUsd).toBeGreaterThan(0);
+        expect(metrics.isCostEstimated).toBe(true);
+    });
+    it('returns null ETA before the first work unit completes', () => {
+        const input = snapshot([{ type: 'source_acquired', adapter: 'live-database', trigger: 'x', fileCount: 1 }]);
+        const metrics = buildDemoMetrics(input, { now: () => Date.now() });
+        expect(metrics.etaMs).toBeNull();
+    });
+    it('extrapolates ETA from completed/total ratio when at least one unit finishes', () => {
+        const start = Date.UTC(2026, 0, 1);
+        const input = snapshot([
+            { type: 'source_acquired', adapter: 'a', trigger: 't', fileCount: 1, emittedAt: new Date(start).toISOString() },
+            { type: 'work_unit_started', unitKey: 'a', skills: [], stepBudget: 10, emittedAt: new Date(start + 1000).toISOString() },
+            { type: 'work_unit_finished', unitKey: 'a', status: 'success', emittedAt: new Date(start + 5000).toISOString() },
+        ], {
+            plannedWorkUnits: [
+                { unitKey: 'a', rawFiles: [], peerFileCount: 0, dependencyCount: 0 },
+                { unitKey: 'b', rawFiles: [], peerFileCount: 0, dependencyCount: 0 },
+                { unitKey: 'c', rawFiles: [], peerFileCount: 0, dependencyCount: 0 },
+            ],
+        });
+        const metrics = buildDemoMetrics(input, { now: () => start + 6_000 });
+        expect(metrics.etaMs).toBe(12_000);
+    });
+    it('reports ETA=0 when the run is finished', () => {
+        const input = snapshot([], { status: 'done' });
+        const metrics = buildDemoMetrics(input, { now: () => Date.now() });
+        expect(metrics.etaMs).toBe(0);
+    });
+});
+describe('format helpers', () => {
+    it('formats duration in s/m/h cascades', () => {
+        expect(formatDuration(5_000)).toBe('5s');
+        expect(formatDuration(95_000)).toBe('1m35s');
+        expect(formatDuration(3_700_000)).toBe('1h01m');
+        expect(formatDuration(-1)).toBe('--');
+    });
+    it('formats ETA as estimating before any data and as duration once running', () => {
+        expect(formatEta(null, 'running')).toBe('estimating...');
+        expect(formatEta(8_000, 'running')).toBe('8s');
+        expect(formatEta(8_000, 'done')).toBe('done');
+    });
+    it('formats cost with sub-cent guard', () => {
+        expect(formatCost(0)).toBe('$0.000');
+        expect(formatCost(0.0005)).toBe('<$0.001');
+        expect(formatCost(0.012)).toBe('$0.012');
+        expect(formatCost(2.5)).toBe('$2.50');
+    });
+    it('formats token counts with K/M abbreviations', () => {
+        expect(formatTokens(0)).toBe('0');
+        expect(formatTokens(450)).toBe('450');
+        expect(formatTokens(2_300)).toBe('2.3K');
+        expect(formatTokens(1_500_000)).toBe('1.50M');
+    });
+    it('formats tokens per second', () => {
+        expect(formatTokensPerSec(0)).toBe('0/s');
+        expect(formatTokensPerSec(450)).toBe('450/s');
+        expect(formatTokensPerSec(2300)).toBe('2.3K/s');
+    });
+    it('renders a deterministic progress bar with hash and dash characters', () => {
+        expect(progressBar(0, 10)).toBe('----------');
+        expect(progressBar(0.5, 10)).toBe('#####-----');
+        expect(progressBar(1, 10)).toBe('##########');
+        expect(progressBar(1.4, 10)).toBe('##########');
+    });
+});

package/dist/demo-progress.d.ts

@@ -0,0 +1,4 @@
+import type { MemoryFlowEvent, MemoryFlowReplayInput } from '@ktx/context/ingest/memory-flow';
+import type { KtxDemoIo } from './demo.js';
+export declare function formatMemoryFlowEventLine(event: MemoryFlowEvent): string | null;
+export declare function createPlainProgressEmitter(io: KtxDemoIo): (snapshot: MemoryFlowReplayInput) => void;

package/dist/demo-progress.js

@@ -0,0 +1,76 @@
+function plural(n, one, many = `${one}s`) {
+    return `${n} ${n === 1 ? one : many}`;
+}
+function formatDiff(added, modified, deleted, unchanged) {
+    const parts = [];
+    if (added > 0)
+        parts.push(`+${added} new`);
+    if (modified > 0)
+        parts.push(`~${modified} changed`);
+    if (deleted > 0)
+        parts.push(`-${deleted} removed`);
+    if (unchanged > 0)
+        parts.push(`=${unchanged} unchanged`);
+    return parts.length > 0 ? parts.join(', ') : 'no changes';
+}
+export function formatMemoryFlowEventLine(event) {
+    switch (event.type) {
+        case 'source_acquired':
+            return `[connect]  Connected ${event.adapter} - ${plural(event.fileCount, 'database file')} (${event.trigger})`;
+        case 'scope_detected':
+            return event.fingerprint
+                ? `[scope]    Scope locked: ${event.fingerprint}`
+                : '[scope]    Reviewing the whole warehouse (no scope filter)';
+        case 'raw_snapshot_written':
+            return `[snapshot] Captured snapshot ${event.syncId} - ${plural(event.rawFileCount, 'file')}`;
+        case 'diff_computed':
+            return `[diff]     Tables: ${formatDiff(event.added, event.modified, event.deleted, event.unchanged)}`;
+        case 'chunks_planned':
+            return event.evictionCount > 0
+                ? `[plan]     Grouped ${plural(event.workUnitCount, 'table')} into ${plural(event.chunkCount, 'business area')} (${plural(event.evictionCount, 'removal')})`
+                : `[plan]     Grouped ${plural(event.workUnitCount, 'table')} into ${plural(event.chunkCount, 'business area')}`;
+        case 'stage_skipped':
+            return `[skip]     ${event.stage} skipped: ${event.reason}`;
+        case 'work_unit_started':
+            return `[analyze]  Reviewing "${event.unitKey}" - budget ${plural(event.stepBudget, 'agent step')}`;
+        case 'work_unit_step':
+            return null;
+        case 'candidate_action': {
+            const target = event.target === 'sl' ? 'semantic-layer' : 'wiki';
+            return `[draft]    ${event.unitKey} -> ${target}: ${event.action} ${event.key}`;
+        }
+        case 'work_unit_finished':
+            if (event.status === 'success') {
+                return `[done]     ${event.unitKey} reviewed`;
+            }
+            return `[fail]     ${event.unitKey} needs attention${event.reason ? ` - ${event.reason}` : ''}`;
+        case 'reconciliation_finished': {
+            const conflicts = event.conflictCount === 0 ? 'no conflicts' : plural(event.conflictCount, 'conflict');
+            const fallbacks = event.fallbackCount === 0 ? 'nothing flagged for review' : `${plural(event.fallbackCount, 'item')} flagged for review`;
+            return `[validate] Reconciled drafts - ${conflicts}, ${fallbacks}`;
+        }
+        case 'saved': {
+            const total = event.wikiCount + event.slCount;
+            const commit = event.commitSha ? ` - commit ${event.commitSha.slice(0, 7)}` : '';
+            return `[memory]   Saved ${plural(total, 'memory', 'memories')} (${event.wikiCount} wiki, ${event.slCount} semantic-layer)${commit}`;
+        }
+        case 'provenance_recorded':
+            return `[trace]    Recorded provenance for ${plural(event.rowCount, 'row')}`;
+        case 'report_created':
+            return `[report]   Run report ready: ${event.runId}`;
+    }
+}
+export function createPlainProgressEmitter(io) {
+    let printed = 0;
+    return (snapshot) => {
+        while (printed < snapshot.events.length) {
+            const event = snapshot.events[printed++];
+            if (!event)
+                continue;
+            const line = formatMemoryFlowEventLine(event);
+            if (line !== null) {
+                io.stdout.write(`${line}\n`);
+            }
+        }
+    };
+}

package/dist/demo-progress.test.d.ts

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

package/dist/demo-progress.test.js

@@ -0,0 +1,168 @@
+import { describe, expect, it } from 'vitest';
+import { createPlainProgressEmitter, formatMemoryFlowEventLine } from './demo-progress.js';
+function snapshot(events) {
+    return {
+        runId: 'run-1',
+        connectionId: 'orbit_demo',
+        adapter: 'live-database',
+        status: 'running',
+        sourceDir: null,
+        syncId: 'sync-1',
+        errors: [],
+        events,
+        plannedWorkUnits: [],
+        details: { actions: [], provenance: [], transcripts: [] },
+    };
+}
+describe('formatMemoryFlowEventLine', () => {
+    it('formats source_acquired in plain English with adapter and file count', () => {
+        expect(formatMemoryFlowEventLine({
+            type: 'source_acquired',
+            adapter: 'live-database',
+            trigger: 'manual_resync',
+            fileCount: 7,
+        })).toBe('[connect]  Connected live-database - 7 database files (manual_resync)');
+    });
+    it('formats diff_computed as a comma-separated breakdown', () => {
+        expect(formatMemoryFlowEventLine({
+            type: 'diff_computed',
+            added: 3,
+            modified: 1,
+            deleted: 0,
+            unchanged: 4,
+        })).toBe('[diff]     Tables: +3 new, ~1 changed, =4 unchanged');
+    });
+    it('formats diff_computed as "no changes" when every counter is zero', () => {
+        expect(formatMemoryFlowEventLine({
+            type: 'diff_computed',
+            added: 0,
+            modified: 0,
+            deleted: 0,
+            unchanged: 0,
+        })).toBe('[diff]     Tables: no changes');
+    });
+    it('formats chunks_planned without removals as a single readable sentence', () => {
+        expect(formatMemoryFlowEventLine({
+            type: 'chunks_planned',
+            chunkCount: 7,
+            workUnitCount: 5,
+            evictionCount: 0,
+        })).toBe('[plan]     Grouped 5 tables into 7 business areas');
+    });
+    it('formats chunks_planned with removals when evictions are non-zero', () => {
+        expect(formatMemoryFlowEventLine({
+            type: 'chunks_planned',
+            chunkCount: 7,
+            workUnitCount: 5,
+            evictionCount: 2,
+        })).toBe('[plan]     Grouped 5 tables into 7 business areas (2 removals)');
+    });
+    it('formats work_unit_started in human terms', () => {
+        expect(formatMemoryFlowEventLine({
+            type: 'work_unit_started',
+            unitKey: 'revenue-policy',
+            skills: ['sl_expert', 'wiki_writer'],
+            stepBudget: 40,
+        })).toBe('[analyze]  Reviewing "revenue-policy" - budget 40 agent steps');
+    });
+    it('suppresses noisy work_unit_step events', () => {
+        expect(formatMemoryFlowEventLine({
+            type: 'work_unit_step',
+            unitKey: 'revenue-policy',
+            stepIndex: 3,
+            stepBudget: 40,
+        })).toBeNull();
+    });
+    it('formats candidate_action with friendly target and arrow', () => {
+        expect(formatMemoryFlowEventLine({
+            type: 'candidate_action',
+            unitKey: 'revenue-policy',
+            target: 'sl',
+            action: 'created',
+            key: 'warehouse.revenue',
+        })).toBe('[draft]    revenue-policy -> semantic-layer: created warehouse.revenue');
+    });
+    it('formats work_unit_finished with status-aware tag', () => {
+        expect(formatMemoryFlowEventLine({
+            type: 'work_unit_finished',
+            unitKey: 'revenue-policy',
+            status: 'success',
+        })).toBe('[done]     revenue-policy reviewed');
+        expect(formatMemoryFlowEventLine({
+            type: 'work_unit_finished',
+            unitKey: 'revenue-policy',
+            status: 'failed',
+            reason: 'budget exhausted',
+        })).toBe('[fail]     revenue-policy needs attention - budget exhausted');
+    });
+    it('formats reconciliation_finished with friendly counter wording', () => {
+        expect(formatMemoryFlowEventLine({
+            type: 'reconciliation_finished',
+            conflictCount: 0,
+            fallbackCount: 0,
+        })).toBe('[validate] Reconciled drafts - no conflicts, nothing flagged for review');
+        expect(formatMemoryFlowEventLine({
+            type: 'reconciliation_finished',
+            conflictCount: 2,
+            fallbackCount: 1,
+        })).toBe('[validate] Reconciled drafts - 2 conflicts, 1 item flagged for review');
+    });
+    it('formats saved with optional shortened commit sha and pluralized memory count', () => {
+        expect(formatMemoryFlowEventLine({
+            type: 'saved',
+            commitSha: 'abc1234567890', // pragma: allowlist secret
+            wikiCount: 2,
+            slCount: 5,
+        })).toBe('[memory]   Saved 7 memories (2 wiki, 5 semantic-layer) - commit abc1234');
+        expect(formatMemoryFlowEventLine({
+            type: 'saved',
+            commitSha: null,
+            wikiCount: 0,
+            slCount: 1,
+        })).toBe('[memory]   Saved 1 memory (0 wiki, 1 semantic-layer)');
+    });
+    it('formats report_created with run id', () => {
+        expect(formatMemoryFlowEventLine({
+            type: 'report_created',
+            runId: 'run-xyz',
+        })).toBe('[report]   Run report ready: run-xyz');
+    });
+});
+describe('createPlainProgressEmitter', () => {
+    it('writes one line per new event and never re-emits prior events', () => {
+        const written = [];
+        const io = {
+            stdout: { write: (chunk) => written.push(chunk), isTTY: false },
+            stderr: { write: () => undefined },
+        };
+        const emit = createPlainProgressEmitter(io);
+        emit(snapshot([
+            { type: 'source_acquired', adapter: 'live-database', trigger: 'manual_resync', fileCount: 7 },
+            { type: 'diff_computed', added: 0, modified: 0, deleted: 0, unchanged: 7 },
+        ]));
+        emit(snapshot([
+            { type: 'source_acquired', adapter: 'live-database', trigger: 'manual_resync', fileCount: 7 },
+            { type: 'diff_computed', added: 0, modified: 0, deleted: 0, unchanged: 7 },
+            { type: 'work_unit_started', unitKey: 'revenue-policy', skills: ['sl_expert'], stepBudget: 40 },
+        ]));
+        expect(written).toEqual([
+            '[connect]  Connected live-database - 7 database files (manual_resync)\n',
+            '[diff]     Tables: =7 unchanged\n',
+            '[analyze]  Reviewing "revenue-policy" - budget 40 agent steps\n',
+        ]);
+    });
+    it('skips suppressed events without advancing visible output', () => {
+        const written = [];
+        const io = {
+            stdout: { write: (chunk) => written.push(chunk), isTTY: false },
+            stderr: { write: () => undefined },
+        };
+        const emit = createPlainProgressEmitter(io);
+        emit(snapshot([
+            { type: 'work_unit_step', unitKey: 'a', stepIndex: 1, stepBudget: 40 },
+            { type: 'work_unit_step', unitKey: 'a', stepIndex: 2, stepBudget: 40 },
+            { type: 'work_unit_finished', unitKey: 'a', status: 'success' },
+        ]));
+        expect(written).toEqual(['[done]     a reviewed\n']);
+    });
+});

package/dist/demo-replay-store.d.ts

@@ -0,0 +1,12 @@
+import { type MemoryFlowReplayInput } from '@ktx/context/ingest/memory-flow';
+interface SavedDemoReplay {
+    replayPath: string;
+    latestReplayPath: string;
+}
+export declare const DEMO_LATEST_REPLAY_FILE = "latest.memory-flow.v1.json";
+export declare function loadDemoReplayFile(path: string): Promise<MemoryFlowReplayInput>;
+export declare function loadLatestDemoReplay(projectDir: string): Promise<MemoryFlowReplayInput | null>;
+export declare function writeDemoReplay(projectDir: string, input: MemoryFlowReplayInput, options: {
+    label: 'full' | 'deterministic' | 'seeded';
+}): Promise<SavedDemoReplay>;
+export {};

package/dist/demo-replay-store.js

@@ -0,0 +1,47 @@
+import { constants as fsConstants } from 'node:fs';
+import { access, copyFile, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { parseMemoryFlowReplayInput } from '@ktx/context/ingest/memory-flow';
+export const DEMO_LATEST_REPLAY_FILE = 'latest.memory-flow.v1.json';
+async function exists(path) {
+    try {
+        await access(path, fsConstants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function safeReplayName(value) {
+    return value.replace(/[^a-zA-Z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'replay';
+}
+function demoReplayFileName(input, label) {
+    return `${safeReplayName(label)}-${safeReplayName(input.runId)}.memory-flow.v1.json`;
+}
+function wrapReplay(input) {
+    return { memoryFlowReplaySchemaVersion: 1, replay: input };
+}
+export async function loadDemoReplayFile(path) {
+    const parsed = JSON.parse(await readFile(path, 'utf-8'));
+    if (parsed.memoryFlowReplaySchemaVersion !== 1) {
+        throw new Error(`Unsupported demo replay schema version in ${path}`);
+    }
+    return parseMemoryFlowReplayInput(parsed.replay);
+}
+export async function loadLatestDemoReplay(projectDir) {
+    const latestPath = join(resolve(projectDir), 'replays', DEMO_LATEST_REPLAY_FILE);
+    if (!(await exists(latestPath))) {
+        return null;
+    }
+    return loadDemoReplayFile(latestPath);
+}
+export async function writeDemoReplay(projectDir, input, options) {
+    const replayDir = join(resolve(projectDir), 'replays');
+    await mkdir(replayDir, { recursive: true });
+    const replayPath = join(replayDir, demoReplayFileName(input, options.label));
+    const latestReplayPath = join(replayDir, DEMO_LATEST_REPLAY_FILE);
+    const body = `${JSON.stringify(wrapReplay(input), null, 2)}\n`;
+    await writeFile(replayPath, body, 'utf-8');
+    await copyFile(replayPath, latestReplayPath);
+    return { replayPath, latestReplayPath };
+}

package/dist/demo-replay-store.test.d.ts

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

package/dist/demo-replay-store.test.js

@@ -0,0 +1,50 @@
+import { mkdtemp, readFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { DEMO_LATEST_REPLAY_FILE, loadLatestDemoReplay, writeDemoReplay } from './demo-replay-store.js';
+function replay(overrides = {}) {
+    return {
+        metadata: {
+            schemaVersion: 1,
+            mode: 'full',
+            origin: 'captured',
+            timing: 'captured',
+            capturedAt: '2026-05-01T10:00:03.000Z',
+            sourceReportId: 'report-1',
+            sourceReportPath: 'report-1',
+            fallbackReason: null,
+        },
+        runId: 'run-1',
+        connectionId: 'orbit_demo',
+        adapter: 'live-database',
+        status: 'done',
+        sourceDir: null,
+        syncId: 'sync-1',
+        reportId: 'report-1',
+        reportPath: 'report-1',
+        errors: [],
+        events: [{ type: 'report_created', runId: 'run-1', reportPath: 'report-1', emittedAt: '2026-05-01T10:00:03.000Z' }],
+        plannedWorkUnits: [],
+        details: { actions: [], provenance: [], transcripts: [] },
+        ...overrides,
+    };
+}
+describe('demo replay store', () => {
+    it('writes a versioned replay file and updates latest', async () => {
+        const projectDir = await mkdtemp(join(tmpdir(), 'ktx-demo-replay-store-'));
+        const saved = await writeDemoReplay(projectDir, replay(), { label: 'full' });
+        expect(saved.replayPath).toMatch(/replays[/\\]full-run-1.memory-flow.v1.json$/);
+        expect(saved.latestReplayPath).toBe(join(projectDir, 'replays', DEMO_LATEST_REPLAY_FILE));
+        expect(await loadLatestDemoReplay(projectDir)).toMatchObject({
+            runId: 'run-1',
+            metadata: { mode: 'full', origin: 'captured', timing: 'captured' },
+        });
+        const wrapper = JSON.parse(await readFile(saved.latestReplayPath, 'utf-8'));
+        expect(wrapper.memoryFlowReplaySchemaVersion).toBe(1);
+    });
+    it('returns null when no latest local replay exists', async () => {
+        const projectDir = await mkdtemp(join(tmpdir(), 'ktx-demo-replay-store-empty-'));
+        await expect(loadLatestDemoReplay(projectDir)).resolves.toBeNull();
+    });
+});

package/dist/demo-scan.d.ts

@@ -0,0 +1,31 @@
+import { type IngestReportSnapshot, type MemoryFlowReplayInput } from '@ktx/context/ingest';
+import { type KtxLocalProject } from '@ktx/context/project';
+import { runLocalScan, type KtxScanReport, type LocalScanRunResult } from '@ktx/context/scan';
+interface DemoScanOptions {
+    projectDir: string;
+    jobId?: string;
+    now?: () => Date;
+    runLocalScan?: typeof runLocalScan;
+}
+interface DemoScanResult {
+    project: KtxLocalProject;
+    result: LocalScanRunResult;
+}
+interface DemoInspectSummary {
+    projectDir: string;
+    scanReport: KtxScanReport | null;
+    fullReport: IngestReportSnapshot | null;
+    semanticLayerFileCount: number;
+    knowledgeFileCount: number;
+    replayFileCount: number;
+    latestReplay: MemoryFlowReplayInput | null;
+}
+interface DemoInspectDeps {
+    findFullReport?: (project: KtxLocalProject) => Promise<IngestReportSnapshot | null>;
+}
+export declare function runDemoScan(options: DemoScanOptions): Promise<DemoScanResult>;
+export declare function findLatestDemoScanReport(projectDir: string): Promise<KtxScanReport | null>;
+export declare function inspectDemoProject(projectDir: string, projectOverride?: KtxLocalProject, deps?: DemoInspectDeps): Promise<DemoInspectSummary>;
+export declare function formatDemoScanSummary(report: KtxScanReport): string;
+export declare function formatDemoInspect(summary: DemoInspectSummary): string;
+export {};