feat(plugins): console-hosted plugin UI surface (host registry + SDK servePluginUi + console proxy/nav)

Implements planning/design/plugin-ui-surface.md (U1-U3): - host: in-memory lease-based plugin registry (mgmt/plugins.rs) — PUT/GET/DELETE /api/v1/plugins + GET /plugins/{id}/ui-credential; bearer+loopback only (not on the mTLS read-only allowlist); plugins.changed event; port-only registration (proxy always dials 127.0.0.1); secret never in the listing. - sdk: servePluginUi — loopback ephemeral bind + per-boot secret + constant-time check + /__health + static/SPA-fallback + register/renew(30s)/deregister via pf.request (skew-proof, D7). Example + tests. - console: /plugin-ui/{id}/** reverse proxy (server-side secret injection, cookie strip, SSE streaming, stale-secret 401-retry) + credential cache; BFF denylist for the credential endpoint; dynamic Plugins nav (desktop + mobile) fed by a polled list; iframe-in-shell page with health probe, offline card, open-in-tab, deep-link sync. Dev-mode /plugin-ui middleware in vite.config.ts. OpenAPI regen for the new endpoints follows in the next commit (built on Linux). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-18 01:49:42 +02:00
parent d579cd318e
commit ec84b30eae
19 changed files with 1674 additions and 6 deletions
@@ -0,0 +1,65 @@
+// The plugin directory the console reads to grow its nav (plugin-ui-surface §5). This is a
+// hand-written client (not orval-generated) so the nav works without regenerating the API client
+// for the new endpoints; it rides the same `/api` BFF path as every other call, so the bearer token
+// is injected server-side and the browser only ever sends its session cookie.
+import { useQuery } from "@tanstack/react-query";
+import {
+	Blocks,
+	Boxes,
+	Clapperboard,
+	Database,
+	FolderCog,
+	Gamepad2,
+	Home,
+	type LucideIcon,
+	Plug,
+	Puzzle,
+	Wrench,
+} from "lucide-react";
+import { apiFetch } from "@/api/fetcher";
+
+export interface PluginUiSummary {
+	port: number;
+	icon?: string;
+}
+
+export interface PluginSummary {
+	id: string;
+	title: string;
+	version?: string;
+	/** Present iff the plugin serves a UI (and thus gets a nav entry). */
+	ui?: PluginUiSummary;
+}
+
+// A curated lucide set for plugin nav icons. Importing lucide's full dynamic icon map would defeat
+// tree-shaking (U-S4), so a plugin picks a name from here; anything unknown falls back to Puzzle.
+const ICONS: Record<string, LucideIcon> = {
+	"gamepad-2": Gamepad2,
+	puzzle: Puzzle,
+	wrench: Wrench,
+	database: Database,
+	home: Home,
+	blocks: Blocks,
+	boxes: Boxes,
+	plug: Plug,
+	"folder-cog": FolderCog,
+	clapperboard: Clapperboard,
+};
+
+/** Resolve a registered icon name to a component (Puzzle fallback). */
+export const pluginIcon = (name?: string): LucideIcon =>
+	(name ? ICONS[name] : undefined) ?? Puzzle;
+
+/** Live plugin registrations, polled (and refetched on window focus) so the nav stays current. */
+export function usePlugins() {
+	return useQuery({
+		queryKey: ["plugins"],
+		queryFn: () => apiFetch<PluginSummary[]>("/api/v1/plugins"),
+		refetchInterval: 30_000,
+		refetchOnWindowFocus: true,
+	});
+}
+
+/** Only the plugins that surface a UI — the ones that get a nav entry. */
+export const uiPlugins = (list: PluginSummary[] | undefined): PluginSummary[] =>
+	(list ?? []).filter((p) => p.ui);
@@ -12,6 +12,7 @@ import {
 } from "lucide-react";
 import { motion, stagger } from "motion/react";
 import { type ReactNode, useState } from "react";
+import { pluginIcon, uiPlugins, usePlugins } from "@/api/plugins";
 import { BrandMark } from "@/components/brand-mark";
 import { Wordmark } from "@/components/wordmark";
 import { changeLocale, type Locale, locales, useLocale } from "@/lib/i18n";
@@ -91,6 +92,7 @@ export function AppShell({ children }: { children: ReactNode }) {
 						</MLink>
 					))}
 				</motion.nav>
+				<PluginNavSection />
 				<div className="mt-auto pt-4">
 					<LanguageSwitcher />
 				</div>
@@ -119,14 +121,54 @@ export function AppShell({ children }: { children: ReactNode }) {
 	);
 }

