@termix-ssh/plugin-sdk 1.0.21 → 1.0.23

package/dist/host/{use-permissions-VAND5GEG.js → use-permissions-FLQAN6I7.js}

@@ -7,7 +7,7 @@ import {
   resetPermissionsCache,
   setPermissionsForTesting,
   usePermissions
-} from "./chunk-FGX27MAA.js";
+} from "./chunk-GRH7GSKG.js";
 import "./chunk-YGYBM7SQ.js";
 export {
   hasPermission,

package/dist/host-commands.d.ts

@@ -17,6 +17,13 @@ export interface ExecResult {
     stderr: string;
     code: number | null;
 }
+/**
+ * Decodes raw command output. Strict UTF-8 first; when that fails, tries GBK,
+ * which is what a Chinese-locale Windows console sends (its bytes are almost
+ * never valid UTF-8) and keeps it only when it decodes without replacement
+ * characters. Anything else falls back to lossy UTF-8, the old behavior.
+ */
+export declare function decodeCommandOutput(buf: Buffer): string;
 /** Runs one non-interactive command over an existing ssh2 client. */
 export declare function execCommand(client: Client, command: string, timeoutMs?: number): Promise<ExecResult>;
 export type PackageManager = "apt" | "dnf" | "yum" | "pacman" | null;

package/dist/host-commands.js

@@ -11,6 +11,30 @@
 // Homebrew and OrbStack paths a non-interactive shell misses.
 import { EXTRA_PATH_DIRS } from "./host-scripts/docker.js";
 export { EXTRA_PATH_DIRS };
+/**
+ * Decodes raw command output. Strict UTF-8 first; when that fails, tries GBK,
+ * which is what a Chinese-locale Windows console sends (its bytes are almost
+ * never valid UTF-8) and keeps it only when it decodes without replacement
+ * characters. Anything else falls back to lossy UTF-8, the old behavior.
+ */
+export function decodeCommandOutput(buf) {
+    try {
+        return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(buf);
+    }
+    catch {
+        // not valid UTF-8, try the legacy codepage
+    }
+    try {
+        // A Node built with small-ICU has no GBK decoder and throws here.
+        const gbk = new TextDecoder("gbk").decode(buf);
+        if (!gbk.includes("�"))
+            return gbk;
+    }
+    catch {
+        // expected - fall through to lossy UTF-8
+    }
+    return buf.toString("utf8");
+}
 /** Runs one non-interactive command over an existing ssh2 client. */
 export function execCommand(client, command, timeoutMs = 30000) {
     return new Promise((resolve, reject) => {
@@ -48,8 +72,10 @@ export function execCommand(client, command, timeoutMs = 30000) {
                 return;
             }
             stream = _stream;
-            let stdout = "";
-            let stderr = "";
+            // Chunks are buffered and decoded once on close: a multi-byte character
+            // can be split across chunks, and charset detection needs it whole.
+            const stdout = [];
+            const stderr = [];
             let exitCode = null;
             stream
                 .on("close", (code) => {
@@ -57,11 +83,15 @@ export function execCommand(client, command, timeoutMs = 30000) {
                     settled = true;
                     exitCode = typeof code === "number" ? code : null;
                     cleanup();
-                    resolve({ stdout, stderr, code: exitCode });
+                    resolve({
+                        stdout: decodeCommandOutput(Buffer.concat(stdout)),
+                        stderr: decodeCommandOutput(Buffer.concat(stderr)),
+                        code: exitCode,
+                    });
                 }
             })
                 .on("data", (data) => {
-                stdout += data.toString("utf8");
+                stdout.push(data);
             })
                 .on("error", (streamErr) => {
                 if (!settled) {
@@ -73,7 +103,7 @@ export function execCommand(client, command, timeoutMs = 30000) {
             if (stream.stderr) {
                 stream.stderr
                     .on("data", (data) => {
-                    stderr += data.toString("utf8");
+                    stderr.push(data);
                 })
                     .on("error", (stderrErr) => {
                     if (!settled) {

package/dist/manifest.d.ts

@@ -9,6 +9,7 @@
  * "permissionGroups" used to validate clean and be silently dropped, which
  * made a manifest look like it declared something it did not.
  */
+import { type PluginOperationsContribution } from "./operations.js";
 import { type PluginEnvVar } from "./docs.js";
 export { validateThemeCss } from "./theme-css.js";
 export { ENV_NAME_PATTERN, MAX_ENV_DESCRIPTION_LENGTH, pluginDocsPage, pluginDocsUrl, pluginEnvVars, type PluginEnvVar, } from "./docs.js";
@@ -20,7 +21,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.14.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. */
@@ -305,6 +306,10 @@ export interface PluginContributions {
     tabs?: PluginTabContribution[];
     panels?: PluginViewContribution[];
     dashboardCards?: PluginViewContribution[];
+    /** Cards on the host page, filled with app.registerHostSection. */
+    hostSections?: PluginViewContribution[];
+    /** What this plugin can do, for every surface to find on its own. */
+    operations?: PluginOperationsContribution;
     /**
      * The frontend also runs on anonymous guest pages (shared-session and
      * collab links), where it is activated with app.guest set.
@@ -363,6 +368,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

@@ -11,6 +11,7 @@
  */
 import semver from "semver";
 import { isKnownCapability } from "./capabilities.js";
+import { checkOperationReferences, validateOperations, } from "./operations.js";
 import { ENV_NAME_PATTERN, MAX_ENV_DESCRIPTION_LENGTH, pluginDocsUrl, } from "./docs.js";
 export { validateThemeCss } from "./theme-css.js";
 export { ENV_NAME_PATTERN, MAX_ENV_DESCRIPTION_LENGTH, pluginDocsPage, pluginDocsUrl, pluginEnvVars, } from "./docs.js";
@@ -22,7 +23,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.14.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 +172,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. */
@@ -238,6 +246,8 @@ const ALLOWED_CONTRIBUTES = new Set([
     "tabs",
     "panels",
     "dashboardCards",
+    "hostSections",
+    "operations",
     "guest",
     "guestViews",
     "actions",
@@ -254,6 +264,7 @@ const ALLOWED_CONTRIBUTES = new Set([
     "protocols",
     "layouts",
     "themes",
+    "mobile",
 ]);
 const ALLOWED_SETTINGS_FIELD = [
     "key",
@@ -387,8 +398,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;
@@ -728,6 +838,8 @@ function validateContributes(contributes, pluginId, errors) {
     validateTabs(contributes.tabs, errors);
     validateViews(contributes.panels, "panels", errors);
     validateViews(contributes.dashboardCards, "dashboardCards", errors);
+    validateViews(contributes.hostSections, "hostSections", errors);
+    validateOperations(contributes.operations, pluginId, errors);
     if (contributes.guest !== undefined &&
         typeof contributes.guest !== "boolean") {
         errors.push('Field "contributes.guest" must be a boolean');
@@ -1660,6 +1772,7 @@ export function parseManifest(raw) {
             errors.push(`contributes.actions["${action.id}"].permission "${action.permission}" is not declared in contributes.permissions`);
         }
     }
+    checkOperationReferences(manifest.contributes?.operations, manifest.capabilities, (name) => declared.has(qualifyPermission(manifest.id, name)), errors);
     // A settings field may gate on one of this plugin's own permissions, or on
     // a core/other-plugin id used as given. Only the first form is checkable
     // here, and an undeclared one would hide the field from every admin.

package/dist/operations.d.ts

@@ -0,0 +1,222 @@
+/**
+ * The operations contract: what a plugin declares it can do, in one shape every
+ * surface reads (Automations, Fleets, AI, CLI, Mobile, palette, API, MCP).
+ *
+ * Declarations are data in the manifest, so a surface can list and describe an
+ * action without loading the plugin's code. Handlers are registered at
+ * activation with ctx.operations.register and must match a declaration.
+ *
+ * No Node imports: the frontend, the CLI and Mobile read this file too.
+ */
+import type { PluginSettingsOption } from "./manifest.js";
+export declare const OPERATION_RISKS: readonly ["read", "change", "destructive"];
+export type OperationRisk = (typeof OPERATION_RISKS)[number];
+export declare const OPERATION_SCOPES: readonly ["host", "resource", "server"];
+export type OperationScope = (typeof OPERATION_SCOPES)[number];
+export declare const OPERATION_HOST_ACCESS: readonly ["connect", "view", "edit", "manage"];
+export type OperationHostAccess = (typeof OPERATION_HOST_ACCESS)[number];
+export declare const OPERATION_DRY_RUN: readonly ["native", "describe"];
+/** native: the handler checks ctx.dryRun. describe: core reports its text. */
+export type OperationDryRun = (typeof OPERATION_DRY_RUN)[number];
+export declare const OPERATION_FIELD_TYPES: readonly ["boolean", "string", "number", "select", "multiselect", "secret", "textarea", "json", "resource"];
+export type OperationFieldType = (typeof OPERATION_FIELD_TYPES)[number];
+export declare const OPERATION_SEVERITIES: readonly ["info", "warning", "critical"];
+export type OperationSeverity = (typeof OPERATION_SEVERITIES)[number];
+export declare const SIGNAL_KINDS: readonly ["count", "gauge", "status", "list"];
+export type SignalKind = (typeof SIGNAL_KINDS)[number];
+export declare const SIGNAL_STATUSES: readonly ["ok", "warn", "fail", "unknown"];
+export type SignalStatus = (typeof SIGNAL_STATUSES)[number];
+export declare const RESOURCE_COLUMN_TYPES: readonly ["text", "status", "bytes", "percent", "time", "tags"];
+export type ResourceColumnType = (typeof RESOURCE_COLUMN_TYPES)[number];
+/** One input or output of an action. A subset of a settings field, plus rules. */
+export interface OperationField {
+    key: string;
+    type: OperationFieldType;
+    labelKey?: string;
+    descriptionKey?: string;
+    placeholderKey?: string;
+    default?: unknown;
+    options?: PluginSettingsOption[];
+    min?: number;
+    max?: number;
+    /** Key of a boolean field in the same list that must be on. */
+    requires?: string;
+    group?: string;
+    required?: boolean;
+    /** string and textarea only. A regular expression the whole value matches. */
+    pattern?: string;
+    /** Read action whose rows fill the choices, for a list known only at run time. */
+    optionsFrom?: string;
+    /** type "resource" only: the resource id whose list fills the picker. */
+    resource?: string;
+    /** Outputs only: dropped before a run is stored or shown. */
+    sensitive?: boolean;
+}
+export interface OperationWhen {
+    /** Host setting values that must match, such as { enableDocker: true }. */
+    settings?: Record<string, boolean | string | number>;
+    /** Lowercase OS names. A host with no known OS passes. */
+    os?: string[];
+}
+export interface OperationSurfaces {
+    /** Offered to the AI assistant. Off unless set. */
+    assistant?: boolean;
+    /** Offered over MCP. Off unless set. */
+    mcp?: boolean;
+    /** Set false to keep out of the command palette. */
+    palette?: boolean;
+    /** Set false to keep out of Automations. */
+    automations?: boolean;
+    /** Set false to keep out of the phone app. */
+    mobile?: boolean;
+    /** Set false to keep out of the CLI. */
+    cli?: boolean;
+}
+export interface OperationAction {
+    /** `<pluginId>.<name>`. */
+    id: string;
+    /** Bump when inputs change in a way saved references cannot follow. */
+    version?: number;
+    titleKey: string;
+    descriptionKey?: string;
+    icon?: string;
+    scope: OperationScope;
+    /** Required for scope "resource": the resource this acts on. */
+    resource?: string;
+    inputs?: OperationField[];
+    outputs?: OperationField[];
+    risk: OperationRisk;
+    /** One of this plugin's own permissions, short or full. */
+    permission: string;
+    /** Lowest share level. Required for host and resource scopes. */
+    hostAccess?: OperationHostAccess;
+    dryRun?: OperationDryRun;
+    /** A read action of this plugin that proves the result. */
+    check?: string;
+    /** An action of this plugin that reverses this one. */
+    undo?: string;
+    /** Safe to run twice, so a rollout may retry it. */
+    idempotent?: boolean;
+    /** Only one such action per host at a time. */
+    exclusive?: boolean;
+    timeoutMs?: number;
+    when?: OperationWhen;
+    surfaces?: OperationSurfaces;
+}
+export interface OperationEvent {
+    id: string;
+    titleKey: string;
+    descriptionKey?: string;
+    severity?: OperationSeverity;
+    scope: "host" | "server";
+    payload?: OperationField[];
+}
+export interface ResourceColumn {
+    key: string;
+    titleKey: string;
+    type?: ResourceColumnType;
+}
+export interface OperationResource {
+    id: string;
+    titleKey: string;
+    icon?: string;
+    /** Read action that returns { rows: [...] } for one host. */
+    list: string;
+    /** Row field that is unique on a host. */
+    key: string;
+    /** Row field shown as the name. */
+    name: string;
+    /** Row field holding a status word. */
+    status?: string;
+    /** Row field holding a link, for auto links on the homepage. */
+    url?: string;
+    /** Tab type that opens this on a host. */
+    tab?: string;
+    columns?: ResourceColumn[];
+    filters?: string[];
+}
+export interface OperationSignal {
+    id: string;
+    titleKey: string;
+    /** Read action that returns a SignalResult. */
+    read: string;
+    scope: "host" | "server";
+    kind: SignalKind;
+    refreshSec?: number;
+    /** Action offered as the fix when this signal is not ok. */
+    fix?: string;
+}
+export interface PluginOperationsContribution {
+    actions?: OperationAction[];
+    events?: OperationEvent[];
+    resources?: OperationResource[];
+    signals?: OperationSignal[];
+    /**
+     * Actions this plugin may run through ctx.operations.invoke: exact ids,
+     * `<pluginId>.*`, or `*`.
+     */
+    invokes?: string[];
+}
+/** What a signal's read action returns. */
+export interface SignalResult {
+    value?: number | string | null;
+    status: SignalStatus;
+    label?: string;
+    items?: {
+        label: string;
+        status?: SignalStatus;
+    }[];
+    link?: {
+        tab?: string;
+        data?: Record<string, unknown>;
+    };
+}
+/** What a resource's list action returns. */
+export interface ResourceListResult {
+    rows: Record<string, unknown>[];
+}
+/** What a handler returns. */
+export interface OperationResult {
+    /** One plain line for history and per host results. */
+    summary: string;
+    /** Whether anything actually changed. */
+    changed?: boolean;
+    data?: unknown;
+    /** Input for the `undo` action that reverses this exact run. */
+    undoInput?: Record<string, unknown>;
+}
+export declare const OPERATION_ID_PATTERN: RegExp;
+export declare const MAX_OPERATION_TIMEOUT_MS = 3600000;
+export declare const REDACTED_VALUE = "[redacted]";
+/** Shape checks for contributes.operations, run by validateManifest. */
+export declare function validateOperations(value: unknown, pluginId: string | undefined, errors: string[]): void;
+/**
+ * The cross-field rules: every id one declaration names must exist in this
+ * plugin, or a surface would offer a button that goes nowhere.
+ */
+export declare function checkOperationReferences(operations: PluginOperationsContribution | undefined, capabilities: readonly string[], hasPermission: (name: string) => boolean, errors: string[]): void;
+/** Whether a plugin's invokes list lets it run an action. */
+export declare function invokeAllowed(invokes: readonly string[] | undefined, actionId: string): boolean;
+export declare function riskRank(risk: OperationRisk): number;
+/** A surface's own switch. The assistant and MCP are opt in, the rest opt out. */
+export declare function onSurface(action: Pick<OperationAction, "surfaces">, surface: keyof OperationSurfaces): boolean;
+/** Whether an action applies to a host, from fields any client can read. */
+export declare function matchesWhen(when: OperationWhen | undefined, host: {
+    settings?: Record<string, unknown>;
+    os?: string | null;
+}): boolean;
+export interface OperationInputResult {
+    values: Record<string, unknown>;
+    errors: string[];
+}
+/**
+ * Turns raw input into validated values. Keys no field declares are refused,
+ * so nothing a handler did not ask for ever reaches it.
+ */
+export declare function parseOperationInput(fields: readonly OperationField[] | undefined, raw: unknown): OperationInputResult;
+/** A copy safe to store or show: secret and sensitive values are replaced. */
+export declare function redactFields(fields: readonly OperationField[] | undefined, values: unknown): unknown;
+/** Trims text to a byte-friendly length with a plain marker. */
+export declare function capText(text: string, maxLength: number): string;
+/** JSON Schema for a field list, for AI tools, MCP and OpenAPI. */
+export declare function toJsonSchema(fields: readonly OperationField[] | undefined, describe?: (field: OperationField) => string | undefined): Record<string, unknown>;