@owncast/plugin-sdk 0.5.0 → 0.10.1

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);
@@ -25,57 +26,11 @@ function fail(e) {
   process.exit(1);
 }
 
-// toolchainEnv extends the current environment with the variables
-// the dynamic linker needs to find `libbinaryen` next to `wasm-merge`
-// and `wasm-opt` (which extism-js shells out to during the wasm
-// pipeline). Linux uses LD_LIBRARY_PATH; macOS uses DYLD_LIBRARY_PATH
-// plus DYLD_FALLBACK_LIBRARY_PATH (Apple Silicon strips
-// DYLD_LIBRARY_PATH in some sandboxed contexts, the FALLBACK
-// variant survives). Setting all three is safe on both OSes; the
-// inactive ones are ignored. This is the difference between "build
-// succeeds" and `library not loaded: @rpath/libbinaryen.dylib` on
-// macOS.
-function toolchainEnv(cache) {
-  const libDir = path.join(cache, "lib");
-  return {
-    ...process.env,
-    PATH: `${cache}:${process.env.PATH}`,
-    LD_LIBRARY_PATH: `${libDir}:${process.env.LD_LIBRARY_PATH || ""}`,
-    DYLD_LIBRARY_PATH: `${libDir}:${process.env.DYLD_LIBRARY_PATH || ""}`,
-    DYLD_FALLBACK_LIBRARY_PATH: `${libDir}:${process.env.DYLD_FALLBACK_LIBRARY_PATH || "/usr/local/lib:/usr/lib"}`,
-  };
-}
-
 // slugPattern matches a valid plugin slug: a lowercase letter
 // followed by lowercase letters/digits/hyphens, up to 64 chars total.
 // 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(/-+$/, "");
-}
-
 // readAndResolveManifest loads plugin.manifest.json, validates the
 // required fields, and returns a manifest object with `slug` filled
 // in: either the author's explicit `slug`, or one auto-derived from
@@ -127,17 +82,35 @@ function runBinary(name, args) {
     );
     process.exit(1);
   }
-  const env = toolchainEnv(cache);
   try {
     execFileSync(bin, args.length > 0 ? args : [process.cwd()], {
       stdio: "inherit",
-      env,
     });
   } catch (e) {
     process.exit(typeof e.status === "number" ? e.status : 1);
   }
 }
 
+// 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");
@@ -166,99 +139,32 @@ async function buildMain() {
       "no plugin source found (expected src/plugin.ts or plugin.js)",
     );
 
-  // Synthesize an entry that injects the manifest, requires user code,
-  // then re-exports the SDK runtime exports as wasm-visible exports.
+  // 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
+  // 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");
   fs.mkdirSync(buildDir, { recursive: true });
-  const synthEntry = path.join(buildDir, "entry.js");
-  const manifestJSON = JSON.stringify(manifest);
-  // Always emit register/on_event/on_filter as wasm exports. The SDK derives
-  // subscriptions at runtime from the plugin's handler methods and merges
-  // them into the manifest returned by register(). The host then only calls
-  // on_event/on_filter for plugins actually subscribed to that event, so
-  // unused exports are harmless.
-  const entrySrc = `const sdk = require("@owncast/plugin-sdk");
-const MANIFEST_BASE = ${manifestJSON};
-require(${JSON.stringify(entry)});
-function register() {
-  const manifest = Object.assign({}, MANIFEST_BASE, { subscriptions: sdk.describeSubscriptions() });
-  Host.outputString(JSON.stringify(manifest));
-  return 0;
-}
-function on_event() {
-  const envelope = JSON.parse(Host.inputString());
-  sdk.dispatchEvent(envelope);
-  return 0;
-}
-function on_filter() {
-  const envelope = JSON.parse(Host.inputString());
-  const result = sdk.dispatchFilter(envelope);
-  Host.outputString(JSON.stringify(result));
-  return 0;
-}
-function on_http_request() {
-  const request = JSON.parse(Host.inputString());
-  const response = sdk.dispatchHttp(request);
-  Host.outputString(JSON.stringify(response));
-  return 0;
-}
-function on_tab_content() {
-  const req = JSON.parse(Host.inputString());
-  Host.outputString(sdk.dispatchTabContent(req));
-  return 0;
-}
-function on_page_content() {
-  const req = JSON.parse(Host.inputString());
-  Host.outputString(sdk.dispatchPageContent(req));
-  return 0;
-}
-module.exports = { register, on_event, on_filter, on_http_request, on_tab_content, on_page_content };
-`;
-  fs.writeFileSync(synthEntry, entrySrc);
-
-  // Bundle to a single CJS file targeting the QuickJS runtime extism-js uses.
-  const bundledJS = path.join(buildDir, "bundle.js");
+  const scriptOut = path.join(cwd, `${slug}.js`);
   await esbuild.build({
-    entryPoints: [synthEntry],
+    entryPoints: [entry],
     bundle: true,
     format: "cjs",
     platform: "neutral",
     target: "es2020",
-    outfile: bundledJS,
+    external: ["@owncast/plugin-sdk"],
+    outfile: scriptOut,
     logLevel: "warning",
   });
 