+/** Desktop sidebar: the dynamic "Plugins" group, fed by the plugin directory. Renders nothing until
+ * at least one plugin surfaces a UI — a host with no plugins sees zero extra chrome. */
+function PluginNavSection() {
+	const { data } = usePlugins();
+	const plugins = uiPlugins(data);
+	if (plugins.length === 0) return null;
+	return (
+		<div className="mt-6 flex flex-col gap-1">
+			<p className="px-3 pb-1 text-xs font-medium uppercase tracking-wide text-muted-foreground/70">
+				{m.nav_plugins()}
+			</p>
+			{plugins.map((p) => {
+				const Icon = pluginIcon(p.ui?.icon);
+				return (
+					<Link
+						key={p.id}
+						to="/plugins/$pluginId/$"
+						params={{ pluginId: p.id, _splat: "" }}
+						className="group relative flex items-center gap-3 rounded-md px-3 py-2 text-sm text-muted-foreground transition-colors hover:text-foreground"
+						activeProps={{
+							className: "bg-primary/15 text-foreground font-medium",
+						}}
+					>
+						<span
+							aria-hidden
+							className="pointer-events-none absolute inset-0 rounded-md bg-primary/0 transition-colors duration-200 group-hover:bg-primary/15"
+						/>
+						<Icon className="relative size-4" />
+						<span className="relative truncate">{p.title}</span>
+					</Link>
+				);
+			})}
+		</div>
+	);
+}
+
 /** Mobile bottom navigation (< sm): four pinned tabs + a "More" tab whose sheet holds the rest. */
 function MobileNav() {
 	const [moreOpen, setMoreOpen] = useState(false);
 	const pathname = useRouterState({ select: (s) => s.location.pathname });
-	// Highlight "More" when the current route lives in the overflow.
-	const overflowActive = MOBILE_OVERFLOW.some(
-		(n) => pathname === n.to || pathname.startsWith(`${n.to}/`),
-	);
+	const { data } = usePlugins();
+	const plugins = uiPlugins(data);
+	// Highlight "More" when the current route lives in the overflow — plugins included.
+	const overflowActive =
+		pathname.startsWith("/plugins/") ||
+		MOBILE_OVERFLOW.some(
+			(n) => pathname === n.to || pathname.startsWith(`${n.to}/`),
+		);
 	// Fixed two-line-tall label box so a 1- or 2-line label (labels vary by locale) keeps every icon
 	// at the same height.
 	const tab =
@@ -164,6 +206,22 @@ function MobileNav() {
 									<span className={lbl}>{label()}</span>
 								</Link>
 							))}
+							{plugins.map((p) => {
+								const Icon = pluginIcon(p.ui?.icon);
+								return (
+									<Link
+										key={p.id}
+										to="/plugins/$pluginId/$"
+										params={{ pluginId: p.id, _splat: "" }}
+										onClick={() => setMoreOpen(false)}
+										className={cn(tab, "rounded-md")}
+										activeProps={{ className: "text-[var(--brand-light)]" }}
+									>
+										<Icon className="size-5 shrink-0" />
+										<span className={lbl}>{p.title}</span>
+									</Link>
+								);
+							})}
 						</div>
 					</div>
 				)}
