@hachej/boring-data-bridge 0.1.60

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 boringdata
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,9 @@
+# @hachej/boring-data-bridge
+
+Trusted WorkspaceBridge-backed data query plugin. It registers `data.v1.query.run`
+so dashboard/runtime callers can execute either:
+
+- `language: "bsl"` — a BSL/Ibis expression string evaluated by BSL `safe_eval`.
+- `language: "sql"` — read-only SQL routed through a host-registered adapter.
+
+This package intentionally does not define a separate dashboard JSON-to-BSL query DSL.

package/dist/chunk-72EZA7HP.js

@@ -0,0 +1,6 @@
+// src/shared/index.ts
+var DATA_BRIDGE_QUERY_RUN_OP = "data.v1.query.run";
+
+export {
+  DATA_BRIDGE_QUERY_RUN_OP
+};

package/dist/front/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/server/index.d.ts

@@ -0,0 +1,27 @@
+import { WorkspaceServerPlugin } from '@hachej/boring-workspace/server';
+import { DataBridgeSqlQuery, DataBridgeTableResult } from '../shared/index.js';
+
+interface DataBridgeSqlAdapter {
+    requiredCapabilities?: string[];
+    maxRows?: number;
+    execute(args: {
+        query: DataBridgeSqlQuery;
+        sql: string;
+        params?: Record<string, unknown>;
+        limit: number;
+        signal?: AbortSignal;
+    }): Promise<DataBridgeTableResult>;
+}
+interface CreateDataBridgeServerPluginOptions {
+    workspaceRoot: string;
+    bslModelPath?: string;
+    bslProfile?: string;
+    bslProfileFile?: string;
+    sqlAdapters?: Record<string, DataBridgeSqlAdapter>;
+}
+declare function createDataBridgeServerPlugin(options: CreateDataBridgeServerPluginOptions): WorkspaceServerPlugin;
+declare function defaultDataBridgeServerPlugin(_options: unknown, ctx: {
+    workspaceRoot: string;
+}): WorkspaceServerPlugin;
+
+export { type DataBridgeSqlAdapter, createDataBridgeServerPlugin, defaultDataBridgeServerPlugin as default };

package/dist/server/index.js

