@dbx-app/node-core 0.4.3

package/dist/database.js

@@ -0,0 +1,415 @@
+import { createServer, connect as netConnect } from "node:net";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir, platform } from "node:os";
+import Database from "better-sqlite3";
+import { sqlSafetyFromEnv } from "./sql-safety.js";
+const MAX_ROWS = 100;
+const IDLE_TIMEOUT_MS = 5 * 60 * 1000;
+const QUERY_TIMEOUT_MS = 30_000;
+const pools = new Map();
+const proxyTunnels = new Map();
+function poolKey(config) {
+    return `${config.id}:${config.database || ""}`;
+}
+function evictPool(key, entry) {
+    pools.delete(key);
+    if (entry.type === "pg") {
+        entry.pool.end().catch(() => { });
+    }
+    else {
+        entry.pool.end().catch(() => { });
+    }
+}
+function resetIdleTimer(key, entry) {
+    clearTimeout(entry.timer);
+    entry.timer = setTimeout(() => evictPool(key, entry), IDLE_TIMEOUT_MS);
+}
+async function getPgPool(config) {
+    const key = poolKey(config);
+    const existing = pools.get(key);
+    if (existing?.type === "pg") {
+        resetIdleTimer(key, existing);
+        return existing.pool;
+    }
+    const pg = await import("pg");
+    const endpoint = await connectionEndpoint(config);
+    const pool = new pg.default.Pool({
+        connectionString: buildConnectionUrl(config, endpoint),
+        max: 3,
+        idleTimeoutMillis: 30_000,
+        connectionTimeoutMillis: 10_000,
+    });
+    pool.on("error", () => { });
+    const entry = { type: "pg", pool, timer: setTimeout(() => { }, 0) };
+    pools.set(key, entry);
+    resetIdleTimer(key, entry);
+    return pool;
+}
+async function getMysqlPool(config) {
+    const key = poolKey(config);
+    const existing = pools.get(key);
+    if (existing?.type === "mysql") {
+        resetIdleTimer(key, existing);
+        return existing.pool;
+    }
+    const mysql = await import("mysql2/promise");
+    const endpoint = await connectionEndpoint(config);
+    const pool = mysql.default.createPool({
+        uri: buildConnectionUrl(config, endpoint),
+        connectionLimit: 3,
+        idleTimeout: 30_000,
+        connectTimeout: 10_000,
+    });
+    const entry = { type: "mysql", pool, timer: setTimeout(() => { }, 0) };
+    pools.set(key, entry);
+    resetIdleTimer(key, entry);
+    return pool;
+}
+async function connectionEndpoint(config) {
+    if (!config.proxy_enabled || !config.proxy_host)
+        return { host: config.host, port: config.port };
+    const existing = proxyTunnels.get(config.id);
+    if (existing)
+        return { host: "127.0.0.1", port: existing.port };
+    const server = createServer((inbound) => {
+        connectViaProxy(config)
+            .then((outbound) => {
+            inbound.pipe(outbound);
+            outbound.pipe(inbound);
+        })
+            .catch(() => inbound.destroy());
+    });
+    const port = await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            const address = server.address();
+            if (address && typeof address === "object")
+                resolve(address.port);
+            else
+                reject(new Error("Failed to bind proxy tunnel"));
+        });
+    });
+    proxyTunnels.set(config.id, { server, port });
+    return { host: "127.0.0.1", port };
+}
+function buildConnectionUrl(config, endpoint) {
+    const db = config.database || "";
+    const params = config.url_params || "";
+    const suffix = params ? `?${params}` : "";
+    if (isMysqlType(config.db_type)) {
+        return `mysql://${encodeURIComponent(config.username)}:${encodeURIComponent(config.password)}@${endpoint.host}:${endpoint.port}/${db}${suffix}`;
+    }
+    return `postgres://${encodeURIComponent(config.username)}:${encodeURIComponent(config.password)}@${endpoint.host}:${endpoint.port}/${db}${suffix}`;
+}
+function connectViaProxy(config) {
+    return new Promise((resolve, reject) => {
+        const socket = netConnect(config.proxy_port || 1080, config.proxy_host || "127.0.0.1");
+        socket.once("error", reject);
+        socket.once("connect", () => {
+            if ((config.proxy_type || "socks5") === "http") {
+                httpConnect(socket, config, resolve, reject);
+            }
+            else {
+                socks5Connect(socket, config, resolve, reject);
+            }
+        });
+    });
+}
+function httpConnect(socket, config, resolve, reject) {
+    const target = `${config.host}:${config.port}`;
+    const lines = [`CONNECT ${target} HTTP/1.1`, `Host: ${target}`];
+    if (config.proxy_username || config.proxy_password) {
+        const token = Buffer.from(`${config.proxy_username || ""}:${config.proxy_password || ""}`).toString("base64");
+        lines.push(`Proxy-Authorization: Basic ${token}`);
+    }
+    socket.write(`${lines.join("\r\n")}\r\n\r\n`);
+    let buffer = Buffer.alloc(0);
+    socket.on("data", function onData(chunk) {
+        buffer = Buffer.concat([buffer, chunk]);
+        const end = buffer.indexOf("\r\n\r\n");
+        if (end < 0)
+            return;
+        socket.off("data", onData);
+        const head = buffer.subarray(0, end).toString("utf8");
+        if (!/^HTTP\/1\.[01] 200\b/.test(head)) {
+            reject(new Error(`HTTP proxy CONNECT failed: ${head.split("\r\n")[0] || "invalid response"}`));
+            socket.destroy();
+            return;
+        }
+        const rest = buffer.subarray(end + 4);
+        if (rest.length)
+            socket.unshift(rest);
+        resolve(socket);
+    });
+}
+function socks5Connect(socket, config, resolve, reject) {
+    const wantsAuth = !!(config.proxy_username || config.proxy_password);
+    socket.write(Buffer.from(wantsAuth ? [0x05, 0x02, 0x00, 0x02] : [0x05, 0x01, 0x00]));
+    socket.once("data", (method) => {
+        if (method.length < 2 || method[0] !== 0x05) {
+            reject(new Error("Invalid SOCKS greeting"));
+            socket.destroy();
+            return;
+        }
+        if (method[1] === 0x02) {
+            const user = Buffer.from(config.proxy_username || "");
+            const pass = Buffer.from(config.proxy_password || "");
+            socket.write(Buffer.concat([Buffer.from([0x01, user.length]), user, Buffer.from([pass.length]), pass]));
+            socket.once("data", (auth) => {
+                if (auth.length < 2 || auth[1] !== 0x00) {
+                    reject(new Error("SOCKS proxy authentication failed"));
+                    socket.destroy();
+                    return;
+                }
+                sendSocksConnect(socket, config, resolve, reject);
+            });
+        }
+        else if (method[1] === 0x00) {
+            sendSocksConnect(socket, config, resolve, reject);
+        }
+        else {
+            reject(new Error("SOCKS proxy rejected authentication methods"));
+            socket.destroy();
+        }
+    });
+}
+function sendSocksConnect(socket, config, resolve, reject) {
+    const host = Buffer.from(config.host);
+    socket.write(Buffer.concat([Buffer.from([0x05, 0x01, 0x00, 0x03, host.length]), host, portBytes(config.port)]));
+    socket.once("data", (res) => {
+        if (res.length < 4 || res[0] !== 0x05 || res[1] !== 0x00) {
+            reject(new Error(`SOCKS proxy connect failed with code ${res[1] ?? "unknown"}`));
+            socket.destroy();
+            return;
+        }
+        resolve(socket);
+    });
+}
+function portBytes(port) {
+    const buf = Buffer.alloc(2);
+    buf.writeUInt16BE(port);
+    return buf;
+}
+function isMysqlType(dbType) {
+    return dbType === "mysql" || dbType === "doris" || dbType === "starrocks";
+}
+function isDirectType(dbType) {
+    switch (dbType) {
+        case "postgres":
+        case "redshift":
+        case "mysql":
+        case "doris":
+        case "starrocks":
+        case "sqlite":
+            return true;
+        default:
+            return false;
+    }
+}
+function bridgeAppDataDir() {
+    const home = homedir();
+    switch (platform()) {
+        case "darwin":
+            return join(home, "Library", "Application Support", "com.dbx.app");
+        case "win32":
+            return join(process.env.APPDATA || join(home, "AppData", "Roaming"), "com.dbx.app");
+        default:
+            return join(home, ".config", "com.dbx.app");
+    }
+}
+async function bridgeDataRequest(path, body) {
+    let bridgeUrl;
+    try {
+        const portFile = join(bridgeAppDataDir(), "mcp-bridge-port");
+        const port = (await readFile(portFile, "utf-8")).trim();
+        bridgeUrl = `http://127.0.0.1:${port}`;
+    }
+    catch {
+        throw new Error("DBX desktop app is not running. This database type requires DBX to be running for query execution.");
+    }
+    const res = await fetch(`${bridgeUrl}${path}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+        const errBody = await res.text().catch(() => "");
+        let errorMsg;
+        try {
+            const parsed = JSON.parse(errBody);
+            errorMsg = parsed.error || errBody;
+        }
+        catch {
+            errorMsg = errBody;
+        }
+        throw new Error(errorMsg || `Bridge request failed: ${res.status}`);
+    }
+    return res.json();
+}
+function resolveMaxRows(options) {
+    return options?.maxRows ?? MAX_ROWS;
+}
+function resolveTimeoutMs(options) {
+    return options?.timeoutMs ?? QUERY_TIMEOUT_MS;
+}
+function convertBridgeQueryResult(result, options) {
+    const rows = result.rows.slice(0, resolveMaxRows(options)).map((row) => {
+        const obj = {};
+        result.columns.forEach((col, i) => { obj[col] = row[i]; });
+        return obj;
+    });
+    return { columns: result.columns, rows, row_count: rows.length };
+}
+function withTimeout(promise, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(`Query timed out after ${ms}ms`)), ms);
+        promise.then(resolve, reject).finally(() => clearTimeout(timer));
+    });
+}
+async function queryWithRetry(config, fn, options) {
+    const timeoutMs = resolveTimeoutMs(options);
+    try {
+        return await withTimeout(fn(), timeoutMs);
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        const retriable = /terminating connection|Connection lost|ECONNRESET|EPIPE|connection refused/i.test(msg);
+        if (retriable) {
+            const key = poolKey(config);
+            const entry = pools.get(key);
+            if (entry)
+                evictPool(key, entry);
+            return withTimeout(fn(), timeoutMs);
+        }
+        throw e;
+    }
+}
+async function pgQuery(config, sql, params, options) {
+    return queryWithRetry(config, async () => {
+        const pool = await getPgPool(config);
+        const result = await pool.query(sql, params);
+        const rows = (result.rows || []).slice(0, resolveMaxRows(options));
+        return { columns: result.fields?.map((f) => f.name) ?? [], rows, row_count: rows.length };
+    }, options);
+}
+async function mysqlQuery(config, sql, params, options) {
+    return queryWithRetry(config, async () => {
+        const pool = await getMysqlPool(config);
+        const [results, fields] = await pool.query(sql, params);
+        const rows = (Array.isArray(results) ? results : []).slice(0, resolveMaxRows(options));
+        return { columns: fields?.map((f) => f.name) ?? [], rows, row_count: rows.length };
+    }, options);
+}
+async function query(config, sql, params, options) {
+    if (config.db_type === "sqlite")
+        return sqliteQuery(config, sql, options);
+    if (isMysqlType(config.db_type))
+        return mysqlQuery(config, sql, params, options);
+    return pgQuery(config, sql, params, options);
+}
+function sqlitePath(config) {
+    return expandTilde(config.host || config.database || "");
+}
+function expandTilde(path) {
+    if (path === "~")
+        return homedir();
+    if (path.startsWith("~/"))
+        return join(homedir(), path.slice(2));
+    return path;
+}
+function quoteSqliteIdentifier(identifier) {
+    return `"${identifier.replace(/"/g, '""')}"`;
+}
+function sqliteQuery(config, sql, options) {
+    const db = new Database(sqlitePath(config), { readonly: !sqlSafetyFromEnv().allowWrites });
+    try {
+        const stmt = db.prepare(sql);
+        if (stmt.reader) {
+            const rows = stmt.all().slice(0, resolveMaxRows(options));
+            return { columns: stmt.columns().map((column) => column.name), rows, row_count: rows.length };
+        }
+        const result = stmt.run();
+        return { columns: [], rows: [], row_count: result.changes };
+    }
+    finally {
+        db.close();
+    }
+}
+export async function executeQuery(config, sql, options) {
+    if (isDirectType(config.db_type)) {
+        return query(config, sql, undefined, options);
+    }
+    const result = await withTimeout(bridgeDataRequest("/data/execute-query", {
+        connection_name: config.name,
+        database: config.database || "",
+        sql,
+    }), resolveTimeoutMs(options));
+    return convertBridgeQueryResult(result, options);
+}
+export async function listTables(config, schema) {
+    if (config.db_type === "sqlite") {
+        const result = await query(config, `SELECT name, type FROM sqlite_master WHERE type IN ('table', 'view') AND name NOT LIKE 'sqlite_%' ORDER BY name`);
+        return result.rows.map((r) => ({ name: String(r.name || ""), type: String(r.type || "table") }));
+    }
+    if (!isDirectType(config.db_type)) {
+        const tables = await bridgeDataRequest("/data/list-tables", {
+            connection_name: config.name,
+            database: config.database || "",
+            schema: schema || "",
+        });
+        return tables.map((t) => ({ name: t.name, type: t.table_type || "TABLE" }));
+    }
+    let result;
+    if (isMysqlType(config.db_type)) {
+        result = await query(config, `SELECT TABLE_NAME AS name, TABLE_TYPE AS type FROM information_schema.TABLES WHERE TABLE_SCHEMA = DATABASE() ORDER BY TABLE_NAME`);
+    }
+    else {
+        result = await query(config, `SELECT table_name AS name, table_type AS type FROM information_schema.tables WHERE table_schema = $1 ORDER BY table_name`, [schema || "public"]);
+    }
+    return result.rows.map((r) => ({ name: String(r.name || r.NAME), type: String(r.type || r.TYPE || "TABLE") }));
+}
+export async function describeTable(config, table, schema) {
+    if (config.db_type === "sqlite") {
+        const result = await query(config, `PRAGMA table_info(${quoteSqliteIdentifier(table)})`);
+        return result.rows.map((r) => ({
+            name: String(r.name || ""),
+            data_type: String(r.type || ""),
+            is_nullable: Number(r.notnull || 0) === 0,
+            column_default: r.dflt_value != null ? String(r.dflt_value) : null,
+            is_primary_key: Number(r.pk || 0) > 0,
+            comment: null,
+        }));
+    }
+    if (!isDirectType(config.db_type)) {
+        const columns = await bridgeDataRequest("/data/describe-table", {
+            connection_name: config.name,
+            database: config.database || "",
+            schema: schema || "",
+            table,
+        });
+        return columns.map((c) => ({
+            name: c.name,
+            data_type: c.data_type,
+            is_nullable: c.is_nullable,
+            column_default: c.column_default,
+            is_primary_key: c.is_primary_key,
+            comment: c.comment,
+        }));
+    }
+    let result;
+    if (isMysqlType(config.db_type)) {
+        result = await query(config, `SELECT c.COLUMN_NAME AS name, c.DATA_TYPE AS data_type, c.IS_NULLABLE = 'YES' AS is_nullable, c.COLUMN_DEFAULT AS column_default, c.COLUMN_KEY = 'PRI' AS is_primary_key, c.COLUMN_COMMENT AS comment FROM information_schema.COLUMNS c WHERE c.TABLE_SCHEMA = DATABASE() AND c.TABLE_NAME = ? ORDER BY c.ORDINAL_POSITION`, [table]);
+    }
+    else {
+        result = await query(config, `SELECT c.column_name AS name, c.data_type, c.is_nullable = 'YES' AS is_nullable, c.column_default, CASE WHEN tc.constraint_type = 'PRIMARY KEY' THEN true ELSE false END AS is_primary_key, col_description(cls.oid, c.ordinal_position) AS comment FROM information_schema.columns c LEFT JOIN information_schema.key_column_usage kcu ON kcu.table_schema = c.table_schema AND kcu.table_name = c.table_name AND kcu.column_name = c.column_name LEFT JOIN information_schema.table_constraints tc ON tc.constraint_name = kcu.constraint_name AND tc.table_schema = kcu.table_schema AND tc.constraint_type = 'PRIMARY KEY' LEFT JOIN pg_class cls ON cls.relname = c.table_name AND cls.relnamespace = (SELECT oid FROM pg_namespace WHERE nspname = c.table_schema) WHERE c.table_schema = $1 AND c.table_name = $2 ORDER BY c.ordinal_position`, [schema || "public", table]);
+    }
+    return result.rows.map((r) => ({
+        name: String(r.name || ""),
+        data_type: String(r.data_type || ""),
+        is_nullable: Boolean(r.is_nullable),
+        column_default: r.column_default != null ? String(r.column_default) : null,
+        is_primary_key: Boolean(r.is_primary_key),
+        comment: r.comment != null ? String(r.comment) : null,
+    }));
+}

