@termix-ssh/plugin-sdk 1.0.15 → 1.0.18

package/dist/backend.d.ts

@@ -201,6 +201,357 @@ export interface SyncEntityRegistration {
  */
 export interface PluginSync {
     registerEntity: (entity: SyncEntityRegistration) => void;
+    /** Needs sync:provide. Takes over /sync/v2 and /sync/link. Removed on deactivate. */
+    provide: (provider: PluginSyncProvider) => () => void;
+    /** Needs sync:provide. The replica store, change feed and link registry. */
+    readonly host: PluginSyncHost;
+}
+/**
+ * The plugin that owns server and desktop sync. Core forwards every request
+ * under /sync to `handle` (an Express style handler) and answers 404 when no
+ * plugin provides it. Call `next()` to let core answer instead.
+ */
+export interface PluginSyncProvider {
+    handle: (req: unknown, res: unknown, next: (error?: unknown) => void) => void | Promise<void>;
+}
+/** A kind of data that syncs, as the sync provider sees it. */
+export interface SyncEntityInfo {
+    type: string;
+    owner: string;
+    order: number;
+    readOnly: boolean;
+    /** Whether the row would show in a load even if it exists. */
+    covers?: (syncId: string) => boolean;
+}
+/** A row ready for the wire, with its content hash. */
+export interface SyncWireRow {
+    syncId: string;
+    wire: SyncRow;
+    hash: string;
+}
+export interface SyncRecordInfo {
+    entityType: string;
+    syncId: string;
+    revision: number;
+    hash: string | null;
+    deleted: boolean;
+    error: string | null;
+    errorHash: string | null;
+    seq: number;
+}
+export interface SyncConflictInfo {
+    id: number;
+    entityType: string;
+    syncId: string;
+    localRow: string;
+    createdAt: string;
+}
+export interface SyncAccountInfo {
+    id: string;
+    username: string;
+    isAdmin: boolean;
+    active: boolean;
+}
+export interface SyncProxyHeader {
+    name: string;
+    value: string;
+}
+export interface SyncBasicAuth {
+    username: string;
+    password: string;
+}
+/** A client certificate for a server that asks for mutual TLS. */
+export interface SyncClientCert {
+    /** Base64 of the PFX/P12 file. */
+    pfx: string;
+    passphrase: string;
+    /** The file name, to show which certificate is saved. */
+    name: string | null;
+}
+/** Extra per server connection options. Kept open so new ones need no migration. */
+export type SyncLinkOptions = Record<string, unknown>;
+/** One server a desktop is linked to, with a replica of its data. */
+export interface SyncLinkInfo {
+    id: number;
+    /** The local user the replica belongs to. */
+    userId: string;
+    serverUrl: string;
+    serverName: string | null;
+    serverVersion: string | null;
+    sessionToken: string | null;
+    customHeaders: SyncProxyHeader[];
+    basicAuth: SyncBasicAuth | null;
+    allowInvalidCertificate: boolean;
+    clientCert: SyncClientCert | null;
+    remoteUserId: string | null;
+    remoteUsername: string | null;
+    account: {
+        remoteUserId?: string;
+        username?: string;
+        isAdmin?: boolean;
+        roles?: string[];
+        permissions?: string[];
+    } | null;
+    disabledTypes: string[];
+    /** Extra connection options for this server, kept open for new ones. */
+    options: SyncLinkOptions;
+    knownTypes: string[];
+    cursor: number;
+    status: "idle" | "syncing" | "offline" | "error" | "signed_out";
+    lastError: string | null;
+    linkedAt: string;
+    lastSyncAt: string | null;
+}
+export interface SyncLinkCreate {
+    userId: string;
+    serverUrl: string;
+    serverName?: string | null;
+    serverVersion?: string | null;
+    sessionToken: string;
+    customHeaders?: SyncProxyHeader[];
+    basicAuth?: SyncBasicAuth | null;
+    allowInvalidCertificate?: boolean;
+    clientCert?: SyncClientCert | null;
+    remoteUserId?: string | null;
+    remoteUsername?: string | null;
+}
+export type SyncLinkPatch = Partial<Pick<SyncLinkInfo, "serverName" | "serverVersion" | "sessionToken" | "customHeaders" | "basicAuth" | "allowInvalidCertificate" | "clientCert" | "remoteUserId" | "remoteUsername" | "account" | "disabledTypes" | "options" | "knownTypes" | "cursor" | "status" | "lastError" | "lastSyncAt">>;
+export type SyncRemoteErrorKind = "offline" | "tls" | "client_cert" | "proxy" | "basic_auth" | "signed_out" | "server";
+export interface SyncRemoteError extends Error {
+    readonly kind: SyncRemoteErrorKind;
+    readonly status?: number;
+}
+export interface SyncRemoteTarget {
+    serverUrl: string;
+    sessionToken?: string | null;
+    customHeaders?: SyncProxyHeader[];
+    basicAuth?: SyncBasicAuth | null;
+    allowInvalidCertificate?: boolean;
+    clientCert?: SyncClientCert | null;
+}
+export interface SyncRemoteRequest {
+    method?: string;
+    body?: unknown;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+export interface SyncPushOp {
+    entityType: string;
+    syncId: string;
+    baseRevision: number;
+    op: "upsert" | "delete";
+    row?: SyncRow;
+}
+export type SyncPushResult = {
+    syncId: string;
+    entityType: string;
+    status: "ok";
+    revision: number;
+} | {
+    syncId: string;
+    entityType: string;
+    status: "conflict";
+    revision: number;
+    deleted: boolean;
+    row: SyncRow | null;
+} | {
+    syncId: string;
+    entityType: string;
+    status: "rejected";
+    reason: string;
+};
+export interface SyncRemotePlugin {
+    id: string;
+    name: string;
+    version: string;
+    source: string;
+    artifact: boolean;
+    enabled: boolean;
+    active: boolean;
+    desktop: string;
+    syncEntities: string[];
+    granted: string[];
+}
+/**
+ * What the sync provider gets from core: the replica store, the change feed,
+ * the linked server registry, sessions and a few helpers. Core keeps all of
+ * it neutral; the provider decides when and how to use it. Needs sync:provide.
+ */
+export interface PluginSyncHost {
+    /** True on the desktop app's own backend. */
+    readonly embedded: boolean;
+    info: {
+        appName: () => Promise<string>;
+        version: () => string;
+    };
+    entities: {
+        list: () => SyncEntityInfo[];
+        get: (type: string) => SyncEntityInfo | undefined;
+        /** Registers core's own entities once. */
+        ensureCore: () => Promise<void>;
+        onChanged: (listener: () => void) => () => void;
+        onLocalWrite: (listener: () => void) => () => void;
+    };
+    /** Rows and bookkeeping of one local user's replica. */
+    replica: {
+        resolvers: (userId: string, onMissing?: () => void) => unknown;
+        loadRows: (type: string, userId: string, resolvers: unknown) => Promise<{
+            rows: Map<string, SyncWireRow>;
+            failed: Set<string>;
+        }>;
+        loadRow: (type: string, userId: string, syncId: string, resolvers: unknown) => Promise<SyncWireRow | null>;
+        writeRow: (type: string, userId: string, wire: SyncRow, resolvers: unknown) => Promise<void>;
+        deleteRow: (type: string, userId: string, syncId: string) => Promise<void>;
+        orderSelfReferences: (type: string, rows: SyncRow[]) => SyncRow[];
+        counts: (userId: string) => Promise<Record<string, number>>;
+        wipe: (userId: string) => Promise<void>;
+        regenerateSyncIds: (userId: string) => Promise<void>;
+        removeSharedCopies: (userId: string) => Promise<void>;
+        records: {
+            list: (userId: string) => Promise<Map<string, SyncRecordInfo>>;
+            put: (userId: string, type: string, syncId: string, values: {
+                revision: number;
+                hash: string | null;
+                deleted: boolean;
+            }) => Promise<void>;
+            setError: (userId: string, type: string, syncId: string, reason: string, hash: string) => Promise<void>;
+            clearErrors: (userId: string) => Promise<void>;
+            listErrors: (userId: string) => Promise<SyncRecordInfo[]>;
+            deleteForUser: (userId: string) => Promise<void>;
+            key: (type: string, syncId: string) => string;
+        };
+        conflicts: {
+            save: (userId: string, type: string, syncId: string, row: SyncRow, revision: number) => Promise<void>;
+            list: (userId: string) => Promise<SyncConflictInfo[]>;
+            get: (userId: string, id: number) => Promise<SyncConflictInfo | null>;
+            delete: (userId: string, id: number) => Promise<void>;
+        };
+    };
+    /** The server side: what changed for an account and what a desktop pushed. */
+    feed: {
+        withUserLock: <T>(userId: string, run: () => Promise<T>) => Promise<T>;
+        changes: (userId: string, cursor: number, limit: number, types?: string[]) => Promise<{
+            records: Array<{
+                seq: number;
+                entityType: string;
+                syncId: string;
+                revision: number;
+                deleted: boolean;
+                row: SyncRow | null;
+            }>;
+            hasMore: boolean;
+            nextCursor: number;
+            entityTypes: Array<{
+                type: string;
+                owner: string;
+                order: number;
+                readOnly: boolean;
+            }>;
+        }>;
+        parsePushOps: (body: unknown) => Promise<SyncPushOp[] | null>;
+        applyPush: (userId: string, ops: SyncPushOp[]) => Promise<SyncPushResult[]>;
+        /** Streams a change notice to the account's open event streams. */
+        listen: (userId: string, res: unknown) => Promise<() => void>;
+    };
+    /**
+     * The linked server registry, kept in core so it is there before plugins.
+     * One link per local user. Without a user, the active account is meant.
+     */
+    links: {
+        list: () => Promise<SyncLinkInfo[]>;
+        get: (userId?: string) => Promise<SyncLinkInfo | null>;
+        create: (link: SyncLinkCreate) => Promise<SyncLinkInfo>;
+        update: (patch: SyncLinkPatch, userId?: string) => Promise<SyncLinkInfo | null>;
+        remove: (userId?: string) => Promise<void>;
+    };
+    /** Desktop accounts: the local user and the replica user of each server. */
+    accounts: {
+        list: () => Promise<SyncAccountInfo[]>;
+        /** A new empty account, ready to be linked to a server. */
+        create: () => Promise<string>;
+        /** Which account the app signs in as from now on. */
+        setActive: (userId: string) => Promise<void>;
+        activeId: () => Promise<string | null>;
+        /** Deletes an account and all its data. The last one cannot go. */
+        remove: (userId: string) => Promise<void>;
+    };
+    http: {
+        json: <T>(target: SyncRemoteTarget, pathname: string, request?: SyncRemoteRequest) => Promise<T>;
+        fetch: (target: SyncRemoteTarget, pathname: string, request?: SyncRemoteRequest) => Promise<{
+            ok: boolean;
+            status: number;
+            body: AsyncIterable<Uint8Array> | null;
+        }>;
+        normalizeServerUrl: (input: string) => string | null;
+        isRemoteError: (error: unknown) => error is SyncRemoteError;
+    };
+    sessions: {
+        /** A long lived session for a linked desktop. Shows in the account's sessions. */
+        issueDesktop: (userId: string, options: {
+            days: number;
+            deviceInfo: string;
+        }) => Promise<string>;
+        revoke: (sessionId: string) => Promise<void>;
+        find: (sessionId: string) => Promise<{
+            expiresAt: string;
+            deviceInfo: string | null;
+        } | null>;
+        findUser: (userId: string) => Promise<{
+            id: string;
+            username: string;
+        } | null>;
+        /** The user and session behind a token, or null when it is not valid. */
+        verify: (token: string) => Promise<{
+            userId: string;
+            sessionId?: string;
+        } | null>;
+        /** Sets the sign in cookie on a response, like a login does. A name sets another cookie. */
+        setCookie: (req: unknown, res: unknown, value: string, options?: {
+            name?: string;
+            days?: number;
+        }) => void;
+        /** Removes the sign in cookie, without ending the session behind it. */
+        clearCookie: (req: unknown, res: unknown, name?: string) => void;
+        /** Express middleware that signs the request in and sets userId and sessionId. */
+        middleware: () => unknown;
+        /** Express middleware that lets a request through only on a desktop. */
+        desktopOnly: () => unknown;
+    };
+    hosts: {
+        findForSync: (userId: string, syncId: string) => Promise<{
+            id: number;
+            name: string | null;
+        } | null>;
+        statusBySyncId: (userId: string) => Promise<Record<string, unknown>>;
+    };
+    plugins: {
+        listForDesktop: () => Promise<{
+            plugins: SyncRemotePlugin[];
+            registryKeys: unknown;
+        }>;
+        /** Sends a plugin archive; false when there is no such plugin to share. */
+        sendPackage: (pluginId: string, res: unknown) => Promise<boolean>;
+        mirror: (link: SyncLinkInfo) => Promise<void>;
+        lastRemote: () => SyncRemotePlugin[];
+        localNames: () => Map<string, string>;
+    };
+    desktop: {
+        /** Tells the app's main process how to reach the linked origin. */
+        applyProxy: (link: SyncLinkInfo | null) => Promise<void>;
+        deviceName: () => string;
+    };
+    alerts: {
+        send: (alert: {
+            title: string;
+            body: string;
+            severity: "info" | "warning" | "error";
+            category: string;
+            dedupeKey: string;
+            link?: {
+                tab: string;
+            };
+        }) => Promise<void>;
+    };
 }
 /**
  * A plain key/value hand-off between plugins. `provide` and `revoke` only take
@@ -798,6 +1149,17 @@ export interface PluginHosts {
     activity: PluginHostActivityApi;
     /** Read only hosts this plugin manages. */
     locks: PluginHostLocksApi;
+    /** Folder rows for the acting user. Needs hosts:write. */
+    folders: PluginHostFoldersApi;
+}
+export interface PluginHostFoldersApi {
+    /** Creates the folder row if missing and sets its color and icon. */
+    ensure: (name: string, style?: {
+        color?: string | null;
+        icon?: string | null;
+    }) => Promise<void>;
+    /** Removes the folder row and subfolders once no host is left in them. */
+    removeEmpty: (name: string) => Promise<boolean>;
 }
 export interface PluginHostImportOptions {
     /** Update a host that matches on ip, port and username instead of skipping it. */
@@ -1136,7 +1498,26 @@ export interface PluginNetwork {
         timeoutMs?: number;
     }) => Promise<boolean>;
 }
