@termix-ssh/plugin-sdk 1.0.1 → 1.0.4

package/dist/manifest.d.ts

@@ -9,6 +9,8 @@
  * "permissionGroups" used to validate clean and be silently dropped, which
  * made a manifest look like it declared something it did not.
  */
+import { type PluginEnvVar } from "./docs.js";
+export { ENV_NAME_PATTERN, MAX_ENV_DESCRIPTION_LENGTH, pluginDocsPage, pluginDocsUrl, pluginEnvVars, type PluginEnvVar, } from "./docs.js";
 /**
  * The plugin API this build implements. A minor bump adds to the API and
  * never removes; a major bump may break plugins.
@@ -17,7 +19,7 @@
  * "^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.1.0";
+export declare const PLUGIN_API_VERSION = "1.2.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. */
@@ -27,6 +29,13 @@ export declare function isApiCompatible(range: string): boolean;
  * core (2.9.0-beta.1) counts as that release.
  */
 export declare function isTermixCompatible(range: string, coreVersion: string | null): boolean;
+export declare const MAX_FEATURES = 20;
+export declare const MAX_FEATURE_LENGTH = 160;
+/**
+ * The usable feature lines of a manifest or registry entry. Anything that is
+ * not a short non-empty string is dropped, so an index cannot flood the page.
+ */
+export declare function pluginFeatures(value: unknown): string[];
 /**
  * The video id of a YouTube link, or null for anything else. Only the id is
  * ever used, so a manifest can never point the embed at another site.
@@ -416,6 +425,12 @@ export interface PluginManifest {
     icon?: string;
     /** A YouTube link shown at the top of the plugin's page. */
     video?: string;
+    /** Short lines listing what the plugin does, shown on its page. */
+    features?: string[];
+    /** Where the plugin's docs live. https only. */
+    docs?: string;
+    /** Environment variables the plugin reads. */
+    env?: PluginEnvVar[];
     engine: PluginEngine;
     /** Catalog capability ids. */
     capabilities: string[];

package/dist/manifest.js

@@ -11,6 +11,8 @@
  */
 import semver from "semver";
 import { isKnownCapability } from "./capabilities.js";
+import { ENV_NAME_PATTERN, MAX_ENV_DESCRIPTION_LENGTH, pluginDocsUrl, } from "./docs.js";
+export { ENV_NAME_PATTERN, MAX_ENV_DESCRIPTION_LENGTH, pluginDocsPage, pluginDocsUrl, pluginEnvVars, } from "./docs.js";
 /**
  * The plugin API this build implements. A minor bump adds to the API and
  * never removes; a major bump may break plugins.
@@ -19,7 +21,7 @@ import { isKnownCapability } from "./capabilities.js";
  * "^1.2" needs 1.2 or later). engine.termix is checked against the core
  * version by the server.
  */
-export const PLUGIN_API_VERSION = "1.1.0";
+export const PLUGIN_API_VERSION = "1.2.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. */
@@ -47,6 +49,22 @@ const YOUTUBE_HOSTS = new Set([
     "youtube-nocookie.com",
     "www.youtube-nocookie.com",
 ]);
