@hachej/boring-data-catalog 0.1.13

package/README.md

@@ -0,0 +1,298 @@
+# @hachej/boring-data-catalog
+
+<div align="center">
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+</div>
+
+A configurable data catalog plugin for the workbench — left sidebar tab with a searchable, faceted list and a visualization panel to explore rows. Built on [`@hachej/boring-data-explorer`](../data-explorer/README.md).
+
+```bash
+git clone https://github.com/hachej/boring-ui.git && cd boring-ui && pnpm install
+```
+
+> **Note:** This plugin is workspace-private (`"private": true`) — install from source within the monorepo.
+
+---
+
+## TL;DR
+
+**The Problem**: You have a data source (customers, invoices, time series, whatever) and you want users to browse it from a sidebar tab, click rows to open detail visualizations, and let the agent open specific rows programmatically. But wiring up a catalog tab + explorer panel + surface resolver + agent tool is repetitive.
+
+**The Solution**: `@hachej/boring-data-catalog` gives you a one-call plugin factory: pass in an `ExplorerDataSource` adapter and configure labels, facets, and behavior. It contributes a left tab, a visualization panel, a catalog, and a surface resolver — all wired up.
+
+### Why Use @hachej/boring-data-catalog?
+
+| Feature | What It Does |
+|---------|--------------|
+| **Left sidebar catalog tab** | Persistent sidebar listing rows from your adapter, with search and facet filters |
+| **Visualization panel** | Click a row → opens a detail panel that also shows an explorer table |
+| **Surface resolver** | Agent can open a specific row via `openSurface` with `DATA_CATALOG_ROW_SURFACE_KIND` |
+| **Agent tool** | Server plugin ships a `search_catalog` tool the agent uses to find rows before opening them |
+| **Pre-wired with data-explorer** | Search + facets + drag-out behavior comes for free |
+| **Customizable** | Swap the visualization component, customize facets/groupBy/onSelect, or pick which contributions to include |
+
+---
+
+## Quick Example
+
+**Frontend (workbench):**
+
+```ts
+import { createDataCatalogPlugin } from "@hachej/boring-data-catalog/front"
+import type { ExplorerDataSource } from "@hachej/boring-data-explorer/shared"
+
+// Your data adapter
+const adapter: ExplorerDataSource = {
+  async search({ query, filters, limit, offset }) {
+    // fetch from your backend
+    return { items: [...], total, hasMore: ... }
+  },
+}
+
+// One plugin = left tab + visualization panel + catalog + surface resolver
+const catalogPlugin = createDataCatalogPlugin({
+  id: "customers",
+  label: "Customers",
+  adapter,
+  facets: [
+    { key: "industry", label: "Industry", formatValue: (v) => v },
+    { key: "region", label: "Region", order: ["US", "EU", "APAC"], formatValue: (v) => v },
+  ],
+  groupBy: "industry",
+})
+```
+
+Add `catalogPlugin` to your `WorkspaceProvider` plugins array.
+
+**Server (agent runtime):**
+
+```ts
+import { createDataCatalogServerPlugin } from "@hachej/boring-data-catalog/server"
+import { ExplorerDataSource } from "@hachej/boring-data-explorer/shared"
+
+const catalogServerPlugin = createDataCatalogServerPlugin({
+  label: "Customers",
+  adapter,        // same ExplorerDataSource as front
+  defaultLimit: 20,
+  maxLimit: 50,
+})
+```
+
+Add `catalogServerPlugin` to `createAgentApp` `plugins` array.
+
+Now agents can search the catalog via the tool and open specific rows via the UI bridge `openSurface` command:
+```
+openSurface({ kind: DATA_CATALOG_ROW_SURFACE_KIND, target: row.id, meta: { catalogId, row } })
+```
+
+---
+
+## What It Contributes
+
+One call to `createDataCatalogPlugin()` contributes four front registrations:
+
+| Contribution | What | Toggle |
+|--------|------|--------|
+| **Left tab** | Sidebar tab with searchable, faceted table | `includeLeftTab` (default: true) |
+| **Visualization panel** | Center panel for exploring a selected row's context | `includeVisualizationPanel` (default: true) |
+| **Catalog** | Command-palette-searchable catalog entry | `includeCatalog` (default: true) |
+| **Surface resolver** | Maps `openSurface` calls to panel open | `includeSurfaceResolver` (default: true if visualization panel is on) |
+
+You can disable any of these with the `include*` flags. For example, a plugin that only contributes a left tab:
+
+```ts
+createDataCatalogPlugin({
+  id: "metrics",
+  label: "Metrics",
+  adapter,
+  includeLeftTab: true,
+  includeVisualizationPanel: false,
+  includeCatalog: false,
+  includeSurfaceResolver: false,
+})
+```
+
+---
+
+## Configuration
+
+```ts
+interface CreateDataCatalogPluginOptions {
+  pluginId?: string
+  id: string
+  label: string
+  adapter: ExplorerDataSource        // required — your data source
+  facets?: FacetConfig[]             // facet filter definitions
+  groupBy?: string                   // group key for the left tab rows
+  getDragPayload?: (row) => DragPayload | null
+  onSelect?: (row, context) => void  // custom row click handler
+  emptyState?: ReactNode
+  searchPlaceholder?: string
+  pageSize?: number
+  debounceMs?: number
+  leftTabId?: string
+  leftTabTitle?: string
+  leftTabIcon?: IconType
+  catalogId?: string
+  catalogLabel?: string
+  visualizationPanelId?: string
+  visualizationTitle?: string
+  visualizationIcon?: IconType
+  visualizationComponent?: ComponentType<PaneProps<DataCatalogVisualizationParams>>
+  includeLeftTab?: boolean           // default true
+  includeCatalog?: boolean           // default true
+  includeVisualizationPanel?: boolean // default true
+  includeSurfaceResolver?: boolean   // default true (if visualization panel on)
+  source?: "builtin" | "app"         // panel attribution
+}
+```
+
+---
+
+## Architecture
+
+```
+┌───────────────────────────────────────┐
+│   Workspace Left Sidebar             │
+│   ┌───────────────────────────────┐  │
+│   │ 📊 Customers (left tab)       │  │
+│   │ ┌───────────────────────────┐ │  │
+│   │ │ [Search: "acme..."]       │ │  │
+│   │ │ [Industry: Tech ▼]        │ │  │
+│   │ │ ───────────────────────── │ │  │
+│   │ │ US: Acme Corp      [T]  ✓ │ │  │
+│   │ │ EU: Acme GmbH      [T]    │ │  │
+│   │ │ APAC: Acme KK      [L]    │ │  │
+│   │ └─────────────────────────── │ │  │
+│   └───────────────────────────────┘  │
+└───────────────┬───────────────────────┘
+                │ click row → open panel
+                ▼
+┌───────────────────────────────────────┐
+│   Center Panel (visualization)        │
+│   ┌───────────────────────────────┐  │
+│   │ Acme Corp                     │  │
+│   │ US: Acme Corp [T]            │  │
+│   │ ┌───────────────────────────┐│  │
+│   │ │ [Search...]               ││  │
+│   │ │ [filtered by row context] ││  │
+│   │ │ ...explorer table...      ││  │
+│   │ └───────────────────────────┘│  │
+│   └───────────────────────────────┘  │
+└───────────────────────────────────────┘
+```
+
+The agent can open any row programmatically:
+```
+POST /api/v1/ui/commands
+{ kind: "openSurface", params: {
+  surfaceKind: "data-catalog-row",
+  target: <row.id>,
+  meta: { catalogId: "customers", row: { title: "Acme Corp", ... } }
+}}
+```
+
+---
+
+## Installation
+
+```bash
+# From source (workspace-only — not published to npm)
+cd boring-ui/plugins/data-catalog && pnpm install && pnpm build
+```
+
+---
+
+## How @hachej/boring-data-catalog Compares
+
+| Feature | @hachej/boring-data-catalog | Custom sidebar + table | Embedded BI tool |
+|---------|------------------------------|-----------------------|------------------|
+| Catalog tab + panel | ✅ One plugin call | ❌ DIY each piece | ⚠️ Configuration-heavy |
+| Agent tool + bridge | ✅ search + openSurface | ❌ DIY | ❌ |
+| Wiring effort | ✅ ~10 lines | ❌ Hours | ❌ Days |
+| Data source flexibility | ✅ Any backend via ExplorerDataSource | ⚠️ Custom per source | ⚠️ Vendor-defined |
+| Workbench integration | ✅ Drag-to-panel, exec_ui | ⚠️ Manual | ❌ None |
+| Customizable outputs | ✅ Toggle left-tab / panel / catalog / resolver | ❌ All or nothing | ❌ |
+
+**When to use @hachej/boring-data-catalog:**
+- You want a sidebar catalog tab that lets users browse your data
+- You want the agent to search and open specific rows in panels
+- You want a left-tab + visualization panel combo with minimal code
+
+**When it might not fit:**
+- You only need a standalone table (use `@hachej/boring-data-explorer` directly)
+- You want a full BI dashboard with charting (embed a dedicated BI tool)
+- You need real-time data streaming (not supported in v1)
+
+---
+
+## Package Surfaces
+
+| Import | Environment | What You Get |
+|--------|-------------|--------------|
+| `@hachej/boring-data-catalog/front` | Browser | `createDataCatalogPlugin()`, types, hooks, surface resolver |
+| `@hachej/boring-data-catalog/server` | Node | `createDataCatalogServerPlugin()` — agent tool + skill prompt |
+| `@hachej/boring-data-catalog/shared` | Any | `DATA_CATALOG_PLUGIN_ID`, `DATA_CATALOG_ROW_SURFACE_KIND`, constants |
+
+---
+
+## Dependencies
+
+| Package | Required | Why |
+|---------|----------|-----|
+| `@hachej/boring-data-explorer` | ✅ Yes | Core table component and `ExplorerDataSource` adapter |
+| `@hachej/boring-workspace` | ✅ peerDependency | Plugin system and panel registry |
+| `lucide-react` | ✅ Yes | Catalog icons (Database, BarChart3) |
+
+---
+
+## Troubleshooting
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| Catalog tab doesn't appear | Front plugin not in workspace | Add `createDataCatalogPlugin()` to `WorkspaceProvider` plugins |
+| Clicking a row does nothing | `adapter.search()` is broken or returns nothing | Test your adapter independently |
+| Agent tool not found | Server plugin not registered | Add `createDataCatalogServerPlugin()` to agent app `plugins` |
+| Agent can't open rows | Surface resolver disabled | Set `includeSurfaceResolver: true` (on by default) |
+| Icons not rendering | Invalid lucide icon name | Check `leftTabIcon` / `visualizationIcon` against [lucide.dev](https://lucide.dev/icons/) |
+
+---
+
+## Limitations
+
+- **Workspace-private** — `"private": true` in package.json. Not published to npm. Install from source within the monorepo.
+- **Single data source per plugin** — Each call to `createDataCatalogPlugin()` wires to one `ExplorerDataSource`. For multiple catalogs, instantiate the plugin multiple times with different adapters and labels.
+- **No charting or visualization** — The visualization panel shows another explorer table, not charts. For visualizations, provide a custom `visualizationComponent`.
+- **No server-side caching** — Each search triggers a fresh `search()` call. Cache at your adapter level if needed.
+- **Real-time data** — Not supported in v1. Search uses debounce and pagination but no live streaming.
+
+---
+
+## FAQ
+
+**Q: How do I use multiple data sources?**  
+A: Call `createDataCatalogPlugin()` once per data source, each with a different `id`, `label`, and `adapter`. For a static source list, implement a small `ExplorerDataSource` whose `search()` filters and slices an in-memory `ExplorerItem[]`.
+
+**Q: How does the agent open a specific row?**  
+A: The catalog registers a surface resolver. The agent uses the UI bridge `openSurface` command: `{ kind: DATA_CATALOG_ROW_SURFACE_KIND, target: row.id, meta: { catalogId, row } }`.
+
+**Q: Can I customize the visualization panel?**  
+A: Yes. Pass a custom `visualizationComponent` to `createDataCatalogPlugin()`. It receives `PaneProps<DataCatalogVisualizationParams>` with the selected row and context.
+
+**Q: What if my data source is a REST API, not a database?**  
+A: The `ExplorerDataSource` adapter is backend-agnostic. Implement `search()` (and optionally `fetchFacets()`) to hit your REST endpoint.
+
+**Q: Can I disable outputs I don't need?**  
+A: Yes. Set `includeLeftTab`, `includeVisualizationPanel`, `includeCatalog`, or `includeSurfaceResolver` to `false`. A left-tab-only plugin is a perfectly valid output.
+
+---
+
+*About Contributions:* Please don't take this the wrong way, but I do not accept outside contributions for any of my projects. I simply don't have the mental bandwidth to review anything, and it's my name on the thing, so I'm responsible for any problems it causes; thus, the risk-reward is highly asymmetric from my perspective. I'd also have to worry about other "stakeholders," which seems unwise for tools I mostly make for myself for free. Feel free to submit issues, and even PRs if you want to illustrate a proposed fix, but know I won't merge them directly. Instead, I'll have Claude or Codex review submissions via `gh` and independently decide whether and how to address them. Bug reports in particular are welcome. Sorry if this offends, but I want to avoid wasted time and hurt feelings. I understand this isn't in sync with the prevailing open-source ethos that seeks community contributions, but it's the only way I can move at this velocity and keep my sanity.
+
+---
+
+## License
+
+MIT

package/dist/front/index.d.ts

@@ -0,0 +1,105 @@
+import { BoringFrontSurfaceResolverRegistration, BoringFrontFactoryWithId } from '@hachej/boring-workspace/plugin';
+import { ReactNode, ComponentType } from 'react';
+import { ExplorerDataSource, FacetConfig, ExplorerItem, DragPayload } from '@hachej/boring-data-explorer/shared';
+import { LeftTabParams, WorkspaceBridge, PanelConfig, PaneProps } from '@hachej/boring-workspace';
+export { DATA_CATALOG_DEFAULT_TOOL_NAME, DATA_CATALOG_PLUGIN_ID, DATA_CATALOG_ROW_SURFACE_KIND } from '../shared/index.js';
+export { DataExplorerProps } from '@hachej/boring-data-explorer/front';
+
+interface DataCatalogVisualizationParams {
+    row?: ExplorerItem;
+    query?: string;
+}
+interface OpenDataCatalogVisualizationOptions {
+    catalogId: string;
+    surfaceKind?: string;
+    title?: string;
+    params?: Record<string, unknown>;
+}
+interface DataCatalogSelectContext {
+    params?: LeftTabParams;
+    bridge?: WorkspaceBridge;
+}
+interface CreateDataCatalogContributionsOptions {
+    /**
+     * Base contribution id. Defaults catalog id to this value and left tab /
+     * visualization panel ids to derived names.
+     */
+    id?: string;
+    label?: string;
+    adapter: ExplorerDataSource;
+    facets?: FacetConfig[];
+    groupBy?: string;
+    getDragPayload?: (row: ExplorerItem) => DragPayload | null | undefined;
+    onSelect?: (row: ExplorerItem, context: DataCatalogSelectContext) => void;
+    emptyState?: ReactNode;
+    searchPlaceholder?: string;
+    pageSize?: number;
+    debounceMs?: number;
+    leftTabId?: string;
+    leftTabTitle?: string;
+    leftTabIcon?: PanelConfig["icon"];
+    includeLeftTab?: boolean;
+    catalogId?: string;
+    catalogLabel?: string;
+    includeCatalog?: boolean;
+    visualizationPanelId?: string;
+    visualizationTitle?: string;
+    visualizationIcon?: PanelConfig["icon"];
+    visualizationComponent?: ComponentType<PaneProps<DataCatalogVisualizationParams>>;
+    includeVisualizationPanel?: boolean;
+    surfaceKind?: string;
+    surfaceResolverId?: string;
+    includeSurfaceResolver?: boolean;
+    source?: PanelConfig["source"];
+}
+interface CreateDataCatalogPluginOptions extends CreateDataCatalogContributionsOptions {
+    pluginId?: string;
+}
+interface DataCatalogResolvedQuery {
+    query?: string;
+    controlled: boolean;
+}
+interface DataCatalogVisualizationState extends DataCatalogResolvedQuery {
+    row?: ExplorerItem;
+    title: string;
+}
+
+declare function dataCatalogPanelInstanceId(rowId: string, prefix?: string): string;
+declare function openDataCatalogVisualization(row: ExplorerItem, options: OpenDataCatalogVisualizationOptions): void;
+declare function createDataCatalogOpenHandler(options: OpenDataCatalogVisualizationOptions): (row: ExplorerItem) => void;
+
+interface CreateDataCatalogSurfaceResolverOptions {
+    id: string;
+    catalogId: string;
+    visualizationPanelId: string;
+    visualizationTitle: string;
+    panelIdPrefix?: string;
+    surfaceKind?: string;
+    surfaceResolverId?: string;
+    source?: string;
+}
+declare function createDataCatalogSurfaceResolver(options: CreateDataCatalogSurfaceResolverOptions): BoringFrontSurfaceResolverRegistration;
+
+declare function readDataCatalogRow(value: unknown): ExplorerItem | undefined;
+declare function resolveDataCatalogQuery(params: LeftTabParams | DataCatalogVisualizationParams | undefined): string | undefined;
+declare function resolveDataCatalogControlledQuery(params: LeftTabParams | DataCatalogVisualizationParams | undefined): DataCatalogResolvedQuery;
+declare function resolveDataCatalogVisualizationState(params: DataCatalogVisualizationParams | undefined, fallbackTitle: string): DataCatalogVisualizationState;
+declare function useDataCatalogQuery(params: LeftTabParams | DataCatalogVisualizationParams | undefined): DataCatalogResolvedQuery;
+declare function useDataCatalogVisualizationState(params: DataCatalogVisualizationParams | undefined, fallbackTitle: string): DataCatalogVisualizationState;
+declare function useDataCatalogOpenVisualization(options: OpenDataCatalogVisualizationOptions): (row: ExplorerItem) => void;
+
+/**
+ * Builds a `BoringFrontFactoryWithId` for the data-catalog plugin.
+ * The factory captures `options` in a closure and registers the
+ * configured left tab, visualization panel, catalog entry, and
+ * surface resolver imperatively when the workspace calls it.
+ *
+ * Each contribution is opt-out via the `include*` flags so host apps
+ * can compose a subset (e.g. catalog-only without a visualization
+ * panel). The returned factory carries its `pluginId` + `pluginLabel`
+ * so it can be passed directly to `WorkspaceProvider.plugins` (the
+ * shell captures via the front factory API).
+ */
+declare function createDataCatalogPlugin(options: CreateDataCatalogPluginOptions): BoringFrontFactoryWithId;
+
+export { type CreateDataCatalogPluginOptions, type CreateDataCatalogSurfaceResolverOptions, type DataCatalogResolvedQuery, type DataCatalogSelectContext, type DataCatalogVisualizationParams, type DataCatalogVisualizationState, type OpenDataCatalogVisualizationOptions, createDataCatalogOpenHandler, createDataCatalogPlugin, createDataCatalogSurfaceResolver, dataCatalogPanelInstanceId, openDataCatalogVisualization, readDataCatalogRow, resolveDataCatalogControlledQuery, resolveDataCatalogQuery, resolveDataCatalogVisualizationState, useDataCatalogOpenVisualization, useDataCatalogQuery, useDataCatalogVisualizationState };

package/dist/front/index.js

@@ -0,0 +1,294 @@
+"use client";
+
+// src/front/index.tsx
+import { BarChart3, Database } from "lucide-react";
+import { PanelChrome } from "@hachej/boring-workspace";
+import {
+  definePlugin
+} from "@hachej/boring-workspace/plugin";
+import { DataExplorer } from "@hachej/boring-data-explorer/front";
+
+// src/shared/constants.ts
+var DATA_CATALOG_PLUGIN_ID = "data-catalog";
+var DATA_CATALOG_DEFAULT_TOOL_NAME = "query_data_catalog";
+var DATA_CATALOG_ROW_SURFACE_KIND = "data-catalog.open-row";
+
+// src/front/openVisualization.ts
+import { postUiCommand } from "@hachej/boring-workspace";
+function stableHash(input) {
+  let hash = 2166136261;
+  for (let i = 0; i < input.length; i++) {
+    hash ^= input.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(36);
+}
+function slugForPanelId(input) {
+  const slug = input.trim().replace(/[^a-zA-Z0-9_-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 32);
+  return slug || "row";
+}
+function dataCatalogPanelInstanceId(rowId, prefix = "data") {
+  const hash = stableHash(rowId);
+  const slug = slugForPanelId(rowId);
+  const safePrefix = slugForPanelId(prefix);
+  const suffix = `${slug}-${hash}`;
+  const prefixBudget = Math.max(0, 64 - suffix.length - 1);
+  const trimmedPrefix = safePrefix.slice(0, prefixBudget);
+  return trimmedPrefix ? `${trimmedPrefix}-${suffix}` : suffix.slice(0, 64);
+}
+function openDataCatalogVisualization(row, options) {
+  const meta = {
+    ...options.params ?? {},
+    // Keep routing keys authoritative even when callers pass extra params.
+    row,
+    catalogId: options.catalogId,
+    ...options.title ? { title: options.title } : {}
+  };
+  postUiCommand({
+    kind: "openSurface",
+    params: {
+      kind: options.surfaceKind ?? DATA_CATALOG_ROW_SURFACE_KIND,
+      target: row.id,
+      meta
+    }
+  });
+}
+function createDataCatalogOpenHandler(options) {
+  return (row) => openDataCatalogVisualization(row, options);
+}
+
+// src/front/surfaceResolver.ts
+function isExplorerItem(value) {
+  if (!value || typeof value !== "object") return false;
+  const row = value;
+  return typeof row.id === "string" && typeof row.title === "string";
+}
+function stringMeta(meta, key) {
+  const value = meta[key];
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function createDataCatalogSurfaceResolver(options) {
+  const kind = options.surfaceKind ?? DATA_CATALOG_ROW_SURFACE_KIND;
+  const panelIdPrefix = options.panelIdPrefix ?? options.id;
+  return {
+    id: options.surfaceResolverId ?? `${options.id}-row`,
+    kind,
+    source: options.source,
+    resolve(request) {
+      if (request.kind !== kind) return void 0;
+      const meta = request.meta ?? {};
+      const catalogId = stringMeta(meta, "catalogId");
+      if (catalogId && catalogId !== options.catalogId) return void 0;
+      const row = isExplorerItem(meta.row) ? meta.row : void 0;
+      const {
+        catalogId: _catalogId,
+        row: _row,
+        title: _title,
+        ...extraParams
+      } = meta;
+      return {
+        id: dataCatalogPanelInstanceId(request.target, panelIdPrefix),
+        component: options.visualizationPanelId,
+        title: stringMeta(meta, "title") ?? row?.title ?? options.visualizationTitle,
+        params: {
+          ...extraParams,
+          ...row ? { row } : { query: request.target }
+        },
+        score: 0
+      };
+    }
+  };
+}
+
+// src/front/hooks.ts
+import { useCallback, useMemo } from "react";
+function readDataCatalogRow(value) {
+  if (!value || typeof value !== "object") return void 0;
+  const row = value;
+  if (typeof row.id !== "string" || typeof row.title !== "string") return void 0;
+  return row;
+}
+function resolveDataCatalogQuery(params) {
+  if (!params) return void 0;
+  if ("searchQuery" in params && typeof params.searchQuery === "string") {
+    return params.searchQuery;
+  }
+  if ("query" in params && typeof params.query === "string") return params.query;
+  return void 0;
+}
+function resolveDataCatalogControlledQuery(params) {
+  const query = resolveDataCatalogQuery(params);
+  return { query, controlled: query !== void 0 };
+}
+function resolveDataCatalogVisualizationState(params, fallbackTitle) {
+  const row = readDataCatalogRow(params?.row);
+  const query = resolveDataCatalogQuery(params) ?? row?.id;
+  return {
+    row,
+    query,
+    controlled: query !== void 0,
+    title: row?.title ?? fallbackTitle
+  };
+}
+function useDataCatalogQuery(params) {
+  return useMemo(() => resolveDataCatalogControlledQuery(params), [params]);
+}
+function useDataCatalogVisualizationState(params, fallbackTitle) {
+  return useMemo(
+    () => resolveDataCatalogVisualizationState(params, fallbackTitle),
+    [fallbackTitle, params]
+  );
+}
+function useDataCatalogOpenVisualization(options) {
+  const { catalogId, surfaceKind, title, params } = options;
+  return useCallback(
+    (row) => openDataCatalogVisualization(row, { catalogId, surfaceKind, title, params }),
+    [catalogId, surfaceKind, title, params]
+  );
+}
+
+// src/front/index.tsx
+import { jsx, jsxs } from "react/jsx-runtime";
+function createDataCatalogPlugin(options) {
+  const id = options.id ?? DATA_CATALOG_PLUGIN_ID;
+  const label = options.label ?? "Data";
+  const catalogId = options.catalogId ?? id;
+  const catalogLabel = options.catalogLabel ?? label;
+  const leftTabId = options.leftTabId ?? `${id}-tab`;
+  const leftTabTitle = options.leftTabTitle ?? label;
+  const visualizationPanelId = options.visualizationPanelId ?? `${id}-visualization`;
+  const visualizationTitle = options.visualizationTitle ?? `${label} View`;
+  const surfaceKind = options.surfaceKind ?? DATA_CATALOG_ROW_SURFACE_KIND;
+  const source = options.source ?? "app";
+  const includeVisualizationPanel = options.includeVisualizationPanel ?? true;
+  const includeLeftTab = options.includeLeftTab ?? true;
+  const includeCatalog = options.includeCatalog ?? true;
+  const includeSurfaceResolver = options.includeSurfaceResolver ?? (includeVisualizationPanel && !options.onSelect);
+  const emptyState = options.emptyState ?? "No data found";
+  const searchPlaceholder = options.searchPlaceholder ?? `Search ${label.toLowerCase()}...`;
+  const onSelect = options.onSelect ?? (includeVisualizationPanel ? createDataCatalogOpenHandler({ catalogId, surfaceKind }) : () => {
+  });
+  function DataCatalogLeftTab({ params, className }) {
+    const { query, controlled } = useDataCatalogQuery(params);
+    const bridge = params?.bridge;
+    const handleSelect = (row) => onSelect(row, { params, bridge });
+    return /* @__PURE__ */ jsx(
+      DataExplorer,
+      {
+        adapter: options.adapter,
+        facets: options.facets,
+        groupBy: options.groupBy,
+        onActivate: handleSelect,
+        getDragPayload: options.getDragPayload,
+        emptyState,
+        searchPlaceholder,
+        query: controlled ? query : void 0,
+        searchable: !controlled,
+        pageSize: options.pageSize,
+        debounceMs: options.debounceMs,
+        className: className ?? "h-full"
+      }
+    );
+  }
+  function DefaultVisualizationPanel({
+    params,
+    api: panelApi,
+    className
+  }) {
+    const { row, query, controlled, title } = useDataCatalogVisualizationState(
+      params,
+      visualizationTitle
+    );
+    const handleSelect = (nextRow) => onSelect(nextRow, { params });
+    return /* @__PURE__ */ jsxs(
+      PanelChrome,
+      {
+        title,
+        icon: options.visualizationIcon ?? BarChart3,
+        panelApi,
+        className,
+        children: [
+          row ? /* @__PURE__ */ jsxs("div", { className: "border-b border-border/60 px-3 py-2", children: [
+            /* @__PURE__ */ jsx("div", { className: "truncate text-sm font-medium text-foreground", children: row.title }),
+            /* @__PURE__ */ jsx("div", { className: "truncate text-xs text-muted-foreground", children: row.subtitle ?? row.id })
+          ] }) : null,
+          /* @__PURE__ */ jsx(
+            DataExplorer,
+            {
+              adapter: options.adapter,
+              facets: options.facets,
+              groupBy: options.groupBy,
+              onActivate: handleSelect,
+              getDragPayload: options.getDragPayload,
+              emptyState,
+              searchPlaceholder,
+              query: controlled ? query : void 0,
+              searchable: !controlled,
+              pageSize: options.pageSize,
+              debounceMs: options.debounceMs,
+              className: "h-full"
+            }
+          )
+        ]
+      }
+    );
+  }
+  const leftTab = includeLeftTab ? {
+    id: leftTabId,
+    title: leftTabTitle,
+    icon: options.leftTabIcon ?? Database,
+    component: DataCatalogLeftTab,
+    source,
+    chromeless: true,
+    panelId: leftTabId
+  } : void 0;
+  const visualizationPanel = includeVisualizationPanel ? {
+    id: visualizationPanelId,
+    label: visualizationTitle,
+    icon: options.visualizationIcon ?? BarChart3,
+    component: options.visualizationComponent ?? DefaultVisualizationPanel,
+    placement: "center",
+    source
+  } : void 0;
+  const catalog = includeCatalog ? {
+    id: catalogId,
+    label: catalogLabel,
+    adapter: options.adapter,
+    onSelect: (row) => onSelect(row, {})
+  } : void 0;
+  const resolver = includeSurfaceResolver ? createDataCatalogSurfaceResolver({
+    id,
+    catalogId,
+    visualizationPanelId,
+    visualizationTitle,
+    panelIdPrefix: id,
+    surfaceKind,
+    surfaceResolverId: options.surfaceResolverId,
+    source
+  }) : void 0;
+  return definePlugin({
+    id,
+    label,
+    leftTabs: leftTab ? [leftTab] : [],
+    panels: visualizationPanel ? [visualizationPanel] : [],
+    catalogs: catalog ? [catalog] : [],
+    surfaceResolvers: resolver ? [resolver] : []
+  });
+}
+export {
+  DATA_CATALOG_DEFAULT_TOOL_NAME,
+  DATA_CATALOG_PLUGIN_ID,
+  DATA_CATALOG_ROW_SURFACE_KIND,
+  createDataCatalogOpenHandler,
+  createDataCatalogPlugin,
+  createDataCatalogSurfaceResolver,
+  dataCatalogPanelInstanceId,
+  openDataCatalogVisualization,
+  readDataCatalogRow,
+  resolveDataCatalogControlledQuery,
+  resolveDataCatalogQuery,
+  resolveDataCatalogVisualizationState,
+  useDataCatalogOpenVisualization,
+  useDataCatalogQuery,
+  useDataCatalogVisualizationState
+};

package/dist/server/index.d.ts

@@ -0,0 +1,29 @@
+import { ExplorerDataSource, SearchResult } from '@hachej/boring-data-explorer/shared';
+import { WorkspaceServerPlugin } from '@hachej/boring-workspace/server';
+import { AgentTool } from '@hachej/boring-workspace';
+
+interface DataCatalogAgentToolOptions {
+    name?: string;
+    label?: string;
+    adapter: ExplorerDataSource;
+    defaultLimit?: number;
+    maxLimit?: number;
+}
+interface DataCatalogSkillOptions {
+    label?: string;
+    toolName?: string;
+    surfaceKind?: string;
+    guidance?: string;
+}
+interface DataCatalogServerPluginOptions extends DataCatalogAgentToolOptions, DataCatalogSkillOptions {
+    id?: string;
+}
+declare function formatDataCatalogSearchResult(query: string, result: SearchResult): string;
+declare function createDataCatalogAgentTool(options: DataCatalogAgentToolOptions): AgentTool;
+declare function createDataCatalogSkillPrompt(options?: DataCatalogSkillOptions): string;
+declare function createDataCatalogServerPlugin(options: DataCatalogServerPluginOptions): WorkspaceServerPlugin & {
+    agentTools: AgentTool[];
+    systemPrompt: string;
+};
+
+export { type DataCatalogAgentToolOptions, type DataCatalogServerPluginOptions, type DataCatalogSkillOptions, createDataCatalogAgentTool, createDataCatalogServerPlugin, createDataCatalogSkillPrompt, formatDataCatalogSearchResult };

package/dist/server/index.js

@@ -0,0 +1,127 @@
+// src/server/index.ts
+import {
+  defineServerPlugin
+} from "@hachej/boring-workspace/server";
+
+// src/shared/constants.ts
+var DATA_CATALOG_PLUGIN_ID = "data-catalog";
+var DATA_CATALOG_DEFAULT_TOOL_NAME = "query_data_catalog";
+var DATA_CATALOG_ROW_SURFACE_KIND = "data-catalog.open-row";
+
+// src/server/index.ts
+function textResult(text, details) {
+  return { content: [{ type: "text", text }], details };
+}
+function errorResult(text) {
+  return { content: [{ type: "text", text }], isError: true };
+}
+function clampLimit(value, fallback, max) {
+  const numeric = typeof value === "number" ? value : typeof value === "string" ? Number(value) : NaN;
+  if (!Number.isFinite(numeric)) return fallback;
+  return Math.max(1, Math.min(max, Math.floor(numeric)));
+}
+function normalizeLimitOptions(options) {
+  const rawMax = options.maxLimit ?? 50;
+  const maxLimit = typeof rawMax === "number" && Number.isFinite(rawMax) ? Math.max(1, Math.floor(rawMax)) : 50;
+  const rawDefault = options.defaultLimit ?? 20;
+  const defaultLimit = typeof rawDefault === "number" && Number.isFinite(rawDefault) ? Math.max(1, Math.min(maxLimit, Math.floor(rawDefault))) : Math.min(20, maxLimit);
+  return { defaultLimit, maxLimit };
+}
+function formatBadge(row) {
+  const parts = [
+    row.leading?.code,
+    ...(row.trailing ?? []).map((badge) => badge.code),
+    row.meta
+  ].filter(Boolean);
+  return parts.length > 0 ? ` [${parts.join(", ")}]` : "";
+}
+function formatDataCatalogSearchResult(query, result) {
+  if (result.items.length === 0) {
+    return `No ${query ? `results for "${query}"` : "catalog results"}.`;
+  }
+  const lines = result.items.map((row) => {
+    const subtitle = row.subtitle ? ` \u2014 ${row.subtitle}` : "";
+    return `${row.id}: ${row.title}${subtitle}${formatBadge(row)}`;
+  });
+  const total = Number.isFinite(result.total) ? result.total : result.items.length;
+  return `Found ${total} results (showing ${result.items.length}):
+
+${lines.join("\n")}`;
+}
+function createDataCatalogAgentTool(options) {
+  const name = options.name ?? DATA_CATALOG_DEFAULT_TOOL_NAME;
+  const label = options.label ?? "data catalog";
+  const { defaultLimit, maxLimit } = normalizeLimitOptions(options);
+  return {
+    name,
+    description: `Search the ${label}. Use this before opening data visualizations or asking for a specific dataset.`,
+    parameters: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: "Search keywords for datasets, series, tables, or metrics."
+        },
+        limit: {
+          type: "number",
+          description: `Maximum number of results. Default ${defaultLimit}, max ${maxLimit}.`,
+          minimum: 1,
+          maximum: maxLimit
+        }
+      },
+      required: ["query"],
+      additionalProperties: false
+    },
+    async execute(params, ctx) {
+      const query = String(params.query ?? "").trim();
+      if (!query) return errorResult("query is required");
+      const limit = clampLimit(params.limit, defaultLimit, maxLimit);
+      try {
+        const result = await options.adapter.search({
+          query,
+          filters: {},
+          limit,
+          offset: 0,
+          signal: ctx.abortSignal
+        });
+        return textResult(formatDataCatalogSearchResult(query, result), result);
+      } catch (error) {
+        return errorResult(error instanceof Error ? error.message : String(error));
+      }
+    }
+  };
+}
+function createDataCatalogSkillPrompt(options = {}) {
+  const label = options.label ?? "data catalog";
+  const toolName = options.toolName ?? DATA_CATALOG_DEFAULT_TOOL_NAME;
+  const surfaceKind = options.surfaceKind ?? DATA_CATALOG_ROW_SURFACE_KIND;
+  const guidance = options.guidance?.trim();
+  return [
+    "## Data Catalog Plugin",
+    "",
+    `Use \`${toolName}\` to search the ${label} before referencing datasets, series, tables, or metrics.`,
+    `When you need to show a catalog row to the user, use the workspace UI bridge \`openSurface\` command with \`{ kind: '${surfaceKind}', target: row.id, meta: { catalogId, row } }\` so the client plugin resolver chooses the panel.`,
+    guidance ? "" : void 0,
+    guidance || void 0
+  ].filter((line) => line !== void 0).join("\n");
+}
+function createDataCatalogServerPlugin(options) {
+  const tool = createDataCatalogAgentTool(options);
+  return defineServerPlugin({
+    id: options.id ?? DATA_CATALOG_PLUGIN_ID,
+    label: options.label ?? "Data Catalog",
+    agentTools: [tool],
+    systemPrompt: createDataCatalogSkillPrompt({
+      label: options.label,
+      toolName: tool.name,
+      surfaceKind: options.surfaceKind,
+      guidance: options.guidance
+    })
+  });
+}
+export {
+  createDataCatalogAgentTool,
+  createDataCatalogServerPlugin,
+  createDataCatalogSkillPrompt,
+  formatDataCatalogSearchResult
+};

package/dist/shared/index.d.ts

@@ -0,0 +1,5 @@
+declare const DATA_CATALOG_PLUGIN_ID = "data-catalog";
+declare const DATA_CATALOG_DEFAULT_TOOL_NAME = "query_data_catalog";
+declare const DATA_CATALOG_ROW_SURFACE_KIND = "data-catalog.open-row";
+
+export { DATA_CATALOG_DEFAULT_TOOL_NAME, DATA_CATALOG_PLUGIN_ID, DATA_CATALOG_ROW_SURFACE_KIND };

package/dist/shared/index.js

@@ -0,0 +1,9 @@
+// src/shared/constants.ts
+var DATA_CATALOG_PLUGIN_ID = "data-catalog";
+var DATA_CATALOG_DEFAULT_TOOL_NAME = "query_data_catalog";
+var DATA_CATALOG_ROW_SURFACE_KIND = "data-catalog.open-row";
+export {
+  DATA_CATALOG_DEFAULT_TOOL_NAME,
+  DATA_CATALOG_PLUGIN_ID,
+  DATA_CATALOG_ROW_SURFACE_KIND
+};

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@hachej/boring-data-catalog",
+  "version": "0.1.13",
+  "type": "module",
+  "private": false,
+  "license": "MIT",
+  "description": "Plugin BUILDER for Boring workspace data catalogs. Consumers call `createDataCatalogPlugin(options)` to bind their own adapter/facets and get a configured BoringFrontFactoryWithId. NOT a direct `defaultPluginPackages` entry (no default export, options required) \u2014 wrap in an app-local plugin module that default-exports the built factory, then list that wrapper in `defaultPluginPackages`.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hachej/boring-ui"
+  },
+  "homepage": "https://github.com/hachej/boring-ui",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/front/index.d.ts",
+      "import": "./dist/front/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,
+  "scripts": {
+    "build": "pnpm --filter @hachej/boring-data-explorer build && pnpm --filter @hachej/boring-workspace build && tsup",
+    "typecheck": "pnpm --filter @hachej/boring-data-explorer build && pnpm --filter @hachej/boring-workspace build && tsc --noEmit",
+    "test": "pnpm --filter @hachej/boring-data-explorer build && pnpm --filter @hachej/boring-workspace build && vitest run --passWithNoTests",
+    "lint": "pnpm run typecheck",
+    "clean": "rm -rf dist .tsbuildinfo"
+  },
+  "peerDependencies": {
+    "@hachej/boring-workspace": "workspace:*",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "dependencies": {
+    "@hachej/boring-data-explorer": "workspace:*",
+    "lucide-react": "^1.8.0"
+  },
+  "devDependencies": {
+    "@hachej/boring-workspace": "workspace:*",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^22.15.3",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^4.0.0",
+    "jsdom": "^29.0.2",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^2.0.0"
+  }
+}