lumia-plugin 0.2.4 → 0.2.6

package/README.md

@@ -14,7 +14,7 @@ Run any command with `--help` to see detailed options.
 
 ## Template
 
-The CLI ships with a showcase template that demonstrates logging, settings, variables, and alert handling. It mirrors the starter plugin available in this repository so the CLI can scaffold it anywhere.
+The CLI ships with a showcase template that demonstrates settings, actions, variables, and alert handling. It mirrors the starter plugin available in this repository so the CLI can scaffold it anywhere.
 
 ## License
 

package/examples/base_plugin/README.md

@@ -0,0 +1,16 @@
+# Showcase Plugin Template
+
+This template demonstrates a minimal, production-friendly Lumia Stream plugin workflow:
+
+- Defines a small set of settings with a short setup tutorial
+- Exposes a single action that triggers an alert
+- Updates a few variables that alerts and other Lumia features can use
+- Keeps logging to errors only
+
+Use the CLI to copy and customize the template:
+
+```
+npx lumia-plugin create my_plugin
+```
+
+After scaffolding you can tailor the manifest, code, and README to match your idea.

package/examples/base_plugin/main.js

@@ -0,0 +1,90 @@
+const { Plugin } = require("@lumiastream/plugin");
+
+const DEFAULTS = {
+	message: "Hello from Showcase Plugin!",
+	username: "Viewer",
+	color: "#00c2ff",
+	duration: 5,
+};
+
+const VARIABLE_NAMES = {
+	message: "message",
+	username: "username",
+	color: "color",
+	duration: "duration",
+};
+
+class ShowcasePluginTemplate extends Plugin {
+	async onload() {
+		await this._syncDefaults();
+	}
+
+	async onsettingsupdate(settings, previous = {}) {
+		if (
+			settings?.defaultMessage !== previous?.defaultMessage ||
+			settings?.defaultColor !== previous?.defaultColor ||
+			settings?.defaultDuration !== previous?.defaultDuration
+		) {
+			await this._syncDefaults(settings);
+		}
+	}
+
+	async actions(config = {}) {
+		const actions = Array.isArray(config.actions) ? config.actions : [];
+		for (const action of actions) {
+			if (action?.type === "trigger_alert") {
+				await this._triggerSampleAlert(action.value);
+			}
+		}
+	}
+
+	async _syncDefaults(settings = this.settings) {
+		const message = settings?.defaultMessage ?? DEFAULTS.message;
+		const color = settings?.defaultColor ?? DEFAULTS.color;
+		const duration = Number(settings?.defaultDuration ?? DEFAULTS.duration);
+
+		await this.lumia.setVariable(VARIABLE_NAMES.message, message);
+		await this.lumia.setVariable(VARIABLE_NAMES.color, color);
+		await this.lumia.setVariable(VARIABLE_NAMES.duration, duration);
+	}
+
+	async _triggerSampleAlert(data = {}) {
+		const username = data?.username ?? DEFAULTS.username;
+		const message =
+			data?.message ?? this.settings?.defaultMessage ?? DEFAULTS.message;
+		const color = data?.color ?? this.settings?.defaultColor ?? DEFAULTS.color;
+		const duration = Number(
+			data?.duration ?? this.settings?.defaultDuration ?? DEFAULTS.duration
+		);
+
+		await this.lumia.setVariable(VARIABLE_NAMES.username, username);
+		await this.lumia.setVariable(VARIABLE_NAMES.message, message);
+		await this.lumia.setVariable(VARIABLE_NAMES.color, color);
+		await this.lumia.setVariable(VARIABLE_NAMES.duration, duration);
+
+		try {
+			await this.lumia.triggerAlert({
+				alert: "sample_alert",
+				dynamic: {
+					value: color,
+					username,
+					message,
+					color,
+					duration,
+				},
+				extraSettings: {
+					username,
+					message,
+					color,
+					duration,
+				},
+			});
+		} catch (error) {
+			await this.lumia.addLog(
+				`Sample alert failed: ${error?.message ?? String(error)}`
+			);
+		}
+	}
+}
+
+module.exports = ShowcasePluginTemplate;

package/examples/base_plugin/manifest.json