package/dist/diagnostics.d.ts

@@ -0,0 +1,20 @@
+export declare const DIRECT_QUERY_TYPES: readonly ["postgres", "redshift", "mysql", "doris", "starrocks", "sqlite"];
+export declare const BRIDGE_REQUIRED_TYPES: readonly ["redis", "mongodb", "duckdb", "clickhouse", "sqlserver", "oracle", "elasticsearch", "dameng", "kingbase", "highgo", "vastbase", "goldendb", "gaussdb", "tdengine", "h2", "snowflake", "trino", "hive", "db2", "informix", "neo4j", "cassandra", "bigquery", "kylin", "sundb", "jdbc", "access"];
+export interface DbxDiagnostics {
+    appDataDir: string;
+    dbPath: string;
+    dbPathExists: boolean;
+    connectionsTableExists: boolean;
+    connectionSecretsTableExists?: boolean;
+    connectionRowCount: number;
+    loadConnectionsOk: boolean;
+    loadedConnectionCount: number;
+    loadConnectionsError?: string;
+    loadConnectionsHint?: string;
+    bridgePortFile: string;
+    bridgePortFileExists: boolean;
+    bridgeUrl?: string;
+    directQueryTypes: string[];
+    bridgeRequiredTypes: string[];
+}
+export declare function getDbxDiagnostics(): Promise<DbxDiagnostics>;

