taurusdb-core 0.1.0

package/dist/utils/formatter.d.ts

@@ -0,0 +1,70 @@
+export type StatementType = "select" | "show" | "explain" | "describe" | "insert" | "update" | "delete" | "alter" | "drop" | "create" | "grant" | "revoke" | "unknown";
+export declare const ErrorCode: {
+    readonly DATASOURCE_NOT_FOUND: "DATASOURCE_NOT_FOUND";
+    readonly CREDENTIAL_MISSING: "CREDENTIAL_MISSING";
+    readonly BLOCKED_SQL: "BLOCKED_SQL";
+    readonly CONFIRMATION_REQUIRED: "CONFIRMATION_REQUIRED";
+    readonly CONFIRMATION_INVALID: "CONFIRMATION_INVALID";
+    readonly INVALID_INPUT: "INVALID_INPUT";
+    readonly SQL_SYNTAX_ERROR: "SQL_SYNTAX_ERROR";
+    readonly QUERY_TIMEOUT: "QUERY_TIMEOUT";
+    readonly QUERY_CANCELLED: "QUERY_CANCELLED";
+    readonly CONNECTION_FAILED: "CONNECTION_FAILED";
+    readonly RESULT_TOO_LARGE: "RESULT_TOO_LARGE";
+    readonly UNSUPPORTED_FEATURE: "UNSUPPORTED_FEATURE";
+};
+export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
+export type ToolError = {
+    code: ErrorCode;
+    message: string;
+    retryable?: boolean;
+    details?: Record<string, unknown>;
+};
+export type ResponseMetadata = {
+    task_id: string;
+    sql_hash?: string;
+    statement_type?: StatementType;
+    duration_ms?: number;
+};
+export type ToolResponse<T = unknown> = {
+    ok: boolean;
+    summary: string;
+    data?: T;
+    error?: ToolError;
+    metadata: ResponseMetadata;
+};
+export type FormatSuccessOptions = {
+    summary: string;
+    metadata: ResponseMetadata;
+};
+export type FormatErrorOptions<T = unknown> = {
+    code: ErrorCode;
+    message: string;
+    summary: string;
+    metadata: ResponseMetadata;
+    retryable?: boolean;
+    details?: Record<string, unknown>;
+    data?: T;
+};
+export type FormatBlockedOptions = {
+    reason: string;
+    metadata: ResponseMetadata;
+    summary?: string;
+    details?: Record<string, unknown>;
+};
+export type FormatConfirmationRequiredOptions = {
+    confirmationToken: string;
+    metadata: ResponseMetadata;
+    summary?: string;
+    message?: string;
+    riskLevel?: string;
+    sqlHash?: string;
+};
+export declare function formatSuccess<T>(data: T, options: FormatSuccessOptions): ToolResponse<T>;
+export declare function formatError<T = unknown>(options: FormatErrorOptions<T>): ToolResponse<T>;
+export declare function formatBlocked(options: FormatBlockedOptions): ToolResponse;
+export declare function formatConfirmationRequired(options: FormatConfirmationRequiredOptions): ToolResponse<{
+    confirmation_token: string;
+    risk_level?: string;
+    sql_hash?: string;
+}>;

package/dist/utils/formatter.js

@@ -0,0 +1,60 @@
+export const ErrorCode = {
+    DATASOURCE_NOT_FOUND: "DATASOURCE_NOT_FOUND",
+    CREDENTIAL_MISSING: "CREDENTIAL_MISSING",
+    BLOCKED_SQL: "BLOCKED_SQL",
+    CONFIRMATION_REQUIRED: "CONFIRMATION_REQUIRED",
+    CONFIRMATION_INVALID: "CONFIRMATION_INVALID",
+    INVALID_INPUT: "INVALID_INPUT",
+    SQL_SYNTAX_ERROR: "SQL_SYNTAX_ERROR",
+    QUERY_TIMEOUT: "QUERY_TIMEOUT",
+    QUERY_CANCELLED: "QUERY_CANCELLED",
+    CONNECTION_FAILED: "CONNECTION_FAILED",
+    RESULT_TOO_LARGE: "RESULT_TOO_LARGE",
+    UNSUPPORTED_FEATURE: "UNSUPPORTED_FEATURE",
+};
+export function formatSuccess(data, options) {
+    return {
+        ok: true,
+        summary: options.summary,
+        data,
+        metadata: options.metadata,
+    };
+}
+export function formatError(options) {
+    return {
+        ok: false,
+        summary: options.summary,
+        data: options.data,
+        error: {
+            code: options.code,
+            message: options.message,
+            retryable: options.retryable,
+            details: options.details,
+        },
+        metadata: options.metadata,
+    };
+}
+export function formatBlocked(options) {
+    return formatError({
+        code: ErrorCode.BLOCKED_SQL,
+        message: options.reason,
+        summary: options.summary ?? "The SQL statement is blocked by safety policy.",
+        retryable: false,
+        details: options.details,
+        metadata: options.metadata,
+    });
+}
+export function formatConfirmationRequired(options) {
+    return formatError({
+        code: ErrorCode.CONFIRMATION_REQUIRED,
+        message: options.message ?? "Re-run the same SQL with confirmation_token to continue.",
+        summary: options.summary ?? "This SQL will modify data and requires explicit confirmation.",
+        retryable: true,
+        metadata: options.metadata,
+        data: {
+            confirmation_token: options.confirmationToken,
+            risk_level: options.riskLevel,
+            sql_hash: options.sqlHash,
+        },
+    });
+}

