@termix-ssh/plugin-sdk 1.0.20 → 1.0.22

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 1.0.22
+
+Plugin API 1.13.0.
+
+### Added
+
+- `contributes.mobile` in the manifest says how a plugin shows in the Termix mobile app: `webview`, `native` or `none`, with an optional mobile bundle, screen sizes, views and a note
+- `termix-plugin build` bundles `src/mobile` into the `contributes.mobile.entry` file, and `validate` checks that it exists
+- `@termix-ssh/plugin-sdk/frame-host` runs one plugin view outside the shell, with core's bridge, registries and CSS, so the mobile app can show `webview` plugins
+- SSH transport providers get the host's owner, sync id, connection origin and local only flag in `claims` and `open`, and core's SSH relay takes a `syncId` instead of a host id
+- `ctx.sync.host.entities.idsOf` maps sync ids to the local ids of the user's own rows of one type
+- Rail items take `useStatus` for a small ok, warning or error dot on the icon
+- `shell.editHost(hostId)` opens the editor of a saved host
+- A sync entity can be read only with `load`, `write` and `erase`, so a plugin can sync rows a user does not own, like a shared library, down to linked desktops
+- `getFolderAuthOverride` and `setFolderAuthOverride` in `@termix-ssh/plugin-sdk/ui` read and set a user's own login for the shared hosts in a folder
+
+### Fixed
+
+- `@termix-ssh/plugin-sdk/ui` is built in production mode, so outside Termix it no longer sends requests to the Vite dev server path
+- `execCommand` buffers output and decodes it once as strict UTF-8 with a GBK fallback, exposed as `decodeCommandOutput`, so messages from a Windows host on a legacy codepage are readable instead of � characters
+
+## 1.0.21
+
+Plugin API 1.12.0.
+
+### Added
+
+- `@termix-ssh/plugin-sdk/host-scripts`: Docker, Linux metrics, systemd, journal and OpenRC command builders and parsers, plus `scriptShell()` and `passwordSudoScript()` to send scripts to `bash -s` on stdin. It has no Node or ssh2 imports, so the Termix mobile app runs the same code
+
 ## 1.0.20
 
 Plugin API 1.12.0.

package/PLUGIN-GUIDE.md

@@ -1,6 +1,6 @@
 # Termix plugin guide
 
-SDK 1.0.20 | Plugin API 1.12.0
+SDK 1.0.22 | Plugin API 1.13.0
 
 This guide is for anyone, person or AI coding tool, building a Termix plugin. It ships inside
 `@termix-ssh/plugin-sdk`, so the copy in your `node_modules` always matches the SDK you have installed.
@@ -175,7 +175,49 @@ Unknown fields are refused at every level, so a typo fails validation. The schem
 
 `contributes` holds `tabs`, `panels`, `dashboardCards`, `actions`, `actionSlots`, `permissions`,
 `settings`, `protocols`, `auth`, `syncEntities`, `keybindingActions`, `http`, `guest`, `guestViews`,