-  // Generate index.d.ts declaring exports + host imports based on permissions.
-  const dts = path.join(buildDir, "index.d.ts");
-  fs.writeFileSync(dts, generateInterface(manifest));
-
-  // Find toolchain.
-  const cache = findCacheDir();
-  const extismJs = path.join(cache, "extism-js");
-  if (!fs.existsSync(extismJs)) {
-    throw new Error(
-      `extism-js not found at ${extismJs}, run \`npm install\` to fetch the toolchain`,
-    );
-  }
-  const env = toolchainEnv(cache);
-
-  const wasmOut = path.join(cwd, `${slug}.wasm`);
-  execFileSync(extismJs, [bundledJS, "-i", dts, "-o", wasmOut], {
-    stdio: "inherit",
-    env,
-  });
-
-  // public/ and assets/ live at the source root; the host's
-  // loose-files loader picks them up as siblings of the built
-  // <slug>.wasm without any rename, so the build CLI doesn't need to
-  // create or mirror anything for them.
-
-  console.log(`built ${path.relative(cwd, wasmOut)}`);
+  // 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();
@@ -269,16 +175,25 @@ async function packageMain() {
   const manifest = readAndResolveManifest(manifestPath);
   const slug = manifest.slug;
 
-  const wasmPath = path.join(cwd, `${slug}.wasm`);
-  if (!fs.existsSync(wasmPath)) {
+  const scriptPath = path.join(cwd, `${slug}.js`);
+  if (!fs.existsSync(scriptPath)) {
     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, 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();
   zip.file("plugin.manifest.json", fs.readFileSync(manifestPath));
-  zip.file("plugin.wasm", fs.readFileSync(wasmPath));
+  zip.file("plugin.js", fs.readFileSync(scriptPath));
   let fileCount = 2;
   // Bundle a top-level icon.png if the plugin source root has one.
   // The host reads it from /api/plugins/<slug>/icon to render in the
@@ -291,7 +206,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()) {
@@ -329,19 +244,19 @@ async function packageMain() {
     `packaged ${path.relative(cwd, outPath)} (${sizeKb} KB, ${fileCount} files)`,
   );
 
-  // Drop the intermediate <slug>.wasm now that it's bundled inside the
+  // Drop the intermediate <slug>.js now that it's bundled inside the
   // .ocpkg. The .ocpkg is the only artifact authors care about: leaving
-  // the loose .wasm next to it just confuses "what do I ship". Only
+  // the loose script next to it just confuses "what do I ship". Only
   // runs on a successful package so a mid-pipeline failure leaves the
   // last good build in place for debugging.
   try {
-    fs.unlinkSync(wasmPath);
+    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, wasmPath)}: ${e.message}`);
+      console.warn(`warning: could not clean up ${path.relative(cwd, scriptPath)}: ${e.message}`);
     }
   }
 }
@@ -366,112 +281,6 @@ function* walkFiles(dir) {
   }
 }
 
-function generateInterface(manifest) {
-  const exports = [
-    "register(): I32",
-    "on_event(): I32",
-    "on_filter(): I32",
-    "on_http_request(): I32",
-    "on_tab_content(): I32",
-    "on_page_content(): I32",
-  ];
-
-  const perms = new Set(manifest.permissions || []);
-  const imports = [];
-  // Timers are ambient (no permission): the host always provides them, since
-  // a plugin can't setTimeout in the sandbox.
-  imports.push("owncast_timer_set(id: I64, delayMs: I64, repeat: I32): I32");
-  imports.push("owncast_timer_clear(id: I64): void");
-  // Config is ambient too: a plugin reading its own manifest-declared config
-  // (admin override falling back to the declared default) needs no permission.
-  imports.push("owncast_config_get(keyPtr: PTR): PTR");
-  // Asset reading is ambient: a plugin reads only files it shipped itself.
-  imports.push("owncast_asset_read(pathPtr: PTR): PTR");
-  if (perms.has("chat.send")) {
-    imports.push("owncast_send_chat(textPtr: PTR): void");
-    imports.push("owncast_send_chat_action(textPtr: PTR): void");
-    imports.push("owncast_send_chat_system(bodyPtr: PTR): void");
-    imports.push("owncast_send_chat_to(clientId: I64, textPtr: PTR): void");
-  }
-  if (perms.has("chat.history")) {
-    imports.push("owncast_chat_history(limit: I32): PTR");
-    imports.push("owncast_chat_clients(): PTR");
-  }
-  if (perms.has("chat.moderate")) {
-    imports.push("owncast_delete_message(idPtr: PTR): void");
-    imports.push("owncast_kick_client(clientId: I64): void");
-  }
-  if (perms.has("notifications.send")) {
-    imports.push("owncast_notify_discord(textPtr: PTR): void");
-    imports.push("owncast_notify_browser_push(payloadPtr: PTR): void");
-    imports.push("owncast_notify_fediverse(payloadPtr: PTR): void");
-  }
-  if (perms.has("users.read")) {
-    imports.push("owncast_users_list(): PTR");
-    imports.push("owncast_user_get(idPtr: PTR): PTR");
-  }
-  if (perms.has("users.moderate")) {
-    imports.push(
-      "owncast_user_set_enabled(idPtr: PTR, enabled: I32, reasonPtr: PTR): void",
-    );
-    imports.push("owncast_ban_ip(ipPtr: PTR): void");
-  }
-  if (perms.has("storage.upload")) {
-    imports.push("owncast_storage_upload(namePtr: PTR, dataPtr: PTR): PTR");
-  }
-  if (perms.has("storage.fs")) {
-    imports.push("owncast_fs_read(pathPtr: PTR): PTR");
-    imports.push("owncast_fs_write(pathPtr: PTR, dataPtr: PTR): PTR");
-    imports.push("owncast_fs_list(dirPtr: PTR): PTR");
-    imports.push("owncast_fs_delete(pathPtr: PTR): PTR");
-    imports.push("owncast_fs_exists(pathPtr: PTR): I32");
-  }
-  if (perms.has("fediverse.post")) {
-    imports.push("owncast_fediverse_post(textPtr: PTR): PTR");
-  }
-  if (perms.has("storage.kv")) {
-    imports.push("owncast_kv_get(keyPtr: PTR): PTR");
-    imports.push("owncast_kv_set(keyPtr: PTR, valPtr: PTR): void");
-  }
-  if (perms.has("events.emit"))
-    imports.push(
-      "owncast_emit_event(eventTypePtr: PTR, payloadPtr: PTR): void",
-    );
-  if (perms.has("http.sse"))
-    imports.push(
-      "owncast_sse_send(channelPtr: PTR, eventPtr: PTR, dataPtr: PTR): void",
-    );
-  if (perms.has("server.read")) {
-    imports.push("owncast_stream_current(): PTR");
-    imports.push("owncast_server_info(): PTR");
-    imports.push("owncast_server_socials(): PTR");
-    imports.push("owncast_server_emotes(): PTR");
-    imports.push("owncast_server_federation(): PTR");
-    imports.push("owncast_stream_broadcaster(): PTR");
-    imports.push("owncast_server_tags(): PTR");
-  }
-  if (perms.has("videoconfig.read")) {
-    imports.push("owncast_video_config_read(): PTR");
-  }
-  if (perms.has("videoconfig.write")) {
-    imports.push("owncast_video_config_write(configPtr: PTR): PTR");
-  }
-  if (perms.has("ui.modify")) {
-    imports.push("owncast_add_actions(actionsPtr: PTR): void");
-    imports.push("owncast_clear_actions(): void");
-  }
-
-  let out = `declare module 'main' {\n`;
-  for (const e of exports) out += `  export function ${e};\n`;
-  out += `}\n`;
-  if (imports.length > 0) {
-    out += `\ndeclare module 'extism:host' {\n  interface user {\n`;
-    for (const i of imports) out += `    ${i};\n`;
-    out += `  }\n}\n`;
-  }
-  return out;
-}
-
 function findCacheDir() {
   // Look in node_modules/@owncast/plugin-sdk/bin/.cache (when used as a dep)
   // and in the repo's tools/ dir (when developing). The dev candidate
@@ -482,12 +291,10 @@ function findCacheDir() {
     path.join(__dirname, "..", "bin", ".cache"),
     path.join(__dirname, "..", "..", "..", "tools"),
   ];
-  // Pick the first candidate that has any of the expected tools, different
-  // commands need different binaries (build needs extism-js, test needs
-  // owncast-plugin-test) but they share a cache.
+  // Pick the first candidate that has the prebuilt host binaries (the only
+  // 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, "extism-js")) ||
       fs.existsSync(path.join(c, "owncast-plugin-test")) ||
       fs.existsSync(path.join(c, "owncast-plugin-serve"))
     ) {