@termix-ssh/plugin-sdk 1.0.0

package/dist/vitest-preset.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The vitest config every plugin uses.
+ *
+ * A plugin's vitest.config.ts is one line:
+ *
+ *   import { pluginVitestConfig } from "@termix-ssh/plugin-sdk/vitest-preset";
+ *   export default pluginVitestConfig(import.meta.url);
+ *
+ * Two projects: tests/backend runs in node, tests/frontend in jsdom.
+ */
+export interface PluginVitestOptions {
+    /** Extra aliases merged over the defaults. */
+    alias?: Record<string, string>;
+}
+export declare function pluginVitestConfig(configUrl: string, options?: PluginVitestOptions): {
+    resolve: {
+        alias: Record<string, string>;
+    };
+    test: {
+        globals: boolean;
+        setupFiles: string[];
+        projects: ({
+            resolve: {
+                alias: Record<string, string>;
+            };
+            test: {
+                name: string;
+                root: string;
+                environment: string;
+                globals: boolean;
+                setupFiles: string[];
+                include: string[];
+                server?: undefined;
+            };
+        } | {
+            resolve: {
+                alias: Record<string, string>;
+            };
+            test: {
+                name: string;
+                root: string;
+                environment: string;
+                globals: boolean;
+                setupFiles: string[];
+                server: {
+                    deps: {
+                        inline: RegExp[];
+                    };
+                };
+                include: string[];
+            };
+        })[];
+    };
+};

package/dist/vitest-preset.js

