@dbx-app/node-core 0.4.3

package/README.md

@@ -0,0 +1,33 @@
+# DBX Node Core
+
+Shared Node.js runtime utilities for DBX CLI and DBX MCP Server.
+
+This package reads DBX Desktop connection storage, redacts connection summaries, builds schema context, applies SQL safety rules, and executes supported direct database queries.
+
+## Supported Runtime
+
+Requires Node.js 22.13.0 or newer.
+
+## Direct Query Support
+
+Direct execution currently supports:
+
+- PostgreSQL and Redshift
+- MySQL-compatible databases, including MySQL, Doris, and StarRocks
+- SQLite
+
+Other DBX connection types can be routed through DBX Desktop bridge integrations used by the CLI and MCP server.
+
+## Public Modules
+
+```ts
+import {
+  createBackend,
+  loadConnections,
+  getDbxDiagnostics,
+  evaluateSqlSafety,
+  buildSchemaContext,
+} from "@dbx-app/node-core";
+```
+
+The package is intended as a shared implementation layer for official DBX Node packages. Applications should prefer `@dbx-app/cli` for terminal workflows and `@dbx-app/mcp-server` for MCP clients.

package/dist/backend.d.ts

@@ -0,0 +1,12 @@
+import type { ConnectionConfig } from "./connections.js";
+import type { ColumnInfo, QueryOptions, QueryResult, TableInfo } from "./database.js";
+export interface Backend {
+    loadConnections(): Promise<ConnectionConfig[]>;
+    findConnection(name: string): Promise<ConnectionConfig | undefined>;
+    addConnection(config: Omit<ConnectionConfig, "id">): Promise<ConnectionConfig>;
+    removeConnection(name: string): Promise<boolean>;
+    listTables(config: ConnectionConfig, schema?: string): Promise<TableInfo[]>;
+    describeTable(config: ConnectionConfig, table: string, schema?: string): Promise<ColumnInfo[]>;
+    executeQuery(config: ConnectionConfig, sql: string, options?: QueryOptions): Promise<QueryResult>;
+}
+export declare function createBackend(env?: NodeJS.ProcessEnv): Promise<Backend>;

package/dist/backend.js

@@ -0,0 +1,16 @@
+import { addConnection as desktopAddConnection, findConnection as desktopFindConnection, loadConnections as desktopLoadConnections, removeConnection as desktopRemoveConnection, } from "./connections.js";
+import { describeTable as desktopDescribeTable, executeQuery as desktopExecuteQuery, listTables as desktopListTables, } from "./database.js";
+export async function createBackend(env = process.env) {
+    if (env.DBX_WEB_URL) {
+        return await import("./web-backend.js");
+    }
+    return {
+        loadConnections: desktopLoadConnections,
+        findConnection: desktopFindConnection,
+        addConnection: desktopAddConnection,
+        removeConnection: desktopRemoveConnection,
+        listTables: desktopListTables,
+        describeTable: desktopDescribeTable,
+        executeQuery: desktopExecuteQuery,
+    };
+}

package/dist/bridge.d.ts

@@ -0,0 +1,9 @@
+export declare function getBridgeUrl(): Promise<string>;
+export declare function postBridge(path: string, body: Record<string, unknown>): Promise<{
+    ok: true;
+    text: string;
+} | {
+    ok: false;
+    text: string;
+}>;
+export declare function notifyReload(): Promise<void>;

package/dist/bridge.js

@@ -0,0 +1,23 @@
+import { readFile } from "node:fs/promises";
+import { bridgePortFilePath } from "./paths.js";
+export async function getBridgeUrl() {
+    const port = (await readFile(bridgePortFilePath(), "utf-8")).trim();
+    return `http://127.0.0.1:${port}`;
+}
+export async function postBridge(path, body) {
+    try {
+        const bridgeUrl = await getBridgeUrl();
+        const res = await fetch(`${bridgeUrl}${path}`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+        });
+        return { ok: res.ok, text: res.ok ? "" : await res.text() };
+    }
+    catch {
+        return { ok: false, text: "DBX is not running. Please start DBX first." };
+    }
+}
+export async function notifyReload() {
+    await postBridge("/reload-connections", {});
+}

package/dist/connections.d.ts

