@kaelio/ktx 0.1.0-rc.5 → 0.1.0

package/dist/io/print-list.d.ts

@@ -22,7 +22,7 @@ export interface PrintListColumn<Row> {
      * - `'suffix'` — trailing em-dash optional value. Default: any column with `optional: true`.
      */
     role?: 'name' | 'metric' | 'badge' | 'suffix';
-    /** Custom pretty-mode value formatter (e.g. score → "87%"). Plain/JSON unaffected. */
+    /** Custom pretty-mode value formatter (for example, score -> "#1"). Plain/JSON unaffected. */
     prettyFormat?: (value: Row[keyof Row & string], row: Row) => string;
 }
 export interface PrintListArgs<Row> {
@@ -40,3 +40,4 @@ export interface PrintListArgs<Row> {
     io: KtxCliIo;
 }
 export declare function printList<Row extends object>(args: PrintListArgs<Row>): void;
+export declare function createRankBadgeFormatter<Row extends object>(rows: ReadonlyArray<Row>): (_value: Row[keyof Row & string], row: Row) => string;

package/dist/io/print-list.js

@@ -15,6 +15,13 @@ export function printList(args) {
             return;
     }
 }
+export function createRankBadgeFormatter(rows) {
+    const ranks = new WeakMap();
+    rows.forEach((row, index) => {
+        ranks.set(row, index + 1);
+    });
+    return (_value, row) => `#${ranks.get(row) ?? rows.indexOf(row) + 1}`;
+}
 function isEmpty(value) {
     return value === undefined || value === null || value === '';
 }

