@nbt-dev/components 0.0.5

package/src/core/config.tsx

@@ -0,0 +1,39 @@
+import React from "react";
+
+// Runtime config for the devtools, replacing the inspector's compile-time
+// `NIMBIT_API_ENDPOINT` define. Hosts pass the console's base URL once via
+// <NimbitDevTools apiBaseUrl="…" /> and every fetch/WebSocket derives from it.
+// Empty string => same-origin (the inspector default when served by the console).
+export type DevToolsConfig = {
+  apiBaseUrl: string;
+};
+
+const DevToolsConfigContext = React.createContext<DevToolsConfig>({
+  apiBaseUrl: "",
+});
+
+export const DevToolsConfigProvider: React.FC<{
+  apiBaseUrl?: string;
+  children: React.ReactNode;
+}> = ({ apiBaseUrl = "", children }) => {
+  const value = React.useMemo(() => ({ apiBaseUrl }), [apiBaseUrl]);
+  return (
+    <DevToolsConfigContext.Provider value={value}>
+      {children}
+    </DevToolsConfigContext.Provider>
+  );
+};
+
+export function useDevToolsConfig(): DevToolsConfig {
+  return React.useContext(DevToolsConfigContext);
+}
+
+// Turn an http(s) base into a ws(s) base. Empty => derive from window.location.
+export function wsBaseFrom(apiBaseUrl: string): string {
+  if (!apiBaseUrl) {
+    const loc = window.location;
+    const proto = loc.protocol === "https:" ? "wss:" : "ws:";
+    return `${proto}//${loc.host}`;
+  }
+  return apiBaseUrl.replace(/^http(s?):/, "ws$1:");
+}

package/src/core/data-store.ts

@@ -0,0 +1,113 @@
+import {
+  FRAME_DELTA_INS,
+  FRAME_DELTA_UPD,
+  FRAME_DELTA_DEL,
+  type ColumnDef,
+  type SchemaFrame,
+  type DeltaFrame,
+} from "../generated/bulk-protocol";
+
+export class BulkDataStore {
+  columns: ColumnDef[] = [];
+  rows: string[][] = [];
+  totalRows = 0;
+  searchActive = false;
+
+  private _fullRows: string[][] = [];
+  private _fullTotalRows = 0;
+  private _idColIndex = -1;
+  private _query = "";
+
+  applySchema(schema: SchemaFrame): void {
+    this.columns = schema.columns;
+    this.totalRows = schema.totalRows;
+    this.rows = [];
+    this._fullRows = [];
+    this._fullTotalRows = schema.totalRows;
+    this.searchActive = false;
+    this._query = "";
+    this._idColIndex = schema.columns.findIndex((c) => c.name === "id");
+  }
+
+  appendChunk(chunk: string[][]): void {
+    for (let i = 0; i < chunk.length; i++) {
+      const row = chunk[i]!;
+      this._fullRows.push(row);
+      if (!this.searchActive) this.rows.push(row);
+    }
+  }
+
+  applyDelta(delta: DeltaFrame): void {
+    const target = this._fullRows;
+    if (delta.op === FRAME_DELTA_INS && delta.rowData) {
+      target.push(delta.rowData);
+      this._fullTotalRows++;
+      this.totalRows++;
+      if (!this.searchActive) this.rows = this._fullRows;
+      else this._applySearch();
+      return;
+    }
+    if (delta.op === FRAME_DELTA_UPD && delta.rowData) {
+      const idx = this._findRowById(target, delta.rowData);
+      if (idx >= 0) target[idx] = delta.rowData;
+      if (this.searchActive) this._applySearch();
+      return;
+    }
+    if (delta.op === FRAME_DELTA_DEL && delta.id !== undefined) {
+      const idStr = String(delta.id);
+      const idx = this._findRowByIdStr(target, idStr);
+      if (idx >= 0) {
+        target.splice(idx, 1);
+        this._fullTotalRows--;
+        this.totalRows--;
+        if (!this.searchActive) this.rows = this._fullRows;
+        else this._applySearch();
+      }
+      return;
+    }
+  }
+
+  search(query: string): void {
+    const q = query.trim().toLowerCase();
+    if (!q) { this.exitSearch(); return; }
+    this.searchActive = true;
+    this._query = q;
+    this._applySearch();
+  }
+
+  exitSearch(): void {
+    if (!this.searchActive) return;
+    this.rows = this._fullRows;
+    this.totalRows = this._fullTotalRows;
+    this.searchActive = false;
+    this._query = "";
+  }
+
+  getRowCount(): number {
+    return this.rows.length;
+  }
+
+  private _findRowById(rows: string[][], rowData: string[]): number {
+    if (this._idColIndex < 0) return -1;
+    const id = rowData[this._idColIndex];
+    for (let i = 0; i < rows.length; i++) {
+      if (rows[i]![this._idColIndex] === id) return i;
+    }
+    return -1;
+  }
+
+  private _findRowByIdStr(rows: string[][], idStr: string): number {
+    if (this._idColIndex < 0) return -1;
+    for (let i = 0; i < rows.length; i++) {
+      if (rows[i]![this._idColIndex] === idStr) return i;
+    }
+    return -1;
+  }
+
+  private _applySearch(): void {
+    this.rows = this._fullRows.filter((row) =>
+      row.some((value) => value.toLowerCase().includes(this._query)),
+    );
+    this.totalRows = this.rows.length;
+  }
+}

