@kaelio/ktx 0.4.0 → 0.5.0

package/dist/database-tree-picker.js

@@ -99,15 +99,39 @@ function schemasFromEnabledTables(enabledTables) {
     }
     return result;
 }
-export async function pickDatabaseScope(args, io, render = defaultRenderer) {
-    const { inputs, schemaIds, allTables } = buildTreeInputs(args.discovered);
+function schemaOptions(args) {
+    return args.schemas
+        .filter((schema) => !args.schemaSuggestion.excluded.has(schema))
+        .slice()
+        .sort((left, right) => {
+        const leftSuggested = args.schemaSuggestion.suggested.has(left);
+        const rightSuggested = args.schemaSuggestion.suggested.has(right);
+        if (leftSuggested !== rightSuggested)
+            return leftSuggested ? -1 : 1;
+        return left.localeCompare(right);
+    })
+        .map((schema) => ({
+        value: schema,
+        label: schema,
+        ...(args.schemaSuggestion.suggested.has(schema) ? { hint: 'suggested' } : {}),
+    }));
+}
+function initialStageOneSchemas(args) {
+    if (args.existing.enabledTables.length > 0) {
+        return schemasFromEnabledTables(args.existing.enabledTables);
+    }
+    return [...(args.initialSchemas ?? [])];
+}
+async function runStageTwoTreePicker(input) {
+    const { args, discovered, selectedSchemas, io, render } = input;
+    const { inputs, schemaIds, allTables } = buildTreeInputs(discovered);
     const tree = buildPickerTree(inputs);
     const byId = new Map(tree.map((node) => [node.id, node]));
     const tableCount = allTables.length;
     const schemaCount = schemaIds.length;
     const initialSelection = args.existing.enabledTables.length > 0
         ? initialSelectionForExisting(args.existing.enabledTables, byId)
-        : initialSelectionFromDefaults(args.defaultSchemas, schemaIds);
+        : initialSelectionFromDefaults(selectedSchemas, schemaIds);
     const initialState = buildInitialState({
         tree,
         existingSelectedIds: initialSelection,
@@ -132,3 +156,54 @@ export async function pickDatabaseScope(args, io, render = defaultRenderer) {
     const activeSchemas = args.supportsSchemaScope ? schemasFromEnabledTables(enabledTables) : [];
     return { kind: 'selected', activeSchemas, enabledTables };
 }
+export async function pickDatabaseScope(args, io, render = defaultRenderer) {
+    let selectedSchemas = initialStageOneSchemas(args);
+    while (true) {
+        const pickedSchemas = await args.prompts.autocompleteMultiselect({
+            message: `Choose ${args.schemaNounPlural} to enable for ${args.connectionId}\nType to filter. Space to select. Enter when done.`,
+            placeholder: `Search ${args.schemaNounPlural}`,
+            options: schemaOptions(args),
+            initialValues: selectedSchemas,
+            required: false,
+        });
+        if (pickedSchemas.includes('back')) {
+            return { kind: 'back' };
+        }
+        selectedSchemas = pickedSchemas;
+        if (selectedSchemas.length === 0) {
+            io.stderr.write(`Nothing selected - type to filter, or Escape to skip ${args.schemaNoun} scope.\n`);
+            continue;
+        }
+        const selectedNoun = selectedSchemas.length === 1 ? args.schemaNoun : args.schemaNounPlural;
+        const action = await args.prompts.select({
+            message: `Enable all tables in ${selectedSchemas.length} ${selectedNoun}, or refine tables?`,
+            options: [
+                { value: 'save', label: `Enable all tables in selected ${selectedNoun}` },
+                { value: 'refine', label: 'Refine: choose individual tables' },
+                { value: 'back', label: 'Back' },
+            ],
+        });
+        if (action === 'back') {
+            continue;
+        }
+        const discovered = await args.listTablesForSchemas(selectedSchemas);
+        if (action === 'save' && args.existing.enabledTables.length === 0) {
+            return {
+                kind: 'selected',
+                activeSchemas: args.supportsSchemaScope ? selectedSchemas : [],
+                enabledTables: discovered.map(qualifiedTableId),
+            };
+        }
+        const refined = await runStageTwoTreePicker({
+            args,
+            discovered,
+            selectedSchemas,
+            io,
+            render,
+        });
+        if (refined.kind === 'back') {
+            continue;
+        }
+        return refined;
+    }
+}

package/dist/database-tree-picker.test.js

@@ -5,8 +5,17 @@ function makeIo() {
     let stderr = '';
     return {
         io: {
-            stdout: { isTTY: true, write: (chunk) => { stdout += chunk; } },
-            stderr: { write: (chunk) => { stderr += chunk; } },
+            stdout: {
+                isTTY: true,
+                write: (chunk) => {
+                    stdout += chunk;
+                },
+            },
+            stderr: {
+                write: (chunk) => {
+                    stderr += chunk;
+                },
+            },
         },
         stdout: () => stdout,
         stderr: () => stderr,
@@ -34,22 +43,80 @@ const discovered = [
     { schema: 'public', name: 'events', kind: 'view' },
     { schema: 'public', name: 'sessions', kind: 'table' },
 ];
+function promptAdapter(overrides = {}) {
+    return {
+        autocompleteMultiselect: vi.fn(async () => ['analytics']),
+        select: vi.fn(async () => 'refine'),
+        ...overrides,
+    };
+}
 function baseArgs(overrides = {}) {
     return {
         connectionId: 'warehouse',
         schemaNoun: 'schema',
         schemaNounPlural: 'schemas',
-        discovered,
+        schemas: ['analytics', 'public'],
+        schemaSuggestion: { excluded: new Set(), suggested: new Set(['analytics']) },
         existing: { enabledTables: [] },
-        defaultSchemas: ['analytics'],
         supportsSchemaScope: true,
+        listTablesForSchemas: vi.fn(async () => discovered),
+        prompts: promptAdapter(),
         ...overrides,
     };
 }
 describe('pickDatabaseScope', () => {
+    it('starts Stage 1 with no checked schemas and does not enumerate tables before schema selection', async () => {
+        const prompts = promptAdapter({
+            autocompleteMultiselect: vi.fn(async () => ['analytics']),
+            select: vi.fn(async () => 'save'),
+        });
+        const listTablesForSchemas = vi.fn(async () => [
+            { schema: 'analytics', name: 'orders', kind: 'table' },
+        ]);
+        const result = await pickDatabaseScope(baseArgs({
+            connectionId: 'warehouse',
+            schemaNoun: 'dataset',
+            schemaNounPlural: 'datasets',
+            schemas: ['analytics', 'raw'],
+            schemaSuggestion: { excluded: new Set(['raw']), suggested: new Set(['analytics']) },
+            listTablesForSchemas,
+            prompts,
+        }), makeIo().io, captureRenderer().renderer);
+        expect(listTablesForSchemas).toHaveBeenCalledTimes(1);
+        expect(listTablesForSchemas).toHaveBeenCalledWith(['analytics']);
+        expect(result).toEqual({
+            kind: 'selected',
+            activeSchemas: ['analytics'],
+            enabledTables: ['analytics.orders'],
+        });
+    });
+    it('routes partial existing allowlists through Stage 2 so save preserves table selections', async () => {
+        const { renderer, setResult } = captureRenderer();
+        setResult({ kind: 'save', selectedIds: ['analytics.customers'] });
+        const prompts = promptAdapter({
+            autocompleteMultiselect: vi.fn(async () => ['analytics']),
+            select: vi.fn(async () => 'save'),
+        });
+        const listTablesForSchemas = vi.fn(async () => [
+            { schema: 'analytics', name: 'customers', kind: 'table' },
+            { schema: 'analytics', name: 'orders', kind: 'table' },
+        ]);
+        const result = await pickDatabaseScope(baseArgs({
+            schemas: ['analytics'],
+            schemaSuggestion: { excluded: new Set(), suggested: new Set(['analytics']) },
+            existing: { enabledTables: ['analytics.customers'] },
+            listTablesForSchemas,
+            prompts,
+        }), makeIo().io, renderer);
+        expect(result).toEqual({
+            kind: 'selected',
+            activeSchemas: ['analytics'],
+            enabledTables: ['analytics.customers'],
+        });
+    });
     it('builds a 2-level tree (schemas as parents, tables as children) and uses save-empty action', async () => {
         const { renderer, capture, setResult } = captureRenderer();
-        setResult({ kind: 'quit' });
+        setResult({ kind: 'save', selectedIds: ['analytics'] });
         await pickDatabaseScope(baseArgs(), makeIo().io, renderer);
         expect(capture.state?.skipEmptyAction).toBe('save-empty');
         const schemaIds = capture.state?.tree.filter((n) => n.parentId === null).map((n) => n.id);
@@ -63,21 +130,21 @@ describe('pickDatabaseScope', () => {
         ]);
         expect(capture.state?.byId.get('public.events')?.title).toBe('events (view)');
     });
-    it('pre-checks default schemas at the parent level when no existing selection', async () => {
+    it('pre-checks selected schemas at the parent level when no existing selection reaches Stage 2', async () => {
         const { renderer, capture, setResult } = captureRenderer();
-        setResult({ kind: 'quit' });
-        await pickDatabaseScope(baseArgs({ defaultSchemas: ['analytics'] }), makeIo().io, renderer);
+        setResult({ kind: 'save', selectedIds: ['analytics'] });
+        await pickDatabaseScope(baseArgs(), makeIo().io, renderer);
         expect([...(capture.state?.checked ?? [])]).toEqual(['analytics']);
     });
     it('collapses an existing full-schema selection back into the parent check', async () => {
         const { renderer, capture, setResult } = captureRenderer();
-        setResult({ kind: 'quit' });
+        setResult({ kind: 'save', selectedIds: ['analytics'] });
         await pickDatabaseScope(baseArgs({ existing: { enabledTables: ['analytics.customers', 'analytics.orders'] } }), makeIo().io, renderer);
         expect([...(capture.state?.checked ?? [])]).toEqual(['analytics']);
     });
     it('keeps a partial existing selection at the leaf level', async () => {
         const { renderer, capture, setResult } = captureRenderer();
-        setResult({ kind: 'quit' });
+        setResult({ kind: 'save', selectedIds: ['analytics.customers'] });
         await pickDatabaseScope(baseArgs({ existing: { enabledTables: ['analytics.customers'] } }), makeIo().io, renderer);
         expect([...(capture.state?.checked ?? [])]).toEqual(['analytics.customers']);
     });
@@ -101,21 +168,6 @@ describe('pickDatabaseScope', () => {
             enabledTables: ['analytics.customers', 'analytics.orders', 'public.events'],
         });
     });
-    it('treats empty save as enable-all', async () => {
-        const { renderer, setResult } = captureRenderer();
-        setResult({ kind: 'save', selectedIds: [] });
-        const result = await pickDatabaseScope(baseArgs(), makeIo().io, renderer);
-        expect(result).toEqual({
-            kind: 'selected',
-            activeSchemas: ['analytics', 'public'],
-            enabledTables: [
-                'analytics.customers',
-                'analytics.orders',
-                'public.events',
-                'public.sessions',
-            ],
-        });
-    });
     it('omits activeSchemas when the driver does not support a schema scope', async () => {
         const { renderer, setResult } = captureRenderer();
         setResult({ kind: 'save', selectedIds: ['analytics'] });
@@ -126,10 +178,11 @@ describe('pickDatabaseScope', () => {
             enabledTables: ['analytics.customers', 'analytics.orders'],
         });
     });
-    it('returns back when the picker quits', async () => {
-        const { renderer, setResult } = captureRenderer();
-        setResult({ kind: 'quit' });
-        const result = await pickDatabaseScope(baseArgs(), makeIo().io, renderer);
+    it('returns back when Stage 1 is cancelled', async () => {
+        const prompts = promptAdapter({
+            autocompleteMultiselect: vi.fn(async () => ['back']),
+        });
+        const result = await pickDatabaseScope(baseArgs({ prompts }), makeIo().io, captureRenderer().renderer);
         expect(result).toEqual({ kind: 'back' });
     });
 });

package/dist/demo-assets.d.ts

@@ -1,3 +1,4 @@
+import { type KtxCliIo } from './cli-runtime.js';
 interface DemoProjectResult {
     projectDir: string;
     configPath: string;
@@ -7,11 +8,17 @@ interface DemoProjectResult {
 interface EnsureDemoProjectOptions {
     projectDir: string;
     force: boolean;
+    io?: KtxCliIo;
+    cliVersion?: string;
 }
+/** @internal */
 export declare const DEMO_CONNECTION_ID = "orbit_demo";
+/** @internal */
 export declare const DEMO_ADAPTER = "live-database";
+/** @internal */
 export declare const DEMO_REPLAY_FILE = "replay.memory-flow.v1.json";
 export declare function defaultDemoProjectDir(): string;
+/** @internal */
 export declare function ensureDemoProject(options: EnsureDemoProjectOptions): Promise<DemoProjectResult>;
 export declare function ensureSeededDemoProject(options: EnsureDemoProjectOptions): Promise<DemoProjectResult>;
 export {};

package/dist/demo-assets.js

@@ -4,8 +4,12 @@ import { tmpdir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { randomBytes } from 'node:crypto';
+import { getKtxCliPackageInfo } from './cli-runtime.js';
+/** @internal */
 export const DEMO_CONNECTION_ID = 'orbit_demo';
+/** @internal */
 export const DEMO_ADAPTER = 'live-database';
+/** @internal */
 export const DEMO_REPLAY_FILE = 'replay.memory-flow.v1.json';
 const REQUIRED_PACKAGED_BASE_ASSET_PATHS = ['demo.db', 'manifest.json', DEMO_REPLAY_FILE];
 const REQUIRED_SEEDED_ASSET_PATHS = [
@@ -93,6 +97,7 @@ async function assertPackagedSeededAssetsPresent() {
         throw new Error(`Packaged seeded demo assets are incomplete: missing ${missing.join(', ')}`);
     }
 }
+/** @internal */
 export async function ensureDemoProject(options) {
     const projectDir = resolve(options.projectDir);
     const configPath = join(projectDir, 'ktx.yaml');
@@ -113,6 +118,19 @@ export async function ensureDemoProject(options) {
     await copyFile(join(assetDir(), 'manifest.json'), join(projectDir, 'manifest.json'));
     const replayPath = await copyPackagedReplay(projectDir);
     await writeFile(configPath, demoConfig(databasePath), 'utf-8');
+    if (options.io) {
+        const { emitTelemetryEvent } = await import('./telemetry/index.js');
+        await emitTelemetryEvent({
+            name: 'connection_added',
+            projectDir,
+            io: options.io,
+            packageInfo: { ...getKtxCliPackageInfo(), version: options.cliVersion ?? getKtxCliPackageInfo().version },
+            fields: {
+                driver: 'sqlite',
+                isDemoConnection: true,
+            },
+        });
+    }
     return { projectDir, configPath, databasePath, replayPath };
 }
 async function copyDirIfExists(src, dest) {

package/dist/demo-assets.test.js

@@ -2,7 +2,7 @@ import { access, readFile, rm, stat } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { afterEach, describe, expect, it } from 'vitest';
+import { afterEach, describe, expect, it, vi } from 'vitest';
 import { DEMO_ADAPTER, DEMO_CONNECTION_ID, DEMO_REPLAY_FILE, defaultDemoProjectDir, ensureDemoProject, ensureSeededDemoProject, } from './demo-assets.js';
 const packagedDemoSource = 'packaged-orbit-demo';
 function packagedDemoAssetPath(relativePath) {
@@ -11,9 +11,25 @@ function packagedDemoAssetPath(relativePath) {
 async function readPackagedJson(relativePath) {
     return JSON.parse(await readFile(packagedDemoAssetPath(relativePath), 'utf-8'));
 }
+function makeIo() {
+    let stderr = '';
+    return {
+        stdout: {
+            isTTY: true,
+            write() { },
+        },
+        stderr: {
+            write(chunk) {
+                stderr += chunk;
+            },
+        },
+        stderrText: () => stderr,
+    };
+}
 describe('demo assets', () => {
     const projectDir = join(tmpdir(), `ktx-demo-assets-${process.pid}`);
     afterEach(async () => {
+        vi.unstubAllEnvs();
         await rm(projectDir, { recursive: true, force: true });
     });
     it('resolves the default demo root under the OS temp directory', () => {
@@ -85,6 +101,16 @@ describe('demo assets', () => {
         await expect(ensureDemoProject({ projectDir, force: false })).rejects.toThrow('Demo project already exists');
         await expect(ensureDemoProject({ projectDir, force: true })).resolves.toMatchObject({ projectDir });
     });
+    it('emits debug telemetry when the demo connection is created', async () => {
+        vi.stubEnv('KTX_TELEMETRY_DEBUG', '1');
+        vi.stubEnv('CI', '');
+        const io = makeIo();
+        await ensureDemoProject({ projectDir, force: false, io, cliVersion: '0.2.0' });
+        expect(io.stderrText()).toContain('"event":"connection_added"');
+        expect(io.stderrText()).toContain('"driver":"sqlite"');
+        expect(io.stderrText()).toContain('"isDemoConnection":true');
+        expect(io.stderrText()).not.toContain(projectDir);
+    });
     it('copies the seeded project assets used by the setup wizard tour', async () => {
         await ensureSeededDemoProject({ projectDir, force: false });
         await expect(access(join(projectDir, 'semantic-layer', 'dbt-main', 'mart_arr_daily.yaml'))).resolves.toBeUndefined();

package/dist/demo-metrics.d.ts

@@ -1,4 +1,4 @@
-import type { MemoryFlowReplayInput } from '@ktx/context/ingest/memory-flow';
+import type { MemoryFlowReplayInput } from './context/ingest/memory-flow/types.js';
 interface DemoMetricsTuning {
     inputTokensPerStep?: number;
     outputTokensPerStep?: number;
@@ -27,9 +27,13 @@ export declare function buildDemoMetrics(input: MemoryFlowReplayInput, options?:
     tuning?: DemoMetricsTuning;
 }): DemoMetricsSnapshot;
 export declare function formatDuration(ms: number): string;
+/** @internal */
 export declare function formatEta(ms: number | null, status: MemoryFlowReplayInput['status']): string;
 export declare function formatCost(usd: number): string;
+/** @internal */
 export declare function formatTokens(n: number): string;
+/** @internal */
 export declare function formatTokensPerSec(n: number): string;
+/** @internal */
 export declare function progressBar(ratio: number, width?: number): string;
 export {};

package/dist/demo-metrics.js

@@ -91,6 +91,7 @@ export function formatDuration(ms) {
     const hr = Math.floor(min / 60);
     return `${hr}h${(min % 60).toString().padStart(2, '0')}m`;
 }
+/** @internal */
 export function formatEta(ms, status) {
     if (status !== 'running')
         return 'done';
@@ -107,6 +108,7 @@ export function formatCost(usd) {
         return `$${usd.toFixed(3)}`;
     return `$${usd.toFixed(2)}`;
 }
+/** @internal */
 export function formatTokens(n) {
     if (!Number.isFinite(n) || n <= 0)
         return '0';
@@ -116,6 +118,7 @@ export function formatTokens(n) {
         return `${(n / 1000).toFixed(1)}K`;
     return `${(n / 1_000_000).toFixed(2)}M`;
 }
+/** @internal */
 export function formatTokensPerSec(n) {
     if (!Number.isFinite(n) || n <= 0)
         return '0/s';
@@ -124,6 +127,7 @@ export function formatTokensPerSec(n) {
     return `${(n / 1000).toFixed(1)}K/s`;
 }
 const PROGRESS_BAR_WIDTH = 12;
+/** @internal */
 export function progressBar(ratio, width = PROGRESS_BAR_WIDTH) {
     const clamped = Math.max(0, Math.min(1, ratio));
     const filled = Math.round(clamped * width);

package/dist/doctor.d.ts

@@ -1,4 +1,4 @@
-import type { KtxConfigIssue } from '@ktx/context/project';
+import type { KtxConfigIssue } from './context/project/config.js';
 import type { BuildProjectStatusOptions } from './status-project.js';
 type DoctorStatus = 'pass' | 'warn' | 'fail';
 type KtxDoctorOutputMode = 'plain' | 'json';
@@ -27,6 +27,7 @@ export type KtxDoctorArgs = {
     outputMode: KtxDoctorOutputMode;
     inputMode?: KtxDoctorInputMode;
     verbose?: boolean;
+    fast?: boolean;
 } | {
     command: 'validate';
     projectDir: string;

package/dist/doctor.js

@@ -401,7 +401,8 @@ export async function runKtxDoctor(args, io = process, deps = {}) {
                 renderMissingProjectMessage(args.projectDir, args.outputMode, io);
                 return 1;
             }
-            const { validateKtxProjectConfig } = await import('@ktx/context/project');
+            const { validateKtxProjectConfig } = await import('./context/project/config.js');
+            ;
             const rawConfig = await readFile(configPath, 'utf-8');
             const validation = validateKtxProjectConfig(rawConfig);
             if (!validation.ok) {
@@ -417,7 +418,9 @@ export async function runKtxDoctor(args, io = process, deps = {}) {
                 renderMissingProjectMessage(args.projectDir, args.outputMode, io);
                 return 1;
             }
-            const { loadKtxProject, validateKtxProjectConfig } = await import('@ktx/context/project');
+            const { loadKtxProject } = await import('./context/project/project.js');
+            const { validateKtxProjectConfig } = await import('./context/project/config.js');
+            ;
             const { buildProjectStatus, renderProjectStatus } = await import('./status-project.js');
             const rawConfig = await readFile(configPath, 'utf-8');
             const validation = validateKtxProjectConfig(rawConfig);
@@ -426,7 +429,14 @@ export async function runKtxDoctor(args, io = process, deps = {}) {
                 return 1;
             }
             const project = await loadKtxProject({ projectDir: args.projectDir });
-            const projectStatus = await buildProjectStatus(project, { ...deps, configIssues: validation.issues });
+            const fast = args.fast ?? false;
+            const useSpinner = !fast && args.outputMode === 'plain' && io.stdout.isTTY === true;
+            const projectStatus = await buildProjectStatus(project, {
+                ...deps,
+                configIssues: validation.issues,
+                fast,
+                useSpinner,
+            });
             const verbose = args.verbose ?? false;
             const toolchainChecks = verbose ? await runSetupChecks() : undefined;
             if (args.outputMode === 'json') {

package/dist/doctor.test.js

@@ -95,7 +95,7 @@ describe('runSetupDoctorChecks', () => {
                 if (command === 'uv' && args[0] === '--version')
                     return 'uv 0.9.5';
                 if (command === process.execPath && args.includes('--version'))
-                    return '@ktx/cli 0.0.0-private';
+                    return '@kaelio/ktx 0.0.0-private';
                 throw new Error(`${command} ${args.join(' ')}`);
             },
             pathExists: async () => true,
@@ -152,7 +152,7 @@ describe('runSetupDoctorChecks', () => {
                 if (command === 'uv' && args[0] === '--version')
                     return 'uv 0.9.5';
                 if (command === process.execPath && args.includes('--version'))
-                    return '@ktx/cli 0.0.0-private';
+                    return '@kaelio/ktx 0.0.0-private';
                 throw new Error(`${command} ${args.join(' ')}`);
             },
             pathExists: async () => true,
@@ -276,7 +276,7 @@ describe('runKtxDoctor', () => {
         expect(out).toContain('KTX status');
         expect(out).toContain('Config');
         expect(out).toContain('Unsupported storrage: unknown field');
-        expect(out).toContain('Unsupported ingest.llm: use top-level llm.provider');
+        expect(out).toContain('Unsupported ingest.llm: unknown field');
         expect(out).toContain('ktx.yaml');
     });
     it('emits structured JSON when ktx.yaml fails Zod validation', async () => {
@@ -444,11 +444,6 @@ describe('runKtxDoctor', () => {
             '    driver: postgres',
             '    url: env:WAREHOUSE_DATABASE_URL',
             '    readonly: true',
-            '    historicSql:',
-            '      enabled: true',
-            '      dialect: postgres',
-            '      windowDays: 30',
-            '      concurrency: 4',
             '  local:',
             '    driver: sqlite',
             '    file_path: ./warehouse.db',
@@ -476,8 +471,6 @@ describe('runKtxDoctor', () => {
         const out = testIo.stdout();
         expect(out).toContain('Warnings');
         expect(out).toContain('connections.warehouse.readonly is no longer used.');
-        expect(out).toContain('connections.warehouse.historicSql.concurrency is no longer used.');
-        expect(out).toContain('connections.warehouse.historicSql.windowDays does not constrain pg_stat_statements.');
         expect(out).toContain('connections.local.file_path was removed.');
         expect(out).toContain('connections.docs.last_successful_cursor is local sync state.');
         delete process.env.ANTHROPIC_API_KEY;
@@ -559,7 +552,7 @@ describe('runKtxDoctor', () => {
             await expect(runKtxDoctor({ command: 'validate', projectDir: tempDir, outputMode: 'plain', inputMode: 'disabled' }, testIo.io, {})).resolves.toBe(1);
             const out = testIo.stdout();
             expect(out).toContain('Unsupported storrage: unknown field');
-            expect(out).toContain('Unsupported ingest.llm: use top-level llm.provider');
+            expect(out).toContain('Unsupported ingest.llm: unknown field');
         });
         it('emits structured JSON issues when validation fails', async () => {
             await writeFile(join(tempDir, 'ktx.yaml'), ['storrage: {}', ''].join('\n'), 'utf-8');

package/dist/embedding-resolution.d.ts

@@ -0,0 +1,37 @@
+import type { KtxEmbeddingProvider } from './llm/types.js';
+import { createKtxEmbeddingProvider as defaultCreateKtxEmbeddingProvider } from './llm/embedding-provider.js';
+import type { KtxLocalProject } from './context/project/project.js';
+import type { KtxCliIo } from './cli-runtime.js';
+import { ensureManagedLocalEmbeddingsDaemon as defaultEnsureManagedDaemon, tryUseManagedLocalEmbeddingsDaemon as defaultTryUseManagedDaemon } from './managed-local-embeddings.js';
+import type { KtxManagedPythonInstallPolicy } from './managed-python-command.js';
+type EmbeddingResolutionMode = 'ensure' | 'use-if-running';
+export type EmbeddingProviderResolution = {
+    kind: 'disabled';
+} | {
+    kind: 'configured';
+    provider: KtxEmbeddingProvider;
+    baseUrl: string;
+} | {
+    kind: 'managed-running';
+    provider: KtxEmbeddingProvider;
+    baseUrl: string;
+} | {
+    kind: 'managed-started';
+    provider: KtxEmbeddingProvider;
+    baseUrl: string;
+} | {
+    kind: 'managed-unavailable';
+    reason: string;
+};
+export interface ResolveProjectEmbeddingProviderOptions {
+    mode: EmbeddingResolutionMode;
+    cliVersion: string;
+    io: KtxCliIo;
+    /** Required when mode === 'ensure'. */
+    installPolicy?: KtxManagedPythonInstallPolicy;
+    tryUseManagedDaemon?: typeof defaultTryUseManagedDaemon;
+    ensureManagedDaemon?: typeof defaultEnsureManagedDaemon;
+    createKtxEmbeddingProvider?: typeof defaultCreateKtxEmbeddingProvider;
+}
+export declare function resolveProjectEmbeddingProvider(project: KtxLocalProject, options: ResolveProjectEmbeddingProviderOptions): Promise<EmbeddingProviderResolution>;
+export {};

package/dist/embedding-resolution.js

@@ -0,0 +1,63 @@
+import { createKtxEmbeddingProvider as defaultCreateKtxEmbeddingProvider } from './llm/embedding-provider.js';
+import { resolveLocalKtxEmbeddingConfig } from './context/llm/local-config.js';
+import { ensureManagedLocalEmbeddingsDaemon as defaultEnsureManagedDaemon, tryUseManagedLocalEmbeddingsDaemon as defaultTryUseManagedDaemon, } from './managed-local-embeddings.js';
+function usesManagedDaemon(embeddings) {
+    if (embeddings.backend !== 'sentence-transformers') {
+        return false;
+    }
+    const baseUrl = embeddings.sentenceTransformers?.base_url;
+    return baseUrl === undefined || baseUrl === '';
+}
+export async function resolveProjectEmbeddingProvider(project, options) {
+    const embeddings = project.config.ingest.embeddings;
+    if (embeddings.backend === 'none') {
+        return { kind: 'disabled' };
+    }
+    const createProvider = options.createKtxEmbeddingProvider ?? defaultCreateKtxEmbeddingProvider;
+    if (!usesManagedDaemon(embeddings)) {
+        const resolved = resolveLocalKtxEmbeddingConfig(embeddings, process.env);
+        if (!resolved) {
+            return { kind: 'managed-unavailable', reason: 'embedding config missing required fields' };
+        }
+        const provider = createProvider(resolved);
+        const baseUrl = embeddings.sentenceTransformers?.base_url ?? '';
+        return { kind: 'configured', provider, baseUrl };
+    }
+    const tryUse = options.tryUseManagedDaemon ?? defaultTryUseManagedDaemon;
+    const running = await tryUse({ cliVersion: options.cliVersion, projectDir: project.projectDir });
+    if (running) {
+        const provider = buildManagedProvider(embeddings, running.baseUrl, createProvider);
+        return provider
+            ? { kind: 'managed-running', provider, baseUrl: running.baseUrl }
+            : { kind: 'managed-unavailable', reason: 'failed to build embedding provider from running daemon' };
+    }
+    if (options.mode === 'use-if-running') {
+        return { kind: 'managed-unavailable', reason: 'managed embeddings daemon is not running' };
+    }
+    const ensure = options.ensureManagedDaemon ?? defaultEnsureManagedDaemon;
+    if (!options.installPolicy) {
+        throw new Error("installPolicy is required when mode === 'ensure'");
+    }
+    const daemon = await ensure({
+        cliVersion: options.cliVersion,
+        projectDir: project.projectDir,
+        installPolicy: options.installPolicy,
+        io: options.io,
+    });
+    const provider = buildManagedProvider(embeddings, daemon.baseUrl, createProvider);
+    return provider
+        ? { kind: 'managed-started', provider, baseUrl: daemon.baseUrl }
+        : { kind: 'managed-unavailable', reason: 'failed to build embedding provider after starting daemon' };
+}
+function buildManagedProvider(embeddings, baseUrl, createProvider) {
+    const merged = {
+        ...embeddings,
+        sentenceTransformers: {
+            ...embeddings.sentenceTransformers,
+            base_url: baseUrl,
+            pathPrefix: '',
+        },
+    };
+    const resolved = resolveLocalKtxEmbeddingConfig(merged, process.env);
+    return resolved ? createProvider(resolved) : null;
+}