@@ -0,0 +1,43 @@
+export interface ConnectionConfig {
+    id: string;
+    name: string;
+    db_type: string;
+    driver_profile?: string;
+    host: string;
+    port: number;
+    username: string;
+    password: string;
+    database?: string;
+    url_params?: string;
+    ssh_enabled: boolean;
+    proxy_enabled?: boolean;
+    proxy_type?: "socks5" | "http";
+    proxy_host?: string;
+    proxy_port?: number;
+    proxy_username?: string;
+    proxy_password?: string;
+    ssl: boolean;
+}
+export interface ConnectionStoreOptions {
+    path?: string;
+}
+export interface ConnectionStoreDiagnostics {
+    dbPath: string;
+    dbPathExists: boolean;
+    connectionsTableExists: boolean;
+    connectionSecretsTableExists: boolean;
+    connectionRowCount: number;
+    loadConnectionsOk: boolean;
+    loadedConnectionCount: number;
+    loadConnectionsError?: string;
+}
+export declare class ConnectionStoreError extends Error {
+    readonly code = "CONNECTION_STORE_ERROR";
+    constructor(path: string, cause: unknown);
+}
+export declare function canonicalizeConnection(config: ConnectionConfig): ConnectionConfig;
+export declare function loadConnections(options?: ConnectionStoreOptions): Promise<ConnectionConfig[]>;
+export declare function inspectConnectionStore(options?: ConnectionStoreOptions): Promise<ConnectionStoreDiagnostics>;
+export declare function findConnection(name: string): Promise<ConnectionConfig | undefined>;
+export declare function addConnection(config: Omit<ConnectionConfig, "id">): Promise<ConnectionConfig>;
+export declare function removeConnection(name: string): Promise<boolean>;

package/dist/connections.js

