@owncast/plugin-sdk 0.3.1 → 0.4.0

package/bin/owncast-plugin.js

@@ -238,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");
@@ -296,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));
@@ -310,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("/");
@@ -329,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.1",
+  "version": "0.4.0",
   "description": "SDK for authoring Owncast plugins in JavaScript",
   "license": "MIT",
   "author": "Owncast",