@kaelio/ktx 0.11.0 → 0.12.0

package/dist/context/sl/source-files.js

@@ -0,0 +1,131 @@
+import { createHash } from 'node:crypto';
+import YAML from 'yaml';
+// Semantic-layer source identity lives in the file's `name:` field, which mirrors
+// the warehouse identifier verbatim (Snowflake's uppercase `SIGNED_UP`, `EVENT$LOG`).
+// The filename is a derived label and never participates in identity: reads resolve
+// a source by scanning the connection directory and matching `name:`, and writes
+// reuse the resolved file's path, so files can be freely renamed by humans without
+// changing which source they define.
+function assertSafePathToken(kind, value) {
+    if (value.trim().length === 0 ||
+        value.includes('..') ||
+        value.includes('\\') ||
+        value.startsWith('/') ||
+        value.startsWith('.') ||
+        value.includes('//')) {
+        throw new Error(`Unsafe ${kind}: ${value}`);
+    }
+    return value;
+}
+export function assertSafeConnectionId(connectionId) {
+    if (!isSafeConnectionId(connectionId)) {
+        throw new Error(`Unsafe connection id: ${connectionId}`);
+    }
+    return assertSafePathToken('connection id', connectionId);
+}
+export function isSafeConnectionId(connectionId) {
+    return typeof connectionId === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(connectionId);
+}
+export function sourceNameFromPath(path) {
+    return (path
+        .split('/')
+        .at(-1)
+        ?.replace(/\.ya?ml$/, '') ?? path);
+}
+// The one predicate for "this path is a semantic-layer YAML file". ktx itself
+// always writes `.yaml` (see `slSourceFileName`), but humans rename freely and
+// the dbt ecosystem's habit is `.yml`, so every reader must accept both — a
+// listing that recognizes only one extension makes the same file visible to
+// some entry points and invisible to others.
+export function isSlYamlPath(path) {
+    return path.endsWith('.yaml') || path.endsWith('.yml');
+}
+// Windows refuses these basenames regardless of extension — a genuinely universal
+// filesystem invariant, so the static list is acceptable.
+const WINDOWS_RESERVED_BASENAME = /^(?:con|prn|aux|nul|com[0-9]|lpt[0-9])$/;
+const SAFE_FILE_BASENAME = /^[a-z0-9][a-z0-9_]{0,63}$/;
+/**
+ * Derive the filename for a semantic-layer source. Total over all possible
+ * source names — never throws.
+ *
+ * Names that are already safe lowercase snake_case become `<name>.yaml`;
+ * anything else becomes `<slug>-<8 hex of sha256(name)>.yaml`. The two ranges
+ * are disjoint and the mapping is injective: safe filenames contain no `-`,
+ * hashed filenames always end in `-<8 hex>`, and slugs are lowercased so names
+ * differing only by case get distinct hashes instead of colliding paths on
+ * case-insensitive filesystems (macOS APFS, Windows).
+ *
+ * @internal
+ */
+export function slSourceFileName(sourceName) {
+    if (SAFE_FILE_BASENAME.test(sourceName) && !WINDOWS_RESERVED_BASENAME.test(sourceName)) {
+        return `${sourceName}.yaml`;
+    }
+    const slug = sourceName
+        .toLowerCase()
+        .replace(/[^a-z0-9_]+/g, '_')
+        .replace(/_+/g, '_')
+        .replace(/^_+|_+$/g, '')
+        .slice(0, 64);
+    const hash = createHash('sha256').update(sourceName, 'utf-8').digest('hex').slice(0, 8);
+    return `${slug || 'src'}-${hash}.yaml`;
+}
+export function slSourceFilePath(connectionId, sourceName) {
+    return `semantic-layer/${assertSafeConnectionId(connectionId)}/${slSourceFileName(sourceName)}`;
+}
+// Same keying as `loadLocalSlSourceRecords`: the in-file `name:` is the identity;
+// the filename is only a fallback for files so broken that even the `name:` is
+// unrecoverable, or genuinely nameless ones. A file left mid-edit with a syntax
+// error below its `name:` line keeps its declared identity (see
+// `slDeclaredSourceName`), so a human-renamed source is still addressed by name
+// while broken instead of silently reverting to its filename.
+export function slSourceNameForFile(path, content) {
+    return slDeclaredSourceName(content) ?? sourceNameFromPath(path);
+}
+/**
+ * The `name:` a semantic-layer YAML file declares, or null when the file is
+ * nameless or so broken even the name is unrecoverable. Null is how
+ * `writeSource` tells a genuine name conflict at a derived path apart from the
+ * broken remains of the source being written, which a rewrite must repair
+ * rather than refuse.
+ *
+ * Uses `parseDocument`, not `parse`: a file with a syntax error below the
+ * `name:` line still parses into a partial tree whose top-level `name:` is
+ * intact. `parse` would throw on the same input and drop the source to its
+ * filename — wrong for human-renamed files, whose filename is not the name.
+ */
+export function slDeclaredSourceName(content) {
+    let doc;
+    try {
+        doc = YAML.parseDocument(content);
+    }
+    catch {
+        return null;
+    }
+    const name = doc.get('name');
+    return typeof name === 'string' && name.length > 0 ? name : null;
+}
+/**
+ * Find the standalone/overlay file that defines `sourceName` for a connection.
+ * Returns null when no file declares the name (the source may still exist as a
+ * manifest entry under `_schema/`). Throws when more than one file declares the
+ * same name — that breaks the one-file-per-name invariant and must be repaired
+ * by hand rather than silently picking one.
+ */
+export async function resolveSlSourceFile(fileStore, connectionId, sourceName) {
+    const dir = `semantic-layer/${assertSafeConnectionId(connectionId)}`;
+    const schemaDir = `${dir}/_schema`;
+    const listed = await fileStore.listFiles(dir);
+    const paths = listed.files.filter((file) => isSlYamlPath(file) && !file.startsWith(`${schemaDir}/`)).sort();
+    const matches = [];
+    for (const path of paths) {
+        const raw = await fileStore.readFile(path);
+        if (slSourceNameForFile(path, raw.content) === sourceName) {
+            matches.push({ path, content: raw.content });
+        }
+    }
+    if (matches.length > 1) {
+        throw new Error(`Multiple semantic-layer files declare source "${sourceName}": ${matches.map((match) => match.path).join(', ')}`);
+    }
+    return matches[0] ?? null;
+}

