@owncast/plugin-sdk 0.5.0 → 0.10.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owncast/plugin-sdk",
-  "version": "0.5.0",
+  "version": "0.10.1",
   "description": "SDK for authoring Owncast plugins in JavaScript",
   "license": "MIT",
   "author": "Owncast",
@@ -28,6 +28,7 @@
   "files": [
     "index.js",
     "index.d.ts",
+    "slug.js",
     "testing.js",
     "bin/owncast-plugin.js",
     "scripts/postinstall.js"

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,23 +18,20 @@ 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) 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
+// 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) —
+// 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`.
 //
@@ -98,29 +98,6 @@ 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, version) {
   // Per-platform asset naming matches Go's GOOS-GOARCH convention so the
   // release CI can `go build` once per matrix entry without renaming.
@@ -155,38 +132,6 @@ 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
@@ -211,7 +156,7 @@ async function main() {
         fs.chmodSync(dest, 0o755);
         fs.unlinkSync(gz);
       } catch (e) {
-        // 404 is expected before the first release; other errors get a soft
+        // 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` +

package/slug.js

@@ -0,0 +1,26 @@
+// slugify mirrors the host's Go slugify and the Python SDK's: ASCII letters and
+// digits pass through lowercased, everything else collapses to a single hyphen,
+// and trailing hyphens are trimmed. Shared by the build CLI and the JS test API
+// so a manifest that omits `slug` resolves to the same `<slug>.js` artifact name
+// everywhere. Non-ASCII names (e.g. "Café") degrade noisily (-> "caf"), so pin
+// `slug` in the manifest for accented or non-Latin display names.
+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(/-+$/, "");
+}
+
+module.exports = { slugify };

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([
@@ -28,35 +28,12 @@ const fs = require("fs");
 const os = require("os");
 const path = require("path");
 const { execFileSync } = require("child_process");
+const { slugify } = require("./slug");
 
 // Find the directory holding the owncast-plugin-test binary. Check for that
 // binary specifically (not just any toolchain file) so we correctly fall
 // through to the dev tools/ dir when postinstall has only fetched part of the
 // toolchain (e.g., on a not-yet-released SDK version).
-// slugifyForTest mirrors the slugify in the build CLI + host SDKs so
-// this entrypoint can locate the .wasm file when a manifest omits
-// `slug`. ASCII letters and digits pass through lowercased;
-// everything else collapses to a single hyphen; trailing hyphens are
-// trimmed.
-function slugifyForTest(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(/-+$/, "");
-}
-
 function findCacheDir() {
   const candidates = [
     path.join(__dirname, "bin", ".cache"), // installed under node_modules
@@ -81,7 +58,7 @@ function findCacheDir() {
  * Sets `process.exitCode` to non-zero if any scenario failed (never resets a
  * previously-failed code), and returns true on success / false on failure
  * WITHOUT exiting the process. That lets one node process run several test
- * files in a row (see runScenarioFiles); the process ends with the right code
+ * files in a row (see runScenarioFiles). The process ends with the right code
  * once the event loop drains.
  *
  * @param {Array<object>} scenarios, scenario objects: { name, given?, events, expect? }
@@ -113,20 +90,22 @@ function runScenarios(scenarios, opts = {}) {
     console.error("manifest.name is required");
     return fail(2);
   }
-  // wasm + symlink filenames key off slug (the identifier), not the
-  // display name. Derive the slug here the same way the build CLI
-  // does so this entrypoint works on manifests that omit `slug`.
-  const slug = manifest.slug || slugifyForTest(manifest.name);
+  // The built artifact + symlink filenames key off slug (the identifier), not
+  // the display name. Derive the slug here the same way the build CLI does so
+  // this entrypoint works on manifests that omit `slug`.
+  const slug = manifest.slug || slugify(manifest.name);
   if (!slug) {
     console.error(
       `could not derive slug from manifest.name ${JSON.stringify(manifest.name)}; set manifest.slug explicitly`,
     );
     return fail(2);
   }
-  const wasmPath = path.join(cwd, `${slug}.wasm`);
-  if (!fs.existsSync(wasmPath)) {
+  // Plugins ship as source: `owncast-plugin build` bundles src/plugin.{js,ts}
+  // into <slug>.js, which is what the host loads. (`npm test` builds first.)
+  const scriptPath = path.join(cwd, `${slug}.js`);
+  if (!fs.existsSync(scriptPath)) {
     console.error(
-      `${slug}.wasm not found at ${wasmPath}, run \`owncast-plugin package\` first`,
+      `${slug}.js not found at ${scriptPath}, run \`owncast-plugin build\` first`,
     );
     return fail(2);
   }
@@ -141,32 +120,20 @@ function runScenarios(scenarios, opts = {}) {
     return fail(2);
   }
 
-  // Build a temp project dir that links to the wasm + manifest and contains
-  // only the scenarios we're running. The binary will auto-discover them.
+  // Build a temp project dir that links to the built script + manifest and
+  // contains only the scenarios we're running. The binary auto-discovers them.
   const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "owncast-plugin-test-"));
   try {
     fs.symlinkSync(manifestPath, path.join(tmp, "plugin.manifest.json"));
-    fs.symlinkSync(wasmPath, path.join(tmp, `${slug}.wasm`));
+    fs.symlinkSync(scriptPath, path.join(tmp, `${slug}.js`));
     fs.mkdirSync(path.join(tmp, "__tests__"));
     fs.writeFileSync(
       path.join(tmp, "__tests__", "scenarios.test.json"),
       JSON.stringify(scenarios, null, 2),
     );
 
-    // Match the build CLI: extism-js (and its wasm-merge/wasm-opt
-    // children) needs LD_LIBRARY_PATH on Linux and DYLD_LIBRARY_PATH +
-    // DYLD_FALLBACK_LIBRARY_PATH on macOS to find libbinaryen via
-    // @rpath. Setting all three is safe on both OSes; the inactive
-    // ones are ignored.
-    const libDir = path.join(cache, "lib");
-    const env = {
-      ...process.env,
-      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"}`,
-    };
     try {
-      execFileSync(bin, [tmp], { stdio: "inherit", env });
+      execFileSync(bin, [tmp], { stdio: "inherit" });
     } catch (e) {
       return fail(typeof e.status === "number" ? e.status : 1);
     }