@@ -0,0 +1,125 @@
+{
+	"id": "showcase_plugin",
+	"name": "Showcase Plugin",
+	"version": "1.0.0",
+	"author": "Lumia Stream",
+	"email": "",
+	"website": "",
+	"repository": "",
+	"description": "Starter template that demonstrates settings, actions, variables, and alerts with a minimal code path.",
+	"license": "MIT",
+	"lumiaVersion": "^9.0.0",
+	"category": "apps",
+	"keywords": "sample, demo, lumia, showcase, template",
+	"icon": "",
+	"changelog": "",
+	"config": {
+		"settings": [
+			{
+				"key": "defaultMessage",
+				"label": "Default Message",
+				"type": "text",
+				"defaultValue": "Hello from Showcase Plugin!",
+				"helperText": "Used when the action does not supply a message."
+			},
+			{
+				"key": "defaultColor",
+				"label": "Default Color",
+				"type": "color",
+				"defaultValue": "#00c2ff",
+				"helperText": "Used when the action does not supply a color."
+			},
+			{
+				"key": "defaultDuration",
+				"label": "Default Duration (seconds)",
+				"type": "number",
+				"defaultValue": 5,
+				"min": 1,
+				"max": 60,
+				"helperText": "Used when the action does not supply a duration."
+			}
+		],
+		"settings_tutorial": "---\n### Setup\n1) Enter a default message and color.\n2) Adjust the default duration if you want a longer or shorter alert.\n3) Click Save to store the defaults.\n---\n### What this plugin does\n- Stores the message, username, color, and duration in variables.\n- Uses those values when triggering the sample alert.\n---",
+		"actions_tutorial": "---\n### Trigger Sample Alert\nUse this action to fire the sample alert. You can override the message, username, color, and duration per action. The alert uses both dynamic and extraSettings so variations and templates have the same data.\n---",
+		"actions": [
+			{
+				"type": "trigger_alert",
+				"label": "Trigger Sample Alert",
+				"description": "Trigger the sample alert with optional overrides.",
+				"fields": [
+					{
+						"key": "username",
+						"label": "Username",
+						"type": "text",
+						"defaultValue": "Viewer"
+					},
+					{
+						"key": "message",
+						"label": "Message",
+						"type": "text",
+						"defaultValue": "Hello from Showcase Plugin!"
+					},
+					{
+						"key": "color",
+						"label": "Color",
+						"type": "color",
+						"defaultValue": "#00c2ff"
+					},
+					{
+						"key": "duration",
+						"label": "Duration (seconds)",
+						"type": "number",
+						"defaultValue": 5,
+						"min": 1,
+						"max": 60
+					}
+				]
+			}
+		],
+		"variables": [
+			{
+				"name": "message",
+				"description": "Stores the most recent message handled by the plugin.",
+				"value": ""
+			},
+			{
+				"name": "username",
+				"description": "Stores the most recent username handled by the plugin.",
+				"value": ""
+			},
+			{
+				"name": "color",
+				"description": "Tracks the color used by the latest sample alert.",
+				"value": ""
+			},
+			{
+				"name": "duration",
+				"description": "Tracks the duration used by the latest sample alert.",
+				"value": 0
+			}
+		],
+		"alerts": [
+			{
+				"title": "Sample Alert",
+				"key": "sample_alert",
+				"acceptedVariables": [
+					"message",
+					"username",
+					"color",
+					"duration"
+				],
+				"defaultMessage": "{{username}}: {{message}}",
+				"variationConditions": [
+					{
+						"type": "EQUAL_SELECTION",
+						"description": "Matches dynamic.value against the selected color.",
+						"selections": [
+							{ "label": "Blue", "value": "#00c2ff" },
+							{ "label": "Red", "value": "#ff5f5f" }
+						]
+					}
+				]
+			}
+		]
+	}
+}

package/examples/base_plugin/package.json

@@ -0,0 +1,10 @@
+{
+	"name": "lumia-showcase-plugin-template",
+	"version": "1.0.0",
+	"private": true,
+	"description": "Internal template illustrating settings, actions, variables, and alerts for Lumia Stream plugins.",
+	"main": "main.js",
+	"dependencies": {
+		"@lumiastream/plugin": "^0.2.6"
+	}
+}

