@termix-ssh/plugin-sdk 1.0.11 → 1.0.13

package/dist/desktop.d.ts

@@ -2,7 +2,6 @@
  * The desktop app's bridge (window.electronAPI), typed for plugins. It exists
  * only inside the Termix desktop app; check isElectron before calling it.
  */
-import type { PluginSshPromptRequest } from "./backend.js";
 export interface ServerConfig {
     serverUrl?: string;
     allowInvalidCertificate?: boolean;
@@ -30,27 +29,6 @@ export interface DialogResult {
     filePaths?: string[];
     [key: string]: unknown;
 }
-export interface LocalDirectoryResult {
-    success: boolean;
-    path: string;
-    parent?: string;
-    entries: LocalFileEntry[];
-    error?: string;
-}
-export interface LocalCollectedFile {
-    path: string;
-    name: string;
-    relativePath: string;
-    size: number;
-    created?: string;
-    modified: string;
-}
-export type LocalPathMutationResult = ({
-    success: true;
-} & Partial<LocalFileEntry>) | {
-    success: false;
-    error?: string;
-};
 export interface ElectronAPI {
     getAppVersion: () => Promise<string>;
     setZoomFactor?: (factor: number) => void;
@@ -62,51 +40,6 @@ export interface ElectronAPI {
         success: boolean;
     }>;
     testServerConnection: (serverUrl: string, allowInvalidCertificate?: boolean) => Promise<ConnectionTestResult>;
-    answerC2SAuth: (id: string, answer: string | null) => Promise<boolean>;
-    onC2SAuthPrompt: (callback: (prompt: {
-        id: string;
-        closed?: boolean;
-        tunnelName?: string;
-        request?: PluginSshPromptRequest;
-    }) => void) => () => void;
-    getC2STunnelConfig: () => Promise<unknown[]>;
-    saveC2STunnelConfig: (config: unknown[]) => Promise<{
-        success: boolean;
-        error?: string;
-    }>;
-    checkLocalPortAvailable: (host: string, port: number) => Promise<{
-        available: boolean;
-        error?: string;
-    }>;
-    getC2STunnelPresetDefaultName: () => Promise<string>;
-    startC2STunnel: (tunnel: unknown, index: number, authToken?: string) => Promise<{
-        success: boolean;
-        tunnelName?: string;
-        error?: string;
-        code?: string;
-    }>;
-    testC2STunnel: (tunnel: unknown, index: number, authToken?: string) => Promise<{
-        success: boolean;
-        message?: string;
-        error?: string;
-        code?: string;
-    }>;
-    stopC2STunnel: (tunnelName: string) => Promise<{
-        success: boolean;
-        error?: string;
-    }>;
-    getC2STunnelStatuses: () => Promise<Record<string, unknown>>;
-    onC2STunnelStatuses?: (callback: (statuses: Record<string, unknown>) => void) => () => void;
-    startC2SAutoStartTunnels: () => Promise<{
-        success: boolean;
-        started: number;
-        errors: string[];
-    }>;
-    /** Where the linked server relays client tunnel streams, a /plugin-ws/ path. */
-    setC2SRelayPath?: (relayPath: string) => Promise<{
-        success: boolean;
-        error?: string;
-    }>;
     onCloseActiveTab?: (callback: () => void) => () => void;
     clearSessionCookies: () => Promise<void>;
     getSessionCookie: (name: string, targetUrl?: string) => Promise<string | null>;
@@ -117,46 +50,6 @@ export interface ElectronAPI {
     }>;
     showSaveDialog: (options: DialogOptions) => Promise<DialogResult>;
     showOpenDialog: (options: DialogOptions) => Promise<DialogResult>;
-    getLocalHomeDirectory?: () => Promise<string>;
-    listLocalDirectory?: (path?: string) => Promise<LocalDirectoryResult>;
-    statLocalPaths?: (paths: string[]) => Promise<Array<(LocalFileEntry & {
-        success: true;
-    }) | {
-        success: false;
-        path: string;
-        error?: string;
-    }>>;
-    collectLocalFiles?: (paths: string[]) => Promise<{
-        success: boolean;
-        files: LocalCollectedFile[];
-        truncated?: boolean;
-        error?: string;
-    }>;
-    createLocalFolder?: (parentPath: string, folderName: string) => Promise<LocalPathMutationResult>;
-    renameLocalPath?: (path: string, newName: string) => Promise<LocalPathMutationResult>;
-    trashLocalPath?: (path: string) => Promise<LocalPathMutationResult>;
-    chmodLocalPath?: (path: string, permissions: string) => Promise<LocalPathMutationResult>;
-    openExternalEditor: (fileData: {
-        fileName: string;
-        content: string;
-        encoding?: "utf8" | "base64";
-        editorPath?: string | null;
-    }) => Promise<{
-        success: boolean;
-        editId?: string;
-        path?: string;
-        error?: string;
-    }>;
-    closeExternalEditor: (editId: string) => Promise<{
-        success: boolean;
-        error?: string;
-    }>;
-    onExternalEditorSaved?: (callback: (payload: {
-        editId: string;
-        content: string;
-        encoding: "utf8";
-        path: string;
-    }) => void) => () => void;
     onUpdateAvailable: (callback: () => void) => void;
     onUpdateDownloaded: (callback: () => void) => void;
     removeAllListeners: (channel: string) => void;
@@ -197,142 +90,6 @@ export interface ElectronAPI {
         success: boolean;
         error?: string;
     }>;
-    startLocalTerminal(dimensions: {
-        cols: number;
-        rows: number;
-        shell?: "default" | "wsl";
-    }): Promise<{
-        sessionId: string;
-        shell: string;
-    }>;
-    readyLocalTerminal(sessionId: string): Promise<boolean>;
-    writeLocalTerminal(sessionId: string, data: string): Promise<boolean>;
-    resizeLocalTerminal(sessionId: string, cols: number, rows: number): Promise<boolean>;
-    closeLocalTerminal(sessionId: string): Promise<boolean>;
-    onLocalTerminalData(sessionId: string, callback: (data: string) => void): () => void;
-    onLocalTerminalExit(sessionId: string, callback: (exitCode: number) => void): () => void;
-    /** Local disk browsing for the dual-pane file manager (desktop only). */
-    localFs?: {
-        home: () => Promise<LocalFsResult<LocalFsHomeInfo>>;
-        list: (dirPath: string) => Promise<LocalFsResult<LocalDirectoryListing>>;
-        mkdir: (parentPath: string, name: string) => Promise<LocalFsResult<{
-            path: string;
-        }>>;
-        createFile: (parentPath: string, name: string) => Promise<LocalFsResult<{
-            path: string;
-        }>>;
-        rename: (oldPath: string, newName: string) => Promise<LocalFsResult<{
-            path: string;
-        }>>;
-        trash: (paths: string[]) => Promise<LocalFsResult<LocalTrashResult>>;
-        ensureDir: (dirPath: string, rootPath?: string) => Promise<LocalFsResult<{
-            path: string;
-        }>>;
-        exists: (paths: string[]) => Promise<LocalFsResult<{
-            existing: string[];
-        }>>;
-        walk: (paths: string[]) => Promise<LocalFsResult<LocalWalkResult>>;
-        reveal: (targetPath: string) => Promise<LocalFsResult<unknown>>;
-        open: (targetPath: string) => Promise<LocalFsResult<unknown>>;
-    };
-    /** Streamed local<->remote transfers driven by the main process. */
-    localTransfer?: {
-        /** The /plugin-api/<id> path that serves the streaming routes. */
-        setApiPath?: (apiPath: string) => Promise<LocalFsResult<object>>;
-        upload: (options: LocalUploadRequest) => Promise<LocalFsResult<{
-            bytes: number;
-        }>>;
-        download: (options: LocalDownloadRequest) => Promise<LocalFsResult<{
-            path: string;
-        }>>;
-        cancel: (transferId: string) => Promise<LocalFsResult<{
-            cancelled: boolean;
-        }>>;
-        onProgress: (callback: (payload: LocalTransferProgress) => void) => () => void;
-    };
-}
-export type LocalFsResult<T> = ({
-    success: true;
-} & T) | {
-    success: false;
-    error: string;
-    code?: string;
-};
-export interface LocalFsHomeInfo {
-    home: string;
-    separator: string;
-    platform: string;
-}
-export interface LocalFileEntry {
-    name: string;
-    path: string;
-    type: "file" | "directory" | "link" | "other";
-    created?: string;
-    modified?: string;
-    permissions?: string;
-    owner?: string;
-    group?: string;
-    size: number;
-    modifiedTimestamp?: number;
-    linkTarget?: string;
-    hidden: boolean;
-}
-export interface LocalDirectoryListing {
-    path: string;
-    parent: string | null;
-    entries: LocalFileEntry[];
-}
-export interface LocalTrashResult {
-    trashed: number;
-    failed: Array<{
-        path: string;
-        error: string;
-    }>;
-}
-export interface LocalWalkFile {
-    localPath: string;
-    /** Path relative to the drop root; "/"-separated and includes the root's own name. */
-    relativePath: string;
-    size: number;
-}
-export interface LocalWalkResult {
-    files: LocalWalkFile[];
-    emptyDirs: string[];
-    totalBytes: number;
-}
-/**
- * Which Termix backend a transfer talks to. The main process resolves the
- * actual URL and credentials for the origin; the renderer never supplies them.
- */
-export type LocalTransferOrigin = "local" | "remote";
-export interface LocalUploadRequest {
-    transferId: string;
-    origin: LocalTransferOrigin;
-    fields: Record<string, string>;
-    localPath: string;
-    fileName: string;
-    deviceId?: string;
-    /** The renderer's token for the embedded backend (origin "local"); sent as a Bearer header. */
-    authToken?: string;
-}
-export interface LocalDownloadRequest {
-    transferId: string;
-    origin: LocalTransferOrigin;
-    body: Record<string, unknown>;
-    destPath: string;
-    /** Selected download folder; destPath must resolve strictly inside it (code EINVAL otherwise). */
-    rootPath: string;
-    expectedSize?: number;
-    /** Replace an existing file at destPath; otherwise the transfer is refused with code EEXIST. */
-    overwrite?: boolean;
-    deviceId?: string;
-    /** The renderer's token for the embedded backend (origin "local"); sent as a Bearer header. */
-    authToken?: string;
-}
-export interface LocalTransferProgress {
-    transferId: string;
-    transferred: number;
-    total?: number;
 }
 declare global {
     interface Window {

package/dist/frontend.d.ts

@@ -222,6 +222,146 @@ export interface TabsApi extends Pick<ShellApi, "openTab" | "openSingletonTab" |
     /** Called once the shell has restored its tabs after login. */
     onReady: (listener: () => void) => Disposer;
 }
+/**
+ * A whole-app layout. Core renders the chosen one inside its providers and an
+ * error boundary; everything it shows comes from useShell(). Declare it in
+ * manifest contributes.layouts and add the ui:layout capability.
+ */
+export interface LayoutContribution {
+    id: string;
+    /** Your own i18n key or plain text, the same as the manifest's label. */
+    label: string;
+    component: ComponentType;
+    /** Shown on phones and narrow windows. The desktop app never uses it. */
+    mobileComponent?: ComponentType;
+    /** Theme to start with when nobody chose one. */
+    defaultTheme?: string;
+}
+/** A tab as a layout sees it. Splits are tabs too, with a `split` field. */
+export interface ShellTabState extends PluginTabRecord {
+    instanceId: string;
+    customLabel?: string;
+    /** Set while the tab sits in a split pane. */
+    parentSplitTabId?: string;
+    openedAt?: number;
+}
+/** What a dock region shows and how it is sized, in Normal-size pixels. */
+export interface ShellDockState {
+    view: string | null;
+    open: boolean;
+    width: number;
+    dragging: boolean;
+    setView: (view: string | null) => void;
+    setWidth: (width: number) => void;
+    /** Starts a drag from the dock's edge, from a mousedown. */
+    startResize: (event: {
+        clientX: number;
+        preventDefault: () => void;
+    }) => void;
+    resetWidth: () => void;
+}
+/** The live shell: state and actions, nothing drawn. Read with useShell(). */
+export interface ShellController {
+    tabs: {
+        list: ShellTabState[];
+        /** What a tab bar shows: tabs not sitting in a split. */
+        topLevel: ShellTabState[];
+        activeId: string;
+        /** True once saved tabs were restored after login. */
+        ready: boolean;
+        /** The user turned on tab numbers. */
+        showNumbers: boolean;
+        setActive: (id: string) => void;
+        reorder: (topLevel: ShellTabState[]) => void;
+        close: (id: string) => Promise<void>;
+        rename: (id: string, label: string) => void;
+        /** Reconnects or reloads a session tab. */
+        refresh: (id: string) => void;
+        reconnectAll: () => void;
+        openSingleton: (type: string) => string | undefined;
+    };
+    split: {
+        /** The split shown now, or null. */
+        activeId: string | null;
+        focusedPaneId: string | null;
+        /** Every split with its panes, for a split menu. */
+        summaries: Array<{
+            id: string;
+            label: string;
+            full: boolean;
+            panes: Array<{
+                id: string;
+                index: number;
+                tabId: string | null;
+                label: string | null;
+            }>;
+        }>;
+        activeFull: boolean;
+        /** Split a tab, apply a preset, unsplit, add to a pane. */
+        handleAction: (action: Record<string, unknown> & {
+            kind: string;
+        }) => void;
+    };
+    hosts: {
+        list: PluginHostRecord[];
+        loading: boolean;
+        loaded: boolean;
+        reload: () => Promise<void>;
+    };
+    regions: {
+        left: ShellDockState & {
+            view: string;
+        };
+        right: ShellDockState;
+        /** What a rail click does: toggles or switches the left dock. */
+        railClick: (view: string) => void;
+        openInRightDock: (view: string) => void;
+        toggleRightDock: () => void;
+    };
+    palette: {
+        isOpen: boolean;
+        open: () => void;
+        close: () => void;
+    };
+    fullscreen: {
+        active: boolean;
+        toggle: () => void;
+    };
+    /** The same callbacks tabs and panels get. */
+    actions: ShellApi;
+    env: {
+        isMobile: boolean;
+        isElectron: boolean;
+        user: {
+            username: string;
+            isAdmin: boolean;
+        };
+        permissions: string[];
+        branding: {
+            appName: string | null;
+            tagline: string | null;
+            logo: string | null;
+        };
+    };
+    /** Core registries, as hooks a layout calls while rendering. */
+    registries: {
+        useRailItems: () => ReadonlyArray<{
+            id: string;
+        } & Record<string, unknown>>;
+        usePanels: () => ReadonlyArray<{
+            id: string;
+        } & Record<string, unknown>>;
+        useTabTypes: () => ReadonlyArray<{
+            id: string;
+        } & Record<string, unknown>>;
+        useDashboardCards: () => ReadonlyArray<{
+            id: string;
+        } & Record<string, unknown>>;
+    };
+    logout: (options?: {
+        manual?: boolean;
+    }) => void;
+}
 export interface RailItemContribution {
     /** Must be declared in manifest contributes.tabs or contributes.panels. */
     id: string;
@@ -489,7 +629,13 @@ export interface HostBadgeContribution {
     component: ComponentType<{
         host: PluginHostRecord;
     }>;
+    /** Lower comes first. Ties sort by id. */
+    order?: number;
 }
+/** The dot or stripe that shows a host's status on its row. */
+export type HostStatusIndicatorContribution = HostBadgeContribution;
+/** A control in the host editor's toolbar. */
+export type HostEditorToolbarItemContribution = HostBadgeContribution;
 export interface HostContextMenuItemContribution {
     id: string;
     titleKey: string;
@@ -655,10 +801,11 @@ export type OnboardingMode = "full" | "partial" | "rerun";
  * Where a plugin step sits in onboarding. "setup" comes right after the
  * appearance steps, for things that need doing before the feature works
  * (like pointing at a guacd server). "explore" (the default) comes after
- * that, "security" after the account security step. Onboarding is for
+ * that, "security" after the account security step. "start" comes before
+ * the appearance steps, for choices that shape how the rest looks. Onboarding is for
  * choices, not for explaining features.
  */
-export type OnboardingSection = "setup" | "explore" | "security";
+export type OnboardingSection = "start" | "setup" | "explore" | "security";
 export interface OnboardingStepProps {
     /**
      * "full" is a new user's first run, "partial" shows only steps they have
@@ -699,6 +846,16 @@ export interface OnboardingStepContribution {
     permission?: string;
     section?: OnboardingSection;
     order?: number;
+    /**
+     * Exact place in the flow, 1 to 99, instead of a section. Core steps sit at
+     * 10 (plugins), 20, 25, 30 (preset), 40 (appearance) and 90 (security).
+     */
+    position?: number;
+    /**
+     * Older step keys this step took over, like "preset". People who already
+     * saw one of them are not shown this step again.
+     */
+    replaces?: string[];
     when?: (context: {
         isAdmin: boolean;
         isDesktop: boolean;
@@ -848,6 +1005,10 @@ export interface TermixApp extends TermixAppInfo {
     registerHostAction: (action: HostActionContribution) => Disposer;
     registerHostProtocol: (protocol: HostProtocolContribution) => Disposer;
     registerHostBadge: (badge: HostBadgeContribution) => Disposer;
+    /** Draws a host row's status. A layout renders every registered one. */
+    registerHostStatusIndicator: (indicator: HostStatusIndicatorContribution) => Disposer;
+    /** Adds a control to the host editor's toolbar. */
+    registerHostEditorToolbarItem: (item: HostEditorToolbarItemContribution) => Disposer;
     registerHostContextMenuItem: (item: HostContextMenuItemContribution) => Disposer;
     registerPaletteEntry: (entry: PaletteEntryContribution) => Disposer;
     registerPaletteGroup: (group: PaletteGroupContribution) => Disposer;
@@ -886,6 +1047,12 @@ export interface TermixApp extends TermixAppInfo {
     registerSshAuthEditor: (editor: SshAuthEditorContribution) => Disposer;
     registerLoginMethod: (method: LoginMethodContribution) => Disposer;
     registerSecondFactorUI: (factor: SecondFactorContribution) => Disposer;
+    /**
+     * A whole-app layout. Declared in manifest contributes.layouts with the
+     * ui:layout capability. Only the chosen layout's plugin is loaded, so
+     * register it in activate. Needs plugin API 1.4.
+     */
+    registerLayout: (layout: LayoutContribution) => Disposer;
     /**
      * Translates a key from the plugin's own locales, for code outside a
      * component (a toast from activate). Components use useTranslation().
@@ -993,6 +1160,7 @@ export interface PluginHostBridge {
     useTheme: () => {
         theme: "light" | "dark";
     };
+    useShell: () => ShellController | null;
     toast: ToastApi;
     getApi: (pluginId: string) => PluginApiClient;
     getApiFor: (pluginId: string, origin: unknown) => PluginApiClient;
@@ -1154,6 +1322,11 @@ export declare function useCurrentUser(): CurrentUser | null;
 export declare function useTheme(): {
     theme: "light" | "dark";
 };
+/**
+ * The live shell, for a layout. Null outside the signed-in app. Needs plugin
+ * API 1.4.
+ */
+export declare function useShell(): ShellController | null;
 export declare function useToast(): ToastApi;
 export declare function logActivity(type: string, hostId: number, hostName: string): Promise<void>;
 /** Tells the shell hosts were added or changed, so its lists reload. */

package/dist/frontend.js

@@ -98,6 +98,13 @@ export function useCurrentUser() {
 export function useTheme() {
     return requireHost().useTheme();
 }
+/**
+ * The live shell, for a layout. Null outside the signed-in app. Needs plugin
+ * API 1.4.
+ */
+export function useShell() {
+    return requireHost().useShell();
+}
 export function useToast() {
     return requireHost().toast;
 }