Skip to content

Take control over your live stream video by running it yourself. Streaming + chat out of the box.

feat(plugins): add support for commands w/ !help overview

Gabe Kangas5569ad3fa887
diff --git a/pluginhost/pluginevents.go b/pluginhost/pluginevents.go
index 4ba7b335de..0a675117ad 100644
--- a/pluginhost/pluginevents.go
+++ b/pluginhost/pluginevents.go
@@ -125,6 +125,49 @@ func filteredBody(final any, fallback string) string {
return fallback
}
+// moderatorScope is the user scope that grants moderator privileges; mod-only
+// commands are hidden from non-moderators in the help listing.
+const moderatorScope = "MODERATOR"
+
+// newHelpResponder returns a dispatcher.Listener that answers the unified
+// `!help` chat command. The host owns !help (no plugin implements it): it
+// aggregates command metadata across all loaded plugins — which no single
+// sandboxed plugin could see — and posts the list as a system message via
+// `post`. snapshot yields the current loaded plugins; post sends a system
+// chat message.
+func newHelpResponder(snapshot func() []*plugins.Loaded, post func(text string)) dispatcher.Listener {
+ return func(ctx context.Context, e dispatcher.Event) {
+ webhookEvent, ok := e.Payload.(webhooks.WebhookEvent)
+ if !ok || webhookEvent.Type != models.MessageSent {
+ return
+ }
+ data, ok := webhookEvent.EventData.(*webhooks.WebhookChatMessage)
+ if !ok || data == nil {
+ return
+ }
+ // Ignore bot/system posts (e.g. the help message itself, or a plugin's
+ // chat.send) so !help can't be triggered by non-human messages.
+ if data.User != nil && data.User.IsBot {
+ return
+ }
+ if !plugins.IsHelpCommand(data.RawBody) {
+ return
+ }
+ isMod := false
+ if data.User != nil {
+ for _, s := range data.User.Scopes {
+ if s == moderatorScope {
+ isMod = true
+ break
+ }
+ }
+ }
+ if text := plugins.BuildHelpMessage(snapshot(), isMod); text != "" {
+ post(text)
+ }
+ }
+}
+
// newPluginEventListener returns a dispatcher.Listener that translates each
// Owncast event (carried as a webhooks.WebhookEvent) into the plugin SDK's
// payload shape and dispatches it to subscribed plugins. Dispatch runs on its
diff --git a/pluginhost/pluginhost.go b/pluginhost/pluginhost.go
index ccdeb8d60b..05a0b5302e 100644
--- a/pluginhost/pluginhost.go
+++ b/pluginhost/pluginhost.go
@@ -396,6 +396,15 @@ func New(ctx context.Context, deps Deps) (*Host, error) {
deps.Events.AddListener(newPluginEventListener(pluginDispatcher))
deps.Events.AddFilter(newPluginChatFilter(pluginDispatcher))
+ // Host-owned `!help`: list every plugin's chat commands (no single plugin
+ // can see across the sandbox, so the host aggregates and answers). Posts a
+ // system message — works even when no plugin holds chat.send.
+ deps.Events.AddListener(newHelpResponder(manager.Snapshot, func(text string) {
+ if err := deps.Chat.SendSystemMessage(text, false); err != nil {
+ log.Errorln("plugin !help:", err)
+ }
+ }))
+
// Host-driven timers: plugins can't setTimeout in the sandbox, so
// owncast.timer.* asks the host to schedule callbacks. The hub resolves a
// plugin slug to its live instance to call back; cancelling a plugin's
diff --git a/services/plugins/engines/javascript/engine.wasm b/services/plugins/engines/javascript/engine.wasm
index 087697ad94..0af7d7a11f 100644
Binary files a/services/plugins/engines/javascript/engine.wasm and b/services/plugins/engines/javascript/engine.wasm differ
diff --git a/services/plugins/engines/python/engine.wasm b/services/plugins/engines/python/engine.wasm
index cbb108fdf9..66b2e9d38c 100644
Binary files a/services/plugins/engines/python/engine.wasm and b/services/plugins/engines/python/engine.wasm differ
diff --git a/services/plugins/manager.go b/services/plugins/manager.go
index 583e250b87..893d8a48bc 100644
--- a/services/plugins/manager.go
+++ b/services/plugins/manager.go
@@ -1277,6 +1277,10 @@ func loadFromBytes(ctx context.Context, env *HostEnv, manifestBytes, artifactByt
return nil, err
}
manifest.Subscriptions = runtime.Subscriptions
+ // Command metadata is derived by the SDK and reported via register() (like
+ // subscriptions); the host aggregates it for !help. Informational only, so
+ // it isn't part of AgreesWith's security checks.
+ manifest.Commands = runtime.Commands
var adminGlobs []glob.Glob
var adminPaths []string
diff --git a/services/plugins/manifest.go b/services/plugins/manifest.go
index 3cdd3ab84b..c863af73a1 100644
--- a/services/plugins/manifest.go
+++ b/services/plugins/manifest.go
@@ -27,6 +27,18 @@ type Subscriptions struct {
Filter []Subscription `json:"filter,omitempty"`
}
+// CommandInfo is one chat command a plugin advertises for the unified !help.
+// Reported by the SDK in register() output; purely informational (the plugin's
+// own router does the actual matching).
+type CommandInfo struct {
+ Name string `json:"name"`
+ Prefix string `json:"prefix,omitempty"`
+ Description string `json:"description,omitempty"`
+ Usage string `json:"usage,omitempty"`
+ Aliases []string `json:"aliases,omitempty"`
+ ModOnly bool `json:"modOnly,omitempty"`
+}
+
type ConfigField struct {
Type string `json:"type"`
Default any `json:"default,omitempty"`
@@ -61,16 +73,21 @@ type Manifest struct {
// hyphenated, matches slugPattern. Authors can pin it via the
// JSON `slug` field; if empty, it's auto-derived from
// DisplayName at parse time by slugify.
- Slug string `json:"slug,omitempty"`
- Version string `json:"version"`
- Description string `json:"description,omitempty"`
- Bot BotConfig `json:"bot,omitempty"`
- Subscriptions Subscriptions `json:"subscriptions"`
- Permissions []string `json:"permissions,omitempty"`
- Config map[string]ConfigField `json:"config,omitempty"`
- Admin AdminConfig `json:"admin,omitempty"`
- Actions []ActionButton `json:"actions,omitempty"`
- Network NetworkConfig `json:"network,omitempty"`
+ Slug string `json:"slug,omitempty"`
+ Version string `json:"version"`
+ Description string `json:"description,omitempty"`
+ Bot BotConfig `json:"bot,omitempty"`
+ Subscriptions Subscriptions `json:"subscriptions"`
+ // Commands is the plugin's chat-command metadata, derived by the SDK from
+ // its defineCommands/plugin.commands table and reported via register() (not
+ // authored in the sidecar manifest). The host aggregates these across
+ // plugins to answer a unified !help.
+ Commands []CommandInfo `json:"commands,omitempty"`
+ Permissions []string `json:"permissions,omitempty"`
+ Config map[string]ConfigField `json:"config,omitempty"`
+ Admin AdminConfig `json:"admin,omitempty"`
+ Actions []ActionButton `json:"actions,omitempty"`
+ Network NetworkConfig `json:"network,omitempty"`
// Styles is a list of CSS files the plugin contributes to the
// viewer page (the public streaming page). Each entry is a path
// relative to the plugin's own URL namespace: bare paths like
diff --git a/services/plugins/shared_engine_test.go b/services/plugins/shared_engine_test.go
index c289fc8ae8..1547596789 100644
--- a/services/plugins/shared_engine_test.go
+++ b/services/plugins/shared_engine_test.go
@@ -229,6 +229,55 @@ module.exports = definePlugin({
}
}
+// TestSharedEngineReportsCommands verifies command metadata declared in a
+// plugin's command table flows SDK → engine register() → host manifest, so the
+// host can build !help.
+func TestSharedEngineReportsCommands(t *testing.T) {
+ ctx := context.Background()
+ compiledEngines.resetForTest(ctx)
+ t.Cleanup(func() { compiledEngines.resetForTest(ctx) })
+
+ env, _, _ := captureEnv()
+
+ jsScript := `
+const { definePlugin } = require("@owncast/plugin-sdk");
+module.exports = definePlugin({
+ commands: { uptime: { description: "Stream uptime", run: () => {} } },
+});`
+ js := loadShared(t, ctx, env, RuntimeJavaScript, "js-cmds", jsScript, []string{})
+ defer js.Close(ctx)
+ assertHasCommand(t, js, "uptime", "Stream uptime")
+
+ pyScript := `
+plugin.commands({"uptime": {"description": "Stream uptime", "run": lambda ctx: None}})
+`
+ py := loadShared(t, ctx, env, RuntimePython, "py-cmds", pyScript, []string{})
+ defer py.Close(ctx)
+ assertHasCommand(t, py, "uptime", "Stream uptime")
+
+ // And the host can render a unified help listing from it.
+ help := BuildHelpMessage([]*Loaded{js, py}, false)
+ if !strings.Contains(help, "`!uptime`") || !strings.Contains(help, "Stream uptime") {
+ t.Errorf("help should list the reported command:\n%s", help)
+ }
+}
+
+func assertHasCommand(t *testing.T, l *Loaded, name, desc string) {
+ t.Helper()
+ for _, c := range l.Manifest.Commands {
+ if c.Name == name {
+ if c.Description != desc {
+ t.Errorf("%s: command %q description = %q, want %q", l.Manifest.Slug, name, c.Description, desc)
+ }
+ if c.Prefix != "!" {
+ t.Errorf("%s: command %q prefix = %q, want \"!\"", l.Manifest.Slug, name, c.Prefix)
+ }
+ return
+ }
+ }
+ t.Errorf("%s: register() did not report command %q; got %+v", l.Manifest.Slug, name, l.Manifest.Commands)
+}
+
func TestSharedEnginePythonRegister(t *testing.T) {
ctx := context.Background()
compiledEngines.resetForTest(ctx)