-`uiPresets`, `uses`, `layouts` and `themes`. Frontend `register*` calls need their ids declared here first.
+`uiPresets`, `uses`, `layouts`, `themes` and `mobile`. Frontend `register*` calls need their ids declared here first.
+
+### Mobile app
+
+`contributes.mobile` says how the plugin shows in the Termix mobile app. Leave it out and the app treats the
+plugin as having nothing to show (official plugins are mapped by the app itself).
+
+```json
+"mobile": { "mode": "webview", "views": ["hello"], "sizes": ["phone", "tablet"] }
+```
+
+| Field     | Notes                                                                                                                                             |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mode`    | `webview` (the app shows your UI from the server), `native` (the app has its own screens) or `none`.                                              |
+| `entry`   | `webview` only. A bundle made for the app, like `dist/mobile.js`, next to `frontend.js`. Unset: your normal frontend runs in a phone sized frame. |
+| `sizes`   | `webview` only. `phone`, `tablet` or both (the default).                                                                                          |
+| `views`   | `webview` only. Ids from your `tabs`, `panels` or `dashboardCards` the app offers. Default: every tab.                                            |
+| `feature` | `native` only. The app feature that stands in for the plugin. Default: the plugin id.                                                             |
+| `note`    | A locale key or plain text the app shows next to the plugin.                                                                                      |
+
+`build` makes `entry` from `src/mobile/index.tsx`, and it shares `frontend.css`.
+
+How a `webview` plugin runs in the app:
+
+- Only your plugin loads, with the same app object, SDK hooks and `/ui` kit as the web app. Each view opens
+  on its own screen: a tab with `host-context-menu` in `openFrom` opens from a host, the rest from the app's
+  plugin list.
+- Every request and socket goes through the app, which adds the login, proxy headers and client
+  certificate. The app only lets through your own `/plugin-api`, `/plugin-ws` and `/plugin-assets`, your
+  settings and a short list of core reads (hosts, folders, permissions, current user, version, health,
+  activity). Other core routes answer 403, so call your own backend instead.
+- Images load straight from the server, without proxy headers or a client certificate.
+- Nothing in `localStorage` survives closing the view. Keep preferences in settings.
+- Other plugins' views, extensions and components are not there, and neither is the shell (`useShell()`
+  is null). `/ui` names newer than the app's copy of the SDK make the view say it needs a newer app.
+- The app checks your `engine.api` against the plugin API of its own copy of the SDK. When the app's API
+  is too old for the range, it asks the user to update the app instead of opening the view. When the range
+  is for an older API major, it asks to update the plugin. Ask only for the API you use.
+- Turning a plugin off on the server hides it in the app the next time the app checks: when it comes back
+  to the front, when the list is pulled down, or when any request answers 503 with your `pluginId`.
+
+Termix 26.10.5 and older refuse any manifest with `mobile`, so a plugin that declares it needs
+`"engine": { "termix": ">=26.10.6", "api": "^1.13" }`.
 
 Capabilities and permissions are different things. A capability (`hosts:read`, with a colon) is what your
 code may reach. A permission (`hello.use`, with a dot) is what a user may do.
@@ -304,7 +346,7 @@ router.post("/notes", async (req, res) => {
 - `ctx.rbac.require("manage")` on a single route, `await ctx.rbac.has("manage")` in code. A full id like
   `hosts.edit` checks a core permission.
 - Host access: `ctx.hosts.checkAccess(hostId, "connect" | "view" | "edit" | "manage")`.
-- Transports: with `ssh:transport`, `ctx.ssh.transports.provide({ claims(hostId), open({ id, ip, port }) })`
+- Transports: with `ssh:transport`, `ctx.ssh.transports.provide({ claims(hostId, host), open(host) })`, where `host` has `id`, `ip`, `port` and on Termix 26.10.6+ also `userId`, `syncId`, `connectionOrigin` and `localOnly`
   returns a stream the SSH client uses instead of a direct, proxy or jump host connection. Core also serves
   `/plugin-ws/core/ssh-relay?hostId=` for callers with connect access, so one Termix can relay to another.
 - Managed hosts: with `hosts:lock`, `ctx.hosts.locks.provide({ isLocked, note, allowManualCreate })` makes
@@ -335,7 +377,9 @@ try {
 
 `ctx.ssh.withConnection(hostId, { pool, purpose }, fn)` borrows a pooled connection for frequent short
 commands. `@termix-ssh/plugin-sdk/host-commands` has helpers to detect the OS and run package manager and
-sudo commands. Hosts from `ctx.hosts` never carry secrets. Pass the host or its id to `ctx.ssh`.
+sudo commands. `@termix-ssh/plugin-sdk/host-scripts` builds Docker, metrics, systemd and journal
+commands and parses their output; send a script on stdin to the command `scriptShell()` returns. Hosts from
+`ctx.hosts` never carry secrets. Pass the host or its id to `ctx.ssh`.
 
 ### The desktop app
 
@@ -451,6 +495,23 @@ Other storage: `ctx.kv` for a few values, `ctx.settings` for settings, `ctx.secr
 `ctx.files.dataDir()` for files. To sync a table to a linked desktop, use `ctx.sync.registerEntity` and
 `contributes.syncEntities`. The entity name is part of the protocol and never changes.
 