package/dist/diagnostics.js

@@ -0,0 +1,79 @@
+import { access, readFile } from "node:fs/promises";
+import { bridgePortFilePath, dbPath, appDataDir } from "./paths.js";
+import { inspectConnectionStore } from "./connections.js";
+export const DIRECT_QUERY_TYPES = ["postgres", "redshift", "mysql", "doris", "starrocks", "sqlite"];
+export const BRIDGE_REQUIRED_TYPES = [
+    "redis",
+    "mongodb",
+    "duckdb",
+    "clickhouse",
+    "sqlserver",
+    "oracle",
+    "elasticsearch",
+    "dameng",
+    "kingbase",
+    "highgo",
+    "vastbase",
+    "goldendb",
+    "gaussdb",
+    "tdengine",
+    "h2",
+    "snowflake",
+    "trino",
+    "hive",
+    "db2",
+    "informix",
+    "neo4j",
+    "cassandra",
+    "bigquery",
+    "kylin",
+    "sundb",
+    "jdbc",
+    "access",
+];
+export async function getDbxDiagnostics() {
+    const portFile = bridgePortFilePath();
+    const bridgePortFileExists = await exists(portFile);
+    let bridgeUrl;
+    if (bridgePortFileExists) {
+        const port = (await readFile(portFile, "utf-8")).trim();
+        if (port)
+            bridgeUrl = `http://127.0.0.1:${port}`;
+    }
+    const path = dbPath();
+    const connectionStore = await inspectConnectionStore({ path });
+    return {
+        appDataDir: appDataDir(),
+        dbPath: path,
+        dbPathExists: connectionStore.dbPathExists,
+        connectionsTableExists: connectionStore.connectionsTableExists,
+        connectionSecretsTableExists: connectionStore.connectionSecretsTableExists,
+        connectionRowCount: connectionStore.connectionRowCount,
+        loadConnectionsOk: connectionStore.loadConnectionsOk,
+        loadedConnectionCount: connectionStore.loadedConnectionCount,
+        loadConnectionsError: connectionStore.loadConnectionsError,
+        loadConnectionsHint: connectionStore.loadConnectionsError
+            ? connectionStoreHint(connectionStore.loadConnectionsError)
+            : undefined,
+        bridgePortFile: portFile,
+        bridgePortFileExists,
+        bridgeUrl,
+        directQueryTypes: [...DIRECT_QUERY_TYPES],
+        bridgeRequiredTypes: [...BRIDGE_REQUIRED_TYPES],
+    };
+}
+function connectionStoreHint(message) {
+    if (/NODE_MODULE_VERSION|compiled against a different Node\.js version/i.test(message)) {
+        return "Rebuild DBX CLI native dependencies with your active Node.js: pnpm rebuild better-sqlite3 keytar --pending, or reinstall the package with the same Node.js version you use to run dbx.";
+    }
+    return undefined;
+}
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./backend.js";
+export * from "./bridge.js";
+export * from "./connections.js";
+export * from "./database.js";
+export * from "./diagnostics.js";
+export * from "./paths.js";
+export * from "./schema-context.js";
+export * from "./sql-safety.js";

