@kaelio/ktx 0.11.0 → 0.12.0

package/dist/doctor.js

@@ -4,6 +4,7 @@ import { access, readFile } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { promisify } from 'node:util';
+import { shouldUseColorOutput } from './io/tty.js';
 import { KTX_NEXT_STEP_DIRECT_COMMANDS } from './next-steps.js';
 const execFileAsync = promisify(execFile);
 function workspaceRootDir() {
@@ -121,12 +122,6 @@ const GROUP_LABEL = {
     search: 'Semantic search',
     history: 'Query history',
 };
-function shouldUseColor(io) {
-    if (io.stdout.isTTY !== true)
-        return false;
-    const env = process.env;
-    return !env.NO_COLOR && env.TERM !== 'dumb' && !env.CI;
-}
 function styleStatus(useColor, status, text) {
     if (!useColor)
         return text;
@@ -322,17 +317,20 @@ export function renderInvalidConfigMessage(projectDir, issues, outputMode, io) {
         }, null, 2)}\n`);
         return;
     }
-    const useColor = shouldUseColor(io);
+    const useColor = shouldUseColorOutput(io.stdout);
     const dim = (text) => styleDim(useColor, text);
     const bold = (text) => styleBold(useColor, text);
     const status = (s, text) => styleStatus(useColor, s, text);
     const abbreviated = abbreviateHome(projectDir) ?? projectDir;
+    const errorCount = issues.filter((issue) => issue.severity === 'error').length;
+    const warningCount = issues.length - errorCount;
     const lines = [];
-    lines.push(`${bold('KTX status')} ${dim('·')} ${abbreviated}`);
+    lines.push(`${bold('ktx status')} ${dim('·')} ${abbreviated}`);
     lines.push('');
-    lines.push(`  ${status('fail', '✗')} ${bold('Config')}    ktx.yaml has ${issues.length} schema issue${issues.length === 1 ? '' : 's'}`);
+    lines.push(`  ${status('fail', '✗')} ${bold('Config')}    ktx.yaml has ${errorCount} schema issue${errorCount === 1 ? '' : 's'}${warningCount > 0 ? ` · ${warningCount} ignored field${warningCount === 1 ? '' : 's'}` : ''}`);
     for (const issue of issues) {
-        lines.push(`      ${status('fail', '✗')} ${issue.message}`);
+        const glyph = issue.severity === 'error' ? status('fail', '✗') : status('warn', '⚠');
+        lines.push(`      ${glyph} ${issue.message}`);
         if (issue.fix) {
             lines.push(`        ${dim(`→ ${issue.fix}`)}`);
         }
@@ -342,23 +340,35 @@ export function renderInvalidConfigMessage(projectDir, issues, outputMode, io) {
     lines.push('');
     io.stdout.write(lines.join('\n'));
 }
-export function renderValidConfigMessage(projectDir, outputMode, io) {
+export function renderValidConfigMessage(projectDir, outputMode, io, warnings = []) {
     if (outputMode === 'json') {
         io.stdout.write(`${JSON.stringify({
             ok: true,
             projectDir,
+            ...(warnings.length > 0 ? { warnings } : {}),
         }, null, 2)}\n`);
         return;
     }
-    const useColor = shouldUseColor(io);
+    const useColor = shouldUseColorOutput(io.stdout);
     const dim = (text) => styleDim(useColor, text);
     const bold = (text) => styleBold(useColor, text);
     const status = (s, text) => styleStatus(useColor, s, text);
     const abbreviated = abbreviateHome(projectDir) ?? projectDir;
     const lines = [];
-    lines.push(`${bold('KTX status')} ${dim('·')} ${abbreviated}`);
+    lines.push(`${bold('ktx status')} ${dim('·')} ${abbreviated}`);
     lines.push('');
-    lines.push(`  ${status('pass', '✓')} ${bold('Config')}    ${dim('ktx.yaml schema valid')}`);
+    if (warnings.length > 0) {
+        lines.push(`  ${status('warn', '⚠')} ${bold('Config')}    ktx.yaml schema valid · ${warnings.length} ignored field${warnings.length === 1 ? '' : 's'}`);
+        for (const warning of warnings) {
+            lines.push(`      ${status('warn', '⚠')} ${warning.message}`);
+            if (warning.fix) {
+                lines.push(`        ${dim(`→ ${warning.fix}`)}`);
+            }
+        }
+    }
+    else {
+        lines.push(`  ${status('pass', '✓')} ${bold('Config')}    ${dim('ktx.yaml schema valid')}`);
+    }
     lines.push('');
     io.stdout.write(lines.join('\n'));
 }
@@ -371,15 +381,15 @@ export function renderMissingProjectMessage(projectDir, outputMode, io) {
         }, null, 2)}\n`);
         return;
     }
