@kaelio/ktx 0.11.0 → 0.12.0

package/dist/admin.js

@@ -18,7 +18,7 @@ export function registerAdminCommands(program, context) {
     });
     admin
         .command('init')
-        .description('Initialize a Git-backed KTX project directory for maintenance scripts')
+        .description('Initialize a Git-backed ktx project directory for maintenance scripts')
         .argument('[directory]', 'Project directory')
         .option('--force', 'Rewrite ktx.yaml and scaffold files in an existing project', false)
         .action(async (projectDir, commandOptions, command) => {

package/dist/clack.d.ts

@@ -39,5 +39,21 @@ export interface KtxCliPromptAdapter {
     spinner(): KtxCliSpinner;
 }
 export declare function createClackSpinner(): KtxCliSpinner;
+/**
+ * Stderr-only, non-animated spinner. Use this instead of {@link createCliSpinner}
+ * when the next step reads stdin in raw mode (an Ink TUI or a keypress wait):
+ * the animated clack spinner seizes stdin via `@clack/core`'s `block()` and
+ * leaves it dirty, which the following raw-mode reader misreads as a stray key.
+ */
 export declare function createStaticCliSpinner(io: KtxCliSpinnerIo): KtxCliSpinner;
+/**
+ * Animated spinner in an interactive terminal, static `◐/◇/■` lines otherwise
+ * (scripts, CI, piped output) so logs stay clean and uncluttered by frames.
+ */
+export declare function createCliSpinner(io: KtxCliIo): KtxCliSpinner;
+export declare function runWithCliSpinner<T>(spinner: KtxCliSpinner, text: {
+    start: string;
+    success: string;
+    failure: string;
+}, run: () => Promise<T>): Promise<T>;
 export declare function createClackPromptAdapter(): KtxCliPromptAdapter;

package/dist/clack.js

@@ -36,30 +36,61 @@ class KtxCliPromptCancelledError extends Error {
     }
 }
 export function createClackSpinner() {
-    return spinner();
+    // clack colors the animated spinner frame magenta by default; styleFrame
+    // (typed in SpinnerOptions, absent from the README) recolors it ktx orange.
+    return spinner({ styleFrame: orange });
 }
-function magenta(text) {
-    return ansiColor(text, 35, 39);
+// ktx mascot orange (#FF8A4C) via 24-bit truecolor.
+function orange(text) {
+    if (!ansiEnabled()) {
+        return text;
+    }
+    return `${ESC}[38;2;255;138;76m${text}${ESC}[39m`;
 }
 function red(text) {
     return ansiColor(text, 31, 39);
 }
+/**
+ * Stderr-only, non-animated spinner. Use this instead of {@link createCliSpinner}
+ * when the next step reads stdin in raw mode (an Ink TUI or a keypress wait):
+ * the animated clack spinner seizes stdin via `@clack/core`'s `block()` and
+ * leaves it dirty, which the following raw-mode reader misreads as a stray key.
+ */
 export function createStaticCliSpinner(io) {
     return {
         start(message) {
-            io.stderr.write(`${magenta('◐')}  ${message}\n`);
+            io.stderr.write(`${orange('◐')}  ${message}\n`);
         },
         message(message) {
-            io.stderr.write(`${magenta('│')}  ${message}\n`);
+            io.stderr.write(`${orange('│')}  ${message}\n`);
         },
         stop(message) {
-            io.stderr.write(`${magenta('◇')}  ${message}\n`);
+            io.stderr.write(`${orange('◇')}  ${message}\n`);
         },
         error(message) {
             io.stderr.write(`${red('■')}  ${message}\n`);
         },
     };
 }
+/**
+ * Animated spinner in an interactive terminal, static `◐/◇/■` lines otherwise
+ * (scripts, CI, piped output) so logs stay clean and uncluttered by frames.
+ */
+export function createCliSpinner(io) {
+    return io.stdout.isTTY === true ? createClackSpinner() : createStaticCliSpinner(io);
+}
+export async function runWithCliSpinner(spinner, text, run) {
+    spinner.start(text.start);
+    try {
+        const value = await run();
+        spinner.stop(text.success);
+        return value;
+    }
+    catch (error) {
+        spinner.error(text.failure);
+        throw error;
+    }
+}
 export function createClackPromptAdapter() {
     return {
         async confirm(options) {

package/dist/claude-code-prompt-caching.js

@@ -15,7 +15,7 @@ export function formatClaudeCodePromptCachingWarning(fields) {
     if (fields.length === 0) {
         return null;
     }
-    return `claude-code ignores ${fields.join(', ')} because the Claude Agent SDK does not expose KTX prompt-cache TTL, tool, or history markers.`;
+    return `claude-code ignores ${fields.join(', ')} because the Claude Agent SDK does not expose ktx prompt-cache TTL, tool, or history markers.`;
 }
 export function formatClaudeCodePromptCachingFix() {
     return 'Remove those promptCaching fields or use anthropic, vertex, or gateway when those cache knobs are required.';

package/dist/cli-program.js

@@ -162,8 +162,8 @@ export function resolveCommandProjectDirOverride(command) {
 function createBaseProgram(info, io) {
     return new Command()
         .name('ktx')
-        .description('KTX data agent context layer CLI')
-        .option('--project-dir <path>', 'KTX project directory (default: KTX_PROJECT_DIR, nearest ktx.yaml, or cwd)')
+        .description('ktx data agent context layer CLI')
+        .option('--project-dir <path>', 'ktx project directory (default: KTX_PROJECT_DIR, nearest ktx.yaml, or cwd)')
         .option('--debug', 'Enable diagnostic logging to stderr')
         .version(`${info.name} ${info.version}`, '-v, --version', 'Show CLI version')
         .helpOption('-h, --help', 'Show this help text')
@@ -349,7 +349,7 @@ export function buildKtxProgram(options) {
         const attachProjectGroup = shouldAttachCommandProjectGroup(path, hasProject);
         telemetry.beginCommandSpan({
             commandPath: path,
-            flagsPresent: collectCommandFlagsPresent(commandNode),
+            flagsPresent: collectCommandFlagsPresent(actionCommand),
             projectDir: attachProjectGroup ? projectDir : undefined,
             hasProject,
             attachProjectGroup,

package/dist/cli-runtime.js

@@ -14,7 +14,7 @@ export function packageInfoFromJson(packageJson) {
         !('version' in packageJson) ||
         typeof packageJson.name !== 'string' ||
         typeof packageJson.version !== 'string') {
-        throw new Error('Invalid KTX CLI package metadata');
+        throw new Error('Invalid ktx CLI package metadata');
     }
     return {
         name: packageJson.name,
@@ -28,7 +28,7 @@ async function runInit(args, io) {
         projectDir: args.projectDir,
         force: args.force,
     });
-    io.stdout.write(`Initialized KTX project at ${result.projectDir}\n`);
+    io.stdout.write(`Initialized ktx project at ${result.projectDir}\n`);
     io.stdout.write(`Config: ${result.configPath}\n`);
     io.stdout.write(`Commit: ${result.commitHash ?? 'none'}\n`);
     return 0;

package/dist/commands/connection-commands.js

@@ -27,7 +27,7 @@ export function registerConnectionCommands(program, context, commandName = 'conn
     connection
         .command('test')
         .description('Test one or all configured connections (default: all)')
-        .argument('[connectionId]', 'KTX connection id to test (omit to test all)')
+        .argument('[connectionId]', 'ktx connection id to test (omit to test all)')
         .option('--all', 'Test every configured connection and print a summary list')
         .action(async (connectionId, options, command) => {
         if (options.all === true && connectionId !== undefined) {

package/dist/commands/ingest-commands.js

@@ -7,16 +7,16 @@ profileMark('module:commands/ingest-commands');
 export function registerIngestCommands(program, context, commandOptions) {
     const ingest = program
         .command('ingest')
-        .description('Build or inspect KTX context, or capture text into memory')
+        .description('Build or inspect ktx context, or capture text into memory')
         .usage('[options] [connectionId]')
         .argument('[connectionId]', 'Configured connection id to ingest (omit to ingest all)')
         .option('--all', 'Ingest all configured connections', false)
         .addOption(new Option('--query-history', 'Include database query-history usage patterns').conflicts('noQueryHistory'))
         .addOption(new Option('--no-query-history', 'Skip database query-history usage patterns'))
         .option('--query-history-window-days <days>', 'Query-history lookback window for this run', parsePositiveIntegerOption)
-        .option('--text <content>', 'Capture inline text into KTX memory; repeatable', collectOption, [])
-        .option('--file <path>', 'Capture a text file into KTX memory; use - for stdin; repeatable', collectOption, [])
-        .option('--connection-id <connectionId>', 'KTX connection id to tag captured text/file notes')
+        .option('--text <content>', 'Capture inline text into ktx memory; repeatable', collectOption, [])
+        .option('--file <path>', 'Capture a text file into ktx memory; use - for stdin; repeatable', collectOption, [])
+        .option('--connection-id <connectionId>', 'ktx connection id to tag captured text/file notes')
         .option('--user-id <id>', 'Memory user id for text/file capture attribution', 'local-cli')
         .option('--fail-fast', 'Stop after the first failed text/file item', false)
         .addOption(new Option('--plain', 'Print plain text output').conflicts(['json']))

package/dist/commands/mcp-commands.js

@@ -13,11 +13,11 @@ function binPath() {
 }
 function formatMcpStartResultMessage(input) {
     return [
-        input.status === 'started' ? `KTX MCP daemon started: ${input.url}` : `KTX MCP daemon already running: ${input.url}`,
+        input.status === 'started' ? `ktx MCP daemon started: ${input.url}` : `ktx MCP daemon already running: ${input.url}`,
         '',
-        'KTX is ready for configured agents.',
-        'Open your agent for this KTX project and ask a data question, for example:',
-        '  "Use KTX to show me the available tables and metrics."',
+        'ktx is ready for configured agents.',
+        'Open your agent for this ktx project and ask a data question, for example:',
+        '  "Use ktx to show me the available tables and metrics."',
         '',
     ].join('\n');
 }
@@ -34,13 +34,13 @@ async function printMcpStatus(context, projectDir) {
 export function registerMcpCommands(program, context) {
     const mcp = program
         .command('mcp')
-        .description('Manage the KTX MCP HTTP server (bare command: show status)')
+        .description('Manage the ktx MCP HTTP server (bare command: show status)')
         .action(async (_options, command) => {
         await printMcpStatus(context, resolveCommandProjectDir(command));
     });
     mcp
         .command('stdio')
-        .description('Run the KTX MCP server over stdio')
+        .description('Run the ktx MCP server over stdio')
         .action(async (_options, command) => {
         await (context.deps.mcp?.runStdioServer ?? runKtxMcpStdioServer)({
             projectDir: resolveCommandProjectDir(command),
@@ -50,7 +50,7 @@ export function registerMcpCommands(program, context) {
     });
     mcp
         .command('start')
-        .description('Start the KTX MCP HTTP server')
+        .description('Start the ktx MCP HTTP server')
         .option('--host <host>', 'Host to bind', '127.0.0.1')
         .option('--port <n>', 'Port to bind', parsePositiveIntegerOption, 7878)
         .option('--token <token>', 'Bearer token required for non-loopback binding')
@@ -78,7 +78,7 @@ export function registerMcpCommands(program, context) {
                 allowedOrigins: options.allowedOrigin,
                 io: context.io,
             });
-            context.io.stdout.write(`KTX MCP server listening at http://${options.host}:${options.port}/mcp\n`);
+            context.io.stdout.write(`ktx MCP server listening at http://${options.host}:${options.port}/mcp\n`);
             return;
         }
         const result = await (context.deps.mcp?.startDaemon ?? startKtxMcpDaemon)({
@@ -95,22 +95,22 @@ export function registerMcpCommands(program, context) {
     });
     mcp
         .command('stop')
-        .description('Stop the KTX MCP daemon')
+        .description('Stop the ktx MCP daemon')
         .action(async (_options, command) => {
         const result = await (context.deps.mcp?.stopDaemon ?? stopKtxMcpDaemon)({
             projectDir: resolveCommandProjectDir(command),
         });
-        context.io.stdout.write(result.status === 'stopped' ? 'KTX MCP daemon stopped.\n' : 'KTX MCP daemon is not running.\n');
+        context.io.stdout.write(result.status === 'stopped' ? 'ktx MCP daemon stopped.\n' : 'ktx MCP daemon is not running.\n');
     });
     mcp
         .command('status')
-        .description('Show KTX MCP daemon status')
+        .description('Show ktx MCP daemon status')
         .action(async (_options, command) => {
         await printMcpStatus(context, resolveCommandProjectDir(command));
     });
     mcp
         .command('logs')
-        .description('Print the KTX MCP daemon log')
+        .description('Print the ktx MCP daemon log')
         .option('--follow', 'Follow log output', false)
         .action(async (options, command) => {
         const logPath = mcpDaemonLayout(resolveCommandProjectDir(command)).logPath;

package/dist/commands/runtime-commands.js

@@ -12,7 +12,7 @@ async function runRuntimeArgs(context, args) {
 export function registerRuntimeCommands(program, context) {
     const runtime = program
         .command('runtime')
-        .description('Install, start, stop, and inspect the KTX-managed Python runtime')
+        .description('Install, start, stop, and inspect the ktx-managed Python runtime')
         .showHelpAfterError();
     runtime
         .command('install')
@@ -30,7 +30,7 @@ export function registerRuntimeCommands(program, context) {
     });
     runtime
         .command('start')
-        .description('Start the KTX daemon')
+        .description('Start the ktx daemon')
         .addOption(createRuntimeFeatureOption())
         .option('--force', 'Restart even when a matching daemon is already running', false)
         .action(async (options, command) => {
@@ -44,8 +44,8 @@ export function registerRuntimeCommands(program, context) {
     });
     runtime
         .command('stop')
-        .description('Stop the KTX daemon')
-        .option('--all', 'Stop all KTX daemon processes recorded or discoverable on this machine', false)
+        .description('Stop the ktx daemon')
+        .option('--all', 'Stop all ktx daemon processes recorded or discoverable on this machine', false)
         .action(async (options, command) => {
         await runRuntimeArgs(context, {
             command: 'stop',

package/dist/commands/setup-commands.js

@@ -1,5 +1,6 @@
 import { InvalidArgumentError, Option } from '@commander-js/extra-typings';
 import { resolveCommandProjectDir } from '../cli-program.js';
+import { isKtxSetupLlmBackend } from '../setup-models.js';
 async function runSetupArgs(context, args) {
     const runner = context.deps.setup ?? (await import('../setup.js')).runKtxSetup;
     context.setExitCode(await runner(args, context.io));
@@ -7,7 +8,7 @@ async function runSetupArgs(context, args) {
 function positiveInteger(value) {
     const parsed = Number.parseInt(value, 10);
     if (!Number.isInteger(parsed) || parsed <= 0) {
-        throw new Error(`Expected a positive integer, received ${value}`);
+        throw new InvalidArgumentError(`Expected a positive integer, received ${value}`);
     }
     return parsed;
 }
@@ -18,7 +19,7 @@ function embeddingBackend(value) {
     throw new InvalidArgumentError(`invalid choice '${value}'`);
 }
 function llmBackend(value) {
-    if (value === 'anthropic' || value === 'vertex' || value === 'claude-code' || value === 'codex') {
+    if (isKtxSetupLlmBackend(value)) {
         return value;
     }
     throw new InvalidArgumentError(`invalid choice '${value}'`);
@@ -125,8 +126,8 @@ function shouldShowSetupEntryMenu(options, command) {
 export function registerSetupCommands(program, context) {
     const setup = program
         .command('setup')
-        .description('Set up or resume a local KTX project')
-        .addOption(new Option('--project-dir <path>', 'KTX project directory').hideHelp())
+        .description('Set up or resume a local ktx project')
+        .addOption(new Option('--project-dir <path>', 'ktx project directory').hideHelp())
         .option('--agents', 'Install agent integration only', false)
         .addOption(new Option('--target <target>', 'Agent target').choices([
         'claude-code',
@@ -184,7 +185,7 @@ export function registerSetupCommands(program, context) {
         .argParser((value, previous) => [...previous, value])
         .default([])
         .hideHelp())
-        .addOption(new Option('--skip-databases', 'Leave database setup incomplete; KTX cannot work until a database is added')
+        .addOption(new Option('--skip-databases', 'Leave database setup incomplete; ktx cannot work until a database is added')
         .hideHelp()
         .default(false))
         .addOption(new Option('--source <type>', 'Source connector type').argParser(sourceType).hideHelp())

package/dist/commands/sl-commands.js

@@ -30,7 +30,7 @@ export function registerSlCommands(program, context, commandName = 'sl') {
         .description('List, search, validate, or query local semantic-layer sources')
         .usage('[options] [query...]')
         .argument('[query...]', 'Search query; omit to list all sources')
-        .option('--connection-id <id>', 'KTX connection id')
+        .option('--connection-id <id>', 'ktx connection id')
         .option('--limit <number>', 'Maximum search results (search mode only)', parsePositiveIntegerOption)
         .addOption(new Option('--output <mode>', 'Output mode: pretty (default in TTY), plain (TSV), or json').choices([
         'pretty',

package/dist/commands/sql-commands.js

@@ -20,7 +20,7 @@ export function registerSqlCommands(program, context) {
         .command('sql')
         .description('Execute parser-validated read-only SQL against a configured connection')
         .argument('<sql...>', 'SQL query to execute')
-        .requiredOption('-c, --connection <id>', 'KTX connection id')
+        .requiredOption('-c, --connection <id>', 'ktx connection id')
         .option('--max-rows <n>', 'Maximum rows to return', parseSqlMaxRowsOption, DEFAULT_MAX_ROWS)
         .addOption(new Option('--output <mode>', 'Output mode: pretty (default), plain (TSV), or json').choices([
         'pretty',

package/dist/commands/status-commands.js

@@ -10,7 +10,7 @@ function inputMode(options) {
 export function registerStatusCommands(program, context) {
     program
         .command('status')
-        .description('Check current KTX setup and project readiness')
+        .description('Check current ktx setup and project readiness')
         .option('--json', 'Print JSON output', false)
         .option('-v, --verbose', 'Show every check, including passing ones', false)
         .option('--validate', 'Only validate the ktx.yaml schema; skip readiness checks', false)

package/dist/connection.js

@@ -86,7 +86,7 @@ async function testMetabaseConnection(project, connectionId, createClient) {
 }
 async function createDefaultLookerClient(project, connectionId) {
     const factory = new DefaultLookerConnectionClientFactory(createLocalLookerCredentialResolver(project));
-    return (await factory.createClient(connectionId));
+    return factory.createLookerClient(connectionId);
 }
 async function testLookerConnection(project, connectionId, createClient) {
     const client = await createClient(project, connectionId);

package/dist/connectors/clickhouse/connector.js

@@ -432,7 +432,7 @@ export class KtxClickHouseScanConnector {
     }
     assertConnection(connectionId) {
         if (connectionId !== this.connectionId) {
-            throw new Error(`KTX ClickHouse connector ${this.id} cannot serve connection ${connectionId}`);
+            throw new Error(`ktx ClickHouse connector ${this.id} cannot serve connection ${connectionId}`);
         }
     }
 }

package/dist/connectors/mysql/connector.js

@@ -508,7 +508,7 @@ export class KtxMysqlScanConnector {
     }
     assertConnection(connectionId) {
         if (connectionId !== this.connectionId) {
-            throw new Error(`KTX MySQL connector ${this.id} cannot serve connection ${connectionId}`);
+            throw new Error(`ktx MySQL connector ${this.id} cannot serve connection ${connectionId}`);
         }
     }
 }

package/dist/connectors/snowflake/connector.d.ts

@@ -72,7 +72,7 @@ export interface KtxSnowflakeScanConnectorOptions {
     connectionId: string;
     connection: KtxSnowflakeConnectionConfig | undefined;
     /**
-     * KTX project directory. When provided, snowflake-sdk's logger is redirected to
+     * ktx project directory. When provided, snowflake-sdk's logger is redirected to
      * `<projectDir>/.ktx/logs/snowflake.log` so its JSON output does not bleed into
      * the CLI's TTY. Tests that use a fake driverFactory can leave this undefined.
      */

package/dist/connectors/sqlite/connector.js

@@ -35,29 +35,6 @@ function sqlitePathFromUrl(url) {
     }
     return url;
 }
-function stripLeadingSqlComments(sql) {
-    let index = 0;
-    while (index < sql.length) {
-        while (/\s/.test(sql[index] ?? '')) {
-            index += 1;
-        }
-        if (sql.startsWith('--', index)) {
-            const end = sql.indexOf('\n', index + 2);
-            index = end === -1 ? sql.length : end + 1;
-            continue;
-        }
-        if (sql.startsWith('/*', index)) {
-            const end = sql.indexOf('*/', index + 2);
-            if (end === -1) {
-                return sql.slice(index);
-            }
-            index = end + 2;
-            continue;
-        }
-        break;
-    }
-    return sql.slice(index);
-}
 export function isKtxSqliteConnectionConfig(connection) {
     const driver = String(connection?.driver ?? '').toLowerCase();
     return driver === 'sqlite';
@@ -171,7 +148,7 @@ export class KtxSqliteScanConnector {
     }
     async executeReadOnly(input, _ctx) {
         this.assertConnection(input.connectionId);
-        const result = this.query(limitSqlForExecution(stripLeadingSqlComments(input.sql), input.maxRows), input.params);
+        const result = this.query(limitSqlForExecution(input.sql, input.maxRows), input.params);
         return { ...result, rowCount: result.rows.length };
     }
     async getColumnDistinctValues(table, columnName, options) {
@@ -274,7 +251,7 @@ export class KtxSqliteScanConnector {
     }
     assertConnection(connectionId) {
         if (connectionId !== this.connectionId) {
-            throw new Error(`KTX SQLite connector ${this.id} cannot serve connection ${connectionId}`);
+            throw new Error(`ktx SQLite connector ${this.id} cannot serve connection ${connectionId}`);
         }
     }
 }

package/dist/connectors/sqlserver/connector.js

@@ -1,4 +1,4 @@
-import { assertReadOnlySql } from '../../context/connections/read-only-sql.js';
+import { assertReadOnlySql, stripTrailingSqlNoise } from '../../context/connections/read-only-sql.js';
 import { getDialectForDriver } from '../../context/connections/dialects.js';
 import { tryConstraintQuery } from '../../context/scan/constraint-discovery.js';
 import { scopedTableNames } from '../../context/scan/table-ref.js';
@@ -142,7 +142,7 @@ function isDeniedError(error) {
     return number === 229 || number === 230 || number === 297;
 }
 function limitSqlForSqlServerExecution(sqlText, maxRows) {
-    const trimmed = assertReadOnlySql(sqlText).replace(/;+\s*$/, '');
+    const trimmed = stripTrailingSqlNoise(assertReadOnlySql(sqlText));
     if (!maxRows) {
         return trimmed;
     }
@@ -575,7 +575,7 @@ export class KtxSqlServerScanConnector {
     }
     assertConnection(connectionId) {
         if (connectionId !== this.connectionId) {
-            throw new Error(`KTX SQL Server connector ${this.id} cannot serve connection ${connectionId}`);
+            throw new Error(`ktx SQL Server connector ${this.id} cannot serve connection ${connectionId}`);
         }
     }
 }

package/dist/context/connections/connection-type.d.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 export declare const connectionTypeSchema: z.ZodEnum<{
+    PLAIN: "PLAIN";
     BIGQUERY: "BIGQUERY";
     SNOWFLAKE: "SNOWFLAKE";
     MYSQL: "MYSQL";
@@ -19,7 +20,6 @@ export declare const connectionTypeSchema: z.ZodEnum<{
     METABASE: "METABASE";
     LOOKER: "LOOKER";
     NOTION: "NOTION";
-    PLAIN: "PLAIN";
     BETTERSTACK: "BETTERSTACK";
 }>;
 export type ConnectionType = z.infer<typeof connectionTypeSchema>;

package/dist/context/connections/read-only-sql.d.ts

@@ -1,2 +1,3 @@
 export declare function assertReadOnlySql(sql: string): string;
+export declare function stripTrailingSqlNoise(sql: string): string;
 export declare function limitSqlForExecution(sql: string, maxRows: number | undefined): string;

package/dist/context/connections/read-only-sql.js

@@ -1,14 +1,128 @@
 const MUTATING_SQL = /^\s*(insert|update|delete|merge|alter|drop|create|truncate|grant|revoke|copy|call|do|vacuum|analyze|refresh)\b/i;
 const READ_SQL = /^\s*(select|with)\b/i;
+// Agents (and the daemon's sqlglot validator, which ignores comments) routinely
+// emit read-only queries prefixed with `-- ...` or `/* ... */`. Strip leading
+// comments so the prefix check sees the real statement; otherwise valid SELECT/WITH
+// SQL is rejected here while the parser-backed validator accepts it.
+function stripLeadingSqlComments(sql) {
+    let index = 0;
+    while (index < sql.length) {
+        while (/\s/.test(sql[index] ?? '')) {
+            index += 1;
+        }
+        if (sql.startsWith('--', index)) {
+            const end = sql.indexOf('\n', index + 2);
+            index = end === -1 ? sql.length : end + 1;
+            continue;
+        }
+        if (sql.startsWith('/*', index)) {
+            const end = sql.indexOf('*/', index + 2);
+            if (end === -1) {
+                return sql.slice(index);
+            }
+            index = end + 2;
+            continue;
+        }
+        break;
+    }
+    return sql.slice(index);
+}
+// Lexes past one string literal, quoted identifier, or comment starting at
+// `index`, using standard-SQL rules ('' and "" escapes; no dialect extensions
+// such as backslash escapes or dollar quoting). Returns the index after the
+// token, or `index` unchanged when no quoted/comment token starts there.
+function skipQuotedOrComment(sql, index) {
+    const quote = sql[index];
+    if (quote === "'" || quote === '"') {
+        let i = index + 1;
+        while (i < sql.length) {
+            if (sql[i] === quote) {
+                if (sql[i + 1] === quote) {
+                    i += 2;
+                    continue;
+                }
+                return i + 1;
+            }
+            i += 1;
+        }
+        return sql.length;
+    }
+    if (sql.startsWith('--', index)) {
+        const end = sql.indexOf('\n', index + 2);
+        return end === -1 ? sql.length : end + 1;
+    }
+    if (sql.startsWith('/*', index)) {
+        const end = sql.indexOf('*/', index + 2);
+        return end === -1 ? sql.length : end + 2;
+    }
+    return index;
+}
+// Backstop against statement smuggling (`select 1; drop table x`): reject any
+// semicolon that is followed by real content. Semicolons inside string
+// literals, quoted identifiers, and comments are fine, as are trailing
+// semicolons (optionally followed by whitespace and comments). This deliberately
+// lexes standard SQL only, so dialect-specific escapes can cause a false
+// reject — never a false accept; the canonical gate is the daemon's
+// sqlglot-backed validateReadOnly.
+function assertSingleSqlStatement(sql) {
+    let index = 0;
+    let sawSemicolon = false;
+    while (index < sql.length) {
+        const skipped = skipQuotedOrComment(sql, index);
+        if (skipped > index) {
+            index = skipped;
+            continue;
+        }
+        if (sql[index] === ';') {
+            sawSemicolon = true;
+        }
+        else if (sawSemicolon && !/\s/.test(sql[index])) {
+            throw new Error('Only one SQL statement can be executed.');
+        }
+        index += 1;
+    }
+}
 export function assertReadOnlySql(sql) {
-    const trimmed = sql.trim();
+    const trimmed = stripLeadingSqlComments(sql).trim();
     if (!READ_SQL.test(trimmed) || MUTATING_SQL.test(trimmed)) {
         throw new Error('Only read-only SELECT/WITH queries can be executed locally.');
     }
+    assertSingleSqlStatement(trimmed);
     return trimmed;
 }
+// `assertReadOnlySql` deliberately keeps trailing semicolons, comments, and
+// whitespace (e.g. `select 1; -- done`) — harmless for direct single-statement
+// execution. A row-limit subquery wrapper needs a bare expression instead: a
+// trailing `;` would sit illegally inside the subquery, and a trailing line
+// comment would comment out the closing paren and limit clause. Lex forward with
+// the same standard-SQL rules as the single-statement gate and truncate at the
+// end of the last meaningful token, dropping trailing semicolons, comments, and
+// whitespace. Characters inside string literals and quoted identifiers stay
+// meaningful, so a `;` or `--` within a literal is never mistaken for a
+// terminator (a plain regex cannot make that distinction).
+export function stripTrailingSqlNoise(sql) {
+    let index = 0;
+    let meaningfulEnd = 0;
+    while (index < sql.length) {
+        if (sql.startsWith('--', index) || sql.startsWith('/*', index)) {
+            index = skipQuotedOrComment(sql, index);
+            continue;
+        }
+        const afterQuoted = skipQuotedOrComment(sql, index);
+        if (afterQuoted > index) {
+            meaningfulEnd = afterQuoted;
+            index = afterQuoted;
+            continue;
+        }
+        if (sql[index] !== ';' && !/\s/.test(sql[index] ?? '')) {
+            meaningfulEnd = index + 1;
+        }
+        index += 1;
+    }
+    return sql.slice(0, meaningfulEnd);
+}
 export function limitSqlForExecution(sql, maxRows) {
-    const trimmed = assertReadOnlySql(sql).replace(/;+\s*$/, '');
+    const trimmed = stripTrailingSqlNoise(assertReadOnlySql(sql));
     if (!maxRows) {
         return trimmed;
     }