@termix-ssh/plugin-sdk 1.0.20 → 1.0.22

package/dist/host-scripts/text.js

@@ -0,0 +1,111 @@
+/**
+ * Quoting, encoding and the error type the host scripts share.
+ *
+ * No Node APIs here: this entry also runs in the mobile app.
+ */
+/** A bad input to a host script builder. `status` is the HTTP status to answer with. */
+export class HostScriptError extends Error {
+    status;
+    extra;
+    constructor(message, status = 400, extra = {}) {
+        super(message);
+        this.status = status;
+        this.extra = extra;
+        this.name = "HostScriptError";
+    }
+}
+/** Wraps a value in single quotes for a POSIX shell. */
+export function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+// Written by hand because some JS engines (Hermes) have no TextDecoder.
+/** UTF-8 bytes of a string. */
+export function utf8Encode(text) {
+    const out = [];
+    for (const char of text) {
+        const cp = char.codePointAt(0) ?? 0xfffd;
+        if (cp < 0x80)
+            out.push(cp);
+        else if (cp < 0x800)
+            out.push(0xc0 | (cp >> 6), 0x80 | (cp & 63));
+        else if (cp < 0x10000) {
+            out.push(0xe0 | (cp >> 12), 0x80 | ((cp >> 6) & 63), 0x80 | (cp & 63));
+        }
+        else {
+            out.push(0xf0 | (cp >> 18), 0x80 | ((cp >> 12) & 63), 0x80 | ((cp >> 6) & 63), 0x80 | (cp & 63));
+        }
+    }
+    return Uint8Array.from(out);
+}
+/** A string from UTF-8 bytes. Bad sequences become U+FFFD. */
+export function utf8Decode(bytes) {
+    let out = "";
+    let i = 0;
+    while (i < bytes.length) {
+        const b = bytes[i];
+        let need = 0;
+        let cp = 0;
+        if (b < 0x80)
+            cp = b;
+        else if (b >= 0xc2 && b < 0xe0)
+            [need, cp] = [1, b & 31];
+        else if (b >= 0xe0 && b < 0xf0)
+            [need, cp] = [2, b & 15];
+        else if (b >= 0xf0 && b < 0xf5)
+            [need, cp] = [3, b & 7];
+        else {
+            out += "\ufffd";
+            i++;
+            continue;
+        }
+        let j = 1;
+        for (; j <= need; j++) {
+            const next = bytes[i + j];
+            if (next === undefined || (next & 0xc0) !== 0x80)
+                break;
+            cp = (cp << 6) | (next & 63);
+        }
+        const tooSmall = [0, 0x80, 0x800, 0x10000][need];
+        if (j <= need ||
+            cp < tooSmall ||
+            cp > 0x10ffff ||
+            (cp >= 0xd800 && cp < 0xe000)) {
+            out += "\ufffd";
+            i += Math.max(1, j);
+            continue;
+        }
+        out += String.fromCodePoint(cp);
+        i += need + 1;
+    }
+    return out;
+}
+const B64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+/** Base64 of the UTF-8 bytes of a string, for `base64 -d` on the host. */
+export function toBase64(text) {
+    const bytes = utf8Encode(text);
+    let out = "";
+    for (let i = 0; i < bytes.length; i += 3) {
+        const a = bytes[i];
+        const b = i + 1 < bytes.length ? bytes[i + 1] : 0;
+        const c = i + 2 < bytes.length ? bytes[i + 2] : 0;
+        const n = (a << 16) | (b << 8) | c;
+        out += B64[(n >> 18) & 63] + B64[(n >> 12) & 63];
+        out += i + 1 < bytes.length ? B64[(n >> 6) & 63] : "=";
+        out += i + 2 < bytes.length ? B64[n & 63] : "=";
+    }
+    return out;
+}
+/** Reads key=value lines. Only the first = splits a line. */
+export function parseKeys(output) {
+    const out = {};
+    for (const line of output.split("\n")) {
+        const eq = line.indexOf("=");
+        if (eq > 0)
+            out[line.slice(0, eq).trim()] = line.slice(eq + 1).trim();
+    }
+    return out;
+}
+/** Trims output and keeps it short enough to show. */
+export function scrub(text, max = 600) {
+    return text.trim().slice(0, max);
+}

package/dist/manifest.d.ts

@@ -20,7 +20,7 @@ export { ENV_NAME_PATTERN, MAX_ENV_DESCRIPTION_LENGTH, pluginDocsPage, pluginDoc
  * "^1.2" needs 1.2 or later). engine.termix is checked against the core
  * version by the server.
  */
-export declare const PLUGIN_API_VERSION = "1.12.0";
+export declare const PLUGIN_API_VERSION = "1.13.0";
 /** The API major, the default engine.api for a new plugin. */
 export declare const SUPPORTED_PLUGIN_API_VERSION: string;
 /** Whether this build's plugin API satisfies a manifest's engine.api. */
