dbtour 0.7.1 → 0.9.0

package/dist/cli.d.ts

@@ -10,6 +10,8 @@ export interface Io {
     load?: (source: SourceConfig) => Promise<Source>;
     /** How an add-on is loaded; tests hand in their own. */
     loadAddon?: (addon: AddonConfig) => Promise<Addon>;
+    /** When serve stops; Ctrl+C unless a test hands in its own. */
+    stop?: Promise<void>;
     /** Where mcp reads requests and writes answers; process.stdin and process.stdout unless a test hands in its own. */
     stdin?: Readable;
     stdout?: Writable;

package/dist/cli.js

@@ -13,10 +13,13 @@ import { createInterface } from 'node:readline';
 import { dirname, join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { parseArgs } from 'node:util';
-import { configFile, defaultConfigText, modelFile, parseConfig, resolveConnection } from "./config.js";
+import { configFile, defaultConfigText, modelFile, parseConfig, resolveConnection, resolveReader } from "./config.js";
 import { emptyModel, scope, validate } from "./model.js";
 import { applyNotes, parseNotes } from "./notes.js";
 import { answerLine } from "./mcp.js";
+import { checkQuery, clampLimit, defaultTimeoutMs, resultText } from "./sql.js";
+import { startServer } from "./serve.js";
+import { randomBytes } from 'node:crypto';
 import { loadAddon, loadSource } from "./plugins.js";
 import { renderMarkdown } from "./render/markdown.js";
 const help = `Usage: dbtour <command>
@@ -27,10 +30,19 @@ const help = `Usage: dbtour <command>
                           add-ons in ${configFile} render (explorer: index.html) under <out>
   mcp [project]           answer an agent's questions about <out>/${modelFile} and the notes over MCP,
                           on stdin and stdout: claude mcp add dbtour -- npx dbtour mcp
+  sql "<query>"           run one SELECT through a source's reader, a read-only login of its own,
+                          rolled back, at most --limit rows (100); --source <name>, --json
+  serve [--port 4321]     the rendered page on this machine; its SQL editor runs queries through the
+                          readers, as sql does
 
 Set the connection string in the environment variable ${configFile} names, never in the file.`;
 export async function main(argv, io = { cwd: process.cwd(), log: console.log, error: console.error }) {
-    const { values, positionals } = parseArgs({ args: argv, options: { help: { type: 'boolean', short: 'h' }, source: { type: 'string' } }, allowPositionals: true, strict: false });
+    const { values, positionals } = parseArgs({
+        args: argv,
+        options: { help: { type: 'boolean', short: 'h' }, source: { type: 'string' }, limit: { type: 'string' }, json: { type: 'boolean' }, port: { type: 'string' } },
+        allowPositionals: true,
+        strict: false,
+    });
     const command = positionals[0];
     if (values.help || command === undefined) {
         io.log(help);
@@ -46,6 +58,14 @@ export async function main(argv, io = { cwd: process.cwd(), log: console.log, er
                 return await render(io);
             case 'mcp':
                 return await mcp(positionals[1] === undefined ? io : { ...io, cwd: resolve(io.cwd, positionals[1]) });
+            case 'serve':
+                return await serve(io, typeof values.port === 'string' ? Number(values.port) : defaultPort);
+            case 'sql':
+                return await sql(io, positionals[1], {
+                    source: typeof values.source === 'string' ? values.source : undefined,
+                    limit: typeof values.limit === 'string' ? Number(values.limit) : undefined,
+                    json: values.json === true,
+                });
             default:
                 io.error(`"${command}" is not a dbtour command.\n\n${help}`);
                 return 1;
@@ -189,10 +209,112 @@ async function mcp(io) {
     };
     const version = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
     const output = io.stdout ?? process.stdout;
+    // The query tool is offered only when a source has a reader; its errors go back to the agent as text.
+    const run = config.sources.some((s) => s.reader !== undefined)
+        ? async (text, source, limit) => {
+            try {
+                return { content: [{ type: 'text', text: resultText(await runQuery(io, config, text, source, limit)) }] };
+            }
+            catch (error) {
+                return { content: [{ type: 'text', text: error instanceof Error ? error.message : String(error) }], isError: true };
+            }
+        }
+        : undefined;
+    // One request at a time, in order: a query is awaited before the next line is read.
     for await (const line of createInterface({ input: io.stdin ?? process.stdin, crlfDelay: Infinity })) {
-        const reply = answerLine(line, { model: current, version });
+        const reply = await answerLine(line, { model: current, version, run });
         if (reply !== undefined)
             output.write(reply + '\n');
     }
     return 0;
 }
+/** dbtour serve's port unless --port says otherwise: one an editor's own dev servers seldom take. */
+const defaultPort = 4321;
+/**
+ * The rendered folder on 127.0.0.1, with a door for its SQL editor: a query posted by the page runs as dbtour
+ * sql runs it. A token made fresh each time is handed to the page and required on every query.
+ */
+async function serve(io, port) {
+    const config = readConfig(io);
+    const root = join(io.cwd, config.out);
+    if (!existsSync(join(root, 'index.html')))
+        throw missing(`No ${join(config.out, 'index.html')} to serve: add explorer to addons in ${configFile}, run dbtour render, then dbtour serve again`);
+    const readers = config.sources.filter((s) => s.reader !== undefined);
+    const token = randomBytes(24).toString('base64url');
+    let server;
+    try {
+        server = await startServer({
+            root,
+            port,
+            token,
+            sources: config.sources.map((s) => ({ name: s.name, reader: s.reader !== undefined })),
+            run: readers.length
+                ? async (text, source, limit) => ({ ...(await runQuery(io, config, text, source, limit)), source: pickSource(config, source).name })
+                : undefined,
+        });
+    }
+    catch (error) {
+        if (error.code === 'EADDRINUSE')
+            throw new Error(`Port ${port} is taken: run dbtour serve --port ${port + 1}`, { cause: error });
+        throw error;
+    }
+    io.log(`Serving ${config.out} at ${server.url}`);
+    io.log(readers.length ? `Queries run through ${readers.map((s) => `${s.name}'s reader`).join(', ')}. Ctrl+C to stop.` : `No source has a reader, so the page can be read but runs no query: add reader to a source in ${configFile}. Ctrl+C to stop.`);
+    await (io.stop ?? new Promise((done) => process.once('SIGINT', () => done())));
+    await server.close();
+    return 0;
+}
+async function sql(io, text, options) {
+    if (text === undefined || text.trim() === '') {
+        io.error('Give the query to run: dbtour sql "SELECT TOP (10) * FROM dbo.Orders"');
+        return 1;
+    }
+    const result = await runQuery(io, readConfig(io), text, options.source, options.limit);
+    io.log(options.json ? JSON.stringify(result, cellJson, 2) : resultText(result));
+    return 0;
+}
+/** JSON for a cell: a date as ISO, bytes as hex. */
+function cellJson(_key, value) {
+    if (value && typeof value === 'object' && value.type === 'Buffer')
+        return `0x${Buffer.from(value.data).toString('hex')}`;
+    return value;
+}
+/**
+ * The query checked, then run through the chosen source's reader. Refusals throw before any connection is
+ * made: a query that is not one read, no reader or the extract's own login, a source that cannot run.
+ */
+async function runQuery(io, config, text, sourceName, limit) {
+    const checked = checkQuery(text);
+    if (!checked.ok)
+        throw new Error(checked.reason);
+    const source = pickSource(config, sourceName);
+    const reader = resolveReader(source, io.env ?? process.env);
+    const load = io.load ?? ((s) => loadSource(s, importer(io.cwd)));
+    const { run } = await load(source);
+    if (run === undefined)
+        throw missing(`Source ${source.name} (${source.type}) cannot run queries: update ${source.module ?? `dbtour-source-${source.type}`} to the version of dbtour you have, then run it again`);
+    try {
+        return await run({ ...source, connection: reader }, checked.sql, { limit: clampLimit(limit), timeoutMs: defaultTimeoutMs });
+    }
+    catch (error) {
+        throw new Error(`${source.name} (${source.type}): ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+}
+/** The source named, or the only one with a reader; several want a name, and none says what to add. */
+function pickSource(config, name) {
+    if (name !== undefined) {
+        const named = config.sources.filter((s) => s.name === name);
+        if (named.length === 0)
+            throw new Error(`There is no source named ${name}: ${config.sources.map((s) => s.name).join(', ')}`);
+        // Two of one name would leave which database the query runs in to the order of the file.
+        if (named.length > 1)
+            throw new Error(`Two sources are named ${name}: give each its own name in ${configFile}, then run it again`);
+        return named[0];
+    }
+    const readers = config.sources.filter((s) => s.reader !== undefined);
+    if (readers.length === 1)
+        return readers[0];
+    if (readers.length > 1)
+        throw new Error(`Several sources have a reader: say which with ${readers.map((s) => `--source ${s.name}`).join(' or ')}`);
+    return config.sources[0];
+}

package/dist/config.d.ts

@@ -3,6 +3,11 @@ export interface SourceConfig {
     name: string;
     /** `${NAME}`: the environment variable holding the connection string. Never the string itself. */
     connection?: string;
+    /**
+     * `${NAME}`: the variable holding the connection string queries run with, for a login of its own with
+     * db_datareader alone. Never the extract's connection.
+     */
+    reader?: string;
     /** A module to import instead of dbtour-source-<type>. */
     module?: string;
     [option: string]: unknown;
@@ -24,3 +29,9 @@ export declare const modelFile = "schema.json";
 export declare function parseConfig(text: string): Config;
 export declare function defaultConfigText(type: string): string;
 export declare function resolveConnection(value: string | undefined, env: Record<string, string | undefined>): string | undefined;
+/**
+ * The connection queries run with: the source's reader, a login of its own. Refused when it is missing (exit
+ * 2, with what to add), when it names the same variable as the extract's connection, or when the two
+ * variables hold the same string, since then a query would run with a login that may write.
+ */
+export declare function resolveReader(source: SourceConfig, env: Record<string, string | undefined>): string;

package/dist/config.js

@@ -52,6 +52,8 @@ sources:
     name: ${type === 'mssql' ? 'MyDatabase' : 'my-database'}
     # The name of the environment variable holding the connection string. Never the string itself.
     connection: \${${variable}}
+    # Optional: a read-only login of its own (db_datareader), for dbtour sql and the MCP query tool.
+    # reader: \${${variable}_READER}
 # Descriptions, relations and groups the database cannot say. Optional.
 notes: dbtour.notes.yaml
 # What else render writes. explorer is the page: npm install --save-dev dbtour-addon-explorer
@@ -73,3 +75,25 @@ export function resolveConnection(value, env) {
     }
     return resolved;
 }
+/**
+ * The connection queries run with: the source's reader, a login of its own. Refused when it is missing (exit
+ * 2, with what to add), when it names the same variable as the extract's connection, or when the two
+ * variables hold the same string, since then a query would run with a login that may write.
+ */
+export function resolveReader(source, env) {
+    const example = `\${DBTOUR_${source.type.toUpperCase()}_READER}`;
+    if (typeof source.reader !== 'string' || source.reader === '') {
+        throw Object.assign(new Error(`Source ${source.name} has no reader, the login dbtour runs queries with: add "reader: ${example}" to it in ${configFile}, naming a login with db_datareader alone, and set that variable`), { exitCode: 2 });
+    }
+    const readerVariable = variablePattern.exec(source.reader)?.[1];
+    const connectionVariable = typeof source.connection === 'string' ? variablePattern.exec(source.connection)?.[1] : undefined;
+    if (readerVariable !== undefined && readerVariable === connectionVariable) {
+        throw new Error(`reader names the same variable as connection (${readerVariable}): a reader is a login of its own, with db_datareader alone, so a query can never write`);
+    }
+    const reader = resolveConnection(source.reader, env);
+    const connection = connectionVariable === undefined ? undefined : env[connectionVariable];
+    if (connection !== undefined && connection === reader) {
+        throw new Error(`reader resolves to the same connection string as connection: give ${readerVariable} a login of its own, with db_datareader alone`);
+    }
+    return reader;
+}

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export * from './model.ts';
 export { parseNotes, applyNotes, type Notes, type TableNotes, type RelationNote, type Applied } from './notes.ts';
-export { parseConfig, defaultConfigText, resolveConnection, configFile, modelFile, type Config, type SourceConfig, type AddonConfig } from './config.ts';
-export { loadSource, sourceModuleName, loadAddon, addonModuleName, type Source, type Extract, type Importer, type Addon, type Files } from './plugins.ts';
+export { parseConfig, defaultConfigText, resolveConnection, resolveReader, configFile, modelFile, type Config, type SourceConfig, type AddonConfig } from './config.ts';
+export { loadSource, sourceModuleName, loadAddon, addonModuleName, type Source, type Extract, type Run, type Importer, type Addon, type Files } from './plugins.ts';
+export { checkQuery, clampLimit, resultText, formatCell, defaultLimit, maxLimit, defaultTimeoutMs, maxResultBytes, type QueryResult, type RunOptions, type Checked } from './sql.ts';
 export { renderMarkdown, renderTableMarkdown, driverName, wholeDiagramLimit } from './render/markdown.ts';
 export { erDiagram, neighbourhood, entityName } from './render/mermaid.ts';

package/dist/index.js

@@ -1,6 +1,7 @@
 export * from "./model.js";
 export { parseNotes, applyNotes } from "./notes.js";
-export { parseConfig, defaultConfigText, resolveConnection, configFile, modelFile } from "./config.js";
+export { parseConfig, defaultConfigText, resolveConnection, resolveReader, configFile, modelFile } from "./config.js";
 export { loadSource, sourceModuleName, loadAddon, addonModuleName } from "./plugins.js";
+export { checkQuery, clampLimit, resultText, formatCell, defaultLimit, maxLimit, defaultTimeoutMs, maxResultBytes } from "./sql.js";
 export { renderMarkdown, renderTableMarkdown, driverName, wholeDiagramLimit } from "./render/markdown.js";
 export { erDiagram, neighbourhood, entityName } from "./render/mermaid.js";

package/dist/mcp.d.ts

@@ -5,6 +5,11 @@ export interface Context {
     /** The model with its notes, read again when the files change; throws when there is none. */
     model: () => Model;
     version: string;
+    /**
+     * Runs a query through a source's reader. Given only when a source has one, and only then is the query
+     * tool offered: the other tools read the model, this one reads rows.
+     */
+    run?: (sql: string, source: string | undefined, limit: number | undefined) => Promise<ToolResult>;
 }
 export interface ToolResult {
     content: {
@@ -28,6 +33,22 @@ export declare const toolList: {
     };
 }[];
 /** One line in, at most one line out: a notification and a blank line get none. */
-export declare function answerLine(line: string, context: Context): string | undefined;
-export declare function answer(message: unknown, context: Context): object | undefined;
+export declare function answerLine(line: string, context: Context): string | undefined | Promise<string | undefined>;
+/** The answer to one request; a promise only for a query, the one tool that waits on the database. */
+export declare function answer(message: unknown, context: Context): object | undefined | Promise<object>;
+/** Offered beside the others only when a source has a reader; see Context.run. */
+export declare const queryTool: {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: Record<string, unknown>;
+        required: string[];
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        openWorldHint: boolean;
+    };
+};
 export declare function callTool(model: Model, name: string, args: Record<string, unknown>): ToolResult;

package/dist/mcp.js

@@ -5,6 +5,7 @@
 import { findTables, localRef, tableRef } from "./model.js";
 import { driverName, formatCount, renderTableMarkdown } from "./render/markdown.js";
 import { buildIndex, search } from "./search.js";
+import { checkQuery, defaultLimit, maxLimit } from "./sql.js";
 // The versions this server speaks, newest first. It uses only initialize, ping, tools/list and tools/call,
 // which none of them changed, so it agrees to whichever the client asks for and offers the newest otherwise.
 export const protocolVersions = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05'];
@@ -77,8 +78,11 @@ export function answerLine(line, context) {
         return JSON.stringify(failure(null, -32700, 'That line is not JSON: send one JSON-RPC message per line.'));
     }
     const response = answer(message, context);
+    if (response instanceof Promise)
+        return response.then((r) => JSON.stringify(r));
     return response === undefined ? undefined : JSON.stringify(response);
 }