package/src/core/index.ts

@@ -0,0 +1,34 @@
+// Shared runtime every primitive leans on: the console-base-URL config context,
+// the one bulk-WS provider that table + graph demux off, the live cartridge
+// registry, and the tailwind `cn` helper. Standalone apps compose:
+//   <DevToolsConfigProvider apiBaseUrl={...}><BulkStreamProvider registry={...}>
+export {
+  DevToolsConfigProvider,
+  useDevToolsConfig,
+  wsBaseFrom,
+} from "./config";
+export type { DevToolsConfig } from "./config";
+export { cn } from "./utils";
+export {
+  BulkStreamProvider,
+  useBulkSubscription,
+  useBulkRowCounts,
+} from "./use-bulk-stream";
+export type { BulkSubscription } from "./use-bulk-stream";
+export { useLiveBulkRegistry } from "./use-cartridge-info";
+export type {
+  BulkEntity,
+  BulkRegistry,
+  LiveRegistryState,
+} from "./use-cartridge-info";
+export {
+  getDevToolsToken,
+  setDevToolsToken,
+  clearDevToolsToken,
+  authHeaders,
+  fetchWhoAmI,
+  devToolsSignIn,
+  devToolsSignOut,
+  wsAuthProtocols,
+} from "./auth";
+export type { WhoAmI } from "./auth";

package/src/core/use-bulk-stream.ts