package/dist/utils/hash.d.ts

@@ -0,0 +1,2 @@
+export declare function normalizeSql(sql: string): string;
+export declare function sqlHash(normalized: string): string;

package/dist/utils/hash.js

@@ -0,0 +1,247 @@
+import { createHash } from "node:crypto";
+const SQL_KEYWORDS = new Set([
+    "select",
+    "show",
+    "describe",
+    "desc",
+    "explain",
+    "from",
+    "where",
+    "group",
+    "by",
+    "order",
+    "having",
+    "limit",
+    "offset",
+    "join",
+    "left",
+    "right",
+    "inner",
+    "outer",
+    "cross",
+    "on",
+    "as",
+    "distinct",
+    "union",
+    "all",
+    "insert",
+    "into",
+    "values",
+    "update",
+    "set",
+    "delete",
+    "create",
+    "alter",
+    "drop",
+    "truncate",
+    "table",
+    "database",
+    "schema",
+    "if",
+    "exists",
+    "not",
+    "null",
+    "and",
+    "or",
+    "in",
+    "is",
+    "like",
+    "between",
+    "case",
+    "when",
+    "then",
+    "else",
+    "end",
+    "asc",
+    "desc",
+    "with",
+    "recursive",
+    "grant",
+    "revoke",
+    "begin",
+    "commit",
+    "rollback",
+].map((keyword) => keyword.toLowerCase()));
+function isWhitespace(char) {
+    return char === " " || char === "\t" || char === "\n" || char === "\r" || char === "\f";
+}
+function isWordChar(char) {
+    return /[A-Za-z0-9_$]/.test(char);
+}
+function stripSqlComments(sql) {
+    let result = "";
+    let quoteState = "none";
+    let index = 0;
+    while (index < sql.length) {
+        const char = sql[index];
+        const next = sql[index + 1];
+        if (quoteState === "none") {
+            if (char === "'" || char === '"' || char === "`") {
+                quoteState = char;
+                result += char;
+                index += 1;
+                continue;
+            }
+            if (char === "/" && next === "*") {
+                if (result.length > 0 && !isWhitespace(result[result.length - 1])) {
+                    result += " ";
+                }
+                index += 2;
+                while (index < sql.length && !(sql[index] === "*" && sql[index + 1] === "/")) {
+                    index += 1;
+                }
+                if (index < sql.length) {
+                    index += 2;
+                }
+                continue;
+            }
+            if (char === "-" && next === "-") {
+                if (result.length > 0 && !isWhitespace(result[result.length - 1])) {
+                    result += " ";
+                }
+                index += 2;
+                while (index < sql.length && sql[index] !== "\n") {
+                    index += 1;
+                }
+                continue;
+            }
+            if (char === "#") {
+                if (result.length > 0 && !isWhitespace(result[result.length - 1])) {
+                    result += " ";
+                }
+                index += 1;
+                while (index < sql.length && sql[index] !== "\n") {
+                    index += 1;
+                }
+                continue;
+            }
+        }
+        else if (char === quoteState) {
+            if (sql[index + 1] === quoteState) {
+                result += char;
+                result += sql[index + 1];
+                index += 2;
+                continue;
+            }
+            quoteState = "none";
+            result += char;
+            index += 1;
+            continue;
+        }
+        result += char;
+        index += 1;
+    }
+    return result;
+}
+function trimLineEndWhitespace(sql) {
+    return sql
+        .replace(/\r\n/g, "\n")
+        .split("\n")
+        .map((line) => line.replace(/[ \t]+$/g, ""))
+        .join("\n");
+}
+function collapseWhitespaceOutsideLiterals(sql) {
+    let result = "";
+    let quoteState = "none";
+    let pendingSpace = false;
+    let index = 0;
+    while (index < sql.length) {
+        const char = sql[index];
+        if (quoteState === "none") {
+            if (char === "'" || char === '"' || char === "`") {
+                if (pendingSpace && result.length > 0) {
+                    result += " ";
+                }
+                pendingSpace = false;
+                quoteState = char;
+                result += char;
+                index += 1;
+                continue;
+            }
+            if (isWhitespace(char)) {
+                pendingSpace = true;
+                index += 1;
+                continue;
+            }
+            if (pendingSpace && result.length > 0) {
+                result += " ";
+            }
+            pendingSpace = false;
+            result += char;
+            index += 1;
+            continue;
+        }
+        result += char;
+        if (char === quoteState) {
+            if (sql[index + 1] === quoteState) {
+                result += sql[index + 1];
+                index += 2;
+                continue;
+            }
+            quoteState = "none";
+        }
+        index += 1;
+    }
+    return result.trim();
+}
+function uppercaseKeywordsOutsideLiterals(sql) {
+    let result = "";
+    let quoteState = "none";
+    let index = 0;
+    let currentWord = "";
+    const flushWord = () => {
+        if (currentWord.length === 0) {
+            return;
+        }
+        const lower = currentWord.toLowerCase();
+        result += SQL_KEYWORDS.has(lower) ? lower.toUpperCase() : currentWord;
+        currentWord = "";
+    };
+    while (index < sql.length) {
+        const char = sql[index];
+        if (quoteState === "none") {
+            if (char === "'" || char === '"' || char === "`") {
+                flushWord();
+                quoteState = char;
+                result += char;
+                index += 1;
+                continue;
+            }
+            if (isWordChar(char)) {
+                currentWord += char;
+            }
+            else {
+                flushWord();
+                result += char;
+            }
+            index += 1;
+            continue;
+        }
+        flushWord();
+        result += char;
+        if (char === quoteState) {
+            if (sql[index + 1] === quoteState) {
+                result += sql[index + 1];
+                index += 2;
+                continue;
+            }
+            quoteState = "none";
+        }
+        index += 1;
+    }
+    flushWord();
+    return result;
+}
+function stripTrailingSemicolon(sql) {
+    return sql.replace(/\s*;\s*$/, "").trim();
+}
+export function normalizeSql(sql) {
+    const withoutComments = stripSqlComments(sql);
+    const lineTrimmed = trimLineEndWhitespace(withoutComments);
+    const collapsed = collapseWhitespaceOutsideLiterals(lineTrimmed);
+    const keywordUppercased = uppercaseKeywordsOutsideLiterals(collapsed);
+    return stripTrailingSemicolon(keywordUppercased);
+}
+export function sqlHash(normalized) {
+    return createHash("sha256").update(normalized).digest("hex").slice(0, 16);
+}

