@owncast/plugin-sdk 0.4.1 → 0.4.2

package/bin/owncast-plugin.js

@@ -366,6 +366,13 @@ function generateInterface(manifest) {
 
   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");
@@ -424,6 +431,7 @@ function generateInterface(manifest) {
     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");

package/index.d.ts

@@ -1,7 +1,18 @@
-/** Built-in chat message payload. */
+/**
+ * Built-in chat message payload (`chat.message.received` and the chat filter).
+ *
+ * `user` carries the full sender identity — use `user.id` for stable per-user
+ * state and `user.scopes` (e.g. `"MODERATOR"`) for reliable, non-spoofable
+ * moderation gating rather than matching on the display name. `clientId`
+ * identifies the originating connection; pass it to `owncast.chat.sendTo` (or
+ * `owncast.chat.replyTo(msg, …)`) to whisper a reply back to the sender.
+ *
+ * `user` is undefined for the rare message with no associated account.
+ */
 export interface ChatMessage {
   id: string;
-  user: string;
+  user?: ChatUser;
+  clientId?: number;
   body: string;
   timestamp: string;
 }
@@ -117,6 +128,7 @@ export const Events: {
   readonly StreamTitleChanged: "stream.title.changed";
   readonly SseConnect: "sse.connect";
   readonly SseDisconnect: "sse.disconnect";
+  readonly Tick: "tick";
   readonly FediverseFollow: "fediverse.follow";
   readonly FediverseLike: "fediverse.like";
   readonly FediverseRepost: "fediverse.repost";
@@ -197,6 +209,12 @@ export interface SocialHandle {
   icon?: string;
 }
 
+/** A custom chat emote from owncast.server.emotes(). */
+export interface Emote {
+  name: string; // the `:code:` chat clients substitute
+  url: string; // image the emote renders to
+}
+
 export interface FederationInfo {
   enabled: boolean;
   username?: string;
@@ -278,6 +296,12 @@ export interface SSEConnectionEvent {
   user?: ChatUser;
 }
 
+/** Payload for the once-a-second tick event (onTick). `now` is the host
+ *  wall-clock time in unix milliseconds when the tick fired. */
+export interface TickEvent {
+  now: number;
+}
+
 export interface PluginDef {
   /** Notification handler for chat messages. Fire-and-forget. */
   onChatMessage?(msg: ChatMessage): void | Promise<void>;
@@ -309,6 +333,10 @@ export interface PluginDef {
    *  the matching onSseConnect). Requires the `http.sse` permission. */
   onSseDisconnect?(event: SSEConnectionEvent): void | Promise<void>;
 
+  /** Fires once a second for periodic work. `now` is the host wall-clock time
+   *  in unix milliseconds. Defining this opts the plugin into the tick. */
+  onTick?(event: TickEvent): void | Promise<void>;
+
   /** Someone on the fediverse followed the streamer's account. */
   onFediverseFollow?(event: FediverseEngagement): void | Promise<void>;
   /** Someone on the fediverse liked a streamer post / federated stream announcement. */
@@ -337,6 +365,62 @@ export interface PluginDef {
 
 export function definePlugin(def: PluginDef): PluginDef;
 
+/** What a command handler receives. */
+export interface CommandContext {
+  /** The originating chat message. */
+  msg: ChatMessage;
+  /** The sender (same as `msg.user`). */
+  user?: ChatUser;
+  /** The canonical command name that matched (not the alias used). */
+  command: string;
+  /** Whitespace-split arguments after the command word. */
+  args: string[];
+  /** The raw argument string (everything after the command word, trimmed). */
+  argString: string;
+  /** Post a public reply as the plugin's chat bot. */
+  reply(text: string): void;
+  /** Whisper a reply to the sender; falls back to a public post if their
+   *  connection is unknown. */
+  replyPrivately(text: string): void;
+}
+
+/** One command in a {@link defineCommands} table. */
+export interface CommandDefinition {
+  /** Alternate names that invoke this command. */
+  aliases?: string[];
+  /** Only allow senders whose scopes include "MODERATOR". */
+  modOnly?: boolean;
+  /** Minimum milliseconds between invocations per user (clocked off
+   *  `msg.timestamp`). */
+  cooldownMs?: number;
+  /** Invoked when the command runs. */
+  run(ctx: CommandContext): void;
+  /** Invoked instead of `run` when a non-moderator calls a `modOnly` command. */
+  onDenied?(ctx: CommandContext): void;
+  /** Invoked instead of `run` when the per-user cooldown hasn't elapsed. */
+  onCooldown?(ctx: CommandContext): void;
+}
+
+export interface CommandsConfig {
+  /** Command prefix. Default `"!"`. */
+  prefix?: string;
+  /** Match command names case-sensitively. Default false. */
+  caseSensitive?: boolean;
+  commands: Record<string, CommandDefinition>;
+  /** Fallback when a prefixed message matches no command. */
+  onUnknown?(ctx: CommandContext): void;
+  /** Default denied/cooldown handlers, used when a command omits its own. */
+  onDenied?(ctx: CommandContext): void;
+  onCooldown?(ctx: CommandContext): void;
+}
+
+/** Build a chat-command router (prefix parsing, aliases, per-user cooldowns,
+ *  moderator gating). Feed the returned function a `ChatMessage`; it returns
+ *  true when the message was a command (even if gated), false otherwise. */
+export function defineCommands(
+  config: CommandsConfig,
+): (msg: ChatMessage) => boolean;
+
 /** Typed wrappers around the Owncast host. Each method throws if the
  *  corresponding permission was not declared in plugin.manifest.json. */
 export const owncast: {
@@ -350,8 +434,14 @@ export const owncast: {
      *  responsible for escaping any untrusted content. Same `chat.send`
      *  permission as the other send variants. */
     system(body: string): void;
-    /** Private message to one chat client. */
+    /** Private message to one chat client. Requires `chat.send`. */
     sendTo(clientId: number | bigint, text: string): void;
+    /** Whisper a reply back to whoever sent a chat message. Pass the
+     *  `ChatMessage` from `onChatMessage`/`filterChatMessage` (or a bare
+     *  clientId). Returns `false` if the sender's connection is unknown (no
+     *  clientId), so callers can fall back to a public `send`. Requires
+     *  `chat.send`. */
+    replyTo(msg: ChatMessage | number | bigint, text: string): boolean;
     /** Recent chat history (most recent last). Requires `chat.history`.
      *  Default limit is 50; pass a smaller number to get fewer. */
     history(limit?: number): ChatMessage[];
@@ -418,6 +508,20 @@ export const owncast: {
   kv: {
     get(key: string): string | null;
     set(key: string, value: string | number): void;
+    /** Read a JSON value, parsed. Returns `fallback` (default `undefined`)
+     *  when the key is unset or holds invalid JSON. Requires `storage.kv`. */
+    getJSON<T = unknown>(key: string, fallback?: T): T;
+    /** Store a value as JSON. Requires `storage.kv`. */
+    setJSON(key: string, value: unknown): void;
+  };
+  /** Read this plugin's admin-configurable settings, declared under
+   *  `config` in the manifest. Ambient — no permission required. */
+  config: {
+    /** The effective value of a manifest-declared config key (admin override,
+     *  else the declared default), parsed to its declared type. Returns
+     *  `fallback` (default `undefined`) for an unknown key or one with no
+     *  value. */
+    get<T = unknown>(key: string, fallback?: T): T;
   };
   events: {
     emit(eventType: string, payload: unknown): void;
@@ -447,6 +551,20 @@ export const owncast: {
      *  `http.sse` permission. */
     send(channel: string, event: string, data: unknown): void;
   };
+  /** Host-driven timers. The sandbox has no setTimeout; these ask the host to
+   *  call your callback back later (in this instance). No permission required.
+   *  Timers do not survive a plugin reload or host restart. */
+  timer: {
+    /** Run `fn` once after ~`ms` milliseconds. Returns an id for `clear()`.
+     *  Very small delays are clamped up by the host; throws past the
+     *  per-plugin pending-timer cap. */
+    setTimeout(fn: () => void, ms: number): number;
+    /** Run `fn` every ~`ms` milliseconds until `clear()`. The next run is
+     *  scheduled only after the previous one returns. Returns an id. */
+    setInterval(fn: () => void, ms: number): number;
+    /** Cancel a pending timeout or interval by its id. */
+    clear(id: number): void;
+  };
   http: {
     fetch(url: string, opts?: HttpRequestOpts): HttpResponse;
   };
@@ -459,6 +577,8 @@ export const owncast: {
   server: {
     info(): ServerInfo;
     socials(): SocialHandle[];
+    /** Custom chat emotes (`:code:` → image URL) configured on this server. */
+    emotes(): Emote[];
     federation(): FederationInfo;
     tags(): string[];
   };

package/index.js

@@ -7,6 +7,14 @@
 
 let registered = null;
 
+// 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
+// a guest-allocated id the host echoes back. State persists across calls
+// because the plugin instance is reused; timers are dropped on reload.
+let nextTimerId = 1;
+const timerCallbacks = new Map(); // id -> { fn, repeat }
+
 const FilterAction = Object.freeze({
   Pass: "pass",
   Modify: "modify",
@@ -27,6 +35,8 @@ const Events = Object.freeze({
   // SSE connection lifecycle (who connected to / left a plugin's stream)
   SseConnect: "sse.connect",
   SseDisconnect: "sse.disconnect",
+  // Once-a-second tick for periodic work (opt in by defining onTick)
+  Tick: "tick",
   // Fediverse, engagement (metadata only) + inbound posts (with content)
   FediverseFollow: "fediverse.follow",
   FediverseLike: "fediverse.like",
@@ -109,6 +119,8 @@ const HANDLERS = Object.freeze({
   // SSE connection lifecycle
   onSseConnect: { event: Events.SseConnect, kind: HandlerKind.Notify },
   onSseDisconnect: { event: Events.SseDisconnect, kind: HandlerKind.Notify },
+  // Once-a-second tick
+  onTick: { event: Events.Tick, kind: HandlerKind.Notify },
   // Fediverse engagement (actor + target metadata)
   onFediverseFollow: {
     event: Events.FediverseFollow,
@@ -141,6 +153,111 @@ function definePlugin(def) {
   return def;
 }
 
+// defineCommands builds a chat-command router so plugins stop reimplementing
+// prefix parsing, aliases, per-user cooldowns, and moderator gating. It returns
+// a function you feed a ChatMessage (from onChatMessage or filterChatMessage);
+// it parses the command and invokes the matching handler's run(ctx). The return
+// value is true when the message was a command (even if gated), false when it
+// wasn't — so a filter can drop command messages from chat:
+//
+//   const commands = defineCommands({
+//     prefix: "!",
+//     commands: {
+//       uptime: { run: (ctx) => ctx.reply("up!") },
+//       ban: { modOnly: true, cooldownMs: 5000, run: (ctx) => ctx.reply(`bye ${ctx.args[0]}`) },
+//     },
+//   });
+//   module.exports = definePlugin({
+//     onChatMessage: commands,
+//     // or, to hide command messages from chat:
+//     // filterChatMessage: (msg) => (commands(msg) ? filter.drop("command") : filter.pass()),
+//   });
+//
+// run(ctx) receives { msg, user, command, args, argString, reply, replyPrivately }.
+// reply posts publicly; replyPrivately whispers to the sender (falling back to a
+// public post if their connection is unknown). Optional hooks: per-command or
+// top-level onCooldown(ctx) / onDenied(ctx), and a top-level onUnknown(ctx).
+function defineCommands(config) {
+  config = config || {};
+  const prefix = config.prefix || "!";
+  const caseSensitive = !!config.caseSensitive;
+  const norm = (s) => (caseSensitive ? s : s.toLowerCase());
+
+  // Resolve every name and alias to its canonical command definition.
+  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 });
+  }
+
+  // Per-(command,user) cooldown clock, in memory for the plugin's lifetime.
+  const lastRun = new Map();
+
+  return function handle(msg) {
+    const body = (msg && msg.body) || "";
+    if (!body.startsWith(prefix)) return false;
+    const rest = body.slice(prefix.length);
+    const parts = rest.split(/\s+/).filter(Boolean);
+    if (parts.length === 0) return false;
+    const called = parts[0];
+    const args = parts.slice(1);
+    const argString = rest.slice(called.length).trim();
+
+    const ctx = {
+      msg,
+      user: msg && msg.user,
+      command: norm(called),
+      args,
+      argString,
+      reply: (text) => owncast.chat.send(text),
+      replyPrivately: (text) => {
+        if (!owncast.chat.replyTo(msg, text)) owncast.chat.send(text);
+      },
+    };
+
+    const entry = table.get(norm(called));
+    if (!entry) {
+      if (isFn(config.onUnknown)) config.onUnknown(ctx);
+      return false;
+    }
+    const { name, def } = entry;
+    ctx.command = name;
+
+    // Moderator gating: the sender's scopes must include MODERATOR.
+    if (def.modOnly) {
+      const scopes = (msg.user && msg.user.scopes) || [];
+      if (!scopes.includes("MODERATOR")) {
+        if (isFn(def.onDenied)) def.onDenied(ctx);
+        else if (isFn(config.onDenied)) config.onDenied(ctx);
+        return true; // matched a command, but the caller wasn't allowed
+      }
+    }
+
+    // Per-user cooldown, clocked off msg.timestamp so it's deterministic in
+    // tests and independent of any sandbox clock quirks.
+    const cooldownMs = def.cooldownMs || 0;
+    if (cooldownMs > 0) {
+      const userId =
+        (msg.user && msg.user.id) ||
+        (msg.clientId != null ? `c${msg.clientId}` : "anon");
+      const key = `${name}${userId}`;
+      const now = msg.timestamp ? new Date(msg.timestamp).getTime() : 0;
+      const prev = lastRun.get(key);
+      if (now && prev && now - prev < cooldownMs) {
+        if (isFn(def.onCooldown)) def.onCooldown(ctx);
+        else if (isFn(config.onCooldown)) config.onCooldown(ctx);
+        return true;
+      }
+      if (now) lastRun.set(key, now);
+    }
+
+    if (isFn(def.run)) def.run(ctx);
+    return true;
+  };
+}
+
 // Used by the build-generated entry to compute subscriptions for register().
 // Filters can optionally declare a priority via definePlugin({filterPriority}),
 // applied to every filter subscription this plugin owns. Lower = earlier.
@@ -170,8 +287,20 @@ function describeSubscriptions() {
 }
 
 function dispatchEvent(envelope) {
-  if (!registered) return;
   const { eventType, payload } = envelope;
+  // Internal: a host-scheduled timer elapsed. Run the author's callback,
+  // dropping one-shot entries first so a throw still cleans up. Not routed to
+  // user handlers or the `on` map.
+  if (eventType === "timer.fire") {
+    const id = payload && payload.id;
+    const entry = timerCallbacks.get(id);
+    if (entry) {
+      if (!entry.repeat) timerCallbacks.delete(id);
+      entry.fn();
+    }
+    return;
+  }
+  if (!registered) return;
   for (const [method, info] of Object.entries(HANDLERS)) {
     if (
       info.kind === HandlerKind.Notify &&
@@ -228,6 +357,27 @@ function permError(apiName, perm) {
   return new Error(msg);
 }
 
+// scheduleTimer registers a callback and asks the host to schedule it. The id
+// is guest-allocated and echoed back on "timer.fire". Throws if the host
+// rejects the schedule (per-plugin pending-timer cap).
+function scheduleTimer(fn, ms, repeat) {
+  if (typeof fn !== "function") {
+    throw new Error("owncast.timer: callback must be a function");
+  }
+  const id = nextTimerId++;
+  const delay = Math.max(0, Math.floor(Number(ms) || 0));
+  const fns = Host.getFunctions();
+  if (!fns.owncast_timer_set) {
+    throw new Error("owncast.timer is unavailable in this host");
+  }
+  const ok = fns.owncast_timer_set(BigInt(id), BigInt(delay), repeat ? 1 : 0);
+  if (ok !== 1) {
+    throw new Error("owncast.timer: too many pending timers");
+  }
+  timerCallbacks.set(id, { fn, repeat });
+  return id;
+}
+
 const owncast = {
   chat: {
     send(text) {
@@ -277,6 +427,20 @@ const owncast = {
         Memory.fromString(text).offset,
       );
     },
+    // replyTo whispers text back to whoever sent a chat message. Pass the
+    // ChatMessage from onChatMessage/filterChatMessage (or a bare clientId).
+    // Returns true if the sender's connection was known and the reply sent,
+    // false otherwise (e.g. the message carried no clientId) — letting callers
+    // fall back to a public post.
+    replyTo(msgOrClientId, text) {
+      const clientId =
+        msgOrClientId && typeof msgOrClientId === "object"
+          ? msgOrClientId.clientId
+          : msgOrClientId;
+      if (clientId === undefined || clientId === null) return false;
+      this.sendTo(clientId, text);
+      return true;
+    },
     clients() {
       const fns = Host.getFunctions();
       if (!fns.owncast_chat_clients)
@@ -503,6 +667,14 @@ const owncast = {
       if (offset == 0) return [];
       return JSON.parse(Memory.find(offset).readString());
     },
+    emotes() {
+      const fns = Host.getFunctions();
+      if (!fns.owncast_server_emotes)
+        throw new Error(`permission '${Permissions.ServerRead}' not granted`);
+      const offset = fns.owncast_server_emotes();
+      if (offset == 0) return [];
+      return JSON.parse(Memory.find(offset).readString());
+    },
     federation() {
       const fns = Host.getFunctions();
       if (!fns.owncast_server_federation)
@@ -569,6 +741,34 @@ const owncast = {
         Memory.fromString(String(value)).offset,
       );
     },
+    // getJSON/setJSON are convenience wrappers over the string-only store, so
+    // plugins don't reimplement JSON.parse/stringify for every stored object.
+    // getJSON returns `fallback` (default undefined) when the key is unset or
+    // holds invalid JSON.
+    getJSON(key, fallback) {
+      const raw = this.get(key);
+      if (raw == null) return fallback;
+      try {
+        return JSON.parse(raw);
+      } catch (_e) {
+        return fallback;
+      }
+    },
+    setJSON(key, value) {
+      this.set(key, JSON.stringify(value));
+    },
+  },
+  config: {
+    // get returns the effective value of a manifest-declared config key (the
+    // admin-set override, else the declared default), already parsed to its
+    // declared type. Returns `fallback` (default undefined) for an unknown key
+    // or one with no value. Ambient — no permission required.
+    get(key, fallback) {
+      const fns = Host.getFunctions();
+      const offset = fns.owncast_config_get(Memory.fromString(key).offset);
+      if (offset == 0) return fallback;
+      return JSON.parse(Memory.find(offset).readString());
+    },
   },
   events: {
     emit(eventType, payload) {
@@ -627,6 +827,26 @@ const owncast = {
       );
     },
   },
+  timer: {
+    // setTimeout(fn, ms) runs fn once after ~ms milliseconds. setInterval
+    // repeats until clear(id). The host drives the schedule (the sandbox has
+    // no setTimeout); your callback runs in this instance when it fires.
+    // Returns an id for clear(). Very small delays are clamped up by the host,
+    // and there's a per-plugin cap on pending timers (throws past it).
+    // Note: timers are in-memory and do not survive a plugin reload or a host
+    // restart. No permission required.
+    setTimeout(fn, ms) {
+      return scheduleTimer(fn, ms, false);
+    },
+    setInterval(fn, ms) {
+      return scheduleTimer(fn, ms, true);
+    },
+    clear(id) {
+      timerCallbacks.delete(id);
+      const fns = Host.getFunctions();
+      if (fns.owncast_timer_clear) fns.owncast_timer_clear(BigInt(id));
+    },
+  },
   http: {
     // fetch(url, opts) → { status, headers, body }
     // Wraps Extism's built-in Http.request. Throws if the manifest didn't
@@ -652,6 +872,7 @@ const owncast = {
 
 module.exports = {
   definePlugin,
+  defineCommands,
   owncast,
   filter,
   FilterAction,

package/package.json

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

package/scripts/postinstall.js

@@ -19,11 +19,24 @@ const { execFileSync } = require("child_process");
 
 const EXTISM_JS_VERSION = "v1.6.0";
 const BINARYEN_VERSION = "version_119";
-// Tracks the SDK version that the host binaries were cut for. Usually
-// matches the SDK's own version in package.json.
-const HOST_BINARIES_VERSION = require("../package.json").version;
 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() {
+  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`;
+}
+const HOST_BINARIES_VERSION = hostBinariesVersion();
+
 const platform = process.platform;
 const arch = process.arch;
 

package/testing.js

@@ -78,28 +78,40 @@ function findCacheDir() {
  * 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.
+ * 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
+ * once the event loop drains.
  *
  * @param {Array<object>} scenarios, scenario objects: { name, given?, events, expect? }
  * @param {object}        [opts]
  * @param {string}        [opts.cwd], plugin project directory (default: process.cwd())
+ * @returns {boolean} true if every scenario passed
  */
+function fail(code) {
+  // Record a non-zero exit code without clobbering an earlier failure or
+  // aborting sibling test files. Returns false for `return fail(...)`.
+  if (!process.exitCode) process.exitCode = code;
+  return false;
+}
+
 function runScenarios(scenarios, opts = {}) {
   if (!Array.isArray(scenarios) || scenarios.length === 0) {
     console.error("runScenarios: no scenarios provided");
-    process.exit(2);
+    return fail(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);
+    return fail(2);
   }
   const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
   if (!manifest.name) {
     console.error("manifest.name is required");
-    process.exit(2);
+    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
@@ -109,14 +121,14 @@ function runScenarios(scenarios, opts = {}) {
     console.error(
       `could not derive slug from manifest.name ${JSON.stringify(manifest.name)}; set manifest.slug explicitly`,
     );
-    process.exit(2);
+    return fail(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);
+    return fail(2);
   }
 
   const cache = findCacheDir();
@@ -126,7 +138,7 @@ function runScenarios(scenarios, opts = {}) {
       `owncast-plugin-test not found at ${bin}\n` +
         `Reinstall @owncast/plugin-sdk to fetch the host toolchain (postinstall handles it).`,
     );
-    process.exit(2);
+    return fail(2);
   }
 
   // Build a temp project dir that links to the wasm + manifest and contains
@@ -156,11 +168,46 @@ function runScenarios(scenarios, opts = {}) {
     try {
       execFileSync(bin, [tmp], { stdio: "inherit", env });
     } catch (e) {
-      process.exit(typeof e.status === "number" ? e.status : 1);
+      return fail(typeof e.status === "number" ? e.status : 1);
     }
   } finally {
     fs.rmSync(tmp, { recursive: true, force: true });
   }
+  return true;
+}
+
+/**
+ * Discover and run every `__tests__/*.test.js` file in one node process,
+ * aggregating their exit status. Lets you organize scenarios across multiple
+ * files (by module/feature) without a shell loop spawning a process per file.
+ * Each discovered file is expected to call runScenarios() at load time.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.cwd], plugin project directory (default: process.cwd())
+ * @returns {boolean} true if every file's scenarios passed
+ */
+function runScenarioFiles(opts = {}) {
+  const cwd = opts.cwd ? path.resolve(opts.cwd) : process.cwd();
+  const dir = path.join(cwd, "__tests__");
+  if (!fs.existsSync(dir)) {
+    console.error(`no __tests__ directory in ${cwd}`);
+    return fail(2);
+  }
+  const files = fs
+    .readdirSync(dir)
+    .filter((f) => f.endsWith(".test.js"))
+    .sort()
+    .map((f) => path.join(dir, f));
+  if (files.length === 0) {
+    console.error(`no *.test.js files in ${dir}`);
+    return fail(2);
+  }
+  for (const f of files) {
+    // Each file runs its own runScenarios() at require time, which records a
+    // non-zero process.exitCode on failure but no longer aborts the process.
+    require(f);
+  }
+  return !process.exitCode;
 }
 
-module.exports = { runScenarios };
+module.exports = { runScenarios, runScenarioFiles };