package/dist/context/sl/tools/base-semantic-layer.tool.d.ts

@@ -1,4 +1,4 @@
-import type { ZodType } from 'zod';
+import type { z } from 'zod';
 import type { GitAuthorResolverPort } from '../../../context/tools/authors.js';
 import type { ToolContext, ToolOutput } from '../../../context/tools/base-tool.js';
 import { BaseTool } from '../../../context/tools/base-tool.js';
@@ -21,7 +21,7 @@ export interface BaseSemanticLayerToolDeps {
     slSearchService: SlSearchService;
     authorResolver: GitAuthorResolverPort;
 }
-export declare abstract class BaseSemanticLayerTool<TInput extends ZodType = ZodType> extends BaseTool<TInput> {
+export declare abstract class BaseSemanticLayerTool<TInput extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>> extends BaseTool<TInput> {
     protected readonly semanticLayerService: SemanticLayerService;
     protected readonly slSearchService: SlSearchService;
     protected readonly authorResolver: GitAuthorResolverPort;

package/dist/context/sl/tools/base-semantic-layer.tool.js

@@ -14,13 +14,8 @@ export class BaseSemanticLayerTool extends BaseTool {
     }
     async readSourceYaml(connectionId, sourceName, context) {
         const semanticLayerService = context?.session?.semanticLayerService ?? this.semanticLayerService;
-        try {
-            const { content } = await semanticLayerService.readSourceFile(connectionId, sourceName);
-            return content;
-        }
-        catch {
-            return null;
-        }
+        const file = await semanticLayerService.readSourceFile(connectionId, sourceName);
+        return file?.content ?? null;
     }
     buildMarkdown(success, errors, sourceName, extra) {
         const parts = [];

package/dist/context/sl/tools/sl-edit-source.tool.js

@@ -91,14 +91,8 @@ If no source exists yet, use sl_write_source instead — this tool will reject t
             }
         }
         // Read existing source
-        let currentYaml = null;
-        try {
-            const { content } = await semanticLayerService.readSourceFile(connectionId, sourceName);
-            currentYaml = content;
-        }
-        catch {
-            currentYaml = null;
-        }
+        const currentFile = await semanticLayerService.readSourceFile(connectionId, sourceName);
+        const currentYaml = currentFile?.content ?? null;
         if (!currentYaml) {
             const manifestBacked = await semanticLayerService.isManifestBacked(connectionId, sourceName);
             if (manifestBacked) {
@@ -138,6 +132,14 @@ If no source exists yet, use sl_write_source instead — this tool will reject t
         catch (e) {
             return this.buildOutput(false, [`YAML parse error after edits: ${e}`], sourceName);
         }
+        // The in-file `name:` is the source's identity — an edited name would make
+        // writeSource create a second source instead of updating this one.
+        if (source.name !== sourceName) {
+            return this.buildOutput(false, [
+                `Edits change "name:" from "${sourceName}" to "${source.name ?? '<missing>'}" — renaming is not supported. ` +
+                    `Delete the source and recreate it under the new name.`,
+            ], sourceName);
+        }
         source = normalizeSemanticLayerDescriptions(source, { fillMissing: !!context.session?.ingest });
         // Re-serialize and write
         const updatedYaml = YAML.stringify(source, { indent: 2, lineWidth: 0, version: '1.1' });

package/dist/context/sl/tools/sl-warehouse-validation.js

@@ -2,8 +2,8 @@ import YAML from 'yaml';
 import { SYSTEM_GIT_AUTHOR } from '../../../context/tools/authors.js';
 import { sourceOverlaySchema } from '../schemas.js';
 import { SemanticLayerService } from '../semantic-layer.service.js';
+import { resolveSlSourceFile, slSourceFilePath } from '../source-files.js';
 import { sourceDefinitionSchema } from './base-semantic-layer.tool.js';
-const slSourcePath = (connectionId, sourceName) => `semantic-layer/${connectionId}/${sourceName}.yaml`;
 function resolveDialect(warehouse) {
     if (!warehouse) {
         return null;
@@ -33,32 +33,28 @@ function wrapWithSingleRowQuery(sql, dialect) {
 export async function validateSingleSource(deps, connectionId, sourceName) {
     const errors = [];
     const warnings = [];
-    let content;
-    try {
-        const result = await deps.semanticLayerService.readSourceFile(connectionId, sourceName);
-        content = result.content;
-    }
-    catch {
-        errors.push(`${sourceName}.yaml: file not found`);
+    const file = await deps.semanticLayerService.readSourceFile(connectionId, sourceName);
+    if (!file) {
+        errors.push(`${sourceName}: no standalone or overlay file found`);
         return { errors, warnings };
     }
     let parsed;
     try {
-        parsed = YAML.parse(content);
+        parsed = YAML.parse(file.content);
     }
     catch (e) {
-        errors.push(`${sourceName}.yaml: invalid YAML — ${e instanceof Error ? e.message : String(e)}`);
+        errors.push(`${sourceName}: invalid YAML — ${e instanceof Error ? e.message : String(e)}`);
         return { errors, warnings };
     }
     if (!parsed || typeof parsed !== 'object') {
-        errors.push(`${sourceName}.yaml: top-level content is not an object`);
+        errors.push(`${sourceName}: top-level content is not an object`);
         return { errors, warnings };
     }
     const isOverlay = !parsed.table && !parsed.sql;
     if (!isOverlay) {
         const isManifestBacked = await deps.semanticLayerService.isManifestBacked(connectionId, sourceName);
         if (isManifestBacked) {
-            errors.push(`${sourceName}.yaml: standalone source shadows an existing manifest entry — ` +
+            errors.push(`${sourceName}: standalone source shadows an existing manifest entry — ` +
                 `writing it as-is drops the manifest's columns and joins. ` +
                 `Remove "sql:", "table:", "grain:", and base-table "columns:" and keep only ` +
                 `"name:" plus overlay fields such as "measures:", "segments:", "descriptions:", ` +
@@ -71,16 +67,16 @@ export async function validateSingleSource(deps, connectionId, sourceName) {
     const result = schema.safeParse(parsed);
     if (!result.success) {
         const issues = result.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ');
-        errors.push(`${sourceName}.yaml: schema — ${issues}`);
+        errors.push(`${sourceName}: schema — ${issues}`);
         const errorPaths = new Set(result.error.issues.map((i) => String(i.path[0])));
         if (errorPaths.has('joins')) {
-            warnings.push(`${sourceName}.yaml: hint — join format: {to, on: 'local_col = TARGET.col', relationship: 'many_to_one|one_to_many|one_to_one'}`);
+            warnings.push(`${sourceName}: hint — join format: {to, on: 'local_col = TARGET.col', relationship: 'many_to_one|one_to_many|one_to_one'}`);
         }
         if (errorPaths.has('columns')) {
-            warnings.push(`${sourceName}.yaml: hint — overlay columns must be computed: {name, expr, type}. Use column_overrides for manifest column descriptions or metadata.`);
+            warnings.push(`${sourceName}: hint — overlay columns must be computed: {name, expr, type}. Use column_overrides for manifest column descriptions or metadata.`);
         }
         if (errorPaths.has('measures')) {
-            warnings.push(`${sourceName}.yaml: hint — measure format: {name, expr, description (optional), filter (optional)}`);
+            warnings.push(`${sourceName}: hint — measure format: {name, expr, description (optional), filter (optional)}`);
         }
         return { errors, warnings };
     }
@@ -93,7 +89,7 @@ export async function validateSingleSource(deps, connectionId, sourceName) {
     const seenMeasures = new Set();
     for (const m of measures) {
         if (seenMeasures.has(m.name)) {
-            errors.push(`${sourceName}.yaml: duplicate measure name "${m.name}"`);
+            errors.push(`${sourceName}: duplicate measure name "${m.name}"`);
         }
         seenMeasures.add(m.name);
     }
@@ -125,7 +121,7 @@ export async function validateSingleSource(deps, connectionId, sourceName) {
             const actual = new Set((probe.headers ?? []).map((h) => h.toLowerCase()));
             const missing = sourceColumns.map((c) => c.name).filter((n) => !actual.has(n.toLowerCase()));
             if (missing.length > 0) {
-                errors.push(`${sourceName}.yaml: declared columns absent from sql result — ${missing.join(', ')} (warehouse returned: ${[...actual].slice(0, 10).join(', ')}${actual.size > 10 ? ', …' : ''})`);
+                errors.push(`${sourceName}: declared columns absent from sql result — ${missing.join(', ')} (warehouse returned: ${[...actual].slice(0, 10).join(', ')}${actual.size > 10 ? ', …' : ''})`);
             }
         }
         catch (e) {
@@ -151,7 +147,7 @@ function formatProbeError(args) {
     const errMsg = error instanceof Error ? error.message : String(error);
     const refColumns = sourceColumns.filter((c) => referencesColumn(probeSql, c.name));
     const lines = [
-        measureName ? `${sourceName}.yaml: measure "${measureName}" ${headline}.` : `${sourceName}.yaml: ${headline}.`,
+        measureName ? `${sourceName}: measure "${measureName}" ${headline}.` : `${sourceName}: ${headline}.`,
     ];
     if (warehouse) {
         lines.push(`  Warehouse: ${warehouse}`);
@@ -179,7 +175,7 @@ async function probeOverlayMeasures(deps, connectionId, sourceName, warehouse) {
         composed = all.find((s) => s.name === sourceName);
     }
     catch (e) {
-        errors.push(`${sourceName}.yaml: failed to load composed source for probe — ${e instanceof Error ? e.message : String(e)}`);
+        errors.push(`${sourceName}: failed to load composed source for probe — ${e instanceof Error ? e.message : String(e)}`);
         return errors;
     }
     if (!composed?.table || composed.measures.length === 0) {
@@ -214,22 +210,54 @@ async function probeOverlayMeasures(deps, connectionId, sourceName, warehouse) {
     }
     return errors;
 }
+/**
+ * A read-only view of the config repo at one commit, shaped for
+ * `resolveSlSourceFile` so name→file resolution runs against history exactly as
+ * it does against the working tree — one resolver, two backing stores. Used to
+ * recover the path a source occupied at `preHead` after the live file is gone.
+ */
+function gitCommitFileStore(git, commitHash) {
+    return {
+        async listFiles(path) {
+            return { files: await git.listFilesAtCommit(path, commitHash) };
+        },
+        async readFile(path) {
+            return { content: await git.getFileAtCommit(path, commitHash) };
+        },
+    };
+}
 /**
  * Restore `sourceName` to the content it had at `preHead`, or delete it if it didn't
  * exist then. Used by sl_rollback (agent-driven) and the pre-squash revert gate
  * (automatic). Returns a short human-readable description of what happened.
  */
 export async function revertSourceToPreHead(deps, connectionId, preHead, sourceName) {
-    const relPath = slSourcePath(connectionId, sourceName);
+    // Find the file that defines this source. While it is still on disk
+    // (invalid-but-present) the live resolver finds it by its in-file `name:`.
+    // Once the session deleted it, the path is gone too — and humans rename files
+    // freely, so it is NOT the writer-derived filename. Recover it from history by
+    // resolving the name against the preHead commit instead of guessing.
+    const live = await resolveSlSourceFile(deps.configService, connectionId, sourceName);
+    let relPath;
     let preContent = null;
-    if (preHead) {
-        try {
-            preContent = await deps.gitService.getFileAtCommit(relPath, preHead);
-        }
-        catch {
-            preContent = null;
+    if (live) {
+        relPath = live.path;
+        if (preHead) {
+            try {
+                preContent = await deps.gitService.getFileAtCommit(relPath, preHead);
+            }
+            catch {
+                preContent = null;
+            }
         }
     }
+    else {
+        const atPreHead = preHead
+            ? await resolveSlSourceFile(gitCommitFileStore(deps.gitService, preHead), connectionId, sourceName)
+            : null;
+        relPath = atPreHead?.path ?? slSourceFilePath(connectionId, sourceName);
+        preContent = atPreHead?.content ?? null;
+    }
     if (preContent !== null) {
         await deps.configService.writeFile(relPath, preContent, SYSTEM_GIT_AUTHOR.name, SYSTEM_GIT_AUTHOR.email, `Revert SL source to pre-session state: ${sourceName}`, { skipLock: true });
         return 'restored to pre-session content';

package/dist/context/sl/tools/sl-write-source.tool.js

@@ -12,8 +12,10 @@ const slWriteSourceInputSchema = z.object({
     connectionId: slToolConnectionIdSchema.describe('Data source connection ID'),
     sourceName: z
         .string()
-        .regex(/^[a-z0-9][a-z0-9_]*$/, 'Source name must be snake_case (lowercase alphanumeric and underscores)')
-        .describe('Name of the source to create, edit, or delete'),
+        .min(1)
+        .describe("Name of the source to create, edit, or delete. Must equal the source's `name:`. Use the verbatim " +
+        'warehouse identifier when overlaying a manifest source (e.g. SIGNED_UP); snake_case is recommended ' +
+        'for new standalone sources.'),
     source: sourceInputSchema
         .optional()
         .describe('Source definition (standalone with table/sql) or overlay (measures, column_overrides, computed columns, etc.)'),
@@ -122,6 +124,12 @@ Do NOT join back to a table that the SQL already aggregates from if the grain co
         if (!input.source) {
             return this.buildOutput(false, ['Provide `source` to create or rewrite. For targeted edits, use sl_edit_source.'], sourceName);
         }
+        // The in-file `name:` is the source's identity; the file is written under
+        // source.name while the orphan/shadow checks key on sourceName — a mismatch
+        // would validate one source and save another.
+        if (input.source.name !== sourceName) {
+            return this.buildOutput(false, [`source.name "${input.source.name}" does not match sourceName "${sourceName}" — they must be identical.`], sourceName);
+        }
         return this.writeFullSource(connectionId, input.source, sourceName, author, authorEmail, context, semanticLayerService, skipIndex, rawPathValidation.rawPaths);
     }
     async writeFullSource(connectionId, source, sourceName, author, authorEmail, context, semanticLayerService, skipIndex, rawPaths) {
@@ -183,13 +191,8 @@ Do NOT join back to a table that the SQL already aggregates from if the grain co
         }
     }
     async readSourceYamlFromService(service, connectionId, sourceName) {
-        try {
-            const { content } = await service.readSourceFile(connectionId, sourceName);
-            return content;
-        }
-        catch {
-            return null;
-        }
+        const file = await service.readSourceFile(connectionId, sourceName);
+        return file?.content ?? null;
     }
     async rejectOrphanOverlay(semanticLayerService, connectionId, sourceName, content) {
         let parsed;

package/dist/context/sql-analysis/dialect.d.ts

@@ -0,0 +1,2 @@
+import type { SqlAnalysisDialect } from './ports.js';
+export declare function sqlAnalysisDialectForDriver(driver: string | undefined): SqlAnalysisDialect;

package/dist/context/sql-analysis/dialect.js

@@ -0,0 +1,20 @@
+// One mapping from ktx connection identity to the sqlglot dialect name used by
+// the Python daemon (SQL analysis, read-only validation) and semantic-layer
+// compute. Keys cover both vocabularies that name a connection's engine:
+// ktx.yaml driver names ("postgres", "sqlserver") and the local connection-type
+// spellings exposed by KtxConnectionInfo.connectionType ("POSTGRESQL").
+const SQLGLOT_DIALECTS = {
+    postgres: 'postgres',
+    postgresql: 'postgres',
+    bigquery: 'bigquery',
+    snowflake: 'snowflake',
+    mysql: 'mysql',
+    sqlserver: 'tsql',
+    sqlite: 'sqlite',
+    duckdb: 'duckdb',
+    clickhouse: 'clickhouse',
+    databricks: 'databricks',
+};
+export function sqlAnalysisDialectForDriver(driver) {
+    return SQLGLOT_DIALECTS[(driver ?? '').toLowerCase()] ?? 'postgres';
+}

package/dist/context/tools/base-tool.d.ts

@@ -1,4 +1,5 @@
-import { z, type ZodType } from 'zod';
+import { type Tool } from 'ai';
+import { z } from 'zod';
 import { type KtxLogger } from '../../context/core/config.js';
 import type { KtxRuntimeToolDescriptor } from '../llm/runtime-port.js';
 import type { IngestToolMetadata, ToolSession } from './tool-session.js';
@@ -56,30 +57,16 @@ interface MethodologyEntry {
 /**
  * SECURITY: All tools require authentication. userId must always be provided in ToolContext.
  */
-export declare abstract class BaseTool<TInput extends ZodType = ZodType> {
+export declare abstract class BaseTool<TInput extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>> {
     protected readonly logger: KtxLogger;
     abstract readonly name: string;
     constructor(logger?: KtxLogger);
     abstract get description(): string;
     abstract get inputSchema(): TInput;
-    abstract call(input: z.infer<TInput>, context: ToolContext): Promise<any>;
-    getParametersSchema(): {
-        type: 'object';
-        properties: Record<string, any>;
-        required?: string[];
-    };
-    toAnthropicFormat(): {
-        name: string;
-        description: string;
-        input_schema: {
-            type: 'object';
-            properties: Record<string, any>;
-            required?: string[];
-        };
-    };
-    toAiSdkTool(context: ToolContext): any;
+    abstract call(input: z.infer<TInput>, context: ToolContext): Promise<unknown>;
+    toAiSdkTool(context: ToolContext): Tool;
     toRuntimeTool(context: ToolContext): KtxRuntimeToolDescriptor;
-    parseInput(input: Record<string, any>): z.infer<TInput>;
+    parseInput(input: Record<string, unknown>): z.infer<TInput>;
     protected getCurrentUserQuery(context: ToolContext): string | null;
 }
 export {};

package/dist/context/tools/base-tool.js

@@ -1,5 +1,4 @@
 import { tool } from 'ai';
-import { z } from 'zod';
 import { noopLogger } from '../../context/core/config.js';
 import { normalizeKtxRuntimeToolOutput } from '../llm/runtime-tools.js';
 /**
@@ -10,19 +9,6 @@ export class BaseTool {
     constructor(logger = noopLogger) {
         this.logger = logger;
     }
-    getParametersSchema() {
-        const jsonSchema = z.toJSONSchema(this.inputSchema, {
-            target: 'draft-7',
-        });
-        return jsonSchema;
-    }
-    toAnthropicFormat() {
-        return {
-            name: this.name,
-            description: this.description,
-            input_schema: this.getParametersSchema(),
-        };
-    }
     toAiSdkTool(context) {
         const toolName = this.name;
         const logger = this.logger;

package/dist/context-build-view.js

@@ -260,7 +260,7 @@ export function renderContextBuildView(state, options = {}) {
     const totalCount = allTargets.length;
     const hasActive = allTargets.some((t) => t.status === 'running' || t.status === 'queued');
     const allDone = totalCount > 0 && !hasActive;
-    const headerParts = [options.title ?? 'Building KTX context'];
+    const headerParts = [options.title ?? 'Building ktx context'];
     if (totalCount > 0) {
         const progressParts = [`${doneCount}/${totalCount}`];
         if (state.totalElapsedMs > 0)
@@ -550,7 +550,7 @@ function failedStepDetail(result) {
     return result.steps.find((step) => step.status === 'failed')?.detail ?? null;
 }
 const INTERNAL_FAILURE_LINE_RE = /^(Report|Run|Job|Status|Adapter|Connection|Sync|Mode|Dry run|Diff|Tasks|Work units|Failed tasks|Saved memory|Provenance rows):\s*/;
-const ACTIONABLE_FAILURE_LINE_RE = /^(Missing bundled Python runtime manifest|KTX Python runtime is required|KTX daemon HTTP|Error:|Failed\b|Could not\b|Cannot\b)/;
+const ACTIONABLE_FAILURE_LINE_RE = /^(Missing bundled Python runtime manifest|ktx Python runtime is required|ktx daemon HTTP|Error:|Failed\b|Could not\b|Cannot\b)/;
 function trimErrorPrefix(line) {
     return line.replace(/^Error:\s*/, '');
 }
@@ -559,7 +559,7 @@ function firstCapturedFailureLine(output) {
         .split(/\r?\n/)
         .map((candidate) => candidate.trim())
         .filter((candidate) => candidate.length > 0)
-        .filter((candidate) => !candidate.startsWith('KTX scan completed'))
+        .filter((candidate) => !candidate.startsWith('ktx scan completed'))
         .filter((candidate) => !INTERNAL_FAILURE_LINE_RE.test(candidate));
     const line = lines.find((candidate) => ACTIONABLE_FAILURE_LINE_RE.test(candidate)) ?? lines.at(-1) ?? null;
     return line ? trimErrorPrefix(line) : null;
@@ -584,7 +584,7 @@ function failureTextForTarget(input) {
     const code = networkErrorCode(input.error, input.capturedOutput);
     if (code && isLocalSqlAnalysisConnectionRefused({ capturedOutput: input.capturedOutput, fallback: input.fallback })) {
         return [
-            `KTX could not reach the local SQL analysis runtime while processing query history for ${input.target.connectionId}.`,
+            `ktx could not reach the local SQL analysis runtime while processing query history for ${input.target.connectionId}.`,
             `Reason: ${NETWORK_ERROR_REASONS[code]} (${code}).`,
             `Retry: ${retryCommand({
                 projectDir: input.projectDir,
@@ -598,7 +598,7 @@ function failureTextForTarget(input) {
     if (code) {
         const operation = input.target.operation === 'database-ingest' ? 'reading schema for' : 'ingesting';
         return [
-            `KTX lost its connection to ${friendlyDriverName(input.target.driver)} while ${operation} ${input.target.connectionId}.`,
+            `ktx lost its connection to ${friendlyDriverName(input.target.driver)} while ${operation} ${input.target.connectionId}.`,
             `Reason: ${NETWORK_ERROR_REASONS[code]} (${code}).`,
             `Retry: ${retryCommand({
                 projectDir: input.projectDir,

package/dist/database-tree-picker.js

@@ -1,5 +1,7 @@
 import { parseDottedTableEntry } from './context/scan/enabled-tables.js';
+import { createStaticCliSpinner } from './clack.js';
 import { profileMark } from './startup-profile.js';
+import { withSearchableMultiselectNavigation } from './prompt-navigation.js';
 import { buildInitialState, buildPickerTree, } from './tree-picker-state.js';
 import { renderTreePickerTui, } from './tree-picker-tui.js';
 profileMark('module:database-tree-picker');
@@ -167,7 +169,7 @@ export async function pickDatabaseScope(args, io, render = defaultRenderer) {
     let selectedSchemas = initialStageOneSchemas(args);
     while (true) {
         const pickedSchemas = await args.prompts.autocompleteMultiselect({
-            message: `Choose ${args.schemaNounPlural} to enable for ${args.connectionId}\nType to filter. Space to select. Enter when done.`,
+            message: withSearchableMultiselectNavigation(`Choose ${args.schemaNounPlural} to enable for ${args.connectionId}`),
             placeholder: `Search ${args.schemaNounPlural}`,
             options: schemaOptions(args),
             initialValues: selectedSchemas,
@@ -178,7 +180,7 @@ export async function pickDatabaseScope(args, io, render = defaultRenderer) {
         }
         selectedSchemas = pickedSchemas;
         if (selectedSchemas.length === 0) {
-            io.stderr.write(`Nothing selected - type to filter, or Escape to skip ${args.schemaNoun} scope.\n`);
+            io.stderr.write(`Nothing selected - type to search, or Escape to skip ${args.schemaNoun} scope.\n`);
             continue;
         }
         const selectedNoun = selectedSchemas.length === 1 ? args.schemaNoun : args.schemaNounPlural;
@@ -193,7 +195,20 @@ export async function pickDatabaseScope(args, io, render = defaultRenderer) {
         if (action === 'back') {
             continue;
         }
-        const discovered = await args.listTablesForSchemas(selectedSchemas);
+        // Static (stderr-only) spinner: the stage-two table picker below is a raw-mode
+        // Ink TUI, and an animated clack spinner would leave stdin dirty so Ink reads a
+        // stray Escape and exits immediately.
+        const tablesSpinner = createStaticCliSpinner(io);
+        tablesSpinner.start(`Listing tables in ${selectedSchemas.length} ${selectedNoun}…`);
+        let discovered;
+        try {
+            discovered = await args.listTablesForSchemas(selectedSchemas);
+        }
+        catch (error) {
+            tablesSpinner.error('Could not list tables');
+            throw error;
+        }
+        tablesSpinner.stop(`Found ${discovered.length} ${discovered.length === 1 ? 'table' : 'tables'}`);
         if (action === 'save' && args.existing.enabledTables.length === 0) {
             return {
                 kind: 'selected',

package/dist/demo-assets.js

@@ -46,7 +46,6 @@ function demoConfig(databasePath) {
         '  state: sqlite',
         '  search: sqlite-fts5',
         '  git:',
-        '    auto_commit: true',
         '    author: ktx <ktx@example.com>',
         'llm:',
         '  provider:',

package/dist/doctor.d.ts

@@ -67,7 +67,7 @@ interface RenderOptions {
 }
 export declare function formatDoctorReport(report: DoctorReport, options?: Partial<RenderOptions>): string;
 export declare function renderInvalidConfigMessage(projectDir: string, issues: KtxConfigIssue[], outputMode: KtxDoctorOutputMode, io: KtxDoctorIo): void;
-export declare function renderValidConfigMessage(projectDir: string, outputMode: KtxDoctorOutputMode, io: KtxDoctorIo): void;
+export declare function renderValidConfigMessage(projectDir: string, outputMode: KtxDoctorOutputMode, io: KtxDoctorIo, warnings?: KtxConfigIssue[]): void;
 export declare function renderMissingProjectMessage(projectDir: string, outputMode: KtxDoctorOutputMode, io: KtxDoctorIo): void;
 export declare function runKtxDoctor(args: KtxDoctorArgs, io?: KtxDoctorIo, deps?: KtxDoctorDeps): Promise<number>;
 export {};