Self-hosted, plugin-based server management.
TypeScript dockerhomelabpluginsrdpremote-desktopself-hostedserver-managementsftpsshterminaltermixvnc
import { useEffect, type ComponentType } from "react";
import type { Tab } from "@/types/ui-types";
import type {
Disposer,
PluginManifest,
TermixApp,
} from "@termix-ssh/plugin-sdk/frontend";
import {
PLUGIN_SETTINGS_CHANGED_EVENT,
type PluginContributions,
} from "@/api/plugins-api";
import { registerRailItem } from "@/sidebar/rail-items";
import { registerTabType, type TabRenderProps } from "@/shell/tab-registry";
import {
registerCompanionDef,
registerCompanionLayoutDef,
toggleCompanion,
type CompanionDefaults,
type CompanionRenderProps,
} from "@/shell/companions";
import { registerPanel, type PanelRenderProps } from "@/shell/panel-registry";
import {
registerHostEditorSection,
type HostEditorSectionRenderProps,
} from "@/sidebar/HostManagerTabs";
import {
registerHostAction,
registerHostBadge,
registerHostEditorToolbarItem,
registerHostStatusIndicator,
registerHostContextMenuItem,
} from "@/sidebar/host-contributions";
import {
registerPaletteEntry,
registerPaletteGroup,
type PaletteItemDef,
} from "@/shell/palette-registry";
import {
registerKeybindingAction,
registerKeybindingDefault,
type KeybindingEditorProps,
} from "@/shell/keybinding-registry";
import { registerHostProtocol } from "@/sidebar/host-protocols";
import {
registerDashboardCard,
type DashboardCardRenderProps,
} from "@/dashboard/dashboard-cards-registry";
import { registerExtension } from "./extension-registry";
import { registerSettingsComponent } from "@/settings/settings-components";
import {
declareActionSlot,
invokeAction,
registerAction,
registerSlotContribution,
} from "@/shell/action-registry";
import { pluginApiFor, pluginFetch, pluginWsUrl } from "@/lib/plugin-transport";
import { registerPluginComponent } from "./component-registry";
import {
onboardingSteps,
sectionPosition,
} from "@/onboarding/onboarding-registry";
import { pluginStepKey } from "@/types/onboarding";
import type { LucideIcon } from "lucide-react";
import {
registerLoginMethod,
registerSecondFactor,
registerSshAuthEditor,
} from "./auth-registry";
import {
pluginHostBridge,
resolvePluginPermission,
toPluginHostRecord,
} from "./bridge";
import { shell, shellHost, tabsApi } from "./shell-bridge";
import { onRemoteServerChange, remoteServerUrl } from "./desktop";
import { isElectron } from "@/lib/electron";
import {
withPluginContext,
withPluginScope,
withIconBoundary,
guardCallback,
} from "./scope";
import { registerLayout as registerLayoutComponent } from "@/look/layout-registry";
import {
scopeHostArgs,
scopeHostCallback,
scopeHostFields,
} from "./host-scope";
import { manifestDeclares, type ViewKind } from "./view-ownership";
import { pluginKey } from "@/lib/plugin-i18n";
import { pluginDocsPage, pluginDocsUrl } from "@termix-ssh/plugin-sdk/docs";
import { hasPermission } from "@/hooks/use-permissions";
import i18n from "@/i18n/i18n";
const ONBOARDING_ID = /^[a-z0-9][a-z0-9-]{0,63}$/;
export interface PluginAppHandle {
app: TermixApp;
/** Runs every disposer, newest first, isolating failures. */
dispose: () => void;
}
function createDocsApi(manifest: PluginManifest): TermixApp["docs"] {
const url = pluginDocsUrl(manifest?.docs);
const page = (name?: string, anchor?: string) =>
url ? pluginDocsPage(url, name, anchor) : null;
return {
url,
page,
open(name, anchor) {
const target = page(name, anchor);
if (target) window.open(target, "_blank", "noopener,noreferrer");
},
};
}
/**
* Builds the object a plugin's `activate(app)` receives.
*
* Every registration goes into one bag, so disabling the plugin removes all
* of it whatever the plugin's own `deactivate` does. Components are wrapped
* in the plugin's scope as they are registered, which is what gives the SDK
* hooks their plugin id and keeps a crash inside the plugin's own box.
*/
export function createPluginApp(
pluginId: string,
manifest: PluginManifest,
contributes: PluginContributions | null,
options: { guest?: boolean } = {},
): PluginAppHandle {
const bag: Disposer[] = [];
let disposed = false;
const track = (disposer: Disposer): Disposer => {
// An activate that outlived its timeout, or ran on after a disable, still
// registers things. Nothing will dispose them later, so undo them now.
if (disposed) {
try {
disposer();
} catch {
// A failing disposer must not throw into the plugin's activate.
}
return () => {};
}
bag.push(disposer);
return () => {
const index = bag.indexOf(disposer);
if (index >= 0) bag.splice(index, 1);
disposer();
};
};
const scoped = <P extends object>(component: ComponentType<P>) =>
withPluginScope(pluginId, component);
const key = (value: string) => pluginKey(pluginId, value);
// Every host a plugin callback receives carries only this plugin's settings.
const hostCallback = <F extends (...args: never[]) => unknown>(
fn: F | undefined,
): F | undefined => scopeHostCallback(fn, pluginId);
const requireStepId = (id: string, what: string) => {
if (typeof id !== "string" || !ONBOARDING_ID.test(id)) {
throw new Error(`${pluginId}: ${what} id "${id}" is not valid`);
}
};
const requireDeclared = (kind: ViewKind, id: string, what: string) => {
if (!manifestDeclares(contributes, kind, id)) {
const field =
kind === "tab"
? "contributes.tabs"
: kind === "panel"
? "contributes.panels or contributes.tabs"
: kind === "layout"
? "contributes.layouts"
: "contributes.dashboardCards";
throw new Error(
`${pluginId}: ${what} "${id}" is not declared in manifest ${field}`,
);
}
};
const app: TermixApp = {
pluginId,
manifest,
guest: !!options.guest,
registerRailItem(item) {
requireDeclared("panel", item.id, "rail item");
return track(
registerRailItem({
id: item.id,
icon: withIconBoundary(
pluginId,
item.icon as unknown as LucideIcon,
) as unknown as LucideIcon,
labelKey: key(item.titleKey),
kind: item.kind === "tab" ? "tab" : undefined,
hideable: item.hideable,
simplePreset: item.simplePreset,
promotable: item.promotable,
rightDockable: item.rightDockable,
mobilePrimary: item.mobilePrimary,
electronOnly: item.electronOnly,
separatorAfter: item.separatorAfter ?? true,
group: item.group,
hidden: item.hidden,
after: item.after,
order: item.order,
placement: item.placement,
useBadge: item.useBadge,
pluginId,
permission: item.permission
? resolvePluginPermission(pluginId, item.permission)
: undefined,
}),
);
},
registerPanel(id, component, options) {
requireDeclared("panel", id, "panel");
return track(
registerPanel({
id,
pluginId,
component: scoped(
component as unknown as ComponentType<PanelRenderProps>,
),
keepMounted: options?.keepMounted,
}),
);
},
registerCompanion(id, component, options = {}) {
const useDefaults = options.useDefaults;
const Defaults = useDefaults
? scoped(function CompanionDefaultsReader({
onValue,
}: {
onValue: (value: CompanionDefaults) => void;
}) {
const value = useDefaults();
const { open, side, size, edgeButton } = value;
useEffect(() => {
onValue({ open, side, size, edgeButton });
}, [onValue, open, side, size, edgeButton]);
return null;
})
: undefined;
return track(
registerCompanionDef({
id: `${pluginId}.${id}`,
pluginId,
component: scoped(
component as unknown as ComponentType<CompanionRenderProps>,
),
icon: withIconBoundary(pluginId, options.icon as never) as never,
titleKey: options.titleKey ? key(options.titleKey) : undefined,
order: options.order,
tabTypes: options.tabTypes,
when: options.when as never,
Defaults,
}),
);
},
registerCompanionLayout(tabType, resolve) {
return track(
registerCompanionLayoutDef({
id: `${pluginId}.${tabType}`,
tabTypes: [tabType],
resolve: resolve as never,
}),
);
},
toggleCompanion(tab, id) {
toggleCompanion(
tab as unknown as Tab,
id ? `${pluginId}.${id}` : undefined,
);
},
registerTab(type, component, options = {}) {
requireDeclared("tab", type, "tab type");
return track(
registerTabType({
id: type,
pluginId,
component: scoped(
component as unknown as ComponentType<TabRenderProps>,
),
icon: withIconBoundary(pluginId, options.icon as never) as never,
titleKey: options.titleKey ? key(options.titleKey) : undefined,
requiresHost: options.requiresHost,
noHostMessageKey: options.noHostMessageKey
? key(options.noHostMessageKey)
: undefined,
persistent: options.persistent,
singleton: options.singleton,
session: options.session,
hostless: options.hostless,
restore: options.restore as never,
activityTypes: options.activityTypes,
standalone: options.standalone
? scoped(options.standalone)
: undefined,
standaloneViews: options.standaloneViews,
panelFrame: options.panelFrame,
inLayouts: options.inLayouts,
commandTarget: options.commandTarget,
ownBackground: options.ownBackground,
multiInstance: options.multiInstance,
preload: options.preload,
}),
);
},
registerHostEditorSection(section) {
return track(
registerHostEditorSection({
id: section.id,
pluginId,
group: section.group,
labelKey: key(section.titleKey),
icon: withIconBoundary(pluginId, section.icon as never) as never,
order: section.order,
visible: section.visible,
defaults: section.defaults,
component: scoped(
section.component as unknown as ComponentType<HostEditorSectionRenderProps>,
),
}),
);
},
registerHostAction(action) {
return track(
registerHostAction({
...action,
titleKey: key(action.titleKey),
pluginId,
icon: withIconBoundary(pluginId, action.icon as never) as never,
when: hostCallback(action.when) as never,
run: hostCallback(action.run) as never,
// Called while the host list renders, so a throw must not escape.
label: guardCallback(
pluginId,
hostCallback(
action.label as ((...args: unknown[]) => unknown) | undefined,
),
undefined,
) as never,
items: guardCallback(
pluginId,
action.items
? (...args: unknown[]) =>
(
action.items as (
...a: unknown[]
) => { run: (...a: never[]) => unknown }[]
)(...scopeHostArgs(args, pluginId))?.map((item) => ({
...item,
run: hostCallback(item.run),
}))
: undefined,
undefined,
) as never,
}),
);
},
registerHostProtocol(protocol) {
return track(
registerHostProtocol({
...protocol,
pluginId,
titleKey: key(protocol.titleKey),
descriptionKey: protocol.descriptionKey
? key(protocol.descriptionKey)
: undefined,
connectionOriginNoteKey: protocol.connectionOriginNoteKey
? key(protocol.connectionOriginNoteKey)
: undefined,
}),
);
},
registerHostBadge(badge) {
return track(
registerHostBadge({
id: badge.id,
pluginId,
when: hostCallback(badge.when) as never,
component: scoped(badge.component) as never,
order: badge.order,
}),
);
},
registerHostStatusIndicator(indicator) {
return track(
registerHostStatusIndicator({
id: indicator.id,
pluginId,
when: hostCallback(indicator.when) as never,
component: scoped(indicator.component) as never,
order: indicator.order,
}),
);
},
registerHostEditorToolbarItem(item) {
return track(
registerHostEditorToolbarItem({
id: item.id,
pluginId,
when: hostCallback(item.when) as never,
component: scoped(item.component) as never,
order: item.order,
}),
);
},
registerHostContextMenuItem(item) {
return track(
registerHostContextMenuItem({
...item,
titleKey: key(item.titleKey),
pluginId,
when: hostCallback(item.when) as never,
run: hostCallback(item.run) as never,
}),
);
},
registerPaletteEntry(entry) {
return track(
registerPaletteEntry({
...entry,
titleKey: key(entry.titleKey),
pluginId,
when: hostCallback(entry.when) as never,
run: hostCallback(entry.run) as never,
}),
);
},
registerPaletteGroup(group) {
return track(
registerPaletteGroup({
id: group.id,
pluginId,
titleKey: key(group.titleKey),
order: group.order,
showWhenEmpty: group.showWhenEmpty,
load: group.load as unknown as () => Promise<PaletteItemDef[]>,
}),
);
},
registerKeybindingAction(action) {
const declared = (manifest.contributes?.keybindingActions ?? []).some(
(entry) => entry.id === action.id,
);
if (!declared) {
throw new Error(
`${pluginId}: keybinding action "${action.id}" is not declared in manifest contributes.keybindingActions`,
);
}
const validate = action.validate;
return track(
registerKeybindingAction({
id: action.id,
pluginId,
labelKey: key(action.titleKey),
scope: action.scope ?? "session",
editor: action.editor
? (scoped(action.editor) as ComponentType<KeybindingEditorProps>)
: undefined,
summary: action.summary
? (scoped(action.summary) as ComponentType<KeybindingEditorProps>)
: undefined,
validate: validate
? (value) => {
const problem = validate(value);
return problem ? key(problem) : null;
}
: undefined,
run: action.run,
}),
);
},
registerKeybindingDefault(binding) {
return track(
registerKeybindingDefault({
id: binding.id,
pluginId,
combo: binding.combo,
descriptionKey: key(binding.descriptionKey),
}),
);
},
registerDashboardCard(card) {
requireDeclared("card", card.id, "dashboard card");
return track(
registerDashboardCard({
id: card.id,
pluginId,
titleKey: key(card.titleKey),
defaultHeight: card.defaultHeight,
defaultPanel: card.defaultPanel,
frame: card.frame,
component: scoped(
card.component as unknown as ComponentType<DashboardCardRenderProps>,
),
}),
);
},
registerExtension(pointId, extension) {
const components = extension.components
? Object.fromEntries(
Object.entries(extension.components).map(([name, component]) => [
name,
scoped(component),
]),
)
: undefined;
return track(
registerExtension(pointId, { ...extension, components, pluginId }),
);
},
listHosts: () => pluginHostBridge.core.listHosts(pluginId),
getHost(hostId) {
const host = shellHost(hostId);
return host ? toPluginHostRecord(host, pluginId) : undefined;
},
registerSettingsComponent(componentId, component) {
return track(
registerSettingsComponent(pluginId, componentId, scoped(component)),
);
},
registerAction(id, handler, options = {}) {
return track(
registerAction(id, hostCallback(handler), {
permission: options.permission
? resolvePluginPermission(pluginId, options.permission)
: undefined,
pluginId,
}),
);
},
declareActionSlot(slot) {
return track(declareActionSlot(slot));
},
registerSlotContribution(slotId, contribution) {
return track(
registerSlotContribution(slotId, {
...contribution,
titleKey: key(contribution.titleKey),
descriptionKey: contribution.descriptionKey
? key(contribution.descriptionKey)
: undefined,
component: contribution.component
? scoped(contribution.component)
: undefined,
when: contribution.when
? (context: Record<string, unknown>) =>
contribution.when!(scopeHostFields(context, pluginId))
: undefined,
pluginId,
}),
);
},
registerOnboardingStep(step) {
requireStepId(step.id, "onboarding step");
const version = step.version ?? 1;
if (!Number.isInteger(version) || version < 1) {
throw new Error(
`${pluginId}: onboarding step "${step.id}" needs a whole version of 1 or more`,
);
}
const when = guardCallback(pluginId, step.when, false);
return track(
onboardingSteps.register({
id: pluginStepKey(pluginId, step.id),
pluginId,
version,
titleKey: key(step.titleKey),
descriptionKey: step.descriptionKey
? key(step.descriptionKey)
: undefined,
icon: step.icon
? (withIconBoundary(pluginId, step.icon as never) as never)
: undefined,
Component: scoped(step.component),
audience: step.audience ?? "all",
permission: step.permission
? resolvePluginPermission(pluginId, step.permission)
: undefined,
position: sectionPosition(step.section, step.order, step.position),
replaces: step.replaces,
isRelevant: when
? (ctx) =>
when({
isAdmin: ctx.isAdmin,
isDesktop: ctx.isDesktop,
mode: ctx.mode,
}) === true
: undefined,
}),
);
},
invokeAction: (id, ...args) => invokeAction(id, ...args),
registerComponent(id, component) {
return track(registerPluginComponent(id, scoped(component)));
},
registerSshAuthEditor(editor) {
return track(
registerSshAuthEditor({
id: editor.authType,
pluginId,
titleKey: key(editor.titleKey),
hintKey: editor.hintKey ? key(editor.hintKey) : undefined,
component: editor.component
? (scoped(editor.component) as never)
: undefined,
}),
);
},
registerLoginMethod(method) {
return track(
registerLoginMethod({
...method,
titleKey: key(method.titleKey),
pluginId,
component: scoped(method.component) as never,
enrollment: method.enrollment
? (scoped(method.enrollment) as never)
: undefined,
}),
);
},
registerSecondFactorUI(factor) {
return track(
registerSecondFactor({
...factor,
titleKey: key(factor.titleKey),
pluginId,
component: scoped(factor.component) as never,
enrollment: factor.enrollment
? (scoped(factor.enrollment) as never)
: undefined,
}),
);
},
registerLayout(layout) {
requireDeclared("layout", layout.id, "layout");
return track(
registerLayoutComponent({
id: layout.id,
pluginId,
component: withPluginContext(pluginId, layout.component),
mobileComponent: layout.mobileComponent
? withPluginContext(pluginId, layout.mobileComponent)
: undefined,
defaultTheme: layout.defaultTheme,
}),
);
},
t: ((key: string, options?: Record<string, unknown> | string) =>
i18n.t(
pluginKey(pluginId, key),
options as Record<string, unknown>,
)) as TermixApp["t"],
hasPermission: async (permission) => {
try {
return await hasPermission(
resolvePluginPermission(pluginId, permission),
);
} catch {
return false;
}
},
api: pluginHostBridge.getApi(pluginId),
apiFor: (origin) =>
pluginApiFor(
pluginId,
origin as never,
pluginHostBridge.getApi(pluginId) as never,
) as unknown as TermixApp["api"],
fetch: (path, init) => pluginFetch(pluginId, path, init),
wsUrl: (path, options) =>
pluginWsUrl(pluginId, path, options as never) as ReturnType<
TermixApp["wsUrl"]
>,
tabs: {
...tabsApi,
openTab: shell.openTab as TermixApp["tabs"]["openTab"],
openSingletonTab: shell.openSingletonTab,
connectHost: shell.connectHost as TermixApp["tabs"]["connectHost"],
closeTab: shell.closeTab,
onChange: (listener) => track(tabsApi.onChange(listener)),
onReady: (listener) => track(tabsApi.onReady(listener)),
},
confirm: (options) => shell.confirm!(options),
docs: createDocsApi(manifest),
desktop: {
available: isElectron(),
remoteServerUrl,
onRemoteServerChange: (listener) => track(onRemoteServerChange(listener)),
},
onSettingsChanged: (listener) => {
const handler = (event: Event) => {
const detail = (event as CustomEvent).detail as {
pluginId?: string;
scope: "admin" | "user" | "host";
hostId?: number;
};
if (detail?.pluginId !== pluginId) return;
listener({ scope: detail.scope, hostId: detail.hostId });
};
window.addEventListener(PLUGIN_SETTINGS_CHANGED_EVENT, handler);
return track(() =>
window.removeEventListener(PLUGIN_SETTINGS_CHANGED_EVENT, handler),
);
},
onDispose(dispose) {
if (disposed) {
dispose();
return;
}
bag.push(dispose);
},
};
return {
app,
dispose() {
disposed = true;
while (bag.length > 0) {
const disposer = bag.pop()!;
try {
disposer();
} catch (error) {
console.error(`[plugins] ${pluginId}: a disposer threw`, error);
}
}
},
};
}