@@ -0,0 +1,168 @@
+import {
+  DATA_BRIDGE_QUERY_RUN_OP
+} from "../chunk-72EZA7HP.js";
+
+// src/server/index.ts
+import { spawn } from "child_process";
+import {
+  defineServerPlugin,
+  defineTrustedDomainBridgeHandler
+} from "@hachej/boring-workspace/server";
+var SQL_DEFAULT_LIMIT = 1e3;
+var SQL_MAX_LIMIT = 5e3;
+var SQL_ALLOWED_FIRST_TOKENS = /* @__PURE__ */ new Set(["SELECT", "WITH", "EXPLAIN", "DESCRIBE", "SHOW", "DESC"]);
+var MULTI_STMT_RE = /;\s*\S/;
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function normalizeLimit(value, max = SQL_MAX_LIMIT) {
+  const n = typeof value === "number" ? value : Number(value);
+  if (!Number.isFinite(n)) return Math.min(SQL_DEFAULT_LIMIT, max);
+  return Math.max(1, Math.min(Math.floor(n), max));
+}
+function requireCapabilities(actual, required) {
+  const missing = required.find((capability) => !actual.includes(capability));
+  if (missing) throw new Error(`Missing required data capability: ${missing}`);
+}
+function normalizeReadOnlySql(sql) {
+  const query = sql.trim().replace(/;+$/, "").trim();
+  if (!query) throw new Error("SQL query is required");
+  const firstToken = query.split(/\s+/)[0]?.toUpperCase() ?? "";
+  if (!SQL_ALLOWED_FIRST_TOKENS.has(firstToken)) {
+    throw new Error(`Only read-only SQL queries are allowed (${[...SQL_ALLOWED_FIRST_TOKENS].sort().join(", ")})`);
+  }
+  if (MULTI_STMT_RE.test(query)) throw new Error("Multi-statement SQL queries are not allowed");
+  return query;
+}
+function truncateResult(result, limit) {
+  if (result.rows.length <= limit) return result;
+  return {
+    ...result,
+    rows: result.rows.slice(0, limit),
+    rowCount: Math.max(result.rowCount, result.rows.length),
+    truncated: true
+  };
+}
+async function runBslQuery(options, input, signal) {
+  const modelPath = options.bslModelPath ?? process.env.BORING_BSL_MODEL_PATH ?? process.env.BSL_MODEL_PATH;
+  if (!modelPath) throw new Error("BSL adapter is not configured: set BORING_BSL_MODEL_PATH");
+  const payload = {
+    modelPath,
+    profile: options.bslProfile ?? process.env.BORING_BSL_PROFILE,
+    profileFile: options.bslProfileFile ?? process.env.BORING_BSL_PROFILE_FILE,
+    model: input.query.model,
+    query: input.query.query,
+    limit: input.query.limit ?? 5e3
+  };
+  return await runPythonBsl(payload, signal);
+}
+async function runSqlQuery(options, input, capabilities, signal) {
+  if (input.query.language !== "sql") throw new Error("SQL adapter requires query.language=sql");
+  requireCapabilities(capabilities, ["data:sql-query"]);
+  const adapter = options.sqlAdapters?.[input.query.source];
+  if (!adapter) throw new Error(`Data bridge SQL source is not configured: ${input.query.source}`);
+  requireCapabilities(capabilities, adapter.requiredCapabilities ?? []);
+  const maxRows = adapter.maxRows ?? SQL_MAX_LIMIT;
+  const limit = normalizeLimit(input.query.limit, maxRows);
+  const sql = normalizeReadOnlySql(input.query.sql);
+  const result = await adapter.execute({
+    query: { ...input.query, sql, limit },
+    sql,
+    params: input.query.params,
+    limit,
+    signal
+  });
+  return { ...truncateResult(result, limit), source: result.source ?? input.query.source };
+}
+async function runPythonBsl(payload, signal) {
+  const script = String.raw`
+import json, sys
+from pathlib import Path
+import ibis
+from ibis import _
+from returns.result import Failure, Success
+from boring_semantic_layer import from_yaml
+from boring_semantic_layer.utils import safe_eval
+payload = json.loads(sys.stdin.read())
+query = payload["query"]
+models = from_yaml(Path(payload["modelPath"]), profile=payload.get("profile"), profile_path=payload.get("profileFile"))
+sm = models[payload["model"]]
+evaluated = safe_eval(query, context={**models, "sm": sm, "ibis": ibis, "_": _})
+if isinstance(evaluated, Failure):
+    raise evaluated.failure()
+result = evaluated.unwrap() if isinstance(evaluated, Success) else evaluated
+df = result.execute()
+limit = int(payload.get("limit") or 5000)
+rows = json.loads(df.head(limit).to_json(orient="records", date_format="iso"))
+columns = []
+for name in df.columns:
+    series = df[name]
+    kind = "string"
+    if str(series.dtype).startswith("int"):
+        kind = "integer"
+    elif str(series.dtype).startswith("float") or str(series.dtype).startswith("decimal"):
+        kind = "float"
+    elif str(series.dtype).startswith("bool"):
+        kind = "boolean"
+    elif "datetime" in str(series.dtype):
+        kind = "datetime"
+    columns.append({"name": str(name), "type": kind})
+print(json.dumps({"kind":"data-bridge.table","version":1,"columns":columns,"rows":rows,"rowCount":len(rows),"truncated": len(df) > len(rows), "source":"bsl"}))
+`;
+  if (signal?.aborted) throw new Error("BSL query aborted");
+  const child = spawn(process.env.BORING_DATA_BRIDGE_PYTHON ?? "python3", ["-c", script], { stdio: ["pipe", "pipe", "pipe"] });
+  const abort = () => child.kill("SIGKILL");
+  signal?.addEventListener("abort", abort, { once: true });
+  child.stdin.end(JSON.stringify(payload));
+  const [stdout, stderr, code] = await new Promise((resolvePromise) => {
+    let out = "";
+    let err = "";
+    child.stdout.on("data", (chunk) => {
+      out += String(chunk);
+    });
+    child.stderr.on("data", (chunk) => {
+      err += String(chunk);
+    });
+    child.on("close", (exitCode) => resolvePromise([out, err, exitCode]));
+  }).finally(() => signal?.removeEventListener("abort", abort));
+  if (signal?.aborted) throw new Error("BSL query aborted");
+  if (code !== 0) throw new Error(stderr.trim() || `BSL query failed with exit code ${code}`);
+  return JSON.parse(stdout);
+}
+function createDataBridgeServerPlugin(options) {
+  const queryRun = defineTrustedDomainBridgeHandler({
+    op: DATA_BRIDGE_QUERY_RUN_OP,
+    version: 1,
+    owner: "data-bridge",
+    callerClassesAllowed: ["browser", "runtime", "server"],
+    requiredCapabilities: ["data:read"],
+    inputSchema: { type: "object" },
+    maxOutputBytes: 2 * 1024 * 1024,
+    timeoutMs: 3e4,
+    idempotencyPolicy: "none",
+    handler: async ({ input, context, signal }) => {
+      if (!isRecord(input) || !isRecord(input.query)) throw new Error("Invalid data bridge query input");
+      const typedInput = input;
+      if (typedInput.query.language === "sql") {
+        return await runSqlQuery(options, typedInput, context.capabilities, signal);
+      }
+      if (typedInput.query.language !== "bsl") {
+        throw new Error("Data bridge query language must be either bsl or sql");
+      }
+      return await runBslQuery(options, typedInput, signal);
+    }
+  });
+  return defineServerPlugin({
+    id: "data-bridge",
+    label: "Data Bridge",
+    workspaceBridgeHandlers: [queryRun],
+    systemPrompt: "Use data.v1.query.run through WorkspaceBridge for dashboard data. Supported query languages are bsl and sql."
+  });
+}
+function defaultDataBridgeServerPlugin(_options, ctx) {
+  return createDataBridgeServerPlugin({ workspaceRoot: ctx.workspaceRoot });
+}
+export {
+  createDataBridgeServerPlugin,
+  defaultDataBridgeServerPlugin as default
+};