+export const MAX_FEATURES = 20;
+export const MAX_FEATURE_LENGTH = 160;
+/**
+ * The usable feature lines of a manifest or registry entry. Anything that is
+ * not a short non-empty string is dropped, so an index cannot flood the page.
+ */
+export function pluginFeatures(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .filter((f) => typeof f === "string" &&
+        f.trim().length > 0 &&
+        f.length <= MAX_FEATURE_LENGTH)
+        .map((f) => f.trim())
+        .slice(0, MAX_FEATURES);
+}
 /**
  * The video id of a YouTube link, or null for anything else. Only the id is
  * ever used, so a manifest can never point the embed at another site.
@@ -190,6 +208,9 @@ const ALLOWED_TOP_LEVEL = new Set([
     "repository",
     "icon",
     "video",
+    "features",
+    "docs",
+    "env",
     "dependencies",
     "optionalDependencies",
     "provides",
@@ -319,6 +340,11 @@ export function validateManifest(manifest) {
     if ("video" in m && youtubeVideoId(m.video) === null) {
         errors.push(`Field "video" must be a YouTube link such as https://www.youtube.com/watch?v=..., got: ${JSON.stringify(m.video)}`);
     }
+    validateFeatures(m.features, errors);
+    if ("docs" in m && pluginDocsUrl(m.docs) === null) {
+        errors.push(`Field "docs" must be an https URL, got: ${JSON.stringify(m.docs)}`);
+    }
+    validateEnv(m.env, errors);
     for (const field of ["backend", "frontend", "locales"]) {
         if (field in m && requireString(m[field], field, errors)) {
             requireRelativePath(m[field], field, errors);
@@ -343,6 +369,63 @@ export function validateManifest(manifest) {
     validateContributes(m.contributes, typeof m.id === "string" ? m.id : undefined, errors);
     return errors;
 }
+function validateFeatures(features, errors) {
+    if (features === undefined)
+        return;
+    if (!Array.isArray(features)) {
+        errors.push('Field "features" must be an array of strings');
+        return;
+    }
+    if (features.length > MAX_FEATURES) {
+        errors.push(`Field "features" may list at most ${MAX_FEATURES} items`);
+    }
+    features.forEach((feature, i) => {
+        if (typeof feature !== "string" ||
+            feature.trim().length === 0 ||
+            feature.length > MAX_FEATURE_LENGTH) {
+            errors.push(`Field "features[${i}]" must be a non-empty string of at most ${MAX_FEATURE_LENGTH} characters`);
+        }
+    });
+}
+function validateEnv(env, errors) {
+    if (env === undefined)
+        return;
+    if (!Array.isArray(env)) {
+        errors.push('Field "env" must be an array');
+        return;
+    }
+    const seen = new Set();
+    env.forEach((entry, i) => {
+        const where = `env[${i}]`;
+        if (!isPlainObject(entry)) {
+            errors.push(`Field "${where}" must be an object`);
+            return;
+        }
+        rejectUnknown(entry, ["name", "description", "default", "required", "secret"], where, errors);
+        if (typeof entry.name !== "string" || !ENV_NAME_PATTERN.test(entry.name)) {
+            errors.push(`Field "${where}.name" must be an uppercase name like MY_PLUGIN_URL, got: ${JSON.stringify(entry.name)}`);
+        }
+        else if (seen.has(entry.name)) {
+            errors.push(`Field "${where}.name" repeats ${entry.name}`);
+        }
+        else {
+            seen.add(entry.name);
+        }
+        if (typeof entry.description !== "string" ||
+            entry.description.trim().length === 0 ||
+            entry.description.length > MAX_ENV_DESCRIPTION_LENGTH) {
+            errors.push(`Field "${where}.description" must be a non-empty string of at most ${MAX_ENV_DESCRIPTION_LENGTH} characters`);
+        }
+        if ("default" in entry && typeof entry.default !== "string") {
+            errors.push(`Field "${where}.default" must be a string`);
+        }
+        for (const flag of ["required", "secret"]) {
+            if (flag in entry && typeof entry[flag] !== "boolean") {
+                errors.push(`Field "${where}.${flag}" must be true or false`);
+            }
+        }
+    });
+}
 function validateAuthor(author, errors) {
     if (author === undefined)
         return;

package/dist/openapi.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Builds an OpenAPI spec from the @openapi JSDoc blocks above routes. Core and
+ * every plugin use this, so the docs site renders them all the same way.
+ */
+export interface OpenApiTag {
+    name: string;
+    description?: string;
+}
+export interface BuildOpenApiOptions {
+    title: string;
+    version: string;
+    description?: string;
+    /** Source files or globs holding @openapi blocks. */
+    files: string[];
+    tags?: OpenApiTag[];
+}
+export type OpenApiSpec = Record<string, unknown> & {
+    paths?: Record<string, unknown>;
+};
+/** How every Termix route is signed in to. */
+export declare const TERMIX_SECURITY_SCHEMES: {
+    readonly bearerAuth: {
+        readonly type: "http";
+        readonly scheme: "bearer";
+        readonly bearerFormat: "JWT";
+        readonly description: "Session token sent in the Authorization header as Bearer and the token.";
+    };
+    readonly cookieAuth: {
+        readonly type: "apiKey";
+        readonly in: "cookie";
+        readonly name: "jwt";
+        readonly description: "Session JWT cookie set at sign-in. When present, it takes precedence over the Authorization header.";
+    };
+    readonly apiKeyAuth: {
+        readonly type: "http";
+        readonly scheme: "bearer";
+        readonly bearerFormat: "API key starting with tmx_";
+        readonly description: "API key sent in the Authorization header as Bearer and the key, which starts with tmx_. It acts as the key owner and cannot act as anyone else.";
+    };
+};
+export declare function buildOpenApi(options: BuildOpenApiOptions): Promise<OpenApiSpec>;
+/** Whether a spec documents any route. */
+export declare function hasOpenApiPaths(spec: OpenApiSpec): boolean;

package/dist/openapi.js