package/dist/index.js

@@ -0,0 +1,8 @@
+export * from "./backend.js";
+export * from "./bridge.js";
+export * from "./connections.js";
+export * from "./database.js";
+export * from "./diagnostics.js";
+export * from "./paths.js";
+export * from "./schema-context.js";
+export * from "./sql-safety.js";

package/dist/paths.d.ts

@@ -0,0 +1,3 @@
+export declare function appDataDir(): string;
+export declare function dbPath(): string;
+export declare function bridgePortFilePath(): string;

package/dist/paths.js

@@ -0,0 +1,19 @@
+import { homedir, platform } from "node:os";
+import { join } from "node:path";
+export function appDataDir() {
+    const home = homedir();
+    switch (platform()) {
+        case "darwin":
+            return join(home, "Library", "Application Support", "com.dbx.app");
+        case "win32":
+            return join(process.env.APPDATA || join(home, "AppData", "Roaming"), "com.dbx.app");
+        default:
+            return join(home, ".config", "com.dbx.app");
+    }
+}
+export function dbPath() {
+    return join(appDataDir(), "dbx.db");
+}
+export function bridgePortFilePath() {
+    return join(appDataDir(), "mcp-bridge-port");
+}

package/dist/schema-context.d.ts

@@ -0,0 +1,25 @@
+import type { ConnectionConfig } from "./connections.js";
+import type { ColumnInfo, TableInfo } from "./database.js";
+export interface SchemaContextBackend {
+    listTables(config: ConnectionConfig, schema?: string): Promise<TableInfo[]>;
+    describeTable(config: ConnectionConfig, table: string, schema?: string): Promise<ColumnInfo[]>;
+}
+export interface SchemaContextOptions {
+    schema?: string;
+    tables?: string[];
+    maxTables?: number;
+}
+export interface SchemaContextTable {
+    name: string;
+    type: string;
+    columns: ColumnInfo[];
+}
+export interface SchemaContext {
+    connection: string;
+    database: string;
+    schema: string;
+    truncated: boolean;
+    tables: SchemaContextTable[];
+}
+export declare function buildSchemaContext(backend: SchemaContextBackend, config: ConnectionConfig, options?: SchemaContextOptions): Promise<SchemaContext>;
+export declare function formatSchemaContext(context: SchemaContext): string;

