@owncast/plugin-sdk 0.4.2 → 0.6.0

package/bin/owncast-plugin.js

@@ -25,27 +25,6 @@ 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.
@@ -127,11 +106,9 @@ 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);
@@ -166,84 +143,27 @@ 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;
-}
-module.exports = { register, on_event, on_filter, on_http_request };
-`;
-  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; the packager picks them up.
+  console.log(`built ${path.relative(cwd, scriptOut)}`);
 }
 
 // `owncast-plugin package`, bundle the project into a single .ocpkg file
@@ -259,16 +179,19 @@ 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();
   }
 
+  // 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.
   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
@@ -319,19 +242,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
     // 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}`);
     }
   }
 }
@@ -356,108 +279,6 @@ function* walkFiles(dir) {
   }
 }
 
-function generateInterface(manifest) {
-  const exports = [
-    "register(): I32",
-    "on_event(): I32",
-    "on_filter(): I32",
-    "on_http_request(): 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");
-  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
@@ -468,12 +289,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 — `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"))
     ) {

package/index.d.ts

@@ -284,6 +284,15 @@ export interface OutgoingHttpResponse {
   body?: string;
 }
 
+/** Request context passed to `onTabContent` and `onPageContent` handlers. */
+export interface ContentRequest {
+  /** The tab or page-content slot's slug, as declared in the manifest. */
+  slug: string;
+  /** The viewing user's chat identity, when available. Undefined for
+   *  anonymous viewers or when the host cannot resolve an identity. */
+  user?: ChatUser;
+}
+
 /** Payload for the sse.connect / sse.disconnect events. Fired when a browser
  *  opens or closes one of the plugin's `/plugins/<name>/_sse/<channel>`
  *  streams, so the plugin can track who is connected. `connectionId` is unique
@@ -303,6 +312,22 @@ export interface TickEvent {
 }
 
 export interface PluginDef {
+  /** Declarative chat-command table. When set, the SDK wires the chat
+   *  subscription and prefix parsing for you — no onChatMessage needed. Maps
+   *  canonical command name → definition (run/description/usage/aliases/
+   *  modOnly/cooldownMs/...); see {@link CommandDefinition}. For advanced
+   *  composition (e.g. dropping command messages via a filter) use the
+   *  lower-level {@link defineCommands} router instead. If you also provide
+   *  onChatMessage, the router runs first and then onChatMessage runs for every
+   *  message. */
+  commands?: Record<string, CommandDefinition>;
+  /** Command prefix for the `commands` table. Default "!". */
+  commandPrefix?: string;
+  /** Match command names case-sensitively. Default false. */
+  commandsCaseSensitive?: boolean;
+  /** Called when a prefixed message matched no command in `commands`. */
+  onUnknownCommand?(ctx: CommandContext): void;
+
   /** Notification handler for chat messages. Fire-and-forget. */
   onChatMessage?(msg: ChatMessage): void | Promise<void>;
 
@@ -353,6 +378,18 @@ export interface PluginDef {
    *  on `req.authenticated` yourself. Requires `http.serve` permission. */
   onHttpRequest?(req: IncomingHttpRequest): OutgoingHttpResponse;
 
+  /** Render HTML for a dynamic tab. Called by the host when the tab was
+   *  declared in the manifest without a static `content` file. Return the
+   *  full HTML string to inline as the tab body. `req.user` is the viewer's
+   *  chat identity when available, undefined for anonymous viewers. */
+  onTabContent?(req: ContentRequest): string;
+
+  /** Render HTML for the plugin's dynamic extraPageContent slot. Called by
+   *  the host when extraPageContent was declared without a static `content`
+   *  file. Return the full HTML string to inline into the viewer page.
+   *  `req.user` is the viewer's chat identity when available. */
+  onPageContent?(req: ContentRequest): string;
+
   /** Handlers for plugin-emitted custom events. The key is the event type
    *  string (e.g. "announcement.broadcast"). Notifications only, to filter
    *  custom events, additional API will be needed. */
@@ -386,6 +423,11 @@ export interface CommandContext {
 
 /** One command in a {@link defineCommands} table. */
 export interface CommandDefinition {
+  /** Short, human-readable summary of what the command does. Surfaced in
+   *  command listings (e.g. a future `!help`); ignored by the router itself. */
+  description?: string;
+  /** Optional usage/example string, e.g. "!latency <0-4>". */
+  usage?: string;
   /** Alternate names that invoke this command. */
   aliases?: string[];
   /** Only allow senders whose scopes include "MODERATOR". */
@@ -523,6 +565,16 @@ export const owncast: {
      *  value. */
     get<T = unknown>(key: string, fallback?: T): T;
   };
+  /** Read files the plugin bundled in its own `assets/` directory — templates,
+   *  data files, and other bundled resources loaded at request time. Path is
+   *  relative to `assets/` and must not contain `..`. Ambient — no permission
+   *  required. */
+  assets: {
+    /** Raw bytes of the file, or `null` if not found. */
+    read(path: string): Uint8Array | null;
+    /** File contents as a UTF-8 string, or `null` if not found. */
+    readText(path: string): string | null;
+  };
   events: {
     emit(eventType: string, payload: unknown): void;
   };

package/index.js

@@ -7,6 +7,11 @@
 
 let registered = null;
 
+// Command metadata recorded by defineCommands, reported to the host via
+// register() so it can build a unified `!help` across all plugins. One entry
+// per command: { name, prefix, description, usage, aliases, modOnly }.
+const commandManifest = [];
+
 // Host-driven timers. The sandbox has no setTimeout, so owncast.timer.* asks
 // the host to schedule a callback and call back via the internal "timer.fire"
 // event. The author's callback stays here in the long-lived instance, keyed by
@@ -149,6 +154,28 @@ const isFn = (x) => typeof x === JsType.Function;
 const isObj = (x) => x !== null && typeof x === JsType.Object;
 
 function definePlugin(def) {
+  // `commands` is declarative sugar: give definePlugin a command table (and an
+  // optional commandPrefix) and the SDK wires the chat subscription for you —
+  // no onChatMessage needed. It expands into an onChatMessage handler here, so
+  // subscription derivation and dispatch treat it like any chat handler. If you
+  // also pass onChatMessage, the command router runs first, then your handler.
+  // For advanced composition (e.g. dropping command messages from chat via a
+  // filter), use the lower-level defineCommands() router directly instead.
+  if (def && isObj(def.commands)) {
+    const router = defineCommands({
+      prefix: def.commandPrefix,
+      caseSensitive: def.commandsCaseSensitive,
+      commands: def.commands,
+      onUnknown: def.onUnknownCommand,
+    });
+    const userHandler = def.onChatMessage;
+    def.onChatMessage = isFn(userHandler)
+      ? (msg) => {
+          router(msg);
+          userHandler(msg);
+        }
+      : router;
+  }
   registered = def;
   return def;
 }
@@ -183,13 +210,24 @@ function defineCommands(config) {
   const caseSensitive = !!config.caseSensitive;
   const norm = (s) => (caseSensitive ? s : s.toLowerCase());
 
-  // Resolve every name and alias to its canonical command definition.
+  // Resolve every name and alias to its canonical command definition, and
+  // record metadata so the host can build a unified `!help` (see
+  // describeCommands). Metadata is reported via register(); it never affects
+  // routing.
   const table = new Map();
   const defs = config.commands || {};
   for (const name of Object.keys(defs)) {
     const def = defs[name];
     table.set(norm(name), { name, def });
     for (const alias of def.aliases || []) table.set(norm(alias), { name, def });
+    commandManifest.push({
+      name,
+      prefix,
+      description: def.description || "",
+      usage: def.usage || "",
+      aliases: def.aliases || [],
+      modOnly: !!def.modOnly,
+    });
   }
 
   // Per-(command,user) cooldown clock, in memory for the plugin's lifetime.
@@ -286,6 +324,13 @@ function describeSubscriptions() {
   return { notify, filter: filterSubs };
 }
 
+// Used by the build-generated entry to report the plugin's chat commands in
+// register(), so the host can answer a unified `!help`. Empty when the plugin
+// declares no commands.
+function describeCommands() {
+  return commandManifest;
+}
+
 function dispatchEvent(envelope) {
   const { eventType, payload } = envelope;
   // Internal: a host-scheduled timer elapsed. Run the author's callback,
@@ -770,6 +815,26 @@ const owncast = {
       return JSON.parse(Memory.find(offset).readString());
     },
   },
+  // Read files the plugin shipped in its own assets/ directory. Useful for
+  // templates, data files, and other bundled resources that need to be read
+  // at request time. Path is relative to assets/ and must not contain "..".
+  // Ambient — no permission required.
+  assets: {
+    // Returns a Uint8Array of the file's raw bytes, or null if not found.
+    read(path) {
+      const fns = Host.getFunctions();
+      const offset = fns.owncast_asset_read(Memory.fromString(path).offset);
+      if (offset == 0) return null;
+      return new Uint8Array(Memory.find(offset).readBytes());
+    },
+    // Returns the file contents as a UTF-8 string, or null if not found.
+    readText(path) {
+      const fns = Host.getFunctions();
+      const offset = fns.owncast_asset_read(Memory.fromString(path).offset);
+      if (offset == 0) return null;
+      return Memory.find(offset).readString();
+    },
+  },
   events: {
     emit(eventType, payload) {
       const fns = Host.getFunctions();
@@ -870,6 +935,16 @@ const owncast = {
   },
 };
 
+function dispatchTabContent(req) {
+  if (!registered || !isFn(registered.onTabContent)) return "";
+  return registered.onTabContent(req) || "";
+}
+
+function dispatchPageContent(req) {
+  if (!registered || !isFn(registered.onPageContent)) return "";
+  return registered.onPageContent(req) || "";
+}
+
 module.exports = {
   definePlugin,
   defineCommands,
@@ -879,7 +954,10 @@ module.exports = {
   Events,
   Permissions,
   describeSubscriptions,
+  describeCommands,
   dispatchEvent,
   dispatchFilter,
   dispatchHttp,
+  dispatchTabContent,
+  dispatchPageContent,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owncast/plugin-sdk",
-  "version": "0.4.2",
+  "version": "0.6.0",
   "description": "SDK for authoring Owncast plugins in JavaScript",
   "license": "MIT",
   "author": "Owncast",

package/scripts/postinstall.js

@@ -1,11 +1,14 @@
 #!/usr/bin/env node
-// Downloads per-platform tooling into <sdk>/bin/.cache so the build CLI
-// finds it without polluting the user's system:
+// Downloads the prebuilt host binaries into <sdk>/bin/.cache so `owncast-plugin
+// test` / `serve` work without polluting the user's system:
 //
-//   - extism-js                 , JS → wasm compiler (extism/js-pdk releases)
-//   - wasm-merge, wasm-opt, lib , binaryen post-processing (WebAssembly/binaryen releases)
 //   - owncast-plugin-test/serve , scenario runner + dev server (this repo's releases)
 //
+// That's all an author needs: plugins ship source and run on the interpreter
+// engine the host already embeds, so the wasm compiler toolchain (extism-js,
+// binaryen) is NOT downloaded here — it's a maintainer-only dependency of the
+// engine build (see engines/install-toolchain.mjs).
+//
 // PoC scope: linux-x86_64 + darwin-arm64 + darwin-x86_64 covered.
 // owncast-plugin-test/serve downloads gracefully skip if the matching
 // release asset isn't published yet, dev builds can substitute their own
@@ -15,27 +18,74 @@ const fs = require("fs");
 const path = require("path");
 const https = require("https");
 const zlib = require("zlib");
-const { execFileSync } = require("child_process");
 
-const EXTISM_JS_VERSION = "v1.6.0";
-const BINARYEN_VERSION = "version_119";
 const HOST_BINARIES_REPO = "owncast/plugin-sdk";
 
-// The host binaries (owncast-plugin-test/serve) are cut once per MINOR release
-// (a vX.Y.0 git tag); patch releases are JS-only fixes that ride on the same
-// runtime. Deriving the download tag straight from the npm version therefore
-// 404s on every patch (e.g. 0.4.1 has no v0.4.1 binaries), which silently
-// broke `npm test`. Zero the patch component so a patch release fetches its
-// minor's binaries. Override with OWNCAST_PLUGIN_HOST_BINARIES_VERSION (with or
-// without a leading "v") if you ever need a specific tag.
-function hostBinariesVersion() {
+// The host binaries (owncast-plugin-test/serve) implement the host-function
+// contract that the bundled JS runtime imports. That contract is additive
+// within a major version — host functions are only ever added, never removed or
+// renamed (a removal is a breaking change that requires a major bump) — so the
+// NEWEST published binary is compatible with every plugin runtime. We therefore
+// fetch the latest release tag rather than deriving one from the npm version.
+//
+// This keeps the binary in lockstep with `@owncast/plugin-sdk@^x` (which npm
+// already floats to the newest compatible runtime) and fixes the old "zero the
+// patch" guess: that fetched v<major>.<minor>.0, which 404'd on JS-only patches
+// and — when a host change shipped in a patch (e.g. timer support in 0.4.2) —
+// fetched a binary too old to satisfy the runtime's imports, breaking
+// `npm test`.
+//
+// Override with OWNCAST_PLUGIN_HOST_BINARIES_VERSION (with or without a leading
+// "v") to pin a specific tag, e.g. in CI or when bisecting.
+function latestReleaseTag() {
+  return new Promise((resolve, reject) => {
+    https
+      .get(
+        `https://api.github.com/repos/${HOST_BINARIES_REPO}/releases/latest`,
+        {
+          headers: {
+            "User-Agent": "owncast-plugin-sdk-postinstall",
+            Accept: "application/vnd.github+json",
+          },
+        },
+        (res) => {
+          if (res.statusCode !== 200) {
+            res.resume();
+            return reject(new Error(`HTTP ${res.statusCode}`));
+          }
+          let body = "";
+          res.on("data", (c) => (body += c));
+          res.on("end", () => {
+            try {
+              const tag = JSON.parse(body).tag_name;
+              if (!tag) return reject(new Error("no tag_name in response"));
+              resolve(tag);
+            } catch (err) {
+              reject(err);
+            }
+          });
+        },
+      )
+      .on("error", reject);
+  });
+}
+
+async function resolveHostBinariesVersion() {
   const override = process.env.OWNCAST_PLUGIN_HOST_BINARIES_VERSION;
-  if (override) return override.replace(/^v/, "");
-  const pkg = require("../package.json").version; // e.g. "0.4.1"
-  const [major, minor] = pkg.split(".");
-  return `${major}.${minor}.0`;
+  if (override) return override.replace(/^v/i, "");
+  try {
+    return (await latestReleaseTag()).replace(/^v/i, "");
+  } catch (e) {
+    // Offline or API error: best-effort fall back to this package's own
+    // version. The download below 404-skips gracefully if no such release.
+    const pkg = require("../package.json").version;
+    console.warn(
+      `[plugin-sdk] could not resolve latest host-binary release ` +
+        `(${e.message}); falling back to v${pkg}`,
+    );
+    return pkg;
+  }
 }
-const HOST_BINARIES_VERSION = hostBinariesVersion();
 
 const platform = process.platform;
 const arch = process.arch;
@@ -48,30 +98,7 @@ function platformKey() {
   throw new Error(`unsupported platform: ${platform}/${arch}`);
 }
 
-function extismJsURL() {
-  // extism-js release naming uses different conventions per OS.
-  const map = {
-    "linux-x86_64": `extism-js-x86_64-linux-${EXTISM_JS_VERSION}.gz`,
-    "linux-aarch64": `extism-js-aarch64-linux-${EXTISM_JS_VERSION}.gz`,
-    "darwin-x86_64": `extism-js-x86_64-macos-${EXTISM_JS_VERSION}.gz`,
-    "darwin-arm64": `extism-js-aarch64-macos-${EXTISM_JS_VERSION}.gz`,
-  };
-  const file = map[platformKey()];
-  return `https://github.com/extism/js-pdk/releases/download/${EXTISM_JS_VERSION}/${file}`;
-}
-
-function binaryenURL() {
-  const map = {
-    "linux-x86_64": `binaryen-${BINARYEN_VERSION}-x86_64-linux.tar.gz`,
-    "linux-aarch64": `binaryen-${BINARYEN_VERSION}-aarch64-linux.tar.gz`,
-    "darwin-x86_64": `binaryen-${BINARYEN_VERSION}-x86_64-macos.tar.gz`,
-    "darwin-arm64": `binaryen-${BINARYEN_VERSION}-arm64-macos.tar.gz`,
-  };
-  const file = map[platformKey()];
-  return `https://github.com/WebAssembly/binaryen/releases/download/${BINARYEN_VERSION}/${file}`;
-}
-
-function hostBinaryURL(name) {
+function hostBinaryURL(name, version) {
   // Per-platform asset naming matches Go's GOOS-GOARCH convention so the
   // release CI can `go build` once per matrix entry without renaming.
   const map = {
@@ -81,7 +108,7 @@ function hostBinaryURL(name) {
     "darwin-arm64": "darwin-arm64",
   };
   const suffix = map[platformKey()];
-  return `https://github.com/${HOST_BINARIES_REPO}/releases/download/v${HOST_BINARIES_VERSION}/${name}-${suffix}`;
+  return `https://github.com/${HOST_BINARIES_REPO}/releases/download/v${version}/${name}-${suffix}`;
 }
 
 function download(url, dest) {
@@ -105,65 +132,39 @@ async function main() {
   const cacheDir = path.join(__dirname, "..", "bin", ".cache");
   fs.mkdirSync(cacheDir, { recursive: true });
 
-  const extismDest = path.join(cacheDir, "extism-js");
-  if (!fs.existsSync(extismDest)) {
-    const gz = path.join(cacheDir, "extism-js.gz");
-    console.log(`[plugin-sdk] downloading extism-js ${EXTISM_JS_VERSION}...`);
-    await download(extismJsURL(), gz);
-    const buf = zlib.gunzipSync(fs.readFileSync(gz));
-    fs.writeFileSync(extismDest, buf);
-    fs.chmodSync(extismDest, 0o755);
-    fs.unlinkSync(gz);
-  }
-
-  const wasmMergeDest = path.join(cacheDir, "wasm-merge");
-  const wasmOptDest = path.join(cacheDir, "wasm-opt");
-  if (!fs.existsSync(wasmMergeDest) || !fs.existsSync(wasmOptDest)) {
-    const tar = path.join(cacheDir, "binaryen.tar.gz");
-    console.log(`[plugin-sdk] downloading binaryen ${BINARYEN_VERSION}...`);
-    await download(binaryenURL(), tar);
-    execFileSync("tar", ["xzf", tar, "-C", cacheDir]);
-    const extracted = path.join(cacheDir, `binaryen-${BINARYEN_VERSION}`);
-    fs.copyFileSync(path.join(extracted, "bin", "wasm-merge"), wasmMergeDest);
-    fs.copyFileSync(path.join(extracted, "bin", "wasm-opt"), wasmOptDest);
-    fs.chmodSync(wasmMergeDest, 0o755);
-    fs.chmodSync(wasmOptDest, 0o755);
-    // copy lib too, wasm-opt links against libbinaryen.so on linux
-    const libSrc = path.join(extracted, "lib");
-    if (fs.existsSync(libSrc)) {
-      fs.cpSync(libSrc, path.join(cacheDir, "lib"), { recursive: true });
-    }
-    fs.rmSync(extracted, { recursive: true });
-    fs.unlinkSync(tar);
-  }
-
   // owncast-plugin-test + owncast-plugin-serve, built from this repo's
   // host-runtime/ Go sources, published as gzipped release assets on
   // github.com/owncast/plugin-sdk (roughly halves the download). Skip silently
   // if the release doesn't exist yet (dev environments running against a
   // not-yet-released SDK version can substitute their own via
   // tools/bootstrap.sh).
-  for (const binary of ["owncast-plugin-test", "owncast-plugin-serve"]) {
-    const dest = path.join(cacheDir, binary);
-    if (fs.existsSync(dest)) continue;
-    const gz = dest + ".gz";
-    try {
-      console.log(
-        `[plugin-sdk] downloading ${binary} ${HOST_BINARIES_VERSION}...`,
-      );
-      await download(hostBinaryURL(binary) + ".gz", gz);
-      fs.writeFileSync(dest, zlib.gunzipSync(fs.readFileSync(gz)));
-      fs.chmodSync(dest, 0o755);
-      fs.unlinkSync(gz);
-    } catch (e) {
-      // 404 is expected before the first release; other errors get a soft
-      // warning so the user sees them but the install still succeeds.
-      console.warn(
-        `[plugin-sdk] could not fetch ${binary}: ${e.message}\n` +
-          `  Build locally via tools/bootstrap.sh, or use the latest GitHub release.`,
-      );
-      // Make sure no partial files are left behind.
-      for (const p of [gz, dest]) if (fs.existsSync(p)) fs.unlinkSync(p);
+  const hostBinaries = ["owncast-plugin-test", "owncast-plugin-serve"];
+  const missing = hostBinaries.filter(
+    (b) => !fs.existsSync(path.join(cacheDir, b)),
+  );
+  if (missing.length) {
+    // Resolve the version only when something needs downloading, so a repeat
+    // install with a populated cache never hits the network.
+    const version = await resolveHostBinariesVersion();
+    for (const binary of missing) {
+      const dest = path.join(cacheDir, binary);
+      const gz = dest + ".gz";
+      try {
+        console.log(`[plugin-sdk] downloading ${binary} v${version}...`);
+        await download(hostBinaryURL(binary, version) + ".gz", gz);
+        fs.writeFileSync(dest, zlib.gunzipSync(fs.readFileSync(gz)));
+        fs.chmodSync(dest, 0o755);
+        fs.unlinkSync(gz);
+      } catch (e) {
+        // 404 is expected before the first release; other errors get a soft
+        // warning so the user sees them but the install still succeeds.
+        console.warn(
+          `[plugin-sdk] could not fetch ${binary}: ${e.message}\n` +
+            `  Build locally via tools/bootstrap.sh, or use the latest GitHub release.`,
+        );
+        // Make sure no partial files are left behind.
+        for (const p of [gz, dest]) if (fs.existsSync(p)) fs.unlinkSync(p);
+      }
     }
   }
 

package/testing.js

@@ -10,9 +10,9 @@
 //
 //   const { runScenarios } = require("@owncast/plugin-sdk/testing");
 //
-//   const chat = (user, body) => ({
+//   const chat = (name, body) => ({
 //     event: "chat.message.received",
-//     payload: { id: "1", user, body, timestamp: "2024-01-01T00:00:00Z" },
+//     payload: { id: "1", user: { id: name, displayName: name }, body, timestamp: "2024-01-01T00:00:00Z" },
 //   });
 //
 //   runScenarios([