@@ -0,0 +1,412 @@
+import React, {
+  createContext,
+  useContext,
+  useEffect,
+  useRef,
+  useState,
+} from "react";
+import { BulkDataStore } from "./data-store";
+import {
+  getFrameType,
+  getFrameSid,
+  parseSchema,
+  parseDataChunk,
+  parseDelta,
+  parseError,
+  encodeStreamCmd,
+} from "./bulk-decoder";
+import {
+  FRAME_SCHEMA,
+  FRAME_DATA,
+  FRAME_DATA_END,
+  FRAME_DELTA_INS,
+  FRAME_DELTA_UPD,
+  FRAME_DELTA_DEL,
+  FRAME_ERROR,
+  type ColumnDef,
+} from "../generated/bulk-protocol";
+import type { BulkRegistry } from "./use-cartridge-info";
+import { useDevToolsConfig, wsBaseFrom } from "./config";
+import { getDevToolsToken } from "./auth";
+
+// One per-entity table view, demultiplexed off the shared socket by sid. The
+// object is stable across renders and mutated in place; consumers re-render via
+// the listener set (and the cheap per-chunk onRender for virtualization).
+type View = {
+  sid: number;
+  cart: string;
+  entity: string;
+  store: BulkDataStore;
+  columns: ColumnDef[];
+  totalRows: number;
+  loadedRows: number;
+  streaming: boolean;
+  error: string | null;
+  streamRequested: boolean; // sent a `sub` (full stream) at least once
+  onRender: (() => void) | null;
+  listeners: Set<() => void>;
+};
+
+export type BulkSubscription = {
+  store: BulkDataStore;
+  connected: boolean;
+  streaming: boolean;
+  error: string | null;
+  columns: ColumnDef[];
+  totalRows: number;
+  loadedRows: number;
+  search: (q: string) => void;
+  clearSearch: () => void;
+  setOnRender: (fn: (() => void) | null) => void;
+};
+
+type Ctx = {
+  getView: (cart: string, entity: string) => View;
+  ensureStreamed: (view: View) => void;
+  search: (view: View, query: string) => void;
+  clearSearch: (view: View) => void;
+  subscribe: (view: View, cb: () => void) => () => void;
+  connected: boolean;
+  error: string | null;
+};
+
+const BulkStreamContext = createContext<Ctx | null>(null);
+
+function base64UrlEncode(value: string): string {
+  if (typeof btoa === "function") {
+    return btoa(value).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+  }
+  throw new Error("No base64 encoder available for bulk WS auth");
+}
+
+function bulkAuthProtocols(token: string): string[] {
+  return ["nimbit-bulk", `auth-${base64UrlEncode(token)}`];
+}
+
+let _wsTokenCache: { apiBaseUrl: string; token: string; at: number } | null = null;
+const WS_TOKEN_TTL_MS = 60_000;
+
+// Resolve the session token to forward in the WS subprotocol. Prefer the
+// devtools-managed token (set by its own sign-in); otherwise fall back to the
+// host page's cookie session via auth.Session.current. Returns null when there
+// is neither — on an unconfigured/dev console the WS upgrade is open anyway, so
+// we still connect without an auth subprotocol.
+async function fetchWsToken(
+  signal: AbortSignal,
+  apiBaseUrl: string,
+): Promise<string | null> {
+  const own = getDevToolsToken();
+  if (own) return own;
+  const now = Date.now();
+  if (_wsTokenCache?.apiBaseUrl === apiBaseUrl && now - _wsTokenCache.at < WS_TOKEN_TTL_MS) {
+    return _wsTokenCache.token;
+  }
+  const r = await fetch(`${apiBaseUrl}/api/auth/session/current`, {
+    method: "POST",
+    signal,
+    credentials: "include",
+    headers: { "content-type": "application/json" },
+  });
+  if (!r.ok) return null;
+  const j = (await r.json()) as { session?: { token?: string } };
+  const token = j.session?.token;
+  if (!token) return null;
+  _wsTokenCache = { apiBaseUrl, token, at: now };
+  return token;
+}
+
+function invalidateWsToken() {
+  _wsTokenCache = null;
+}
+
+function notify(view: View) {
+  view.listeners.forEach((cb) => cb());
+}
+
+type Props = { registry: BulkRegistry; children: React.ReactNode };
+
+export function BulkStreamProvider({ registry, children }: Props): React.ReactElement {
+  const { apiBaseUrl } = useDevToolsConfig();
+  const wsRef = useRef<WebSocket | null>(null);
+  const sendQueueRef = useRef<string[]>([]);
+  const sidCounterRef = useRef(1);
+  const viewsBySidRef = useRef<Map<number, View>>(new Map());
+  const viewsByKeyRef = useRef<Map<string, View>>(new Map());
+  const preloadedRef = useRef(false);
+
+  const [connected, setConnected] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const sendCmd = (cmd: string) => {
+    const ws = wsRef.current;
+    if (ws && ws.readyState === WebSocket.OPEN) ws.send(cmd);
+    else sendQueueRef.current.push(cmd);
+  };
+
+  const flushQueue = () => {
+    const ws = wsRef.current;
+    if (!ws || ws.readyState !== WebSocket.OPEN) return;
+    const q = sendQueueRef.current;
+    sendQueueRef.current = [];
+    for (const cmd of q) ws.send(cmd);
+  };
+
+  const getView = (cart: string, entity: string): View => {
+    // The server registers entity ops under "<cart>/<entity-lower>" (route
+    // path casing), so normalize here — preload and subscription then share one
+    // view per entity regardless of the caller's casing.
+    const entLower = entity.toLowerCase();
+    const key = `${cart}/${entLower}`;
+    const existing = viewsByKeyRef.current.get(key);
+    if (existing) return existing;
+    const sid = sidCounterRef.current++;
+    const view: View = {
+      sid,
+      cart,
+      entity: entLower,
+      store: new BulkDataStore(),
+      columns: [],
+      totalRows: 0,
+      loadedRows: 0,
+      streaming: false,
+      error: null,
+      streamRequested: false,
+      onRender: null,
+      listeners: new Set(),
+    };
+    viewsByKeyRef.current.set(key, view);
+    viewsBySidRef.current.set(sid, view);
+    return view;
+  };
+
+  const ensureStreamed = (view: View) => {
+    if (view.streamRequested) return;
+    view.streamRequested = true;
+    sendCmd(encodeStreamCmd(view.sid, view.cart, view.entity));
+  };
+
+  const handleMessage = (ev: MessageEvent) => {
+    const buf = ev.data as ArrayBuffer;
+    const sid = getFrameSid(buf);
+    const view = viewsBySidRef.current.get(sid);
+    if (!view) return;
+    const ft = getFrameType(buf);
+    const store = view.store;
+    switch (ft) {
+      case FRAME_SCHEMA: {
+        const schema = parseSchema(buf);
+        store.applySchema(schema);
+        view.columns = schema.columns;
+        view.totalRows = schema.totalRows;
+        view.loadedRows = 0;
+        view.streaming = true;
+        notify(view);
+        break;
+      }
+      case FRAME_DATA:
+      {
+        const rows = parseDataChunk(buf, store.columns);
+        store.appendChunk(rows);
+        view.loadedRows = store.getRowCount();
+        view.onRender?.();
+        break;
+      }
+      case FRAME_DATA_END:
+        view.streaming = false;
+        notify(view);
+        break;
+      case FRAME_DELTA_INS:
+      case FRAME_DELTA_UPD:
+      case FRAME_DELTA_DEL: {
+        const delta = parseDelta(buf, store.columns);
+        store.applyDelta(delta);
+        view.totalRows = store.totalRows;
+        view.loadedRows = store.getRowCount();
+        view.onRender?.();
+        notify(view);
+        break;
+      }
+      case FRAME_ERROR:
+        view.error = parseError(buf);
+        view.streaming = false;
+        notify(view);
+        break;
+    }
+  };
+
+  // Open one shared socket for the provider's lifetime.
+  useEffect(() => {
+    const ac = new AbortController();
+    let cancelled = false;
+    let opened = false;
+    let ws: WebSocket | null = null;
+    sendQueueRef.current = [];
+    sidCounterRef.current = 1;
+    viewsBySidRef.current.clear();
+    viewsByKeyRef.current.clear();
+    preloadedRef.current = false;
+    setConnected(false);
+    setError(null);
+
+    (async () => {
+      let token: string | null = null;
+      try {
+        token = await fetchWsToken(ac.signal, apiBaseUrl);
+      } catch {
+        // Token lookup failed; still attempt the connection — an unconfigured
+        // dev console accepts it, a configured one will close it (handled below).
+      }
+      if (cancelled) return;
+      // With a token, authenticate via the subprotocol; without one, connect
+      // bare (dev/unconfigured consoles synthesize auth on their side).
+      ws = token
+        ? new WebSocket(`${wsBaseFrom(apiBaseUrl)}/_ws/bulk`, bulkAuthProtocols(token))
+        : new WebSocket(`${wsBaseFrom(apiBaseUrl)}/_ws/bulk`, ["nimbit-bulk"]);
+      ws.binaryType = "arraybuffer";
+      wsRef.current = ws;
+      ws.onopen = () => {
+        if (cancelled || wsRef.current !== ws) return;
+        opened = true;
+        setConnected(true);
+        setError(null);
+        flushQueue();
+      };
+      ws.onmessage = handleMessage;
+      ws.onerror = () => {};
+      ws.onclose = () => {
+        if (cancelled || wsRef.current !== ws) return;
+        setConnected(false);
+        wsRef.current = null;
+        if (!opened) {
+          invalidateWsToken();
+          setError("WebSocket connection closed");
+        }
+      };
+    })();
+
+    return () => {
+      cancelled = true;
+      ac.abort();
+      if (ws) {
+        ws.onopen = ws.onmessage = ws.onerror = ws.onclose = null;
+        try {
+          ws.close();
+        } catch {}
+        if (wsRef.current === ws) wsRef.current = null;
+      }
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [apiBaseUrl]);
+
+  // The live protocol exposes only sub/unsub. Subscribe every known entity once
+  // so schema, row counts, snapshots, and deltas stay available to all tabs.
+  useEffect(() => {
+    if (!connected) return;
+    if (preloadedRef.current) return;
+    const keys = Object.keys(registry);
+    if (keys.length === 0) return;
+    preloadedRef.current = true;
+    for (const cart of keys) {
+      for (const ent of registry[cart] ?? []) {
+        const view = getView(cart, ent.name);
+        ensureStreamed(view);
+      }
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [connected, registry]);
+
+  const search = (view: View, query: string) => {
+    view.store.search(query);
+    view.totalRows = view.store.totalRows;
+    view.loadedRows = view.store.getRowCount();
+    notify(view);
+    view.onRender?.();
+  };
+
+  const clearSearch = (view: View) => {
+    view.store.exitSearch();
+    view.totalRows = view.store.totalRows;
+    view.loadedRows = view.store.getRowCount();
+    notify(view);
+    view.onRender?.();
+  };
+
+  const subscribe = (view: View, cb: () => void) => {
+    view.listeners.add(cb);
+    return () => {
+      view.listeners.delete(cb);
+    };
+  };
+
+  const ctx: Ctx = {
+    getView,
+    ensureStreamed,
+    search,
+    clearSearch,
+    subscribe,
+    connected,
+    error,
+  };
+
+  return React.createElement(BulkStreamContext.Provider, { value: ctx }, children);
+}
+
+// Row counts for every entity in the registry, sourced from the SCHEMA preload
+// the provider already runs on connect (FRAME_SCHEMA carries totalRows). No row
+// streaming is triggered — we subscribe to each view but never ensureStreamed.
+// Keyed by the graph id `cart:Entity` (original casing) for the Diagram tab.
+export function useBulkRowCounts(registry: BulkRegistry): Record<string, number> {
+  const ctx = useContext(BulkStreamContext);
+  if (!ctx) throw new Error("useBulkRowCounts must be used within BulkStreamProvider");
+  const [, force] = useState(0);
+
+  const pairs: Array<{ id: string; view: View }> = [];
+  for (const cart of Object.keys(registry)) {
+    for (const ent of registry[cart] ?? []) {
+      pairs.push({ id: `${cart}:${ent.name}`, view: ctx.getView(cart, ent.name) });
+    }
+  }
+
+  const key = pairs.map((p) => p.id).join("|");
+  useEffect(() => {
+    const unsubs = pairs.map((p) => ctx.subscribe(p.view, () => force((n) => n + 1)));
+    return () => unsubs.forEach((u) => u());
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key]);
+
+  const counts: Record<string, number> = {};
+  for (const p of pairs) counts[p.id] = p.view.totalRows;
+  return counts;
+}
+
+// Keyed to a single entity. The view (schema + rows + deltas) is shared and
+// cached in the provider, so switching tabs is instant once visited.
+export function useBulkSubscription(cart: string, entity: string): BulkSubscription {
+  const ctx = useContext(BulkStreamContext);
+  if (!ctx) throw new Error("useBulkSubscription must be used within BulkStreamProvider");
+
+  const view = ctx.getView(cart, entity);
+  const [, force] = useState(0);
+
+  useEffect(() => {
+    const unsub = ctx.subscribe(view, () => force((n) => n + 1));
+    ctx.ensureStreamed(view);
+    return unsub;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [view]);
+
+  return {
+    store: view.store,
+    connected: ctx.connected,
+    streaming: view.streaming,
+    error: view.error ?? ctx.error,
+    columns: view.columns,
+    totalRows: view.totalRows,
+    loadedRows: view.loadedRows,
+    search: (q: string) => ctx.search(view, q),
+    clearSearch: () => ctx.clearSearch(view),
+    setOnRender: (fn) => {
+      view.onRender = fn;
+    },
+  };
+}

package/src/core/use-cartridge-info.ts

@@ -0,0 +1,100 @@
+import { useEffect, useState } from "react";
+import { useDevToolsConfig } from "./config";
+import { authHeaders } from "./auth";
+
+// Live cartridge/entity registry for the Data tab. Instead of the build-time
+// `BULK_REGISTRY` (every cart in the repo, generated by `nbt generate`), we
+// read the daemon's `/_console/contracts` — which only lists *running*
+// cartridges and carries each entity's `searchFields`. Bulk WS routes are
+// derived live (`/_ws/bulk/<cart>/<entity-lower>`) and fed straight into
+// useBulkStream. So the tab reflects what is actually installed right now.
+
+export type BulkEntity = {
+  name: string;
+  route: string;
+  searchFields: readonly string[];
+};
+export type BulkRegistry = Record<string, BulkEntity[]>;
+
+type Contract = {
+  cartridge?: string;
+  core?: boolean;
+  owns?: Record<string, { searchFields?: string[] }>;
+};
+
+function buildRegistry(contracts: Contract[]): { reg: BulkRegistry; core: Set<string> } {
+  const reg: BulkRegistry = {};
+  const core = new Set<string>();
+  for (const c of contracts) {
+    const cart = c.cartridge;
+    if (!cart || !c.owns) continue;
+    const entities: BulkEntity[] = [];
+    for (const [name, ent] of Object.entries(c.owns)) {
+      const sf = Array.isArray(ent?.searchFields) ? ent.searchFields : [];
+      entities.push({
+        name,
+        route: `/_ws/bulk/${cart}/${name.toLowerCase()}`,
+        searchFields: sf,
+      });
+    }
+    if (entities.length > 0) {
+      reg[cart] = entities;
+      if (c.core) core.add(cart);
+    }
+  }
+  return { reg, core };
+}
+
+export type LiveRegistryState = {
+  registry: BulkRegistry;
+  carts: string[];
+  // Cartridge slugs flagged `core` by the daemon. The Data tab keeps `auth`
+  // visible but tucks the rest of these behind a "more cartridges" menu so
+  // deployed (user) cartridges are what's shown by default.
+  coreCarts: Set<string>;
+  loading: boolean;
+  error: string | null;
+};
+
+export function useLiveBulkRegistry(): LiveRegistryState {
+  const { apiBaseUrl } = useDevToolsConfig();
+  const [registry, setRegistry] = useState<BulkRegistry>({});
+  const [coreCarts, setCoreCarts] = useState<Set<string>>(new Set());
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    const ac = new AbortController();
+    let cancelled = false;
+    setLoading(true);
+    setError(null);
+    (async () => {
+      try {
+        const r = await fetch(`${apiBaseUrl}/_console/contracts`, {
+          signal: ac.signal,
+          credentials: "include",
+          headers: authHeaders(),
+        });
+        if (!r.ok) throw new Error(`HTTP ${r.status}`);
+        const data = (await r.json()) as Contract[];
+        if (!Array.isArray(data)) throw new Error("malformed contracts response");
+        if (cancelled) return;
+        const { reg, core } = buildRegistry(data);
+        setRegistry(reg);
+        setCoreCarts(core);
+      } catch (e) {
+        if (cancelled || (e as { name?: string }).name === "AbortError") return;
+        setError(e instanceof Error ? e.message : String(e));
+      } finally {
+        if (!cancelled) setLoading(false);
+      }
+    })();
+    return () => {
+      cancelled = true;
+      ac.abort();
+    };
+  }, [apiBaseUrl]);
+
+  const carts = Object.keys(registry).sort();
+  return { registry, carts, coreCarts, loading, error };
+}

package/src/core/utils.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}