@termix-ssh/plugin-sdk 1.0.22 → 1.0.24

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>;