+/** The answer to one request; a promise only for a query, the one tool that waits on the database. */
 export function answer(message, context) {
     if (typeof message !== 'object' || message === null || Array.isArray(message))
         return failure(null, -32600, 'Send one JSON-RPC request as an object; batches are not accepted.');
@@ -109,12 +113,15 @@ export function answer(message, context) {
         case 'ping':
             return success(id, {});
         case 'tools/list':
-            return success(id, { tools: toolList });
+            return success(id, { tools: context.run ? [...toolList, queryTool] : toolList });
         case 'tools/call': {
             const name = params.name;
-            if (typeof name !== 'string' || !toolNames.includes(name))
-                return failure(id, -32602, `There is no tool "${String(name)}": the tools are ${toolNames.join(', ')}.`);
+            const offered = context.run ? [...toolNames, queryTool.name] : toolNames;
+            if (typeof name !== 'string' || !offered.includes(name))
+                return failure(id, -32602, `There is no tool "${String(name)}": the tools are ${offered.join(', ')}.`);
             const args = typeof params.arguments === 'object' && params.arguments !== null ? params.arguments : {};
+            if (name === queryTool.name)
+                return callQuery(context.run, args).then((result) => success(id, result));
             let model;
             try {
                 model = context.model();
@@ -128,6 +135,37 @@ export function answer(message, context) {
             return failure(id, -32601, `dbtour does not answer ${request.method}: it offers tools only.`);
     }
 }
+/** Offered beside the others only when a source has a reader; see Context.run. */
+export const queryTool = {
+    name: 'query',
+    title: 'Query',
+    description: `Run one SELECT (or WITH … SELECT) through the project's read-only login, inside a transaction that is always rolled back, and get the rows as a table, ${defaultLimit} at most unless you ask for fewer or more (up to ${maxLimit}). Read every table you name with the table tool first. The rows go to the model provider your agent uses: leave out columns that are masked, encrypted or carry a sensitivity label unless the question needs them.`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            sql: { type: 'string', description: 'One SELECT, or a WITH followed by a SELECT, in the database\'s dialect.' },
+            source: { type: 'string', description: 'The source to run it in, by its name in dbtour.yaml, when more than one has a reader.' },
+            limit: { type: 'number', description: `The most rows to return; ${defaultLimit} if not given.` },
+        },
+        required: ['sql'],
+    },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+};
+/** A query refused here never reaches the source; one that runs comes back as the source's answer. */
+async function callQuery(run, args) {
+    if (typeof args.sql !== 'string' || args.sql.trim() === '')
+        return problem('query needs sql: one SELECT, like SELECT TOP (10) * FROM dbo.Orders.');
+    const checked = checkQuery(args.sql);
+    if (!checked.ok)
+        return problem(checked.reason);
+    // Whatever goes wrong in the database is this call's failure, not the server's: the next request is answered.
+    try {
+        return await run(checked.sql, typeof args.source === 'string' ? args.source : undefined, typeof args.limit === 'number' ? args.limit : undefined);
+    }
+    catch (error) {
+        return problem(error instanceof Error ? error.message : String(error));
+    }
+}
 function success(id, result) {
     return { jsonrpc: '2.0', id, result };
 }

package/dist/plugins.d.ts

@@ -1,8 +1,16 @@
 import type { AddonConfig, SourceConfig } from './config.ts';
 import type { Api, Database, Model } from './model.ts';
+import type { QueryResult, RunOptions } from './sql.ts';
 export type Extract = (config: SourceConfig) => Promise<Database | Api>;
+/**
+ * Runs one query dbtour has already checked, with `config.connection` set to the source's reader: read-only,
+ * inside a transaction the source always rolls back, at most `limit` rows, cancelled after `timeoutMs`.
+ */
+export type Run = (config: SourceConfig, sql: string, options: RunOptions) => Promise<QueryResult>;
 export interface Source {
     extract: Extract;
+    /** Absent from a source that cannot run queries, or from one published before it could. */
+    run?: Run;
 }
 export type Importer = (specifier: string) => Promise<unknown>;
 export declare function sourceModuleName(source: SourceConfig): string;

package/dist/plugins.js

@@ -22,7 +22,8 @@ export async function loadSource(source, importer = (s) => import(__rewriteRelat
     const extract = loaded?.extract;
     if (typeof extract !== 'function')
         throw new Error(`${name} does not export extract(config), so it is not a dbtour source`);
-    return { extract: extract };
+    const run = loaded.run;
+    return typeof run === 'function' ? { extract: extract, run: run } : { extract: extract };
 }
 export function addonModuleName(addon) {
     return addon.module ?? `dbtour-addon-${addon.type}`;

package/dist/serve.d.ts

@@ -0,0 +1,24 @@
+import type { QueryResult } from './sql.ts';
+export interface Served {
+    /** The folder render wrote: index.html and the Markdown beside it. */
+    root: string;
+    /** 0 for any free port. */
+    port: number;
+    /** The session's secret, given to the page in a meta tag and required on every query. */
+    token: string;
+    /** The sources, and whether each has a reader: what the page shows, never a connection string. */
+    sources: {
+        name: string;
+        reader: boolean;
+    }[];
+    /** Runs one query through a source's reader; absent when no source has one. */
+    run?: (sql: string, source: string | undefined, limit: number | undefined) => Promise<QueryResult & {
+        source: string;
+    }>;
+}
+/** The address it listens on: this machine alone. */
+export declare const serveHost = "127.0.0.1";
+export declare function startServer(options: Served): Promise<{
+    url: string;
+    close: () => Promise<void>;
+}>;

package/dist/serve.js

@@ -0,0 +1,129 @@
+// dbtour serve: the rendered folder on this machine, and the one door the page has to the database. The page
+// runs a query by posting it here, and it runs as dbtour sql does: checked, through the source's reader, in a
+// transaction that is rolled back. Only this machine can reach it (127.0.0.1), and only this server's own
+// page can ask: the request must carry the session's token, which the page is given when served, and say it
+// comes from this server (Host and Origin), so another website, or a name rebound to this address, cannot.
+import { createServer } from 'node:http';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { extname, join, normalize, resolve, sep } from 'node:path';
+/** The address it listens on: this machine alone. */
+export const serveHost = '127.0.0.1';
+/** A query and its options are a few lines; anything past this is not one, and is refused unread. */
+const maxBodyBytes = 100 * 1024;
+const types = {
+    '.html': 'text/html; charset=utf-8',
+    '.md': 'text/markdown; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.css': 'text/css; charset=utf-8',
+    '.js': 'text/javascript; charset=utf-8',
+};
+export async function startServer(options) {
+    let origins = new Set();
+    let hosts = new Set();
+    const server = createServer((request, response) => {
+        handle(request, response, options, hosts, origins).catch((error) => send(response, 500, { error: error instanceof Error ? error.message : String(error) }));
+    });
+    await new Promise((done, fail) => {
+        server.once('error', fail);
+        server.listen(options.port, serveHost, () => done());
+    });
+    const port = server.address().port;
+    hosts = new Set([`${serveHost}:${port}`, `localhost:${port}`]);
+    origins = new Set([...hosts].map((h) => `http://${h}`));
+    return {
+        url: `http://${serveHost}:${port}`,
+        close: () => new Promise((done) => server.close(() => done())),
+    };
+}
+async function handle(request, response, options, hosts, origins) {
+    // Every route, not only the query: the page carries the token and the model, and the Markdown and
+    // schema.json are the schema, none of it for a site whose name was rebound to this address.
+    if (!hosts.has(request.headers.host ?? '')) {
+        return send(response, 403, { error: 'Open the page at the address dbtour serve printed: this server answers only to its own name.' });
+    }
+    const path = decodeURIComponent(new URL(request.url ?? '/', 'http://local').pathname);
+    if (path === '/api/query')
+        return query(request, response, options, hosts, origins);
+    if (request.method !== 'GET' && request.method !== 'HEAD')
+        return send(response, 405, { error: 'Only the page and its files are here: GET them.' });
+    const file = resolve(options.root, normalize(`.${path === '/' ? '/index.html' : path}`));
+    // Nothing outside the rendered folder, however the path is written.
+    if (file !== resolve(options.root) && !file.startsWith(resolve(options.root) + sep))
+        return send(response, 404, { error: 'Not here.' });
+    if (!existsSync(file) || !statSync(file).isFile())
+        return send(response, 404, { error: 'Not here.' });
+    let body = readFileSync(file);
+    if (file === join(resolve(options.root), 'index.html'))
+        body = withServe(body.toString('utf8'), options);
+    response.writeHead(200, { 'content-type': types[extname(file)] ?? 'application/octet-stream', 'cache-control': 'no-store' });
+    response.end(request.method === 'HEAD' ? undefined : body);
+}
+/** The page, told it is served: the token to send with a query, and which sources can run one. */
+function withServe(html, options) {
+    const value = JSON.stringify({ token: options.token, sources: options.sources }).replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;');
+    const meta = `<meta name="dbtour-serve" content="${value}">`;
+    return html.includes('</head>') ? html.replace('</head>', `${meta}</head>`) : meta + html;
+}
+async function query(request, response, options, hosts, origins) {
+    if (request.method !== 'POST')
+        return send(response, 405, { error: 'POST a query: {"sql": "SELECT …"}.' });
+    // The page's own requests name this server; anything else is another site, or a name rebound to this address.
+    const origin = request.headers.origin;
+    if (!hosts.has(request.headers.host ?? '') || (origin !== undefined && !origins.has(origin)) || request.headers['x-dbtour-token'] !== options.token) {
+        return send(response, 403, { error: 'Only the page dbtour serve gave out can run a query here: open it again from the address dbtour serve printed.' });
+    }
+    const text = await body(request);
+    if (text === undefined)
+        return send(response, 413, { error: 'That is more than a query: send one SELECT.' });
+    let asked;
+    try {
+        asked = JSON.parse(text);
+    }
+    catch {
+        asked = undefined;
+    }
+    if (typeof asked !== 'object' || asked === null || Array.isArray(asked) || typeof asked.sql !== 'string') {
+        return send(response, 400, { error: 'Send {"sql": "SELECT …"}, with source and limit if you want them.' });
+    }
+    const { sql, source, limit } = asked;
+    if (!options.run) {
+        return send(response, 422, { error: 'This page can be read, but no source has a reader, so a query cannot run here: add reader: ${DBTOUR_MSSQL_READER} to a source in dbtour.yaml and start dbtour serve again.' });
+    }
+    const started = Date.now();
+    try {
+        const result = await options.run(sql, typeof source === 'string' ? source : undefined, typeof limit === 'number' ? limit : undefined);
+        send(response, 200, { ...result, ms: Date.now() - started });
+    }
+    catch (error) {
+        send(response, 422, { error: error instanceof Error ? error.message : String(error) });
+    }
+}
+/**
+ * The request's body, or nothing when it is larger than any query. Past the limit the rest is read and
+ * dropped, not kept, so the connection stays open for the 413 that says why.
+ */
+function body(request) {
+    return new Promise((done, fail) => {
+        const chunks = [];
+        let size = 0;
+        request.on('data', (chunk) => {
+            size += chunk.length;
+            if (size <= maxBodyBytes)
+                chunks.push(chunk);
+        });
+        request.on('end', () => done(size > maxBodyBytes ? undefined : Buffer.concat(chunks).toString('utf8')));
+        request.on('error', fail);
+    });
+}
+/** JSON, with a date as ISO and bytes as hex, as dbtour sql --json writes them. */
+function send(response, status, value) {
+    const text = JSON.stringify(value, (_key, v) => {
+        if (v && typeof v === 'object' && v.type === 'Buffer')
+            return `0x${Buffer.from(v.data).toString('hex')}`;
+        return v;
+    });
+    response.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+    response.end(text);
+}

package/dist/sql.d.ts

@@ -0,0 +1,38 @@
+/** What a query returned: its columns in order, its rows as arrays, and whether the limit stopped it. */
+export interface QueryResult {
+    columns: string[];
+    rows: unknown[][];
+    /** Not every row came back: the limit stopped it, or the rows outgrew the byte budget (`reason`). */
+    truncated: boolean;
+    limit: number;
+    reason?: 'limit' | 'size';
+}
+export interface RunOptions {
+    limit: number;
+    timeoutMs: number;
+}
+/** Enough rows to see what a query returns without spending an agent's context on them. */
+export declare const defaultLimit = 100;
+/** The most one answer carries, however the limit is set: past it, a query wants narrowing, not paging. */
+export declare const maxLimit = 5000;
+/** How long a query may run before it is cancelled: a read that takes longer wants an index or a filter. */
+export declare const defaultTimeoutMs = 30000;
+/**
+ * The most a result holds in memory, however few its rows: a handful of varchar(max) cells can be larger than
+ * any agent can read, and an MCP server that buffered them would stop answering. Past it, the query wants
+ * fewer or narrower columns.
+ */
+export declare const maxResultBytes: number;
+export declare function clampLimit(limit: number | undefined): number;
+export type Checked = {
+    ok: true;
+    sql: string;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function checkQuery(sql: string): Checked;
+/** One cell as text for a table: NULL, dates as ISO, bytes as hex, one line, no stray column separator. */
+export declare function formatCell(value: unknown): string;
+/** The rows as a Markdown table, readable in a terminal and by an agent, and how many came back. */
+export declare function resultText(result: QueryResult): string;

package/dist/sql.js

@@ -0,0 +1,185 @@
+// Running a query someone (or an agent) wrote, safely enough to hand to an agent. The safety is the source's:
+// a read-only login of its own and a transaction that is always rolled back. This is the second line, read
+// before anything reaches the database: one SELECT or WITH, nothing that writes, runs code, ends the transaction
+// or reaches out of the database, and a row limit. It reads T-SQL as SQL Server does for strings, names and
+// comments, so a word inside 'text', [a name] or a comment is not taken for a statement, and it does not trust
+// semicolons, which T-SQL does not need between statements. It cannot see what a name points to (a synonym,
+// another database's table, a linked server): the reader login's permissions are that boundary. Pure, so it is
+// tested in Node.
+/** Enough rows to see what a query returns without spending an agent's context on them. */
+export const defaultLimit = 100;
+/** The most one answer carries, however the limit is set: past it, a query wants narrowing, not paging. */
+export const maxLimit = 5000;
+/** How long a query may run before it is cancelled: a read that takes longer wants an index or a filter. */
+export const defaultTimeoutMs = 30_000;
+/**
+ * The most a result holds in memory, however few its rows: a handful of varchar(max) cells can be larger than
+ * any agent can read, and an MCP server that buffered them would stop answering. Past it, the query wants
+ * fewer or narrower columns.
+ */
+export const maxResultBytes = 10 * 1024 * 1024;
+export function clampLimit(limit) {
+    if (limit === undefined || !Number.isFinite(limit))
+        return defaultLimit;
+    return Math.min(maxLimit, Math.max(1, Math.floor(limit)));
+}
+// Words that write, run code, change the schema or permissions, or reach out of the database. SELECT … INTO
+// writes a table, so INTO is among them. A column with one of these names is written [bracketed].
+const refusedWords = new Set([
+    'INSERT', 'UPDATE', 'DELETE', 'MERGE', 'TRUNCATE', 'DROP', 'ALTER', 'CREATE', 'GRANT', 'REVOKE', 'DENY',
+    'EXEC', 'EXECUTE', 'INTO', 'OPENROWSET', 'OPENDATASOURCE', 'OPENQUERY', 'BULK', 'BACKUP', 'RESTORE',
+    'SHUTDOWN', 'KILL', 'DBCC', 'WAITFOR', 'USE', 'GO', 'RECONFIGURE', 'DECLARE', 'SET',
+    // Transaction control: a COMMIT would keep what the rollback is there to undo.
+    'BEGIN', 'COMMIT', 'ROLLBACK', 'SAVE', 'TRAN', 'TRANSACTION',
+]);
+/** Joins two SELECTs into one query; any other second SELECT at the top is a second statement. */
+const setOperators = new Set(['UNION', 'ALL', 'EXCEPT', 'INTERSECT']);
+/**
+ * The code with every string, quoted name and comment blanked to spaces, so what is left is keywords and plain
+ * names; or what is left open. Positions are kept, so a semicolon found here is one in the query.
+ */
+function blank(sql) {
+    let code = '';
+    let i = 0;
+    const closing = (end, what) => {
+        // A quote is escaped by doubling it: 'it''s', [a]]b], "a""b".
+        for (let j = i + 1; j < sql.length; j++) {
+            if (sql[j] === end) {
+                if (sql[j + 1] === end) {
+                    j++;
+                    continue;
+                }
+                code += ' '.repeat(j + 1 - i);
+                i = j + 1;
+                return undefined;
+            }
+        }
+        return what;
+    };
+    while (i < sql.length) {
+        const c = sql[i];
+        if (c === "'" || c === '"' || c === '[') {
+            const open = closing(c === '[' ? ']' : c, c === "'" ? 'a string' : 'a quoted name');
+            if (open)
+                return { open };
+        }
+        else if (sql.startsWith('--', i)) {
+            // A carriage return ends the comment as a line feed does, as SQL Server reads it.
+            const rest = sql.slice(i).search(/[\r\n]/);
+            const stop = rest === -1 ? sql.length : i + rest;
+            code += ' '.repeat(stop - i);
+            i = stop;
+        }
+        else if (sql.startsWith('/*', i)) {
+            // Block comments nest in T-SQL.
+            let depth = 0;
+            let j = i;
+            while (j < sql.length) {
+                if (sql.startsWith('/*', j)) {
+                    depth++;
+                    j += 2;
+                }
+                else if (sql.startsWith('*/', j)) {
+                    depth--;
+                    j += 2;
+                    if (depth === 0)
+                        break;
+                }
+                else
+                    j++;
+            }
+            if (depth > 0)
+                return { open: 'a comment' };
+            code += ' '.repeat(j - i);
+            i = j;
+        }
+        else {
+            code += c;
+            i++;
+        }
+    }
+    return { code };
+}
+export function checkQuery(sql) {
+    const blanked = blank(sql);
+    if ('open' in blanked)
+        return { ok: false, reason: `The query leaves ${blanked.open} open: close it, then run it again.` };
+    const { code } = blanked;
+    if (code.trim() === '')
+        return { ok: false, reason: 'There is no query to run: write one SELECT, or a WITH followed by a SELECT.' };
+    // One trailing semicolon ends the statement; any other starts a second one.
+    const semicolons = [...code.matchAll(/;/g)].map((m) => m.index);
+    const last = semicolons[semicolons.length - 1];
+    if (semicolons.length > 1 || (last !== undefined && code.slice(last + 1).trim() !== '')) {
+        return { ok: false, reason: 'dbtour runs one statement at a time: send a single SELECT, without a second statement after a semicolon.' };
+    }
+    // Each word with how deep in parentheses it sits: a SELECT inside them is a subquery or a CTE's body.
+    const words = [];
+    let depth = 0;
+    for (const m of code.matchAll(/[A-Za-z_@#][\w@#$]*|[()]/g)) {
+        if (m[0] === '(')
+            depth++;
+        else if (m[0] === ')')
+            depth--;
+        else
+            words.push({ text: m[0], upper: m[0].toUpperCase(), depth });
+    }
+    if (words.length === 0)
+        return { ok: false, reason: 'There is no query to run: write one SELECT, or a WITH followed by a SELECT.' };
+    if (words[0].upper !== 'SELECT' && words[0].upper !== 'WITH') {
+        return { ok: false, reason: `The query starts with ${words[0].text}: dbtour runs only a SELECT, or a WITH followed by a SELECT.` };
+    }
+    const word = words.find((w) => refusedWords.has(w.upper));
+    if (word) {
+        const why = word.upper === 'INTO'
+            ? 'SELECT … INTO writes a table'
+            : ['BEGIN', 'COMMIT', 'ROLLBACK', 'SAVE', 'TRAN', 'TRANSACTION'].includes(word.upper)
+                ? `${word.upper} controls the transaction dbtour rolls back`
+                : `${word.upper} writes, runs code or reaches outside the database`;
+        return { ok: false, reason: `The query uses ${word.text}, and ${why}: dbtour runs reads only. If ${word.text} is a column or a table, write it as [${word.text}].` };
+    }
+    // NEXT VALUE FOR moves a sequence on, and a rollback does not move it back. FETCH NEXT, for paging, is a read.
+    const sequence = words.findIndex((w, i) => w.upper === 'NEXT' && words[i + 1]?.upper === 'VALUE' && words[i + 2]?.upper === 'FOR');
+    if (sequence !== -1)
+        return { ok: false, reason: 'The query uses NEXT VALUE FOR, which moves a sequence on even when the transaction is rolled back: dbtour runs reads only.' };
+    // Without semicolons, a second SELECT at the top is a second statement, unless a set operator joins the two.
+    const top = words.filter((w) => w.depth === 0);
+    const second = top.findIndex((w, i) => w.upper === 'SELECT' && i > 0 && top.slice(0, i).some((p) => p.upper === 'SELECT') && !setOperators.has(top[i - 1].upper));
+    if (second !== -1) {
+        return { ok: false, reason: 'The query has a second SELECT that UNION, EXCEPT or INTERSECT does not join to the first, which T-SQL runs as a second statement: dbtour runs one statement at a time.' };
+    }
+    return { ok: true, sql: (last === undefined ? sql : sql.slice(0, last)).trim() };
+}
+/** Bytes shown before a binary value is cut short: enough to tell two apart. */
+const bytesShown = 32;
+/** Characters of text shown in a cell: a long value is cut, with … after it. */
+const textShown = 200;
+/** One cell as text for a table: NULL, dates as ISO, bytes as hex, one line, no stray column separator. */
+export function formatCell(value) {
+    if (value === null || value === undefined)
+        return 'NULL';
+    if (value instanceof Date)
+        return value.toISOString();
+    if (value instanceof Uint8Array) {
+        const hex = Buffer.from(value.subarray(0, bytesShown)).toString('hex');
+        return `0x${hex}${value.length > bytesShown ? '…' : ''}`;
+    }
+    const text = typeof value === 'object' ? JSON.stringify(value) : String(value);
+    const line = text.replace(/\r?\n/g, '↵').replace(/\|/g, '\\|');
+    return line.length > textShown ? `${line.slice(0, textShown)}…` : line;
+}
+/** The rows as a Markdown table, readable in a terminal and by an agent, and how many came back. */
+export function resultText(result) {
+    const header = `| ${result.columns.map(formatCell).join(' | ')} |\n|${result.columns.map(() => '---').join('|')}|`;
+    const rows = result.rows.map((row) => `| ${row.map(formatCell).join(' | ')} |`);
+    const n = result.rows.length;
+    const counted = (count) => `${count} ${count === 1 ? 'row' : 'rows'}`;
+    const said = result.truncated && result.reason === 'size'
+        ? `The first ${counted(n)}: they came to more than ${maxResultBytes / (1024 * 1024)} MB. Select fewer or narrower columns.`
+        : result.truncated
+            ? `The first ${n} rows: the limit stopped it. Narrow the query, or raise the limit.`
+            : n === 0
+                ? 'No rows.'
+                : `${counted(n)}.`;
+    return `${[header, ...rows].join('\n')}\n\n${said}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dbtour",
-  "version": "0.7.1",
+  "version": "0.9.0",
   "description": "Tour your database and its API: searchable docs, relations and diagrams, generated from the schema, kept in the repo.",
   "type": "module",
   "license": "MIT",
@@ -32,6 +32,10 @@
     "./search": {
       "types": "./dist/search.d.ts",
       "default": "./dist/search.js"
+    },
+    "./sql": {
+      "types": "./dist/sql.d.ts",
+      "default": "./dist/sql.js"
     }
   },
   "files": [