@rahdar/plugin-sdk 0.0.0 → 2026.10.50

package/README.md

@@ -0,0 +1,38 @@
+# @rahdar/plugin-sdk
+
+Build the UI of an [Rahdar](https://github.com/sudoitir/rahdar) plugin.
+
+- **Typings** for everything a plugin's UI may use from Rahdar: routes under Rahdar's own roots, slots,
+  navigation, the API client, permission checks and shared components. At runtime Rahdar provides
+  the SDK itself, so a plugin's bundle never contains a copy.
+- **A Vite preset** that builds the UI as a Module Federation remote taking React, Mantine and
+  TanStack from Rahdar.
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import { rahdarPlugin } from '@rahdar/plugin-sdk/vite';
+
+export default defineConfig({ plugins: [react(), rahdarPlugin({ id: 'acme-notes' })] });
+```
+
+```tsx
+// src/feature.tsx
+import { createRoute } from '@tanstack/react-router';
+import { CONTRACT, clusterRoute, definePlugin, pluginPath, pluginView } from '@rahdar/plugin-sdk';
+
+const notes = createRoute({
+  getParentRoute: () => clusterRoute,
+  path: pluginPath('acme-notes', 'notes'),
+  component: pluginView('acme-notes', NotesView),
+});
+
+export default definePlugin({ contract: CONTRACT, id: 'acme-notes', routes: { cluster: [notes] } });
+```
+
+The SDK's version is the Rahdar version it was built from, and its peer dependencies are the exact
+React, Mantine and TanStack versions that Rahdar ships. Build against the SDK of the oldest Rahdar
+your plugin supports (`rahdar.since` in `plugin.json`).
+
+The guide: <https://rahdar.dev/guide/plugins>.

package/index.js

@@ -0,0 +1,52 @@
+// Generated by build.mjs. Rahdar provides this module at runtime; these names exist so a
+// plugin's build knows what it imports. Running a plugin outside Rahdar fails here, loudly.
+const outsideRahdar = (name) => () => {
+  throw new Error(`${name}: @rahdar/plugin-sdk is provided by Rahdar at runtime; load this plugin in Rahdar.`);
+};
+export const ACTION_SECTIONS = outsideRahdar('ACTION_SECTIONS');
+export const ADMIN_GROUPS = outsideRahdar('ADMIN_GROUPS');
+export const ActionMenuItem = outsideRahdar('ActionMenuItem');
+export const ApiError = outsideRahdar('ApiError');
+export const CONTRACT = outsideRahdar('CONTRACT');
+export const CapabilityGate = outsideRahdar('CapabilityGate');
+export const CodeEditor = outsideRahdar('CodeEditor');
+export const ConfirmDialog = outsideRahdar('ConfirmDialog');
+export const DataTable = outsideRahdar('DataTable');
+export const DescriptionList = outsideRahdar('DescriptionList');
+export const DiagramView = outsideRahdar('DiagramView');
+export const EmptyState = outsideRahdar('EmptyState');
+export const ErrorState = outsideRahdar('ErrorState');
+export const FieldRow = outsideRahdar('FieldRow');
+export const HoldToConfirm = outsideRahdar('HoldToConfirm');
+export const LoadingState = outsideRahdar('LoadingState');
+export const METRIC_RANGES = outsideRahdar('METRIC_RANGES');
+export const MetricChart = outsideRahdar('MetricChart');
+export const NAV_GROUPS = outsideRahdar('NAV_GROUPS');
+export const NodeOutcomeSummary = outsideRahdar('NodeOutcomeSummary');
+export const Notice = outsideRahdar('Notice');
+export const OperationHeldError = outsideRahdar('OperationHeldError');
+export const OutcomeSummary = outsideRahdar('OutcomeSummary');
+export const Page = outsideRahdar('Page');
+export const PageHeader = outsideRahdar('PageHeader');
+export const Pager = outsideRahdar('Pager');
+export const SETTINGS_GROUPS = outsideRahdar('SETTINGS_GROUPS');
+export const Section = outsideRahdar('Section');
+export const Stat = outsideRahdar('Stat');
+export const StatusBadge = outsideRahdar('StatusBadge');
+export const StepUpPrompt = outsideRahdar('StepUpPrompt');
+export const Toolbar = outsideRahdar('Toolbar');
+export const clusterKey = outsideRahdar('clusterKey');
+export const clusterRoute = outsideRahdar('clusterRoute');
+export const definePlugin = outsideRahdar('definePlugin');
+export const gateFor = outsideRahdar('gateFor');
+export const heldOperationsKey = outsideRahdar('heldOperationsKey');
+export const notify = outsideRahdar('notify');
+export const pluginApi = outsideRahdar('pluginApi');
+export const pluginPath = outsideRahdar('pluginPath');
+export const pluginView = outsideRahdar('pluginView');
+export const request = outsideRahdar('request');
+export const rootRoute = outsideRahdar('rootRoute');
+export const useCan = outsideRahdar('useCan');
+export const useMe = outsideRahdar('useMe');
+export const usePluginSeries = outsideRahdar('usePluginSeries');
+export const useUserStream = outsideRahdar('useUserStream');

package/package.json

@@ -1 +1,46 @@
-{"name":"@rahdar/plugin-sdk","version":"0.0.0","description":"Placeholder reserving the name; real releases come from CI.","license":"Apache-2.0","repository":{"type":"git","url":"git+https://github.com/sudoitir/rahdar.git"}}
+{
+  "name": "@rahdar/plugin-sdk",
+  "version": "2026.10.50",
+  "description": "Build the UI of a Rahdar plugin: typings for the Rahdar APIs a plugin may use, and a Vite preset.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sudoitir/rahdar.git",
+    "directory": "web/packages/plugin-sdk"
+  },
+  "homepage": "https://rahdar.dev/guide/plugins",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./types/sdk/index.d.ts",
+      "default": "./index.js"
+    },
+    "./vite": {
+      "types": "./vite.d.ts",
+      "default": "./vite.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "shared.js",
+    "shared.d.ts",
+    "vite.js",
+    "vite.d.ts",
+    "peers.json",
+    "types",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "@mantine/core": "9.6.3",
+    "@mantine/hooks": "9.6.3",
+    "@tanstack/react-query": "5.104.1",
+    "@tanstack/react-router": "1.170.41",
+    "vite": ">=8"
+  },
+  "dependencies": {
+    "@module-federation/vite": "1.23.2"
+  }
+}

package/peers.json

@@ -0,0 +1,8 @@
+{
+  "react": "19.3.0",
+  "react-dom": "19.3.0",
+  "@mantine/core": "9.6.3",
+  "@mantine/hooks": "9.6.3",
+  "@tanstack/react-query": "5.104.1",
+  "@tanstack/react-router": "1.170.41"
+}

package/shared.d.ts

@@ -0,0 +1,3 @@
+export const SHARED_LIBRARIES: string[];
+export const SDK: string;
+export function packageOf(specifier: string): string;

package/shared.js

@@ -0,0 +1,24 @@
+/**
+ * The libraries a plugin's UI takes from Rahdar instead of bundling (ADR-0100): the ones holding
+ * React context or module state, where a second copy breaks hooks, routing, theming or the query
+ * cache. Rahdar's own build (web/vite.config.ts) shares exactly these, so the list lives here, once.
+ */
+export const SHARED_LIBRARIES = [
+  'react',
+  'react/jsx-runtime',
+  'react-dom',
+  'react-dom/client',
+  '@mantine/core',
+  '@mantine/hooks',
+  '@tanstack/react-query',
+  '@tanstack/react-router',
+];
+
+/** The SDK itself: always the running Rahdar's copy. */
+export const SDK = '@rahdar/plugin-sdk';
+
+/** The package a shared specifier belongs to: `react-dom/client` → `react-dom`. */
+export function packageOf(specifier) {
+  const parts = specifier.split('/');
+  return specifier.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
+}

package/types/branding.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Single source of every user-visible product name on the web side.
+ * Mirror of `Branding.java`. See `docs/adr/0001-project-name-and-trademark-risk.md`.
+ *
+ * A rename is: this file, `Branding.java`, the Maven `artifactId`, the image
+ * coordinates, and `index.html` <title>. Nothing else.
+ */
+export declare const branding: {
+    readonly productName: "Rahdar";
+    readonly productShortName: "Rahdar";
+    readonly tagline: "Cluster-wide management and observability for Apache ActiveMQ Artemis";
+    readonly trademarkNotice: string;
+    readonly projectUrl: "https://github.com/sudoitir/rahdar";
+};

package/types/kernel/actions/ActionHost.d.ts

@@ -0,0 +1,16 @@
+import { type ReactNode } from 'react';
+/**
+ * Hosts the dialogs row actions open (ADR-0107), outside any grid: a dialog mounted in a
+ * virtualized row is unmounted when the row scrolls away or when the refresh its own success
+ * triggers removes the row, and its outcome goes with it.
+ *
+ * <p>A dialog is mounted closed and opened on the next frame. Dialogs take their dry-run preview
+ * in `onEnterTransitionEnd`, which a modal mounted already open never fires. On close it is kept
+ * until its exit transition ends, then removed, and focus goes back to what opened it — unless the
+ * dialog navigated away, where moving focus would be a jump the operator did not ask for. The end
+ * is heard as the surface's `transitionend`, which React bubbles out of the dialog's portal; a
+ * timer as long as the slowest exit in the theme removes it if that event never comes.
+ */
+export declare function ActionHostProvider({ children }: Readonly<{
+    children: ReactNode;
+}>): import("react").JSX.Element;

package/types/kernel/actions/hostContext.d.ts

@@ -0,0 +1,4 @@
+import type { ActionHost } from './types.ts';
+export declare const HostContext: import("react").Context<ActionHost | null>;
+/** The action host of the surrounding cluster layout (or test harness). */
+export declare function useActionHost(): ActionHost;

package/types/kernel/actions/types.d.ts

@@ -0,0 +1,130 @@
+import type { ComponentType, ReactNode } from 'react';
+import type { components } from '../api/schema.d.ts';
+import type { GateVerdict } from '../../ui/capabilityGate.ts';
+type Schemas = components['schemas'];
+/**
+ * The sections of a row's action menu, in the order it shows them (ADR-0107). The list is closed,
+ * like the navigation groups: an action names one, and adding one is a kernel change.
+ */
+export declare const ACTION_SECTIONS: readonly [{
+    readonly id: "open";
+    readonly label: "Open";
+}, {
+    readonly id: "copy";
+    readonly label: "Copy";
+}, {
+    readonly id: "operate";
+    readonly label: "Operate";
+}, {
+    readonly id: "destroy";
+    readonly label: "Destroy";
+}];
+export type ActionSection = (typeof ACTION_SECTIONS)[number]['id'];
+/**
+ * `act` offers everything; `navigate` only the Open and Copy sections, for a view that must never
+ * change the broker (Flow).
+ */
+export type ActionMode = 'act' | 'navigate';
+export interface QueueTarget {
+    queueName: string;
+    address?: string | null;
+    snapshot?: Schemas['QueueView'];
+}
+export interface AddressTarget {
+    address: string;
+    snapshot?: Schemas['AddressView'];
+}
+/** Connections, sessions, consumers and producers are per node; a close needs to know which. */
+interface NodeScoped {
+    nodeId: string;
+    nodeName: string;
+}
+export interface ConnectionTarget extends NodeScoped {
+    connectionId: string;
+    snapshot?: Schemas['ConnectionView'];
+}
+export interface SessionTarget extends NodeScoped {
+    sessionId: string;
+    connectionId?: string | null;
+    snapshot?: Schemas['SessionView'];
+}
+export interface ConsumerTarget extends NodeScoped {
+    consumerId: string;
+    queueName?: string | null;
+    sessionId?: string | null;
+    snapshot?: Schemas['ConsumerView'];
+}
+export interface ProducerTarget extends NodeScoped {
+    producerId: string;
+    address?: string | null;
+    sessionId?: string | null;
+    snapshot?: Schemas['ProducerView'];
+}
+export interface MessageTarget {
+    queueName: string;
+    messageId: number;
+    /** The node the message was browsed on; absent for the live node. */
+    node?: string;
+}
+export interface DivertTarget {
+    name: string;
+    snapshot?: Schemas['DivertView'];
+}
+/** A client of the flow view: an identity that may stand for many connections. */
+export interface ClientTarget {
+    label: string;
+}
+/** Each resource kind a row menu or a link can be about, with its target. */
+export interface ActionTargets {
+    queue: QueueTarget;
+    address: AddressTarget;
+    connection: ConnectionTarget;
+    session: SessionTarget;
+    consumer: ConsumerTarget;
+    producer: ProducerTarget;
+    message: MessageTarget;
+    divert: DivertTarget;
+    client: ClientTarget;
+}
+export type ActionKind = keyof ActionTargets;
+/** What the action host gives a dialog it hosts. */
+export interface HostedDialogProps {
+    opened: boolean;
+    onClose: () => void;
+}
+type Blocked = Extract<GateVerdict, {
+    kind: 'blocked';
+}>;
+/**
+ * Where an action's dialog lives (ADR-0107): outside the grid, so it outlives the row that opened
+ * it, the menu that offered it, and the refresh that removes the row when the action succeeds.
+ */
+export interface ActionHost {
+    /**
+     * Opens `Dialog` with `props`, plus `opened` and `onClose`. On close, focus goes back through
+     * `restoreFocus` — unless the dialog navigated away.
+     */
+    open<P extends HostedDialogProps>(Dialog: ComponentType<P>, props: NoInfer<Omit<P, keyof HostedDialogProps>>, options?: {
+        restoreFocus?: () => void;
+    }): void;
+    /** Explains why an action is unavailable, in full. */
+    explain(verdict: Blocked, what: string, options?: {
+        restoreFocus?: () => void;
+    }): void;
+    /** Copies `text` and says so; `what` names it ("queue name"). */
+    copy(text: string, what: string): void;
+}
+/** What a row-action contribution is given. */
+export interface ActionProps<T> {
+    clusterId: string;
+    target: T;
+    host: ActionHost;
+    mode: ActionMode;
+}
+/** What a link contribution is given: it wraps `children` (the name) in a link to the resource. */
+export interface LinkProps<T> {
+    clusterId: string;
+    target: T;
+    children: ReactNode;
+}
+export {};

package/types/kernel/api/paging.d.ts

@@ -0,0 +1,39 @@
+import { type UseQueryResult } from '@tanstack/react-query';
+import { type ApiError } from './request.ts';
+/** Generic paged envelope (`PagedView<T>` on the backend). */
+export interface PagedView<T> {
+    data: T[];
+    page: number;
+    pageSize: number;
+    /** The total across all pages; null where the server cannot know it. */
+    count: number | null;
+    hasNext: boolean;
+}
+/**
+ * A page of a history that can be very long (`HistoryPage<T>` on the backend): by page number for the first
+ * rows, then by the `next` cursor passed as `after`, which has no total.
+ */
+export interface HistoryPage<T> extends PagedView<T> {
+    /** The cursor of the page after this one; null on the last page. */
+    next: string | null;
+    /** Read from a replica that may be a little behind the primary. */
+    mayLag: boolean;
+}
+/** The largest page the server allows (`ResourceQuery.MAX_SIZE`). */
+export declare const MAX_PAGE_SIZE = 500;
+/**
+ * Every row of a list the UI shows in full (roles, environments, channels, …): pages of the maximum size,
+ * followed while the server says another page exists. Stopping early would read as "no such row".
+ */
+export declare function requestAll<T>(path: string): Promise<T[]>;
+export interface ResourceParams {
+    q?: string;
+    sort?: string;
+    page?: number;
+    size?: number;
+}
+export declare function resourceSearch(params: ResourceParams): string;
+/** One page of a cluster-wide listing (queues, addresses, consumers, …), refetched on the usual interval. */
+export declare function useResource<T>(id: string, kind: string, params: ResourceParams): UseQueryResult<PagedView<T>, ApiError>;
+/** Rows in the envelope every list endpoint answers with, for the fixtures that stand in for one. */
+export declare function paged<T>(data: T[]): PagedView<T>;

package/types/kernel/api/polling.d.ts

@@ -0,0 +1,37 @@
+import { type Query, type QueryClient } from '@tanstack/react-query';
+/**
+ * Make TanStack's focus state mean "may refresh on its own": the tab is visible and
+ * refreshing is not paused. Called once, beside the `QueryClient`.
+ *
+ * A side effect: the retryer also waits for focus, so a request that fails while
+ * paused retries on resume rather than during the pause.
+ */
+export declare function installPauseSeam(): void;
+/**
+ * `refetchOnMount` for the QueryClient default, so pausing covers opening a view
+ * and not only the intervals.
+ *
+ * Pausing intervals but not mounts means an operator who pauses and then
+ * navigates has silently unpaused — every query the new screen observes is stale
+ * (the stream marks them so) and refetches on mount.
+ *
+ * A query that has never resolved is exempt: suspending its first fetch would hand
+ * the operator an empty screen. They paused a screen showing data to stop it
+ * moving, not to stop data existing.
+ */
+export declare function mountRefetch(): (query: Query) => boolean;
+export declare function isPollingPaused(): boolean;
+export declare function setPollingPaused(next: boolean): void;
+/** Record that the server said something changed while refreshing was paused. */
+export declare function markPendingChange(): void;
+export declare function usePollingPaused(): boolean;
+export declare function usePendingChange(): boolean;
+/**
+ * Refetch everything the current screen is observing: what resuming does, because the
+ * first thing an operator needs after unpausing is current data.
+ *
+ * `refetchType: 'active'` scopes it to what is on the display, the same scope the
+ * freshness indicator reports on. `cancelRefetch: false` lets a fetch already in
+ * flight finish rather than aborting it for an identical one.
+ */
+export declare function refreshActiveQueries(qc: QueryClient): Promise<void>;

package/types/kernel/api/request.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Transport to the Rahdar API: `request<T>()` and the RFC 9457 `ApiError`.
+ *
+ * DTO types come from `schema.d.ts`, generated by `openapi-typescript` from the
+ * backend's committed OpenAPI snapshot (`web/openapi.json`) — ADR-0019. Each
+ * feature's `api.ts` names the DTOs it uses and holds its own hooks and query
+ * keys, every cluster-scoped key under {@link clusterKey}.
+ */
+export declare const BASE = "/api/v1";
+/** A parsed `application/problem+json` body. */
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly type: string;
+    readonly title: string;
+    readonly brokerErrorKind?: string;
+    readonly fieldErrors: {
+        field: string;
+        message: string;
+    }[];
+    /**
+     * The whole `problem+json` body. Handlers attach extra properties to a problem
+     * — the offending token on a syntax error, the estimate and ceiling on a
+     * refused query — and a message with the number left out is not something an
+     * operator can act on.
+     */
+    readonly problem: Record<string, unknown>;
+    constructor(status: number, body: Record<string, unknown>);
+}
+/** What the server says about an operation it held for approval instead of running. */
+export interface HeldOperation {
+    id: string;
+    /** What the operation would do, in words, such as `Purge queue "orders" on prod`. */
+    summary: string;
+    /** When the request lapses unless someone decides it, as an ISO instant. */
+    expiresAt: string;
+    /** The held operation's API path. */
+    link: string;
+}
+/** The header a `202` carries when the operation was held for approval rather than run. */
+export declare const HELD_HEADER = "X-Rahdar-Held-Operation";
+/**
+ * The operation was not run but held for a second person to approve. It is thrown, not returned, so a
+ * mutation's success path (its toast, its invalidation, the dialog closing on "done") never treats a held
+ * operation as done; `notify.settle` and `ErrorState` show it as sent for approval, not as a failure.
+ */
+export declare class OperationHeldError extends Error {
+    readonly heldOperation: HeldOperation;
+    constructor(heldOperation: HeldOperation);
+}
+/** The root every held-operation query key starts from, so a held outcome or a `held` signal refreshes all of them. */
+export declare const heldOperationsKey: readonly ["held-operations"];
+/**
+ * The header that tells the server a person, not a background refresh, made this request, so it
+ * counts towards the session's idle timeout (ADR-0145). Polling sends it only while the person is
+ * around; the event stream cannot send headers at all, so it never counts.
+ */
+export declare const ACTIVITY_HEADER = "X-Rahdar-Activity";
+/** How long after the last pointer or key press a request still counts as the person's. */
+export declare const ACTIVITY_WINDOW_MS = 60000;
+/** Whether the person used the pointer or keyboard within {@link ACTIVITY_WINDOW_MS}. */
+export declare function personIsActive(): boolean;
+/** The `reason` a 401 hands the sign-in screen when this page had been signed in, so it can say the session ended. */
+export declare const SESSION_ENDED_REASON = "ended";
+/** Reads the `XSRF-TOKEN` cookie Spring Security's `CookieCsrfTokenRepository` sets (identity-and-sessions spec). */
+export declare function csrfToken(): string | undefined;
+/** Whether this page is the sign-in page, which asks for nothing that needs a session. */
+export declare function onLoginPage(): boolean;
+export declare function request<T>(path: string, init?: RequestInit): Promise<T>;
+/** The root every cluster-scoped query key starts from, so invalidating a cluster reaches all of it. */
+export declare const clusterKey: (id: string, ...parts: unknown[]) => readonly ["clusters", string, ...unknown[]];
+/** The path a cluster-wide command is issued under. */
+export declare const lifecycleBase: (clusterId: string) => string;
+/**
+ * A lifecycle command names the cluster, not a node, and comes back as a
+ * per-node outcome. `dryRun` previews without touching any broker; `override`
+ * clears the bulk cap on a destroy, which is the only kind the cap applies to.
+ * A defined `dryRun` is always sent, `false` included: a real run must never be
+ * left to the server's default.
+ */
+export interface LifecycleVars {
+    dryRun?: boolean;
+    override?: boolean;
+}
+export declare function lifecycleQuery(dryRun?: boolean, override?: boolean): string;