@kaelio/ktx 0.0.0 → 0.1.0-rc.0

package/dist/standalone-smoke.test.js

@@ -0,0 +1,714 @@
+import { execFile } from 'node:child_process';
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { promisify } from 'node:util';
+import { parseKtxProjectConfig } from '@ktx/context/project';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import Database from 'better-sqlite3';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+const execFileAsync = promisify(execFile);
+const CLI_BIN = resolve(process.cwd(), 'dist/bin.js');
+function isExecFailure(error) {
+    return error instanceof Error && ('stdout' in error || 'stderr' in error || 'code' in error);
+}
+async function runBuiltCli(args, options = {}) {
+    try {
+        const result = await execFileAsync(process.execPath, [CLI_BIN, ...args], {
+            encoding: 'utf8',
+            timeout: 20_000,
+            ...(options.env ? { env: options.env } : {}),
+        });
+        return {
+            code: 0,
+            stdout: result.stdout,
+            stderr: result.stderr,
+        };
+    }
+    catch (error) {
+        if (!isExecFailure(error)) {
+            throw error;
+        }
+        return {
+            code: typeof error.code === 'number' ? error.code : 1,
+            stdout: error.stdout ?? '',
+            stderr: error.stderr ?? error.message,
+        };
+    }
+}
+function getRunId(stdout) {
+    const match = stdout.match(/^Run: (.+)$/m);
+    if (!match) {
+        throw new Error(`Could not find run id in output:\n${stdout}`);
+    }
+    return match[1];
+}
+function structuredContent(result) {
+    const content = result.structuredContent;
+    expect(content).toBeDefined();
+    return content;
+}
+async function writeWarehouseConfig(projectDir) {
+    await writeFile(join(projectDir, 'ktx.yaml'), [
+        'project: warehouse',
+        'connections:',
+        '  warehouse:',
+        '    driver: postgres',
+        'ingest:',
+        '  adapters:',
+        '    - fake',
+        '',
+    ].join('\n'), 'utf-8');
+}
+async function writeSourceFixture(sourceDir) {
+    await mkdir(join(sourceDir, 'orders'), { recursive: true });
+    await writeFile(join(sourceDir, 'orders', 'orders.json'), '{"name":"orders"}\n', 'utf-8');
+}
+function createSqliteWarehouse(dbPath) {
+    const db = new Database(dbPath);
+    try {
+        db.exec(`
+      PRAGMA foreign_keys = ON;
+      CREATE TABLE customers (
+        id INTEGER PRIMARY KEY,
+        name TEXT NOT NULL
+      );
+      CREATE TABLE orders (
+        id INTEGER PRIMARY KEY,
+        customer_id INTEGER NOT NULL,
+        total NUMERIC,
+        created_at TEXT,
+        FOREIGN KEY(customer_id) REFERENCES customers(id)
+      );
+      INSERT INTO customers (id, name) VALUES (1, 'Ada'), (2, 'Grace');
+      INSERT INTO orders (id, customer_id, total, created_at)
+        VALUES (10, 1, 42.5, '2026-04-28'), (11, 2, 9.5, '2026-04-29');
+    `);
+    }
+    finally {
+        db.close();
+    }
+}
+async function writeSqliteScanConfig(projectDir, dbPath, enrich = false) {
+    await writeFile(join(projectDir, 'ktx.yaml'), [
+        'project: warehouse',
+        'connections:',
+        '  warehouse:',
+        '    driver: sqlite',
+        `    path: ${JSON.stringify(dbPath)}`,
+        '    readonly: true',
+        'ingest:',
+        '  adapters:',
+        '    - live-database',
+        ...(enrich
+            ? [
+                'scan:',
+                '  enrichment:',
+                '    mode: deterministic',
+                '    embeddings:',
+                '      backend: deterministic',
+                '      dimensions: 6',
+            ]
+            : []),
+        '',
+    ].join('\n'), 'utf-8');
+}
+function parseJsonOutput(stdout) {
+    return JSON.parse(stdout);
+}
+async function runSetupNewProject(projectDir) {
+    return await runBuiltCli([
+        'setup',
+        '--project-dir',
+        projectDir,
+        '--new',
+        '--no-input',
+        '--yes',
+        '--skip-llm',
+        '--skip-embeddings',
+        '--skip-databases',
+        '--skip-sources',
+        '--skip-agents',
+    ]);
+}
+describe('standalone built ktx CLI smoke', () => {
+    let tempDir;
+    beforeEach(async () => {
+        tempDir = await mkdtemp(join(tmpdir(), 'ktx-standalone-smoke-'));
+    });
+    afterEach(async () => {
+        await rm(tempDir, { recursive: true, force: true });
+    });
+    it('reports missing local ingest LLM config through the built binary', async () => {
+        const projectDir = join(tempDir, 'project');
+        const sourceDir = join(tempDir, 'source');
+        const init = await runSetupNewProject(projectDir);
+        expect(init).toMatchObject({ code: 0, stderr: '' });
+        expect(init.stdout).toContain(`Project: ${projectDir}`);
+        await writeWarehouseConfig(projectDir);
+        await writeSourceFixture(sourceDir);
+        const run = await runBuiltCli([
+            'dev',
+            'ingest',
+            'run',
+            '--project-dir',
+            projectDir,
+            '--connection-id',
+            'warehouse',
+            '--adapter',
+            'fake',
+            '--source-dir',
+            sourceDir,
+        ]);
+        expect(run).toMatchObject({ code: 1, stdout: '' });
+        expect(run.stderr).toContain('ktx dev ingest run requires llm.provider.backend: anthropic, vertex, or gateway, or an injected agentRunner');
+    });
+    it('runs the default pre-seeded demo without credentials', async () => {
+        const result = await runBuiltCli(['setup', 'demo', '--project-dir', join(tempDir, 'demo-project'), '--plain', '--no-input'], {
+            env: { ...process.env, ANTHROPIC_API_KEY: '' },
+        });
+        expect(result).toMatchObject({ code: 0, stderr: '' });
+        expect(result.stdout).toContain('Mode: seeded');
+        expect(result.stdout).toContain('Source: packaged demo project');
+        expect(result.stdout).toContain('LLM calls: none');
+        expect(result.stdout).toContain('Warehouse:');
+        expect(result.stdout).toContain('dbt:');
+        expect(result.stdout).toContain('BI:');
+        expect(result.stdout).toContain('Notion:');
+        expect(result.stdout).toContain('Semantic-layer sources:');
+        expect(result.stdout).toContain('Knowledge pages:');
+        expect(result.stdout).toContain('ktx serve --mcp stdio');
+        expect(result.stdout).not.toContain(['--mode', 'deterministic'].join(' '));
+    });
+    it('runs hybrid agent search against the seeded demo through the built binary', async () => {
+        const projectDir = join(tempDir, 'seeded-hybrid-search-project');
+        const seeded = await runBuiltCli(['setup', 'demo', '--project-dir', projectDir, '--plain', '--no-input'], {
+            env: { ...process.env, ANTHROPIC_API_KEY: '' },
+        });
+        expect(seeded).toMatchObject({ code: 0, stderr: '' });
+        expect(seeded.stdout).toContain('Mode: seeded');
+        const wikiSearch = await runBuiltCli([
+            'agent',
+            'wiki',
+            'search',
+            'ARR contract',
+            '--json',
+            '--limit',
+            '5',
+            '--project-dir',
+            projectDir,
+        ]);
+        expect(wikiSearch).toMatchObject({ code: 0, stderr: '' });
+        const wikiJson = parseJsonOutput(wikiSearch.stdout);
+        expect(wikiJson.totalFound).toBeGreaterThan(0);
+        expect(wikiJson.results.some((result) => result.matchReasons?.length)).toBe(true);
+        const slSearch = await runBuiltCli([
+            'agent',
+            'sl',
+            'list',
+            '--json',
+            '--query',
+            'ARR',
+            '--project-dir',
+            projectDir,
+        ]);
+        expect(slSearch).toMatchObject({ code: 0, stderr: '' });
+        const slJson = parseJsonOutput(slSearch.stdout);
+        expect(slJson.totalSources).toBeGreaterThan(0);
+        expect(slJson.sources.some((source) => source.matchReasons?.length)).toBe(true);
+    });
+    it('prints guided JSON for agent semantic-layer search outside a project through the built binary', async () => {
+        const projectDir = join(tempDir, 'missing-search-project');
+        await mkdir(projectDir, { recursive: true });
+        const result = await runBuiltCli([
+            'agent',
+            'sl',
+            'list',
+            '--json',
+            '--query',
+            'revenue',
+            '--project-dir',
+            projectDir,
+        ]);
+        expect(result.code).toBe(1);
+        expect(result.stdout).toBe('');
+        const errorJson = parseJsonOutput(result.stderr);
+        expect(errorJson).toEqual({
+            ok: false,
+            error: {
+                code: 'agent_sl_search_missing_project',
+                message: `Semantic-layer search needs an initialized KTX project at ${projectDir}.`,
+                nextSteps: [
+                    'ktx demo',
+                    `ktx setup --project-dir ${projectDir}`,
+                    'ktx ingest <connection>',
+                    `ktx agent sl list --json --query "revenue" --project-dir ${projectDir}`,
+                ],
+            },
+        });
+    });
+    it('runs the pre-seeded demo and inspect without credentials', async () => {
+        const projectDir = join(tempDir, 'seeded-demo-project');
+        const seeded = await runBuiltCli(['setup', 'demo', '--mode', 'seeded', '--project-dir', projectDir, '--no-input']);
+        expect(seeded.code).toBe(0);
+        expect(seeded.stdout).toContain('Mode: seeded');
+        expect(seeded.stdout).toContain('LLM calls: none');
+        expect(seeded.stdout).toContain('Semantic-layer sources:');
+        expect(seeded.stdout).toContain('Knowledge pages:');
+        const inspect = await runBuiltCli(['setup', 'demo', 'inspect', '--project-dir', projectDir, '--no-input']);
+        expect(inspect).toMatchObject({ code: 0, stderr: '' });
+        expect(inspect.stdout).toContain('Mode: seeded');
+        expect(inspect.stdout).toContain('Status: ready');
+        expect(inspect.stdout).toContain('Warehouse: 8 tables, 11,234 rows');
+        expect(inspect.stdout).toContain('Rows: accounts 210, arr_movements 720');
+        expect(inspect.stdout).toContain('dbt: 3 models, 8 source tables');
+        expect(inspect.stdout).toContain('BI: 5 explores, 2 dashboards');
+        expect(inspect.stdout).toContain('Notion: 8 pages');
+        expect(inspect.stdout).toContain('Semantic-layer sources:');
+        expect(inspect.stdout).toContain('Knowledge pages:');
+        expect(inspect.stdout).toContain('Evidence links:');
+        expect(inspect.stdout).toContain('Report: reports/seeded-demo-report.json');
+        expect(inspect.stdout).toContain('Replay: replays/replay.memory-flow.v1.json');
+        expect(inspect.stdout).toContain('Latest replay: seeded (packaged, prebuilt)');
+        expect(inspect.stdout).toContain('ktx agent tools --json');
+        expect(inspect.stdout).toContain('ktx agent context --json');
+        expect(inspect.stdout).not.toContain('ktx ask "your question here"');
+        expect(inspect.stdout).toContain('ktx serve --mcp stdio');
+    });
+    it('serves seeded demo wiki and semantic-layer context over stdio MCP', async () => {
+        const projectDir = join(tempDir, 'seeded-mcp-project');
+        const seeded = await runBuiltCli(['setup', 'demo', '--mode', 'seeded', '--project-dir', projectDir, '--plain', '--no-input'], {
+            env: { ...process.env, ANTHROPIC_API_KEY: '' },
+        });
+        expect(seeded).toMatchObject({ code: 0, stderr: '' });
+        expect(seeded.stdout).toContain('Mode: seeded');
+        const client = new Client({ name: 'ktx-seeded-demo-smoke-client', version: '0.0.0' });
+        const transport = new StdioClientTransport({
+            command: process.execPath,
+            args: [CLI_BIN, 'serve', '--mcp', 'stdio', '--project-dir', projectDir, '--user-id', 'smoke-user'],
+            stderr: 'pipe',
+        });
+        try {
+            await client.connect(transport);
+            const toolNames = (await client.listTools()).tools.map((tool) => tool.name).sort();
+            expect(toolNames).toEqual(expect.arrayContaining(['knowledge_read', 'knowledge_search', 'sl_read_source', 'sl_validate']));
+            const knowledgeSearch = structuredContent(await client.callTool({ name: 'knowledge_search', arguments: { query: 'ARR contract', limit: 5 } }));
+            expect(knowledgeSearch.totalFound).toBeGreaterThan(0);
+            expect(knowledgeSearch.results.map((result) => result.key)).toContain('arr-contract-first');
+            const knowledgeRead = structuredContent(await client.callTool({ name: 'knowledge_read', arguments: { key: 'arr-contract-first' } }));
+            expect(knowledgeRead.key).toBe('arr-contract-first');
+            expect(knowledgeRead.summary).toContain('ARR');
+            expect(knowledgeRead.content).toContain('contract');
+            expect(knowledgeRead.slRefs).toContain('orbit_demo.contracts');
+            const slRead = structuredContent(await client.callTool({
+                name: 'sl_read_source',
+                arguments: { connectionId: 'orbit_demo', sourceName: 'accounts' },
+            }));
+            expect(slRead.sourceName).toBe('accounts');
+            expect(slRead.yaml).toContain('name: accounts');
+            expect(slRead.yaml).toContain('measures:');
+            const slValidate = structuredContent(await client.callTool({
+                name: 'sl_validate',
+                arguments: { connectionId: 'orbit_demo', names: ['accounts', 'contracts'] },
+            }));
+            expect(slValidate.success).toBe(true);
+            expect(slValidate.errors).toEqual([]);
+        }
+        finally {
+            await client.close();
+        }
+    });
+    it('runs doctor setup through the built binary', async () => {
+        const result = await runBuiltCli(['dev', 'doctor', 'setup', '--no-input']);
+        expect(result.stdout).toContain('KTX setup doctor');
+        expect(result.stdout).toContain('Node 22+');
+        expect(result.stdout).toContain('Workspace-local CLI');
+        expect(result.stderr).toBe('');
+        expect([0, 1]).toContain(result.code);
+    });
+    it('reports missing Anthropic credentials for full demo through the built binary', async () => {
+        const projectDir = join(tempDir, 'full-demo-missing-key');
+        const result = await runBuiltCli(['setup', 'demo', '--mode', 'full', '--project-dir', projectDir, '--no-input'], {
+            env: { ...process.env, ANTHROPIC_API_KEY: '' },
+        });
+        expect(result.code).toBe(1);
+        expect(result.stderr).toContain('ktx setup demo --mode full needs ANTHROPIC_API_KEY');
+        expect(result.stderr).toContain('ktx setup demo --mode seeded --no-input');
+    });
+    it('requires force for demo reset through the built binary', async () => {
+        const projectDir = join(tempDir, 'reset-demo-project');
+        const init = await runBuiltCli(['setup', 'demo', 'init', '--project-dir', projectDir, '--no-input']);
+        expect(init).toMatchObject({ code: 0, stderr: '' });
+        const withoutForce = await runBuiltCli(['setup', 'demo', 'reset', '--project-dir', projectDir, '--no-input']);
+        expect(withoutForce.code).toBe(1);
+        expect(withoutForce.stderr).toContain(`ktx setup demo reset is destructive; pass --force to recreate ${projectDir}`);
+        const withForce = await runBuiltCli([
+            'setup',
+            'demo',
+            'reset',
+            '--project-dir',
+            projectDir,
+            '--force',
+            '--no-input',
+        ]);
+        expect(withForce).toMatchObject({ code: 0, stderr: '' });
+        expect(withForce.stdout).toContain(`Demo project reset: ${projectDir}`);
+    });
+    it('reports corrupted demo state with reset guidance through the built binary', async () => {
+        const projectDir = join(tempDir, 'corrupt-demo-project');
+        const init = await runBuiltCli(['setup', 'demo', 'init', '--project-dir', projectDir, '--no-input']);
+        expect(init).toMatchObject({ code: 0, stderr: '' });
+        await rm(join(projectDir, 'demo.db'), { force: true });
+        const replay = await runBuiltCli(['setup', 'demo', '--mode', 'replay', '--project-dir', projectDir, '--no-input']);
+        expect(replay.code).toBe(1);
+        expect(replay.stderr).toContain(`Demo project is not ready at ${projectDir}: missing demo.db`);
+        expect(replay.stderr).toContain(`ktx setup demo reset --project-dir ${projectDir} --force --no-input`);
+    });
+    it('runs demo doctor through the built binary', async () => {
+        const projectDir = join(tempDir, 'doctor-demo-project');
+        const init = await runBuiltCli(['setup', 'demo', 'init', '--project-dir', projectDir, '--no-input']);
+        expect(init).toMatchObject({ code: 0, stderr: '' });
+        const result = await runBuiltCli(['setup', 'demo', 'doctor', '--project-dir', projectDir, '--no-input']);
+        expect(result.stdout).toContain('KTX demo doctor');
+        expect(result.stdout).toContain('Demo dataset');
+        expect(result.stdout).toContain('Demo replay');
+        expect(result.stdout).toContain('Demo LLM provider');
+        expect(result.stderr).toBe('');
+        expect([0, 1]).toContain(result.code);
+    });
+    it('runs demo ingest seeded mode through the built binary', async () => {
+        const projectDir = join(tempDir, 'seeded-ingest-alias');
+        const result = await runBuiltCli([
+            'setup',
+            'demo',
+            'ingest',
+            '--mode',
+            'seeded',
+            '--project-dir',
+            projectDir,
+            '--no-input',
+        ]);
+        expect(result.code).toBe(0);
+        expect(result.stdout).toContain('Mode: seeded');
+        expect(result.stdout).toContain('LLM calls: none');
+    });
+    it('runs structural and enriched scans through the built binary with manifest artifacts', async () => {
+        const projectDir = join(tempDir, 'scan-project');
+        const init = await runSetupNewProject(projectDir);
+        expect(init).toMatchObject({ code: 0, stderr: '' });
+        const dbPath = join(projectDir, 'warehouse.db');
+        createSqliteWarehouse(dbPath);
+        await writeSqliteScanConfig(projectDir, dbPath);
+        const connectionTest = await runBuiltCli(['connection', 'test', 'warehouse', '--project-dir', projectDir]);
+        expect(connectionTest).toMatchObject({ code: 0, stderr: '' });
+        expect(connectionTest.stdout).toContain('Connection test passed: warehouse');
+        expect(connectionTest.stdout).toContain('Driver: sqlite');
+        expect(connectionTest.stdout).toContain('Tables: 2');
+        const structural = await runBuiltCli(['dev', 'scan', 'warehouse', '--project-dir', projectDir]);
+        expect(structural).toMatchObject({ code: 0, stderr: '' });
+        expect(structural.stdout).toContain('Status: done');
+        expect(structural.stdout).toContain('Mode: structural');
+        const structuralRunId = getRunId(structural.stdout);
+        const structuralReportResult = await runBuiltCli([
+            'dev',
+            'scan',
+            'report',
+            '--json',
+            '--project-dir',
+            projectDir,
+            structuralRunId,
+        ]);
+        expect(structuralReportResult).toMatchObject({ code: 0, stderr: '' });
+        const structuralReport = parseJsonOutput(structuralReportResult.stdout);
+        expect(structuralReport.mode).toBe('structural');
+        expect(structuralReport.artifactPaths.manifestShards).toEqual(['semantic-layer/warehouse/_schema/public.yaml']);
+        expect(structuralReport.artifactPaths.enrichmentArtifacts).toEqual([]);
+        expect(structuralReport.manifestShardsWritten).toBe(1);
+        const structuralManifest = await readFile(join(projectDir, 'semantic-layer/warehouse/_schema/public.yaml'), 'utf-8');
+        expect(structuralManifest).toContain('customers:');
+        expect(structuralManifest).toContain('orders:');
+        expect(structuralManifest).toContain('source: formal');
+        expect(structuralManifest).not.toContain('ai:');
+        const providerlessEnriched = await runBuiltCli([
+            'dev',
+            'scan',
+            'warehouse',
+            '--project-dir',
+            projectDir,
+            '--mode',
+            'enriched',
+        ]);
+        expect(providerlessEnriched).toMatchObject({ code: 0, stderr: '' });
+        expect(providerlessEnriched.stdout).toContain('Mode: enriched');
+        expect(providerlessEnriched.stdout).toContain('Relationships');
+        expect(providerlessEnriched.stdout).toContain('Accepted: 1');
+        expect(providerlessEnriched.stdout).toContain('scan_enrichment_backend_not_configured');
+        expect(providerlessEnriched.stdout).toContain('Enrichment artifacts: 3');
+        const providerlessRunId = getRunId(providerlessEnriched.stdout);
+        const providerlessReportResult = await runBuiltCli([
+            'dev',
+            'scan',
+            'report',
+            '--json',
+            '--project-dir',
+            projectDir,
+            providerlessRunId,
+        ]);
+        expect(providerlessReportResult).toMatchObject({ code: 0, stderr: '' });
+        const providerlessReport = parseJsonOutput(providerlessReportResult.stdout);
+        expect(providerlessReport.mode).toBe('enriched');
+        expect(providerlessReport.enrichment).toMatchObject({
+            tableDescriptions: 'skipped',
+            columnDescriptions: 'skipped',
+            embeddings: 'skipped',
+            deterministicRelationships: 'completed',
+            statisticalValidation: 'completed',
+        });
+        expect(providerlessReport.relationships).toEqual({ accepted: 1, review: 0, rejected: 0, skipped: 0 });
+        expect(providerlessReport.warnings).toEqual(expect.arrayContaining([expect.objectContaining({ code: 'scan_enrichment_backend_not_configured' })]));
+        expect(providerlessReport.artifactPaths.enrichmentArtifacts).toEqual(expect.arrayContaining([
+            expect.stringContaining('/enrichment/relationships.json'),
+            expect.stringContaining('/enrichment/relationship-profile.json'),
+            expect.stringContaining('/enrichment/relationship-diagnostics.json'),
+        ]));
+        expect(providerlessReport.artifactPaths.manifestShards).toEqual(['semantic-layer/warehouse/_schema/public.yaml']);
+        await writeSqliteScanConfig(projectDir, dbPath, true);
+        const enriched = await runBuiltCli(['dev', 'scan', 'warehouse', '--project-dir', projectDir, '--mode', 'enriched']);
+        expect(enriched).toMatchObject({ code: 0, stderr: '' });
+        expect(enriched.stdout).toContain('Mode: enriched');
+        const enrichedRunId = getRunId(enriched.stdout);
+        const enrichedReportResult = await runBuiltCli([
+            'dev',
+            'scan',
+            'report',
+            '--json',
+            '--project-dir',
+            projectDir,
+            enrichedRunId,
+        ]);
+        expect(enrichedReportResult).toMatchObject({ code: 0, stderr: '' });
+        const enrichedReport = parseJsonOutput(enrichedReportResult.stdout);
+        expect(enrichedReport.mode).toBe('enriched');
+        expect(enrichedReport.enrichment).toMatchObject({
+            tableDescriptions: 'completed',
+            columnDescriptions: 'completed',
+            embeddings: 'completed',
+        });
+        expect(enrichedReport.artifactPaths.enrichmentArtifacts).toEqual(expect.arrayContaining([
+            expect.stringContaining('/enrichment/descriptions.json'),
+            expect.stringContaining('/enrichment/embeddings.json'),
+            expect.stringContaining('/enrichment/relationships.json'),
+            expect.stringContaining('/enrichment/relationship-profile.json'),
+            expect.stringContaining('/enrichment/relationship-diagnostics.json'),
+        ]));
+        expect(enrichedReport.artifactPaths.manifestShards).toEqual(['semantic-layer/warehouse/_schema/public.yaml']);
+        const enrichedManifest = await readFile(join(projectDir, 'semantic-layer/warehouse/_schema/public.yaml'), 'utf-8');
+        expect(enrichedManifest).toContain('Deterministic description');
+    }, 30_000);
+    it('parses gateway LLM config and OpenAI enrichment embeddings used by standalone scans without network calls', async () => {
+        const projectDir = join(tempDir, 'gateway-config-project');
+        await mkdir(projectDir, { recursive: true });
+        await writeFile(join(projectDir, 'ktx.yaml'), [
+            'project: gateway-smoke',
+            'llm:',
+            '  provider:',
+            '    backend: gateway',
+            '    gateway:',
+            '      api_key: env:AI_GATEWAY_API_KEY', // pragma: allowlist secret
+            '  models:',
+            '    default: env:KTX_SCAN_LLM_MODEL',
+            'scan:',
+            '  enrichment:',
+            '    mode: llm',
+            '    embeddings:',
+            '      backend: openai',
+            '      model: env:KTX_SCAN_EMBEDDING_MODEL',
+            '      dimensions: 1536',
+            '      openai:',
+            '        api_key: env:OPENAI_API_KEY', // pragma: allowlist secret
+            '      batchSize: 16',
+            '',
+        ].join('\n'), 'utf8');
+        const config = parseKtxProjectConfig(await readFile(join(projectDir, 'ktx.yaml'), 'utf8'));
+        expect(config.llm).toEqual({
+            provider: {
+                backend: 'gateway',
+                gateway: { api_key: 'env:AI_GATEWAY_API_KEY' }, // pragma: allowlist secret
+            },
+            models: { default: 'env:KTX_SCAN_LLM_MODEL' },
+        });
+        expect(config.scan.enrichment).toEqual({
+            mode: 'llm',
+            embeddings: {
+                backend: 'openai',
+                model: 'env:KTX_SCAN_EMBEDDING_MODEL',
+                dimensions: 1536,
+                openai: { api_key: 'env:OPENAI_API_KEY' }, // pragma: allowlist secret
+                batchSize: 16,
+            },
+        });
+    });
+    it('adds a redacted Notion connection through the built binary', async () => {
+        const projectDir = join(tempDir, 'notion-project');
+        const init = await runSetupNewProject(projectDir);
+        expect(init).toMatchObject({ code: 0, stderr: '' });
+        const add = await runBuiltCli([
+            'connection',
+            'add',
+            'notion',
+            'notion-main',
+            '--project-dir',
+            projectDir,
+            '--token-env',
+            'NOTION_AUTH_TOKEN',
+            '--crawl-mode',
+            'all_accessible',
+            '--max-pages',
+            '5',
+        ]);
+        expect(add).toMatchObject({ code: 0, stderr: '' });
+        expect(add.stdout).toContain('Connection: notion-main');
+        expect(add.stdout).toContain('Driver: notion');
+        const yaml = await readFile(join(projectDir, 'ktx.yaml'), 'utf-8');
+        expect(yaml).toContain('driver: notion');
+        expect(yaml).toContain('auth_token_ref: env:NOTION_AUTH_TOKEN');
+        expect(yaml).toContain('crawl_mode: all_accessible');
+        expect(yaml).toContain('max_pages_per_run: 5');
+        expect(yaml).not.toContain('ntn_');
+        const parsed = parseKtxProjectConfig(yaml);
+        expect(parsed.connections['notion-main']).toMatchObject({
+            driver: 'notion',
+            auth_token_ref: 'env:NOTION_AUTH_TOKEN',
+            crawl_mode: 'all_accessible',
+        });
+    });
+    it('serves local ingest MCP tools over stdio from the built binary', async () => {
+        const projectDir = join(tempDir, 'project');
+        const init = await runSetupNewProject(projectDir);
+        expect(init).toMatchObject({ code: 0, stderr: '' });
+        await writeWarehouseConfig(projectDir);
+        const client = new Client({ name: 'ktx-smoke-client', version: '0.0.0' });
+        const transport = new StdioClientTransport({
+            command: process.execPath,
+            args: [CLI_BIN, 'serve', '--mcp', 'stdio', '--project-dir', projectDir, '--user-id', 'smoke-user'],
+            stderr: 'pipe',
+        });
+        try {
+            await client.connect(transport);
+            const tools = await client.listTools();
+            const toolNames = tools.tools.map((tool) => tool.name).sort();
+            expect(toolNames).toEqual(expect.arrayContaining([
+                'connection_list',
+                'connection_test',
+                'ingest_report',
+                'ingest_replay',
+                'ingest_status',
+                'ingest_trigger',
+                'knowledge_read',
+                'knowledge_search',
+                'knowledge_write',
+                'scan_list_artifacts',
+                'scan_read_artifact',
+                'scan_report',
+                'scan_status',
+                'scan_trigger',
+                'sl_list_sources',
+                'sl_read_source',
+                'sl_validate',
+                'sl_write_source',
+            ]));
+            const connections = structuredContent(await client.callTool({ name: 'connection_list', arguments: {} }));
+            expect(connections).toEqual({
+                connections: [{ id: 'warehouse', name: 'warehouse', connectionType: 'POSTGRESQL' }],
+            });
+            await expect(client.callTool({ name: 'ingest_status', arguments: { runId: 'missing-run' } })).resolves.toEqual({
+                content: [{ type: 'text', text: 'Ingest run "missing-run" was not found.' }],
+                isError: true,
+            });
+            await expect(client.callTool({ name: 'ingest_report', arguments: { runId: 'missing-run' } })).resolves.toEqual({
+                content: [{ type: 'text', text: 'Ingest report "missing-run" was not found.' }],
+                isError: true,
+            });
+            await expect(client.callTool({ name: 'ingest_replay', arguments: { runId: 'missing-run' } })).resolves.toEqual({
+                content: [{ type: 'text', text: 'Ingest replay "missing-run" was not found.' }],
+                isError: true,
+            });
+        }
+        finally {
+            await client.close();
+        }
+    });
+    it('serves scan execution and artifact inspection tools over stdio from the built binary', async () => {
+        const projectDir = join(tempDir, 'scan-mcp-project');
+        const init = await runSetupNewProject(projectDir);
+        expect(init).toMatchObject({ code: 0, stderr: '' });
+        const dbPath = join(projectDir, 'warehouse.db');
+        createSqliteWarehouse(dbPath);
+        await writeSqliteScanConfig(projectDir, dbPath);
+        const client = new Client({ name: 'ktx-scan-smoke-client', version: '0.0.0' });
+        const transport = new StdioClientTransport({
+            command: process.execPath,
+            args: [CLI_BIN, 'serve', '--mcp', 'stdio', '--project-dir', projectDir, '--user-id', 'smoke-user'],
+            stderr: 'pipe',
+        });
+        try {
+            await client.connect(transport);
+            const connectionTest = structuredContent(await client.callTool({ name: 'connection_test', arguments: { connectionId: 'warehouse' } }));
+            expect(connectionTest).toMatchObject({
+                id: 'warehouse',
+                connectionType: 'SQLITE',
+                ok: true,
+                tableCount: 2,
+            });
+            const trigger = structuredContent(await client.callTool({
+                name: 'scan_trigger',
+                arguments: {
+                    connectionId: 'warehouse',
+                    mode: 'structural',
+                    detectRelationships: false,
+                    dryRun: false,
+                },
+            }));
+            expect(trigger).toMatchObject({
+                status: 'done',
+                done: true,
+                connectionId: 'warehouse',
+                mode: 'structural',
+                dryRun: false,
+            });
+            expect(trigger.report.artifactPaths.manifestShards).toEqual(['semantic-layer/warehouse/_schema/public.yaml']);
+            expect(trigger.report.manifestShardsWritten).toBe(1);
+            const status = structuredContent(await client.callTool({ name: 'scan_status', arguments: { runId: trigger.runId } }));
+            expect(status).toMatchObject({
+                runId: trigger.runId,
+                status: 'done',
+                done: true,
+            });
+            expect(status.reportPath).toContain('scan-report.json');
+            const artifacts = structuredContent(await client.callTool({ name: 'scan_list_artifacts', arguments: { runId: trigger.runId } }));
+            expect(artifacts.artifacts).toEqual(expect.arrayContaining([
+                expect.objectContaining({ path: 'semantic-layer/warehouse/_schema/public.yaml', type: 'manifest_shard' }),
+                expect.objectContaining({ type: 'report' }),
+                expect.objectContaining({ type: 'raw_source' }),
+            ]));
+            const manifestArtifact = structuredContent(await client.callTool({
+                name: 'scan_read_artifact',
+                arguments: {
+                    runId: trigger.runId,
+                    path: 'semantic-layer/warehouse/_schema/public.yaml',
+                },
+            }));
+            expect(manifestArtifact).toMatchObject({
+                runId: trigger.runId,
+                path: 'semantic-layer/warehouse/_schema/public.yaml',
+                type: 'manifest_shard',
+            });
+            expect(manifestArtifact.content).toContain('orders:');
+            expect(manifestArtifact.content).toContain('source: formal');
+        }
+        finally {
+            await client.close();
+        }
+    });
+});