@termix-ssh/plugin-sdk 1.0.0

package/dist/frontend.js

@@ -0,0 +1,388 @@
+/**
+ * The frontend contract: what a plugin's frontend entry receives, and the
+ * hooks its components use.
+ *
+ * A plugin frontend is `src/frontend/index.tsx` exporting `activate(app)` and
+ * optionally `deactivate()`. Everything it contributes goes through `app`, and
+ * everything registered there is removed when the plugin is disabled, without
+ * a page reload.
+ *
+ * This module has no runtime dependencies. The hooks delegate to a host that
+ * core installs at startup (`__setPluginHost`), because React, i18next and the
+ * shell's state all live in core and must be one instance across the shell
+ * and every plugin bundle.
+ */
+import { useCallback, useEffect, useRef, useState } from "react";
+/** Stands in for a saved protocol secret the editor has not changed. */
+export const HOST_PROTOCOL_SECRET_KEPT = "existing_protocol_secret";
+export function definePluginFrontend(plugin) {
+    return plugin;
+}
+let host = null;
+/**
+ * Called once by core, before any plugin loads. Not part of the plugin API:
+ * once set it cannot be swapped, so a plugin cannot replace the bridge every
+ * other plugin talks through.
+ */
+export function __setPluginHost(bridge) {
+    if (host && bridge !== host) {
+        throw new Error("@termix-ssh/plugin-sdk/frontend: the plugin host is already set");
+    }
+    host = bridge;
+}
+/**
+ * Set by the shared test setup, so a plugin component rendered on its own in a
+ * unit test still has hooks. A global rather than an import, because the test
+ * setup and the component can load different copies of this module.
+ */
+const TEST_HOST_KEY = "__termixTestPluginHost";
+function requireHost() {
+    const fallback = globalThis[TEST_HOST_KEY];
+    if (!host && fallback)
+        return fallback;
+    if (!host) {
+        throw new Error("@termix-ssh/plugin-sdk/frontend: no plugin host. Hooks only work inside Termix or renderWithApp().");
+    }
+    return host;
+}
+/** The id of the plugin that registered the component being rendered. */
+export function usePluginId() {
+    return requireHost().usePluginId();
+}
+/**
+ * Translation bound to this plugin's namespace. Keys the plugin does not
+ * define fall back to core's shared strings (common.*, hosts.*).
+ */
+export function useTranslation() {
+    const bridge = requireHost();
+    return bridge.useTranslation(bridge.usePluginId());
+}
+/**
+ * Whether the current user holds a permission. A short name resolves to this
+ * plugin's own namespace, a dotted id is taken as given. UI only: the backend
+ * route checks again.
+ */
+export function usePermission(permission) {
+    const bridge = requireHost();
+    return bridge.usePermission(bridge.usePluginId(), permission);
+}
+export function useSettings(scope, hostId) {
+    const bridge = requireHost();
+    return bridge.useSettings(bridge.usePluginId(), scope, hostId);
+}
+export function useHost(hostId) {
+    return requireHost().useHost(hostId);
+}
+export function useHosts() {
+    return requireHost().useHosts();
+}
+/**
+ * Core's status for one host, kept current by the shell's own polling. Null
+ * outside the app shell (a standalone window) and for hosts with status
+ * checks off.
+ */
+export function useHostStatus(hostId) {
+    return requireHost().useHostStatus(hostId);
+}
+export function useCurrentUser() {
+    return requireHost().useCurrentUser();
+}
+export function useTheme() {
+    return requireHost().useTheme();
+}
+export function useToast() {
+    return requireHost().toast;
+}
+export function logActivity(type, hostId, hostName) {
+    return requireHost().core.logActivity(type, hostId, hostName);
+}
+/** Tells the shell hosts were added or changed, so its lists reload. */
+export function notifyHostsChanged() {
+    requireHost().core.notifyHostsChanged();
+}
+/** How the user wants host status shown: the brand accent, or green/red. */
+export function getHostStatusColorScheme() {
+    return requireHost().core.getHostStatusColorScheme();
+}
+/** The desktop app's local backend token, or null in a browser. */
+export function getLocalAuthToken() {
+    return requireHost().core.getLocalAuthToken();
+}
+export function getHostPassword(hostId, field) {
+    return requireHost().core.getHostPassword(hostId, field);
+}
+export function patchOpenTab(instanceId, updates) {
+    return requireHost().core.patchOpenTab(instanceId, updates);
+}
+export function getCustomKeybindings() {
+    return requireHost().core.getCustomKeybindings();
+}
+export function runKeybindingAction(action, context) {
+    return requireHost().core.runKeybindingAction(action, context);
+}
+export function getClientPreference(name) {
+    return requireHost().core.getClientPreference(name);
+}
+export function setClientPreference(name, value) {
+    requireHost().core.setClientPreference(name, value);
+}
+export function listCredentials() {
+    return requireHost().core.listCredentials();
+}
+export function usePluginApi() {
+    const bridge = requireHost();
+    return bridge.getApi(bridge.usePluginId());
+}
+/**
+ * This plugin's client for a resolved connection origin: "remote" reaches the
+ * desktop app's connected remote server, anything else is usePluginApi's.
+ */
+export function usePluginApiFor(origin) {
+    const bridge = requireHost();
+    return bridge.getApiFor(bridge.usePluginId(), origin);
+}
+/**
+ * This plugin's Appearance area: the preset it declared in
+ * contributes.uiPresets for the user's level, with the user's changes on top.
+ * `set` saves one change; null clears it back to the preset.
+ */
+export function usePluginUiPreferences() {
+    const bridge = requireHost();
+    return bridge.usePluginUiPreferences(bridge.usePluginId());
+}
+/**
+ * Grid or list and row density for one of this plugin's views, kept in its
+ * Appearance area as `<prefix>viewMode` and `<prefix>density`. Declare those
+ * keys in contributes.uiPresets so each preset level can pick a default.
+ */
+export function usePluginPanelView(prefix = "") {
+    const { values, set } = usePluginUiPreferences();
+    const view = values[`${prefix}viewMode`] === "list" ? "list" : "grid";
+    const density = values[`${prefix}density`] === "compact" ? "compact" : "comfortable";
+    return {
+        view,
+        density,
+        compact: density === "compact",
+        setView: (next) => set(`${prefix}viewMode`, next),
+        setDensity: (next) => set(`${prefix}density`, next),
+    };
+}
+export function useTabs() {
+    return requireHost().useTabs();
+}
+/**
+ * The SSH auth types this server can connect with, core's and every enabled
+ * plugin's, for pickers such as a default auth type.
+ */
+export function useSshAuthTypes() {
+    return requireHost().useSshAuthTypes();
+}
+/**
+ * The visible contributions to a slot another plugin owns, with their
+ * metadata (id, titleKey, component). For an owner that needs to build a
+ * catalog from what was contributed rather than just render it in place, e.g.
+ * host-metrics listing manager cards plugins added to "host-metrics.managers"
+ * next to its own. Same permission and `when` filtering as ComponentSlot;
+ * `context` is what each contribution's `when` sees.
+ */
+/**
+ * The connection protocols a host has switched on: "ssh" plus every protocol
+ * a running plugin registered with registerHostProtocol. Lets a
+ * plugin offer a protocol without knowing which plugin owns its settings.
+ */
+export function hostProtocols(record) {
+    return requireHost().hostProtocols(record);
+}
+export function useSlotContributions(slotId, context) {
+    return requireHost().useSlotContributions(slotId, context);
+}
+/**
+ * Every host action any running plugin (and core) registered with
+ * registerHostAction, for a plugin that offers a picker over "what can I do
+ * with this host" without knowing which plugin provides each one - a quick
+ * connect widget, say. Reactive: it re-renders as plugins enable and disable.
+ */
+export function useHostActions() {
+    return requireHost().useHostActions();
+}
+/**
+ * Recent-activity types every registered tab claims (registerTab's
+ * activityTypes), core's and plugins'. For a filter that lists what a user
+ * can pick, without knowing which plugin owns each activity type.
+ */
+export function useActivityTypes() {
+    return requireHost().useActivityTypes();
+}
+/**
+ * What a recent-activity entry of this type opens and how it is labelled -
+ * the tab type claiming it through registerTab's activityTypes, core's or a
+ * plugin's. undefined for a type nothing claims (its plugin is gone).
+ */
+export function activityTarget(type) {
+    return requireHost().activityTarget(type);
+}
+/**
+ * Every item any running plugin added to `pointId` with registerExtension.
+ * Reactive: it re-renders as plugins enable and disable.
+ */
+export function useExtensions(pointId) {
+    return requireHost().useExtensions(pointId);
+}
+/** A single item added to `pointId`, by id, or undefined if none. */
+export function getExtension(pointId, id) {
+    return requireHost().getExtension(pointId, id);
+}
+/**
+ * The component another plugin registered under `id` with
+ * app.registerComponent, or undefined while that plugin is off.
+ */
+export function usePluginComponent(id) {
+    return requireHost().usePluginComponent(id);
+}
+/**
+ * Runs an action another plugin registered, from anywhere in a plugin's code.
+ * Resolves undefined when nobody registered it, so an optional dependency
+ * that is switched off reads as "nothing there".
+ */
+export function invokeAction(id, ...args) {
+    return requireHost().invokeAction(id, ...args);
+}
+const COUNTDOWN_TICK_MS = 250;
+const RETRY_JITTER_RATIO = 0.1;
+export function computeReconnectDelay(attempt, baseDelayMs, maxDelayMs, random = Math.random) {
+    const base = Math.min(baseDelayMs * Math.pow(2, Math.max(0, attempt - 1)), maxDelayMs);
+    const jitter = base * RETRY_JITTER_RATIO * (random() * 2 - 1);
+    return Math.max(baseDelayMs, Math.min(maxDelayMs, Math.round(base + jitter)));
+}
+/**
+ * Exponential-backoff reconnect with jitter, for a plugin's own connect flow
+ * (docker's console, host-metrics polling, remote desktop tokens, the file
+ * manager). Promoted here once a fourth plugin needed its own copy of the
+ * same hook.
+ */
+export function useConnectionRetry({ connect, maxAttempts = 8, baseDelayMs = 2000, maxDelayMs = 8000, enabled = true, autoStart = true, }) {
+    const [status, setStatus] = useState("connecting");
+    const [attempt, setAttempt] = useState(0);
+    const [nextRetryInMs, setNextRetryInMs] = useState(null);
+    const connectRef = useRef(connect);
+    connectRef.current = connect;
+    const enabledRef = useRef(enabled);
+    enabledRef.current = enabled;
+    const attemptRef = useRef(0);
+    const retryTimeoutRef = useRef(null);
+    const countdownIntervalRef = useRef(null);
+    const isMountedRef = useRef(true);
+    const markFailedRef = useRef(() => { });
+    const clearTimers = useCallback(() => {
+        if (retryTimeoutRef.current) {
+            clearTimeout(retryTimeoutRef.current);
+            retryTimeoutRef.current = null;
+        }
+        if (countdownIntervalRef.current) {
+            clearInterval(countdownIntervalRef.current);
+            countdownIntervalRef.current = null;
+        }
+    }, []);
+    const runConnect = useCallback(() => {
+        if (!isMountedRef.current)
+            return;
+        setStatus("connecting");
+        try {
+            void Promise.resolve(connectRef.current()).catch(() => {
+                markFailedRef.current();
+            });
+        }
+        catch {
+            markFailedRef.current();
+        }
+    }, []);
+    const scheduleRetry = useCallback(() => {
+        if (attemptRef.current >= maxAttempts) {
+            setStatus("disconnected");
+            setNextRetryInMs(null);
+            return;
+        }
+        attemptRef.current += 1;
+        setAttempt(attemptRef.current);
+        const delay = computeReconnectDelay(attemptRef.current, baseDelayMs, maxDelayMs);
+        let remaining = delay;
+        setNextRetryInMs(remaining);
+        countdownIntervalRef.current = setInterval(() => {
+            remaining = Math.max(0, remaining - COUNTDOWN_TICK_MS);
+            setNextRetryInMs(remaining);
+        }, COUNTDOWN_TICK_MS);
+        retryTimeoutRef.current = setTimeout(() => {
+            clearTimers();
+            if (!isMountedRef.current || !enabledRef.current)
+                return;
+            runConnect();
+        }, delay);
+    }, [baseDelayMs, maxDelayMs, maxAttempts, clearTimers, runConnect]);
+    const markConnected = useCallback(() => {
+        clearTimers();
+        attemptRef.current = 0;
+        setAttempt(0);
+        setNextRetryInMs(null);
+        if (isMountedRef.current)
+            setStatus("connected");
+    }, [clearTimers]);
+    const markFailed = useCallback(() => {
+        clearTimers();
+        if (!isMountedRef.current)
+            return;
+        setStatus("error");
+        if (enabledRef.current) {
+            scheduleRetry();
+        }
+        else {
+            setNextRetryInMs(null);
+        }
+    }, [clearTimers, scheduleRetry]);
+    markFailedRef.current = markFailed;
+    const retryNow = useCallback(() => {
+        clearTimers();
+        attemptRef.current = 0;
+        setAttempt(0);
+        setNextRetryInMs(null);
+        runConnect();
+    }, [clearTimers, runConnect]);
+    const reset = useCallback(() => {
+        clearTimers();
+        attemptRef.current = 0;
+        setAttempt(0);
+        setNextRetryInMs(null);
+        if (isMountedRef.current)
+            setStatus("connecting");
+    }, [clearTimers]);
+    useEffect(() => {
+        isMountedRef.current = true;
+        if (autoStart) {
+            runConnect();
+        }
+        return () => {
+            isMountedRef.current = false;
+            clearTimers();
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    useEffect(() => {
+        if (enabled && status === "error" && !retryTimeoutRef.current) {
+            scheduleRetry();
+        }
+        if (!enabled) {
+            clearTimers();
+            setNextRetryInMs(null);
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [enabled]);
+    return {
+        status,
+        attempt,
+        maxAttempts,
+        nextRetryInMs,
+        markConnected,
+        markFailed,
+        retryNow,
+        reset,
+    };
+}