@hachej/boring-bi-dashboard 0.1.60

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@hachej/boring-bi-dashboard",
+  "version": "0.1.60",
+  "type": "module",
+  "private": false,
+  "license": "MIT",
+  "description": "BI dashboard plugin primitives for Boring workspace: BSL-backed dashboard specs, charts, metrics, filters, and Perspective panels.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hachej/boring-ui"
+  },
+  "homepage": "https://github.com/hachej/boring-ui",
+  "boring": {
+    "id": "bi-dashboard",
+    "label": "BI Dashboard",
+    "front": "dist/front/index.js",
+    "server": false
+  },
+  "pi": {
+    "skills": [
+      "skills/bi-dashboard-authoring"
+    ],
+    "systemPrompt": "Use the bi-dashboard-authoring skill when the user asks to create, edit, or open a BI dashboard. Dashboard files should live under dashboards/*.dashboard.json."
+  },
+  "files": [
+    "dist",
+    "skills",
+    "example",
+    "playground",
+    "docs",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/front/index.d.ts",
+      "import": "./dist/front/index.js"
+    },
+    "./front": {
+      "types": "./dist/front/index.d.ts",
+      "import": "./dist/front/index.js"
+    },
+    "./shared": {
+      "types": "./dist/shared/index.d.ts",
+      "import": "./dist/shared/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "@hachej/boring-workspace": "0.1.60"
+  },
+  "dependencies": {
+    "lucide-react": "^1.8.0",
+    "zod": "^4.3.6",
+    "@hachej/boring-generated-pane": "0.1.60",
+    "@hachej/boring-ui-kit": "0.1.60"
+  },
+  "devDependencies": {
+    "@duckdb/node-api": "1.5.2-r.1",
+    "@json-render/core": "^0.19.0",
+    "@json-render/react": "^0.19.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsup": "^8.4.0",
+    "tsx": "^4.21.0",
+    "typescript": "~5.9.3",
+    "vitest": "^3.2.6",
+    "@hachej/boring-agent": "0.1.60",
+    "@hachej/boring-data-bridge": "0.1.60",
+    "@hachej/boring-workspace": "0.1.60"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "playground:eval": "tsx playground/run-eval.ts",
+    "playground:smoke": "tsx playground/smoke-dashboard.ts",
+    "lint": "pnpm run typecheck",
+    "clean": "rm -rf dist .tsbuildinfo"
+  }
+}

package/playground/README.md

@@ -0,0 +1,25 @@
+# BI dashboard playground
+
+This folder contains plugin-local playground helpers. The repo-level `workspace-playground` stays generic; BI dashboard is loaded explicitly when needed.
+
+## Browser playground
+
+Run the plugin in the existing workspace playground using the fixture in `../example`. The demo workspace includes `.pi/extensions/bi-dashboard`, which loads the front plugin as a workspace-local extension. For live query data, use the eval runner or another host that loads `@hachej/boring-data-bridge` as a trusted server plugin:
+
+```bash
+pnpm --filter @hachej/boring-data-bridge build
+pnpm --filter @hachej/boring-bi-dashboard build
+BORING_EXTERNAL_PLUGINS=1 \
+BORING_AGENT_WORKSPACE_ROOT="$PWD/plugins/bi-dashboard/example" \
+pnpm --filter workspace-playground dev
+```
+
+## Eval playground
+
+Run the dashboard authoring eval through the plugin-local runner:
+
+```bash
+pnpm --filter @hachej/boring-bi-dashboard playground:eval
+```
+
+The runner seeds a temp workspace from `../example` and loads `@hachej/boring-data-bridge` plus `@hachej/boring-bi-dashboard` explicitly.

package/playground/run-eval.ts

