@kaelio/ktx 0.8.0 → 0.9.0

package/dist/setup-context.js

@@ -5,7 +5,10 @@ import { loadKtxProject } from './context/project/project.js';
 import { markKtxSetupStateStepComplete, readKtxSetupState } from './context/project/setup-config.js';
 import { serializeKtxProjectConfig } from './context/project/config.js';
 import { errorMessage, writePrefixedLines } from './clack.js';
+import { formatErrorDetail } from './telemetry/scrubber.js';
 import { buildPublicIngestPlan } from './public-ingest.js';
+import { runKtxConnection } from './connection.js';
+import { createBufferedCommandIo } from './io/buffered-command-io.js';
 import { runContextBuild, } from './context-build-view.js';
 import { createKtxSetupPromptAdapter, } from './setup-prompts.js';
 const SETUP_CONTEXT_STATE_PATH = ['.ktx', 'setup', 'context-build.json'];
@@ -169,6 +172,98 @@ function listContextTargets(project) {
             .map((target) => target.connectionId),
     };
 }
+function requiredConnectionIds(targets) {
+    return [...targets.primarySourceConnectionIds, ...targets.contextSourceConnectionIds];
+}
+function connectorTypeLabel(project, connectionId) {
+    const driver = String(project.config.connections[connectionId]?.driver ?? '')
+        .trim()
+        .toLowerCase();
+    return driver.length > 0 ? driver : 'unknown';
+}
+async function defaultGateTestConnection(projectDir, connectionId, io) {
+    return await runKtxConnection({ command: 'test', projectDir, connectionId }, io);
+}
+/**
+ * Runs a live connection test for every connection the build depends on. Each
+ * test's output is captured in a buffer and discarded so raw error text never
+ * reaches the user — callers surface only the connection id and connector type.
+ */
+async function testRequiredConnections(projectDir, project, targets, testConnection) {
+    const failures = [];
+    for (const connectionId of requiredConnectionIds(targets)) {
+        const buffered = createBufferedCommandIo();
+        const exitCode = await testConnection(projectDir, connectionId, buffered);
+        if (exitCode !== 0) {
+            failures.push({ connectionId, driver: connectorTypeLabel(project, connectionId) });
+        }
+    }
+    return failures.length === 0 ? { ok: true } : { ok: false, failures };
+}
+/**
+ * Loads the project and resolves the connections the build depends on, applying
+ * the empty-targets and preflight-capability checks. Used both on first entry
+ * and on interactive retry so a fix that adds, removes, or reconfigures a
+ * connection is honored.
+ */
+async function prepareBuildTargets(args, io) {
+    const project = await loadKtxProject({ projectDir: args.projectDir });
+    const targets = listContextTargets(project);
+    if (targets.primarySourceConnectionIds.length === 0 && targets.contextSourceConnectionIds.length === 0) {
+        if (args.allowEmpty === true) {
+            return { kind: 'result', result: { status: 'skipped', projectDir: args.projectDir } };
+        }
+        io.stderr.write('No databases or context sources are configured for a KTX context build.\n');
+        return { kind: 'result', result: { status: 'failed', projectDir: args.projectDir } };
+    }
+    const preflightPlan = buildPublicIngestPlan(project, { projectDir: project.projectDir, all: true });
+    const preflightFailures = preflightPlan.targets.flatMap((target) => target.preflightFailure ? [`${target.connectionId}: ${target.preflightFailure}`] : []);
+    if (preflightFailures.length > 0) {
+        if (args.allowEmpty === true) {
+            return { kind: 'result', result: { status: 'skipped', projectDir: args.projectDir } };
+        }
+        writeMissingCapabilities(preflightFailures, io);
+        return { kind: 'result', result: { status: 'missing-input', projectDir: args.projectDir } };
+    }
+    return { kind: 'ready', project, targets };
+}
+function writeConnectionGateFailureLines(io, projectDir, failures) {
+    io.stderr.write('KTX cannot build context: a required connection failed its live test.\n\n');
+    io.stderr.write('Failed connections:\n');
+    for (const failure of failures) {
+        io.stderr.write(`  ${failure.connectionId} (${failure.driver})\n`);
+    }
+    io.stderr.write('\nEach connection must be reachable before KTX builds context.\n');
+    io.stderr.write(`Run \`ktx connection test <id> --project-dir ${resolve(projectDir)}\` to see the error, fix the connection, then retry.\n`);
+}
+function connectionGateFailureReason(failures) {
+    const names = failures.map((failure) => `${failure.connectionId} (${failure.driver})`).join(', ');
+    return `Required connections failed their live test: ${names}.`;
+}
+async function writeConnectionGateFailedState(args, deps, targets, failures) {
+    const at = (deps.now ?? (() => new Date()))().toISOString();
+    await writeKtxSetupContextState(args.projectDir, {
+        status: 'failed',
+        startedAt: at,
+        updatedAt: at,
+        primarySourceConnectionIds: targets.primarySourceConnectionIds,
+        contextSourceConnectionIds: targets.contextSourceConnectionIds,
+        reportIds: [],
+        artifactPaths: [],
+        retryableFailedTargets: [],
+        commands: contextBuildCommands(args.projectDir),
+        failureReason: connectionGateFailureReason(failures),
+    });
+}
+async function promptConnectionGateRetry(prompts) {
+    return (await prompts.select({
+        message: 'Fix the failing connection, then choose how to proceed.',
+        options: [
+            { value: 'retry', label: 'Retry connection tests' },
+            { value: 'back', label: 'Back' },
+        ],
+    }));
+}
 async function hasFileWithExtension(root, extensions, options = {}) {
     if (!(await pathExists(root))) {
         return false;
@@ -303,12 +398,10 @@ function writeMissingCapabilities(missing, io) {
     }
     io.stderr.write('\nFix this in setup before building context.\n');
 }
-function writeSkippedContext(projectDir, io) {
-    io.stdout.write('\nKTX is configured, but context has not been built yet.\n\n');
-    io.stdout.write('Agents were not connected because KTX has not prepared searchable context for them.\n\n');
-    io.stdout.write(`Resume setup:\n  ktx setup --project-dir ${resolve(projectDir)}\n\n`);
-    io.stdout.write(`Build context:\n  ktx setup --project-dir ${resolve(projectDir)}\n\n`);
-    io.stdout.write(`Check status:\n  ktx status --project-dir ${resolve(projectDir)}\n`);
+function writeSkippedContext(io) {
+    // The setup completion screen owns "what to do next" (it points at `ktx ingest`),
+    // so keep this to a short acknowledgement rather than a competing command list.
+    io.stdout.write('\nLeaving context unbuilt for now.\n');
 }
 function writeSuccess(readiness, targets, io) {
     io.stdout.write('\nKTX context is ready for agents.\n\n');
@@ -473,7 +566,6 @@ async function completeExistingContext(args, io, deps, targets) {
 }
 export async function runKtxSetupContextStep(args, io, deps = {}) {
     try {
-        const project = await loadKtxProject({ projectDir: args.projectDir });
         const prompts = deps.prompts ?? createPromptAdapter();
         const existingState = await readKtxSetupContextState(args.projectDir);
         const completedSteps = (await readKtxSetupState(args.projectDir)).completed_steps;
@@ -487,43 +579,57 @@ export async function runKtxSetupContextStep(args, io, deps = {}) {
         if (existingState.status === 'stale') {
             io.stdout.write('Previous context build state is stale; starting a fresh foreground build.\n');
         }
-        const targets = listContextTargets(project);
-        if (targets.primarySourceConnectionIds.length === 0 && targets.contextSourceConnectionIds.length === 0) {
-            if (args.allowEmpty === true) {
-                return { status: 'skipped', projectDir: args.projectDir };
-            }
-            io.stderr.write('No databases or context sources are configured for a KTX context build.\n');
-            return { status: 'failed', projectDir: args.projectDir };
-        }
-        const preflightPlan = buildPublicIngestPlan(project, { projectDir: project.projectDir, all: true });
-        const preflightFailures = preflightPlan.targets.flatMap((target) => target.preflightFailure ? [`${target.connectionId}: ${target.preflightFailure}`] : []);
-        if (preflightFailures.length > 0) {
-            if (args.allowEmpty === true) {
-                return { status: 'skipped', projectDir: args.projectDir };
-            }
-            writeMissingCapabilities(preflightFailures, io);
-            return { status: 'missing-input', projectDir: args.projectDir };
+        const prepared = await prepareBuildTargets(args, io);
+        if (prepared.kind === 'result') {
+            return prepared.result;
         }
+        let { project, targets } = prepared;
+        const interactive = args.inputMode !== 'disabled' && args.prompt !== false;
         if (args.forcePrompt !== true && args.prompt !== false && deps.verifyContextReady === undefined) {
             const existingContextResult = await completeExistingContext(args, io, deps, targets);
             if (existingContextResult) {
                 return existingContextResult;
             }
         }
-        if (args.inputMode !== 'disabled' && args.prompt !== false) {
+        if (interactive) {
             const choice = await promptForBuild(prompts);
             if (choice === 'back') {
                 return { status: 'back', projectDir: args.projectDir };
             }
             if (choice === 'skip') {
-                writeSkippedContext(args.projectDir, io);
+                writeSkippedContext(io);
                 return { status: 'skipped', projectDir: args.projectDir };
             }
         }
-        return await runBuild(args, io, deps, project, targets);
+        // Live-connection gate: every connection the build depends on must pass a
+        // live test before the (expensive) build starts. A red connection is a hard
+        // stop — we surface only the connection id and connector type, never raw
+        // error text.
+        const testConnection = deps.testConnection ?? defaultGateTestConnection;
+        while (true) {
+            const gate = await testRequiredConnections(args.projectDir, project, targets, testConnection);
+            if (gate.ok) {
+                return await runBuild(args, io, deps, project, targets);
+            }
+            writeConnectionGateFailureLines(io, args.projectDir, gate.failures);
+            if (!interactive) {
+                await writeConnectionGateFailedState(args, deps, targets, gate.failures);
+                return { status: 'failed', projectDir: args.projectDir };
+            }
+            const choice = await promptConnectionGateRetry(prompts);
+            if (choice === 'back') {
+                return { status: 'back', projectDir: args.projectDir };
+            }
+            const reprepared = await prepareBuildTargets(args, io);
+            if (reprepared.kind === 'result') {
+                return reprepared.result;
+            }
+            project = reprepared.project;
+            targets = reprepared.targets;
+        }
     }
     catch (error) {
         writePrefixedLines((chunk) => io.stderr.write(chunk), errorMessage(error));
-        return { status: 'failed', projectDir: args.projectDir };
+        return { status: 'failed', projectDir: args.projectDir, errorDetail: formatErrorDetail(error) };
     }
 }

package/dist/setup-databases.d.ts

@@ -1,12 +1,20 @@
+import type { KtxLlmRuntimePort } from './context/llm/runtime-port.js';
+import { type ProposeQueryHistoryServiceAccountFiltersInput, type QueryHistoryFilterProposal } from './context/ingest/adapters/historic-sql/query-history-filter-picker.js';
 import { type HistoricSqlReadinessProbe } from './context/ingest/historic-sql-probes.js';
+import { loadKtxProject } from './context/project/project.js';
 import type { KtxTableListEntry } from './context/scan/types.js';
-import type { KtxCliIo } from './cli-runtime.js';
+import { type KtxCliIo } from './cli-runtime.js';
 import { type DatabaseScopePickResult, type PickDatabaseScopeArgs } from './database-tree-picker.js';
+import type { KtxManagedPythonInstallPolicy } from './managed-python-command.js';
+import type { ManagedPythonCoreDaemonOptions } from './managed-python-http.js';
 import { type KtxSetupPromptOption } from './setup-prompts.js';
 export type KtxSetupDatabaseDriver = 'sqlite' | 'postgres' | 'mysql' | 'clickhouse' | 'sqlserver' | 'bigquery' | 'snowflake';
 export interface KtxSetupDatabasesArgs {
     projectDir: string;
     inputMode: 'auto' | 'disabled';
+    yes?: boolean;
+    cliVersion?: string;
+    runtimeInstallPolicy?: KtxManagedPythonInstallPolicy;
     databaseDrivers?: KtxSetupDatabaseDriver[];
     databaseConnectionIds?: string[];
     databaseConnectionId?: string;
@@ -77,5 +85,13 @@ export interface KtxSetupDatabasesDeps {
     listTables?: (projectDir: string, connectionId: string, schemas?: string[]) => Promise<KtxTableListEntry[]>;
     pickDatabaseScope?: (args: PickDatabaseScopeArgs, io: KtxCliIo) => Promise<DatabaseScopePickResult>;
     historicSqlReadinessProbe?: HistoricSqlReadinessProbe;
+    queryHistoryFilterPicker?: (input: ProposeQueryHistoryServiceAccountFiltersInput) => Promise<QueryHistoryFilterProposal>;
+    createQueryHistoryLlmRuntime?: (projectDir: string, project: Awaited<ReturnType<typeof loadKtxProject>>) => KtxLlmRuntimePort | null;
 }
+/** @internal */
+export declare function managedDaemonOptionsForSetupQueryHistoryPicker(input: {
+    projectDir: string;
+    args: Pick<KtxSetupDatabasesArgs, 'cliVersion' | 'runtimeInstallPolicy' | 'inputMode'>;
+    io: KtxCliIo;
+}): ManagedPythonCoreDaemonOptions;
 export declare function runKtxSetupDatabasesStep(args: KtxSetupDatabasesArgs, io: KtxCliIo, deps?: KtxSetupDatabasesDeps): Promise<KtxSetupDatabasesResult>;