-    const useColor = shouldUseColor(io);
+    const useColor = shouldUseColorOutput(io.stdout);
     const dim = (text) => styleDim(useColor, text);
     const bold = (text) => styleBold(useColor, text);
     const abbreviated = abbreviateHome(projectDir) ?? projectDir;
     const envProjectDir = process.env.KTX_PROJECT_DIR;
     const lines = [];
-    lines.push(`${bold('KTX status')} ${dim('·')} ${abbreviated}`);
+    lines.push(`${bold('ktx status')} ${dim('·')} ${abbreviated}`);
     lines.push('');
-    lines.push(`  No KTX project here yet. ${dim('(ktx.yaml not found)')}`);
+    lines.push(`  No ktx project here yet. ${dim('(ktx.yaml not found)')}`);
     lines.push('');
     lines.push(`  Run  ${bold('ktx setup')}  to create one.`);
     if (envProjectDir !== undefined) {
@@ -402,14 +412,13 @@ export async function runKtxDoctor(args, io = process, deps = {}) {
                 return 1;
             }
             const { validateKtxProjectConfig } = await import('./context/project/config.js');
-            ;
             const rawConfig = await readFile(configPath, 'utf-8');
             const validation = validateKtxProjectConfig(rawConfig);
             if (!validation.ok) {
                 renderInvalidConfigMessage(args.projectDir, validation.issues, args.outputMode, io);
                 return 1;
             }
-            renderValidConfigMessage(args.projectDir, args.outputMode, io);
+            renderValidConfigMessage(args.projectDir, args.outputMode, io, validation.issues);
             return 0;
         }
         if (args.command === 'project') {
@@ -420,7 +429,6 @@ export async function runKtxDoctor(args, io = process, deps = {}) {
             }
             const { loadKtxProject } = await import('./context/project/project.js');
             const { validateKtxProjectConfig } = await import('./context/project/config.js');
-            ;
             const { buildProjectStatus, renderProjectStatus } = await import('./status-project.js');
             const rawConfig = await readFile(configPath, 'utf-8');
             const validation = validateKtxProjectConfig(rawConfig);
@@ -445,7 +453,7 @@ export async function runKtxDoctor(args, io = process, deps = {}) {
             else {
                 io.stdout.write(renderProjectStatus(projectStatus, {
                     verbose,
-                    useColor: shouldUseColor(io),
+                    useColor: shouldUseColorOutput(io.stdout),
                     durationMs: Date.now() - startedAt,
                     toolchainChecks,
                 }));
@@ -453,10 +461,10 @@ export async function runKtxDoctor(args, io = process, deps = {}) {
             return projectStatus.verdict === 'blocked' ? 1 : 0;
         }
         const setupChecks = await runSetupChecks();
-        const report = { title: 'KTX status', checks: setupChecks };
+        const report = { title: 'ktx status', checks: setupChecks };
         const renderOptions = {
             verbose: args.verbose ?? false,
-            useColor: shouldUseColor(io),
+            useColor: shouldUseColorOutput(io.stdout),
             durationMs: Date.now() - startedAt,
             command: args.command,
         };

package/dist/errors.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Marks an error as an expected operational outcome that ktx surfaces to its
+ * caller (a connected agent or the CLI user) rather than an unexpected ktx
+ * fault. Examples: invalid agent input, a warehouse rejecting a query, or a
+ * validation guard rejecting a request.
+ *
+ * `reportException` skips PostHog Error Tracking for these so the bug stream
+ * stays free of routine, caller-driven failures. The failure is still surfaced
+ * to the caller (as a tool-error result or CLI error) and still recorded by the
+ * outcome-tagged telemetry events, so no diagnostic signal is lost.
+ */
+export declare class KtxExpectedError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * A query was rejected at the warehouse/driver boundary — the warehouse refused
+ * to compile or run it, or a read-only guard rejected it. Reuses the underlying
+ * error's message so the caller still sees the original warehouse diagnostics,
+ * and keeps the driver error as `cause`.
+ */
+export declare class KtxQueryError extends KtxExpectedError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * True for the native JavaScript error types that signal a programming fault — a
+ * bug in ktx code rather than an operational outcome. These are universal
+ * language invariants (a `TypeError` never means "the warehouse rejected the
+ * query"), so callers can use this to keep genuine faults out of the
+ * expected-error classification and let them reach Error Tracking unchanged.
+ */
+export declare function isNativeProgrammingFault(error: unknown): boolean;

package/dist/errors.js

@@ -0,0 +1,44 @@
+/**
+ * Marks an error as an expected operational outcome that ktx surfaces to its
+ * caller (a connected agent or the CLI user) rather than an unexpected ktx
+ * fault. Examples: invalid agent input, a warehouse rejecting a query, or a
+ * validation guard rejecting a request.
+ *
+ * `reportException` skips PostHog Error Tracking for these so the bug stream
+ * stays free of routine, caller-driven failures. The failure is still surfaced
+ * to the caller (as a tool-error result or CLI error) and still recorded by the
+ * outcome-tagged telemetry events, so no diagnostic signal is lost.
+ */
+export class KtxExpectedError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'KtxExpectedError';
+    }
+}
+/**
+ * A query was rejected at the warehouse/driver boundary — the warehouse refused
+ * to compile or run it, or a read-only guard rejected it. Reuses the underlying
+ * error's message so the caller still sees the original warehouse diagnostics,
+ * and keeps the driver error as `cause`.
+ */
+export class KtxQueryError extends KtxExpectedError {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'KtxQueryError';
+    }
+}
+/**
+ * True for the native JavaScript error types that signal a programming fault — a
+ * bug in ktx code rather than an operational outcome. These are universal
+ * language invariants (a `TypeError` never means "the warehouse rejected the
+ * query"), so callers can use this to keep genuine faults out of the
+ * expected-error classification and let them reach Error Tracking unchanged.
+ */
+export function isNativeProgrammingFault(error) {
+    return (error instanceof TypeError ||
+        error instanceof RangeError ||
+        error instanceof ReferenceError ||
+        error instanceof SyntaxError ||
+        error instanceof EvalError ||
+        error instanceof URIError);
+}

package/dist/ingest.d.ts

@@ -60,7 +60,7 @@ export interface KtxIngestDeps {
     startLiveMemoryFlow?: typeof startLiveMemoryFlowTui;
     abortSignal?: AbortSignal;
     env?: NodeJS.ProcessEnv;
-    localIngestOptions?: Pick<RunLocalIngestOptions, 'agentRunner' | 'llmRuntime' | 'memoryModel' | 'semanticLayerCompute' | 'queryExecutor' | 'logger' | 'pullConfigOptions'>;
+    localIngestOptions?: Pick<RunLocalIngestOptions, 'agentRunner' | 'llmRuntime' | 'memoryModel' | 'semanticLayerCompute' | 'queryExecutor' | 'sqlAnalysis' | 'logger' | 'pullConfigOptions'>;
     progress?: (update: KtxIngestProgressUpdate) => void;
     runtimeIo?: KtxIngestIo;
 }

package/dist/ingest.js

@@ -11,7 +11,7 @@ import { resolveProjectEmbeddingProvider } from './embedding-resolution.js';
 import { createKtxCliIngestQueryExecutor } from './ingest-query-executor.js';
 import { readIngestReportSnapshotFile } from './ingest-report-file.js';
 import { createCliOperationalLogger } from './io/logger.js';
-import { createKtxCliLocalIngestAdapters } from './local-adapters.js';
+import { createKtxCliLocalIngestAdapters, resolveKtxCliSqlAnalysis } from './local-adapters.js';
 import { renderMemoryFlowInteractively } from './memory-flow-interactive.js';
 import { renderMemoryFlowTui, startLiveMemoryFlowTui, } from './memory-flow-tui.js';
 import { resolveVizFallback, warnVizFallbackOnce } from './viz-fallback.js';
@@ -525,7 +525,7 @@ export async function runKtxIngest(args, io = process, deps = {}) {
             const localIngestOptions = deps.localIngestOptions ?? {};
             const managedDaemon = managedDaemonOptionsForIngestRun(args, deps.runtimeIo ?? io);
             const operationalLogger = createCliOperationalLogger(io, args.outputMode);
-            const adapterOptions = {
+            const baseAdapterOptions = {
                 ...(localIngestOptions.pullConfigOptions ?? {}),
                 ...(args.databaseIntrospectionUrl ? { databaseIntrospectionUrl: args.databaseIntrospectionUrl } : {}),
                 ...(managedDaemon ? { managedDaemon } : {}),
@@ -535,6 +535,10 @@ export async function runKtxIngest(args, io = process, deps = {}) {
                     : {}),
                 logger: operationalLogger,
             };
+            // One parser-backed SQL analysis port per run: the historic-sql adapter and
+            // the ingest sql_execution tool share the same daemon-backed validator.
+            const sqlAnalysis = localIngestOptions.sqlAnalysis ?? resolveKtxCliSqlAnalysis(baseAdapterOptions);
+            const adapterOptions = { ...baseAdapterOptions, sqlAnalysis };
             const queryExecutor = localIngestOptions.queryExecutor ??
                 (deps.createQueryExecutor ?? createKtxCliIngestQueryExecutor)(ingestProject);
             if (args.adapter === 'metabase' && args.sourceDir) {
@@ -577,6 +581,7 @@ export async function runKtxIngest(args, io = process, deps = {}) {
                         metabaseConnectionId: args.connectionId,
                         ...localIngestOptions,
                         queryExecutor,
+                        sqlAnalysis,
                         trigger: 'manual_resync',
                         jobIdFactory: deps.jobIdFactory,
                         embeddingProvider,
@@ -650,6 +655,7 @@ export async function runKtxIngest(args, io = process, deps = {}) {
                     jobId,
                     ...localIngestOptions,
                     queryExecutor,
+                    sqlAnalysis,
                     pullConfigOptions: adapterOptions,
                     embeddingProvider,
                     ...(args.debugLlmRequestFile ? { llmDebugRequestFile: args.debugLlmRequestFile } : {}),

package/dist/io/symbols.d.ts

@@ -1,3 +1,5 @@
+/** Whether the active terminal renders Unicode glyphs (block/box drawing, arrows). */
+export declare const unicodeSupported: boolean;
 export declare const SYMBOLS: {
     readonly middot: "-" | "·";
     readonly emDash: "--" | "—";

package/dist/io/symbols.js

@@ -9,6 +9,8 @@ function detectUnicodeSupport(env = process.env) {
         env.TERM === 'alacritty');
 }
 const unicode = detectUnicodeSupport();
+/** Whether the active terminal renders Unicode glyphs (block/box drawing, arrows). */
+export const unicodeSupported = unicode;
 export const SYMBOLS = {
     middot: unicode ? '·' : '-',
     emDash: unicode ? '—' : '--',

package/dist/io/tty.d.ts

@@ -6,4 +6,12 @@ type KtxCliOutput = (KtxCliIo['stdout'] | KtxCliIo['stderr']) & {
     on?: unknown;
 };
 export declare function isWritableTtyOutput(output: KtxCliOutput): output is KtxCliOutput & Writable;
+export declare function shouldUseColorOutput(output: {
+    isTTY?: boolean;
+}): boolean;
+/**
+ * Color depth in bits for the given output: 1 when color is disabled, the
+ * stream-reported depth when available, and a 16-color baseline otherwise.
+ */
+export declare function colorDepthForOutput(output: KtxCliOutput): number;
 export {};

package/dist/io/tty.js

@@ -3,3 +3,19 @@ export function isWritableTtyOutput(output) {
         typeof output.on === 'function' &&
         typeof output.columns !== 'undefined');
 }
+export function shouldUseColorOutput(output) {
+    if (output.isTTY !== true)
+        return false;
+    const env = process.env;
+    return !env.NO_COLOR && env.TERM !== 'dumb' && !env.CI;
+}
+/**
+ * Color depth in bits for the given output: 1 when color is disabled, the
+ * stream-reported depth when available, and a 16-color baseline otherwise.
+ */
+export function colorDepthForOutput(output) {
+    if (!shouldUseColorOutput(output))
+        return 1;
+    const getColorDepth = output.getColorDepth;
+    return typeof getColorDepth === 'function' ? getColorDepth.call(output) : 4;
+}

package/dist/llm/embedding-health.js

@@ -21,7 +21,7 @@ async function withTimeout(promise, timeoutMs) {
 export async function runKtxEmbeddingHealthCheck(config, options = {}) {
     try {
         const provider = createKtxEmbeddingProvider(config, options.deps);
-        const embedding = await withTimeout(provider.embed(options.text ?? 'KTX embedding health check'), options.timeoutMs ?? 15_000);
+        const embedding = await withTimeout(provider.embed(options.text ?? 'ktx embedding health check'), options.timeoutMs ?? 15_000);
         if (embedding.length !== config.dimensions) {
             return {
                 ok: false,

package/dist/llm/embedding-provider.js

@@ -49,7 +49,7 @@ class OpenAIEmbeddingProvider {
         this.dimensions = config.dimensions;
         this.maxBatchSize = config.batchSize ?? DEFAULT_BATCH_SIZE;
         if (!config.openai?.apiKey) {
-            throw new Error('openai.apiKey is required when KTX embedding backend is openai');
+            throw new Error('openai.apiKey is required when ktx embedding backend is openai');
         }
         this.client = deps.createOpenAIClient
             ? deps.createOpenAIClient({ apiKey: config.openai.apiKey, baseURL: config.openai.baseURL })
@@ -90,7 +90,7 @@ class SentenceTransformersEmbeddingProvider {
     startupProbe;
     constructor(config, deps) {
         if (!config.sentenceTransformers?.baseURL) {
-            throw new Error('sentenceTransformers.baseURL is required when KTX embedding backend is sentence-transformers');
+            throw new Error('sentenceTransformers.baseURL is required when ktx embedding backend is sentence-transformers');
         }
         this.dimensions = config.dimensions;
         this.maxBatchSize = config.batchSize ?? DEFAULT_BATCH_SIZE;
@@ -156,6 +156,6 @@ export function createKtxEmbeddingProvider(config, deps = {}) {
         case 'sentence-transformers':
             return new SentenceTransformersEmbeddingProvider(config, deps);
         default:
-            throw new Error(`Unsupported KTX embedding backend: ${String(config.backend)}`);
+            throw new Error(`Unsupported ktx embedding backend: ${String(config.backend)}`);
     }
 }

package/dist/llm/model-provider.js

@@ -121,7 +121,7 @@ class DefaultKtxLlmProvider {
         }
         if (config.backend === 'vertex') {
             if (!config.vertex?.location) {
-                throw new Error('vertex.location is required when KTX LLM backend is vertex');
+                throw new Error('vertex.location is required when ktx LLM backend is vertex');
             }
             const vertex = (deps.createVertexAnthropic ?? createVertexAnthropic)({
                 ...(config.vertex.project ? { project: config.vertex.project } : {}),

package/dist/local-adapters.d.ts

@@ -5,6 +5,7 @@ import type { KtxLocalProject } from './context/project/project.js';
 import type { SqlAnalysisPort } from './context/sql-analysis/ports.js';
 import { type ManagedPythonDaemonHttpOptions } from './managed-python-http.js';
 import type { KtxOperationalLogger } from './io/logger.js';
+export declare function resolveKtxCliSqlAnalysis(options: KtxCliLocalIngestAdaptersOptions): SqlAnalysisPort;
 export interface KtxCliLocalIngestAdaptersOptions extends DefaultLocalIngestAdaptersOptions {
     historicSqlConnectionId?: string;
     sqlAnalysis?: SqlAnalysisPort;

package/dist/local-adapters.js

@@ -45,7 +45,7 @@ function ktxCliLookerOptions(options) {
         parser: createManagedDaemonLookerTableIdentifierParser(options.managedDaemon),
     };
 }
-function ktxCliHistoricSqlAnalysis(options) {
+export function resolveKtxCliSqlAnalysis(options) {
     if (options.sqlAnalysis) {
         return options.sqlAnalysis;
     }
@@ -234,7 +234,7 @@ function historicSqlOptionsForLocalRun(project, options) {
         return undefined;
     }
     const base = {
-        sqlAnalysis: ktxCliHistoricSqlAnalysis(options),
+        sqlAnalysis: resolveKtxCliSqlAnalysis(options),
     };
     if (dialect === 'postgres') {
         return {

package/dist/local-scan-connectors.js

@@ -11,7 +11,7 @@ export async function createKtxCliScanConnector(project, connectionId) {
     }
     const registration = getDriverRegistration(driver);
     if (!registration) {
-        throw new Error(`Connection "${connectionId}" uses driver "${driver}", which has no native standalone KTX scan connector. Supported drivers: ${SUPPORTED_DRIVERS}.`);
+        throw new Error(`Connection "${connectionId}" uses driver "${driver}", which has no native standalone ktx scan connector. Supported drivers: ${SUPPORTED_DRIVERS}.`);
     }
     const connectorModule = await registration.load();
     if (!connectorModule.isConnectionConfig(connection)) {

package/dist/managed-local-embeddings.js

@@ -1,4 +1,4 @@
-import { writePrefixedLines } from './clack.js';
+import { createCliSpinner } from './clack.js';
 import { ensureManagedPythonCommandRuntime, } from './managed-python-command.js';
 import { readManagedPythonDaemonStatus, startManagedPythonDaemon, } from './managed-python-daemon.js';
 export function managedLocalEmbeddingHealthConfig(input) {
@@ -21,14 +21,23 @@ export async function ensureManagedLocalEmbeddingsDaemon(options) {
         io: options.io,
         feature: 'local-embeddings',
     });
-    const daemon = await startDaemon({
-        cliVersion: options.cliVersion,
-        projectDir: options.projectDir,
-        features: ['local-embeddings'],
-        force: false,
-    });
+    const spinner = createCliSpinner(options.io);
+    spinner.start('Starting ktx embedding daemon (first run downloads the model)…');
+    let daemon;
+    try {
+        daemon = await startDaemon({
+            cliVersion: options.cliVersion,
+            projectDir: options.projectDir,
+            features: ['local-embeddings'],
+            force: false,
+        });
+    }
+    catch (error) {
+        spinner.error('ktx embedding daemon failed to start');
+        throw error;
+    }
     const verb = daemon.status === 'started' ? 'Started' : 'Using';
-    writePrefixedLines((chunk) => options.io.stderr.write(chunk), `${verb} KTX daemon: ${daemon.baseUrl}`);
+    spinner.stop(`${verb} ktx daemon: ${daemon.baseUrl}`);
     return {
         baseUrl: daemon.baseUrl,
         stdoutLog: daemon.state.stdoutLog,

package/dist/managed-mcp-daemon.js

@@ -92,7 +92,7 @@ export async function startKtxMcpDaemon(options) {
                 url: `http://${existing.host}:${existing.port}/mcp`,
             };
         }
-        throw new Error(`KTX MCP daemon is already running at http://${existing.host}:${existing.port}/mcp ` +
+        throw new Error(`ktx MCP daemon is already running at http://${existing.host}:${existing.port}/mcp ` +
             'with a different configuration. Run `ktx mcp stop` first, then start again.');
     }
     const portAvailable = options.portAvailable ?? defaultPortAvailable;
@@ -126,7 +126,7 @@ export async function startKtxMcpDaemon(options) {
             }),
         });
         if (!child.pid) {
-            throw new Error('Failed to start KTX MCP daemon: child process pid was not available.');
+            throw new Error('Failed to start ktx MCP daemon: child process pid was not available.');
         }
         child.unref();
         const state = {
@@ -167,7 +167,7 @@ export async function readKtxMcpDaemonStatus(options) {
     }
     return {
         kind: 'running',
-        detail: `KTX MCP daemon running at http://${state.host}:${state.port}/mcp`,
+        detail: `ktx MCP daemon running at http://${state.host}:${state.port}/mcp`,
         state,
         url: `http://${state.host}:${state.port}/mcp`,
     };

package/dist/managed-python-command.d.ts

@@ -31,4 +31,11 @@ export interface ManagedPythonSemanticLayerComputeOptions extends ManagedPythonC
 export declare function managedRuntimeInstallCommand(feature: KtxRuntimeFeature): string;
 export declare function ensureManagedPythonCommandRuntime(options: ManagedPythonCommandOptions): Promise<ManagedPythonCommandRuntime>;
 export declare function createManagedPythonSemanticLayerComputePort(options: ManagedPythonSemanticLayerComputeOptions): Promise<KtxSemanticLayerComputePort>;
+/**
+ * Defers the managed-runtime install to the first semantic-layer call so a
+ * long-lived server (the MCP server) can start and serve context tools that
+ * need no Python even when uv is absent. Caches on success only, so a runtime
+ * installed mid-session is picked up on the next call.
+ */
+export declare function createLazyManagedPythonSemanticLayerComputePort(options: ManagedPythonSemanticLayerComputeOptions): KtxSemanticLayerComputePort;
 export {};

package/dist/managed-python-command.js

@@ -1,5 +1,5 @@
 import { createPythonSemanticLayerComputePort } from './context/daemon/semantic-layer-compute.js';
-import { createClackPromptAdapter, createStaticCliSpinner } from './clack.js';
+import { createClackPromptAdapter, createCliSpinner } from './clack.js';
 import { installManagedPythonRuntime, readManagedPythonRuntimeStatus, } from './managed-python-runtime.js';
 import { readExistingTelemetryProjectId } from './telemetry/identity.js';
 export function runtimeInstallPolicyFromFlags(options) {
@@ -19,10 +19,10 @@ export function managedRuntimeInstallCommand(feature) {
 }
 function installPrompt(feature) {
     const label = feature === 'local-embeddings' ? 'local embeddings Python runtime' : 'core Python runtime';
-    return `KTX needs to install the ${label}. This downloads Python dependencies with uv. Continue?`;
+    return `ktx needs to install the ${label}. This downloads a pinned, checksum-verified uv build, Python, and dependencies. Continue?`;
 }
 function runtimeRequiredMessage(feature) {
-    return `KTX Python runtime is required for this command. Run: ${managedRuntimeInstallCommand(feature)}`;
+    return `ktx Python runtime is required for this command. Run: ${managedRuntimeInstallCommand(feature)}`;
 }
 function hasFeature(manifest, feature) {
     return manifest.features.includes(feature);
@@ -49,22 +49,22 @@ export async function ensureManagedPythonCommandRuntime(options) {
         const confirmInstall = options.confirmInstall ?? defaultConfirmInstall;
         const confirmed = await confirmInstall(installPrompt(feature), options.io);
         if (!confirmed) {
-            throw new Error(`KTX Python runtime installation was cancelled. Run: ${managedRuntimeInstallCommand(feature)}`);
+            throw new Error(`ktx Python runtime installation was cancelled. Run: ${managedRuntimeInstallCommand(feature)}`);
         }
     }
-    const progress = (options.spinner ?? (() => createStaticCliSpinner(options.io)))();
-    progress.start(`Installing KTX Python runtime (${feature}) with uv...`);
+    const progress = (options.spinner ?? (() => createCliSpinner(options.io)))();
+    progress.start(`Installing ktx Python runtime (${feature}) with uv...`);
     try {
         const installed = await installRuntime({
             cliVersion: options.cliVersion,
             features: [feature],
             force: false,
         });
-        progress.stop(`KTX Python runtime ready: ${installed.layout.versionDir}`);
+        progress.stop(`ktx Python runtime ready: ${installed.layout.versionDir}`);
         return { layout: installed.layout, manifest: installed.manifest };
     }
     catch (error) {
-        progress.error(`KTX Python runtime install failed: ${error instanceof Error ? error.message : String(error)}`);
+        progress.error(`ktx Python runtime install failed: ${error instanceof Error ? error.message : String(error)}`);
         throw error;
     }
 }
@@ -89,3 +89,29 @@ export async function createManagedPythonSemanticLayerComputePort(options) {
         ...(projectId ? { projectId } : {}),
     });
 }
+/**
+ * Defers the managed-runtime install to the first semantic-layer call so a
+ * long-lived server (the MCP server) can start and serve context tools that
+ * need no Python even when uv is absent. Caches on success only, so a runtime
+ * installed mid-session is picked up on the next call.
+ */
+export function createLazyManagedPythonSemanticLayerComputePort(options) {
+    let cached;
+    const resolve = async () => {
+        if (!cached) {
+            cached = await createManagedPythonSemanticLayerComputePort(options);
+        }
+        return cached;
+    };
+    return {
+        async query(input) {
+            return (await resolve()).query(input);
+        },
+        async validateSources(input) {
+            return (await resolve()).validateSources(input);
+        },
+        async generateSources(input) {
+            return (await resolve()).generateSources(input);
+        },
+    };
+}

package/dist/managed-python-daemon.js

@@ -11,7 +11,7 @@ export class ManagedPythonDaemonStartError extends Error {
     detail;
     stderrLog;
     constructor(detail, stderrLog) {
-        super(`KTX daemon failed to start: ${detail}. stderr: ${stderrLog}`);
+        super(`ktx daemon failed to start: ${detail}. stderr: ${stderrLog}`);
         this.name = 'ManagedPythonDaemonStartError';
         this.detail = detail;
         this.stderrLog = stderrLog;
@@ -502,7 +502,7 @@ export async function startManagedPythonDaemon(options) {
         });
         child.unref();
         if (!child.pid) {
-            throw new Error(`KTX daemon did not report a pid. stderr: ${layout.daemonStderrPath}`);
+            throw new Error(`ktx daemon did not report a pid. stderr: ${layout.daemonStderrPath}`);
         }
         const state = {
             schemaVersion: 1,

package/dist/managed-python-http.js

@@ -12,7 +12,7 @@ function normalizedBaseUrl(baseUrl) {
 function parseJsonObject(raw, path) {
     const parsed = JSON.parse(raw);
     if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
-        throw new Error(`KTX daemon HTTP ${path} returned non-object JSON`);
+        throw new Error(`ktx daemon HTTP ${path} returned non-object JSON`);
     }
     return parsed;
 }
@@ -35,7 +35,7 @@ async function postManagedDaemonJson(baseUrl, path, payload) {
                 const text = Buffer.concat(chunks).toString('utf8');
                 const statusCode = response.statusCode ?? 0;
                 if (statusCode < 200 || statusCode >= 300) {
-                    reject(new Error(`KTX daemon HTTP ${path} failed with ${statusCode}: ${text}`));
+                    reject(new Error(`ktx daemon HTTP ${path} failed with ${statusCode}: ${text}`));
                     return;
                 }
                 try {
@@ -72,7 +72,7 @@ export function createManagedPythonDaemonBaseUrlResolver(options) {
             force: false,
         });
         const verb = daemon.status === 'started' ? 'Started' : 'Using existing';
-        writePrefixedLines((chunk) => options.io.stderr.write(chunk), `${verb} KTX daemon: ${daemon.baseUrl}`);
+        writePrefixedLines((chunk) => options.io.stderr.write(chunk), `${verb} ktx daemon: ${daemon.baseUrl}`);
         cachedBaseUrl = daemon.baseUrl;
         return cachedBaseUrl;
     };