@@ -0,0 +1,179 @@
+import { randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
+import Database from "better-sqlite3";
+import { dbPath as defaultDbPath } from "./paths.js";
+export class ConnectionStoreError extends Error {
+    code = "CONNECTION_STORE_ERROR";
+    constructor(path, cause) {
+        const message = cause instanceof Error ? cause.message : String(cause);
+        super(`Failed to load DBX connections from ${path}: ${message}`);
+        this.name = "ConnectionStoreError";
+    }
+}
+export function canonicalizeConnection(config) {
+    if (config.db_type === "mysql" && config.driver_profile?.toLowerCase() === "tdengine") {
+        return {
+            ...config,
+            db_type: "tdengine",
+            driver_profile: "tdengine",
+            port: config.port === 0 || config.port === 6030 ? 6041 : config.port,
+        };
+    }
+    if (config.db_type === "tdengine") {
+        return {
+            ...config,
+            driver_profile: "tdengine",
+            port: config.port || 6041,
+        };
+    }
+    return config;
+}
+function openDb(readonly = false, path = defaultDbPath()) {
+    return new Database(path, { readonly });
+}
+function getSecret(db, connectionId, key) {
+    const row = db
+        .prepare("SELECT secret FROM connection_secrets WHERE connection_id = ? AND key = ?")
+        .get(connectionId, key);
+    return row?.secret ?? "";
+}
+export async function loadConnections(options = {}) {
+    const path = options.path ?? defaultDbPath();
+    if (!existsSync(path))
+        return [];
+    let db;
+    try {
+        db = openDb(true, path);
+        const rows = db.prepare("SELECT id, config_json FROM connections").all();
+        const configs = [];
+        for (const row of rows) {
+            const config = canonicalizeConnection(JSON.parse(row.config_json));
+            config.id = row.id;
+            if (!config.password)
+                config.password = getSecret(db, row.id, "password");
+            if (!config.proxy_password)
+                config.proxy_password = getSecret(db, row.id, "proxy_password");
+            configs.push(config);
+        }
+        return configs;
+    }
+    catch (error) {
+        throw new ConnectionStoreError(path, error);
+    }
+    finally {
+        db?.close();
+    }
+}
+export async function inspectConnectionStore(options = {}) {
+    const path = options.path ?? defaultDbPath();
+    const diagnostics = {
+        dbPath: path,
+        dbPathExists: existsSync(path),
+        connectionsTableExists: false,
+        connectionSecretsTableExists: false,
+        connectionRowCount: 0,
+        loadConnectionsOk: true,
+        loadedConnectionCount: 0,
+    };
+    if (!diagnostics.dbPathExists)
+        return diagnostics;
+    let db;
+    try {
+        db = openDb(true, path);
+        diagnostics.connectionsTableExists = tableExists(db, "connections");
+        diagnostics.connectionSecretsTableExists = tableExists(db, "connection_secrets");
+        if (diagnostics.connectionsTableExists) {
+            const row = db.prepare("SELECT COUNT(*) AS count FROM connections").get();
+            diagnostics.connectionRowCount = row.count;
+        }
+    }
+    catch (error) {
+        diagnostics.loadConnectionsOk = false;
+        diagnostics.loadConnectionsError = error instanceof Error ? error.message : String(error);
+        return diagnostics;
+    }
+    finally {
+        db?.close();
+    }
+    try {
+        const connections = await loadConnections({ path });
+        diagnostics.loadedConnectionCount = connections.length;
+    }
+    catch (error) {
+        diagnostics.loadConnectionsOk = false;
+        diagnostics.loadConnectionsError = error instanceof Error ? error.message : String(error);
+    }
+    return diagnostics;
+}
+function tableExists(db, name) {
+    const row = db
+        .prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?")
+        .get(name);
+    return !!row;
+}
+export async function findConnection(name) {
+    const connections = await loadConnections();
+    return connections.find((c) => c.name.toLowerCase() === name.toLowerCase());
+}
+export async function addConnection(config) {
+    const id = randomUUID();
+    const db = openDb();
+    const normalized = canonicalizeConnection({ ...config, id });
+    const full = {
+        id,
+        name: normalized.name,
+        db_type: normalized.db_type,
+        driver_profile: normalized.driver_profile ?? normalized.db_type,
+        driver_label: null,
+        url_params: normalized.url_params ?? "",
+        host: normalized.host,
+        port: normalized.port,
+        username: normalized.username,
+        password: "",
+        database: normalized.database ?? null,
+        color: null,
+        ssh_enabled: normalized.ssh_enabled ?? false,
+        ssh_host: "",
+        ssh_port: 22,
+        ssh_user: "",
+        ssh_password: "",
+        ssh_key_path: "",
+        ssh_key_passphrase: "",
+        ssh_expose_lan: false,
+        proxy_enabled: normalized.proxy_enabled ?? false,
+        proxy_type: normalized.proxy_type ?? "socks5",
+        proxy_host: normalized.proxy_host ?? "",
+        proxy_port: normalized.proxy_port ?? 1080,
+        proxy_username: normalized.proxy_username ?? "",
+        proxy_password: "",
+        ssl: normalized.ssl ?? false,
+        sysdba: false,
+        connection_string: null,
+    };
+    const configJson = JSON.stringify(full);
+    const insert = db.transaction(() => {
+        db.prepare("INSERT INTO connections (id, config_json) VALUES (?, ?)").run(id, configJson);
+        if (normalized.password) {
+            db.prepare("INSERT INTO connection_secrets (connection_id, key, secret) VALUES (?, ?, ?)").run(id, "password", normalized.password);
+        }
+        if (normalized.proxy_password) {
+            db.prepare("INSERT INTO connection_secrets (connection_id, key, secret) VALUES (?, ?, ?)").run(id, "proxy_password", normalized.proxy_password);
+        }
+    });
+    insert();
+    db.close();
+    return normalized;
+}
+export async function removeConnection(name) {
+    const connection = await findConnection(name);
+    if (!connection)
+        return false;
+    const db = openDb();
+    const remove = db.transaction(() => {
+        db.prepare("DELETE FROM connections WHERE id = ?").run(connection.id);
+        db.prepare("DELETE FROM connection_secrets WHERE connection_id = ?").run(connection.id);
+    });
+    remove();
+    db.close();
+    return true;
+}

package/dist/database.d.ts

@@ -0,0 +1,25 @@
+import type { ConnectionConfig } from "./connections.js";
+export interface TableInfo {
+    name: string;
+    type: string;
+}
+export interface ColumnInfo {
+    name: string;
+    data_type: string;
+    is_nullable: boolean;
+    column_default: string | null;
+    is_primary_key: boolean;
+    comment: string | null;
+}
+export interface QueryResult {
+    columns: string[];
+    rows: Record<string, unknown>[];
+    row_count: number;
+}
+export interface QueryOptions {
+    maxRows?: number;
+    timeoutMs?: number;
+}
+export declare function executeQuery(config: ConnectionConfig, sql: string, options?: QueryOptions): Promise<QueryResult>;
+export declare function listTables(config: ConnectionConfig, schema?: string): Promise<TableInfo[]>;
+export declare function describeTable(config: ConnectionConfig, table: string, schema?: string): Promise<ColumnInfo[]>;