@@ -0,0 +1,60 @@
+/**
+ * Builds an OpenAPI spec from the @openapi JSDoc blocks above routes. Core and
+ * every plugin use this, so the docs site renders them all the same way.
+ */
+import swaggerJSDoc from "@deadendjs/swagger-jsdoc";
+/** How every Termix route is signed in to. */
+export const TERMIX_SECURITY_SCHEMES = {
+    bearerAuth: {
+        type: "http",
+        scheme: "bearer",
+        bearerFormat: "JWT",
+        description: "Session token sent in the Authorization header as Bearer and the token.",
+    },
+    cookieAuth: {
+        type: "apiKey",
+        in: "cookie",
+        name: "jwt",
+        description: "Session JWT cookie set at sign-in. When present, it takes precedence over the Authorization header.",
+    },
+    apiKeyAuth: {
+        type: "http",
+        scheme: "bearer",
+        bearerFormat: "API key starting with tmx_",
+        description: "API key sent in the Authorization header as Bearer and the key, which starts with tmx_. It acts as the key owner and cannot act as anyone else.",
+    },
+};
+export async function buildOpenApi(options) {
+    const spec = (await swaggerJSDoc({
+        definition: {
+            openapi: "3.0.3",
+            info: {
+                title: options.title,
+                version: options.version,
+                ...(options.description ? { description: options.description } : {}),
+            },
+            servers: [{ url: "/", description: "Your Termix server" }],
+            components: {
+                securitySchemes: TERMIX_SECURITY_SCHEMES,
+                schemas: {
+                    Error: {
+                        type: "object",
+                        properties: {
+                            error: { type: "string" },
+                            details: { type: "string" },
+                        },
+                    },
+                },
+            },
+            security: [{ bearerAuth: [] }, { cookieAuth: [] }, { apiKeyAuth: [] }],
+            ...(options.tags?.length ? { tags: options.tags } : {}),
+        },
+        apis: options.files.map((f) => f.replace(/\\/g, "/")),
+        failOnErrors: true,
+    }));
+    return spec;
+}
+/** Whether a spec documents any route. */
+export function hasOpenApiPaths(spec) {
+    return Object.keys(spec.paths ?? {}).length > 0;
+}

package/dist/testing/setup.js

@@ -77,6 +77,7 @@ const noop = () => { };
 const offline = () => Promise.reject(new Error("No plugin API in a unit test; mock it"));
 globalThis.__termixTestPluginHost = {
     usePluginId: () => "test-plugin",
+    useDocsUrl: () => null,
     useTranslation: () => ({
         t: (key) => key,
         language: "en",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@termix-ssh/plugin-sdk",
-  "version": "1.0.1",
+  "version": "1.0.4",
   "description": "The contract between Termix core and a plugin: types, the capability catalog and the manifest schema.",
   "license": "Apache-2.0",
   "repository": {
@@ -14,7 +14,7 @@
     "node": ">=22"
   },
   "bin": {
-    "termix-plugin": "./cli/index.mjs"
+    "termix-plugin": "cli/index.mjs"
   },
   "exports": {
     "./backend": {
@@ -53,6 +53,14 @@
       "types": "./dist/changelog.d.ts",
       "default": "./dist/changelog.js"
     },
+    "./docs": {
+      "types": "./dist/docs.d.ts",
+      "default": "./dist/docs.js"
+    },
+    "./openapi": {
+      "types": "./dist/openapi.d.ts",
+      "default": "./dist/openapi.js"
+    },
     "./settings": {
       "types": "./dist/settings.d.ts",
       "default": "./dist/settings.js"
@@ -94,6 +102,7 @@
     "schema",
     "tsconfig.plugin.json",
     "README.md",
+    "CHANGELOG.md",
     "client.d.ts"
   ],
   "scripts": {
@@ -101,6 +110,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
+    "@deadendjs/swagger-jsdoc": "^8.1.2",
     "@tailwindcss/node": "^4.2.4",
     "@tailwindcss/oxide": "^4.2.4",
     "esbuild": "^0.28.1",

package/schema/manifest.schema.json

@@ -79,6 +79,33 @@
       "pattern": "^https://(www\\.|m\\.)?(youtube\\.com|youtu\\.be|youtube-nocookie\\.com)/",
       "description": "A YouTube link shown at the top of the plugin's page."
     },
+    "features": {
+      "type": "array",
+      "maxItems": 20,
+      "items": { "type": "string", "minLength": 1, "maxLength": 160 },
+      "description": "Short lines listing what the plugin does, shown on its page."
+    },
+    "docs": {
+      "type": "string",
+      "pattern": "^https://",
+      "description": "Where the plugin's docs live. Shown as a Documentation link in Termix."
+    },
+    "env": {
+      "type": "array",
+      "description": "Environment variables the plugin reads, listed in its docs.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "description"],
+        "properties": {
+          "name": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,63}$" },
+          "description": { "type": "string", "minLength": 1, "maxLength": 300 },
+          "default": { "type": "string" },
+          "required": { "type": "boolean" },
+          "secret": { "type": "boolean" }
+        }
+      }
+    },
     "engine": {
       "type": "object",
       "additionalProperties": false,