@owncast/plugin-sdk 0.3.0 → 0.4.0

package/bin/owncast-plugin.js

@@ -25,6 +25,27 @@ 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.
@@ -106,10 +127,7 @@ function runBinary(name, args) {
     );
     process.exit(1);
   }
-  const env = {
-    ...process.env,
-    LD_LIBRARY_PATH: `${path.join(cache, "lib")}:${process.env.LD_LIBRARY_PATH || ""}`,
-  };
+  const env = toolchainEnv(cache);
   try {
     execFileSync(bin, args.length > 0 ? args : [process.cwd()], {
       stdio: "inherit",
@@ -212,11 +230,7 @@ module.exports = { register, on_event, on_filter, on_http_request };
       `extism-js not found at ${extismJs}, run \`npm install\` to fetch the toolchain`,
     );
   }
-  const env = {
-    ...process.env,
-    PATH: `${cache}:${process.env.PATH}`,
-    LD_LIBRARY_PATH: `${path.join(cache, "lib")}:${process.env.LD_LIBRARY_PATH || ""}`,
-  };
+  const env = toolchainEnv(cache);
 
   const wasmOut = path.join(cwd, `${slug}.wasm`);
   execFileSync(extismJs, [bundledJS, "-i", dts, "-o", wasmOut], {
@@ -224,50 +238,18 @@ module.exports = { register, on_event, on_filter, on_http_request };
     env,
   });
 
-  // If the project ships static assets in ./assets/, mirror them to the
-  // canonical deployment layout (<name>-assets/) so plugin.Server finds them
-  // without per-deployment renames. We use a symlink so edits to assets/
-  // show up live during dev (no rebuild needed for HTML/CSS changes).
-  const assetsSrc = path.join(cwd, "assets");
-  if (fs.existsSync(assetsSrc) && fs.statSync(assetsSrc).isDirectory()) {
-    const assetsDest = path.join(cwd, `${slug}-assets`);
-    let needsLink = true;
-    // Use lstatSync (not existsSync), existsSync follows symlinks and
-    // returns false for a dangling link, but the link's inode is still
-    // there and would make symlinkSync below fail with EEXIST. lstatSync
-    // sees the link itself regardless of whether its target resolves.
-    let st;
-    try {
-      st = fs.lstatSync(assetsDest);
-    } catch {
-      // path doesn't exist at all, fall through to create it.
-    }
-    if (st) {
-      let target;
-      if (st.isSymbolicLink()) {
-        // realpathSync throws on dangling links; treat that as "doesn't
-        // match, replace it" rather than letting it abort the build.
-        try {
-          target = fs.realpathSync(assetsDest);
-        } catch {}
-      }
-      if (target && target === fs.realpathSync(assetsSrc)) {
-        needsLink = false;
-      } else {
-        fs.rmSync(assetsDest, { recursive: true, force: true });
-      }
-    }
-    if (needsLink) {
-      fs.symlinkSync(path.resolve(assetsSrc), assetsDest, "dir");
-    }
-  }
+  // 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)}`);
 }
 
 // `owncast-plugin package`, bundle the project into a single .ocpkg file
-// (zip archive with plugin.manifest.json, plugin.wasm, and optional assets/).
-// Builds the wasm first if it doesn't exist.
+// (zip archive with plugin.manifest.json, plugin.wasm, and optional
+// public/ and assets/ directories). Builds the wasm first if it
+// doesn't exist.
 async function packageMain() {
   const cwd = process.cwd();
   const manifestPath = path.join(cwd, "plugin.manifest.json");
@@ -282,6 +264,7 @@ async function packageMain() {
     await buildMain();
   }
 
+  const publicDir = path.join(cwd, "public");
   const assetsDir = path.join(cwd, "assets");
   const zip = new JSZip();
   zip.file("plugin.manifest.json", fs.readFileSync(manifestPath));
@@ -296,6 +279,26 @@ async function packageMain() {
     zip.file("icon.png", fs.readFileSync(iconPath));
     fileCount++;
   }
+  // 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
+  // http.serve permission. The filename is fixed for simplicity.
+  const instructionsPath = path.join(cwd, "INSTRUCTIONS.md");
+  if (fs.existsSync(instructionsPath) && fs.statSync(instructionsPath).isFile()) {
+    zip.file("INSTRUCTIONS.md", fs.readFileSync(instructionsPath));
+    fileCount++;
+  }
+  // public/ → /plugins/<slug>/<path>, served by the host.
+  if (fs.existsSync(publicDir) && fs.statSync(publicDir).isDirectory()) {
+    for (const file of walkFiles(publicDir)) {
+      const rel = path.relative(publicDir, file).split(path.sep).join("/");
+      zip.file(`public/${rel}`, fs.readFileSync(file));
+      fileCount++;
+    }
+  }
+  // assets/ → host reads internally for manifest fields that inline
+  // file contents (styles, scripts, extraPageContent). Not served at
+  // a URL.
   if (fs.existsSync(assetsDir) && fs.statSync(assetsDir).isDirectory()) {
     for (const file of walkFiles(assetsDir)) {
       const rel = path.relative(assetsDir, file).split(path.sep).join("/");
@@ -315,12 +318,29 @@ async function packageMain() {
   console.log(
     `packaged ${path.relative(cwd, outPath)} (${sizeKb} KB, ${fileCount} files)`,
   );
+
+  // Drop the intermediate <slug>.wasm 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
+  // runs on a successful package so a mid-pipeline failure leaves the
+  // last good build in place for debugging.
+  try {
+    fs.unlinkSync(wasmPath);
+  } 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}`);
+    }
+  }
 }
 
 function* walkFiles(dir) {
   for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-    // Resolve symlinks so the assets/ → <name>-assets/ link the build CLI
-    // makes doesn't cause us to skip files. statSync follows.
+    // statSync (not lstatSync) so a symlinked file or directory in
+    // the source tree resolves to its target and we read its contents
+    // rather than skipping it.
     const full = path.join(dir, entry.name);
     let info;
     try {

package/package.json

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

package/testing.js

@@ -141,9 +141,17 @@ function runScenarios(scenarios, opts = {}) {
       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: `${path.join(cache, "lib")}:${process.env.LD_LIBRARY_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"}`,
     };
     try {
       execFileSync(bin, [tmp], { stdio: "inherit", env });