package/dist/io/print-list.test.js

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { printList } from './print-list.js';
+import { createRankBadgeFormatter, printList } from './print-list.js';
 import { SYMBOLS } from './symbols.js';
 function recorder() {
     let stdout = '';
@@ -209,25 +209,25 @@ describe('printList — pretty mode', () => {
         expect(out).toContain('(2 pages)');
         expect(out).toContain('2 pages');
     });
-    it('renders a leading badge column with prettyFormat in pretty mode', () => {
+    it('renders a leading rank badge column in pretty mode', () => {
         const r = recorder();
+        const rows = [
+            { score: 0.87, scope: 'GLOBAL', key: 'alpha', summary: 'first' },
+            { score: 0.04, scope: 'GLOBAL', key: 'beta', summary: 'second' },
+        ];
         const SEARCH_COLUMNS = [
             {
                 key: 'score',
                 label: 'SCORE',
                 plain: 'score=',
                 role: 'badge',
-                prettyFormat: (v) => `${Math.round(Number(v) * 100)}%`,
+                prettyFormat: createRankBadgeFormatter(rows),
                 dim: true,
             },
             { key: 'scope', label: 'SCOPE', plain: '' },
             { key: 'key', label: 'KEY', plain: '' },
             { key: 'summary', label: 'SUMMARY', plain: '', optional: true, dim: true },
         ];
-        const rows = [
-            { score: 0.87, scope: 'GLOBAL', key: 'alpha', summary: 'first' },
-            { score: 0.04, scope: 'GLOBAL', key: 'beta', summary: 'second' },
-        ];
         printList({
             rows,
             columns: SEARCH_COLUMNS,
@@ -239,18 +239,20 @@ describe('printList — pretty mode', () => {
             io: r.io,
         });
         const out = stripAnsi(r.out());
-        expect(out).toMatch(/87%\s+alpha\s+/);
-        expect(out).toMatch(/4%\s+beta\s+/);
+        expect(out).toMatch(/#1\s+alpha\s+/);
+        expect(out).toMatch(/#2\s+beta\s+/);
+        expect(out).not.toContain('%');
     });
     it('emits the badge column in plain mode using its plain prefix', () => {
         const r = recorder();
+        const rows = [{ score: 0.87, scope: 'GLOBAL', key: 'alpha', summary: 'first' }];
         const SEARCH_COLUMNS = [
             {
                 key: 'score',
                 label: 'SCORE',
                 plain: 'score=',
                 role: 'badge',
-                prettyFormat: (v) => `${Math.round(Number(v) * 100)}%`,
+                prettyFormat: createRankBadgeFormatter(rows),
                 dim: true,
             },
             { key: 'scope', label: 'SCOPE', plain: '' },
@@ -258,7 +260,7 @@ describe('printList — pretty mode', () => {
             { key: 'summary', label: 'SUMMARY', plain: '', optional: true, dim: true },
         ];
         printList({
-            rows: [{ score: 0.87, scope: 'GLOBAL', key: 'alpha', summary: 'first' }],
+            rows,
             columns: SEARCH_COLUMNS,
             groupBy: 'scope',
             mode: 'plain',

package/dist/io/symbols.d.ts

@@ -1,6 +1,6 @@
 export declare const SYMBOLS: {
-    readonly middot: "·" | "-";
-    readonly emDash: "—" | "--";
+    readonly middot: "-" | "·";
+    readonly emDash: "--" | "—";
 };
 export declare function dim(text: string): string;
 export declare function bold(text: string): string;

package/dist/knowledge.d.ts

@@ -13,6 +13,7 @@ export type KtxKnowledgeArgs = {
     output?: string;
     json?: boolean;
     limit?: number;
+    debug?: boolean;
 };
 type KtxKnowledgeIo = import('./cli-runtime.js').KtxCliIo;
 interface KtxKnowledgeDeps {

package/dist/knowledge.js

@@ -2,25 +2,27 @@ import { createLocalKtxEmbeddingProviderFromConfig, KtxIngestEmbeddingPortAdapte
 import { loadKtxProject } from '@ktx/context/project';
 import { listLocalKnowledgePages, searchLocalKnowledgePages, } from '@ktx/context/wiki';
 import { resolveOutputMode } from './io/mode.js';
-import { printList } from './io/print-list.js';
+import { createRankBadgeFormatter, printList } from './io/print-list.js';
 const WIKI_LIST_COLUMNS = [
     { key: 'scope', label: 'SCOPE', plain: '' },
     { key: 'key', label: 'KEY', plain: '' },
     { key: 'summary', label: 'SUMMARY', plain: '', optional: true, dim: true },
 ];
-const WIKI_SEARCH_COLUMNS = [
-    {
-        key: 'score',
-        label: 'SCORE',
-        plain: 'score=',
-        role: 'badge',
-        prettyFormat: (value) => `${Math.round(Number(value) * 100)}%`,
-        dim: true,
-    },
-    { key: 'scope', label: 'SCOPE', plain: '' },
-    { key: 'key', label: 'KEY', plain: '' },
-    { key: 'summary', label: 'SUMMARY', plain: '', optional: true, dim: true },
-];
+function wikiSearchColumns(rows) {
+    return [
+        {
+            key: 'score',
+            label: 'SCORE',
+            plain: 'score=',
+            role: 'badge',
+            prettyFormat: createRankBadgeFormatter(rows),
+            dim: true,
+        },
+        { key: 'scope', label: 'SCOPE', plain: '' },
+        { key: 'key', label: 'KEY', plain: '' },
+        { key: 'summary', label: 'SUMMARY', plain: '', optional: true, dim: true },
+    ];
+}
 function wikiSearchEmbeddingService(project, deps) {
     if ('embeddingService' in deps) {
         return deps.embeddingService ?? null;
@@ -28,6 +30,14 @@ function wikiSearchEmbeddingService(project, deps) {
     const provider = (deps.createEmbeddingProvider ?? createLocalKtxEmbeddingProviderFromConfig)(project.config.ingest.embeddings);
     return provider ? new KtxIngestEmbeddingPortAdapter(provider) : null;
 }
+function writeWikiSearchDebug(io, input) {
+    io.stderr.write(`[debug] wiki search mode=${input.mode} embedding=${input.embeddingConfigured ? 'configured' : 'unconfigured'} results=${input.results.length}\n`);
+    const lanes = input.results[0]?.lanes ?? [];
+    for (const lane of lanes) {
+        const reason = lane.reason ? ` reason=${lane.reason}` : '';
+        io.stderr.write(`[debug] wiki search lane=${lane.lane} status=${lane.status} returned=${lane.returnedCandidateCount} weight=${lane.weight}${reason}\n`);
+    }
+}
 export async function runKtxKnowledge(args, io = process, deps = {}) {
     try {
         const project = await loadKtxProject({ projectDir: args.projectDir });
@@ -48,12 +58,20 @@ export async function runKtxKnowledge(args, io = process, deps = {}) {
             return 0;
         }
         if (args.command === 'search') {
+            const embeddingService = wikiSearchEmbeddingService(project, deps);
             const results = await searchLocalKnowledgePages(project, {
                 query: args.query,
                 userId: args.userId,
-                embeddingService: wikiSearchEmbeddingService(project, deps),
+                embeddingService,
                 limit: args.limit,
             });
+            if (args.debug) {
+                writeWikiSearchDebug(io, {
+                    mode: project.config.storage.search,
+                    embeddingConfigured: embeddingService !== null,
+                    results,
+                });
+            }
             const mode = resolveOutputMode({ explicit: args.output, json: args.json, io });
             let emptyMessage = `No local wiki pages matched "${args.query}"`;
             let emptyHint = 'Run `ktx wiki list` to inspect available pages.';
@@ -66,7 +84,7 @@ export async function runKtxKnowledge(args, io = process, deps = {}) {
             }
             printList({
                 rows: results,
-                columns: WIKI_SEARCH_COLUMNS,
+                columns: wikiSearchColumns(results),
                 groupBy: 'scope',
                 emptyMessage,
                 emptyHint,

package/dist/knowledge.test.js

@@ -1,6 +1,7 @@
 import { mkdtemp, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { stripVTControlCharacters } from 'node:util';
 import { initKtxProject, loadKtxProject } from '@ktx/context/project';
 import { writeLocalKnowledgePage } from '@ktx/context/wiki';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
@@ -67,6 +68,16 @@ describe('runKtxKnowledge', () => {
         await expect(runKtxKnowledge({ command: 'search', projectDir, query: 'paid order', userId: 'local' }, searchIo.io)).resolves.toBe(0);
         expect(searchIo.stdout()).toContain('metrics-revenue');
     });
+    it('prints wiki search rank badges in pretty output', async () => {
+        const projectDir = join(tempDir, 'rank-project');
+        await initKtxProject({ projectDir });
+        await seedWikiPage(projectDir);
+        const searchIo = makeIo();
+        await expect(runKtxKnowledge({ command: 'search', projectDir, query: 'paid order', userId: 'local', output: 'pretty' }, searchIo.io)).resolves.toBe(0);
+        const stdout = stripVTControlCharacters(searchIo.stdout());
+        expect(stdout).toMatch(/#1\s+metrics-revenue/);
+        expect(stdout).not.toContain('%');
+    });
     it('prints wiki list and search as public JSON envelopes', async () => {
         const projectDir = join(tempDir, 'project');
         await initKtxProject({ projectDir });
@@ -110,4 +121,20 @@ describe('runKtxKnowledge', () => {
         expect(searchIo.stdout()).toContain('active-contract-arr-open-tickets');
         expect(searchIo.stderr()).toBe('');
     });
+    it('writes wiki search lane diagnostics to stderr when debug is enabled', async () => {
+        const projectDir = join(tempDir, 'debug-project');
+        await initKtxProject({ projectDir });
+        await seedWikiPage(projectDir);
+        const searchIo = makeIo();
+        await expect(runKtxKnowledge({ command: 'search', projectDir, query: 'paid order', userId: 'local', json: true, debug: true }, searchIo.io, { embeddingService: new FakeEmbeddingPort() })).resolves.toBe(0);
+        expect(JSON.parse(searchIo.stdout())).toMatchObject({
+            kind: 'list',
+            data: { items: [expect.objectContaining({ key: 'metrics-revenue' })] },
+            meta: { command: 'wiki search' },
+        });
+        expect(searchIo.stderr()).toContain('[debug] wiki search mode=sqlite-fts5');
+        expect(searchIo.stderr()).toContain('embedding=configured');
+        expect(searchIo.stderr()).toContain('lane=lexical status=available');
+        expect(searchIo.stderr()).toContain('lane=semantic status=available');
+    });
 });

package/dist/managed-python-command.d.ts

@@ -1,5 +1,6 @@
 import { createPythonSemanticLayerComputePort, type KtxSemanticLayerComputePort } from '@ktx/context/daemon';
 import type { KtxCliIo } from './cli-runtime.js';
+import { type KtxCliSpinner } from './clack.js';
 import { type InstalledKtxRuntimeManifest, type KtxRuntimeFeature, type ManagedPythonRuntimeInstallOptions, type ManagedPythonRuntimeInstallResult, type ManagedPythonRuntimeLayout, type ManagedPythonRuntimeLayoutOptions, type ManagedPythonRuntimeStatus } from './managed-python-runtime.js';
 export type KtxManagedPythonInstallPolicy = 'prompt' | 'auto' | 'never';
 export declare function runtimeInstallPolicyFromFlags(options: {
@@ -14,6 +15,7 @@ export interface ManagedPythonCommandDeps {
     readStatus?: (options: ManagedPythonRuntimeLayoutOptions) => Promise<ManagedPythonRuntimeStatus>;
     installRuntime?: (options: ManagedPythonRuntimeInstallOptions) => Promise<ManagedPythonRuntimeInstallResult>;
     confirmInstall?: (message: string, io: KtxCliIo) => Promise<boolean>;
+    spinner?: () => KtxCliSpinner;
 }
 export interface ManagedPythonCommandOptions extends ManagedPythonCommandDeps {
     cliVersion: string;

package/dist/managed-python-command.js

@@ -1,5 +1,5 @@
 import { createPythonSemanticLayerComputePort } from '@ktx/context/daemon';
-import { createClackPromptAdapter } from './clack.js';
+import { createClackPromptAdapter, createStaticCliSpinner } from './clack.js';
 import { installManagedPythonRuntime, readManagedPythonRuntimeStatus, } from './managed-python-runtime.js';
 export function runtimeInstallPolicyFromFlags(options) {
     if (options.yes === true && options.input === false) {
@@ -50,14 +50,21 @@ export async function ensureManagedPythonCommandRuntime(options) {
             throw new Error(`KTX Python runtime installation was cancelled. Run: ${managedRuntimeInstallCommand(feature)}`);
         }
     }
-    options.io.stderr.write(`Installing KTX Python runtime (${feature}) with uv...\n`);
-    const installed = await installRuntime({
-        cliVersion: options.cliVersion,
-        features: [feature],
-        force: false,
-    });
-    options.io.stderr.write(`KTX Python runtime ready: ${installed.layout.versionDir}\n`);
-    return { layout: installed.layout, manifest: installed.manifest };
+    const progress = (options.spinner ?? (() => createStaticCliSpinner(options.io)))();
+    progress.start(`Installing KTX Python runtime (${feature}) with uv...`);
+    try {
+        const installed = await installRuntime({
+            cliVersion: options.cliVersion,
+            features: [feature],
+            force: false,
+        });
+        progress.stop(`KTX Python runtime ready: ${installed.layout.versionDir}`);
+        return { layout: installed.layout, manifest: installed.manifest };
+    }
+    catch (error) {
+        progress.error(`KTX Python runtime install failed: ${error instanceof Error ? error.message : String(error)}`);
+        throw error;
+    }
 }
 export async function createManagedPythonSemanticLayerComputePort(options) {
     const runtime = await ensureManagedPythonCommandRuntime({
@@ -68,6 +75,7 @@ export async function createManagedPythonSemanticLayerComputePort(options) {
         ...(options.readStatus ? { readStatus: options.readStatus } : {}),
         ...(options.installRuntime ? { installRuntime: options.installRuntime } : {}),
         ...(options.confirmInstall ? { confirmInstall: options.confirmInstall } : {}),
+        ...(options.spinner ? { spinner: options.spinner } : {}),
     });
     const createPythonCompute = options.createPythonCompute ?? createPythonSemanticLayerComputePort;
     return createPythonCompute({

package/dist/managed-python-command.test.js

@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from 'vitest';
-import { createManagedPythonSemanticLayerComputePort, managedRuntimeInstallCommand, runtimeInstallPolicyFromFlags, } from './managed-python-command.js';
+import { createManagedPythonSemanticLayerComputePort, ensureManagedPythonCommandRuntime, managedRuntimeInstallCommand, runtimeInstallPolicyFromFlags, } from './managed-python-command.js';
 function makeIo() {
     let stdout = '';
     let stderr = '';
@@ -85,6 +85,16 @@ function installResult(features = ['core']) {
         manifest: installedManifest,
     };
 }
+function makeSpinnerEvents() {
+    const events = [];
+    const spinner = vi.fn(() => ({
+        start: (msg) => events.push(`start:${msg}`),
+        message: (msg) => events.push(`message:${msg}`),
+        stop: (msg) => events.push(`stop:${msg}`),
+        error: (msg) => events.push(`error:${msg}`),
+    }));
+    return { events, spinner };
+}
 describe('managedRuntimeInstallCommand', () => {
     it('prints the exact command for each managed runtime feature', () => {
         expect(managedRuntimeInstallCommand('core')).toBe('ktx dev runtime install --yes');
@@ -103,6 +113,42 @@ describe('runtimeInstallPolicyFromFlags', () => {
     });
 });
 describe('createManagedPythonSemanticLayerComputePort', () => {
+    it('uses non-animated runtime setup status by default', async () => {
+        const io = makeIo();
+        await expect(ensureManagedPythonCommandRuntime({
+            cliVersion: '0.2.0',
+            installPolicy: 'auto',
+            io: io.io,
+            readStatus: vi.fn(async () => missingStatus()),
+            installRuntime: vi.fn(async () => installResult(['local-embeddings'])),
+            feature: 'local-embeddings',
+        })).resolves.toMatchObject({
+            layout: { versionDir: '/runtime/0.2.0' },
+        });
+        expect(io.stderr()).toContain('Installing KTX Python runtime (local-embeddings) with uv...');
+        expect(io.stderr()).toContain('KTX Python runtime ready: /runtime/0.2.0');
+        expect(io.stderr().match(/Installing KTX Python runtime/g)).toHaveLength(1);
+    });
+    it('shows runtime installation progress with the CLI spinner', async () => {
+        const io = makeIo();
+        const { events, spinner } = makeSpinnerEvents();
+        const options = {
+            cliVersion: '0.2.0',
+            installPolicy: 'auto',
+            io: io.io,
+            readStatus: vi.fn(async () => missingStatus()),
+            installRuntime: vi.fn(async () => installResult(['local-embeddings'])),
+            feature: 'local-embeddings',
+            spinner,
+        };
+        await expect(ensureManagedPythonCommandRuntime(options)).resolves.toMatchObject({
+            layout: { versionDir: '/runtime/0.2.0' },
+        });
+        expect(events).toEqual([
+            'start:Installing KTX Python runtime (local-embeddings) with uv...',
+            'stop:KTX Python runtime ready: /runtime/0.2.0',
+        ]);
+    });
     it('uses the managed ktx-daemon executable when the runtime is ready', async () => {
         const io = makeIo();
         const compute = { query: vi.fn(), validateSources: vi.fn(), generateSources: vi.fn() };
@@ -135,6 +181,7 @@ describe('createManagedPythonSemanticLayerComputePort', () => {
     });
     it('installs the core runtime without prompting when policy is auto', async () => {
         const io = makeIo();
+        const { events, spinner } = makeSpinnerEvents();
         const compute = { query: vi.fn(), validateSources: vi.fn(), generateSources: vi.fn() };
         const createPythonCompute = vi.fn(() => compute);
         const installRuntime = vi.fn(async () => installResult());
@@ -145,17 +192,21 @@ describe('createManagedPythonSemanticLayerComputePort', () => {
             readStatus: vi.fn(async () => missingStatus()),
             installRuntime,
             createPythonCompute,
+            spinner,
         })).resolves.toBe(compute);
         expect(installRuntime).toHaveBeenCalledWith({
             cliVersion: '0.2.0',
             features: ['core'],
             force: false,
         });
-        expect(io.stderr()).toContain('Installing KTX Python runtime (core) with uv');
-        expect(io.stderr()).toContain('KTX Python runtime ready: /runtime/0.2.0');
+        expect(events).toEqual([
+            'start:Installing KTX Python runtime (core) with uv...',
+            'stop:KTX Python runtime ready: /runtime/0.2.0',
+        ]);
     });
     it('prompts before installing when policy is prompt', async () => {
         const io = makeIo();
+        const { events, spinner } = makeSpinnerEvents();
         const confirmInstall = vi.fn(async () => true);
         const installRuntime = vi.fn(async () => installResult());
         await createManagedPythonSemanticLayerComputePort({
@@ -166,6 +217,7 @@ describe('createManagedPythonSemanticLayerComputePort', () => {
             installRuntime,
             createPythonCompute: vi.fn(() => ({ query: vi.fn(), validateSources: vi.fn(), generateSources: vi.fn() })),
             confirmInstall,
+            spinner,
         });
         expect(confirmInstall).toHaveBeenCalledWith('KTX needs to install the core Python runtime. This downloads Python dependencies with uv. Continue?', io.io);
         expect(installRuntime).toHaveBeenCalledWith({
@@ -173,9 +225,11 @@ describe('createManagedPythonSemanticLayerComputePort', () => {
             features: ['core'],
             force: false,
         });
+        expect(events).toContainEqual('start:Installing KTX Python runtime (core) with uv...');
     });
     it('uses injected runtime confirmation instead of reading process TTY directly', async () => {
         const io = makeIo();
+        const { events, spinner } = makeSpinnerEvents();
         const compute = { query: vi.fn(), validateSources: vi.fn(), generateSources: vi.fn() };
         const installRuntime = vi.fn(async () => installResult());
         const confirmInstall = vi.fn(async () => true);
@@ -187,9 +241,10 @@ describe('createManagedPythonSemanticLayerComputePort', () => {
             installRuntime,
             confirmInstall,
             createPythonCompute: () => compute,
+            spinner,
         })).resolves.toBe(compute);
         expect(confirmInstall).toHaveBeenCalledWith('KTX needs to install the core Python runtime. This downloads Python dependencies with uv. Continue?', io.io);
-        expect(io.stderr()).toContain('Installing KTX Python runtime (core) with uv...');
+        expect(events).toContainEqual('start:Installing KTX Python runtime (core) with uv...');
     });
     it('can decide default runtime prompting from injected io capabilities', async () => {
         const io = makeIo();

package/dist/next-steps.js

@@ -29,7 +29,7 @@ function commandLines(commands, indent) {
 }
 export function formatNextStepLines(indent = '  ') {
     return [
-        `${indent}KTX context is ready for agents. Open your coding agent in this directory and ask a data question.`,
+        `${indent}KTX context is ready for agents. Open your coding agent from the KTX project directory and ask a data question.`,
         `${indent}Verify with:`,
         ...commandLines(KTX_NEXT_STEP_DIRECT_COMMANDS, indent),
     ];

package/dist/next-steps.test.js

@@ -38,8 +38,10 @@ describe('KTX demo next steps', () => {
     it('explains what the next-step commands are for', () => {
         const rendered = formatNextStepLines().join('\n');
         expect(rendered).toContain('KTX context is ready for agents.');
+        expect(rendered).toContain('KTX project directory');
         expect(rendered).toContain('ask a data question');
         expect(rendered).toContain('Verify with:');
+        expect(rendered).not.toContain('this directory');
         expect(rendered).not.toContain('Preferred route');
         expect(rendered).not.toContain('Optional MCP:');
     });

package/dist/print-command-tree.js

@@ -8,7 +8,13 @@ function silentIo() {
     };
 }
 function stubPackageInfo() {
-    return { name: '@ktx/cli', version: '0.0.0-docs', contextPackageName: '@ktx/context' };
+    return {
+        name: '@ktx/cli',
+        version: '0.0.0-docs',
+        packageVersion: '0.0.0-private',
+        runtimeVersion: '0.0.0-docs',
+        contextPackageName: '@ktx/context',
+    };
 }
 export function renderKtxCommandTree() {
     const program = buildKtxProgram({

package/dist/public-ingest.d.ts

@@ -3,7 +3,8 @@ import type { KtxProgressPort } from '@ktx/context/scan';
 import type { KtxCliIo } from './index.js';
 import type { KtxIngestArgs, KtxIngestDeps, KtxIngestProgressUpdate } from './ingest.js';
 import { type KtxDatabaseContextDepth } from './ingest-depth.js';
-import type { KtxManagedPythonInstallPolicy } from './managed-python-command.js';
+import { type KtxManagedPythonInstallPolicy, type ManagedPythonCommandRuntime } from './managed-python-command.js';
+import type { KtxRuntimeFeature } from './managed-python-runtime.js';
 import type { KtxScanArgs, KtxScanDeps } from './scan.js';
 type KtxPublicIngestStepName = 'database-schema' | 'query-history' | 'source-ingest' | 'memory-update';
 type KtxPublicIngestStepStatus = 'done' | 'skipped' | 'failed' | 'not-run';
@@ -75,6 +76,13 @@ export interface KtxPublicIngestDeps {
     }>;
     scanProgress?: KtxProgressPort;
     ingestProgress?: (update: KtxIngestProgressUpdate) => void;
+    ensureRuntime?: (options: {
+        cliVersion: string;
+        installPolicy: KtxManagedPythonInstallPolicy;
+        io: KtxCliIo;
+        feature: KtxRuntimeFeature;
+    }) => Promise<ManagedPythonCommandRuntime>;
+    env?: NodeJS.ProcessEnv;
     runtimeIo?: KtxCliIo;
     onPhaseStart?: (phaseKey: KtxPublicIngestPhaseKey) => void;
     onPhaseEnd?: (phaseKey: KtxPublicIngestPhaseKey, status: 'done' | 'failed' | 'skipped', summary?: string) => void;

package/dist/public-ingest.js

@@ -1,6 +1,8 @@
 import { loadKtxProject } from '@ktx/context/project';
 import { databaseContextDepth, deepReadinessGaps, isDatabaseDriver, normalizeConnectionDriver, } from './ingest-depth.js';
+import { ensureManagedPythonCommandRuntime, } from './managed-python-command.js';
 import { publicIngestOutputLine } from './public-ingest-copy.js';
+import { resolvePublicIngestRuntimeRequirements } from './runtime-requirements.js';
 import { profileMark } from './startup-profile.js';
 profileMark('module:public-ingest');
 const sourceAdapterByDriver = new Map([
@@ -304,6 +306,7 @@ function failureDetailWithRetry(input) {
 }
 function markTargetResult(target, args, status, failedOperation, failureDetail) {
     const selectedFailedOperation = failedOperation ?? (target.operation === 'database-ingest' ? 'database-schema' : 'source-ingest');
+    const selectedFailedOperationIndex = target.steps.indexOf(selectedFailedOperation);
     return {
         connectionId: target.connectionId,
         driver: target.driver,
@@ -314,6 +317,10 @@ function markTargetResult(target, args, status, failedOperation, failureDetail)
             if (status === 'done') {
                 return { ...step, status: 'done' };
             }
+            const stepIndex = target.steps.indexOf(step.operation);
+            if (selectedFailedOperationIndex >= 0 && stepIndex >= 0 && stepIndex < selectedFailedOperationIndex) {
+                return { ...step, status: 'done' };
+            }
             if (step.operation === selectedFailedOperation) {
                 return {
                     ...step,
@@ -386,15 +393,34 @@ function createCapturedPublicIngestIo() {
     };
 }
 const INTERNAL_STATUS_LINE_RE = /^(Report|Run|Job|Status|Adapter|Connection|Sync|Diff|Tasks|Work units|Failed tasks|Saved memory|Provenance rows):\s*/;
-function firstCapturedFailureLine(output) {
-    return output
+const ACTIONABLE_FAILURE_LINE_RE = /^(Missing bundled Python runtime manifest|KTX Python runtime is required|KTX managed daemon|Error:|Failed\b|Could not\b|Cannot\b)/;
+const RUNTIME_BACKED_RETRY_LINE_RE = /^Then retry the runtime-backed KTX command\.?$/;
+function trimErrorPrefix(line) {
+    return line.replace(/^Error:\s*/, '');
+}
+function capturedFailureMessage(output) {
+    const lines = output
         .split(/\r?\n/)
         .map((line) => line.trim())
         .filter((line) => line.length > 0)
         .filter((line) => !line.startsWith('KTX scan completed'))
         .filter((line) => !INTERNAL_STATUS_LINE_RE.test(line))
-        .map(publicIngestOutputLine)
-        .find((line) => line.length > 0);
+        .map(publicIngestOutputLine);
+    const actionableIndex = lines.findIndex((line) => ACTIONABLE_FAILURE_LINE_RE.test(line));
+    if (actionableIndex < 0) {
+        const line = lines.find((candidate) => candidate.length > 0);
+        return line ? trimErrorPrefix(line) : undefined;
+    }
+    const firstLine = lines[actionableIndex];
+    if (!firstLine?.startsWith('Missing bundled Python runtime manifest')) {
+        return trimErrorPrefix(firstLine);
+    }
+    const followupLines = lines
+        .slice(actionableIndex + 1)
+        .filter((line) => !RUNTIME_BACKED_RETRY_LINE_RE.test(line))
+        .filter((line) => !/\bRetry:\s/.test(line))
+        .filter((line) => line.startsWith('In a source checkout, build the local runtime assets with:'));
+    return [firstLine, ...followupLines].join('\n');
 }
 export async function executePublicIngestTarget(target, args, io, deps) {
     if (target.preflightFailure) {
@@ -445,7 +471,7 @@ export async function executePublicIngestTarget(target, args, io, deps) {
             if (target.queryHistory?.enabled === true) {
                 deps.onPhaseEnd?.('query-history', 'skipped');
             }
-            return markTargetResult(target, args, 'failed', 'database-schema', capturedScanIo ? firstCapturedFailureLine(capturedScanIo.capturedOutput()) : undefined);
+            return markTargetResult(target, args, 'failed', 'database-schema', capturedScanIo ? capturedFailureMessage(capturedScanIo.capturedOutput()) : undefined);
         }
         deps.onPhaseEnd?.('database-schema', 'done');
         if (target.queryHistory?.enabled === true) {
@@ -478,7 +504,7 @@ export async function executePublicIngestTarget(target, args, io, deps) {
                 : await runIngest(ingestArgs, ingestIo);
             if (qhExitCode !== 0) {
                 deps.onPhaseEnd?.('query-history', 'failed');
-                return markTargetResult(target, args, 'failed', 'query-history', capturedIngestIo ? firstCapturedFailureLine(capturedIngestIo.capturedOutput()) : undefined);
+                return markTargetResult(target, args, 'failed', 'query-history', capturedIngestIo ? capturedFailureMessage(capturedIngestIo.capturedOutput()) : undefined);
             }
             deps.onPhaseEnd?.('query-history', 'done');
         }
@@ -509,12 +535,29 @@ export async function executePublicIngestTarget(target, args, io, deps) {
         ? await runIngest(ingestArgs, ingestIo, ingestDeps)
         : await runIngest(ingestArgs, ingestIo);
     deps.onPhaseEnd?.('source-ingest', exitCode === 0 ? 'done' : 'failed');
-    return markTargetResult(target, args, exitCode === 0 ? 'done' : 'failed', 'source-ingest', capturedIngestIo ? firstCapturedFailureLine(capturedIngestIo.capturedOutput()) : undefined);
+    return markTargetResult(target, args, exitCode === 0 ? 'done' : 'failed', 'source-ingest', capturedIngestIo ? capturedFailureMessage(capturedIngestIo.capturedOutput()) : undefined);
 }
 export async function runKtxPublicIngest(args, io, deps = {}) {
     const loadProject = deps.loadProject ?? loadKtxProject;
     const project = await loadProject({ projectDir: args.projectDir });
     if (shouldUseForegroundContextBuildView(args, io)) {
+        const plan = buildPublicIngestPlan(project, args);
+        const requirements = resolvePublicIngestRuntimeRequirements(plan, { env: deps.env ?? process.env });
+        const ensureRuntime = deps.ensureRuntime ?? ensureManagedPythonCommandRuntime;
+        for (const feature of requirements.features) {
+            try {
+                await ensureRuntime({
+                    cliVersion: args.cliVersion ?? '0.0.0-private',
+                    installPolicy: args.runtimeInstallPolicy ?? 'prompt',
+                    io,
+                    feature,
+                });
+            }
+            catch (error) {
+                io.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+                return 1;
+            }
+        }
         const { runContextBuild } = await import('./context-build-view.js');
         const contextBuild = deps.runContextBuild ?? runContextBuild;
         const result = await contextBuild(project, {