+/**
+ * A way to reach some hosts other than a plain TCP connection. `claims` is
+ * asked for every connection, so it must be quick. `open` returns a stream
+ * the SSH client runs over, like a relayed socket.
+ */
+export interface PluginSshTransportProvider {
+    claims: (hostId: number) => boolean;
+    open: (host: {
+        id: number;
+        ip: string;
+        port: number;
+    }) => Promise<import("node:stream").Duplex>;
+}
+export interface PluginSshTransports {
+    /** Needs ssh:transport. Removed on deactivate. */
+    provide: (provider: PluginSshTransportProvider) => () => void;
+}
 export interface PluginSsh {
+    /** Other ways to reach hosts, used by every connection to them. */
+    transports: PluginSshTransports;
     /**
      * Whether a TCP port answers through the host's jump host chain. Chains are
      * shared and closed when idle. The acting user must be able to connect to

package/dist/capabilities.js

@@ -34,6 +34,8 @@ export const CAPABILITY_CATALOG = [
     entry("db:core-refs", "high"),
     entry("auth:provide", "high"),
     entry("auth:policy", "high"),
+    entry("sync:provide", "high"),
+    entry("ssh:transport", "high"),
     entry("device:serial", "high"),
     entry("notify:hub", "high"),
     entry("ui:layout", "high"),

package/dist/frontend.d.ts

@@ -773,6 +773,43 @@ export interface SettingsComponentProps {
     setValue: (key: string, value: unknown) => void;
     running: boolean;
 }
+/** What a companion starts with. Read from the plugin's own settings. */
+export interface CompanionDefaults {
+    /** Open by itself the first time a matching tab shows. */
+    open?: boolean;
+    side?: "left" | "right" | "bottom";
+    /** Pixels of width, or height at the bottom. */
+    size?: number;
+    /** Show the edge button that opens and closes it. Default true. */
+    edgeButton?: boolean;
+}
+export interface CompanionProps {
+    /** The tab it sits beside. */
+    tab: PluginTabRecord;
+    host?: PluginHostRecord;
+    /** The host in the shape the connection APIs take. */
+    sshHost?: Record<string, unknown>;
+    /** The tab's surface handle (see TabHandle), read at call time. */
+    getHandle: () => TabHandle | null;
+    side: "left" | "right" | "bottom";
+    /** False while the tab is in the background or the panel is closed. */
+    isVisible: boolean;
+    close: () => void;
+    setSide: (side: "left" | "right" | "bottom") => void;
+}
+export interface CompanionOptions {
+    icon?: IconComponent;
+    titleKey?: string;
+    order?: number;
+    /** Tab types it applies to. Any tab with a host when empty. */
+    tabTypes?: string[];
+    when?: (tab: PluginTabRecord, host?: PluginHostRecord) => boolean;
+    /**
+     * A hook returning the starting state. It runs in the plugin's scope, so it
+     * can read the plugin's settings.
+     */
+    useDefaults?: () => CompanionDefaults;
+}
 export type ActionHandler = (...args: never[]) => unknown;
 export interface ActionSlotDefinition {
     id: string;
@@ -1001,6 +1038,14 @@ export interface TermixApp extends TermixAppInfo {
     registerRailItem: (item: RailItemContribution) => Disposer;
     registerPanel: (id: string, component: ComponentType<PanelProps>, options?: PanelOptions) => Disposer;
     registerTab: (type: string, component: ComponentType<TabProps>, options?: TabOptions) => Disposer;
+    /**
+     * A panel that sits beside any host tab the options match (a terminal, a
+     * desktop, ...), bound to that tab's host. The user opens, resizes and moves
+     * it; the tab keeps running underneath.
+     */
+    registerCompanion: (id: string, component: ComponentType<CompanionProps>, options?: CompanionOptions) => Disposer;
+    /** Opens a companion on a tab, or closes it when it is showing. */
+    toggleCompanion: (tab: PluginTabRecord, id?: string) => void;
     registerHostEditorSection: (section: HostEditorSectionContribution) => Disposer;
     registerHostAction: (action: HostActionContribution) => Disposer;
     registerHostProtocol: (protocol: HostProtocolContribution) => Disposer;

package/dist/host/{PluginsTab-S33WIIGC.js → PluginsTab-YAGYRBIE.js}

@@ -29,7 +29,7 @@ import {
   sortPlugins,
   uploadEntry,
   youtubeEmbedUrl
-} from "./chunk-VFTB2RDP.js";
+} from "./chunk-446UEDSK.js";
 import {
   ArrowDownWideNarrow,
   BookOpen,
@@ -107,8 +107,8 @@ import {
   updatePlugin,
   uploadPlugin,
   useConfirm
-} from "./chunk-2IV3VX7F.js";
-import "./chunk-3L45NNT5.js";
+} from "./chunk-LQKK2JJA.js";
+import "./chunk-7LEJ3HYF.js";
 import {
   __toESM,
   define_import_meta_env_default,

package/dist/host/{chunk-57DJU2ZA.js → chunk-2MU6WNSX.js}

@@ -26,7 +26,7 @@ var inFlight = null;
 function load() {
   if (cache) return Promise.resolve(cache);
   if (inFlight) return inFlight;
-  inFlight = import("./rbac-api-KA5IPQQL.js").then(({ getMyPermissions }) => getMyPermissions()).then((result) => {
+  inFlight = import("./rbac-api-LZVENREG.js").then(({ getMyPermissions }) => getMyPermissions()).then((result) => {
     cache = {
       permissions: result.permissions ?? [],
       isAdmin: !!result.isAdmin

package/dist/host/{chunk-VFTB2RDP.js → chunk-446UEDSK.js}

@@ -7,10 +7,10 @@ import {
   Trash,
   cn,
   useAreaPreferences
-} from "./chunk-2IV3VX7F.js";
+} from "./chunk-LQKK2JJA.js";
 import {
   isElectron
-} from "./chunk-3L45NNT5.js";
+} from "./chunk-7LEJ3HYF.js";
 import {
   __commonJS,
   __toESM,
@@ -2383,6 +2383,8 @@ var CAPABILITY_CATALOG = [
   entry("db:core-refs", "high"),
   entry("auth:provide", "high"),
   entry("auth:policy", "high"),
+  entry("sync:provide", "high"),
+  entry("ssh:transport", "high"),
   entry("device:serial", "high"),
   entry("notify:hub", "high"),
   entry("ui:layout", "high"),

package/dist/host/{chunk-3L45NNT5.js → chunk-7LEJ3HYF.js}

@@ -7,6 +7,7 @@ import {
 
 // src/ui/lib/linked-server.ts
 init_define_import_meta_env();
+import { useEffect as useEffect2, useState as useState2 } from "react";
 
 // src/ui/lib/electron.ts
 init_define_import_meta_env();
@@ -5432,7 +5433,6 @@ init_define_import_meta_env();
 init_define_import_meta_env();
 var LEGACY_SEEN = Object.freeze({
   plugins: 1,
-  "desktop-sync": 1,
   preset: 1,
   appearance: 1,
   security: 1
@@ -6316,7 +6316,7 @@ async function updateRole(roleId, roleData) {
   try {
     const response = await rbacApi.put(`/rbac/roles/${roleId}`, roleData);
     if (roleData.permissions) {
-      const { notifyPermissionsChanged } = await import("./use-permissions-LLN6TLAL.js");
+      const { notifyPermissionsChanged } = await import("./use-permissions-BYCDS5PD.js");
       notifyPermissionsChanged();
     }
     return response.data;
@@ -6898,7 +6898,7 @@ function createRemoteOriginApiInstance(path) {
   });
   instance.interceptors.request.use(
     async (config) => {
-      const { getLinkedSession: getLinkedSession2 } = await import("./linked-server-SCJH7DSL.js");
+      const { getLinkedSession: getLinkedSession2 } = await import("./linked-server-OUF3POT7.js");
       const linked = await getLinkedSession2();
       config.baseURL = linked ? `${linked.serverUrl}${path}` : "http://no-server-configured";
       if (config.headers.set) {
@@ -7287,6 +7287,22 @@ function notifySyncChanged() {
   cached = null;
   window.dispatchEvent(new CustomEvent(SYNC_CHANGED_EVENT));
 }
+function useDesktopLinked() {
+  const [linked, setLinked] = useState2(false);
+  useEffect2(() => {
+    let live = true;
+    const read = () => void getLinkedSession().then((session) => {
+      if (live) setLinked(!!session);
+    });
+    read();
+    window.addEventListener(SYNC_CHANGED_EVENT, read);
+    return () => {
+      live = false;
+      window.removeEventListener(SYNC_CHANGED_EVENT, read);
+    };
+  }, []);
+  return linked;
+}
 
 export {
   getPluginStoreState,
@@ -7332,6 +7348,7 @@ export {
   websocketAuthProtocols,
   getLinkedSession,
   notifySyncChanged,
+  useDesktopLinked,
   resolveConnectionOrigin,
   buildOriginWsUrl,
   getAllServerStatuses,