@termix-ssh/plugin-sdk 1.0.22 → 1.0.23

package/dist/host/frame-host.js

@@ -1,7 +1,7 @@
 const __termixNoGlob = () => ({});
 import {
   Toaster
-} from "./chunk-TK3Y437H.js";
+} from "./chunk-BP42N374.js";
 import {
   ThemeProvider,
   createPluginApp,
@@ -12,8 +12,8 @@ import {
   setPluginThemes,
   sshHostToHost,
   useTheme
-} from "./chunk-HQ6NNFSX.js";
-import "./chunk-JRV2HIDK.js";
+} from "./chunk-X65V7ZRW.js";
+import "./chunk-GRH7GSKG.js";
 import {
   SurfaceScope,
   notifyShellReady,
@@ -21,13 +21,13 @@ import {
   setShellCallbacks,
   setShellHosts,
   shellHost
-} from "./chunk-VKNGNEF3.js";
+} from "./chunk-DN6YKMFJ.js";
 import {
   getSSHHosts,
   getTabType,
   setFrontendState,
   setPluginSummaries
-} from "./chunk-P26QKKU5.js";
+} from "./chunk-6WLECSNB.js";
 import {
   init_define_import_meta_env
 } from "./chunk-YGYBM7SQ.js";

package/dist/host/{linked-server-J5G457OA.js → linked-server-YCAJ2NX3.js}

@@ -4,7 +4,7 @@ import {
   getLinkedSession,
   notifySyncChanged,
   useDesktopLinked
-} from "./chunk-P26QKKU5.js";
+} from "./chunk-6WLECSNB.js";
 import "./chunk-YGYBM7SQ.js";
 export {
   SYNC_CHANGED_EVENT,

package/dist/host/{rbac-api-PY22W5UY.js → rbac-api-A64TXDL5.js}

@@ -25,7 +25,7 @@ import {
   shareHost,
   updateHostAccess,
   updateRole
-} from "./chunk-P26QKKU5.js";
+} from "./chunk-6WLECSNB.js";
 import "./chunk-YGYBM7SQ.js";
 export {
   assignRoleToUser,

package/dist/host/testing-host.js

@@ -7,7 +7,7 @@ import {
   PluginViewPlaceholder,
   renderTabContent,
   trackTabHandle
-} from "./chunk-I5F2PSMR.js";
+} from "./chunk-GBBKHJRQ.js";
 import {
   RAIL_ITEMS,
   ServerStatusProvider,
@@ -61,11 +61,11 @@ import {
   setRemoteServerUrlForTesting,
   useShellController,
   useTabStageStore
-} from "./chunk-HQ6NNFSX.js";
+} from "./chunk-X65V7ZRW.js";
 import {
   setPermissionsForTesting
-} from "./chunk-JRV2HIDK.js";
-import "./chunk-7J4QNGFM.js";
+} from "./chunk-GRH7GSKG.js";
+import "./chunk-IMPLAAUM.js";
 import {
   SurfaceScope,
   notifyShellReady,
@@ -73,14 +73,14 @@ import {
   setShellCallbacks,
   setShellHosts,
   setShellLayoutProvider
-} from "./chunk-VKNGNEF3.js";
+} from "./chunk-DN6YKMFJ.js";
 import {
   getTabType,
   listTabTypes,
   resetPluginStore,
   setFrontendState,
   setPluginSummaries
-} from "./chunk-P26QKKU5.js";
+} from "./chunk-6WLECSNB.js";
 import {
   init_define_import_meta_env
 } from "./chunk-YGYBM7SQ.js";

package/dist/host/types/src/ui/lib/db-health-monitor.d.ts

