@termix-ssh/plugin-sdk 1.0.8 → 1.0.10

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 1.0.10
+
+### Changed
+
+- `termix-plugin pack` includes the plugin's `LICENSE` and `NOTICE` files, so third-party notices ship with it
+
+## 1.0.9
+
+### Added
+
+- Worker entries in `package.json` `termix.workers`, each bundled on its own into `dist/workers/<name>.js`
+- A `.wasm`, `.ttf` or `.otf` import gives the file's bytes, in `termix-plugin build` and in plugin tests
+
+### Fixed
+
+- The plugin guide listed jszip, guacamole-lite and @anthropic-ai/sdk as shared packages, but they are bundled
+
 ## 1.0.8
 
 ### Added

package/PLUGIN-GUIDE.md

@@ -1,6 +1,6 @@
 # Termix plugin guide
 
-SDK 1.0.8 | Plugin API 1.2.0
+SDK 1.0.10 | Plugin API 1.2.0
 
 This guide is for anyone, person or AI coding tool, building a Termix plugin. It ships inside
 `@termix-ssh/plugin-sdk`, so the copy in your `node_modules` always matches the SDK you have installed.
@@ -90,7 +90,7 @@ npm test             # termix-plugin test: Vitest
 npm run typecheck    # tsc
 npm run validate     # termix-plugin validate: manifest, files, migrations, changelog, docs
 npm run migrations   # termix-plugin migrations: write migrations after changing tables.ts
