@kaelio/ktx 0.5.0 → 0.6.0

package/dist/setup-embeddings.js

@@ -4,8 +4,9 @@ import { serializeKtxProjectConfig } from './context/project/config.js';
 import { loadKtxProject } from './context/project/project.js';
 import { markKtxSetupStateStepComplete, readKtxSetupState } from './context/project/setup-config.js';
 import { runKtxEmbeddingHealthCheck } from './llm/embedding-health.js';
-import { createStaticCliSpinner } from './clack.js';
+import { createStaticCliSpinner, errorMessage, writePrefixedLines } from './clack.js';
 import { ensureManagedLocalEmbeddingsDaemon, managedLocalEmbeddingHealthConfig, } from './managed-local-embeddings.js';
+import { ManagedPythonDaemonStartError } from './managed-python-daemon.js';
 import { withTextInputNavigation } from './prompt-navigation.js';
 import { envCredentialReference, writeProjectLocalSecretReference } from './setup-secrets.js';
 import { createKtxSetupPromptAdapter, } from './setup-prompts.js';
@@ -305,7 +306,14 @@ export async function runKtxSetupEmbeddingsStep(args, io, deps = {}) {
                 });
             }
             catch (error) {
-                io.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+                const write = (chunk) => io.stderr.write(chunk);
+                if (error instanceof ManagedPythonDaemonStartError) {
+                    const tail = await readLocalEmbeddingDaemonStderrTail(error.stderrLog);
+                    writePrefixedLines(write, localEmbeddingSetupMessage(error.detail, tail));
+                }
+                else {
+                    writePrefixedLines(write, errorMessage(error));
+                }
                 return { status: 'failed', projectDir: args.projectDir };
             }
         }

package/dist/setup-runtime.js

@@ -1,5 +1,6 @@
 import { loadKtxProject } from './context/project/project.js';
 import { markKtxSetupStateStepComplete } from './context/project/setup-config.js';
+import { errorMessage, writePrefixedLines } from './clack.js';
 import { ensureManagedLocalEmbeddingsDaemon, } from './managed-local-embeddings.js';
 import { ensureManagedPythonCommandRuntime, } from './managed-python-command.js';
 import { resolveProjectRuntimeRequirements, } from './runtime-requirements.js';
@@ -39,7 +40,7 @@ export async function runKtxSetupRuntimeStep(args, io, deps = {}) {
         }
     }
     catch (error) {
-        io.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        writePrefixedLines((chunk) => io.stderr.write(chunk), errorMessage(error));
         return { status: 'failed', projectDir: args.projectDir, requirements };
     }
     await markKtxSetupStateStepComplete(args.projectDir, 'runtime');

package/dist/setup-sources.js

@@ -16,6 +16,7 @@ import { parseMetricflowFiles } from './context/ingest/adapters/metricflow/deep-
 import { serializeKtxProjectConfig } from './context/project/config.js';
 import { loadKtxProject } from './context/project/project.js';
 import { markKtxSetupStateStepComplete } from './context/project/setup-config.js';
+import { errorMessage, writePrefixedLines } from './clack.js';
 import { pickNotionRootPages } from './notion-page-picker.js';
 import { runKtxSourceMapping } from './source-mapping.js';
 import { withMultiselectNavigation, withTextInputNavigation } from './prompt-navigation.js';
@@ -1627,7 +1628,7 @@ export async function runKtxSetupSourcesStep(args, io, deps = {}) {
         }
     }
     catch (error) {
-        io.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        writePrefixedLines((chunk) => io.stderr.write(chunk), errorMessage(error));
         return { status: 'failed', projectDir: args.projectDir };
     }
 }

package/dist/setup.js

@@ -23,6 +23,7 @@ import { runKtxSetupRuntimeStep, } from './setup-runtime.js';
 import { createKtxSetupPromptAdapter, createKtxSetupUiAdapter, } from './setup-prompts.js';
 import { readKtxSetupContextState, runKtxSetupContextStep, setupContextStatusFromState, } from './setup-context.js';
 const SOURCE_DRIVERS = new Set(['dbt', 'metricflow', 'metabase', 'looker', 'lookml', 'notion']);