package/dist/schema-context.js

@@ -0,0 +1,43 @@
+const DEFAULT_MAX_TABLES = 8;
+export async function buildSchemaContext(backend, config, options = {}) {
+    const maxTables = Math.max(1, Math.min(options.maxTables ?? DEFAULT_MAX_TABLES, 20));
+    const availableTables = await backend.listTables(config, options.schema);
+    const requested = new Set((options.tables ?? []).map((table) => table.toLowerCase()));
+    const selected = requested.size
+        ? availableTables.filter((table) => requested.has(table.name.toLowerCase()))
+        : availableTables.slice(0, maxTables);
+    const limited = selected.slice(0, maxTables);
+    const tables = await Promise.all(limited.map(async (table) => ({
+        name: table.name,
+        type: table.type,
+        columns: await backend.describeTable(config, table.name, options.schema),
+    })));
+    return {
+        connection: config.name,
+        database: config.database || "",
+        schema: options.schema || "",
+        truncated: selected.length > limited.length || (!requested.size && availableTables.length > limited.length),
+        tables,
+    };
+}
+export function formatSchemaContext(context) {
+    const header = [
+        `Connection: ${context.connection}`,
+        context.database ? `Database: ${context.database}` : "",
+        context.schema ? `Schema: ${context.schema}` : "",
+    ].filter(Boolean);
+    const sections = context.tables.map((table) => {
+        const lines = table.columns.map((column) => {
+            const parts = [
+                column.name,
+                column.data_type,
+                column.is_nullable ? "NULL" : "NOT NULL",
+                column.is_primary_key ? "PK" : "",
+            ].filter(Boolean);
+            return `- ${parts.join(" ")}${column.comment ? ` -- ${column.comment}` : ""}`;
+        });
+        return [`## ${table.name}`, `Type: ${table.type}`, ...lines].join("\n");
+    });
+    const suffix = context.truncated ? "\n\nNote: table list was truncated; request specific table names for more context." : "";
+    return `${header.join("\n")}\n\n${sections.join("\n\n")}${suffix}`;
+}

package/dist/sql-safety.d.ts

@@ -0,0 +1,10 @@
+export interface SqlSafetyOptions {
+    allowWrites?: boolean;
+    allowDangerous?: boolean;
+}
+export interface SqlSafetyDecision {
+    allowed: boolean;
+    reason?: string;
+}
+export declare function evaluateSqlSafety(sql: string, options?: SqlSafetyOptions): SqlSafetyDecision;
+export declare function sqlSafetyFromEnv(env?: NodeJS.ProcessEnv): SqlSafetyOptions;