@termix-ssh/plugin-sdk 1.0.11 → 1.0.12

package/dist/host/{use-permissions-GYCBY2AU.js → use-permissions-6VSHHUMB.js}

@@ -7,8 +7,8 @@ import {
   resetPermissionsCache,
   setPermissionsForTesting,
   usePermissions
-} from "./chunk-LSWB3ZZV.js";
-import "./chunk-YC2MAKSP.js";
+} from "./chunk-VEWOYAMZ.js";
+import "./chunk-YGYBM7SQ.js";
 export {
   hasPermission,
   loadPermissionChecker,

package/dist/manifest.d.ts

@@ -10,6 +10,7 @@
  * made a manifest look like it declared something it did not.
  */
 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";
 /**
  * The plugin API this build implements. A minor bump adds to the API and
@@ -19,7 +20,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.3.0";
+export declare const PLUGIN_API_VERSION = "1.4.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. */
@@ -265,6 +266,41 @@ export interface PluginAuthContribution {
     /** Keyboard-interactive handler ids, e.g. "warpgate". */
     keyboardInteractive?: string[];
 }
+/** A layout id or theme id: short, lowercase, used as a CSS class for themes. */
+export declare const LOOK_ID_PATTERN: RegExp;
+/**
+ * A whole-app layout the frontend registers with app.registerLayout. Needs
+ * the ui:layout capability. Declared here so core can list and choose it
+ * before any plugin code runs.
+ */
+export interface PluginLayoutContribution {
+    id: string;
+    /** i18n key in the plugin's namespace, or plain text. */
+    label: string;
+    description?: string;
+    /** Theme picked with this layout when nobody chose one. */
+    defaultTheme?: string;
+    /** The layout a default-look plugin starts with. */
+    default?: boolean;
+}
+/**
+ * A theme: one CSS file of token rules scoped under `.<id>`, applied as a
+ * class on <html>. Needs the ui:theme capability. No code runs for a theme.
+ */
+export interface PluginThemeContribution {
+    id: string;
+    /** i18n key in the plugin's namespace, or plain text. */
+    label: string;
+    mode: "light" | "dark";
+    /** Path of the CSS file inside the plugin. */
+    css: string;
+    /** Colors the theme picker previews it with. */
+    swatch?: {
+        background: string;
+        panel: string;
+        text: string;
+    };
+}
 export interface PluginContributions {
     tabs?: PluginTabContribution[];
     panels?: PluginViewContribution[];
@@ -323,6 +359,10 @@ export interface PluginContributions {
      * ctx.credentials.resolveHostProtocol.
      */
     protocols?: PluginProtocolContribution[];
+    /** Whole-app layouts. Needs the ui:layout capability. */
+    layouts?: PluginLayoutContribution[];
+    /** Themes. Needs the ui:theme capability. */
+    themes?: PluginThemeContribution[];
 }
 /** A field a protocol login carries besides username and password. */
 export interface PluginProtocolCredentialField {

package/dist/manifest.js

@@ -12,6 +12,7 @@
 import semver from "semver";
 import { isKnownCapability } from "./capabilities.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";
 /**
  * The plugin API this build implements. A minor bump adds to the API and
@@ -21,7 +22,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.3.0";
+export const PLUGIN_API_VERSION = "1.4.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. */
@@ -168,6 +169,8 @@ export const SETTINGS_FIELD_TYPES = [
     "custom",
 ];
 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}$/;
 /** Protocol ids core keeps for itself. */
 export const RESERVED_PROTOCOL_IDS = ["ssh"];
 /** Login keys a declared credential field may not reuse. */
@@ -243,6 +246,8 @@ const ALLOWED_CONTRIBUTES = new Set([
     "uses",
     "keybindingActions",
     "protocols",
+    "layouts",
+    "themes",
 ]);
 const ALLOWED_SETTINGS_FIELD = [
     "key",
@@ -734,6 +739,81 @@ function validateContributes(contributes, pluginId, errors) {
     validateUiPresets(contributes.uiPresets, errors);
     validateKeybindingActions(contributes.keybindingActions, errors);
     validateProtocols(contributes.protocols, errors);
+    validateLayouts(contributes.layouts, errors);
+    validateThemes(contributes.themes, errors);
+}
+/** An array of objects with unique look ids; calls `each` for every valid entry. */
+function validateLookList(value, field, allowed, errors, each) {
+    if (value === undefined)
+        return;
+    if (!Array.isArray(value)) {
+        errors.push(`Field "contributes.${field}" must be an array`);
+        return;
+    }
+    const seen = new Set();
+    value.forEach((raw, index) => {
+        const where = `contributes.${field}[${index}]`;
+        if (!isPlainObject(raw)) {
+            errors.push(`${where} must be an object`);
+            return;
+        }
+        rejectUnknown(raw, allowed, where, errors);
+        if (typeof raw.id !== "string" || !LOOK_ID_PATTERN.test(raw.id)) {
+            errors.push(`${where}.id must match ${LOOK_ID_PATTERN} (lowercase letters, digits, dashes)`);
+        }
+        else {
+            if (seen.has(raw.id))
+                errors.push(`${where}.id duplicates "${raw.id}"`);
+            seen.add(raw.id);
+        }
+        requireString(raw.label, `${where}.label`, errors);
+        each(raw, where);
+    });
+}
+function validateLayouts(value, errors) {
+    validateLookList(value, "layouts", ["id", "label", "description", "defaultTheme", "default"], errors, (raw, where) => {
+        if (raw.description !== undefined)
+            requireString(raw.description, `${where}.description`, errors);
+        if (raw.defaultTheme !== undefined &&
+            (typeof raw.defaultTheme !== "string" ||
+                !LOOK_ID_PATTERN.test(raw.defaultTheme))) {
+            errors.push(`${where}.defaultTheme must be a theme id`);
+        }
+        if (raw.default !== undefined && typeof raw.default !== "boolean") {
+            errors.push(`${where}.default must be a boolean`);
+        }
+    });
+    if (Array.isArray(value) &&
+        value.filter((raw) => isPlainObject(raw) && raw.default === true).length > 1) {
+        errors.push('Only one entry in "contributes.layouts" may set default');
+    }
+}
+const HEX_COLOR = /^#[0-9a-fA-F]{3,8}$/;
+function validateThemes(value, errors) {
+    validateLookList(value, "themes", ["id", "label", "mode", "css", "swatch"], errors, (raw, where) => {
+        if (raw.mode !== "light" && raw.mode !== "dark") {
+            errors.push(`${where}.mode must be "light" or "dark"`);
+        }
+        if (requireString(raw.css, `${where}.css`, errors)) {
+            requireRelativePath(raw.css, `${where}.css`, errors);
+            if (!raw.css.endsWith(".css")) {
+                errors.push(`${where}.css must be a .css file`);
+            }
+        }
+        if (raw.swatch !== undefined) {
+            if (!isPlainObject(raw.swatch)) {
+                errors.push(`${where}.swatch must be an object`);
+                return;
+            }
+            rejectUnknown(raw.swatch, ["background", "panel", "text"], `${where}.swatch`, errors);
+            for (const key of ["background", "panel", "text"]) {
+                const color = raw.swatch[key];
+                if (typeof color !== "string" || !HEX_COLOR.test(color)) {
+                    errors.push(`${where}.swatch.${key} must be a hex color`);
+                }
+            }
+        }
+    });
 }
 export const PROTOCOL_ID_PATTERN = /^[a-z][a-z0-9-]{0,31}$/;
 export const PROTOCOL_FIELD_KEY_PATTERN = /^[a-zA-Z][a-zA-Z0-9]{0,31}$/;
@@ -1595,6 +1675,14 @@ export function parseManifest(raw) {
     if (contributesAuth && !manifest.capabilities.includes("auth:provide")) {
         errors.push('contributes.auth needs the "auth:provide" capability in the capabilities array');
     }
+    if ((manifest.contributes?.layouts?.length ?? 0) > 0 &&
+        !manifest.capabilities.includes("ui:layout")) {
+        errors.push('contributes.layouts needs the "ui:layout" capability in the capabilities array');
+    }
+    if ((manifest.contributes?.themes?.length ?? 0) > 0 &&
+        !manifest.capabilities.includes("ui:theme")) {
+        errors.push('contributes.themes needs the "ui:theme" capability in the capabilities array');
+    }
     for (const secret of manifest.requiresSecret ?? []) {
         if (secret.plugin === manifest.id) {
             errors.push(`requiresSecret["${secret.key}"] points at this plugin; use ctx.secrets.get instead`);

package/dist/testing/setup.js

@@ -89,6 +89,7 @@ globalThis.__termixTestPluginHost = {
     useHostStatus: () => null,
     useCurrentUser: () => null,
     useTheme: () => ({ theme: "dark" }),
+    useShell: () => null,
     toast: { success: noop, error: noop, info: noop, warning: noop },
     getApi: () => ({
         get: offline,

package/dist/theme-css.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Checks a theme's CSS before core serves it.
+ *
+ * A theme is colors and styles only, so its file may hold nothing but rules
+ * whose every selector starts with the theme's own class (`.nord`,
+ * `:root.nord`, `html.nord ...`), optionally inside @media or @supports.
+ * Anything that could load from elsewhere or run code is refused: @import,
+ * url() to another host, other at-rules, expression() and javascript:.
+ */
+/** Every problem with a theme's CSS, empty when it is safe to serve. */
+export declare function validateThemeCss(css: string, themeId: string): string[];

package/dist/theme-css.js

@@ -0,0 +1,142 @@
+/**
+ * Checks a theme's CSS before core serves it.
+ *
+ * A theme is colors and styles only, so its file may hold nothing but rules
+ * whose every selector starts with the theme's own class (`.nord`,
+ * `:root.nord`, `html.nord ...`), optionally inside @media or @supports.
+ * Anything that could load from elsewhere or run code is refused: @import,
+ * url() to another host, other at-rules, expression() and javascript:.
+ */
+const ALLOWED_BLOCK_AT_RULES = new Set(["media", "supports"]);
+function stripComments(css) {
+    return css.replace(/\/\*[\s\S]*?\*\//g, " ");
+}
+/** Splits on commas that are not inside parentheses or brackets. */
+function splitSelectors(prelude) {
+    const parts = [];
+    let depth = 0;
+    let current = "";
+    for (const ch of prelude) {
+        if (ch === "(" || ch === "[")
+            depth += 1;
+        if (ch === ")" || ch === "]")
+            depth -= 1;
+        if (ch === "," && depth === 0) {
+            parts.push(current);
+            current = "";
+            continue;
+        }
+        current += ch;
+    }
+    parts.push(current);
+    return parts.map((part) => part.trim());
+}
+function withoutStrings(css) {
+    return css.replace(/"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'/g, '""');
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** Index of the brace closing the one at `open`, skipping strings. */
+function matchingBrace(css, open) {
+    let depth = 0;
+    let quote = null;
+    for (let i = open; i < css.length; i += 1) {
+        const ch = css[i];
+        if (quote) {
+            if (ch === "\\")
+                i += 1;
+            else if (ch === quote)
+                quote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'")
+            quote = ch;
+        else if (ch === "{")
+            depth += 1;
+        else if (ch === "}") {
+            depth -= 1;
+            if (depth === 0)
+                return i;
+        }
+    }
+    return -1;
+}
+function checkUrls(css, errors) {
+    const urls = css.matchAll(/url\(\s*(['"]?)([^'")]*)\1\s*\)/gi);
+    for (const match of urls) {
+        const target = match[2].trim();
+        if (target.startsWith("data:"))
+            continue;
+        if (/^[a-z][a-z0-9+.-]*:/i.test(target) || target.startsWith("//")) {
+            errors.push(`url(${target}) points outside the plugin`);
+        }
+    }
+}
+function checkRules(css, scope, themeId, errors) {
+    let index = 0;
+    while (index < css.length) {
+        const rest = css.slice(index);
+        if (rest.trim() === "")
+            return;
+        const open = css.indexOf("{", index);
+        const semicolon = css.indexOf(";", index);
+        if (semicolon !== -1 && (open === -1 || semicolon < open)) {
+            const statement = css.slice(index, semicolon).trim();
+            errors.push(statement.startsWith("@")
+                ? `${statement.split(/\s/)[0]} is not allowed in a theme`
+                : `Unexpected "${statement}" outside a rule`);
+            index = semicolon + 1;
+            continue;
+        }
+        if (open === -1) {
+            errors.push(`Unexpected "${rest.trim()}" at the end`);
+            return;
+        }
+        const close = matchingBrace(css, open);
+        if (close === -1) {
+            errors.push("A rule is missing its closing brace");
+            return;
+        }
+        const prelude = css.slice(index, open).trim();
+        const body = css.slice(open + 1, close);
+        if (prelude.startsWith("@")) {
+            const name = prelude.slice(1).split(/[\s(]/)[0].toLowerCase();
+            if (ALLOWED_BLOCK_AT_RULES.has(name)) {
+                checkRules(body, scope, themeId, errors);
+            }
+            else {
+                errors.push(`@${name} is not allowed in a theme`);
+            }
+        }
+        else {
+            for (const selector of splitSelectors(prelude)) {
+                if (!scope.test(selector)) {
+                    errors.push(`Selector "${selector}" must start with .${themeId}, :root.${themeId} or html.${themeId}`);
+                }
+            }
+            if (withoutStrings(body).includes("{")) {
+                errors.push(`Nested rules are not allowed in "${prelude}"`);
+            }
+        }
+        index = close + 1;
+    }
+}
+/** Every problem with a theme's CSS, empty when it is safe to serve. */
+export function validateThemeCss(css, themeId) {
+    const errors = [];
+    const clean = stripComments(css);
+    if (/@import\b/i.test(clean))
+        errors.push("@import is not allowed in a theme");
+    if (/expression\s*\(/i.test(clean))
+        errors.push("expression() is not allowed in a theme");
+    if (/javascript:/i.test(clean))
+        errors.push("javascript: is not allowed in a theme");
+    if (/-moz-binding|behavior\s*:/i.test(clean))
+        errors.push("Script bindings are not allowed in a theme");
+    checkUrls(clean, errors);
+    const id = escapeRegExp(themeId);
+    const scope = new RegExp(`^(?::root|html)?\\.${id}(?![\\w-])`);
+    checkRules(clean, scope, themeId, errors);
+    return [...new Set(errors)];
+}

package/dist/vitest-preset.d.ts

@@ -27,8 +27,14 @@ export declare function pluginVitestConfig(configUrl: string, options?: PluginVi
         enforce: "pre";
         load(id: string): string;
     }[];
+    server: {
+        fs: {
+            allow: string[];
+        };
+    };
     resolve: {
         alias: Record<string, string>;
+        dedupe: string[];
     };
     test: {
         globals: boolean;
@@ -40,8 +46,14 @@ export declare function pluginVitestConfig(configUrl: string, options?: PluginVi
                 enforce: "pre";
                 load(id: string): string;
             }[];
+            server: {
+                fs: {
+                    allow: string[];
+                };
+            };
             resolve: {
                 alias: Record<string, string>;
+                dedupe: string[];
             };
             test: {
                 name: string;
@@ -59,8 +71,14 @@ export declare function pluginVitestConfig(configUrl: string, options?: PluginVi
                 enforce: "pre";
                 load(id: string): string;
             }[];
+            server: {
+                fs: {
+                    allow: string[];
+                };
+            };
             resolve: {
                 alias: Record<string, string>;
+                dedupe: string[];
             };
             test: {
                 name: string;

package/dist/vitest-preset.js

@@ -80,9 +80,18 @@ export function pluginVitestConfig(configUrl, options = {}) {
     // unexpectedly". Threads don't.
     const pool = "threads";
     const plugins = [wasmBinaryPlugin()];
+    // A local SDK linked into node_modules sits outside the plugin folder, so
+    // Vite must be allowed to read it, and React must come from the plugin.
+    const sdkDir = fs.realpathSync(fileURLToPath(new URL("..", import.meta.url)));
+    const server = { fs: { allow: [pluginDir, sdkDir] } };
+    const resolve = {
+        alias,
+        dedupe: ["react", "react-dom", "react-i18next", "i18next"],
+    };
     return {
         plugins,
-        resolve: { alias },
+        server,
+        resolve,
         test: {
             globals: true,
             setupFiles: [setupFile],
@@ -90,7 +99,8 @@ export function pluginVitestConfig(configUrl, options = {}) {
             projects: [
                 {
                     plugins,
-                    resolve: { alias },
+                    server,
+                    resolve,
                     test: {
                         name: `${pluginId}:backend`,
                         root: pluginDir,
@@ -103,7 +113,8 @@ export function pluginVitestConfig(configUrl, options = {}) {
                 },
                 {
                     plugins,
-                    resolve: { alias },
+                    server,
+                    resolve,
                     test: {
                         name: `${pluginId}:frontend`,
                         root: pluginDir,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@termix-ssh/plugin-sdk",
-  "version": "1.0.11",
+  "version": "1.0.12",
   "description": "The contract between Termix core and a plugin: types, the capability catalog and the manifest schema.",
   "license": "Apache-2.0",
   "repository": {

package/schema/manifest.schema.json

@@ -82,7 +82,11 @@
     "features": {
       "type": "array",
       "maxItems": 20,
-      "items": { "type": "string", "minLength": 1, "maxLength": 160 },
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 160
+      },
       "description": "Short lines listing what the plugin does, shown on its page."
     },
     "docs": {
@@ -98,11 +102,24 @@
         "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" }
+          "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"
+          }
         }
       }
     },
@@ -155,7 +172,11 @@
           "files:own",
           "secrets:own",
           "settings:read-core",
-          "ui:surface"
+          "ui:surface",
+          "notify:hub",
+          "plugins:read",
+          "ui:layout",
+          "ui:theme"
         ]
       }
     },
@@ -944,7 +965,9 @@
                       "defaultLevels": {
                         "type": "array",
                         "minItems": 1,
-                        "items": { "enum": ["admin", "user", "folder"] },
+                        "items": {
+                          "enum": ["admin", "user", "folder"]
+                        },
                         "description": "Levels that may set a default for the field. All three by default."
                       },
                       "personal": {
@@ -1127,6 +1150,86 @@
             "type": "string",
             "pattern": "^[A-Za-z0-9-]+(\\.[A-Za-z0-9-]+)+$"
           }
+        },
+        "layouts": {
+          "type": "array",
+          "description": "Whole-app layouts the frontend registers with app.registerLayout. Needs the ui:layout capability.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "label"],
+            "properties": {
+              "id": {
+                "type": "string",
+                "pattern": "^[a-z][a-z0-9-]{1,39}$"
+              },
+              "label": {
+                "type": "string",
+                "minLength": 1,
+                "description": "i18n key in the plugin namespace, or plain text."
+              },
+              "description": {
+                "type": "string",
+                "minLength": 1
+              },
+              "defaultTheme": {
+                "type": "string",
+                "pattern": "^[a-z][a-z0-9-]{1,39}$",
+                "description": "Theme picked with this layout when nobody chose one."
+              },
+              "default": {
+                "type": "boolean",
+                "description": "The layout a default-look plugin starts with. At most one."
+              }
+            }
+          }
+        },
+        "themes": {
+          "type": "array",
+          "description": "Themes: one CSS file each with token rules scoped under .<id>. Needs the ui:theme capability.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "label", "mode", "css"],
+            "properties": {
+              "id": {
+                "type": "string",
+                "pattern": "^[a-z][a-z0-9-]{1,39}$"
+              },
+              "label": {
+                "type": "string",
+                "minLength": 1
+              },
+              "mode": {
+                "type": "string",
+                "enum": ["light", "dark"]
+              },
+              "css": {
+                "type": "string",
+                "pattern": ".css$",
+                "description": "Path of the CSS file inside the plugin."
+              },
+              "swatch": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["background", "panel", "text"],
+                "properties": {
+                  "background": {
+                    "type": "string",
+                    "pattern": "^#[0-9a-fA-F]{3,8}$"
+                  },
+                  "panel": {
+                    "type": "string",
+                    "pattern": "^#[0-9a-fA-F]{3,8}$"
+                  },
+                  "text": {
+                    "type": "string",
+                    "pattern": "^#[0-9a-fA-F]{3,8}$"
+                  }
+                }
+              }
+            }
+          }
         }
       }
     },

package/tsconfig.plugin.json

@@ -12,6 +12,7 @@
     "moduleDetection": "force",
     "esModuleInterop": true,
     "resolveJsonModule": true,
+    "preserveSymlinks": true,
     "noEmit": true,
     "strict": false,
     "noUnusedLocals": false,

package/dist/host/chunk-YC2MAKSP.js

@@ -1,14 +0,0 @@
-const __termixNoGlob = () => ({});
-var __defProp = Object.defineProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-
-// <define:import.meta.env>
-var define_import_meta_env_default = { DEV: false, PROD: true, MODE: "production", SSR: false, BASE_URL: "/" };
-
-export {
-  __export,
-  define_import_meta_env_default
-};