@@ -19,6 +19,8 @@ declare class DatabaseHealthMonitor {
     private static instance;
     private listeners;
     private degradedActive;
+    private probe;
+    private probing;
     private constructor();
     static getInstance(): DatabaseHealthMonitor;
     on(event: string, listener: EventListener): void;
@@ -26,6 +28,9 @@ declare class DatabaseHealthMonitor {
     private emit;
     reportSessionExpired(): void;
     reportDatabaseError(error: unknown): void;
+    /** Sets the quick check used after a request times out. */
+    setReachabilityProbe(probe: (() => Promise<boolean>) | null): void;
+    private markDegraded;
     reportDatabaseSuccess(): void;
     isDegraded(): boolean;
     reset(): void;

package/dist/host/ui.js

@@ -21,10 +21,10 @@ import {
   useInstalledPlugins,
   usePluginHostSections,
   useTabHandlesVersion
-} from "./chunk-I5F2PSMR.js";
+} from "./chunk-GBBKHJRQ.js";
 import {
   Toaster
-} from "./chunk-TK3Y437H.js";
+} from "./chunk-BP42N374.js";
 import {
   ACCENT_PRESET_COLORS,
   BUILTIN_THEMES,
@@ -165,10 +165,10 @@ import {
   useThemes,
   verifySecondFactor,
   withProtocolSettings
-} from "./chunk-HQ6NNFSX.js";
+} from "./chunk-X65V7ZRW.js";
 import {
   usePermissions
-} from "./chunk-JRV2HIDK.js";
+} from "./chunk-GRH7GSKG.js";
 import {
   AddButton,
   Card,
@@ -189,7 +189,7 @@ import {
   isPrerelease,
   reportBetaFeedbackUrl,
   reportCoreIssueUrl
-} from "./chunk-ROB2SH5Q.js";
+} from "./chunk-C52NRTA6.js";
 import {
   Button,
   DefaultsOnly,
@@ -206,7 +206,7 @@ import {
   hasVisibleFields,
   isFieldShown,
   useIsDefaultsEditor
-} from "./chunk-7J4QNGFM.js";
+} from "./chunk-IMPLAAUM.js";
 import {
   Action,
   Activity,
@@ -381,7 +381,7 @@ import {
   useSurfaceKind,
   useUiPreference,
   useUiPreferencesContext
-} from "./chunk-VKNGNEF3.js";
+} from "./chunk-DN6YKMFJ.js";
 import {
   CREDENTIAL_ROW_FIELD_KEYS,
   PRESETS,
@@ -544,7 +544,7 @@ import {
   useTabs,
   useTabsSafe,
   verifyPasswordResetCode
-} from "./chunk-P26QKKU5.js";
+} from "./chunk-6WLECSNB.js";
 import {
   define_import_meta_env_default,
   init_define_import_meta_env
@@ -557,7 +557,7 @@ init_define_import_meta_env();
 init_define_import_meta_env();
 import { jsx } from "react/jsx-runtime";
 var alertVariants = cva(
-  "relative w-full border border-border px-4 py-3 text-sm grid has-[>svg]:grid-cols-[calc(var(--spacing)*4)_1fr] grid-cols-[0_1fr] has-[>svg]:gap-x-3 gap-y-0.5 items-start [&>svg]:size-4 [&>svg]:translate-y-0.5 [&>svg]:text-current",
+  "relative w-full border border-border px-4 py-3 text-sm not-has-[>svg]:block grid has-[>svg]:grid-cols-[calc(var(--spacing)*4)_1fr] grid-cols-[0_1fr] has-[>svg]:gap-x-3 gap-y-0.5 items-start [&>svg]:size-4 [&>svg]:translate-y-0.5 [&>svg]:text-current",
   {
     variants: {
       variant: {

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

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

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.13.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.

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.13.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. */
@@ -245,6 +246,8 @@ const ALLOWED_CONTRIBUTES = new Set([
     "tabs",
     "panels",
     "dashboardCards",
+    "hostSections",
+    "operations",
     "guest",
     "guestViews",
     "actions",
@@ -835,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');
@@ -1767,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>;