@kaelio/ktx 0.4.0 → 0.5.0

package/dist/setup-databases.test.js

@@ -1,7 +1,9 @@
 import { mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join, resolve } from 'node:path';
-import { initKtxProject, parseKtxProjectConfig, readKtxSetupState, writeKtxSetupState } from '@ktx/context/project';
+import { initKtxProject, loadKtxProject } from './context/project/project.js';
+import { parseKtxProjectConfig } from './context/project/config.js';
+import { readKtxSetupState, writeKtxSetupState } from './context/project/setup-config.js';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { runKtxSetupDatabasesStep, } from './setup-databases.js';
 function makeIo() {
@@ -34,15 +36,21 @@ function makePickerStubs(options = {}) {
             scopeCalls.push(args);
             const next = queue.shift();
             if (next === undefined || next === 'enable-all') {
-                const enabledTables = args.discovered.map((t) => `${t.schema}.${t.name}`);
+                const schemas = args.initialSchemas && args.initialSchemas.length > 0 ? [...args.initialSchemas] : [...args.schemas];
+                const discovered = await args.listTablesForSchemas(schemas);
+                const enabledTables = discovered.map((t) => `${t.schema}.${t.name}`);
                 const activeSchemas = args.supportsSchemaScope
-                    ? Array.from(new Set(args.discovered.map((t) => t.schema)))
+                    ? Array.from(new Set(discovered.map((t) => t.schema)))
                     : [];
                 return { kind: 'selected', activeSchemas, enabledTables };
             }
             if (next === 'back') {
                 return { kind: 'back' };
             }
+            await args.listTablesForSchemas(next.schemas);
+            if (next.tables === 'back') {
+                return { kind: 'back' };
+            }
             return {
                 kind: 'selected',
                 activeSchemas: args.supportsSchemaScope ? next.schemas : [],
@@ -58,7 +66,21 @@ function makePromptAdapter(options) {
     const passwordValues = [...(options.passwordValues ?? [])];
     return {
         multiselect: vi.fn(async () => multiselectValues.shift() ?? ['postgres']),
+        autocompleteMultiselect: vi.fn(async (options) => {
+            if (multiselectValues.length > 0) {
+                return multiselectValues.shift() ?? [];
+            }
+            if (options.initialValues && options.initialValues.length > 0) {
+                return options.initialValues;
+            }
+            return options.options.length > 0
+                ? options.options.map((option) => option.value)
+                : ['back'];
+        }),
         select: vi.fn(async ({ message }) => {
+            if (message.startsWith('Enable all tables in ') && message.includes(', or refine tables?')) {
+                return 'save';
+            }
             if (message.includes('How much database context should KTX build?')) {
                 const nextValue = selectValues[0];
                 return nextValue === 'fast' || nextValue === 'deep' || nextValue === 'back'
@@ -90,6 +112,7 @@ describe('setup databases step', () => {
         await initKtxProject({ projectDir: tempDir });
     });
     afterEach(async () => {
+        vi.unstubAllEnvs();
         await rm(tempDir, { recursive: true, force: true });
     });
     it('shows every supported database in the interactive checklist', async () => {
@@ -172,6 +195,38 @@ describe('setup databases step', () => {
         expect(prompts.multiselect).not.toHaveBeenCalled();
         expect(prompts.select).toHaveBeenCalledTimes(1);
     });
+    it('preserves context.depth when editing an existing database connection', async () => {
+        await writeFile(join(tempDir, 'ktx.yaml'), [
+            'connections:',
+            '  warehouse:',
+            '    driver: sqlite',
+            '    path: ./warehouse.sqlite',
+            '    context:',
+            '      depth: deep',
+            '',
+        ].join('\n'), 'utf-8');
+        const prompts = makePromptAdapter({
+            selectValues: ['edit', 'warehouse', 'continue'],
+            textValues: ['./warehouse.sqlite'],
+        });
+        const testConnection = vi.fn(async () => 0);
+        const scanConnection = vi.fn(async () => 0);
+        const io = makeIo();
+        const result = await runKtxSetupDatabasesStep({
+            projectDir: tempDir,
+            inputMode: 'auto',
+            skipDatabases: false,
+            databaseSchemas: [],
+            disableQueryHistory: true,
+        }, io.io, { prompts, testConnection, scanConnection });
+        expect(result.status, io.stderr()).toBe('ready');
+        const config = parseKtxProjectConfig(await readFile(join(tempDir, 'ktx.yaml'), 'utf-8'));
+        expect(config.connections.warehouse).toMatchObject({
+            driver: 'sqlite',
+            path: './warehouse.sqlite',
+            context: { depth: 'deep' },
+        });
+    });
     it('labels existing database connections with the database type', async () => {
         await writeFile(join(tempDir, 'ktx.yaml'), [
             'connections:',
@@ -230,6 +285,27 @@ describe('setup databases step', () => {
             context: { depth: 'fast' },
         });
     });
+    it('emits debug telemetry when setup writes a database connection', async () => {
+        vi.stubEnv('KTX_TELEMETRY_DEBUG', '1');
+        vi.stubEnv('CI', '');
+        const io = makeIo();
+        const prompts = makePromptAdapter({
+            selectValues: ['url'],
+            textValues: ['', 'env:DATABASE_URL'],
+        });
+        const result = await runKtxSetupDatabasesStep({
+            projectDir: tempDir,
+            inputMode: 'auto',
+            databaseDrivers: ['postgres'],
+            databaseSchemas: [],
+            skipDatabases: false,
+        }, io.io, { prompts, testConnection: vi.fn(async () => 0), scanConnection: vi.fn(async () => 0) });
+        expect(result.status).toBe('ready');
+        expect(io.stderr()).toContain('"event":"connection_added"');
+        expect(io.stderr()).toContain('"driver":"postgres"');
+        expect(io.stderr()).toContain('"isDemoConnection":false');
+        expect(io.stderr()).not.toContain(tempDir);
+    });
     it('tells users Escape goes back in free-text connection prompts', async () => {
         const prompts = makePromptAdapter({
             selectValues: ['url'],
@@ -335,16 +411,13 @@ describe('setup databases step', () => {
             {
                 driver: 'bigquery',
                 selectValues: ['no'],
-                textValues: ['', 'analytics', '/path/to/service-account.json', ''],
+                textValues: ['', '/path/to/service-account.json', ''],
                 expectedTextPrompts: [
                     {
                         message: connectionNamePrompt('BigQuery'),
                         placeholder: 'bigquery-warehouse',
                         initialValue: 'bigquery-warehouse',
                     },
-                    {
-                        message: 'BigQuery dataset\nFor example analytics.',
-                    },
                     {
                         message: 'Path to service account JSON file',
                     },
@@ -357,8 +430,8 @@ describe('setup databases step', () => {
             },
             {
                 driver: 'snowflake',
-                selectValues: ['no'],
-                textValues: ['', 'env:SNOWFLAKE_ACCOUNT', 'ANALYTICS_WH', 'ANALYTICS', '', 'env:SNOWFLAKE_USER', ''],
+                selectValues: ['password', 'no'],
+                textValues: ['', 'env:SNOWFLAKE_ACCOUNT', 'ANALYTICS_WH', 'ANALYTICS', 'env:SNOWFLAKE_USER', ''],
                 passwordValues: ['env:SNOWFLAKE_PASSWORD'],
                 expectedTextPrompts: [
                     {
@@ -375,11 +448,6 @@ describe('setup databases step', () => {
                     {
                         message: 'Snowflake database name',
                     },
-                    {
-                        message: 'Snowflake schema\nPress Enter for PUBLIC, or enter a schema name.',
-                        placeholder: 'PUBLIC',
-                        initialValue: 'PUBLIC',
-                    },
                     {
                         message: 'Snowflake username',
                     },
@@ -410,6 +478,8 @@ describe('setup databases step', () => {
                 prompts,
                 testConnection: vi.fn(async () => 0),
                 scanConnection: vi.fn(async () => 0),
+                listSchemas: vi.fn(async () => []),
+                listTables: vi.fn(async () => []),
             });
             expect(result.status).toBe('ready');
             expect(vi.mocked(prompts.text).mock.calls.map(([options]) => options)).toEqual(testCase.expectedTextPrompts.map((expectedPrompt) => ({
@@ -547,13 +617,15 @@ describe('setup databases step', () => {
         });
         const testConnection = vi.fn(async () => 0);
         const scanConnection = vi.fn(async () => 0);
+        const listSchemas = vi.fn(async () => []);
+        const listTables = vi.fn(async () => []);
         const result = await runKtxSetupDatabasesStep({
             projectDir: tempDir,
             inputMode: 'auto',
             skipDatabases: false,
             databaseSchemas: [],
             disableQueryHistory: true,
-        }, makeIo().io, { prompts, testConnection, scanConnection });
+        }, makeIo().io, { prompts, testConnection, scanConnection, listSchemas, listTables });
         expect(result).toEqual({
             status: 'ready',
             projectDir: tempDir,
@@ -735,7 +807,7 @@ describe('setup databases step', () => {
             placeholder: 'env:DATABASE_URL',
             initialValue: 'env:DATABASE_URL',
         });
-        expect(listTables).toHaveBeenCalledWith(tempDir, 'warehouse', ['analytics', 'public']);
+        expect(listTables).toHaveBeenCalledWith(tempDir, 'warehouse', ['analytics']);
         expect(testConnection).toHaveBeenCalledWith(tempDir, 'warehouse', expect.anything());
         expect(scanConnection).toHaveBeenCalledWith(tempDir, 'warehouse', expect.anything());
         const config = parseKtxProjectConfig(await readFile(join(tempDir, 'ktx.yaml'), 'utf-8'));
@@ -907,7 +979,7 @@ describe('setup databases step', () => {
             { schema: 'public', name: 'customers', kind: 'table' },
             { schema: 'public', name: 'orders', kind: 'table' },
         ]);
-        const pickers = makePickerStubs({ scopes: ['back'] });
+        const pickers = makePickerStubs({ scopes: [{ schemas: ['public'], tables: 'back' }] });
         const result = await runKtxSetupDatabasesStep({ projectDir: tempDir, inputMode: 'auto', skipDatabases: false, databaseSchemas: [] }, makeIo().io, {
             prompts,
             testConnection,
@@ -1188,6 +1260,64 @@ describe('setup databases step', () => {
             url: 'env:DATABASE_URL',
         });
     });
+    it('offers schema scope discovery for MySQL and writes selected schemas', async () => {
+        const prompts = makePromptAdapter({
+            multiselectValues: [['mysql']],
+            selectValues: ['url', 'continue'],
+            textValues: ['mysql-warehouse', 'mysql://reader@localhost/analytics'],
+        });
+        const listSchemas = vi.fn(async () => ['analytics', 'mart']);
+        const listTables = vi.fn(async (_projectDir, _connectionId, schemas) => (schemas ?? []).map((schema) => ({ schema, name: 'orders', kind: 'table' })));
+        const pickDatabaseScope = vi.fn(async (args) => {
+            const scopedArgs = args;
+            expect(args.schemaNoun).toBe('database');
+            expect(args.schemas).toEqual(['analytics', 'mart']);
+            expect(scopedArgs.schemaSuggestion.suggested).toEqual(new Set(['analytics', 'mart']));
+            return { kind: 'selected', activeSchemas: ['mart'], enabledTables: ['mart.orders'] };
+        });
+        await runKtxSetupDatabasesStep({ projectDir: tempDir, inputMode: 'auto', skipDatabases: false, databaseSchemas: [] }, makeIo().io, { prompts, testConnection: vi.fn(async () => 0), scanConnection: vi.fn(async () => 0), listSchemas, listTables, pickDatabaseScope });
+        const project = await loadKtxProject({ projectDir: tempDir });
+        expect(project.config.connections['mysql-warehouse']).toMatchObject({
+            driver: 'mysql',
+            schemas: ['mart'],
+            enabled_tables: ['mart.orders'],
+        });
+    });
+    it('maps ClickHouse scripted database schema input to databases and preserves database', async () => {
+        await runKtxSetupDatabasesStep({
+            projectDir: tempDir,
+            inputMode: 'disabled',
+            skipDatabases: false,
+            databaseDrivers: ['clickhouse'],
+            databaseConnectionId: 'clickhouse-warehouse',
+            databaseUrl: 'clickhouse://reader@localhost/analytics',
+            databaseSchemas: ['analytics', 'mart'],
+        }, makeIo().io, { testConnection: vi.fn(async () => 0), scanConnection: vi.fn(async () => 0) });
+        const project = await loadKtxProject({ projectDir: tempDir });
+        expect(project.config.connections['clickhouse-warehouse']).toMatchObject({
+            driver: 'clickhouse',
+            database: 'analytics',
+            databases: ['analytics', 'mart'],
+        });
+        expect(project.config.connections['clickhouse-warehouse']).not.toHaveProperty('schemas');
+    });
+    it('does not prompt for a bootstrap BigQuery dataset before scope discovery', async () => {
+        const prompts = makePromptAdapter({
+            multiselectValues: [['bigquery']],
+            selectValues: ['no', 'continue'],
+            textValues: ['bigquery-warehouse', '/tmp/service-account.json', 'US'],
+        });
+        const listSchemas = vi.fn(async () => ['analytics']);
+        const listTables = vi.fn(async () => [{ schema: 'analytics', name: 'orders', kind: 'table' }]);
+        const pickDatabaseScope = vi.fn(async () => ({
+            kind: 'selected',
+            activeSchemas: ['analytics'],
+            enabledTables: ['analytics.orders'],
+        }));
+        await runKtxSetupDatabasesStep({ projectDir: tempDir, inputMode: 'auto', skipDatabases: false, databaseSchemas: [] }, makeIo().io, { prompts, testConnection: vi.fn(async () => 0), scanConnection: vi.fn(async () => 0), listSchemas, listTables, pickDatabaseScope });
+        const textMessages = vi.mocked(prompts.text).mock.calls.map(([options]) => options.message);
+        expect(textMessages).not.toContain(textInputPrompt('BigQuery dataset\nFor example analytics.'));
+    });
     it('prompts for discovered Postgres schemas before the first scan', async () => {
         const io = makeIo();
         const prompts = makePromptAdapter({
@@ -1237,7 +1367,8 @@ describe('setup databases step', () => {
             connectionId: 'postgres-warehouse',
             schemaNoun: 'schema',
             schemaNounPlural: 'schemas',
-            defaultSchemas: ['orbit_analytics', 'orbit_raw'],
+            schemas: ['orbit_analytics', 'orbit_raw', 'public'],
+            schemaSuggestion: { excluded: new Set(), suggested: new Set() },
         });
         const config = parseKtxProjectConfig(await readFile(join(tempDir, 'ktx.yaml'), 'utf-8'));
         expect(config.connections['postgres-warehouse']).toMatchObject({
@@ -1245,6 +1376,72 @@ describe('setup databases step', () => {
         });
         expect(io.stdout()).toContain('✓ orbit_analytics, orbit_raw');
     });
+    it('falls back to comma-separated free-text when listSchemas fails interactively', async () => {
+        const io = makeIo();
+        const prompts = makePromptAdapter({
+            selectValues: ['url'],
+            textValues: ['', 'env:DATABASE_URL', 'orbit_analytics, orbit_raw'],
+        });
+        const testConnection = vi.fn(async () => 0);
+        const scanConnection = vi.fn(async () => 0);
+        const listSchemas = vi.fn(async () => {
+            throw new Error('permission denied to list schemas');
+        });
+        const listTables = vi.fn(async (_projectDir, _connectionId, schemas) => (schemas ?? []).map((schema) => ({ schema, name: 'events', kind: 'table' })));
+        const pickers = makePickerStubs({
+            scopes: [
+                {
+                    schemas: ['orbit_analytics', 'orbit_raw'],
+                    tables: ['orbit_analytics.events', 'orbit_raw.events'],
+                },
+            ],
+        });
+        const result = await runKtxSetupDatabasesStep({
+            projectDir: tempDir,
+            inputMode: 'auto',
+            databaseDrivers: ['postgres'],
+            databaseSchemas: [],
+            skipDatabases: false,
+        }, io.io, {
+            prompts,
+            testConnection,
+            scanConnection,
+            listSchemas,
+            listTables,
+            pickDatabaseScope: pickers.pickDatabaseScope,
+        });
+        expect(result.status).toBe('ready');
+        expect(io.stderr()).toContain('Could not discover postgresql schemas');
+        expect(vi.mocked(prompts.text).mock.calls.map(([options]) => options.message)).toContain(textInputPrompt('Enter schemas for postgres-warehouse as a comma-separated list (e.g. SALES, MARKETING).'));
+        expect(pickers.scopeCalls[0]).toMatchObject({
+            schemas: ['orbit_analytics', 'orbit_raw'],
+            initialSchemas: ['orbit_analytics', 'orbit_raw'],
+            schemaSuggestion: { suggested: new Set(['orbit_analytics', 'orbit_raw']) },
+        });
+    });
+    it('passes schemas and a lazy table callback to the scope picker instead of eager table discovery', async () => {
+        const listSchemas = vi.fn(async () => ['analytics', 'raw']);
+        const listTables = vi.fn(async (_projectDir, _connectionId, schemas) => (schemas ?? []).map((schema) => ({ schema, name: 'orders', kind: 'table' })));
+        const pickDatabaseScope = vi.fn(async (args) => {
+            const lazyArgs = args;
+            expect(lazyArgs.schemas).toEqual(['analytics', 'raw']);
+            expect(args).not.toHaveProperty('discovered');
+            expect(listTables).not.toHaveBeenCalled();
+            const tables = await lazyArgs.listTablesForSchemas(['analytics']);
+            expect(tables).toEqual([{ schema: 'analytics', name: 'orders', kind: 'table' }]);
+            return { kind: 'selected', activeSchemas: ['analytics'], enabledTables: ['analytics.orders'] };
+        });
+        await runKtxSetupDatabasesStep({ projectDir: tempDir, inputMode: 'auto', databaseDrivers: ['postgres'], skipDatabases: false, databaseSchemas: [] }, makeIo().io, {
+            prompts: makePromptAdapter({ selectValues: ['url'], textValues: ['', 'env:DATABASE_URL'] }),
+            testConnection: vi.fn(async () => 0),
+            scanConnection: vi.fn(async () => 0),
+            listSchemas,
+            listTables,
+            pickDatabaseScope,
+        });
+        expect(listTables).toHaveBeenCalledTimes(1);
+        expect(listTables).toHaveBeenCalledWith(tempDir, 'postgres-warehouse', ['analytics']);
+    });
     it('auto-selects all discovered Postgres schemas in non-interactive setup', async () => {
         const io = makeIo();
         const prompts = makePromptAdapter({});
@@ -1477,6 +1674,7 @@ describe('setup databases step', () => {
     });
     it('writes query history config for supported Snowflake databases after validation succeeds', async () => {
         const io = makeIo();
+        const historicSqlProbe = vi.fn(async () => ({ ok: true, lines: [] }));
         const result = await runKtxSetupDatabasesStep({
             projectDir: tempDir,
             inputMode: 'disabled',
@@ -1491,11 +1689,18 @@ describe('setup databases step', () => {
         }, io.io, {
             testConnection: vi.fn(async () => 0),
             scanConnection: vi.fn(async () => 0),
+            historicSqlProbe,
             prompts: makePromptAdapter({
-                textValues: ['env:SNOWFLAKE_ACCOUNT', 'WH', 'ANALYTICS', 'PUBLIC', 'reader', ''],
+                selectValues: ['password'],
+                textValues: ['env:SNOWFLAKE_ACCOUNT', 'WH', 'ANALYTICS', 'reader', ''],
                 passwordValues: ['env:SNOWFLAKE_PASSWORD'],
             }),
         });
+        expect(historicSqlProbe).toHaveBeenCalledWith(expect.objectContaining({
+            projectDir: tempDir,
+            connectionId: 'snowflake',
+            dialect: 'snowflake',
+        }));
         expect(result.status).toBe('ready');
         const configText = await readFile(join(tempDir, 'ktx.yaml'), 'utf-8');
         const config = parseKtxProjectConfig(configText);
@@ -1517,12 +1722,50 @@ describe('setup databases step', () => {
                 },
             },
         });
-        expect(config.connections.snowflake.historicSql).toBeUndefined();
         expect(configText).not.toContain('live-database');
         expect(configText).not.toContain('historic-sql');
         expect(configText).not.toMatch(/^\s+adapters:/m);
         expect(config.ingest.adapters).toEqual([]);
     });
+    it('configures Snowflake with RSA key-pair auth via setup wizard', async () => {
+        const io = makeIo();
+        const result = await runKtxSetupDatabasesStep({
+            projectDir: tempDir,
+            inputMode: 'disabled',
+            databaseDrivers: ['snowflake'],
+            databaseConnectionId: 'snowflake',
+            databaseSchemas: [],
+            skipDatabases: false,
+        }, io.io, {
+            testConnection: vi.fn(async () => 0),
+            scanConnection: vi.fn(async () => 0),
+            prompts: makePromptAdapter({
+                selectValues: ['rsa'],
+                textValues: [
+                    'env:SNOWFLAKE_ACCOUNT',
+                    'WH',
+                    'ANALYTICS',
+                    'reader',
+                    '~/.ssh/snowflake_rsa_key.p8',
+                    '',
+                ],
+                passwordValues: ['env:SNOWFLAKE_KEY_PASS'],
+            }),
+        });
+        expect(result.status).toBe('ready');
+        const config = parseKtxProjectConfig(await readFile(join(tempDir, 'ktx.yaml'), 'utf-8'));
+        expect(config.connections.snowflake).toMatchObject({
+            driver: 'snowflake',
+            authMethod: 'rsa',
+            account: 'env:SNOWFLAKE_ACCOUNT',
+            warehouse: 'WH',
+            database: 'ANALYTICS',
+            username: 'reader',
+            privateKey: 'file:~/.ssh/snowflake_rsa_key.p8', // pragma: allowlist secret
+            passphrase: 'env:SNOWFLAKE_KEY_PASS', // pragma: allowlist secret
+        });
+        expect(config.connections.snowflake.password).toBeUndefined();
+    });
     it('writes Postgres query history config with minExecutions and ignores window/redaction output', async () => {
         const io = makeIo();
         const result = await runKtxSetupDatabasesStep({
@@ -1564,7 +1807,6 @@ describe('setup databases step', () => {
                 },
             },
         });
-        expect(config.connections.warehouse.historicSql).toBeUndefined();
         const warehouseContext = config.connections.warehouse.context &&
             typeof config.connections.warehouse.context === 'object' &&
             !Array.isArray(config.connections.warehouse.context)
@@ -1683,7 +1925,6 @@ describe('setup databases step', () => {
                 },
             },
         });
-        expect(config.connections.analytics.historicSql).toBeUndefined();
         expect(configText).not.toContain('live-database');
         expect(configText).not.toContain('historic-sql');
         expect(configText).not.toMatch(/^\s+adapters:/m);
@@ -1724,83 +1965,56 @@ describe('setup databases step', () => {
                 },
             },
         });
-        expect(config.connections.warehouse.historicSql).toBeUndefined();
     });
-    it('migrates legacy historicSql to context.queryHistory during database setup', async () => {
-        await writeFile(join(tempDir, 'ktx.yaml'), [
-            'connections:',
-            '  warehouse:',
-            '    driver: postgres',
-            '    readonly: true',
-            '    historicSql:',
-            '      enabled: true',
-            '      dialect: postgres',
-            '      windowDays: 45',
-            '      minExecutions: 9',
-            '      concurrency: 3',
-            '      staleArchiveAfterDays: 120',
-            '      filters:',
-            '        dropTrivialProbes: true',
-            '        serviceAccounts:',
-            '          mode: exclude',
-            '          patterns:',
-            "            - '^svc_'",
-            '        orchestrators:',
-            '          mode: exclude',
-            '          patterns:',
-            '            - airflow',
-            '        dropFailedBelow: 2',
-            '      redactionPatterns:',
-            "        - '(?i)secret'",
-            '',
-        ].join('\n'), 'utf-8');
+    it('prints a non-blocking Postgres query history probe failure after connection test succeeds', async () => {
         const io = makeIo();
-        await expect(runKtxSetupDatabasesStep({
+        const historicSqlProbe = vi.fn(async () => ({
+            ok: false,
+            lines: [
+                '  FAIL pg_stat_statements extension is not installed in the connection database',
+                '  Fix: Run (against this database): CREATE EXTENSION pg_stat_statements;',
+                "  Fix: Ensure shared_preload_libraries includes 'pg_stat_statements'.",
+            ],
+        }));
+        const result = await runKtxSetupDatabasesStep({
             projectDir: tempDir,
             inputMode: 'disabled',
-            databaseConnectionIds: ['warehouse'],
+            databaseDrivers: ['postgres'],
+            databaseConnectionId: 'warehouse',
+            databaseUrl: 'env:DATABASE_URL',
             databaseSchemas: [],
+            enableQueryHistory: true,
             skipDatabases: false,
         }, io.io, {
             testConnection: vi.fn(async () => 0),
             scanConnection: vi.fn(async () => 0),
-            historicSqlProbe: vi.fn(async () => ({ ok: true, lines: [] })),
-        })).resolves.toMatchObject({ status: 'ready' });
-        const config = parseKtxProjectConfig(await readFile(join(tempDir, 'ktx.yaml'), 'utf-8'));
-        expect(config.connections.warehouse.historicSql).toBeUndefined();
-        expect(config.connections.warehouse.context).toMatchObject({
-            queryHistory: {
-                enabled: true,
-                windowDays: 45,
-                minExecutions: 9,
-                concurrency: 3,
-                staleArchiveAfterDays: 120,
-                filters: {
-                    dropTrivialProbes: true,
-                    serviceAccounts: { mode: 'exclude', patterns: ['^svc_'] },
-                    orchestrators: { mode: 'exclude', patterns: ['airflow'] },
-                    dropFailedBelow: 2,
-                },
-                redactionPatterns: ['(?i)secret'],
-            },
+            historicSqlProbe,
         });
+        expect(result.status).toBe('ready');
+        expect(historicSqlProbe).toHaveBeenCalledWith(expect.objectContaining({
+            projectDir: tempDir,
+            connectionId: 'warehouse',
+            dialect: 'postgres',
+        }));
+        expect(io.stdout()).toContain('Query history probe...');
+        expect(io.stdout()).not.toContain('Historic SQL probe...');
+        expect(io.stdout()).toContain('pg_stat_statements extension is not installed');
+        expect(io.stdout()).toContain('Setup written; query history will be skipped until fixed.');
     });
-    it('prints a non-blocking Postgres query history probe failure after connection test succeeds', async () => {
+    it('prints a non-blocking Snowflake query history probe failure with the grants remediation', async () => {
         const io = makeIo();
         const historicSqlProbe = vi.fn(async () => ({
             ok: false,
             lines: [
-                '  FAIL pg_stat_statements extension is not installed in the connection database',
-                '  Fix: Run (against this database): CREATE EXTENSION pg_stat_statements;',
-                "  Fix: Ensure shared_preload_libraries includes 'pg_stat_statements'.",
+                '  FAIL Snowflake role cannot read SNOWFLAKE.ACCOUNT_USAGE.QUERY_HISTORY',
+                '  Fix: Run (as ACCOUNTADMIN): GRANT IMPORTED PRIVILEGES ON DATABASE SNOWFLAKE TO ROLE <connection role>;',
             ],
         }));
         const result = await runKtxSetupDatabasesStep({
             projectDir: tempDir,
             inputMode: 'disabled',
-            databaseDrivers: ['postgres'],
+            databaseDrivers: ['snowflake'],
             databaseConnectionId: 'warehouse',
-            databaseUrl: 'env:DATABASE_URL',
             databaseSchemas: [],
             enableQueryHistory: true,
             skipDatabases: false,
@@ -1808,17 +2022,21 @@ describe('setup databases step', () => {
             testConnection: vi.fn(async () => 0),
             scanConnection: vi.fn(async () => 0),
             historicSqlProbe,
+            prompts: makePromptAdapter({
+                textValues: ['env:SNOWFLAKE_ACCOUNT', 'WH', 'ANALYTICS', 'reader', ''],
+                passwordValues: ['env:SNOWFLAKE_PASSWORD'],
+            }),
         });
         expect(result.status).toBe('ready');
         expect(historicSqlProbe).toHaveBeenCalledWith(expect.objectContaining({
             projectDir: tempDir,
             connectionId: 'warehouse',
-            dialect: 'postgres',
+            dialect: 'snowflake',
         }));
         expect(io.stdout()).toContain('Query history probe...');
-        expect(io.stdout()).not.toContain('Historic SQL probe...');
-        expect(io.stdout()).toContain('pg_stat_statements extension is not installed');
-        expect(io.stdout()).toContain('Setup written; first ingest run will fail until fixed.');
+        expect(io.stdout()).toContain('Snowflake role cannot read SNOWFLAKE.ACCOUNT_USAGE.QUERY_HISTORY');
+        expect(io.stdout()).toContain('GRANT IMPORTED PRIVILEGES ON DATABASE SNOWFLAKE');
+        expect(io.stdout()).toContain('Setup written; query history will be skipped until fixed.');
     });
     it('does not run the query history probe when the regular connection test fails', async () => {
         const io = makeIo();

package/dist/setup-demo-tour.d.ts

@@ -3,12 +3,15 @@ import { ensureSeededDemoProject } from './demo-assets.js';
 import type { KtxPublicIngestPlanTarget } from './public-ingest.js';
 import type { KtxSetupAgentsResult } from './setup-agents.js';
 import { runKtxSetupAgentsStep } from './setup-agents.js';
+/** @internal */
 export declare function renderDemoBanner(projectDir?: string): string;
+/** @internal */
 export declare function renderDemoCardContent(title: string, selections: string[]): string;
+/** @internal */
 export declare function renderDemoAgentTransition(): string;
+/** @internal */
 export declare function renderDemoCompletionSummary(projectDir: string, agentInstalled: boolean): string;
-export declare function waitForDemoNavigation(stdin?: NodeJS.ReadStream): Promise<'forward' | 'back'>;
-export declare function renderDemoCard(title: string, selections: string[], io: KtxCliIo, stdin?: NodeJS.ReadStream, waitNav?: (stdin?: NodeJS.ReadStream) => Promise<'forward' | 'back'>, projectDir?: string): Promise<'forward' | 'back'>;
+/** @internal */
 export interface DemoReplayEvent {
     delayMs: number;
     connectionId: string;
@@ -16,12 +19,13 @@ export interface DemoReplayEvent {
     detailLine: string | null;
     summaryText: string | null;
 }
+/** @internal */
 export declare const DEMO_REPLAY_TARGETS: {
     readonly primarySources: readonly [KtxPublicIngestPlanTarget];
     readonly contextSources: readonly [KtxPublicIngestPlanTarget, KtxPublicIngestPlanTarget, KtxPublicIngestPlanTarget];
 };
+/** @internal */
 export declare function buildDemoReplayTimeline(): DemoReplayEvent[];
-export declare function runDemoContextReplay(io: KtxCliIo, stdin?: NodeJS.ReadStream): Promise<'forward' | 'back'>;
 export interface DemoTourDeps {
     agents?: (args: Parameters<typeof runKtxSetupAgentsStep>[0], io: KtxCliIo) => Promise<KtxSetupAgentsResult>;
     waitForNavigation?: (stdin?: NodeJS.ReadStream) => Promise<'forward' | 'back'>;
@@ -30,4 +34,5 @@ export interface DemoTourDeps {
 }
 export declare function runDemoTour(args: {
     inputMode: 'auto' | 'disabled';
+    cliVersion?: string;
 }, io: KtxCliIo, deps?: DemoTourDeps): Promise<number>;