package/package.json

@@ -1,10 +1,14 @@
 {
 	"name": "lumia-plugin",
-	"version": "0.2.4",
+	"version": "0.2.6",
 	"description": "Command-line tools for creating, building, and validating Lumia Stream plugins.",
 	"bin": {
 		"lumia-plugin": "scripts/cli.js"
 	},
+	"scripts": {
+		"prepack": "node scripts/sync-template.js",
+		"postpack": "node scripts/clean-template.js"
+	},
 	"files": [
 		"scripts",
 		"examples/base_plugin",
@@ -20,7 +24,7 @@
 	"author": "Lumia Stream",
 	"license": "MIT",
 	"dependencies": {
-		"@lumiastream/plugin": "^0.2.4",
+		"@lumiastream/plugin": "^0.2.6",
 		"jszip": "3.10.1"
 	}
 }

package/scripts/build-plugin.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 const path = require("path");
 const fs = require("fs");
+const { spawnSync } = require("child_process");
 const {
 	readManifest,
 	validateManifest,
@@ -64,6 +65,21 @@ async function main() {
 	}
 
 	try {
+		const packageJsonPath = path.join(pluginDir, "package.json");
+		if (fs.existsSync(packageJsonPath)) {
+			console.log("• Running npm install...");
+			const result = spawnSync("npm", ["install"], {
+				cwd: pluginDir,
+				stdio: "inherit",
+			});
+			if (result.status !== 0) {
+				console.error("✖ npm install failed. Aborting build.");
+				process.exit(1);
+			}
+		} else {
+			console.log("• No package.json found; skipping npm install.");
+		}
+
 		const { manifest } = await readManifest(pluginDir);
 		const errors = validateManifest(manifest);
 		if (errors.length) {
@@ -72,10 +88,30 @@ async function main() {
 			process.exit(1);
 		}
 
+		const entryFile =
+			typeof manifest.main === "string" && manifest.main.trim()
+				? manifest.main.trim()
+				: "main.js";
+		const entryPath = path.resolve(pluginDir, entryFile);
+		if (!fs.existsSync(entryPath)) {
+			console.error(`✖ Entry file not found: ${entryFile}`);
+			process.exit(1);
+		}
+
+		console.log(`• Running syntax check on ${entryFile}...`);
+		const checkResult = spawnSync("node", ["--check", entryPath], {
+			cwd: pluginDir,
+			stdio: "inherit",
+		});
+		if (checkResult.status !== 0) {
+			console.error("✖ Syntax check failed. Aborting build.");
+			process.exit(1);
+		}
+
 		const files = await collectFiles(pluginDir);
 		if (!files.length) {
 			console.error(
-				"✖ No files found to package (did you point to the plugin root?)"
+				"✖ No files found to package (did you point to the plugin root?)",
 			);
 			process.exit(1);
 		}

package/scripts/clean-template.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+const path = require("path");
+const fs = require("fs");
+
+const DEST_DIR = path.resolve(__dirname, "..", "examples", "base_plugin");
+
+async function main() {
+	if (!fs.existsSync(DEST_DIR)) return;
+	await fs.promises.rm(DEST_DIR, { recursive: true, force: true });
+}
+
+main().catch((error) => {
+	console.error("✖ Failed to clean template:", error?.message ?? error);
+	process.exit(1);
+});

package/scripts/create-plugin.js

@@ -2,7 +2,19 @@
 const path = require("path");
 const fs = require("fs");
 
-const TEMPLATE_DIR = path.resolve(__dirname, "..", "examples", "base_plugin");
+const TEMPLATE_DIRS = [
+	path.resolve(__dirname, "..", "..", "examples", "base_plugin"),
+	path.resolve(__dirname, "..", "examples", "base_plugin"),
+];
+
+function resolveTemplateDir() {
+	for (const candidate of TEMPLATE_DIRS) {
+		if (fs.existsSync(candidate)) {
+			return candidate;
+		}
+	}
+	return null;
+}
 
 function toSafeId(value) {
 	const cleaned = value
@@ -95,18 +107,18 @@ async function updateManifest(manifestPath, pluginId, displayName) {
 	if (manifest.config && typeof manifest.config === "object") {
 		const { settings, actions, variables } = manifest.config;
 
-		const welcomeSetting = ensureArray(settings).find(
-			(setting) => setting?.key === "welcomeMessage"
+		const defaultMessageSetting = ensureArray(settings).find(
+			(setting) => setting?.key === "defaultMessage"
 		);
-		if (welcomeSetting) {
-			welcomeSetting.defaultValue = `Hello from ${displayName}!`;
+		if (defaultMessageSetting) {
+			defaultMessageSetting.defaultValue = `Hello from ${displayName}!`;
 		}
 
-		const logAction = ensureArray(actions).find(
-			(action) => action?.type === "log_message"
+		const triggerAlertAction = ensureArray(actions).find(
+			(action) => action?.type === "trigger_alert"
 		);
-		if (logAction && Array.isArray(logAction.fields)) {
-			const messageField = logAction.fields.find(
+		if (triggerAlertAction && Array.isArray(triggerAlertAction.fields)) {
+			const messageField = triggerAlertAction.fields.find(
 				(field) => field?.key === "message"
 			);
 			if (messageField) {
@@ -119,7 +131,7 @@ async function updateManifest(manifestPath, pluginId, displayName) {
 			if (variable.origin) {
 				variable.origin = pluginId;
 			}
-			if (variable.name === "last_message" && "example" in variable) {
+			if (variable.name === "message" && "example" in variable) {
 				variable.example = `Hello from ${displayName}!`;
 			}
 		}
@@ -180,8 +192,13 @@ async function main() {
 		return;
 	}
 
-	if (!fs.existsSync(TEMPLATE_DIR)) {
-		console.error("✖ Template directory not found:", TEMPLATE_DIR);
+	const templateDir = resolveTemplateDir();
+	if (!templateDir) {
+		console.error("✖ Template directory not found.");
+		console.error("   Looked in:");
+		for (const candidate of TEMPLATE_DIRS) {
+			console.error(`   - ${candidate}`);
+		}
 		console.error("   Tip: Make sure lumia-plugin is properly installed.");
 		process.exit(1);
 	}
@@ -198,7 +215,7 @@ async function main() {
 		await ensureEmptyDir(targetDir);
 
 		console.log("  📋 Copying template files...");
-		await copyTemplate(TEMPLATE_DIR, targetDir);
+		await copyTemplate(templateDir, targetDir);
 
 		console.log("  ✏️  Updating manifest.json...");
 		await updateManifest(

package/scripts/sync-template.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+const path = require("path");
+const fs = require("fs");
+
+const SOURCE_DIR = path.resolve(__dirname, "..", "..", "examples", "base_plugin");
+const DEST_DIR = path.resolve(__dirname, "..", "examples", "base_plugin");
+
+async function copyDir(src, dest) {
+	const stats = await fs.promises.stat(src);
+	if (stats.isDirectory()) {
+		await fs.promises.mkdir(dest, { recursive: true });
+		const entries = await fs.promises.readdir(src);
+		for (const entry of entries) {
+			await copyDir(path.join(src, entry), path.join(dest, entry));
+		}
+		return;
+	}
+	if (stats.isFile()) {
+		await fs.promises.copyFile(src, dest);
+	}
+}
+
+async function main() {
+	const sourceExists = fs.existsSync(SOURCE_DIR);
+	const destExists = fs.existsSync(DEST_DIR);
+
+	if (!sourceExists && !destExists) {
+		console.error("✖ Template source not found:", SOURCE_DIR);
+		process.exit(1);
+	}
+
+	if (!sourceExists) {
+		console.warn("⚠ Template source missing, leaving existing copy in place.");
+		return;
+	}
+
+	if (destExists) {
+		await fs.promises.rm(DEST_DIR, { recursive: true, force: true });
+	}
+
+	await copyDir(SOURCE_DIR, DEST_DIR);
+}
+
+main().catch((error) => {
+	console.error("✖ Failed to sync template:", error?.message ?? error);
+	process.exit(1);
+});