-npm run pack         # termix-plugin pack: write <id>-<version>.tmxplug
+npm run pack         # termix-plugin pack: write <id>-<version>.tmxplug (with LICENSE and NOTICE)
 npm run format       # Prettier
 npm run format:check
 ```
@@ -334,8 +334,27 @@ ctx.schedule.every(60_000, () => refresh(), { jitterMs: 5_000 });
 ### Shared packages
 
 These come from Termix and are never bundled: `@termix-ssh/plugin-sdk`, `express`, `ssh2`, `ws`, `multer`,
-`cookie-parser`, `axios`, `jszip`, `guacamole-lite`, `@anthropic-ai/sdk`, `drizzle-orm`, `sharp` and every
-Node builtin. List the ones you use in `peerDependencies`. Any other npm package is bundled.
+`cookie-parser`, `axios`, `drizzle-orm`, `sharp` and every Node builtin. List the ones you use in
+`peerDependencies`. Any other npm package is bundled.
+
+### Workers and WebAssembly
+
+Heavy work (decoding, encoding, parsing) belongs in a worker thread so it never blocks the server. Name
+each worker entry in `package.json`:
+
+```json
+"termix": { "workers": { "engine": "src/backend/engine/worker.ts" } }
+```
+
+`build` bundles it alone into `dist/workers/engine.js`; start it with
+`new Worker(new URL("./workers/engine.js", import.meta.url))`. A worker bundles everything it imports and
+can't use the shared packages above, so it must not import `@termix-ssh/plugin-sdk`. Talk to it with
+`postMessage`.
+
+Importing a `.wasm`, `.ttf` or `.otf` file gives its bytes as a `Uint8Array`, in `build` and in tests, so a module ships
+inside the bundle with no file to find. Compile it once on the main thread with `new WebAssembly.Module`
+and post that to each worker. Add `declare module "*.wasm" { const bytes: Uint8Array; export default bytes; }`
+to a `.d.ts` in the plugin.
 
 ## Database
 
@@ -683,20 +702,20 @@ To run your own registry instead, see https://docs.termix.site/develop/registrie
 
 ## termix-plugin CLI
 
-| Command                        | What it does                                                                                   |
-| ------------------------------ | ---------------------------------------------------------------------------------------------- |
-| `build`                        | Bundle `dist/backend.js` and `dist/frontend.js`, CSS, locales, migrations, `dist/openapi.json` |
-| `validate`                     | Check the manifest, its files, migrations for every database, the changelog and `package.json` |
-| `test`                         | Apply patches, run Vitest                                                                      |
-| `migrations`                   | Write a migration per database from `tables.ts`. `--check` fails when one is missing           |
-| `openapi`                      | Write `dist/openapi.json` from `@openapi` blocks                                               |
-| `pack`                         | Validate, then write `<id>-<version>.tmxplug`. `--out <dir>`                                   |
-| `sign <file>`                  | Sign a `.tmxplug` with `TERMIX_PLUGIN_SIGNING_KEY`                                             |
-| `verify <file> --key <base64>` | Check a `.tmxplug` against its `.sig`                                                          |
-| `keygen`                       | Write a new signing key pair. `--out <dir>`                                                    |
-| `changelog`                    | Print one version's notes. `--version x.y.z`                                                   |
-| `patch`                        | Apply the plugin's dependency patches (`build` and `test` do this too)                         |
-| `dev`                          | Build, pack and install on a server, again on every change. `--server`, `--key`, `--once`      |
+| Command                        | What it does                                                                                    |
+| ------------------------------ | ----------------------------------------------------------------------------------------------- |
+| `build`                        | Bundle `dist/backend.js`, `dist/frontend.js`, workers, CSS, locales, migrations, `openapi.json` |
+| `validate`                     | Check the manifest, its files, migrations for every database, the changelog and `package.json`  |
+| `test`                         | Apply patches, run Vitest                                                                       |
+| `migrations`                   | Write a migration per database from `tables.ts`. `--check` fails when one is missing            |
+| `openapi`                      | Write `dist/openapi.json` from `@openapi` blocks                                                |
+| `pack`                         | Validate, then write `<id>-<version>.tmxplug`. `--out <dir>`                                    |
+| `sign <file>`                  | Sign a `.tmxplug` with `TERMIX_PLUGIN_SIGNING_KEY`                                              |
+| `verify <file> --key <base64>` | Check a `.tmxplug` against its `.sig`                                                           |
+| `keygen`                       | Write a new signing key pair. `--out <dir>`                                                     |
+| `changelog`                    | Print one version's notes. `--version x.y.z`                                                    |
+| `patch`                        | Apply the plugin's dependency patches (`build` and `test` do this too)                          |
+| `dev`                          | Build, pack and install on a server, again on every change. `--server`, `--key`, `--once`       |
 
 ## SDK entry points
 

package/cli/commands/build.mjs

@@ -52,6 +52,43 @@ export function externalRequireInterop(externals) {
   };
 }
 
+// A .wasm or font import becomes its bytes (a Uint8Array) inside the bundle,
+// so it ships in backend.js or a worker with no separate file to find.
+export const BINARY_EXTENSIONS = [".wasm", ".ttf", ".otf"];
+const BINARY_LOADERS = Object.fromEntries(
+  BINARY_EXTENSIONS.map((ext) => [ext, "binary"]),
+);
+
+const REQUIRE_BANNER =
+  "import { createRequire as __termixCreateRequire } from 'node:module'; const require = __termixCreateRequire(import.meta.url);";
+
+/**
+ * package.json "termix": { "workers": { "engine": "src/backend/engine/worker.ts" } }
+ * bundles each entry on its own into dist/workers/<name>.js, for
+ * new Worker(new URL("./workers/<name>.js", import.meta.url)). Nothing is left
+ * external: core's import fallback only runs on the main thread, so a worker
+ * can't rely on host packages and must not import the SDK.
+ */
+export function readWorkerEntries(cwd, pluginId) {
+  const pkgPath = path.join(cwd, "package.json");
+  const pkg = fs.existsSync(pkgPath)
+    ? JSON.parse(fs.readFileSync(pkgPath, "utf8"))
+    : {};
+  const workers = pkg.termix?.workers ?? {};
+  return Object.entries(workers).map(([name, entry]) => {
+    if (!/^[a-z0-9-]+$/.test(name)) {
+      throw new Error(`${pluginId}: worker name "${name}" must be lowercase`);
+    }
+    const file = path.resolve(cwd, String(entry));
+    if (!fs.existsSync(file)) {
+      throw new Error(
+        `${pluginId}: worker "${name}" entry ${entry} is missing`,
+      );
+    }
+    return { name, file };
+  });
+}
+
 const SDK_PATCHES = path.join(
   path.dirname(fileURLToPath(import.meta.url)),
   "..",
@@ -216,13 +253,27 @@ export async function build({ cwd }) {
     // node_modules import instead, resolved at runtime like a host-provided
     // package.
     external: [...BACKEND_EXTERNALS, ...(manifest.nativeDependencies ?? [])],
+    loader: BINARY_LOADERS,
     // Bundled CJS deps still call require() for Node builtins at runtime.
     // ESM has no ambient require, so give esbuild's require shim a real one.
-    banner: {
-      js: "import { createRequire as __termixCreateRequire } from 'node:module'; const require = __termixCreateRequire(import.meta.url);",
-    },
+    banner: { js: REQUIRE_BANNER },
   });
 
+  for (const worker of readWorkerEntries(cwd, pluginId)) {
+    await esbuild.build({
+      entryPoints: [worker.file],
+      outfile: path.join(outDir, "workers", `${worker.name}.js`),
+      bundle: true,
+      format: "esm",
+      platform: "node",
+      target: "node22",
+      sourcemap: true,
+      logLevel: "warning",
+      loader: BINARY_LOADERS,
+      banner: { js: REQUIRE_BANNER },
+    });
+  }
+
   // Without this Node finds the host's typeless package.json, tries backend.js
   // as CommonJS first and warns before reparsing it as ESM.
   fs.writeFileSync(

package/cli/lib/tmxplug.mjs

@@ -11,6 +11,9 @@ export const TMXPLUG_CONTENTS = [
   "README.md",
   "CHANGELOG.md",
   "icon.svg",
+  // Licence texts, so third-party notices travel with the plugin.
+  "LICENSE",
+  "NOTICE",
 ];
 
 const BLOCK = 512;

package/dist/vitest-preset.d.ts

@@ -8,11 +8,25 @@
  *
  * Two projects: tests/backend runs in node, tests/frontend in jsdom.
  */
+/**
+ * termix-plugin build turns a .wasm or font import into its bytes. Tests get the same,
+ * so code that imports a module compiles it the same way under vitest.
+ */
+export declare function wasmBinaryPlugin(): {
+    name: string;
+    enforce: "pre";
+    load(id: string): string;
+};
 export interface PluginVitestOptions {
     /** Extra aliases merged over the defaults. */
     alias?: Record<string, string>;
 }
 export declare function pluginVitestConfig(configUrl: string, options?: PluginVitestOptions): {
+    plugins: {
+        name: string;
+        enforce: "pre";
+        load(id: string): string;
+    }[];
     resolve: {
         alias: Record<string, string>;
     };
@@ -21,6 +35,11 @@ export declare function pluginVitestConfig(configUrl: string, options?: PluginVi
         setupFiles: string[];
         pool: "threads";
         projects: ({
+            plugins: {
+                name: string;
+                enforce: "pre";
+                load(id: string): string;
+            }[];
             resolve: {
                 alias: Record<string, string>;
             };
@@ -35,6 +54,11 @@ export declare function pluginVitestConfig(configUrl: string, options?: PluginVi
                 server?: undefined;
             };
         } | {
+            plugins: {
+                name: string;
+                enforce: "pre";
+                load(id: string): string;
+            }[];
             resolve: {
                 alias: Record<string, string>;
             };

package/dist/vitest-preset.js

@@ -29,6 +29,24 @@ function findRepoRoot(startDir) {
         dir = parent;
     }
 }
+/**
+ * termix-plugin build turns a .wasm or font import into its bytes. Tests get the same,
+ * so code that imports a module compiles it the same way under vitest.
+ */
+export function wasmBinaryPlugin() {
+    return {
+        name: "termix-wasm-binary",
+        enforce: "pre",
+        load(id) {
+            const file = id.split("?")[0];
+            if (![".wasm", ".ttf", ".otf"].some((ext) => file.endsWith(ext))) {
+                return null;
+            }
+            const base64 = fs.readFileSync(file).toString("base64");
+            return `export default new Uint8Array(Buffer.from(${JSON.stringify(base64)}, "base64"));`;
+        },
+    };
+}
 export function pluginVitestConfig(configUrl, options = {}) {
     const pluginDir = path.dirname(fileURLToPath(configUrl));
     const manifestPath = path.join(pluginDir, "manifest.json");
@@ -61,7 +79,9 @@ export function pluginVitestConfig(configUrl, options = {}) {
     // Forks workers on Windows abort now and then with "Worker exited
     // unexpectedly". Threads don't.
     const pool = "threads";
+    const plugins = [wasmBinaryPlugin()];
     return {
+        plugins,
         resolve: { alias },
         test: {
             globals: true,
@@ -69,6 +89,7 @@ export function pluginVitestConfig(configUrl, options = {}) {
             pool,
             projects: [
                 {
+                    plugins,
                     resolve: { alias },
                     test: {
                         name: `${pluginId}:backend`,
@@ -81,6 +102,7 @@ export function pluginVitestConfig(configUrl, options = {}) {
                     },
                 },
                 {
+                    plugins,
                     resolve: { alias },
                     test: {
                         name: `${pluginId}:frontend`,

package/package.json

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