@owncast/plugin-sdk 0.6.0 → 0.11.0

package/README.md

@@ -1,6 +1,6 @@
 # @owncast/plugin-sdk
 
-SDK for authoring [Owncast](https://owncast.online) plugins in JavaScript or TypeScript. Plugins compile to WebAssembly and run sandboxed inside the Owncast server.
+SDK for authoring [Owncast](https://owncast.online) plugins in JavaScript or TypeScript. Plugins ship as source and run sandboxed inside the Owncast server, on a JavaScript engine the host embeds, so there's no wasm toolchain to install.
 
 Most authors don't install this directly, instead, scaffold a new project with `npx create-owncast-plugin@latest <slug>` and the generated `package.json` already lists it as a dependency.
 
@@ -9,10 +9,10 @@ Most authors don't install this directly, instead, scaffold a new project with `
 ```sh
 npx create-owncast-plugin@latest my-plugin
 cd my-plugin
-npm install     # postinstall fetches the per-platform wasm toolchain
-npm run build   # compiles src/plugin.js into an intermediate build artifact
-npm run package # zips manifest + wasm + assets + icon.png into my-plugin.ocpkg
-npm test        # runs scenarios from __tests__/
+npm install     # postinstall fetches the prebuilt test/serve host binaries
+npm run build   # bundles src/plugin.{js,ts} into my-plugin.js
+npm test        # builds, then runs scenarios from __tests__/
+npm run package # zips manifest + my-plugin.js + assets + icon.png into my-plugin.ocpkg
 ```
 
 Then install `my-plugin.ocpkg` in Owncast. From the admin's **Plugins** page click **Upload plugin** and pick the file, or copy it directly to the server's `data/plugins/` directory. Toggle **Enabled** on the plugin's row to load it.
@@ -43,7 +43,7 @@ Declare the permissions your plugin uses (`chat.send` for the example above) in
 - `index.d.ts`, TypeScript declarations for editor autocomplete on every event payload and host API.
 - `testing.js`, JS test API (`runScenarios`) for writing `__tests__/*.test.js` with the full ergonomics of JavaScript instead of static JSON.
 - `bin/owncast-plugin`, CLI: `build`, `test`, `serve`, `package` subcommands.
-- `scripts/postinstall.js`, downloads the per-platform wasm toolchain (`extism-js`, `wasm-merge`, `wasm-opt`) and the Go test/serve runner on install.
+- `scripts/postinstall.js`, downloads the Go test/serve host binaries on install. Plugins ship as source and run on the engine the host embeds, so no wasm toolchain (`extism-js`, binaryen) is fetched (that's a maintainer-only dependency of the engine build).
 
 ## License
 

package/bin/owncast-plugin.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-// `owncast-plugin build`  , bundle src/plugin.{js,ts} into <slug>.wasm
-// `owncast-plugin test`   , run scenarios in __tests__/ against the wasm
+// `owncast-plugin build`  , bundle src/plugin.{js,ts} into <slug>.js
+// `owncast-plugin test`   , run scenarios in __tests__/ against the plugin
 // `owncast-plugin serve`  , run a localhost dev HTTP server
 // `owncast-plugin package`, produce a single-file <slug>.ocpkg suitable
 //                            for distribution / installation
@@ -8,7 +8,7 @@
 // "Slug" is the plugin's identifier: lowercase, hyphenated, used in
 // filenames, URL segments, and as the registry's primary key. Plugin
 // authors set the human-readable display name via `name` in their
-// manifest; if they don't set `slug`, the CLI auto-derives it from
+// manifest. If they don't set `slug`, the CLI auto-derives it from
 // `name`.
 
 const fs = require("fs");
@@ -16,6 +16,7 @@ const path = require("path");
 const { execFileSync } = require("child_process");
 const esbuild = require("esbuild");
 const JSZip = require("jszip");
+const { slugify } = require("../slug");
 
 const cmd = process.argv[2] || "build";
 const restArgs = process.argv.slice(3);
@@ -30,30 +31,13 @@ function fail(e) {
 // Same shape the host + SDK + registry all validate against.
 const slugPattern = /^[a-z][a-z0-9-]{0,63}$/;
 
-// slugify mirrors the host's Go slugify: ASCII letters and digits
-// pass through lowercased; everything else collapses to a single
-// hyphen; leading and trailing hyphens are trimmed.
-// Non-ASCII names (e.g. "Café") degrade noisily (-> "caf"); plugins
-// with accented or non-Latin display names should pin `slug` in the
-// manifest instead of relying on auto-derivation.
-function slugify(input) {
-  let out = "";
-  let prevHyphen = false;
-  for (const ch of input) {
-    const code = ch.codePointAt(0);
-    let lower = ch;
-    if (code >= 65 && code <= 90) lower = String.fromCodePoint(code + 32);
-    const lc = lower.codePointAt(0);
-    if ((lc >= 97 && lc <= 122) || (lc >= 48 && lc <= 57)) {
-      out += lower;
-      prevHyphen = false;
-    } else if (!prevHyphen && out.length > 0) {
-      out += "-";
-      prevHyphen = true;
-    }
-  }
-  return out.replace(/-+$/, "");
-}
+// Canonical registry browse categories for the optional manifest
+// `category` field. Shared taxonomy with the registry and the admin UI.
+const categories = new Set([
+  "chat-bots", "chat-filters", "moderation", "authentication", "themes",
+  "overlays", "notifications", "integrations", "video", "analytics",
+  "games", "admin-utilities", "examples", "other",
+]);
 
 // readAndResolveManifest loads plugin.manifest.json, validates the
 // required fields, and returns a manifest object with `slug` filled
@@ -83,6 +67,13 @@ function readAndResolveManifest(manifestPath) {
       `manifest.slug ${JSON.stringify(slug)} must match ${slugPattern} (lowercase letters/digits/hyphens, starting with a letter, max 64 chars)`,
     );
   }
+  if (manifest.category !== undefined && !categories.has(manifest.category)) {
+    // Warn only: the host and registry tolerate unknown categories, they
+    // just won't match any browse filter.
+    console.warn(
+      `warning: manifest.category ${JSON.stringify(manifest.category)} is not a known category (${[...categories].join(", ")})`,
+    );
+  }
   manifest.slug = slug;
   return manifest;
 }
@@ -115,6 +106,26 @@ function runBinary(name, args) {
   }
 }
 
+// loadCheck runs `owncast-plugin-test --load-only <dir>` and aborts the
+// current command when the plugin fails the install-time load check.
+function loadCheck(dir) {
+  const cache = findCacheDir();
+  const bin = path.join(cache, "owncast-plugin-test");
+  if (!fs.existsSync(bin)) {
+    console.error(
+      `owncast-plugin-test not found at ${bin} — cannot verify the plugin ` +
+        `loads. Run npm install so the SDK postinstall fetches the host binaries.`,
+    );
+    process.exit(1);
+  }
+  try {
+    execFileSync(bin, ["--load-only", dir], { stdio: "inherit" });
+  } catch (e) {
+    console.error("package aborted: plugin failed the install-time load check");
+    process.exit(typeof e.status === "number" ? e.status : 1);
+  }
+}
+
 async function buildMain() {
   const cwd = process.cwd();
   const manifestPath = path.join(cwd, "plugin.manifest.json");
@@ -145,7 +156,7 @@ async function buildMain() {
 
   // Shared-engine model: bundle the author's plugin into a tiny CommonJS
   // script with @owncast/plugin-sdk marked EXTERNAL. It ships in the .ocpkg as
-  // plugin.js; the host infers the JavaScript runtime from that filename and
+  // plugin.js. The host infers the JavaScript runtime from that filename and
   // runs it on the embedded JS engine, which provides
   // require("@owncast/plugin-sdk"). No per-plugin wasm, no extism-js.
   const buildDir = path.join(cwd, ".owncast-build");
@@ -162,13 +173,13 @@ async function buildMain() {
     logLevel: "warning",
   });
 
-  // public/ and assets/ live at the source root; the packager picks them up.
+  // public/ and assets/ live at the source root, and the packager picks them up.
   console.log(`built ${path.relative(cwd, scriptOut)}`);
 }
 
 // `owncast-plugin package`, bundle the project into a single .ocpkg file
-// (zip archive with plugin.manifest.json, plugin.wasm, and optional
-// public/ and assets/ directories). Builds the wasm first if it
+// (zip archive with plugin.manifest.json, plugin.js source, and optional
+// public/ and assets/ directories). Builds the source first if it
 // doesn't exist.
 async function packageMain() {
   const cwd = process.cwd();
@@ -184,9 +195,15 @@ async function packageMain() {
     await buildMain();
   }
 
+  // Refuse to package a plugin a real Owncast server would refuse to load.
+  // owncast-plugin-test --load-only runs the same install-time load path the
+  // host runs: register(), manifest/runtime agreement, and permission-gated
+  // subscriptions (e.g. a fediverse handler without "fediverse.inbound").
+  loadCheck(cwd);
+
   // The code entry's name (plugin.js) is what tells the host this is a
-  // JavaScript plugin — no "type" field in the manifest. The manifest ships
-  // verbatim.
+  // JavaScript plugin, so there is no "type" field in the manifest. The
+  // manifest ships verbatim.
   const publicDir = path.join(cwd, "public");
   const assetsDir = path.join(cwd, "assets");
   const zip = new JSZip();
@@ -204,7 +221,7 @@ async function packageMain() {
   }
   // Bundle a top-level INSTRUCTIONS.md if the plugin source root has one.
   // The host serves it to the admin (which renders it as markdown in a
-  // details tab); like icon.png it needs no manifest field and no
+  // details tab). Like icon.png it needs no manifest field and no
   // http.serve permission. The filename is fixed for simplicity.
   const instructionsPath = path.join(cwd, "INSTRUCTIONS.md");
   if (fs.existsSync(instructionsPath) && fs.statSync(instructionsPath).isFile()) {
@@ -251,7 +268,7 @@ async function packageMain() {
     fs.unlinkSync(scriptPath);
   } catch (e) {
     // Don't fail the package step over a cleanup miss. The .ocpkg is
-    // already written; surface the warning so the author notices the
+    // already written, so surface the warning so the author notices the
     // straggler but treat the run as successful.
     if (e.code !== "ENOENT") {
       console.warn(`warning: could not clean up ${path.relative(cwd, scriptPath)}: ${e.message}`);
@@ -290,7 +307,7 @@ function findCacheDir() {
     path.join(__dirname, "..", "..", "..", "tools"),
   ];
   // Pick the first candidate that has the prebuilt host binaries (the only
-  // tooling the SDK ships now — `build` is pure esbuild and needs nothing here).
+  // tooling the SDK ships now, since `build` is pure esbuild and needs nothing here).
   for (const c of candidates) {
     if (
       fs.existsSync(path.join(c, "owncast-plugin-test")) ||