common/hermes
2
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

feat: dashboard plugin system — extend the web UI with custom tabs

Browse Source 
Add a plugin system that lets plugins add new tabs to the dashboard.
Plugins live in ~/.hermes/plugins/<name>/dashboard/ alongside any
existing CLI/gateway plugin code.

Plugin structure:
  plugins/<name>/dashboard/
    manifest.json     # name, label, icon, tab config, entry point
    dist/index.js     # pre-built JS bundle (IIFE, uses SDK globals)
    plugin_api.py     # optional FastAPI router mounted at /api/plugins/<name>/

Backend (hermes_cli/web_server.py):
- Plugin discovery: scans plugins/*/dashboard/manifest.json from user,
  bundled, and project plugin directories
- GET /api/dashboard/plugins — returns discovered plugin manifests
- GET /api/dashboard/plugins/rescan — force re-discovery
- GET /dashboard-plugins/<name>/<path> — serves plugin static assets
  with path traversal protection
- Optional API route mounting: imports plugin_api.py and mounts its
  router under /api/plugins/<name>/
- Plugin API routes bypass session token auth (localhost-only)

Frontend (web/src/plugins/):
- Plugin SDK exposed on window.__HERMES_PLUGIN_SDK__ — provides React,
  hooks, UI components (Card, Badge, Button, etc.), API client,
  fetchJSON, theme/i18n hooks, and utilities
- Plugin registry on window.__HERMES_PLUGINS__.register(name, Component)
- usePlugins() hook: fetches manifests, loads JS/CSS, resolves components
- App.tsx dynamically adds nav items and routes for discovered plugins
- Icon resolution via static map of 20 common Lucide icons (no tree-
  shaking penalty — bundle only +5KB over baseline)

Example plugin (plugins/example-dashboard/):
- Demonstrates SDK usage: Card components, backend API call, SDK reference
- Backend route: GET /api/plugins/example/hello

Tested: plugin discovery, static serving, API routes, path traversal
blocking, unknown plugin 404, bundle size (400KB vs 394KB baseline).
This commit is contained in:
Teknium
2026-04-16 03:10:28 -07:00
committed by Teknium
parent 23a42635f0
commit 01214a7f73
11 changed files with 660 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

114
web/src/App.tsx
View File

@@ -1,5 +1,11 @@
import { useMemo } from "react";
import { Routes, Route, NavLink, Navigate } from "react-router-dom";
import { Activity, BarChart3, Clock, FileText, KeyRound, MessageSquare, Package, Settings } from "lucide-react";
import {
Activity, BarChart3, Clock, FileText, KeyRound,
MessageSquare, Package, Settings, Puzzle,
Sparkles, Terminal, Globe, Database, Shield,
Wrench, Zap, Heart, Star, Code, Eye,
} from "lucide-react";
import StatusPage from "@/pages/StatusPage";
import ConfigPage from "@/pages/ConfigPage";
import EnvPage from "@/pages/EnvPage";
@@ -11,20 +17,90 @@ import SkillsPage from "@/pages/SkillsPage";
import { LanguageSwitcher } from "@/components/LanguageSwitcher";
import { ThemeSwitcher } from "@/components/ThemeSwitcher";
import { useI18n } from "@/i18n";
import { usePlugins } from "@/plugins";
import type { RegisteredPlugin } from "@/plugins";
const NAV_ITEMS = [
{ path: "/", labelKey: "status" as const, icon: Activity },
{ path: "/sessions", labelKey: "sessions" as const, icon: MessageSquare },
{ path: "/analytics", labelKey: "analytics" as const, icon: BarChart3 },
{ path: "/logs", labelKey: "logs" as const, icon: FileText },
{ path: "/cron", labelKey: "cron" as const, icon: Clock },
{ path: "/skills", labelKey: "skills" as const, icon: Package },
{ path: "/config", labelKey: "config" as const, icon: Settings },
{ path: "/env", labelKey: "keys" as const, icon: KeyRound },
] as const;
// ---------------------------------------------------------------------------
// Built-in nav items
// ---------------------------------------------------------------------------
interface NavItem {
path: string;
label: string;
labelKey?: string;
icon: React.ComponentType<{ className?: string }>;
}
const BUILTIN_NAV: NavItem[] = [
{ path: "/", labelKey: "status", label: "Status", icon: Activity },
{ path: "/sessions", labelKey: "sessions", label: "Sessions", icon: MessageSquare },
{ path: "/analytics", labelKey: "analytics", label: "Analytics", icon: BarChart3 },
{ path: "/logs", labelKey: "logs", label: "Logs", icon: FileText },
{ path: "/cron", labelKey: "cron", label: "Cron", icon: Clock },
{ path: "/skills", labelKey: "skills", label: "Skills", icon: Package },
{ path: "/config", labelKey: "config", label: "Config", icon: Settings },
{ path: "/env", labelKey: "keys", label: "Keys", icon: KeyRound },
];
// ---------------------------------------------------------------------------
// Helpers
// ---------------------------------------------------------------------------
/** Map of icon names plugins can use. Covers common choices without importing all of lucide. */
const ICON_MAP: Record<string, React.ComponentType<{ className?: string }>> = {
Activity, BarChart3, Clock, FileText, KeyRound,
MessageSquare, Package, Settings, Puzzle,
Sparkles, Terminal, Globe, Database, Shield,
Wrench, Zap, Heart, Star, Code, Eye,
};
/** Resolve a Lucide icon name to a component, fallback to Puzzle. */
function resolveIcon(name: string): React.ComponentType<{ className?: string }> {
return ICON_MAP[name] ?? Puzzle;
}
/** Insert plugin nav items at the position specified in their manifest. */
function buildNavItems(builtIn: NavItem[], plugins: RegisteredPlugin[]): NavItem[] {
const items = [...builtIn];
for (const { manifest } of plugins) {
const pluginItem: NavItem = {
path: manifest.tab.path,
label: manifest.label,
icon: resolveIcon(manifest.icon),
};
const pos = manifest.tab.position ?? "end";
if (pos === "end") {
items.push(pluginItem);
} else if (pos.startsWith("after:")) {
const target = "/" + pos.slice(6);
const idx = items.findIndex((i) => i.path === target);
items.splice(idx >= 0 ? idx + 1 : items.length, 0, pluginItem);
} else if (pos.startsWith("before:")) {
const target = "/" + pos.slice(7);
const idx = items.findIndex((i) => i.path === target);
items.splice(idx >= 0 ? idx : items.length, 0, pluginItem);
} else {
items.push(pluginItem);
}
}
return items;
}
// ---------------------------------------------------------------------------
// App
// ---------------------------------------------------------------------------
export default function App() {
const { t } = useI18n();
const { plugins } = usePlugins();
const navItems = useMemo(
() => buildNavItems(BUILTIN_NAV, plugins),
[plugins],
);
return (
<div className="flex min-h-screen flex-col bg-background text-foreground overflow-x-hidden">
@@ -40,7 +116,7 @@ export default function App() {
</div>
<nav className="flex items-stretch overflow-x-auto scrollbar-none">
{NAV_ITEMS.map(({ path, labelKey, icon: Icon }) => (
{navItems.map(({ path, label, labelKey, icon: Icon }) => (
<NavLink
key={path}
to={path}
@@ -56,7 +132,9 @@ export default function App() {
{({ isActive }) => (
<>
<Icon className="h-4 w-4 sm:h-3.5 sm:w-3.5 shrink-0" />
<span className="hidden sm:inline">{t.app.nav[labelKey]}</span>
<span className="hidden sm:inline">
{labelKey ? (t.app.nav as Record<string, string>)[labelKey] ?? label : label}
</span>
<span className="absolute inset-0 bg-foreground pointer-events-none transition-opacity duration-150 group-hover:opacity-5 opacity-0" />
{isActive && (
<span className="absolute bottom-0 left-0 right-0 h-px bg-foreground" />
@@ -87,6 +165,16 @@ export default function App() {
<Route path="/skills" element={<SkillsPage />} />
<Route path="/config" element={<ConfigPage />} />
<Route path="/env" element={<EnvPage />} />
{/* Plugin routes */}
{plugins.map(({ manifest, component: PluginComponent }) => (
<Route
key={manifest.name}
path={manifest.tab.path}
element={<PluginComponent />}
/>
))}
<Route path="*" element={<Navigate to="/" replace />} />
</Routes>
</main>

23
web/src/lib/api.ts
View File

@@ -9,7 +9,7 @@ declare global {
}
let _sessionToken: string | null = null;
async function fetchJSON<T>(url: string, init?: RequestInit): Promise<T> {
export async function fetchJSON<T>(url: string, init?: RequestInit): Promise<T> {
// Inject the session token into all /api/ requests.
const headers = new Headers(init?.headers);
const token = window.__HERMES_SESSION_TOKEN__;
@@ -192,6 +192,12 @@ export const api = {
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ name }),
}),
// Dashboard plugins
getPlugins: () =>
fetchJSON<PluginManifestResponse[]>("/api/dashboard/plugins"),
rescanPlugins: () =>
fetchJSON<{ ok: boolean; count: number }>("/api/dashboard/plugins/rescan"),
};
export interface PlatformStatus {
@@ -432,3 +438,18 @@ export interface ThemeListResponse {
themes: Array<{ name: string; label: string; description: string }>;
active: string;
}
// ── Dashboard plugin types ─────────────────────────────────────────────
export interface PluginManifestResponse {
name: string;
label: string;
description: string;
icon: string;
version: string;
tab: { path: string; position: string };
entry: string;
css?: string | null;
has_api: boolean;
source: string;
}

5
web/src/main.tsx
View File

@@ -4,6 +4,11 @@ import "./index.css";
import App from "./App";
import { I18nProvider } from "./i18n";
import { ThemeProvider } from "./themes";
import { exposePluginSDK } from "./plugins";
// Expose the plugin SDK before rendering so plugins loaded via <script>
// can access React, components, etc. immediately.
exposePluginSDK();
createRoot(document.getElementById("root")!).render(
<BrowserRouter>

3
web/src/plugins/index.ts Normal file
View File

@@ -0,0 +1,3 @@
export { exposePluginSDK, getPluginComponent, onPluginRegistered, getRegisteredCount } from "./registry";
export { usePlugins } from "./usePlugins";
export type { PluginManifest, RegisteredPlugin } from "./types";

131
web/src/plugins/registry.ts Normal file
View File

@@ -0,0 +1,131 @@
/**
* Dashboard Plugin SDK + Registry
*
* Exposes React, UI components, hooks, and utilities on the window so
* that plugin bundles can use them without bundling their own copies.
*
* Plugins call window.__HERMES_PLUGINS__.register(name, Component)
* to register their tab component.
*/
import React, {
useState,
useEffect,
useCallback,
useMemo,
useRef,
useContext,
createContext,
} from "react";
import { api, fetchJSON } from "@/lib/api";
import { cn, timeAgo, isoTimeAgo } from "@/lib/utils";
import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card";
import { Badge } from "@/components/ui/badge";
import { Button } from "@/components/ui/button";
import { Input } from "@/components/ui/input";
import { Label } from "@/components/ui/label";
import { Select, SelectOption } from "@/components/ui/select";
import { Separator } from "@/components/ui/separator";
import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs";
import { useI18n } from "@/i18n";
import { useTheme } from "@/themes";
// ---------------------------------------------------------------------------
// Plugin registry — plugins call register() to add their component.
// ---------------------------------------------------------------------------
type RegistryListener = () => void;
const _registered: Map<string, React.ComponentType> = new Map();
const _listeners: Set<RegistryListener> = new Set();
function _notify() {
for (const fn of _listeners) {
try { fn(); } catch { /* ignore */ }
}
}
/** Register a plugin component. Called by plugin JS bundles. */
function registerPlugin(name: string, component: React.ComponentType) {
_registered.set(name, component);
_notify();
}
/** Get a registered component by plugin name. */
export function getPluginComponent(name: string): React.ComponentType | undefined {
return _registered.get(name);
}
/** Subscribe to registry changes (returns unsubscribe fn). */
export function onPluginRegistered(fn: RegistryListener): () => void {
_listeners.add(fn);
return () => _listeners.delete(fn);
}
/** Get current count of registered plugins. */
export function getRegisteredCount(): number {
return _registered.size;
}
// ---------------------------------------------------------------------------
// Expose SDK + registry on window
// ---------------------------------------------------------------------------
declare global {
interface Window {
__HERMES_PLUGIN_SDK__: unknown;
__HERMES_PLUGINS__: {
register: typeof registerPlugin;
};
}
}
export function exposePluginSDK() {
window.__HERMES_PLUGINS__ = {
register: registerPlugin,
};
window.__HERMES_PLUGIN_SDK__ = {
// React core — plugins use these instead of importing react
React,
hooks: {
useState,
useEffect,
useCallback,
useMemo,
useRef,
useContext,
createContext,
},
// Hermes API client
api,
// Raw fetchJSON for plugin-specific endpoints
fetchJSON,
// UI components (shadcn/ui primitives)
components: {
Card,
CardHeader,
CardTitle,
CardContent,
Badge,
Button,
Input,
Label,
Select,
SelectOption,
Separator,
Tabs,
TabsList,
TabsTrigger,
},
// Utilities
utils: { cn, timeAgo, isoTimeAgo },
// Hooks
useI18n,
useTheme,
};
}

22
web/src/plugins/types.ts Normal file
View File

@@ -0,0 +1,22 @@
/** Types for the dashboard plugin system. */
export interface PluginManifest {
name: string;
label: string;
description: string;
icon: string;
version: string;
tab: {
path: string;
position: string; // "end", "after:<tab>", "before:<tab>"
};
entry: string;
css?: string | null;
has_api: boolean;
source: string;
}
export interface RegisteredPlugin {
manifest: PluginManifest;
component: React.ComponentType;
}

90
web/src/plugins/usePlugins.ts Normal file
View File

@@ -0,0 +1,90 @@
/**
* usePlugins hook — discovers and loads dashboard plugins.
*
* 1. Fetches plugin manifests from GET /api/dashboard/plugins
* 2. Injects CSS <link> tags for plugins that declare css
* 3. Loads plugin JS bundles via <script> tags
* 4. Waits for plugins to call register() and resolves them
*/
import { useState, useEffect, useRef } from "react";
import { api } from "@/lib/api";
import type { PluginManifest, RegisteredPlugin } from "./types";
import { getPluginComponent, onPluginRegistered } from "./registry";
export function usePlugins() {
const [manifests, setManifests] = useState<PluginManifest[]>([]);
const [plugins, setPlugins] = useState<RegisteredPlugin[]>([]);
const [loading, setLoading] = useState(true);
const loadedScripts = useRef<Set<string>>(new Set());
// Fetch manifests on mount.
useEffect(() => {
api
.getPlugins()
.then((list) => {
setManifests(list);
if (list.length === 0) setLoading(false);
})
.catch(() => setLoading(false));
}, []);
// Load plugin assets when manifests arrive.
useEffect(() => {
if (manifests.length === 0) return;
for (const manifest of manifests) {
// Inject CSS if specified.
if (manifest.css) {
const cssUrl = `/dashboard-plugins/${manifest.name}/${manifest.css}`;
if (!document.querySelector(`link[href="${cssUrl}"]`)) {
const link = document.createElement("link");
link.rel = "stylesheet";
link.href = cssUrl;
document.head.appendChild(link);
}
}
// Load JS bundle.
const jsUrl = `/dashboard-plugins/${manifest.name}/${manifest.entry}`;
if (loadedScripts.current.has(jsUrl)) continue;
loadedScripts.current.add(jsUrl);
const script = document.createElement("script");
script.src = jsUrl;
script.async = true;
script.onerror = () => {
console.warn(`[plugins] Failed to load ${manifest.name} from ${jsUrl}`);
};
document.body.appendChild(script);
}
// Give plugins a moment to load and register, then stop loading state.
const timeout = setTimeout(() => setLoading(false), 2000);
return () => clearTimeout(timeout);
}, [manifests]);
// Listen for plugin registrations and resolve them against manifests.
useEffect(() => {
function resolvePlugins() {
const resolved: RegisteredPlugin[] = [];
for (const manifest of manifests) {
const component = getPluginComponent(manifest.name);
if (component) {
resolved.push({ manifest, component });
}
}
setPlugins(resolved);
// If all plugins registered, stop loading early.
if (resolved.length === manifests.length && manifests.length > 0) {
setLoading(false);
}
}
resolvePlugins();
const unsub = onPluginRegistered(resolvePlugins);
return unsub;
}, [manifests]);
return { plugins, manifests, loading };
}