@@ -0,0 +1,96 @@
+/**
+ * The vitest config every plugin uses.
+ *
+ * A plugin's vitest.config.ts is one line:
+ *
+ *   import { pluginVitestConfig } from "@termix-ssh/plugin-sdk/vitest-preset";
+ *   export default pluginVitestConfig(import.meta.url);
+ *
+ * Two projects: tests/backend runs in node, tests/frontend in jsdom.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Walks up from a plugin directory to a Termix checkout, if it is in one.
+ *
+ * Inside the repo the SDK's browser entries and the test host resolve to
+ * core's source, so a test exercises the real registries. Outside it they
+ * resolve to the builds the SDK ships in dist/host.
+ */
+function findRepoRoot(startDir) {
+    let dir = startDir;
+    for (;;) {
+        if (fs.existsSync(path.join(dir, "src", "ui")))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+export function pluginVitestConfig(configUrl, options = {}) {
+    const pluginDir = path.dirname(fileURLToPath(configUrl));
+    const manifestPath = path.join(pluginDir, "manifest.json");
+    const pluginId = (fs.existsSync(manifestPath) &&
+        JSON.parse(fs.readFileSync(manifestPath, "utf8")).id) ||
+        path.basename(pluginDir);
+    const setupFile = fileURLToPath(new URL("./testing/setup.js", import.meta.url));
+    const repoRoot = findRepoRoot(pluginDir);
+    // Inside a Termix checkout the SDK's browser entries resolve to source and
+    // the test host is core's, so renderWithApp exercises the real registries
+    // and the plugin shares one SDK instance with them.
+    const alias = {
+        ...(repoRoot
+            ? {
+                "@termix-ssh/plugin-sdk/frontend": path.join(repoRoot, "packages", "plugin-sdk", "src", "frontend.ts"),
+                "@termix-ssh/plugin-sdk/ui": path.join(repoRoot, "src", "ui", "plugin-host", "sdk-ui.ts"),
+                "@termix-ssh/plugin-host/testing": path.join(repoRoot, "src", "ui", "plugin-host", "testing-host.tsx"),
+                // Core's own modules behind sdk-ui and the test host import each
+                // other this way. Plugin code may not (eslint refuses it).
+                "@/types": path.join(repoRoot, "src", "types"),
+                "@": path.join(repoRoot, "src", "ui"),
+            }
+            : {
+                // Outside a Termix checkout: the UI kit resolves through the
+                // package, and the test host is the copy the SDK ships.
+                "@termix-ssh/plugin-host/testing": fileURLToPath(new URL("./host/testing-host.js", import.meta.url)),
+            }),
+        ...options.alias,
+    };
+    return {
+        resolve: { alias },
+        test: {
+            globals: true,
+            setupFiles: [setupFile],
+            projects: [
+                {
+                    resolve: { alias },
+                    test: {
+                        name: `${pluginId}:backend`,
+                        root: pluginDir,
+                        environment: "node",
+                        globals: true,
+                        setupFiles: [setupFile],
+                        include: ["tests/backend/**/*.test.ts"],
+                    },
+                },
+                {
+                    resolve: { alias },
+                    test: {
+                        name: `${pluginId}:frontend`,
+                        root: pluginDir,
+                        environment: "jsdom",
+                        globals: true,
+                        setupFiles: [setupFile],
+                        // Run the SDK through Vite rather than plain Node, so its import
+                        // of the test host sees the alias above and the plugin and the
+                        // host share one copy of @termix-ssh/plugin-sdk/frontend.
+                        server: { deps: { inline: [/@termix-ssh\/plugin-sdk/] } },
+                        include: ["tests/frontend/**/*.test.{ts,tsx}"],
+                    },
+                },
+            ],
+        },
+    };
+}

package/package.json

@@ -0,0 +1,143 @@
+{
+  "name": "@termix-ssh/plugin-sdk",
+  "version": "1.0.0",
+  "description": "The contract between Termix core and a plugin: types, the capability catalog and the manifest schema.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Termix-SSH/Termix.git",
+    "directory": "packages/plugin-sdk"
+  },
+  "homepage": "https://github.com/Termix-SSH/Termix/tree/main/packages/plugin-sdk#readme",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "termix-plugin": "./cli/index.mjs"
+  },
+  "exports": {
+    "./backend": {
+      "types": "./dist/backend.d.ts",
+      "default": "./dist/backend.js"
+    },
+    "./db": {
+      "types": "./dist/db.d.ts",
+      "default": "./dist/db.js"
+    },
+    "./ddl": {
+      "types": "./dist/ddl.d.ts",
+      "default": "./dist/ddl.js"
+    },
+    "./table-builder": {
+      "types": "./dist/table-builder.d.ts",
+      "default": "./dist/table-builder.js"
+    },
+    "./frontend": {
+      "types": "./dist/frontend.d.ts",
+      "default": "./dist/frontend.js"
+    },
+    "./desktop": {
+      "types": "./dist/desktop.d.ts",
+      "default": "./dist/desktop.js"
+    },
+    "./manifest": {
+      "types": "./dist/manifest.d.ts",
+      "default": "./dist/manifest.js"
+    },
+    "./capabilities": {
+      "types": "./dist/capabilities.d.ts",
+      "default": "./dist/capabilities.js"
+    },
+    "./settings": {
+      "types": "./dist/settings.d.ts",
+      "default": "./dist/settings.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
+    },
+    "./testing/setup": {
+      "types": "./dist/testing/setup.d.ts",
+      "default": "./dist/testing/setup.js"
+    },
+    "./vitest-preset": {
+      "types": "./dist/vitest-preset.d.ts",
+      "default": "./dist/vitest-preset.js"
+    },
+    "./host-commands": {
+      "types": "./dist/host-commands.d.ts",
+      "default": "./dist/host-commands.js"
+    },
+    "./ssh-certs": {
+      "types": "./dist/ssh-certs.d.ts",
+      "default": "./dist/ssh-certs.js"
+    },
+    "./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"
+    },
+    "./testing-host": {
+      "default": "./dist/host/testing-host.js"
+    },
+    "./theme.css": "./dist/host/theme.css"
+  },
+  "files": [
+    "dist",
+    "cli",
+    "schema",
+    "tsconfig.plugin.json",
+    "README.md",
+    "client.d.ts"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@tailwindcss/node": "^4.2.4",
+    "@tailwindcss/oxide": "^4.2.4",
+    "esbuild": "^0.28.1",
+    "semver": "^7.6.3",
+    "tailwindcss": "^4.2.4",
+    "tar": "^7.5.22"
+  },
+  "peerDependencies": {
+    "@testing-library/react": "^16.3.3",
+    "better-sqlite3": "*",
+    "drizzle-orm": "*",
+    "i18next": "^26.4.2",
+    "react": "*",
+    "react-dom": "^19.2.8",
+    "react-i18next": "^17.0.14",
+    "sonner": "^2.0.8",
+    "ssh2": "*",
+    "vitest": "*"
+  },
+  "peerDependenciesMeta": {
+    "drizzle-orm": {
+      "optional": true
+    },
+    "ssh2": {
+      "optional": true
+    },
+    "better-sqlite3": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "vitest": {
+      "optional": true
+    },
+    "@testing-library/react": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/schema/changelog.schema.json

@@ -0,0 +1,67 @@
+{
+  "$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 }
+      }
+    }
+  }
+}