@@ -0,0 +1,100 @@
+#!/usr/bin/env -S tsx
+import { cpSync, mkdtempSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { dirname, join, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+import { runEvalSuite, type SuiteReport } from "@hachej/boring-agent/eval"
+import { createWorkspaceAgentServer } from "@hachej/boring-workspace/app/server"
+import { parseDashboardSpec } from "../src/shared/validation"
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+const PLUGIN_ROOT = resolve(__dirname, "..")
+const EXAMPLE_ROOT = resolve(PLUGIN_ROOT, "example")
+const DEFAULT_EVAL = resolve(EXAMPLE_ROOT, "eval/bi-dashboard.yaml")
+
+function seedWorkspace(): string {
+  const root = mkdtempSync(join(tmpdir(), "bi-dashboard-playground-"))
+  cpSync(EXAMPLE_ROOT, root, { recursive: true })
+  return root
+}
+
+async function main(): Promise<number> {
+  const fixturesPath = resolve(process.argv[2] ?? DEFAULT_EVAL)
+  const workspaceRoot = seedWorkspace()
+  console.log(`[bi-dashboard playground] running suite: ${fixturesPath}`)
+  console.log(`[bi-dashboard playground] seeded workspace: ${workspaceRoot}`)
+
+  const app = await createWorkspaceAgentServer({
+    workspaceRoot,
+    appRoot: PLUGIN_ROOT,
+    mode: "local",
+    logger: false,
+    defaultPluginPackages: ["@hachej/boring-data-bridge", "@hachej/boring-bi-dashboard"],
+    workspaceBridge: { allowInsecureLocalCliBrowserAuth: true },
+  })
+
+  try {
+    const report = await runEvalSuite({ app, fixturesPath, concurrency: 1 })
+    console.log(
+      `[bi-dashboard playground] ${report.passed}/${report.total} passed (${(report.passRate * 100).toFixed(1)}%) in ${(report.totalDurationMs / 1000).toFixed(1)}s`,
+    )
+
+    const validationErrors = validateWrittenDashboards(report)
+    if (validationErrors.length > 0) {
+      console.error("\n[bi-dashboard playground] generated dashboard validation failed:")
+      for (const error of validationErrors) console.error(`  - ${error}`)
+      return 1
+    }
+
+    if (!report.allPassed) {
+      console.error(`\n[bi-dashboard playground] ${report.failed} prompt(s) failed:`)
+      for (const r of report.results) {
+        if (r.ok) continue
+        console.error(`\n  prompt: ${r.prompt}`)
+        console.error(`  reason: ${r.reason ?? "(no reason)"}`)
+        if (r.actual.length > 0) {
+          console.error(`  actual calls: ${JSON.stringify(r.actual, null, 2).replace(/\n/g, "\n  ")}`)
+        }
+        if (r.text) {
+          console.error(`  text: ${r.text.slice(0, 200)}${r.text.length > 200 ? "…" : ""}`)
+        }
+      }
+      return 1
+    }
+
+    return 0
+  } finally {
+    await app.close()
+  }
+}
+
+function validateWrittenDashboards(report: SuiteReport): string[] {
+  const errors: string[] = []
+  for (const result of report.results) {
+    for (const call of result.actual) {
+      if (call.tool !== "write") continue
+      const path = typeof call.params.path === "string" ? call.params.path : ""
+      if (!/\.dashboard\.json$/i.test(path)) continue
+      if (typeof call.params.content !== "string") {
+        errors.push(`${path || "dashboard write"}: content is not a string`)
+        continue
+      }
+      try {
+        const parsed = parseDashboardSpec(JSON.parse(call.params.content))
+        if (!parsed.spec) errors.push(`${path}: ${parsed.errors.join("; ")}`)
+      } catch (error) {
+        errors.push(`${path}: invalid JSON (${error instanceof Error ? error.message : String(error)})`)
+      }
+    }
+  }
+  return errors
+}
+
+main().then(
+  (code) => process.exit(code),
+  (err) => {
+    console.error("[bi-dashboard playground] fatal:", err)
+    process.exit(2)
+  },
+)

package/playground/smoke-dashboard.ts

@@ -0,0 +1,101 @@
+#!/usr/bin/env -S tsx
+import { readFileSync } from "node:fs"
+import { dirname, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+import { DuckDBConnection, quotedIdentifier, quotedString } from "@duckdb/node-api"
+import { createWorkspaceBridgeRegistry } from "@hachej/boring-workspace/server"
+import { createDataBridgeServerPlugin, type DataBridgeSqlAdapter } from "@hachej/boring-data-bridge/server"
+import type { DataBridgeTableResult } from "@hachej/boring-data-bridge/shared"
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+const PLUGIN_ROOT = resolve(__dirname, "..")
+const EXAMPLE_ROOT = resolve(PLUGIN_ROOT, "example")
+const DASHBOARD_PATH = resolve(EXAMPLE_ROOT, "dashboards/people.dashboard.json")
+
+async function createPeopleDuckDbAdapter(): Promise<{ adapter: DataBridgeSqlAdapter; close: () => void }> {
+  const connection = await DuckDBConnection.create()
+  await connection.run(
+    `create or replace view ${quotedIdentifier("people")} as select * from read_csv_auto(${quotedString(resolve(EXAMPLE_ROOT, "data/people.csv"))}, HEADER = true)`,
+  )
+  return {
+    adapter: {
+      maxRows: 100,
+      async execute({ sql, limit }) {
+        const reader = await connection.runAndReadUntil(sql, limit + 1)
+        const rows = reader.getRowObjectsJson().slice(0, limit) as Record<string, unknown>[]
+        return {
+          kind: "data-bridge.table",
+          version: 1,
+          columns: reader.columnNames().map((name) => ({ name, type: "string" })),
+          rows,
+          rowCount: rows.length,
+          truncated: !reader.done || reader.currentRowCount > limit,
+          source: "people-duckdb",
+        }
+      },
+    },
+    close: () => connection.closeSync(),
+  }
+}
+
+async function main(): Promise<number> {
+  const dashboard = JSON.parse(readFileSync(DASHBOARD_PATH, "utf8")) as {
+    profile?: unknown
+    queries?: Record<string, { id: string; source?: string; sql?: string; params?: Record<string, unknown>; model?: string; query?: string; limit?: number }>
+  }
+  if (dashboard.profile !== "bi-dashboard" || !dashboard.queries) {
+    console.error("[bi-dashboard smoke] invalid dashboard fixture")
+    return 1
+  }
+
+  const { adapter, close } = await createPeopleDuckDbAdapter()
+  try {
+    const plugin = createDataBridgeServerPlugin({
+      workspaceRoot: EXAMPLE_ROOT,
+      sqlAdapters: { "people-duckdb": adapter },
+    })
+    const registry = createWorkspaceBridgeRegistry()
+    for (const contribution of plugin.workspaceBridgeHandlers ?? []) {
+      registry.registerHandler(contribution.definition, contribution.handler)
+    }
+
+    for (const [queryId, query] of Object.entries(dashboard.queries)) {
+      const bridgeQuery = query.sql
+        ? { language: "sql" as const, source: query.source ?? "default", sql: query.sql, params: query.params, limit: query.limit }
+        : { language: "bsl" as const, model: query.model ?? "", query: query.query ?? "", limit: query.limit }
+
+      const res = await registry.call({
+        op: "data.v1.query.run",
+        input: { query: bridgeQuery },
+      }, {
+        callerClass: "runtime",
+        workspaceId: "bi-dashboard-smoke",
+        capabilities: ["data:read", "data:sql-query"],
+        actor: { actorKind: "agent", performedBy: { label: "bi-dashboard smoke" } },
+      })
+
+      if (!res.ok) {
+        console.error(`[bi-dashboard smoke] ${queryId} failed: ${res.error.message}`)
+        return 1
+      }
+      const output = res.output as DataBridgeTableResult
+      if (!Array.isArray(output.rows) || output.rows.length === 0) {
+        console.error(`[bi-dashboard smoke] ${queryId} returned no rows`)
+        return 1
+      }
+      console.log(`[bi-dashboard smoke] ${queryId}: ${output.rows.length} row(s)`)
+    }
+    return 0
+  } finally {
+    close()
+  }
+}
+
+main().then(
+  (code) => process.exit(code),
+  (err) => {
+    console.error("[bi-dashboard smoke] fatal:", err)
+    process.exit(2)
+  },
+)

package/skills/bi-dashboard-authoring/SKILL.md

@@ -0,0 +1,78 @@
+---
+description: Create or edit BSL BI dashboard JSON specs for the BI Dashboard plugin.
+---
+
+# bi-dashboard-authoring
+
+Use this skill when the user asks to create, edit, or open a BI dashboard for
+`@hachej/boring-bi-dashboard`.
+
+## Files
+
+- write dashboard specs as JSON files under `dashboards/`
+- use the suffix `.dashboard.json`
+- when the user asks to open or view the dashboard and `exec_ui` is available,
+  open the file with:
+
+```json
+{
+  "kind": "openSurface",
+  "params": {
+    "kind": "workspace.open.path",
+    "target": "dashboards/example.dashboard.json"
+  }
+}
+```
+
+## Contract
+
+Write provider-neutral BSL dashboard specs. Do not write React. Do not write raw
+ECharts or raw Perspective configs.
+
+Use this top-level shape:
+
+```json
+{
+  "kind": "boring.generated-pane",
+  "profile": "bi-dashboard",
+  "version": 1,
+  "title": "Dashboard title",
+  "queries": {
+    "query_id": {
+      "id": "query_id",
+      "model": "orders",
+      "groupBy": [],
+      "measures": []
+    }
+  },
+  "root": "dashboard",
+  "elements": {
+    "dashboard": {
+      "type": "DashboardGrid",
+      "props": { "columns": 2 },
+      "children": []
+    }
+  }
+}
+```
+
+## Components
+
+Use only these component types and prop names:
+
+- `DashboardGrid` — layout container with string `children`; optional `props.columns` must be one of `1`, `2`, `3`, `4`, `6`, or `12`
+- `BSLMetric` — KPI card; requires `props.queryId`, `props.label`, and `props.valueField`; optional `props.format` is `number`, `currency`, or `percent`
+- `BSLChart` — chart placeholder; requires `props.queryId` and `props.chartType`; use `props.renderer: "echarts"` for normal charts; allowed chart types are `bar`, `line`, `area`, `scatter`, `heatmap`, `pie`, `treemap`, `sunburst`, `gauge`, and `table`; optional axis props are `props.x`, `props.y`, and `props.color` (not `xField`, `yField`, or `yFields`)
+- `BSLPerspectiveViewer` — exploratory table/pivot; use `props.plugin: "Datagrid"` for detail tables; optional `props.columns`, `props.groupBy`, and `props.splitBy` are string arrays; optional `props.sort` is an array of `[field, "asc" | "desc"]` tuples
+- `BSLFilter` — filter control targeting one or more query IDs; requires `props.id`, `props.field`, `props.controlType`, and `props.targetQueries`; `controlType` is `select`, `multiSelect`, `dateRange`, `numberRange`, or `search`
+- `BSLText` — markdown notes or section text; requires `props.markdown`
+
+## Authoring rules
+
+- every component ID referenced in `children` must exist in `elements`
+- every `queryId` and filter `targetQueries` entry must exist in `queries`
+- use the exact validated prop names above; avoid invented aliases such as `xField`, `yField`, or `yFields`
+- keep the spec concise and readable
+- choose sensible query IDs and component IDs from the dashboard domain
+- prefer semantic BSL fields such as `revenue`, `order_count`, `month`, `region`,
+  `customer_id`, and `cohort_month` over UI-specific names