package/dist/utils/id.d.ts

@@ -0,0 +1,2 @@
+export declare function generateTaskId(now?: number): string;
+export declare function generateQueryId(now?: number): string;

package/dist/utils/id.js

@@ -0,0 +1,11 @@
+import { monotonicFactory } from "ulid";
+const monotonicUlid = monotonicFactory();
+function generatePrefixedId(prefix, now = Date.now()) {
+    return `${prefix}${monotonicUlid(now).toLowerCase()}`;
+}
+export function generateTaskId(now) {
+    return generatePrefixedId("task_", now);
+}
+export function generateQueryId(now) {
+    return generatePrefixedId("qry_", now);
+}

package/dist/utils/logger.d.ts

@@ -0,0 +1,9 @@
+import pino, { type DestinationStream, type Logger } from "pino";
+type TaskContext = {
+    task_id: string;
+};
+export declare function createLogger(destination?: DestinationStream | NodeJS.WritableStream): Logger;
+export declare const logger: pino.Logger;
+export declare function withTaskContext<T>(task_id: string, fn: () => Promise<T>): Promise<T>;
+export declare function getTaskContext(): TaskContext | undefined;
+export {};

package/dist/utils/logger.js

@@ -0,0 +1,39 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import pino from "pino";
+const taskContextStorage = new AsyncLocalStorage();
+const REDACT_PATHS = [
+    "password",
+    "*.password",
+    "credentials.*",
+    "secret",
+    "token",
+    "*.token",
+];
+function createDefaultDestination() {
+    return pino.destination({ fd: 2, sync: false });
+}
+function createLoggerOptions() {
+    return {
+        level: process.env.TAURUSDB_MCP_LOG_LEVEL ?? "info",
+        base: undefined,
+        redact: {
+            paths: REDACT_PATHS,
+            censor: "[REDACTED]",
+        },
+        mixin: () => {
+            const taskId = taskContextStorage.getStore()?.task_id;
+            return taskId ? { task_id: taskId } : {};
+        },
+        timestamp: pino.stdTimeFunctions.isoTime,
+    };
+}
+export function createLogger(destination) {
+    return pino(createLoggerOptions(), destination ?? createDefaultDestination());
+}
+export const logger = createLogger();
+export function withTaskContext(task_id, fn) {
+    return taskContextStorage.run({ task_id }, fn);
+}
+export function getTaskContext() {
+    return taskContextStorage.getStore();
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "taurusdb-core",
+  "version": "0.1.0",
+  "description": "Shared TaurusDB data-plane engine for schema, SQL execution, guardrails, and diagnostics.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "keywords": [
+    "taurusdb",
+    "mysql",
+    "database",
+    "diagnostics",
+    "guardrails"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc --noEmit -p tsconfig.json",
+    "test": "node --test tests/*.test.mjs"
+  },
+  "dependencies": {
+    "mysql2": "^3.22.1",
+    "node-sql-parser": "^5.4.0",
+    "pino": "^9.11.0",
+    "ulid": "^3.0.1",
+    "zod": "^3.24.1"
+  }
+}