+A registered table syncs the rows each user owns, both ways. For data you keep for the whole server (a shared
+library, rows other users share), register a read only entity with `table: null`, `readOnly: true` and `load`,
+`write` and `erase` (Termix 26.10.6+). `load(userId)` returns the rows that user should get, each with a
+`syncId`. The desktop keeps them with `write` and drops them with `erase`, and never pushes them back:
+
+```ts
+ctx.sync.registerEntity({
+  type: "sharedIcons",
+  table: null,
+  readOnly: true,
+  order: 70,
+  load: (userId) => iconsVisibleTo(userId),
+  write: (userId, row) => storeCopy(userId, row),
+  erase: (userId, syncId) => dropCopy(userId, syncId),
+});
+```
+
 ## Frontend
 
 ```tsx
@@ -905,6 +966,7 @@ To run your own registry instead, see https://docs.termix.site/develop/registrie
 | `@termix-ssh/plugin-sdk/testing`                                     | `createMockCtx`, `createTestDb`, `renderWithApp`, `createFakeContext`                          |
 | `@termix-ssh/plugin-sdk/vitest-preset`                               | `pluginVitestConfig`                                                                           |
 | `@termix-ssh/plugin-sdk/host-commands`                               | OS detection, package manager and sudo helpers over ssh2                                       |
+| `@termix-ssh/plugin-sdk/host-scripts`                                | Docker, metrics, systemd and journal command builders and parsers, scripts sent to `bash -s`   |
 | `@termix-ssh/plugin-sdk/ssh-certs`                                   | `applyCertificateAuth()` for certificate based SSH auth                                        |
 | `@termix-ssh/plugin-sdk/ssh-keys`                                    | `generateSshKeyPair()`, `detectSshKeyType()`, `publicKeyFromPrivate()`, `validateSshKeyPair()` |
 | `@termix-ssh/plugin-sdk/desktop`                                     | The desktop app bridge, typed. Check it exists before use                                      |

package/cli/commands/build.mjs

@@ -25,6 +25,43 @@ const FRONTEND_ENTRIES = [
   "src/frontend/index.mjs",
   "src/frontend/index.js",
 ];
+const MOBILE_ENTRIES = [
+  "src/mobile/index.tsx",
+  "src/mobile/index.ts",
+  "src/mobile/index.mjs",
+  "src/mobile/index.js",
+];
+
+/** Builds a bundle that runs in a browser against core's shared modules. */
+async function buildBrowserBundle(entry, outfile, outDir) {
+  await esbuild.build({
+    entryPoints: [entry],
+    outfile,
+    bundle: true,
+    format: "esm",
+    platform: "browser",
+    target: "es2022",
+    jsx: "automatic",
+    sourcemap: true,
+    logLevel: "warning",
+    external: FRONTEND_EXTERNALS,
+    // Vite replaces these in the dev server; a plugin bundle has to have
+    // them too, or code that reads them throws when the plugin loads.
+    define: {
+      "process.env.NODE_ENV": '"production"',
+      "import.meta.env.DEV": "false",
+      "import.meta.env.PROD": "true",
+      "import.meta.env.MODE": '"production"',
+      "import.meta.env.SSR": "false",
+      "import.meta.env":
+        '{"DEV":false,"PROD":true,"MODE":"production","SSR":false,"BASE_URL":"/"}',
+    },
+    plugins: [
+      externalRequireInterop(FRONTEND_EXTERNALS),
+      staticUrlImports({ outDir }),
+    ],
+  });
+}
 
 /**
  * A bundled CommonJS package that calls require("react/jsx-runtime") (or any
@@ -192,15 +229,12 @@ export async function buildTailwind(cwd, outDir) {
   // build() adds to what a compiler already emitted, so each half gets its own.
   const compiler = () =>
     compile(input, { base: path.dirname(THEME_CSS), onDependency: () => {} });
-  const scanner = new Scanner({
-    sources: [
-      {
-        base: path.join(cwd, "src", "frontend"),
-        pattern: "**/*",
-        negated: false,
-      },
-    ],
-  });
+  // The mobile bundle uses the same stylesheet.
+  const sources = ["frontend", "mobile"]
+    .map((dir) => path.join(cwd, "src", dir))
+    .filter((dir, index) => index === 0 || fs.existsSync(dir))
+    .map((base) => ({ base, pattern: "**/*", negated: false }));
+  const scanner = new Scanner({ sources });
   // Flattened and minified the way core's own CSS is, so it does not rely
   // on native CSS nesting.
   const emit = async (candidates, options) =>
@@ -297,33 +331,18 @@ export async function build({ cwd }) {
 
   const frontendEntry = resolveEntry(cwd, FRONTEND_ENTRIES);
   if (frontendEntry) {
-    await esbuild.build({
-      entryPoints: [frontendEntry],
-      outfile: path.join(outDir, "frontend.js"),
-      bundle: true,
-      format: "esm",
-      platform: "browser",
-      target: "es2022",
-      jsx: "automatic",
-      sourcemap: true,
-      logLevel: "warning",
-      external: FRONTEND_EXTERNALS,
-      // Vite replaces these in the dev server; a plugin bundle has to have
-      // them too, or code that reads them throws when the plugin loads.
-      define: {
-        "process.env.NODE_ENV": '"production"',
-        "import.meta.env.DEV": "false",
-        "import.meta.env.PROD": "true",
-        "import.meta.env.MODE": '"production"',
-        "import.meta.env.SSR": "false",
-        "import.meta.env":
-          '{"DEV":false,"PROD":true,"MODE":"production","SSR":false,"BASE_URL":"/"}',
-      },
-      plugins: [
-        externalRequireInterop(FRONTEND_EXTERNALS),
-        staticUrlImports({ outDir }),
-      ],
-    });
+    await buildBrowserBundle(
+      frontendEntry,
+      path.join(outDir, "frontend.js"),
+      outDir,
+    );
+  }
+
+  // A bundle the mobile app loads in its WebView, next to the frontend one.
+  const mobileEntry = resolveEntry(cwd, MOBILE_ENTRIES);
+  const mobileOut = manifest.contributes?.mobile?.entry;
+  if (mobileEntry && typeof mobileOut === "string") {
+    await buildBrowserBundle(mobileEntry, path.join(cwd, mobileOut), outDir);
   }
 
   if (frontendEntry) await buildTailwind(cwd, outDir);

package/cli/commands/validate.mjs

@@ -28,6 +28,10 @@ export async function validate({ cwd }) {
     // A theme only plugin has no frontend code.
     ...(isThemeOnly(raw) ? [] : [raw.frontend ?? "dist/frontend.js"]),
     raw.locales ?? "locales",
+    // Built from src/mobile by termix-plugin build.
+    ...(typeof raw.contributes?.mobile?.entry === "string"
+      ? [raw.contributes.mobile.entry]
+      : []),
   ];
   for (const rel of referenced) {
     if (!fs.existsSync(path.join(cwd, rel))) {

package/dist/backend.d.ts

@@ -149,8 +149,24 @@ export interface SyncWriteEvent {
 export interface SyncEntityRegistration {
     /** Stable wire name. Never change it: records on both sides match on it. */
     type: string;
-    /** The table, as returned by ctx.db.define. */
+    /** The table, as returned by ctx.db.define. Null for an entity with `load`. */
     table: unknown;
+    /**
+     * Server to desktop only: a desktop never pushes these rows. Required with
+     * `load`.
+     */
+    readOnly?: boolean;
+    /**
+     * Builds the rows the user gets instead of reading the rows they own in
+     * `table`, for data kept for the whole server (a shared library, rows other
+     * users share with them). Rows are on the wire: plaintext, each with a
+     * syncId. Needs `readOnly: true`, `write` and `erase`.
+     */
+    load?: (userId: string) => Promise<SyncRow[]>;
+    /** Keeps a copy of an inbound row on the desktop, for an entity with `load`. */
+    write?: (userId: string, wire: SyncRow) => Promise<void>;
+    /** Drops the desktop copy with this syncId, for an entity with `load`. */
+    erase?: (userId: string, syncId: string) => Promise<void>;
     /** Column holding the owning user id. Defaults to "userId". */
     userColumn?: string;
     /** Fields stored encrypted with the owner's data key. Plaintext on the wire. */
@@ -391,6 +407,8 @@ export interface PluginSyncHost {
         ensureCore: () => Promise<void>;
         onChanged: (listener: () => void) => () => void;
         onLocalWrite: (listener: () => void) => () => void;
+        /** Local ids of the user's own rows of a type, by sync id. Termix 26.10.6+. */
+        idsOf?: (type: string, userId: string, syncIds: string[]) => Promise<Record<string, number>>;
     };
     /** Rows and bookkeeping of one local user's replica. */
     replica: {
@@ -1503,13 +1521,20 @@ export interface PluginNetwork {
  * asked for every connection, so it must be quick. `open` returns a stream
  * the SSH client runs over, like a relayed socket.
  */
+/** The host a transport is asked about. Fields past port come from Termix 26.10.6. */
+export interface PluginSshTransportHost {
+    id: number;
+    ip: string;
+    port: number;
+    /** Owner of the host row. */
+    userId?: string | null;
+    syncId?: string | null;
+    connectionOrigin?: "local" | "remote" | null;
+    localOnly?: boolean;
+}
 export interface PluginSshTransportProvider {
-    claims: (hostId: number) => boolean;
-    open: (host: {
-        id: number;
-        ip: string;
-        port: number;
-    }) => Promise<import("node:stream").Duplex>;
+    claims: (hostId: number, host?: PluginSshTransportHost) => boolean;
+    open: (host: PluginSshTransportHost) => Promise<import("node:stream").Duplex>;
 }
 export interface PluginSshTransports {
     /** Needs ssh:transport. Removed on deactivate. */

package/dist/frontend.d.ts

@@ -185,6 +185,8 @@ export interface ShellApi {
      * user reviews and saves it. Absent in some shells.
      */
     openHostEditor?: (draft?: HostDraft) => void;
+    /** Opens the editor of a saved host. Termix 26.10.6+, absent in some shells. */
+    editHost?: (hostId: number) => void;
     /** Opens a rail view in the left sidebar. */
     openRailView: (id: string) => void;
     /** Closes a rail view wherever it is shown. */
@@ -412,6 +414,11 @@ export interface RailItemContribution {
      * Zero or nothing shows no badge.
      */
     useBadge?: () => number | null | undefined;
+    /**
+     * A hook for a small status dot on the icon: "ok" (green), "warning" or
+     * "error". Nothing shows no dot. Layouts from Termix 26.10.6 draw it.
+     */
+    useStatus?: () => "ok" | "warning" | "error" | null | undefined;
 }
 export interface PanelProps {
     /**

package/dist/host/{PluginsTab-ZSMTJ5C5.js → PluginsTab-CM2B33BD.js}

@@ -29,12 +29,19 @@ import {
   sortPlugins,
   uploadEntry,
   youtubeEmbedUrl
-} from "./chunk-CITUENSU.js";
+} from "./chunk-ROB2SH5Q.js";
+import {
+  Button,
+  FakeSwitch,
+  Input,
+  PluginIcon,
+  SectionCard,
+  hasSettingsPage
+} from "./chunk-7J4QNGFM.js";
 import {
   ArrowDownWideNarrow,
   BookOpen,
   Bug,
-  Button,
   Check,
   ChevronLeft,
   ChevronRight,
@@ -44,13 +51,11 @@ import {
   Download,
   ExternalLink,
   Facts,
-  FakeSwitch,
   FlaskConical,
   GRID_SIZES,
   Globe,
   GroupHeading,
   InlineView,
-  Input,
   Library,
   Lightbulb,
   ListFilter,
@@ -58,12 +63,10 @@ import {
   PanePrompt,
   PanelShell,
   Pin,
-  PluginIcon,
   Puzzle,
   RefreshCw,
   RotateCcw,
   Search,
-  SectionCard,
   Select,
   SelectContent,
   SelectItem,
@@ -88,7 +91,6 @@ import {
   getPluginRegistry,
   getPlugins,
   getRegistries,
-  hasSettingsPage,
   installPlugin,
   installUploadedPlugin,
   openPluginSettings,
@@ -107,8 +109,8 @@ import {
   updatePlugin,
   uploadPlugin,
   useConfirm
-} from "./chunk-EYONBBRJ.js";
-import "./chunk-7LEJ3HYF.js";
+} from "./chunk-VKNGNEF3.js";
+import "./chunk-P26QKKU5.js";
 import {
   __toESM,
   define_import_meta_env_default,
@@ -1560,9 +1562,12 @@ function usePluginsManager() {
     [run, t, failToast]
   );
   const requestUpload = useCallback2(
-    async (file) => {
+    async (file, signatureFile) => {
       try {
-        const preview = await uploadPlugin(file);
+        const preview = await uploadPlugin(
+          file,
+          signatureFile ? await signatureFile.text() : void 0
+        );
         setConsent({
           plugin: uploadEntry(preview),
           mode: "upload",
@@ -2576,12 +2581,15 @@ function UploadButton({ manager }) {
       {
         ref: input,
         type: "file",
-        accept: ".tmxplug",
+        accept: ".tmxplug,.sig",
+        multiple: true,
         className: "hidden",
         onChange: (e) => {
-          const file = e.target.files?.[0];
+          const files = [...e.target.files ?? []];
           e.target.value = "";
-          if (file) void manager.requestUpload(file);
+          const file = files.find((f) => f.name.endsWith(".tmxplug"));
+          const signature = files.find((f) => f.name.endsWith(".sig"));
+          if (file) void manager.requestUpload(file, signature);
         }
       }
     ),
@@ -2681,7 +2689,7 @@ function InstalledCard({
       )
     ] }) : !running ? /* @__PURE__ */ jsxs6("div", { className: "flex items-center gap-2 border-t border-border px-3 py-2", children: [
       /* @__PURE__ */ jsx6("span", { className: "size-1.5 shrink-0 bg-muted-foreground/40" }),
-      /* @__PURE__ */ jsx6("span", { className: "text-[11px] text-muted-foreground", children: plugin.status === "server" ? t("plugins.manager.status.server") : t("plugins.manager.status.disabled") })
+      /* @__PURE__ */ jsx6("span", { className: "text-[11px] text-muted-foreground", children: plugin.status === "server" ? t("plugins.manager.status.server") : plugin.status === "safeMode" ? t("plugins.manager.status.safeMode") : t("plugins.manager.status.disabled") })
     ] }) : /* @__PURE__ */ jsxs6("div", { className: "flex items-center gap-2 border-t border-border px-3 py-2", children: [
       /* @__PURE__ */ jsx6("span", { className: "size-1.5 shrink-0 bg-green-500" }),
       /* @__PURE__ */ jsx6("span", { className: "text-[11px] text-muted-foreground", children: plugin.pinnedVersion ? t("plugins.manager.pinnedTo", {
@@ -2759,7 +2767,9 @@ function StatusCell({ plugin }) {
   const { t } = useTranslation7();
   const running = plugin.status === "running";
   const failed = plugin.status === "failed" || plugin.status === "blocked";
-  const label = plugin.status === "blocked" ? t("plugins.manager.status.blocked") : failed ? t("plugins.manager.status.failed") : plugin.status === "server" ? t("plugins.manager.status.server") : !running ? t("plugins.manager.status.disabled") : plugin.pinnedVersion ? t("plugins.manager.pinnedTo", { version: plugin.pinnedVersion }) : t("plugins.manager.status.running");
+  const label = plugin.status === "blocked" ? t("plugins.manager.status.blocked") : failed ? t("plugins.manager.status.failed") : plugin.status === "server" ? t("plugins.manager.status.server") : plugin.status === "safeMode" ? t("plugins.manager.status.safeMode") : !running ? t("plugins.manager.status.disabled") : plugin.pinnedVersion ? t("plugins.manager.pinnedTo", {
+    version: plugin.pinnedVersion
+  }) : t("plugins.manager.status.running");
   return /* @__PURE__ */ jsxs6(
     "span",
     {