@kaelio/ktx 0.0.0 → 0.1.0-rc.0

package/dist/doctor.js

@@ -0,0 +1,272 @@
+import { execFile } from 'node:child_process';
+import { constants as fsConstants } from 'node:fs';
+import { access } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+function workspaceRootDir() {
+    return resolve(fileURLToPath(new URL('../../../', import.meta.url)));
+}
+async function defaultExecText(command, args, options = {}) {
+    const result = await execFileAsync(command, args, {
+        cwd: options.cwd,
+        env: options.env,
+        encoding: 'utf8',
+        maxBuffer: 1024 * 1024,
+    });
+    return `${result.stdout}${result.stderr}`.trim();
+}
+async function defaultPathExists(path) {
+    try {
+        await access(path, fsConstants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function failureMessage(error) {
+    if (error instanceof Error && error.message.trim().length > 0) {
+        return error.message.trim().split('\n')[0] ?? error.message.trim();
+    }
+    return String(error);
+}
+function parseVersion(value) {
+    const match = value.match(/(\d+)\.(\d+)\.(\d+)/);
+    if (!match) {
+        return [];
+    }
+    return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+function versionAtLeast(value, minimum) {
+    const parsed = parseVersion(value);
+    if (parsed.length !== 3) {
+        return false;
+    }
+    for (let index = 0; index < minimum.length; index += 1) {
+        if (parsed[index] > minimum[index])
+            return true;
+        if (parsed[index] < minimum[index])
+            return false;
+    }
+    return true;
+}
+function check(status, id, label, detail, fix) {
+    return fix ? { id, label, status, detail, fix } : { id, label, status, detail };
+}
+const SEMANTIC_SEARCH_HEALTH_TEXT = 'KTX semantic search doctor probe';
+const SEMANTIC_SEARCH_HEALTH_TIMEOUT_MS = 5_000;
+const SEMANTIC_SEARCH_LOCAL_HEALTH_TIMEOUT_MS = 120_000;
+function semanticEmbeddingSetupFix(projectDir, backend) {
+    if (backend === 'openai') {
+        return `Set OPENAI_API_KEY or rerun: ktx setup --project-dir ${projectDir} --embedding-backend openai --no-input`;
+    }
+    return `Run: ktx setup --project-dir ${projectDir} --no-input`;
+}
+function embeddingConfigLabel(config) {
+    const model = config.model?.trim() || 'model not configured';
+    return `${config.backend}/${model} (${config.dimensions}d)`;
+}
+function semanticLaneFallbackDetail(reason) {
+    return `${reason}. Semantic lane will be skipped; lexical, dictionary, and token lanes remain available.`;
+}
+async function defaultEmbeddingHealthCheck(config, options) {
+    const { runKtxEmbeddingHealthCheck } = await import('@ktx/llm');
+    return runKtxEmbeddingHealthCheck(config, options);
+}
+async function runSemanticSearchEmbeddingCheck(config, projectDir, deps = {}) {
+    if (config.backend === 'none' || config.backend === 'deterministic') {
+        return check('warn', 'semantic-search-embeddings', 'Semantic search embeddings', semanticLaneFallbackDetail(`ingest.embeddings.backend is ${config.backend}`), semanticEmbeddingSetupFix(projectDir, config.backend));
+    }
+    try {
+        const { resolveLocalKtxEmbeddingConfig } = await import('@ktx/context');
+        const resolved = resolveLocalKtxEmbeddingConfig(config, deps.env ?? process.env);
+        if (!resolved) {
+            return check('warn', 'semantic-search-embeddings', 'Semantic search embeddings', semanticLaneFallbackDetail(`No runtime embedding config resolved for ${embeddingConfigLabel(config)}`), semanticEmbeddingSetupFix(projectDir, config.backend));
+        }
+        const healthCheck = deps.embeddingHealthCheck ?? defaultEmbeddingHealthCheck;
+        const timeoutMs = deps.embeddingProbeTimeoutMs ??
+            (resolved.backend === 'sentence-transformers'
+                ? SEMANTIC_SEARCH_LOCAL_HEALTH_TIMEOUT_MS
+                : SEMANTIC_SEARCH_HEALTH_TIMEOUT_MS);
+        const health = await healthCheck(resolved, {
+            text: SEMANTIC_SEARCH_HEALTH_TEXT,
+            timeoutMs,
+        });
+        if (health.ok) {
+            return check('pass', 'semantic-search-embeddings', 'Semantic search embeddings', `${embeddingConfigLabel(resolved)} probe succeeded`);
+        }
+        return check('warn', 'semantic-search-embeddings', 'Semantic search embeddings', semanticLaneFallbackDetail(`${embeddingConfigLabel(resolved)} probe failed: ${health.message}`), semanticEmbeddingSetupFix(projectDir, config.backend));
+    }
+    catch (error) {
+        return check('warn', 'semantic-search-embeddings', 'Semantic search embeddings', semanticLaneFallbackDetail(`${embeddingConfigLabel(config)} probe failed: ${failureMessage(error)}`), semanticEmbeddingSetupFix(projectDir, config.backend));
+    }
+}
+export async function runSetupDoctorChecks(deps = {}) {
+    const env = deps.env ?? process.env;
+    const root = deps.workspaceRoot ?? workspaceRootDir();
+    const execText = deps.execText ?? defaultExecText;
+    const pathExists = deps.pathExists ?? defaultPathExists;
+    const importBetterSqlite3 = deps.importBetterSqlite3 ?? (() => import('better-sqlite3'));
+    const checks = [];
+    const nodeDetail = `${process.version} ABI ${process.versions.modules}`;
+    checks.push(versionAtLeast(process.version, [22, 0, 0])
+        ? check('pass', 'node', 'Node 22+', nodeDetail)
+        : check('fail', 'node', 'Node 22+', nodeDetail, 'Install Node 22 or newer, then rerun `pnpm run setup:dev`'));
+    try {
+        const pnpmVersion = await execText('pnpm', ['--version'], { cwd: root, env });
+        checks.push(versionAtLeast(pnpmVersion, [10, 20, 0])
+            ? check('pass', 'pnpm', 'pnpm 10.20+', pnpmVersion)
+            : check('fail', 'pnpm', 'pnpm 10.20+', pnpmVersion, 'Run: corepack enable && corepack prepare pnpm@10.28.0 --activate'));
+    }
+    catch (error) {
+        checks.push(check('fail', 'pnpm', 'pnpm 10.20+', failureMessage(error), 'Run: corepack enable && corepack prepare pnpm@10.28.0 --activate'));
+    }
+    try {
+        const corepackVersion = await execText('corepack', ['--version'], { cwd: root, env });
+        checks.push(check('pass', 'corepack', 'Corepack', corepackVersion));
+    }
+    catch (error) {
+        checks.push(check('warn', 'corepack', 'Corepack', failureMessage(error), 'Run: corepack enable'));
+    }
+    try {
+        const uvVersion = await execText('uv', ['--version'], { cwd: root, env });
+        checks.push(check('pass', 'uv', 'uv', uvVersion));
+    }
+    catch (error) {
+        checks.push(check('fail', 'uv', 'uv', failureMessage(error), 'Install uv, then rerun `pnpm run setup:dev`'));
+    }
+    try {
+        await importBetterSqlite3();
+        checks.push(check('pass', 'native-sqlite', 'Native SQLite', 'better-sqlite3 loaded'));
+    }
+    catch (error) {
+        checks.push(check('fail', 'native-sqlite', 'Native SQLite', failureMessage(error), 'Run: pnpm run native:rebuild'));
+    }
+    const cliBin = join(root, 'packages/cli/dist/bin.js');
+    if (await pathExists(cliBin)) {
+        checks.push(check('pass', 'package-build', 'TypeScript package build', 'packages/cli/dist/bin.js exists'));
+    }
+    else {
+        checks.push(check('fail', 'package-build', 'TypeScript package build', 'Missing packages/cli/dist/bin.js', 'Run: pnpm run build'));
+    }
+    try {
+        const output = await execText(process.execPath, [cliBin, '--version'], { cwd: root, env });
+        checks.push(check('pass', 'workspace-cli', 'Workspace-local CLI', output));
+    }
+    catch (error) {
+        checks.push(check('fail', 'workspace-cli', 'Workspace-local CLI', failureMessage(error), 'Run: pnpm run build && pnpm run ktx -- --version'));
+    }
+    return checks;
+}
+async function runProjectChecks(projectDir, deps = {}) {
+    const { loadKtxProject } = await import('@ktx/context/project');
+    const checks = [];
+    try {
+        const project = await loadKtxProject({ projectDir });
+        checks.push(check('pass', 'project-config', 'Project config', project.config.project));
+        const connectionCount = Object.keys(project.config.connections).length;
+        checks.push(connectionCount > 0
+            ? check('pass', 'connections', 'Connections', `${connectionCount} configured`)
+            : check('warn', 'connections', 'Connections', '0 configured', 'Add a connection to ktx.yaml or run `ktx setup demo init`'));
+        checks.push(check('pass', 'storage', 'Storage', `${project.config.storage.state}/${project.config.storage.search}`));
+        checks.push(check('pass', 'llm-provider', 'LLM provider', project.config.llm.provider.backend));
+        checks.push(await runSemanticSearchEmbeddingCheck(project.config.ingest.embeddings, projectDir, deps));
+        const runHistoricSqlDoctorChecks = deps.runHistoricSqlDoctorChecks ?? (await import('./historic-sql-doctor.js')).runPostgresHistoricSqlDoctorChecks;
+        checks.push(...(await runHistoricSqlDoctorChecks(project, deps)));
+    }
+    catch (error) {
+        checks.push(check('fail', 'project-config', 'Project config', failureMessage(error), `Run: ktx init ${projectDir} --name <project-name>`));
+    }
+    return checks;
+}
+async function runDemoProjectChecks(projectDir, deps = {}) {
+    const env = deps.env ?? process.env;
+    const { DEMO_CONNECTION_ID, DEMO_REPLAY_FILE } = await import('./demo-assets.js');
+    const { loadKtxProject } = await import('@ktx/context/project');
+    const checks = [];
+    const requiredPaths = [
+        ['demo-config', 'Demo config', 'ktx.yaml'],
+        ['demo-database', 'Demo dataset', 'demo.db'],
+        ['demo-state', 'Demo state database', 'state.sqlite'],
+        ['demo-replay', 'Demo replay', join('replays', DEMO_REPLAY_FILE)],
+        ['demo-raw-sources', 'Demo raw sources directory', 'raw-sources'],
+        ['demo-semantic-layer', 'Demo semantic-layer directory', 'semantic-layer'],
+        ['demo-knowledge', 'Demo knowledge directory', 'knowledge'],
+    ];
+    for (const [id, label, relativePath] of requiredPaths) {
+        const absolutePath = join(projectDir, relativePath);
+        checks.push((await defaultPathExists(absolutePath))
+            ? check('pass', id, label, relativePath)
+            : check('fail', id, label, `Missing ${relativePath}`, `Run: ktx setup demo init --project-dir ${projectDir} --force --no-input`));
+    }
+    try {
+        const project = await loadKtxProject({ projectDir });
+        const connection = project.config.connections[DEMO_CONNECTION_ID];
+        checks.push(connection?.driver === 'sqlite'
+            ? check('pass', 'demo-connection', 'Demo connection', `${DEMO_CONNECTION_ID} uses sqlite`)
+            : check('fail', 'demo-connection', 'Demo connection', `${DEMO_CONNECTION_ID} is missing or is not sqlite`, `Run: ktx setup demo init --project-dir ${projectDir} --force --no-input`));
+        const provider = project.config.llm.provider.backend;
+        checks.push(provider === 'anthropic' || provider === 'vertex' || provider === 'gateway'
+            ? check('pass', 'demo-llm-provider', 'Demo LLM provider', provider)
+            : check('fail', 'demo-llm-provider', 'Demo LLM provider', provider, `Run: ktx setup demo init --project-dir ${projectDir} --force --no-input`));
+        if (provider === 'anthropic' && !env.ANTHROPIC_API_KEY) {
+            checks.push(check('warn', 'anthropic-credentials', 'Anthropic credentials', 'ANTHROPIC_API_KEY is not set', 'Export ANTHROPIC_API_KEY to run `ktx setup demo --mode full --no-input`'));
+        }
+        else {
+            checks.push(check('pass', 'anthropic-credentials', 'Anthropic credentials', 'Configured for current provider'));
+        }
+        checks.push(await runSemanticSearchEmbeddingCheck(project.config.ingest.embeddings, projectDir, deps));
+        const runHistoricSqlDoctorChecks = deps.runHistoricSqlDoctorChecks ?? (await import('./historic-sql-doctor.js')).runPostgresHistoricSqlDoctorChecks;
+        checks.push(...(await runHistoricSqlDoctorChecks(project, deps)));
+    }
+    catch (error) {
+        checks.push(check('fail', 'demo-config-parse', 'Demo config parse', failureMessage(error), `Run: ktx setup demo init --project-dir ${projectDir} --force --no-input`));
+    }
+    return checks;
+}
+export function formatDoctorReport(report) {
+    const lines = [report.title];
+    for (const item of report.checks) {
+        lines.push(`${item.status.toUpperCase()} ${item.label}: ${item.detail}`);
+        if (item.fix) {
+            lines.push(`     Fix: ${item.fix}`);
+        }
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+function hasFailures(report) {
+    return report.checks.some((item) => item.status === 'fail');
+}
+function writeReport(report, outputMode, io) {
+    if (outputMode === 'json') {
+        io.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+        return;
+    }
+    io.stdout.write(formatDoctorReport(report));
+}
+export async function runKtxDoctor(args, io = process, deps = {}) {
+    try {
+        const runSetupChecks = deps.runSetupChecks ?? (() => runSetupDoctorChecks());
+        const setupChecks = await runSetupChecks();
+        const report = args.command === 'setup'
+            ? { title: 'KTX setup doctor', checks: setupChecks }
+            : args.command === 'demo'
+                ? {
+                    title: 'KTX demo doctor',
+                    checks: [...setupChecks, ...(await runDemoProjectChecks(args.projectDir, deps))],
+                }
+                : {
+                    title: 'KTX project doctor',
+                    checks: [...setupChecks, ...(await runProjectChecks(args.projectDir, deps))],
+                };
+        writeReport(report, args.outputMode, io);
+        return hasFailures(report) ? 1 : 0;
+    }
+    catch (error) {
+        io.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+}

package/dist/doctor.test.d.ts

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

package/dist/doctor.test.js

@@ -0,0 +1,339 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { formatDoctorReport, runKtxDoctor, runSetupDoctorChecks, } from './doctor.js';
+function makeIo() {
+    let stdout = '';
+    let stderr = '';
+    return {
+        io: {
+            stdout: {
+                write: (chunk) => {
+                    stdout += chunk;
+                },
+            },
+            stderr: {
+                write: (chunk) => {
+                    stderr += chunk;
+                },
+            },
+        },
+        stdout: () => stdout,
+        stderr: () => stderr,
+    };
+}
+async function writeProjectConfig(projectDir, embeddingLines) {
+    await writeFile(join(projectDir, 'ktx.yaml'), [
+        'project: warehouse',
+        'connections:',
+        '  warehouse:',
+        '    driver: sqlite',
+        '    path: ./warehouse.db',
+        'ingest:',
+        '  adapters:',
+        '    - live-database',
+        '  embeddings:',
+        ...embeddingLines.map((line) => `    ${line}`),
+        '',
+    ].join('\n'), 'utf-8');
+}
+describe('formatDoctorReport', () => {
+    it('prints exact fixes for failing setup checks', () => {
+        const checks = [
+            { id: 'node', label: 'Node 22+', status: 'pass', detail: 'v22.16.0 ABI 127' },
+            {
+                id: 'native-sqlite',
+                label: 'Native SQLite',
+                status: 'fail',
+                detail: 'Cannot load better-sqlite3',
+                fix: 'Run: pnpm run native:rebuild',
+            },
+        ];
+        expect(formatDoctorReport({ title: 'KTX setup doctor', checks })).toBe([
+            'KTX setup doctor',
+            'PASS Node 22+: v22.16.0 ABI 127',
+            'FAIL Native SQLite: Cannot load better-sqlite3',
+            '     Fix: Run: pnpm run native:rebuild',
+            '',
+        ].join('\n'));
+    });
+});
+describe('runSetupDoctorChecks', () => {
+    it('returns pass checks when injected commands and file checks succeed', async () => {
+        const checks = await runSetupDoctorChecks({
+            env: { PATH: '/bin' },
+            workspaceRoot: '/workspace/ktx',
+            execText: async (command, args) => {
+                if (command === 'pnpm' && args[0] === '--version')
+                    return '10.28.0';
+                if (command === 'corepack' && args[0] === '--version')
+                    return '0.32.0';
+                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';
+                throw new Error(`${command} ${args.join(' ')}`);
+            },
+            pathExists: async () => true,
+            importBetterSqlite3: async () => ({ default: function Database() { } }),
+        });
+        expect(checks.map((check) => [check.id, check.status])).toEqual([
+            ['node', 'pass'],
+            ['pnpm', 'pass'],
+            ['corepack', 'pass'],
+            ['uv', 'pass'],
+            ['native-sqlite', 'pass'],
+            ['package-build', 'pass'],
+            ['workspace-cli', 'pass'],
+        ]);
+    });
+    it('returns exact fixes when setup checks fail', async () => {
+        const checks = await runSetupDoctorChecks({
+            env: {},
+            workspaceRoot: '/workspace/ktx',
+            execText: async (command) => {
+                throw new Error(`${command} not found`);
+            },
+            pathExists: async () => false,
+            importBetterSqlite3: async () => {
+                throw new Error('Cannot find module better-sqlite3');
+            },
+        });
+        expect(checks).toContainEqual({
+            id: 'pnpm',
+            label: 'pnpm 10.20+',
+            status: 'fail',
+            detail: 'pnpm not found',
+            fix: 'Run: corepack enable && corepack prepare pnpm@10.28.0 --activate',
+        });
+        expect(checks).toContainEqual({
+            id: 'package-build',
+            label: 'TypeScript package build',
+            status: 'fail',
+            detail: 'Missing packages/cli/dist/bin.js',
+            fix: 'Run: pnpm run build',
+        });
+    });
+    it('treats missing corepack as a warning so setup doctor can still pass', async () => {
+        const checks = await runSetupDoctorChecks({
+            env: { PATH: '/bin' },
+            workspaceRoot: '/workspace/ktx',
+            execText: async (command, args) => {
+                if (command === 'pnpm' && args[0] === '--version')
+                    return '10.28.0';
+                if (command === 'corepack' && args[0] === '--version')
+                    throw new Error('spawn corepack ENOENT');
+                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';
+                throw new Error(`${command} ${args.join(' ')}`);
+            },
+            pathExists: async () => true,
+            importBetterSqlite3: async () => ({ default: function Database() { } }),
+        });
+        const testIo = makeIo();
+        await expect(runKtxDoctor({ command: 'setup', outputMode: 'plain', inputMode: 'disabled' }, testIo.io, {
+            runSetupChecks: async () => checks,
+        })).resolves.toBe(0);
+        expect(checks).toContainEqual({
+            id: 'corepack',
+            label: 'Corepack',
+            status: 'warn',
+            detail: 'spawn corepack ENOENT',
+            fix: 'Run: corepack enable',
+        });
+        expect(testIo.stdout()).toContain('WARN Corepack: spawn corepack ENOENT');
+        expect(testIo.stderr()).toBe('');
+    });
+});
+describe('runKtxDoctor', () => {
+    let tempDir;
+    beforeEach(async () => {
+        tempDir = await mkdtemp(join(tmpdir(), 'ktx-doctor-'));
+    });
+    afterEach(async () => {
+        await rm(tempDir, { recursive: true, force: true });
+    });
+    it('prints setup report and exits nonzero when a check fails', async () => {
+        const testIo = makeIo();
+        await expect(runKtxDoctor({ command: 'setup', outputMode: 'plain', inputMode: 'disabled' }, testIo.io, {
+            runSetupChecks: async () => [
+                { id: 'node', label: 'Node 22+', status: 'pass', detail: 'v22.16.0 ABI 127' },
+                {
+                    id: 'package-build',
+                    label: 'TypeScript package build',
+                    status: 'fail',
+                    detail: 'Missing packages/cli/dist/bin.js',
+                    fix: 'Run: pnpm run build',
+                },
+            ],
+        })).resolves.toBe(1);
+        expect(testIo.stdout()).toContain('KTX setup doctor');
+        expect(testIo.stdout()).toContain('FAIL TypeScript package build: Missing packages/cli/dist/bin.js');
+        expect(testIo.stdout()).toContain('Fix: Run: pnpm run build');
+        expect(testIo.stderr()).toBe('');
+    });
+    it('prints JSON setup report', async () => {
+        const testIo = makeIo();
+        await expect(runKtxDoctor({ command: 'setup', outputMode: 'json', inputMode: 'disabled' }, testIo.io, {
+            runSetupChecks: async () => [
+                { id: 'node', label: 'Node 22+', status: 'pass', detail: 'v22.16.0 ABI 127' },
+            ],
+        })).resolves.toBe(0);
+        expect(JSON.parse(testIo.stdout())).toEqual({
+            title: 'KTX setup doctor',
+            checks: [{ id: 'node', label: 'Node 22+', status: 'pass', detail: 'v22.16.0 ABI 127' }],
+        });
+    });
+    it('runs project checks against a valid ktx.yaml', async () => {
+        await writeFile(join(tempDir, 'ktx.yaml'), [
+            'project: warehouse',
+            'connections:',
+            '  warehouse:',
+            '    driver: sqlite',
+            '    path: ./warehouse.db',
+            'ingest:',
+            '  adapters:',
+            '    - live-database',
+            '',
+        ].join('\n'), 'utf-8');
+        const testIo = makeIo();
+        await expect(runKtxDoctor({ command: 'project', projectDir: tempDir, outputMode: 'plain', inputMode: 'disabled' }, testIo.io, {
+            runSetupChecks: async () => [
+                { id: 'node', label: 'Node 22+', status: 'pass', detail: 'v22.16.0 ABI 127' },
+            ],
+        })).resolves.toBe(0);
+        expect(testIo.stdout()).toContain('KTX project doctor');
+        expect(testIo.stdout()).toContain('PASS Project config: warehouse');
+        expect(testIo.stdout()).toContain('PASS Connections: 1 configured');
+    });
+    it('includes Postgres historic-SQL readiness in project doctor output', async () => {
+        await writeFile(join(tempDir, 'ktx.yaml'), [
+            'project: warehouse',
+            'connections:',
+            '  warehouse:',
+            '    driver: postgres',
+            '    url: env:WAREHOUSE_DATABASE_URL',
+            '    readonly: true',
+            '    historicSql:',
+            '      enabled: true',
+            '      dialect: postgres',
+            'ingest:',
+            '  adapters:',
+            '    - live-database',
+            '    - historic-sql',
+            '',
+        ].join('\n'), 'utf-8');
+        const testIo = makeIo();
+        const runHistoricSqlDoctorChecks = vi.fn(async () => [
+            {
+                id: 'historic-sql-postgres-warehouse',
+                label: 'Postgres Historic SQL (warehouse)',
+                status: 'warn',
+                detail: 'pg_stat_statements ready (PostgreSQL 16.4) with warnings: pg_stat_statements.max is 1000; set it to at least 5000 to reduce query-template eviction churn',
+                fix: `Update the Postgres parameter group or config, then rerun \`ktx dev doctor --project-dir ${tempDir}\``,
+            },
+        ]);
+        await expect(runKtxDoctor({ command: 'project', projectDir: tempDir, outputMode: 'plain', inputMode: 'disabled' }, testIo.io, {
+            runSetupChecks: async () => [
+                { id: 'node', label: 'Node 22+', status: 'pass', detail: 'v22.16.0 ABI 127' },
+            ],
+            runHistoricSqlDoctorChecks,
+        })).resolves.toBe(0);
+        expect(runHistoricSqlDoctorChecks).toHaveBeenCalledTimes(1);
+        expect(testIo.stdout()).toContain('WARN Postgres Historic SQL (warehouse): pg_stat_statements ready');
+        expect(testIo.stdout()).toContain('Fix: Update the Postgres parameter group or config');
+    });
+    it('warns when semantic-search embeddings are not configured', async () => {
+        await writeProjectConfig(tempDir, ['backend: deterministic', 'model: deterministic', 'dimensions: 8']);
+        const testIo = makeIo();
+        await expect(runKtxDoctor({ command: 'project', projectDir: tempDir, outputMode: 'plain', inputMode: 'disabled' }, testIo.io, {
+            runSetupChecks: async () => [
+                { id: 'node', label: 'Node 22+', status: 'pass', detail: 'v22.16.0 ABI 127' },
+            ],
+        })).resolves.toBe(0);
+        expect(testIo.stdout()).toContain('WARN Semantic search embeddings: ingest.embeddings.backend is deterministic.');
+        expect(testIo.stdout()).toContain('Semantic lane will be skipped; lexical, dictionary, and token lanes remain available.');
+        expect(testIo.stdout()).toContain(`Fix: Run: ktx setup --project-dir ${tempDir} --no-input`);
+    });
+    it('probes configured semantic-search embeddings for project doctor', async () => {
+        await writeProjectConfig(tempDir, [
+            'backend: sentence-transformers',
+            'model: all-MiniLM-L6-v2',
+            'dimensions: 384',
+            'sentenceTransformers:',
+            '  base_url: http://127.0.0.1:8765',
+            "  pathPrefix: ''",
+        ]);
+        const healthCheck = vi.fn(async () => ({ ok: true }));
+        const testIo = makeIo();
+        await expect(runKtxDoctor({ command: 'project', projectDir: tempDir, outputMode: 'plain', inputMode: 'disabled' }, testIo.io, {
+            runSetupChecks: async () => [
+                { id: 'node', label: 'Node 22+', status: 'pass', detail: 'v22.16.0 ABI 127' },
+            ],
+            embeddingHealthCheck: healthCheck,
+            embeddingProbeTimeoutMs: 1234,
+        })).resolves.toBe(0);
+        expect(healthCheck).toHaveBeenCalledWith({
+            backend: 'sentence-transformers',
+            model: 'all-MiniLM-L6-v2',
+            dimensions: 384,
+            sentenceTransformers: { baseURL: 'http://127.0.0.1:8765', pathPrefix: '' },
+        }, { text: 'KTX semantic search doctor probe', timeoutMs: 1234 });
+        expect(testIo.stdout()).toContain('PASS Semantic search embeddings: sentence-transformers/all-MiniLM-L6-v2 (384d) probe succeeded');
+    });
+    it('allows local sentence-transformers semantic-search probes enough time for cold start', async () => {
+        await writeProjectConfig(tempDir, [
+            'backend: sentence-transformers',
+            'model: all-MiniLM-L6-v2',
+            'dimensions: 384',
+            'sentenceTransformers:',
+            '  base_url: http://127.0.0.1:8765',
+            "  pathPrefix: ''",
+        ]);
+        const healthCheck = vi.fn(async () => ({ ok: true }));
+        const testIo = makeIo();
+        await expect(runKtxDoctor({ command: 'project', projectDir: tempDir, outputMode: 'plain', inputMode: 'disabled' }, testIo.io, {
+            runSetupChecks: async () => [
+                { id: 'node', label: 'Node 22+', status: 'pass', detail: 'v22.16.0 ABI 127' },
+            ],
+            embeddingHealthCheck: healthCheck,
+        })).resolves.toBe(0);
+        expect(healthCheck).toHaveBeenCalledWith(expect.objectContaining({
+            backend: 'sentence-transformers',
+            model: 'all-MiniLM-L6-v2',
+            dimensions: 384,
+        }), { text: 'KTX semantic search doctor probe', timeoutMs: 120_000 });
+    });
+    it('reports unhealthy semantic-search embeddings as a warning in JSON output', async () => {
+        await writeProjectConfig(tempDir, [
+            'backend: sentence-transformers',
+            'model: all-MiniLM-L6-v2',
+            'dimensions: 384',
+            'sentenceTransformers:',
+            '  base_url: http://127.0.0.1:8765',
+            "  pathPrefix: ''",
+        ]);
+        const healthCheck = vi.fn(async () => ({
+            ok: false,
+            message: 'connect ECONNREFUSED 127.0.0.1:8765',
+        }));
+        const testIo = makeIo();
+        await expect(runKtxDoctor({ command: 'project', projectDir: tempDir, outputMode: 'json', inputMode: 'disabled' }, testIo.io, {
+            runSetupChecks: async () => [
+                { id: 'node', label: 'Node 22+', status: 'pass', detail: 'v22.16.0 ABI 127' },
+            ],
+            embeddingHealthCheck: healthCheck,
+        })).resolves.toBe(0);
+        const report = JSON.parse(testIo.stdout());
+        expect(report.checks).toContainEqual({
+            id: 'semantic-search-embeddings',
+            label: 'Semantic search embeddings',
+            status: 'warn',
+            detail: 'sentence-transformers/all-MiniLM-L6-v2 (384d) probe failed: connect ECONNREFUSED 127.0.0.1:8765. Semantic lane will be skipped; lexical, dictionary, and token lanes remain available.',
+            fix: `Run: ktx setup --project-dir ${tempDir} --no-input`,
+        });
+    });
+});

package/dist/example-smoke.test.d.ts

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