@termix-ssh/plugin-sdk 1.0.0 → 1.0.2

package/dist/host/{use-permissions-NULZL43J.js → use-permissions-5CZEA3P4.js}

@@ -1,15 +1,17 @@
 const __termixNoGlob = () => ({});
 import {
   hasPermission,
+  loadPermissionChecker,
   notifyPermissionsChanged,
   preloadPermissions,
   resetPermissionsCache,
   setPermissionsForTesting,
   usePermissions
-} from "./chunk-XGWE7BTJ.js";
+} from "./chunk-XKMRKQFN.js";
 import "./chunk-YC2MAKSP.js";
 export {
   hasPermission,
+  loadPermissionChecker,
   notifyPermissionsChanged,
   preloadPermissions,
   resetPermissionsCache,

package/dist/manifest.d.ts

@@ -17,7 +17,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.0.0";
+export declare const PLUGIN_API_VERSION = "1.1.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 +27,18 @@ 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.
+ */
+export declare function youtubeVideoId(value: unknown): string | null;
 export declare const PLUGIN_CATEGORIES: readonly ["Terminal", "Files & Transfer", "Infrastructure", "Monitoring", "Networking", "Access & Security", "Productivity"];
 export declare const PLUGIN_PLATFORMS: readonly ["linux", "win32", "darwin"];
 export declare const ACTION_CONTRIBUTION_KINDS: readonly ["button", "component"];
@@ -327,7 +339,8 @@ export interface PluginProtocolContribution {
     defaultPort?: number;
     /**
      * What the owner's login falls back to from the host's own SSH login
-     * when the protocol login leaves it empty.
+     * when the protocol login leaves it empty. The password only falls back
+     * while the host signs in to SSH with a password.
      */
     hostLoginFallback?: Array<"username" | "password">;
 }
@@ -408,6 +421,10 @@ export interface PluginManifest {
     repository?: string;
     category: string;
     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[];
     engine: PluginEngine;
     /** Catalog capability ids. */
     capabilities: string[];

package/dist/manifest.js

@@ -19,7 +19,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.0.0";
+export const PLUGIN_API_VERSION = "1.1.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. */
@@ -38,6 +38,62 @@ export function isTermixCompatible(range, coreVersion) {
         return false;
     return semver.satisfies(semver.coerce(coreVersion).version, range);
 }
+const YOUTUBE_ID = /^[A-Za-z0-9_-]{11}$/;
+const YOUTUBE_HOSTS = new Set([
+    "youtube.com",
+    "www.youtube.com",
+    "m.youtube.com",
+    "youtu.be",
+    "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.
+ */
+export function youtubeVideoId(value) {
+    if (typeof value !== "string")
+        return null;
+    let url;
+    try {
+        url = new URL(value.trim());
+    }
+    catch {
+        return null;
+    }
+    if (url.protocol !== "https:" || url.username || url.password)
+        return null;
+    const host = url.hostname.toLowerCase();
+    if (!YOUTUBE_HOSTS.has(host))
+        return null;
+    let id;
+    if (host === "youtu.be") {
+        id = url.pathname.slice(1);
+    }
+    else if (url.pathname === "/watch") {
+        id = url.searchParams.get("v");
+    }
+    else {
+        id = /^\/(?:embed|shorts|live)\/([^/]+)\/?$/.exec(url.pathname)?.[1];
+    }
+    return id && YOUTUBE_ID.test(id) ? id : null;
+}
 export const PLUGIN_CATEGORIES = [
     "Terminal",
     "Files & Transfer",
@@ -64,6 +120,7 @@ export const RESERVED_PLUGIN_IDS = [
     "termix",
     "plugin",
     "plugins",
+    "onboarding",
     "users",
     "system",
     "sdk",
@@ -148,6 +205,8 @@ const ALLOWED_TOP_LEVEL = new Set([
     ...REQUIRED_TOP_LEVEL,
     "repository",
     "icon",
+    "video",
+    "features",
     "dependencies",
     "optionalDependencies",
     "provides",
@@ -274,6 +333,10 @@ export function validateManifest(manifest) {
         requireString(m.repository, "repository", errors);
     if ("icon" in m)
         requireString(m.icon, "icon", errors);
+    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);
     for (const field of ["backend", "frontend", "locales"]) {
         if (field in m && requireString(m[field], field, errors)) {
             requireRelativePath(m[field], field, errors);
@@ -298,6 +361,24 @@ 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 validateAuthor(author, errors) {
     if (author === undefined)
         return;

package/dist/testing/setup.js

@@ -7,6 +7,14 @@
 import { afterEach, vi } from "vitest";
 import { installSafePorts } from "./safe-ports.js";
 installSafePorts();
+// Radix measures some controls (Checkbox, Switch) and jsdom has no observer.
+if (typeof globalThis.ResizeObserver === "undefined") {
+    globalThis.ResizeObserver = class {
+        observe() { }
+        unobserve() { }
+        disconnect() { }
+    };
+}
 if (typeof window !== "undefined" && !window.matchMedia) {
     window.matchMedia = vi.fn().mockImplementation((query) => ({
         matches: false,

package/dist/testing.d.ts

@@ -492,6 +492,8 @@ export interface RenderedPluginApp {
         paletteGroups: () => string[];
         keybindingActions: () => string[];
         keybindingDefaults: () => string[];
+        /** Onboarding step ids, without the plugin prefix. */
+        onboardingSteps: () => string[];
     };
     /** A registered palette group's items, as the palette loads them on open. */
     loadPaletteGroup: (id: string) => Promise<import("./frontend.js").PaletteItem[]>;
@@ -515,6 +517,16 @@ export interface RenderedPluginApp {
     renderTab: (type: string, props?: Record<string, unknown>) => HTMLElement;
     renderPanel: (id: string, props?: Record<string, unknown>) => HTMLElement;
     renderDashboardCard: (id: string) => HTMLElement;
+    /**
+     * Renders an onboarding step with OnboardingStepProps for a first run,
+     * overridable. Read what the step set with the returned `canContinue()`
+     * and `next()` (runs its beforeNext, true when it has none).
+     */
+    renderOnboardingStep: (id: string, props?: Record<string, unknown>) => {
+        element: HTMLElement;
+        canContinue: () => boolean;
+        next: () => Promise<boolean>;
+    };
     /** Renders one component of a contributed extension, "view" by default. */
     renderExtension: (pointId: string, id: string, component?: string, props?: Record<string, unknown>) => HTMLElement;
     renderHostEditorSection: (id: string, props?: Record<string, unknown>) => HTMLElement;

package/dist/vitest-preset.d.ts

@@ -19,6 +19,7 @@ export declare function pluginVitestConfig(configUrl: string, options?: PluginVi
     test: {
         globals: boolean;
         setupFiles: string[];
+        pool: "threads";
         projects: ({
             resolve: {
                 alias: Record<string, string>;
@@ -27,6 +28,7 @@ export declare function pluginVitestConfig(configUrl: string, options?: PluginVi
                 name: string;
                 root: string;
                 environment: string;
+                pool: "threads";
                 globals: boolean;
                 setupFiles: string[];
                 include: string[];
@@ -40,6 +42,7 @@ export declare function pluginVitestConfig(configUrl: string, options?: PluginVi
                 name: string;
                 root: string;
                 environment: string;
+                pool: "threads";
                 globals: boolean;
                 setupFiles: string[];
                 server: {

package/dist/vitest-preset.js

@@ -58,11 +58,15 @@ export function pluginVitestConfig(configUrl, options = {}) {
             }),
         ...options.alias,
     };
+    // Forks workers on Windows abort now and then with "Worker exited
+    // unexpectedly". Threads don't.
+    const pool = "threads";
     return {
         resolve: { alias },
         test: {
             globals: true,
             setupFiles: [setupFile],
+            pool,
             projects: [
                 {
                     resolve: { alias },
@@ -70,6 +74,7 @@ export function pluginVitestConfig(configUrl, options = {}) {
                         name: `${pluginId}:backend`,
                         root: pluginDir,
                         environment: "node",
+                        pool,
                         globals: true,
                         setupFiles: [setupFile],
                         include: ["tests/backend/**/*.test.ts"],
@@ -81,6 +86,7 @@ export function pluginVitestConfig(configUrl, options = {}) {
                         name: `${pluginId}:frontend`,
                         root: pluginDir,
                         environment: "jsdom",
+                        pool,
                         globals: true,
                         setupFiles: [setupFile],
                         // Run the SDK through Vite rather than plain Node, so its import

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@termix-ssh/plugin-sdk",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "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": {
@@ -49,6 +49,10 @@
       "types": "./dist/capabilities.d.ts",
       "default": "./dist/capabilities.js"
     },
+    "./changelog": {
+      "types": "./dist/changelog.d.ts",
+      "default": "./dist/changelog.js"
+    },
     "./settings": {
       "types": "./dist/settings.d.ts",
       "default": "./dist/settings.js"
@@ -75,7 +79,6 @@
     },
     "./tsconfig.plugin.json": "./tsconfig.plugin.json",
     "./schema/manifest.schema.json": "./schema/manifest.schema.json",
-    "./schema/changelog.schema.json": "./schema/changelog.schema.json",
     "./ui": {
       "types": "./dist/host/ui.d.ts",
       "default": "./dist/host/ui.js"
@@ -91,6 +94,7 @@
     "schema",
     "tsconfig.plugin.json",
     "README.md",
+    "CHANGELOG.md",
     "client.d.ts"
   ],
   "scripts": {

package/schema/manifest.schema.json

@@ -72,7 +72,18 @@
     "icon": {
       "type": "string",
       "minLength": 1,
-      "description": "A Lucide icon name, or a relative path to an icon.svg in the plugin root."
+      "description": "A Lucide icon name, like \"Play\"."
+    },
+    "video": {
+      "type": "string",
+      "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."
     },
     "engine": {
       "type": "object",

package/cli/lib/changelog.mjs

@@ -1,126 +0,0 @@
-export const CHANGE_TYPES = [
-  "added",
-  "changed",
-  "fixed",
-  "removed",
-  "deprecated",
-  "security",
-];
-
-const SEMVER = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/;
-const DATE = /^\d{4}-\d{2}-\d{2}$/;
-const TOP_KEYS = ["$schema", "unreleased", "releases"];
-const RELEASE_KEYS = ["version", "date", "notes", "changes"];
-const CHANGE_KEYS = ["type", "text"];
-
-function compareVersions(a, b) {
-  const pa = SEMVER.exec(a);
-  const pb = SEMVER.exec(b);
-  for (let i = 1; i <= 3; i++) {
-    const diff = Number(pa[i]) - Number(pb[i]);
-    if (diff !== 0) return diff;
-  }
-  if (pa[4] === pb[4]) return 0;
-  if (!pa[4]) return 1;
-  if (!pb[4]) return -1;
-  return pa[4] < pb[4] ? -1 : 1;
-}
-
-function unknownKeys(value, allowed, where, problems) {
-  for (const key of Object.keys(value)) {
-    if (!allowed.includes(key))
-      problems.push(`${where} has unknown key "${key}"`);
-  }
-}
-
-function checkChanges(changes, where, problems) {
-  if (!Array.isArray(changes)) {
-    problems.push(`${where} must be an array`);
-    return;
-  }
-  changes.forEach((change, i) => {
-    const at = `${where}[${i}]`;
-    if (!change || typeof change !== "object" || Array.isArray(change)) {
-      problems.push(`${at} must be an object`);
-      return;
-    }
-    unknownKeys(change, CHANGE_KEYS, at, problems);
-    if (!CHANGE_TYPES.includes(change.type)) {
-      problems.push(`${at}.type must be one of ${CHANGE_TYPES.join(", ")}`);
-    }
-    if (typeof change.text !== "string" || change.text.trim() === "") {
-      problems.push(`${at}.text must be a non-empty string`);
-    }
-  });
-}
-
-/**
- * Checks a parsed CHANGELOG.json. The newest release has to be the version
- * in the manifest, so a release never ships without its notes.
- */
-export function validateChangelog(changelog, manifestVersion) {
-  const problems = [];
-  if (!changelog || typeof changelog !== "object" || Array.isArray(changelog)) {
-    return ["CHANGELOG.json must be an object"];
-  }
-  unknownKeys(changelog, TOP_KEYS, "CHANGELOG.json", problems);
-
-  if (changelog.unreleased !== undefined) {
-    checkChanges(changelog.unreleased, "unreleased", problems);
-  }
-
-  const releases = changelog.releases;
-  if (!Array.isArray(releases) || releases.length === 0) {
-    problems.push("releases must be a non-empty array");
-    return problems;
-  }
-
-  const seen = new Set();
-  releases.forEach((release, i) => {
-    const at = `releases[${i}]`;
-    if (!release || typeof release !== "object" || Array.isArray(release)) {
-      problems.push(`${at} must be an object`);
-      return;
-    }
-    unknownKeys(release, RELEASE_KEYS, at, problems);
-    if (typeof release.version !== "string" || !SEMVER.test(release.version)) {
-      problems.push(`${at}.version must be a version like 1.2.3`);
-    } else if (seen.has(release.version)) {
-      problems.push(`${at}.version ${release.version} is listed twice`);
-    } else {
-      seen.add(release.version);
-    }
-    if (
-      release.date !== undefined &&
-      (typeof release.date !== "string" || !DATE.test(release.date))
-    ) {
-      problems.push(`${at}.date must be a date like 2026-10-01`);
-    }
-    if (release.notes !== undefined && typeof release.notes !== "string") {
-      problems.push(`${at}.notes must be a string`);
-    }
-    checkChanges(release.changes, `${at}.changes`, problems);
-    if (Array.isArray(release.changes) && release.changes.length === 0) {
-      problems.push(`${at}.changes must list at least one change`);
-    }
-  });
-
-  const versions = releases
-    .map((release) => release?.version)
-    .filter((v) => typeof v === "string" && SEMVER.test(v));
-  for (let i = 1; i < versions.length; i++) {
-    if (compareVersions(versions[i - 1], versions[i]) < 0) {
-      problems.push("releases must be listed newest first");
-      break;
-    }
-  }
-
-  const newest = releases[0]?.version;
-  if (manifestVersion && newest !== manifestVersion) {
-    problems.push(
-      `the newest release is ${newest}, but manifest version is ${manifestVersion}`,
-    );
-  }
-
-  return problems;
-}

package/schema/changelog.schema.json

@@ -1,67 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://raw.githubusercontent.com/Termix-SSH/Termix/main/packages/plugin-sdk/schema/changelog.schema.json",
-  "title": "Termix plugin changelog",
-  "description": "Every release of a plugin, newest first. The newest release must match the manifest version.",
-  "type": "object",
-  "additionalProperties": false,
-  "required": ["releases"],
-  "properties": {
-    "$schema": { "type": "string" },
-    "unreleased": {
-      "description": "Changes that are merged but not released yet.",
-      "type": "array",
-      "items": { "$ref": "#/$defs/change" }
-    },
-    "releases": {
-      "type": "array",
-      "minItems": 1,
-      "items": { "$ref": "#/$defs/release" }
-    }
-  },
-  "$defs": {
-    "release": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["version", "changes"],
-      "properties": {
-        "version": {
-          "type": "string",
-          "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?$"
-        },
-        "date": {
-          "description": "When the version was released. Leave it out until it ships.",
-          "type": "string",
-          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
-        },
-        "notes": {
-          "description": "A short line shown above the list of changes.",
-          "type": "string"
-        },
-        "changes": {
-          "type": "array",
-          "minItems": 1,
-          "items": { "$ref": "#/$defs/change" }
-        }
-      }
-    },
-    "change": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["type", "text"],
-      "properties": {
-        "type": {
-          "enum": [
-            "added",
-            "changed",
-            "fixed",
-            "removed",
-            "deprecated",
-            "security"
-          ]
-        },
-        "text": { "type": "string", "minLength": 1 }
-      }
-    }
-  }
-}