@owncast/plugin-sdk 0.1.0 → 0.3.0

package/scripts/postinstall.js

@@ -2,13 +2,13 @@
 // Downloads per-platform tooling into <sdk>/bin/.cache so the build CLI
 // finds it 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)
+//   - 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)
 //
 // 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
+// release asset isn't published yet, dev builds can substitute their own
 // via tools/bootstrap.sh.
 
 const fs = require("fs");
@@ -41,7 +41,7 @@ function extismJsURL() {
     "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`
+    "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}`;
@@ -52,7 +52,7 @@ function binaryenURL() {
     "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`
+    "darwin-arm64": `binaryen-${BINARYEN_VERSION}-arm64-macos.tar.gz`,
   };
   const file = map[platformKey()];
   return `https://github.com/WebAssembly/binaryen/releases/download/${BINARYEN_VERSION}/${file}`;
@@ -65,7 +65,7 @@ function hostBinaryURL(name) {
     "linux-x86_64": "linux-amd64",
     "linux-aarch64": "linux-arm64",
     "darwin-x86_64": "darwin-amd64",
-    "darwin-arm64": "darwin-arm64"
+    "darwin-arm64": "darwin-arm64",
   };
   const suffix = map[platformKey()];
   return `https://github.com/${HOST_BINARIES_REPO}/releases/download/v${HOST_BINARIES_VERSION}/${name}-${suffix}`;
@@ -75,8 +75,10 @@ function download(url, dest) {
   return new Promise((resolve, reject) => {
     const req = (u) =>
       https.get(u, (res) => {
-        if (res.statusCode === 302 || res.statusCode === 301) return req(res.headers.location);
-        if (res.statusCode !== 200) return reject(new Error(`HTTP ${res.statusCode} for ${u}`));
+        if (res.statusCode === 302 || res.statusCode === 301)
+          return req(res.headers.location);
+        if (res.statusCode !== 200)
+          return reject(new Error(`HTTP ${res.statusCode} for ${u}`));
         const out = fs.createWriteStream(dest);
         res.pipe(out);
         out.on("finish", () => out.close(resolve));
@@ -113,7 +115,7 @@ async function main() {
     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
+    // 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 });
@@ -122,7 +124,7 @@ async function main() {
     fs.unlinkSync(tar);
   }
 
-  // owncast-plugin-test + owncast-plugin-serve — built from this repo's
+  // 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
@@ -133,7 +135,9 @@ async function main() {
     if (fs.existsSync(dest)) continue;
     const gz = dest + ".gz";
     try {
-      console.log(`[plugin-sdk] downloading ${binary} ${HOST_BINARIES_VERSION}...`);
+      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);
@@ -143,7 +147,7 @@ async function main() {
       // 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.`
+          `  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

@@ -0,0 +1,158 @@
+// JavaScript test API for Owncast plugins.
+//
+// Lets authors write their __tests__/*.test.js with the full ergonomics of JS
+//, loops, helpers, fixtures, computed payloads, shared setup, instead of
+// hand-authoring static JSON. Each call to `runScenarios([...])` invokes the
+// same `owncast-plugin-test` host binary the JSON scenarios use, so this is
+// purely a more pleasant authoring layer over the same execution.
+//
+// Quick start:
+//
+//   const { runScenarios } = require("@owncast/plugin-sdk/testing");
+//
+//   const chat = (user, body) => ({
+//     event: "chat.message.received",
+//     payload: { id: "1", user, body, timestamp: "2024-01-01T00:00:00Z" },
+//   });
+//
+//   runScenarios([
+//     { name: "greets users",   events: [chat("alice", "hi")],   expect: { chatSends: ["hello, alice!"] } },
+//     { name: "ignores others", events: [chat("bob", "morning")], expect: { chatSends: [] } },
+//   ]);
+//
+// Each scenario object has the same shape as a JSON scenario file:
+//   { name, given?, events: [...], expect?: {...} }
+// See the Plugin Author Guide for every assertion field.
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { execFileSync } = require("child_process");
+
+// 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
+    path.join(__dirname, "..", "..", "tools"), // dev fallback (repo root tools/)
+  ];
+  for (const c of candidates) {
+    if (fs.existsSync(path.join(c, "owncast-plugin-test"))) return c;
+  }
+  return candidates[0];
+}
+
+/**
+ * Run an array of scenarios against the loaded plugin via the
+ * `owncast-plugin-test` host binary.
+ *
+ * The binary takes a project directory and auto-discovers
+ * `__tests__/*.test.json`. To avoid colliding with any JSON scenarios you
+ * might also have in the project, this function sets up a temporary project
+ * dir that links to your manifest + wasm and contains only the generated
+ * scenarios it's running.
+ *
+ * Exits the process with status 0 if every scenario passed, non-zero otherwise.
+ *
+ * @param {Array<object>} scenarios, scenario objects: { name, given?, events, expect? }
+ * @param {object}        [opts]
+ * @param {string}        [opts.cwd], plugin project directory (default: process.cwd())
+ */
+function runScenarios(scenarios, opts = {}) {
+  if (!Array.isArray(scenarios) || scenarios.length === 0) {
+    console.error("runScenarios: no scenarios provided");
+    process.exit(2);
+  }
+
+  const cwd = opts.cwd ? path.resolve(opts.cwd) : process.cwd();
+  const manifestPath = path.join(cwd, "plugin.manifest.json");
+  if (!fs.existsSync(manifestPath)) {
+    console.error(`plugin.manifest.json not found in ${cwd}`);
+    process.exit(2);
+  }
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+  if (!manifest.name) {
+    console.error("manifest.name is required");
+    process.exit(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);
+  if (!slug) {
+    console.error(
+      `could not derive slug from manifest.name ${JSON.stringify(manifest.name)}; set manifest.slug explicitly`,
+    );
+    process.exit(2);
+  }
+  const wasmPath = path.join(cwd, `${slug}.wasm`);
+  if (!fs.existsSync(wasmPath)) {
+    console.error(
+      `${slug}.wasm not found at ${wasmPath}, run \`owncast-plugin package\` first`,
+    );
+    process.exit(2);
+  }
+
+  const cache = findCacheDir();
+  const bin = path.join(cache, "owncast-plugin-test");
+  if (!fs.existsSync(bin)) {
+    console.error(
+      `owncast-plugin-test not found at ${bin}\n` +
+        `Reinstall @owncast/plugin-sdk to fetch the host toolchain (postinstall handles it).`,
+    );
+    process.exit(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.
+  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.mkdirSync(path.join(tmp, "__tests__"));
+    fs.writeFileSync(
+      path.join(tmp, "__tests__", "scenarios.test.json"),
+      JSON.stringify(scenarios, null, 2),
+    );
+
+    const env = {
+      ...process.env,
+      LD_LIBRARY_PATH: `${path.join(cache, "lib")}:${process.env.LD_LIBRARY_PATH || ""}`,
+    };
+    try {
+      execFileSync(bin, [tmp], { stdio: "inherit", env });
+    } catch (e) {
+      process.exit(typeof e.status === "number" ? e.status : 1);
+    }
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+module.exports = { runScenarios };