@@ -363,6 +363,33 @@ export interface PluginContributions {
     layouts?: PluginLayoutContribution[];
     /** Themes. Needs the ui:theme capability. */
     themes?: PluginThemeContribution[];
+    /** How the plugin shows in the Termix mobile app. Plugin API 1.13. */
+    mobile?: PluginMobileContribution;
+}
+/**
+ * - "webview": the app shows the plugin's UI from the server in a WebView.
+ * - "native": the app has its own screens for this plugin.
+ * - "none": nothing to show in the app.
+ */
+export declare const MOBILE_MODES: readonly ["webview", "native", "none"];
+export type PluginMobileMode = (typeof MOBILE_MODES)[number];
+export declare const MOBILE_SIZES: readonly ["phone", "tablet"];
+export type PluginMobileSize = (typeof MOBILE_SIZES)[number];
+export interface PluginMobileContribution {
+    mode: PluginMobileMode;
+    /**
+     * webview: a bundle built for the app, in the same folder as the frontend
+     * bundle. Unset means the normal frontend runs in a phone sized frame.
+     */
+    entry?: string;
+    /** webview: screen sizes the UI works at. Defaults to both. */
+    sizes?: PluginMobileSize[];
+    /** webview: tab, panel or card ids the app offers. Defaults to every tab. */
+    views?: string[];
+    /** native: the app feature that stands in for it. Defaults to the plugin id. */
+    feature?: string;
+    /** i18n key in the plugin's namespace, or plain text, shown in the app. */
+    note?: string;
 }
 /** A field a protocol login carries besides username and password. */
 export interface PluginProtocolCredentialField {

package/dist/manifest.js

@@ -22,7 +22,7 @@ export { ENV_NAME_PATTERN, MAX_ENV_DESCRIPTION_LENGTH, pluginDocsPage, pluginDoc
  * "^1.2" needs 1.2 or later). engine.termix is checked against the core
  * version by the server.
  */
-export const PLUGIN_API_VERSION = "1.12.0";
+export const PLUGIN_API_VERSION = "1.13.0";
 /** The API major, the default engine.api for a new plugin. */
 export const SUPPORTED_PLUGIN_API_VERSION = String(semver.major(PLUGIN_API_VERSION));
 /** Whether this build's plugin API satisfies a manifest's engine.api. */
@@ -171,6 +171,13 @@ export const SETTINGS_FIELD_TYPES = [
 export const SETTINGS_SCOPES = ["admin", "user", "host"];
 /** A layout id or theme id: short, lowercase, used as a CSS class for themes. */
 export const LOOK_ID_PATTERN = /^[a-z][a-z0-9-]{1,39}$/;
+/**
+ * - "webview": the app shows the plugin's UI from the server in a WebView.
+ * - "native": the app has its own screens for this plugin.
+ * - "none": nothing to show in the app.
+ */
+export const MOBILE_MODES = ["webview", "native", "none"];
+export const MOBILE_SIZES = ["phone", "tablet"];
 /** Protocol ids core keeps for itself. */
 export const RESERVED_PROTOCOL_IDS = ["ssh"];
 /** Login keys a declared credential field may not reuse. */
@@ -254,6 +261,7 @@ const ALLOWED_CONTRIBUTES = new Set([
     "protocols",
     "layouts",
     "themes",
+    "mobile",
 ]);
 const ALLOWED_SETTINGS_FIELD = [
     "key",
@@ -387,8 +395,107 @@ export function validateManifest(manifest) {
     validateProvidesSecret(m.providesSecret, errors);
     validateRequiresSecret(m.requiresSecret, errors);
     validateContributes(m.contributes, typeof m.id === "string" ? m.id : undefined, errors);
+    if (isPlainObject(m.contributes)) {
+        validateMobile(m.contributes, typeof m.frontend === "string" ? m.frontend : DEFAULT_FRONTEND_ENTRY, errors);
+    }
     return errors;
 }
+function folderOf(file) {
+    const parts = file.split("/").filter((part) => part !== "" && part !== ".");
+    return parts.slice(0, -1).join("/");
+}
+function validateMobile(contributes, frontend, errors) {
+    const mobile = contributes.mobile;
+    if (mobile === undefined)
+        return;
+    const where = "contributes.mobile";
+    if (!isPlainObject(mobile)) {
+        errors.push(`Field "${where}" must be an object`);
+        return;
+    }
+    rejectUnknown(mobile, ["mode", "entry", "sizes", "views", "feature", "note"], `"${where}"`, errors);
+    const mode = mobile.mode;
+    if (!MOBILE_MODES.includes(mode)) {
+        errors.push(`${where}.mode must be one of: ${MOBILE_MODES.join(", ")}`);
+        return;
+    }
+    for (const key of ["entry", "sizes", "views"]) {
+        if (mobile[key] !== undefined && mode !== "webview") {
+            errors.push(`${where}.${key} is only for mode "webview"`);
+        }
+    }
+    if (mobile.feature !== undefined && mode !== "native") {
+        errors.push(`${where}.feature is only for mode "native"`);
+    }
+    if (mobile.entry !== undefined &&
+        requireString(mobile.entry, `${where}.entry`, errors)) {
+        const before = errors.length;
+        requireRelativePath(mobile.entry, `${where}.entry`, errors);
+        if (!mobile.entry.endsWith(".js")) {
+            errors.push(`${where}.entry must be a .js file`);
+        }
+        else if (errors.length === before &&
+            folderOf(mobile.entry) !== folderOf(frontend)) {
+            // Core only serves the folder the frontend bundle sits in.
+            errors.push(`${where}.entry must sit in the same folder as the frontend bundle (${frontend})`);
+        }
+    }
+    if (mobile.sizes !== undefined) {
+        const sizes = mobile.sizes;
+        if (!Array.isArray(sizes) || sizes.length === 0) {
+            errors.push(`${where}.sizes must be a non-empty array`);
+        }
+        else {
+            const seen = new Set();
+            for (const size of sizes) {
+                if (!MOBILE_SIZES.includes(size)) {
+                    errors.push(`${where}.sizes entries must be one of: ${MOBILE_SIZES.join(", ")}`);
+                }
+                else if (seen.has(size)) {
+                    errors.push(`${where}.sizes duplicates "${String(size)}"`);
+                }
+                seen.add(size);
+            }
+        }
+    }
+    if (mobile.views !== undefined) {
+        const views = mobile.views;
+        if (!Array.isArray(views) || views.length === 0) {
+            errors.push(`${where}.views must be a non-empty array`);
+        }
+        else {
+            const declared = new Set();
+            for (const field of ["tabs", "panels", "dashboardCards"]) {
+                const list = contributes[field];
+                if (!Array.isArray(list))
+                    continue;
+                for (const view of list) {
+                    if (isPlainObject(view) && typeof view.id === "string") {
+                        declared.add(view.id);
+                    }
+                }
+            }
+            const seen = new Set();
+            for (const view of views) {
+                if (typeof view !== "string" || !declared.has(view)) {
+                    errors.push(`${where}.views entries must be ids from contributes.tabs, panels or dashboardCards, got: ${JSON.stringify(view)}`);
+                }
+                else if (seen.has(view)) {
+                    errors.push(`${where}.views duplicates "${view}"`);
+                }
+                seen.add(view);
+            }
+        }
+    }
+    if (mobile.feature !== undefined &&
+        (typeof mobile.feature !== "string" ||
+            !LOOK_ID_PATTERN.test(mobile.feature))) {
+        errors.push(`${where}.feature must match ${LOOK_ID_PATTERN} (lowercase letters, digits, dashes)`);
+    }
+    if (mobile.note !== undefined) {
+        requireString(mobile.note, `${where}.note`, errors);
+    }
+}
 function validateFeatures(features, errors) {
     if (features === undefined)
         return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@termix-ssh/plugin-sdk",
-  "version": "1.0.20",
+  "version": "1.0.22",
   "description": "The contract between Termix core and a plugin: types, the capability catalog and the manifest schema.",
   "license": "Apache-2.0",
   "repository": {
@@ -81,6 +81,10 @@
       "types": "./dist/host-commands.d.ts",
       "default": "./dist/host-commands.js"
     },
+    "./host-scripts": {
+      "types": "./dist/host-scripts/index.d.ts",
+      "default": "./dist/host-scripts/index.js"
+    },
     "./ssh-certs": {
       "types": "./dist/ssh-certs.d.ts",
       "default": "./dist/ssh-certs.js"
@@ -98,6 +102,10 @@
     "./testing-host": {
       "default": "./dist/host/testing-host.js"
     },
+    "./frame-host": {
+      "default": "./dist/host/frame-host.js"
+    },
+    "./frame-host.css": "./dist/host/frame-host.css",
     "./theme.css": "./dist/host/theme.css"
   },
   "files": [

package/schema/manifest.schema.json

@@ -1239,6 +1239,48 @@
               }
             }
           }
+        },
+        "mobile": {
+          "type": "object",
+          "description": "How the plugin shows in the Termix mobile app. Needs plugin API 1.13 (Termix 26.10.6).",
+          "additionalProperties": false,
+          "required": ["mode"],
+          "properties": {
+            "mode": {
+              "type": "string",
+              "enum": ["webview", "native", "none"],
+              "description": "webview: the app shows the plugin's UI from the server. native: the app has its own screens. none: nothing to show in the app."
+            },
+            "entry": {
+              "type": "string",
+              "pattern": "\\.js$",
+              "description": "webview only. A bundle built for the app, in the same folder as the frontend bundle. Unset means the normal frontend runs in a phone sized frame."
+            },
+            "sizes": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": { "type": "string", "enum": ["phone", "tablet"] },
+              "description": "webview only. Screen sizes the UI works at. Defaults to both."
+            },
+            "views": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": { "type": "string", "minLength": 1 },
+              "description": "webview only. Tab, panel or card ids the app offers. Defaults to every tab."
+            },
+            "feature": {
+              "type": "string",
+              "pattern": "^[a-z][a-z0-9-]{1,39}$",
+              "description": "native only. The app feature that stands in for this plugin. Defaults to the plugin id."
+            },
+            "note": {
+              "type": "string",
+              "minLength": 1,
+              "description": "i18n key in the plugin's namespace, or plain text, shown in the app."
+            }
+          }
         }
       }
     },