Files
kandev/apps/web/lib/plugins/registry.ts
T
Kandev Agent c53f699714 feat: add plugin system with grpc runtime and native ui plugins
- go plugin backends ship as release tarballs (per-platform binaries, checksums) that
  kandev installs from url/upload or filesystem sideload+sync, then spawns and
  supervises via hashicorp/go-plugin (unix socket / loopback tcp+automtls)
- strict typed grpc contract (kandev.plugin.v1): DeliverEvent/InvokeTool/HandleWebhook
  plus a capability-gated host service (state, secrets, emit); author sdk in
  pkg/pluginsdk; packaging cli in cmd/plugin-pack
- native frontend bundles: window.registerKandevPlugin + registry/host loader with
  dynamic routes, nav items, slots and ws handlers; plugins settings page with
  install dialog, sync button and enable/disable/uninstall
- gated behind the plugins feature flag (prod off, dev/e2e on); covered by unit and
  integration tests plus playwright e2e against a real packaged fixture plugin

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-16 17:55:45 +01:00

158 lines
5.0 KiB
TypeScript

/**
* Reactive singleton `PluginRegistry` (docs/plans/plugins/PLUGIN-API.md).
*
* Holds every registration made by every loaded plugin, tracks the owning
* pluginId so a disabled/uninstalled plugin can be bulk-revoked, and exposes
* a tiny external-store subscription so React components re-render on
* registration changes (`usePluginRegistry()`).
*
* `pluginRegistry.forPlugin(pluginId)` returns the exact `PluginRegistry`
* shape from the frozen contract (no pluginId param on the register*
* methods) — this is what `host.ts` passes into a plugin's `initialize()`.
*/
import { useSyncExternalStore } from "react";
import type { NavItem, PluginRegistry, SlotComponent, WsHandler } from "./types";
import type { ComponentType } from "react";
interface Owned<T> {
pluginId: string;
value: T;
}
interface RouteRegistration {
path: string;
Component: ComponentType;
}
interface SlotRegistration {
slot: string;
Component: SlotComponent;
}
interface WsHandlerRegistration {
action: string;
handler: WsHandler;
}
function removeByPlugin<T>(list: Owned<T>[], pluginId: string): Owned<T>[] {
return list.filter((entry) => entry.pluginId !== pluginId);
}
class PluginRegistryStore {
private routes: Owned<RouteRegistration>[] = [];
private settingsRoutes: Owned<RouteRegistration>[] = [];
private navItems: Owned<NavItem>[] = [];
private slotComponents: Owned<SlotRegistration>[] = [];
private wsHandlers: Owned<WsHandlerRegistration>[] = [];
private listeners = new Set<() => void>();
private version = 0;
subscribe = (listener: () => void): (() => void) => {
this.listeners.add(listener);
return () => {
this.listeners.delete(listener);
};
};
getVersion = (): number => this.version;
registerRoute(pluginId: string, path: string, Component: ComponentType): void {
this.routes.push({ pluginId, value: { path, Component } });
this.notify();
}
registerSettingsRoute(pluginId: string, path: string, Component: ComponentType): void {
this.settingsRoutes.push({ pluginId, value: { path, Component } });
this.notify();
}
registerNavItem(pluginId: string, item: NavItem): void {
this.navItems.push({ pluginId, value: item });
this.notify();
}
registerComponent(pluginId: string, slot: string, Component: SlotComponent): void {
this.slotComponents.push({ pluginId, value: { slot, Component } });
this.notify();
}
registerWsHandler(pluginId: string, action: string, handler: WsHandler): void {
this.wsHandlers.push({ pluginId, value: { action, handler } });
this.notify();
}
/** Bulk-revoke every registration owned by `pluginId` (disable/uninstall). */
unregisterPlugin(pluginId: string): void {
const before = this.totalCount();
this.routes = removeByPlugin(this.routes, pluginId);
this.settingsRoutes = removeByPlugin(this.settingsRoutes, pluginId);
this.navItems = removeByPlugin(this.navItems, pluginId);
this.slotComponents = removeByPlugin(this.slotComponents, pluginId);
this.wsHandlers = removeByPlugin(this.wsHandlers, pluginId);
if (this.totalCount() !== before) this.notify();
}
getRoutes(): RouteRegistration[] {
return this.routes.map((entry) => entry.value);
}
getSettingsRoutes(): RouteRegistration[] {
return this.settingsRoutes.map((entry) => entry.value);
}
getNavItems(): NavItem[] {
return this.navItems.map((entry) => entry.value);
}
getSlotComponents(slot: string): SlotComponent[] {
return this.slotComponents
.filter((entry) => entry.value.slot === slot)
.map((entry) => entry.value.Component);
}
getWsHandlers(action: string): WsHandler[] {
return this.wsHandlers
.filter((entry) => entry.value.action === action)
.map((entry) => entry.value.handler);
}
/** Registry view scoped to one plugin — matches the frozen `PluginRegistry` contract. */
forPlugin(pluginId: string): PluginRegistry {
return {
registerRoute: (path, Component) => this.registerRoute(pluginId, path, Component),
registerNavItem: (item) => this.registerNavItem(pluginId, item),
registerSettingsRoute: (path, Component) =>
this.registerSettingsRoute(pluginId, path, Component),
registerComponent: (slot, Component) => this.registerComponent(pluginId, slot, Component),
registerWsHandler: (action, handler) => this.registerWsHandler(pluginId, action, handler),
};
}
private totalCount(): number {
return (
this.routes.length +
this.settingsRoutes.length +
this.navItems.length +
this.slotComponents.length +
this.wsHandlers.length
);
}
private notify(): void {
this.version += 1;
this.listeners.forEach((listener) => listener());
}
}
export const pluginRegistry = new PluginRegistryStore();
/** Snapshot hook: re-renders the caller whenever any plugin registration changes. */
export function usePluginRegistry(): PluginRegistryStore {
useSyncExternalStore(
pluginRegistry.subscribe,
pluginRegistry.getVersion,
pluginRegistry.getVersion,
);
return pluginRegistry;
}