Mudstack Plugin Boilerplate - initial commit

.gitignore

@@ -0,0 +1,8 @@
+node_modules/
+.env
+*.log
+dist/
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Mudstack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1 +1,50 @@
-# mudstack-plugins
+# Mudstack plugin template and examples
+
+Sample and boilerplate [Mudstack](https://www.mudstack.com) plugins. This repo is not part of the main Mudstack app; it helps you start or learn how to build plugins that run inside Mudstack (e.g. thumbnailers, context menu commands, custom integrations).
+
+- **[@mudstack/plugins on npm](https://www.npmjs.com/package/@mudstack/plugins)** – Types and base class for building plugins with IntelliSense.
+
+## Getting started (template)
+
+Start a new plugin by **forking this repo** or using **Use this template** (if enabled). The root of the repo is the plugin template.
+
+1. **Rename the plugin** in `manifest.json` and `package.json`:
+   - `manifest.json`: change `id`, `name`, `description`, `author`.
+   - `package.json`: change `name`, `description`, `author`.
+2. Run **`yarn install`** or **`npm install`** in the repo root.
+3. **Implement your logic** in `index.js`. Your class extends `MudstackPlugin` and has access to `this.api` (logging, events, db, config, etc.). See [@mudstack/plugins](https://www.npmjs.com/package/@mudstack/plugins) for the full API.
+4. **Install the plugin** in Mudstack: copy this folder into your Mudstack plugins directory, or follow Mudstack’s plugin installation docs.
+
+You can add `dependencies`, `subscriptions`, and `registrations` in `manifest.json` as needed (see the `examples/` folder for reference).
+
+## Examples
+
+The `examples/` folder contains reference plugins you can learn from or try:
+
+- **hello-world** – Minimal plugin: logs on activate/deactivate and optionally subscribes to an event.
+- **context-menu-example** – Adds a context menu command and handles the event when the user runs it.
+
+Use them as reference, or copy a folder into your Mudstack plugins directory to run them.
+
+## Directory layout
+
+```
+mudstack-plugins/
+├── README.md           # This file
+├── LICENSE
+├── .gitignore
+├── package.json        # Template plugin (rename and customize)
+├── manifest.json
+├── index.js
+└── examples/
+    ├── hello-world/
+    │   ├── package.json
+    │   ├── manifest.json
+    │   └── index.js
+    └── context-menu-example/
+        ├── package.json
+        ├── manifest.json
+        └── index.js
+```
+
+Each plugin is a standalone folder (examples have their own `package.json`). Install dependencies inside the plugin folder you’re working on (repo root for the template, or an example folder).

examples/context-menu-example/index.js

@@ -0,0 +1,24 @@
+const { MudstackPlugin } = require('@mudstack/plugins');
+
+class ContextMenuExamplePlugin extends MudstackPlugin {
+  async activate() {
+    await super.activate();
+    this.api.log('info', '[ContextMenuExample] Plugin activated');
+  }
+
+  async deactivate() {
+    this.api.log('info', '[ContextMenuExample] Plugin deactivating');
+    await super.deactivate();
+  }
+
+  /**
+   * Called when the user runs the "Say Hello (example)" context menu command.
+   * Subscribed via manifest subscriptions (event + handler); no manual events.on() needed.
+   */
+  async handleSayHello(message) {
+    const { id: requestId, payload } = message || {};
+    this.api.log('info', '[ContextMenuExample] User ran the context menu command', payload);
+  }
+}
+
+module.exports = ContextMenuExamplePlugin;

examples/context-menu-example/manifest.json

@@ -0,0 +1,25 @@
+{
+  "id": "com.mudstack.example.context-menu",
+  "name": "Context Menu Example",
+  "version": "1.0.0",
+  "description": "Adds a context menu command and handles the event when the user runs it",
+  "author": "Mudstack",
+  "main": "index.js",
+  "enabled": true,
+  "dependencies": [],
+  "subscriptions": [
+    {
+      "event": "com.mudstack.example.context-menu.say-hello",
+      "handler": "handleSayHello"
+    }
+  ],
+  "registrations": [],
+  "contextMenuCommands": [
+    {
+      "id": "com.mudstack.example.context-menu.say-hello",
+      "title": "Say Hello (example)",
+      "description": "Example context menu command from the context-menu-example plugin",
+      "eventType": "com.mudstack.example.context-menu.say-hello"
+    }
+  ]
+}

examples/context-menu-example/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "mudstack-example-context-menu",
+  "version": "1.0.0",
+  "description": "Mudstack plugin example that adds a context menu command",
+  "main": "index.js",
+  "author": "Mudstack",
+  "license": "MIT",
+  "keywords": ["mudstack", "plugin", "example", "context-menu"],
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "dependencies": {
+    "@mudstack/plugins": "^1.0.0"
+  }
+}

examples/hello-world/index.js

@@ -0,0 +1,15 @@
+const { MudstackPlugin } = require("@mudstack/plugins");
+
+class HelloWorldPlugin extends MudstackPlugin {
+  async activate() {
+    await super.activate();
+    this.api.log("info", "[HelloWorld] Plugin activated");
+  }
+
+  async deactivate() {
+    this.api.log("info", "[HelloWorld] Plugin deactivating");
+    await super.deactivate();
+  }
+}
+
+module.exports = HelloWorldPlugin;

examples/hello-world/manifest.json

@@ -0,0 +1,12 @@
+{
+  "id": "com.mudstack.example.hello-world",
+  "name": "Hello World Example",
+  "version": "1.0.0",
+  "description": "Minimal Mudstack plugin that logs on activate/deactivate",
+  "author": "Mudstack",
+  "main": "index.js",
+  "enabled": true,
+  "dependencies": [],
+  "subscriptions": [],
+  "registrations": []
+}

examples/hello-world/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "mudstack-example-hello-world",
+  "version": "1.0.0",
+  "description": "Minimal Mudstack plugin example",
+  "main": "index.js",
+  "author": "Mudstack",
+  "license": "MIT",
+  "keywords": ["mudstack", "plugin", "example"],
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "dependencies": {
+    "@mudstack/plugins": "^1.0.0"
+  }
+}

index.js

@@ -0,0 +1,15 @@
+const { MudstackPlugin } = require('@mudstack/plugins');
+
+class MyPlugin extends MudstackPlugin {
+  async activate() {
+    await super.activate();
+    this.api.log('info', 'MyPlugin activated');
+  }
+
+  async deactivate() {
+    this.api.log('info', 'MyPlugin deactivating');
+    await super.deactivate();
+  }
+}
+
+module.exports = MyPlugin;

manifest.json

@@ -0,0 +1 @@
+{"id":"com.example.my-mudstack-plugin","name":"My Mudstack Plugin","version":"1.0.0","description":"A Mudstack plugin (rename me)","author":"","main":"index.js","enabled":true,"dependencies":[],"subscriptions":[],"registrations":[]}

package.json

@@ -0,0 +1 @@
+{"name":"my-mudstack-plugin","version":"1.0.0","description":"A Mudstack plugin (rename me)","main":"index.js","author":"","license":"MIT","keywords":["mudstack","plugin"],"engines":{"node":">=16.0.0"},"dependencies":{"@mudstack/plugins":"^1.0.0"}}