+const KTX_DOCS_URL = 'https://docs.kaelio.com/ktx';
 function createEntryMenuPromptAdapter() {
     return createKtxSetupPromptAdapter({
         selectCancelValue: 'exit',
@@ -330,6 +331,7 @@ export async function runKtxSetup(args, io, deps = {}) {
 async function runKtxSetupInner(args, io, deps = {}) {
     const setupUi = deps.setupUi ?? createKtxSetupUiAdapter();
     setupUi.intro('KTX setup', io);
+    setupUi.note(KTX_DOCS_URL, '📚 Docs', io);
     let entryAction;
     let projectResult;
     let agentNextActions;
@@ -400,6 +402,7 @@ async function runKtxSetupInner(args, io, deps = {}) {
         const shouldRunContext = !agentOnlySetup && (!runOnly || runOnly === 'context');
         const shouldRunAgents = agentsRequested || !runOnly || runOnly === 'agents';
         const showPromptInstructions = projectResult.confirmedCreation !== true;
+        let skipSourcesFromDatabaseMenu = false;
         const setupSteps = agentOnlySetup
             ? []
             : ['models', 'embeddings', 'databases', 'sources', 'runtime', 'context'];
@@ -414,8 +417,9 @@ async function runKtxSetupInner(args, io, deps = {}) {
                 return !args.skipEmbeddings && shouldRunEmbeddings;
             if (step === 'databases')
                 return !args.skipDatabases && shouldRunDatabases;
-            if (step === 'sources')
-                return args.skipSources !== true && shouldRunSources;
+            if (step === 'sources') {
+                return args.skipSources !== true && !skipSourcesFromDatabaseMenu && shouldRunSources;
+            }
             if (step === 'runtime')
                 return shouldRunRuntime;
             if (step === 'context')
@@ -472,7 +476,7 @@ async function runKtxSetupInner(args, io, deps = {}) {
             else if (step === 'databases') {
                 const databasesRunner = deps.databases ??
                     ((databaseArgs, databaseIo) => runKtxSetupDatabasesStep(databaseArgs, databaseIo, deps.databasesDeps));
-                stepResult = await databasesRunner({
+                const databaseResult = await databasesRunner({
                     projectDir: projectResult.projectDir,
                     inputMode: args.inputMode,
                     ...(args.databaseDrivers ? { databaseDrivers: args.databaseDrivers } : {}),
@@ -494,6 +498,8 @@ async function runKtxSetupInner(args, io, deps = {}) {
                         : {}),
                     skipDatabases: args.skipDatabases || !shouldRunDatabases,
                 }, io);
+                skipSourcesFromDatabaseMenu = databaseResult.status === 'ready' && databaseResult.skipSources === true;
+                stepResult = databaseResult;
             }
             else if (step === 'sources') {
                 const sourcesRunner = deps.sources ?? ((sourceArgs, sourceIo) => runKtxSetupSourcesStep(sourceArgs, sourceIo, deps.sourcesDeps));
@@ -519,7 +525,7 @@ async function runKtxSetupInner(args, io, deps = {}) {
                     ...(args.notionCrawlMode ? { notionCrawlMode: args.notionCrawlMode } : {}),
                     ...(args.notionRootPageIds ? { notionRootPageIds: args.notionRootPageIds } : {}),
                     runInitialSourceIngest: args.runInitialSourceIngest ?? false,
-                    skipSources: args.skipSources === true || !shouldRunSources,
+                    skipSources: args.skipSources === true || !shouldRunSources || skipSourcesFromDatabaseMenu,
                 }, io);
             }
             else if (step === 'runtime') {

package/dist/skills/historic_sql_patterns/SKILL.md

@@ -15,8 +15,7 @@ Use this skill when the WorkUnit raw file is a `patterns-input/part-0001.json` s
 3. Call `read_raw_file` for that exact raw file path.
 4. Identify recurring analytical intents that span at least two tables and have repeated usage signal.
 5. Emit one `pattern` evidence object per durable cross-table intent by calling `emit_historic_sql_evidence`.
-6. Set each evidence object's `rawPath` to the exact raw file path read in step 3.
-7. Stop after all pattern evidence has been emitted.
+6. Stop after all pattern evidence has been emitted.
 
 Every join column mentioned in pattern descriptions must be verified via
 entity_details for both sides of the join.
@@ -56,7 +55,6 @@ Each call to `emit_historic_sql_evidence` must use this shape:
 ```json
 {
   "kind": "pattern",
-  "rawPath": "patterns-input/part-0001.json",
   "pattern": {
     "slug": "order-lifecycle-analysis",
     "title": "Order Lifecycle Analysis",

package/dist/skills/historic_sql_table_digest/SKILL.md

@@ -53,7 +53,6 @@ Call `emit_historic_sql_evidence` with this shape:
 {
   "kind": "table_usage",
   "table": "public.orders",
-  "rawPath": "tables/public.orders.json",
   "usage": {
     "narrative": "Orders are repeatedly queried for paid/refunded lifecycle analysis and customer-level rollups.",
     "frequencyTier": "high",

package/dist/skills/sl/SKILL.md

@@ -124,7 +124,7 @@ Every standalone column requires `name` and `type`. Overlays have computed colum
 
 ### Grain
 
-`grain: [col_a, col_b]` - the set of columns that uniquely identify one row. The query engine uses grain to prevent fan-out in joins. Overlays inherit grain from the manifest unless they override.
+`grain: [col_a, col_b]` - the set of columns that uniquely identify one row. The query engine uses grain to prevent fanout in joins. Overlays inherit grain from the manifest unless they override.
 
 ### Joins
 
@@ -177,7 +177,7 @@ The reverse edge (wiki pages that cite this source) is derived automatically fro
 
 ## Part 2 - Querying via `sl_query`
 
-The `sl_query` tool generates correct SQL from a structured query. It handles joins, fan-out prevention, aggregation correctness, and filter classification automatically. Prefer it over writing raw SQL whenever the SL has the relevant sources.
+The `sl_query` tool generates correct SQL from a structured query. It handles joins, fanout prevention, aggregation correctness, and filter classification automatically. Prefer it over writing raw SQL whenever the SL has the relevant sources.
 
 ### When to prefer sl_query over raw SQL
 

package/dist/sql.js

@@ -11,16 +11,12 @@ function sqlAnalysisDialectForDriver(driver) {
     const normalized = String(driver ?? '').trim().toLowerCase();
     const map = {
         postgres: 'postgres',
-        postgresql: 'postgres',
         bigquery: 'bigquery',
         snowflake: 'snowflake',
         mysql: 'mysql',
         sqlserver: 'tsql',
-        mssql: 'tsql',
         sqlite: 'sqlite',
-        sqlite3: 'sqlite',
         clickhouse: 'clickhouse',
-        redshift: 'redshift',
     };
     return map[normalized] ?? 'postgres';
 }

package/dist/status-project.d.ts

@@ -1,6 +1,6 @@
-import type { KtxConfigIssue, KtxProjectConnectionConfig } from './context/project/config.js';
+import type { KtxConfigIssue } from './context/project/config.js';
 import type { KtxLocalProject } from './context/project/project.js';
-import type { PostgresPgssProbeResult } from './context/ingest/adapters/historic-sql/types.js';
+import { type HistoricSqlReadinessProbe } from './context/ingest/historic-sql-probes.js';
 import type { DoctorCheck } from './doctor.js';
 type ProjectStatusLevel = 'ok' | 'warn' | 'fail' | 'skipped';
 type ProjectVerdict = 'ready' | 'partial' | 'blocked';
@@ -131,24 +131,9 @@ export interface ProjectStatus {
         validationConcurrency: number;
     };
 }
-interface QueryHistoryProbeInput {
-    projectDir: string;
-    connectionId: string;
-    connection: KtxProjectConnectionConfig;
-    env: NodeJS.ProcessEnv;
-}
-interface GenericProbeResult {
-    warnings: string[];
-    info?: string[];
-}
-type PostgresQueryHistoryProbe = (input: QueryHistoryProbeInput) => Promise<PostgresPgssProbeResult>;
-type SnowflakeQueryHistoryProbe = (input: QueryHistoryProbeInput) => Promise<GenericProbeResult>;
-type BigQueryQueryHistoryProbe = (input: QueryHistoryProbeInput) => Promise<GenericProbeResult>;
 export interface BuildProjectStatusOptions {
     env?: NodeJS.ProcessEnv;
-    postgresQueryHistoryProbe?: PostgresQueryHistoryProbe;
-    snowflakeQueryHistoryProbe?: SnowflakeQueryHistoryProbe;
-    bigqueryQueryHistoryProbe?: BigQueryQueryHistoryProbe;
+    queryHistoryReadinessProbe?: HistoricSqlReadinessProbe;
     claudeCodeAuthProbe?: ClaudeCodeAuthProbe;
     configIssues?: KtxConfigIssue[];
     fast?: boolean;

package/dist/status-project.js

@@ -3,13 +3,11 @@ import { basename, join } from 'node:path';
 import { runClaudeCodeAuthProbe } from './context/llm/claude-code-runtime.js';
 import { ktxLocalStateDbPath } from './context/project/local-state-db.js';
 import { isQueryHistoryEnabled, queryHistoryDialectForConnection, } from './context/ingest/adapters/historic-sql/connection-dialect.js';
+import { historicSqlProbeCatalogName, runHistoricSqlReadinessProbe, } from './context/ingest/historic-sql-probes.js';
 import { formatClaudeCodePromptCachingFix, formatClaudeCodePromptCachingWarning, ignoredClaudeCodePromptCachingFields, } from './claude-code-prompt-caching.js';
 import { bold as _bold, dim as _dim, green, red, yellow, } from './io/symbols.js';
 import { KTX_NEXT_STEP_DIRECT_COMMANDS } from './next-steps.js';
 const PROJECT_READY_COMMANDS = KTX_NEXT_STEP_DIRECT_COMMANDS.map((step) => step.command);
-function hasOwnField(value, key) {
-    return Object.prototype.hasOwnProperty.call(value, key);
-}
 function resolveRef(value, env) {
     if (typeof value !== 'string')
         return { resolved: '', via: 'missing' };
@@ -26,6 +24,12 @@ function resolveRef(value, env) {
     }
     return { resolved: trimmed, via: 'literal' };
 }
+function failureDetail(error) {
+    if (error instanceof Error && error.message.trim().length > 0) {
+        return error.message.trim().split('\n')[0] ?? error.message.trim();
+    }
+    return String(error);
+}
 function envHint(value) {
     if (typeof value === 'string' && value.trim().startsWith('env:')) {
         return value.trim().slice(4).trim();
@@ -165,7 +169,6 @@ function buildConnectionStatus(name, conn, env) {
     const warn = (detail, fix) => ({ name, driver, status: 'warn', detail, fix });
     switch (driver) {
         case 'postgres':
-        case 'postgresql':
         case 'mysql':
         case 'clickhouse':
         case 'sqlserver': {
@@ -237,180 +240,11 @@ function buildConnectionStatus(name, conn, env) {
             return { name, driver, status: 'ok', detail: 'configured' };
     }
 }
-function failureDetail(error) {
-    if (error instanceof Error && error.message.trim().length > 0) {
-        return error.message.trim().split('\n')[0] ?? error.message.trim();
-    }
-    return String(error);
-}
-function postgresReadinessDetail(result) {
-    const warningText = result.warnings.length > 0 ? ` with warnings: ${result.warnings.join('; ')}` : '';
-    const info = result.info ?? [];
-    const infoText = info.length > 0 ? `; info: ${info.join('; ')}` : '';
-    return `pg_stat_statements ready (${result.pgServerVersion})${warningText}${infoText}`;
-}
-function genericReadinessDetail(label, result) {
-    const warningText = result.warnings.length > 0 ? ` with warnings: ${result.warnings.join('; ')}` : '';
-    const info = result.info ?? [];
-    const infoText = info.length > 0 ? `; info: ${info.join('; ')}` : '';
-    return `${label} ready${warningText}${infoText}`;
-}
-function probeFailureFix(error, dialect, connectionId, projectDir) {
-    if (error instanceof Error && error.name === 'HistoricSqlExtensionMissingError' && 'remediation' in error) {
-        return String(error.remediation);
-    }
-    if (error instanceof Error && error.name === 'HistoricSqlGrantsMissingError' && 'remediation' in error) {
-        return String(error.remediation);
-    }
-    if (error instanceof Error && error.name === 'HistoricSqlVersionUnsupportedError') {
-        return 'Use PostgreSQL 14 or newer, or disable query history for this connection';
-    }
-    return `Fix connections.${connectionId} ${dialect} settings, then rerun \`ktx status --project-dir ${projectDir}\``;
-}
-async function defaultPostgresQueryHistoryProbe(input) {
-    const [{ PostgresPgssReader }, { KtxPostgresHistoricSqlQueryClient }, { isKtxPostgresConnectionConfig }] = await Promise.all([
-        import('./context/ingest/adapters/historic-sql/postgres-pgss-reader.js'),
-        import('./connectors/postgres/historic-sql-query-client.js'),
-        import('./connectors/postgres/connector.js'),
-    ]);
-    const inputDriver = input.connection.driver ?? 'unknown';
-    if (!isKtxPostgresConnectionConfig(input.connection)) {
-        throw new Error(`Native PostgreSQL connector cannot run driver "${inputDriver}"`);
-    }
-    const client = new KtxPostgresHistoricSqlQueryClient({
-        connectionId: input.connectionId,
-        connection: input.connection,
-        env: input.env,
-    });
-    try {
-        return await new PostgresPgssReader().probe(client);
-    }
-    finally {
-        await client.cleanup();
-    }
-}
-async function defaultSnowflakeQueryHistoryProbe(input) {
-    const [{ SnowflakeHistoricSqlQueryHistoryReader }, { KtxSnowflakeHistoricSqlQueryClient }, { isKtxSnowflakeConnectionConfig }] = await Promise.all([
-        import('./context/ingest/adapters/historic-sql/snowflake-query-history-reader.js'),
-        import('./connectors/snowflake/historic-sql-query-client.js'),
-        import('./connectors/snowflake/connector.js'),
-    ]);
-    const inputDriver = input.connection.driver ?? 'unknown';
-    if (!isKtxSnowflakeConnectionConfig(input.connection)) {
-        throw new Error(`Native Snowflake connector cannot run driver "${inputDriver}"`);
-    }
-    const client = new KtxSnowflakeHistoricSqlQueryClient({
-        connectionId: input.connectionId,
-        connection: input.connection,
-        projectDir: input.projectDir,
-        env: input.env,
-    });
-    try {
-        return await new SnowflakeHistoricSqlQueryHistoryReader().probe(client);
-    }
-    finally {
-        await client.cleanup();
-    }
-}
-async function defaultBigQueryQueryHistoryProbe(input) {
-    const [{ BigQueryHistoricSqlQueryHistoryReader }, { KtxBigQueryScanConnector, isKtxBigQueryConnectionConfig }, { resolveKtxConfigReference },] = await Promise.all([
-        import('./context/ingest/adapters/historic-sql/bigquery-query-history-reader.js'),
-        import('./connectors/bigquery/connector.js'),
-        import('./context/core/config-reference.js'),
-    ]);
-    const inputDriver = input.connection.driver ?? 'unknown';
-    if (!isKtxBigQueryConnectionConfig(input.connection)) {
-        throw new Error(`Native BigQuery connector cannot run driver "${inputDriver}"`);
-    }
-    const rawCredentials = typeof input.connection.credentials_json === 'string' ? input.connection.credentials_json : '';
-    const resolvedCredentials = resolveKtxConfigReference(rawCredentials, input.env);
-    if (!resolvedCredentials) {
-        throw new Error(`Query history BigQuery connection ${input.connectionId} requires credentials_json`);
-    }
-    const parsed = JSON.parse(resolvedCredentials);
-    if (typeof parsed.project_id !== 'string' || parsed.project_id.trim().length === 0) {
-        throw new Error(`Query history BigQuery connection ${input.connectionId} requires credentials_json.project_id`);
-    }
-    const region = typeof input.connection.location === 'string' && input.connection.location.trim().length > 0
-        ? input.connection.location.trim()
-        : 'us';
-    const connector = new KtxBigQueryScanConnector({
-        connectionId: input.connectionId,
-        connection: input.connection,
-    });
-    try {
-        return await new BigQueryHistoricSqlQueryHistoryReader({
-            projectId: parsed.project_id,
-            region,
-        }).probe({
-            async executeQuery(sql) {
-                const result = await connector.executeReadOnly({ connectionId: input.connectionId, sql }, {});
-                return {
-                    headers: result.headers,
-                    rows: result.rows,
-                    totalRows: result.totalRows,
-                };
-            },
-        });
-    }
-    finally {
-        await connector.cleanup();
-    }
-}
-function postgresProbeDispatch(input, probe) {
-    return {
-        label: 'postgres',
-        spinnerLabel: `Probing pg_stat_statements on ${input.connectionId}`,
-        fastSkipDetail: 'pg_stat_statements probe skipped (--fast)',
-        run: async () => {
-            const result = await probe(input);
-            return {
-                status: result.warnings.length > 0 ? 'warn' : 'ok',
-                detail: postgresReadinessDetail(result),
-                ...(result.warnings.length > 0
-                    ? {
-                        fix: `Update the Postgres parameter group or config, then rerun \`ktx status --project-dir ${input.projectDir}\``,
-                    }
-                    : {}),
-            };
-        },
-    };
-}
-function snowflakeProbeDispatch(input, probe) {
-    return {
-        label: 'snowflake',
-        spinnerLabel: `Probing SNOWFLAKE.ACCOUNT_USAGE.QUERY_HISTORY on ${input.connectionId}`,
-        fastSkipDetail: 'SNOWFLAKE.ACCOUNT_USAGE.QUERY_HISTORY probe skipped (--fast)',
-        run: async () => {
-            const result = await probe(input);
-            return {
-                status: result.warnings.length > 0 ? 'warn' : 'ok',
-                detail: genericReadinessDetail('SNOWFLAKE.ACCOUNT_USAGE.QUERY_HISTORY', result),
-            };
-        },
-    };
-}
-function bigqueryProbeDispatch(input, probe) {
-    return {
-        label: 'bigquery',
-        spinnerLabel: `Probing INFORMATION_SCHEMA.JOBS_BY_PROJECT on ${input.connectionId}`,
-        fastSkipDetail: 'INFORMATION_SCHEMA.JOBS_BY_PROJECT probe skipped (--fast)',
-        run: async () => {
-            const result = await probe(input);
-            return {
-                status: result.warnings.length > 0 ? 'warn' : 'ok',
-                detail: genericReadinessDetail('INFORMATION_SCHEMA.JOBS_BY_PROJECT', result),
-            };
-        },
-    };
-}
 async function buildQueryHistoryStatus(project, options) {
     const targets = Object.entries(project.config.connections)
         .filter(([, connection]) => isQueryHistoryEnabled(connection))
         .sort(([left], [right]) => left.localeCompare(right));
-    const postgresProbe = options.postgresQueryHistoryProbe ?? defaultPostgresQueryHistoryProbe;
-    const snowflakeProbe = options.snowflakeQueryHistoryProbe ?? defaultSnowflakeQueryHistoryProbe;
-    const bigqueryProbe = options.bigqueryQueryHistoryProbe ?? defaultBigQueryQueryHistoryProbe;
+    const probe = options.queryHistoryReadinessProbe ?? runHistoricSqlReadinessProbe;
     const env = options.env ?? process.env;
     const statuses = [];
     for (const [connectionId, connection] of targets) {
@@ -427,51 +261,64 @@ async function buildQueryHistoryStatus(project, options) {
             });
             continue;
         }
-        const probeInput = {
-            projectDir: project.projectDir,
-            connectionId,
-            connection,
-            env,
-        };
-        const dispatched = dialect === 'postgres'
-            ? postgresProbeDispatch(probeInput, postgresProbe)
-            : dialect === 'snowflake'
-                ? snowflakeProbeDispatch(probeInput, snowflakeProbe)
-                : bigqueryProbeDispatch(probeInput, bigqueryProbe);
+        const catalogName = historicSqlProbeCatalogName(dialect);
         if (options.fast === true) {
             statuses.push({
                 connection: connectionId,
                 driver,
                 dialect,
                 status: 'skipped',
-                detail: dispatched.fastSkipDetail,
+                detail: `${catalogName} probe skipped (--fast)`,
             });
             continue;
         }
-        try {
-            const outcome = await withSpinner(options.useSpinner === true, dispatched.spinnerLabel, dispatched.run);
+        const outcome = await withSpinner(options.useSpinner === true, `Probing ${catalogName} on ${connectionId}`, () => probe({
+            projectDir: project.projectDir,
+            connectionId,
+            connection,
+            env,
+        }));
+        if (!outcome) {
             statuses.push({
                 connection: connectionId,
                 driver,
-                dialect,
-                ...outcome,
+                dialect: driver,
+                status: 'fail',
+                detail: `query history is not supported for driver "${driver}"`,
+                fix: `Disable connections.${connectionId}.context.queryHistory, or use a postgres, snowflake, or bigquery connection`,
             });
+            continue;
         }
-        catch (error) {
+        if (outcome.ok) {
+            const { detail, warnings } = outcome.runner.formatSuccessDetail(outcome.result);
             statuses.push({
                 connection: connectionId,
                 driver,
                 dialect,
-                status: 'fail',
-                detail: failureDetail(error),
-                fix: probeFailureFix(error, dispatched.label, connectionId, project.projectDir),
+                status: warnings.length > 0 ? 'warn' : 'ok',
+                detail,
+                ...(dialect === 'postgres' && warnings.length > 0
+                    ? {
+                        fix: `Update the Postgres parameter group or config, then rerun \`ktx status --project-dir ${project.projectDir}\``,
+                    }
+                    : {}),
             });
+            continue;
         }
+        const advice = outcome.runner.fixAdvice(outcome.error);
+        statuses.push({
+            connection: connectionId,
+            driver,
+            dialect,
+            status: 'fail',
+            detail: advice.failHeadline,
+            fix: advice.remediation,
+        });
     }
     return statuses;
 }
 const ADAPTER_DRIVER_REQUIREMENT = {
-    'live-database': ['postgres', 'postgresql', 'mysql', 'snowflake', 'bigquery', 'clickhouse', 'sqlite', 'sqlserver'],
+    'live-database': ['postgres', 'mysql', 'snowflake', 'bigquery', 'clickhouse', 'sqlite', 'sqlserver'],
     dbt: ['dbt', 'dbt-core', 'dbt-cloud'],
     notion: ['notion'],
     metabase: ['metabase'],
@@ -501,27 +348,6 @@ function buildStorageStatus(config) {
 }
 function buildWarnings(config, connections, llm, embeddings) {
     const warnings = [];
-    for (const [connectionId, connection] of Object.entries(config.connections)) {
-        const driver = String(connection.driver ?? '').toLowerCase();
-        if (hasOwnField(connection, 'readonly')) {
-            warnings.push({
-                message: `connections.${connectionId}.readonly is no longer used.`,
-                fix: `Remove connections.${connectionId}.readonly from ktx.yaml.`,
-            });
-        }
-        if ((driver === 'sqlite' || driver === 'sqlite3') && hasOwnField(connection, 'file_path')) {
-            warnings.push({
-                message: `connections.${connectionId}.file_path was removed.`,
-                fix: `Rename connections.${connectionId}.file_path to path.`,
-            });
-        }
-        if (driver === 'notion' && hasOwnField(connection, 'last_successful_cursor')) {
-            warnings.push({
-                message: `connections.${connectionId}.last_successful_cursor is local sync state.`,
-                fix: 'Remove it from ktx.yaml. KTX stores the Notion cursor in .ktx/db.sqlite.',
-            });
-        }
-    }
     for (const adapter of config.ingest.adapters) {
         const requiredDrivers = ADAPTER_DRIVER_REQUIREMENT[adapter];
         if (!requiredDrivers)

package/dist/telemetry/events.d.ts

@@ -330,8 +330,8 @@ export declare const telemetryEventSchemas: {
         isCi: z.ZodBoolean;
         reason: z.ZodEnum<{
             crash: "crash";
-            signal: "signal";
             request: "request";
+            signal: "signal";
         }>;
         uptimeMs: z.ZodNumber;
     }, z.core.$strict>;

package/dist/telemetry/index.js

@@ -28,6 +28,9 @@ export async function showTelemetryNoticeIfNeeded(io, packageInfo) {
 const emittedProjectSnapshots = new Set();
 const MCP_SAMPLE_RATE = 0.1;
 let mcpSampled;
+function telemetryDebugEnabled() {
+    return process.env.KTX_TELEMETRY_DEBUG === '1';
+}
 export function shouldEmitMcpTelemetry() {
     mcpSampled ??= Math.random() < MCP_SAMPLE_RATE;
     return mcpSampled;
@@ -36,22 +39,24 @@ export function mcpTelemetrySampleRate() {
     return MCP_SAMPLE_RATE;
 }
 export async function emitTelemetryEvent(input) {
+    const debug = telemetryDebugEnabled();
     const identity = await loadTelemetryIdentity({
         stdoutIsTTY: input.io.stdout.isTTY === true,
         stderr: input.io.stderr,
         env: process.env,
     });
-    if (!identity.enabled || !identity.installId) {
+    if ((!identity.enabled || !identity.installId) && !debug) {
         return;
     }
     const packageInfo = input.packageInfo ?? getKtxCliPackageInfo();
-    const projectId = input.projectDir ? computeTelemetryProjectId(identity.installId, input.projectDir) : undefined;
+    const installId = identity.installId ?? 'debug';
+    const projectId = input.projectDir ? computeTelemetryProjectId(installId, input.projectDir) : undefined;
     await trackTelemetryEvent({
         event: buildTelemetryEvent(input.name, buildCommonEnvelope({
             cliVersion: packageInfo.version,
             isCi: Boolean(process.env.CI),
         }), input.fields),
-        distinctId: identity.installId,
+        distinctId: installId,
         projectId,
         env: process.env,
         stderr: input.io.stderr,

package/dist/tree-picker-state.d.ts

@@ -22,9 +22,9 @@ export interface PickerState {
     checked: Set<string>;
     cursorId: string;
     search: {
-        editing: boolean;
         query: string;
     };
+    isNavigating: boolean;
     pendingConfirm: PendingConfirmKind | null;
     preLoadWarnings: string[];
     transientHint: {
@@ -34,7 +34,7 @@ export interface PickerState {
     requireConfirmOnSave: boolean;
     skipEmptyAction: SkipEmptyAction;
 }
-export type PickerCommand = 'cursor-up' | 'cursor-down' | 'cursor-left' | 'cursor-right' | 'expand' | 'collapse' | 'expand-all' | 'collapse-all' | 'toggle-check' | 'select-all-visible' | 'toggle-select-all-visible' | 'select-none' | 'clear-transient-hint' | 'search-start' | 'search-cancel' | 'search-submit' | 'search-backspace' | {
+export type PickerCommand = 'cursor-up' | 'cursor-down' | 'cursor-left' | 'cursor-right' | 'expand' | 'collapse' | 'expand-all' | 'collapse-all' | 'toggle-check' | 'select-all-visible' | 'toggle-select-all-visible' | 'select-none' | 'clear-transient-hint' | 'search-clear' | 'search-backspace' | {
     type: 'search-input';
     value: string;
 } | 'save-request' | 'save-confirm' | 'save-cancel' | 'quit';