@nbt-dev/devtools 0.0.1

package/README.md

@@ -0,0 +1,73 @@
+# @nbt-dev/devtools
+
+A drop-in React devtools panel for any frontend backed by a [nimbit
+console](https://github.com/nbt-dev). It gives you, against the live daemon:
+
+- **Console** — streaming server logs (`/_console/logs/ws`)
+- **Data** — a live, virtualized browser over every installed cartridge's
+  entities, streamed off the bulk WebSocket (`/_ws/bulk`) with search + row
+  detail
+- **Diagram** — an entity-relationship graph with live row counts
+
+It assumes your app uses nimbit auth: the data socket reads the current session
+bearer from `POST /api/auth/session/current` (sent with `credentials:
+"include"`), same as the console inspector.
+
+## Install
+
+```bash
+npm install @nbt-dev/devtools
+```
+
+`react` and `react-dom` (>=18) are peer dependencies.
+
+## Usage
+
+Mount the panel once near your app root and import the stylesheet once anywhere:
+
+```tsx
+import { NimbitDevTools } from "@nbt-dev/devtools";
+import "@nbt-dev/devtools/styles.css";
+
+export default function App() {
+  return (
+    <>
+      <YourApp />
+      {/* Empty string => same-origin. Point at the console otherwise. */}
+      <NimbitDevTools apiBaseUrl="https://console.example.com" />
+    </>
+  );
+}
+```
+
+The panel renders nothing until toggled. Open/close it from anywhere:
+
+```ts
+import { toggleDevTools } from "@nbt-dev/devtools";
+
+// e.g. bind to Ctrl+F12
+toggleDevTools();
+// or, with no import: window.dispatchEvent(new CustomEvent("devtools-toggle"))
+```
+
+### Next.js
+
+`NimbitDevTools` is a client component (the bundle carries a `"use client"`
+banner). Render it inside a client boundary / your root layout's client tree.
+
+## Styling
+
+The shipped `styles.css` is self-contained and scoped under `.nimbit-devtools`
+(the panel + its portalled surfaces). It ships only Tailwind's theme + utilities
+layers — no preflight reset — so it never disturbs your app's own styles. Works
+with or without Tailwind in the host.
+
+## API
+
+| Export | Description |
+| --- | --- |
+| `NimbitDevTools` | The panel. Props: `apiBaseUrl?`, `defaultActiveTab?`. |
+| `toggleDevTools()` | Dispatches the `devtools-toggle` window event. |
+| `DevToolsProvider`, `useDevTools` | Lower-level state if you compose `DevTools` yourself. |
+| `DevToolsConfigProvider`, `useDevToolsConfig` | The `apiBaseUrl` config context. |
+| `DevTools` | The bare panel (expects the providers above). |

package/dist/components/devtools/console-tab.d.ts

@@ -0,0 +1,3 @@
+import React from "react";
+declare const ConsoleTab: React.FC;
+export default ConsoleTab;

package/dist/components/devtools/data-browser/bulk-decoder.d.ts

@@ -0,0 +1,16 @@
+import { type ColumnDef, type SchemaFrame, type DeltaFrame } from "../../../generated/bulk-protocol";
+export declare function getFrameType(buf: ArrayBuffer): number;
+export declare function getFrameSid(buf: ArrayBuffer): number;
+export declare function parseSchema(buf: ArrayBuffer): SchemaFrame;
+export declare function parseDataChunk(buf: ArrayBuffer, columns: ColumnDef[]): string[][];
+export declare function parseDelta(buf: ArrayBuffer, columns: ColumnDef[]): DeltaFrame;
+export declare function parseError(buf: ArrayBuffer): string;
+export declare function encodeSchemaCmd(sid: number, cart: string, entity: string): string;
+export declare function encodeStreamCmd(sid: number, cart: string, entity: string, opts?: {
+    sort?: string;
+    sort_desc?: boolean;
+    filters?: Record<string, string>;
+}): string;
+export declare function encodeSearchCmd(sid: number, query: string): string;
+export declare function encodeUnsubCmd(sid: number): string;
+export declare function encodeClearSearchCmd(sid: number): string;

package/dist/components/devtools/data-browser/data-store.d.ts

@@ -0,0 +1,18 @@
+import { type ColumnDef, type SchemaFrame, type DeltaFrame } from "../../../generated/bulk-protocol";
+export declare class BulkDataStore {
+    columns: ColumnDef[];
+    rows: string[][];
+    totalRows: number;
+    searchActive: boolean;
+    private _fullRows;
+    private _fullTotalRows;
+    private _idColIndex;
+    applySchema(schema: SchemaFrame): void;
+    appendChunk(chunk: string[][]): void;
+    applyDelta(delta: DeltaFrame): void;
+    enterSearch(schema: SchemaFrame): void;
+    exitSearch(): void;
+    getRowCount(): number;
+    private _findRowById;
+    private _findRowByIdStr;
+}

package/dist/components/devtools/data-browser/data-table.d.ts

@@ -0,0 +1,9 @@
+import React from "react";
+type DataTableProps = {
+    cart: string;
+    entity: string;
+    searchFields: readonly string[];
+    onSelectRow: (rowJson: Record<string, string>) => void;
+};
+declare const DataTable: React.FC<DataTableProps>;
+export default DataTable;

package/dist/components/devtools/data-tab.d.ts

@@ -0,0 +1,3 @@
+import React from "react";
+declare const DataTab: React.FC;
+export default DataTab;

package/dist/components/devtools/dev-tools.d.ts

@@ -0,0 +1,3 @@
+import React from "react";
+declare const DevTools: React.FC;
+export default DevTools;

package/dist/components/devtools/devtools-context.d.ts

@@ -0,0 +1,35 @@
+import React from "react";
+export type DevToolsDock = "bottom" | "right";
+export type DevToolsTab = {
+    id: string;
+    title: string;
+    icon?: React.ReactNode;
+    render: () => React.ReactNode;
+};
+export type DevToolsSize = {
+    h: number;
+    w: number;
+};
+type DevToolsCtx = {
+    open: boolean;
+    setOpen: (v: boolean) => void;
+    toggle: () => void;
+    dock: DevToolsDock;
+    setDock: (d: DevToolsDock) => void;
+    activeTab: string | null;
+    setActiveTab: (id: string) => void;
+    size: DevToolsSize;
+    setSize: (s: DevToolsSize | ((prev: DevToolsSize) => DevToolsSize)) => void;
+    maximized: boolean;
+    setMaximized: (v: boolean) => void;
+    dataCart: string | null;
+    setDataCart: (v: string | null) => void;
+    dataEntity: string | null;
+    setDataEntity: (v: string | null) => void;
+};
+export declare const DevToolsProvider: React.FC<{
+    children: React.ReactNode;
+    defaultActiveTab?: string;
+}>;
+export declare function useDevTools(): DevToolsCtx;
+export {};

package/dist/components/devtools/entity-graph/diagram-tab.d.ts

@@ -0,0 +1,2 @@
+import React from "react";
+export declare const DiagramView: React.FC;

package/dist/components/devtools/entity-graph/entity-graph-utils.d.ts

@@ -0,0 +1,92 @@
+export type GraphInputField = {
+    name: string;
+    type: string;
+    optional?: boolean;
+    array?: boolean;
+    kind?: string;
+    target?: string;
+    targetCart?: string;
+    relationKind?: string;
+    fkField?: string;
+};
+export type GraphInputEntity = {
+    name: string;
+    fields: GraphInputField[];
+};
+export type GraphInputCart = {
+    name: string;
+    entities: GraphInputEntity[];
+};
+export type EntityGraphField = {
+    name: string;
+    displayName: string;
+    type: string;
+    kind: string;
+    optional: boolean;
+    array: boolean;
+    target?: string;
+    targetCart?: string;
+    relationKind?: string;
+    fkField?: string;
+    implicit?: boolean;
+};
+export type EntityGraphNodeData = {
+    id: string;
+    cartridge: string;
+    entity: string;
+    fields: EntityGraphField[];
+    fieldCount: number;
+    scalarCount: number;
+    relationCount: number;
+    documentCount: number;
+    rowCount: number;
+};
+export type EntityGraphNode = EntityGraphNodeData & {
+    position: {
+        x: number;
+        y: number;
+    };
+};
+export type EntityGraphEdge = {
+    id: string;
+    source: string;
+    target: string;
+    sourceField: string;
+    targetField: string;
+    label: string;
+    relationKind?: string;
+    fkField?: string;
+};
+export type EntityGraphTotals = {
+    entities: number;
+    relationships: number;
+    rows: number;
+};
+export type EntityGraphModel = {
+    nodes: EntityGraphNode[];
+    edges: EntityGraphEdge[];
+    totals: EntityGraphTotals;
+};
+type ContractField = {
+    name: string;
+    type: string;
+    optional?: boolean;
+    array?: boolean;
+    kind?: string;
+    target?: string;
+    target_cart?: string;
+    relation_kind?: string;
+    fk_field?: string;
+};
+type ContractEntity = {
+    fields?: ContractField[];
+};
+export type Contract = {
+    cartridge?: string;
+    owns?: Record<string, ContractEntity>;
+};
+export declare function cartsFromContracts(contracts: Contract[]): GraphInputCart[];
+export declare function entityGraphId(cartridge: string, entity: string): string;
+export declare function buildEntityGraphModel(cartridges: GraphInputCart[]): EntityGraphModel;
+export declare function filterEntityGraphModel(model: EntityGraphModel, visibleIds: Set<string>): EntityGraphModel;
+export {};

package/dist/components/devtools/entity-graph/entity-node.d.ts

@@ -0,0 +1,9 @@
+import React from "react";
+import { type NodeProps } from "@xyflow/react";
+export type EntityNodeHighlight = {
+    focused: boolean;
+    connected: boolean;
+    dimmed: boolean;
+    fields: string[];
+};
+export declare function EntityNode({ data, selected }: NodeProps): React.JSX.Element;

package/dist/components/devtools/network-tab.d.ts

@@ -0,0 +1,3 @@
+import React from "react";
+declare const NetworkTab: React.FC;
+export default NetworkTab;

package/dist/components/devtools/settings-tab.d.ts

@@ -0,0 +1,3 @@
+import React from "react";
+declare const SettingsTab: React.FC;
+export default SettingsTab;

package/dist/components/ui/button.d.ts

@@ -0,0 +1,10 @@
+import * as React from "react";
+import { type VariantProps } from "class-variance-authority";
+declare const buttonVariants: (props?: ({
+    variant?: "link" | "default" | "outline" | "secondary" | "ghost" | "destructive" | null | undefined;
+    size?: "default" | "xs" | "sm" | "lg" | "icon" | "icon-xs" | "icon-sm" | "icon-lg" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+declare function Button({ className, variant, size, asChild, ...props }: React.ComponentProps<"button"> & VariantProps<typeof buttonVariants> & {
+    asChild?: boolean;
+}): React.JSX.Element;
+export { Button, buttonVariants };

package/dist/components/ui/sheet.d.ts

@@ -0,0 +1,14 @@
+import * as React from "react";
+import { Dialog as SheetPrimitive } from "radix-ui";
+declare function Sheet({ ...props }: React.ComponentProps<typeof SheetPrimitive.Root>): React.JSX.Element;
+declare function SheetTrigger({ ...props }: React.ComponentProps<typeof SheetPrimitive.Trigger>): React.JSX.Element;
+declare function SheetClose({ ...props }: React.ComponentProps<typeof SheetPrimitive.Close>): React.JSX.Element;
+declare function SheetContent({ className, children, side, showCloseButton, ...props }: React.ComponentProps<typeof SheetPrimitive.Content> & {
+    side?: "top" | "right" | "bottom" | "left";
+    showCloseButton?: boolean;
+}): React.JSX.Element;
+declare function SheetHeader({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+declare function SheetFooter({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+declare function SheetTitle({ className, ...props }: React.ComponentProps<typeof SheetPrimitive.Title>): React.JSX.Element;
+declare function SheetDescription({ className, ...props }: React.ComponentProps<typeof SheetPrimitive.Description>): React.JSX.Element;
+export { Sheet, SheetTrigger, SheetClose, SheetContent, SheetHeader, SheetFooter, SheetTitle, SheetDescription, };

package/dist/config.d.ts

@@ -0,0 +1,10 @@
+import React from "react";
+export type DevToolsConfig = {
+    apiBaseUrl: string;
+};
+export declare const DevToolsConfigProvider: React.FC<{
+    apiBaseUrl?: string;
+    children: React.ReactNode;
+}>;
+export declare function useDevToolsConfig(): DevToolsConfig;
+export declare function wsBaseFrom(apiBaseUrl: string): string;

package/dist/generated/bulk-protocol.d.ts

@@ -0,0 +1,38 @@
+export declare const FRAME_SCHEMA = 1;
+export declare const FRAME_DATA = 2;
+export declare const FRAME_DATA_END = 3;
+export declare const FRAME_DELTA_INS = 4;
+export declare const FRAME_DELTA_UPD = 5;
+export declare const FRAME_DELTA_DEL = 6;
+export declare const FRAME_SEARCH_RESULT = 7;
+export declare const FRAME_SEARCH_END = 8;
+export declare const FRAME_ERROR = 255;
+export declare const TYPE_U8 = 1;
+export declare const TYPE_U16 = 2;
+export declare const TYPE_U32 = 3;
+export declare const TYPE_U64 = 4;
+export declare const TYPE_S8 = 5;
+export declare const TYPE_S16 = 6;
+export declare const TYPE_S32 = 7;
+export declare const TYPE_S64 = 8;
+export declare const TYPE_BOOL = 9;
+export declare const TYPE_FLOAT32 = 10;
+export declare const TYPE_FLOAT64 = 11;
+export declare const TYPE_STRING = 12;
+export declare const TYPE_DATETIME = 13;
+export declare const TYPE_DOCUMENT = 14;
+export type ColumnDef = {
+    name: string;
+    type: number;
+    fixedSize: number;
+};
+export type SchemaFrame = {
+    totalRows: number;
+    columns: ColumnDef[];
+};
+export type DeltaFrame = {
+    op: number;
+    rowData?: string[];
+    id?: string;
+};
+export declare function fixedSizeForType(type: number): number;

package/dist/hooks/use-bulk-stream.d.ts

@@ -0,0 +1,24 @@
+import React from "react";
+import { BulkDataStore } from "../components/devtools/data-browser/data-store";
+import { type ColumnDef } from "../generated/bulk-protocol";
+import type { BulkRegistry } from "./use-cartridge-info";
+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 Props = {
+    registry: BulkRegistry;
+    children: React.ReactNode;
+};
+export declare function BulkStreamProvider({ registry, children }: Props): React.ReactElement;
+export declare function useBulkRowCounts(registry: BulkRegistry): Record<string, number>;
+export declare function useBulkSubscription(cart: string, entity: string): BulkSubscription;
+export {};

package/dist/hooks/use-cartridge-info.d.ts

@@ -0,0 +1,13 @@
+export type BulkEntity = {
+    name: string;
+    route: string;
+    searchFields: readonly string[];
+};
+export type BulkRegistry = Record<string, BulkEntity[]>;
+export type LiveRegistryState = {
+    registry: BulkRegistry;
+    carts: string[];
+    loading: boolean;
+    error: string | null;
+};
+export declare function useLiveBulkRegistry(): LiveRegistryState;

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+import React from "react";
+export type NimbitDevToolsProps = {
+    apiBaseUrl?: string;
+    defaultActiveTab?: string;
+};
+export declare const NimbitDevTools: React.FC<NimbitDevToolsProps>;
+export default NimbitDevTools;
+export declare function toggleDevTools(): void;
+export { DevToolsProvider, useDevTools, } from "./components/devtools/devtools-context";
+export { DevToolsConfigProvider, useDevToolsConfig } from "./config";
+export type { DevToolsConfig } from "./config";
+export { default as DevTools } from "./components/devtools/dev-tools";
+export type { DevToolsDock, DevToolsTab, DevToolsSize, } from "./components/devtools/devtools-context";