@@ -0,0 +1,8 @@
+import { createFileRoute } from "@tanstack/react-router";
+import { SectionPlugin } from "@/sections/Plugins";
+
+// A plugin's console-hosted UI (plugin-ui-surface). The `$` splat carries the plugin's own path so
+// deep links survive a reload; the section maps it to the iframe src and keeps it in sync.
+export const Route = createFileRoute("/plugins/$pluginId/$")({
+	component: SectionPlugin,
+});
@@ -0,0 +1,136 @@
+// A plugin's UI, embedded in the console (plugin-ui-surface §5). We probe the plugin's liveness
+// first and only mount the iframe when it answers — otherwise the iframe would show the proxy's raw
+// 502. The iframe is same-origin (proxied through /plugin-ui), so the plugin can talk to its own
+// loopback REST with the operator's session and, optionally, keep the address bar in sync by posting
+// `{ type: "pf-ui:navigate", path }` to the parent.
+import { useQuery } from "@tanstack/react-query";
+import { getRouteApi, useNavigate } from "@tanstack/react-router";
+import { ExternalLink, RefreshCw } from "lucide-react";
+import { type FC, useEffect, useMemo, useRef } from "react";
+import { pluginIcon, usePlugins } from "@/api/plugins";
+import { Button } from "@/components/ui/button";
+import { useLocale } from "@/lib/i18n";
+import { m } from "@/paraglide/messages";
+
+const route = getRouteApi("/plugins/$pluginId/$");
+
+export const SectionPlugin: FC = () => {
+	useLocale();
+	const { pluginId, _splat } = route.useParams();
+	const navigate = useNavigate();
+	const iframeRef = useRef<HTMLIFrameElement>(null);
+
+	// Header metadata (title/version/icon) from the directory; falls back to the id.
+	const { data: plugins } = usePlugins();
+	const meta = plugins?.find((p) => p.id === pluginId);
+	const Icon = pluginIcon(meta?.ui?.icon);
+	const title = meta?.title ?? pluginId;
+
+	// Liveness: a 200 from /__health means the plugin is up. On failure we stop polling and show the
+	// offline card (the manual Retry re-probes).
+	const health = useQuery({
+		queryKey: ["plugin-health", pluginId],
+		queryFn: async () => {
+			const r = await fetch(`/plugin-ui/${pluginId}/__health`, {
+				credentials: "same-origin",
+			});
+			if (!r.ok) throw new Error(`health ${r.status}`);
+			return true;
+		},
+		retry: false,
+		refetchInterval: (q) => (q.state.status === "error" ? false : 20_000),
+	});
+
+	// The iframe src is fixed at the initial deep-link path; the plugin's own in-app navigation drives
+	// the console URL via postMessage (below), never the src — so there's no reload loop.
+	// biome-ignore lint/correctness/useExhaustiveDependencies: intentionally pinned to the initial path
+	const initialSrc = useMemo(
+		() => `/plugin-ui/${pluginId}/${_splat ?? ""}`,
+		[pluginId],
+	);
+
+	// Keep the console address bar in sync with the plugin's internal routing.
+	useEffect(() => {
+		const onMessage = (e: MessageEvent) => {
+			if (e.source !== iframeRef.current?.contentWindow) return;
+			const data = e.data as { type?: string; path?: string };
+			if (data?.type === "pf-ui:navigate" && typeof data.path === "string") {
+				navigate({
+					to: "/plugins/$pluginId/$",
+					params: { pluginId, _splat: data.path.replace(/^\//, "") },
+					replace: true,
+				});
+			}
+		};
+		window.addEventListener("message", onMessage);
+		return () => window.removeEventListener("message", onMessage);
+	}, [pluginId, navigate]);
+
+	return (
+		<div className="flex h-[calc(100dvh-7rem)] min-h-[480px] flex-col gap-3 sm:h-[calc(100dvh-5rem)]">
+			{/* Header strip: identity + open-in-new-tab (the plugin stands alone full-window too). */}
+			<div className="flex items-center gap-3">
+				<Icon className="size-5 text-muted-foreground" />
+				<h1 className="text-lg font-semibold">{title}</h1>
+				{meta?.version && (
+					<span className="rounded bg-muted px-1.5 py-0.5 text-xs text-muted-foreground">
+						v{meta.version}
+					</span>
+				)}
+				<a
+					href={`/plugin-ui/${pluginId}/`}
+					target="_blank"
+					rel="noreferrer"
+					className="ml-auto inline-flex items-center gap-1.5 text-sm text-muted-foreground transition-colors hover:text-foreground"
+				>
+					<ExternalLink className="size-4" />
+					{m.plugin_open_new_tab()}
+				</a>
+			</div>
+
+			{health.isError ? (
+				<OfflineCard title={title} onRetry={() => health.refetch()} />
+			) : health.isSuccess ? (
+				<iframe
+					ref={iframeRef}
+					src={initialSrc}
+					title={title}
+					className="w-full flex-1 rounded-lg border bg-card"
+					// The plugin is operator-installed code on our own origin (no new trust boundary —
+					// plugin-ui-surface §7.4); allow it to run scripts, forms, popups, and full-window.
+					sandbox="allow-scripts allow-forms allow-popups allow-same-origin allow-modals"
+					allow="fullscreen"
+				/>
+			) : (
+				// Probing: a calm shimmer rather than a flash of empty frame.
+				<div className="flex-1 animate-pulse rounded-lg border bg-card/50" />
+			)}
+		</div>
+	);
+};
+
+const OfflineCard: FC<{ title: string; onRetry: () => void }> = ({
+	title,
+	onRetry,
+}) => (
+	<div className="flex flex-1 items-center justify-center rounded-lg border border-dashed">
+		<div className="flex max-w-md flex-col items-center gap-3 p-8 text-center">
+			<h2 className="text-base font-semibold">{m.plugin_offline_title()}</h2>
+			<p className="text-sm text-muted-foreground">
+				<span className="font-medium text-foreground">{title}</span> —{" "}
+				{m.plugin_offline_hint()}
+			</p>
+			{/* The exact runner commands, so the operator can act without leaving the page. */}
+			<pre className="w-full overflow-x-auto rounded-md bg-muted p-3 text-left text-xs text-muted-foreground">
+				<code>
+					systemctl --user status punktfunk-scripting{"\n"}
+					Get-ScheduledTask PunktfunkScripting{"  # Windows"}
+				</code>
+			</pre>
+			<Button variant="outline" size="sm" onClick={onRetry}>
+				<RefreshCw className="size-4" />
+				{m.plugin_retry()}
+			</Button>
+		</div>
+	</div>
+);