package/dist/shared/index.d.ts

@@ -0,0 +1,37 @@
+declare const DATA_BRIDGE_QUERY_RUN_OP: "data.v1.query.run";
+type DataBridgeScalarType = "string" | "integer" | "float" | "boolean" | "date" | "datetime" | "json";
+type DataBridgeRole = "dimension" | "measure" | "time" | "unknown";
+interface DataBridgeColumn {
+    name: string;
+    type: DataBridgeScalarType;
+    role?: DataBridgeRole;
+}
+interface DataBridgeBslQuery {
+    language: "bsl";
+    model: string;
+    query: string;
+    limit?: number;
+}
+interface DataBridgeSqlQuery {
+    language: "sql";
+    source: string;
+    sql: string;
+    params?: Record<string, unknown>;
+    limit?: number;
+}
+type DataBridgeQuery = DataBridgeBslQuery | DataBridgeSqlQuery;
+interface DataBridgeQueryRunInput {
+    source?: string;
+    query: DataBridgeQuery;
+}
+interface DataBridgeTableResult {
+    kind: "data-bridge.table";
+    version: 1;
+    columns: DataBridgeColumn[];
+    rows: Record<string, unknown>[];
+    rowCount: number;
+    truncated?: boolean;
+    source?: string;
+}
+
+export { DATA_BRIDGE_QUERY_RUN_OP, type DataBridgeBslQuery, type DataBridgeColumn, type DataBridgeQuery, type DataBridgeQueryRunInput, type DataBridgeRole, type DataBridgeScalarType, type DataBridgeSqlQuery, type DataBridgeTableResult };

package/dist/shared/index.js

@@ -0,0 +1,6 @@
+import {
+  DATA_BRIDGE_QUERY_RUN_OP
+} from "../chunk-72EZA7HP.js";
+export {
+  DATA_BRIDGE_QUERY_RUN_OP
+};

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@hachej/boring-data-bridge",
+  "version": "0.1.60",
+  "type": "module",
+  "private": false,
+  "license": "MIT",
+  "description": "WorkspaceBridge-backed semantic data adapter plugin for Boring workspace.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hachej/boring-ui"
+  },
+  "homepage": "https://github.com/hachej/boring-ui",
+  "boring": {
+    "id": "data-bridge",
+    "label": "Data Bridge",
+    "front": "dist/front/index.js",
+    "server": "dist/server/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/shared/index.d.ts",
+      "import": "./dist/shared/index.js"
+    },
+    "./front": {
+      "types": "./dist/front/index.d.ts",
+      "import": "./dist/front/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.js"
+    },
+    "./shared": {
+      "types": "./dist/shared/index.d.ts",
+      "import": "./dist/shared/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "peerDependencies": {
+    "@hachej/boring-workspace": "0.1.60"
+  },
+  "devDependencies": {
+    "@duckdb/node-api": "1.5.2-r.1",
+    "tsup": "^8.4.0",
+    "typescript": "~5.9.3",
+    "vitest": "^3.2.6",
+    "@hachej/boring-workspace": "0.1.60"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "lint": "pnpm run typecheck",
+    "clean": "rm -rf dist .tsbuildinfo"
+  }
+}