lumia-plugin 0.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Lumia Stream
+
+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.

package/README.md

@@ -0,0 +1,21 @@
+# Lumia Stream Plugin CLI
+
+The `@lumiastream/plugin-cli` package bundles the command-line tools for creating, building, and validating Lumia Stream plugins without pulling the full SDK into your runtime dependencies.
+
+## Commands
+
+```
+npx @lumiastream/plugin-cli create <directory>
+npx @lumiastream/plugin-cli build [--dir <path>] [--out <file>]
+npx @lumiastream/plugin-cli validate <plugin-directory>
+```
+
+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.
+
+## License
+
+MIT

package/examples/base-plugin/README.md

@@ -0,0 +1,17 @@
+# Showcase Plugin Template
+
+This template demonstrates a handful of common Lumia Stream plugin capabilities:
+
+- Logs lifecycle events and recent actions
+- Stores and updates variables that other Lumia features can consume
+- Responds to custom actions for logging, variable updates, and alert triggering
+- Triggers a sample alert effect using configurable colors and duration
+- Shows how to react to setting changes inside `onsettingsupdate`
+
+Use the CLI to copy and customise the template:
+
+```
+npx @lumiastream/plugin-cli 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,143 @@
+const { Plugin } = require('@lumiastream/plugin-sdk');
+
+const VARIABLE_NAMES = {
+  lastMessage: 'last_message',
+  lastAlertColor: 'last_alert_color',
+};
+
+const DEFAULTS = {
+  welcomeMessage: 'Hello from Showcase Plugin!',
+  color: '#00c2ff',
+  alertDuration: 5,
+};
+
+class ShowcasePluginTemplate extends Plugin {
+  async onload() {
+    const message = this._currentMessage();
+    await this._log('Plugin loaded');
+    await this._rememberMessage(message);
+
+    if (this.settings.autoAlert === 'load') {
+      await this._triggerSampleAlert({
+        color: this.settings.favoriteColor,
+        duration: DEFAULTS.alertDuration,
+      });
+    }
+  }
+
+  async onunload() {
+    await this._log('Plugin unloaded');
+  }
+
+  async onsettingsupdate(settings, previous = {}) {
+    await this._log('Settings updated');
+
+    if (settings?.welcomeMessage && settings.welcomeMessage !== previous?.welcomeMessage) {
+      await this._rememberMessage(settings.welcomeMessage);
+    }
+
+    if (settings?.autoAlert === 'load' && previous?.autoAlert !== 'load') {
+      await this._log('Auto alert configured to fire on load');
+    }
+  }
+
+  async actions(config = {}) {
+    const actions = Array.isArray(config.actions) ? config.actions : [];
+    for (const action of actions) {
+      switch (action?.type) {
+        case 'log_message':
+          await this._handleLogMessage(action.data);
+          break;
+        case 'update_variable':
+          await this._handleUpdateVariable(action.data);
+          break;
+        case 'trigger_alert':
+          await this._triggerSampleAlert(action.data);
+          break;
+        default:
+          await this._log(`Unknown action type: ${action?.type ?? 'undefined'}`);
+      }
+    }
+  }
+
+  _tag() {
+    return `[${this.manifest?.id ?? 'showcase-plugin'}]`;
+  }
+
+  _currentMessage() {
+    return (
+      this.settings?.welcomeMessage ||
+      `Hello from ${this.manifest?.name ?? 'Showcase Plugin'}!`
+    );
+  }
+
+  async _log(message, severity = 'info') {
+    const prefix = this._tag();
+    const decorated =
+      severity === 'warn'
+        ? `${prefix} ⚠️ ${message}`
+        : severity === 'error'
+        ? `${prefix} ❌ ${message}`
+        : `${prefix} ${message}`;
+
+    await this.lumia.addLog(decorated);
+  }
+
+  async _rememberMessage(value) {
+    await this.lumia.setVariable(VARIABLE_NAMES.lastMessage, value);
+  }
+
+  async _handleLogMessage(data = {}) {
+    const message = data?.message || this._currentMessage();
+    const severity = data?.severity || 'info';
+
+    await this._log(message, severity);
+
+    if (typeof this.lumia.showToast === 'function') {
+      await this.lumia.showToast({
+        message: `${this.manifest?.name ?? 'Plugin'}: ${message}`,
+        time: 4,
+      });
+    }
+
+    if (this.settings.autoAlert === 'after-log') {
+      await this._triggerSampleAlert({
+        color: this.settings.favoriteColor,
+        duration: DEFAULTS.alertDuration,
+      });
+    }
+  }
+
+  async _handleUpdateVariable(data = {}) {
+    const value = data?.value ?? new Date().toISOString();
+    await this._rememberMessage(value);
+    await this._log(`Stored variable value: ${value}`);
+  }
+
+  async _triggerSampleAlert(data = {}) {
+    const color =
+      data?.color ||
+      this.settings?.favoriteColor ||
+      DEFAULTS.color;
+    const duration = Number(data?.duration) || DEFAULTS.alertDuration;
+
+    try {
+      const success = await this.lumia.triggerAlert({
+        alert: 'sample_light',
+        extraSettings: { color, duration },
+      });
+
+      if (!success) {
+        await this._log('Sample alert reported failure', 'warn');
+        return;
+      }
+
+      await this.lumia.setVariable(VARIABLE_NAMES.lastAlertColor, color);
+      await this._log(`Triggered sample alert with color ${color} for ${duration}s`);
+    } catch (error) {
+      await this._log(`Failed to trigger sample alert: ${error.message ?? error}`, 'error');
+    }
+  }
+}
+
+module.exports = ShowcasePluginTemplate;

package/examples/base-plugin/manifest.json

@@ -0,0 +1,151 @@
+{
+	"id": "showcase-plugin",
+	"name": "Showcase Plugin",
+	"version": "1.0.0",
+	"author": "LumiaStream",
+	"email": "",
+	"website": "",
+	"repository": "",
+	"description": "Sample plugin that demonstrates Lumia Stream logging, variables, alerts, and settings.",
+	"longDescription": "",
+	"license": "MIT",
+	"lumiaVersion": "^9.0.0",
+	"keywords": ["sample", "demo", "lumia"],
+	"category": "examples",
+	"icon": "",
+	"screenshots": [],
+	"changelog": "",
+	"config": {
+		"settings": [
+			{
+				"key": "welcomeMessage",
+				"label": "Welcome Message",
+				"type": "text",
+				"defaultValue": "Hello from Showcase Plugin!",
+				"helperText": "Shown when the plugin loads and stored in the sample variable."
+			},
+			{
+				"key": "favoriteColor",
+				"label": "Favorite Color",
+				"type": "color",
+				"defaultValue": "#00c2ff",
+				"helperText": "Used when triggering the sample light alert."
+			},
+			{
+				"key": "autoAlert",
+				"label": "Trigger Sample Alert",
+				"type": "select",
+				"defaultValue": "never",
+				"options": [
+					{ "label": "Never", "value": "never" },
+					{ "label": "On Load", "value": "load" },
+					{ "label": "After Log Action", "value": "after-log" }
+				],
+				"helperText": "Automatically fire the sample alert at different times."
+			}
+		],
+		"actions": [
+			{
+				"type": "log_message",
+				"label": "Log Message",
+				"description": "Write a formatted message to the Lumia log panel and optionally trigger the sample alert.",
+				"fields": [
+					{
+						"key": "message",
+						"label": "Message",
+						"type": "text",
+						"defaultValue": "Hello from Showcase Plugin!"
+					},
+					{
+						"key": "severity",
+						"label": "Severity",
+						"type": "select",
+						"defaultValue": "info",
+						"options": [
+							{ "label": "Info", "value": "info" },
+							{ "label": "Warning", "value": "warn" },
+							{ "label": "Error", "value": "error" }
+						]
+					}
+				]
+			},
+			{
+				"type": "update_variable",
+				"label": "Update Variable",
+				"description": "Persist a value into the sample Lumia variable.",
+				"fields": [
+					{
+						"key": "value",
+						"label": "Value",
+						"type": "text",
+						"defaultValue": "Triggered from an action"
+					}
+				]
+			},
+			{
+				"type": "trigger_alert",
+				"label": "Trigger Sample Alert",
+				"description": "Fire the sample alert with optional overrides.",
+				"fields": [
+					{
+						"key": "color",
+						"label": "Color",
+						"type": "color",
+						"defaultValue": "#ff5f5f"
+					},
+					{
+						"key": "duration",
+						"label": "Duration (seconds)",
+						"type": "number",
+						"defaultValue": 5,
+						"min": 1,
+						"max": 60
+					}
+				]
+			}
+		],
+		"variables": [
+			{
+				"name": "last_message",
+				"system": false,
+				"origin": "showcase-plugin",
+				"allowedPlaces": ["automations", "overlays"],
+				"description": "Stores the most recent message handled by the plugin.",
+				"value": "",
+				"example": "Hello from Showcase Plugin!"
+			},
+			{
+				"name": "last_alert_color",
+				"system": false,
+				"origin": "showcase-plugin",
+				"allowedPlaces": ["automations", "overlays"],
+				"description": "Tracks the color used by the latest sample alert.",
+				"value": "",
+				"example": "#00c2ff"
+			}
+		],
+		"alerts": [
+			{
+				"id": "sample_light",
+				"label": "Sample Light Alert",
+				"description": "Change lights to the selected color for a few seconds.",
+				"fields": [
+					{
+						"key": "color",
+						"label": "Color",
+						"type": "color",
+						"defaultValue": "#00c2ff"
+					},
+					{
+						"key": "duration",
+						"label": "Duration (seconds)",
+						"type": "number",
+						"defaultValue": 5,
+						"min": 1,
+						"max": 60
+					}
+				]
+			}
+		]
+	}
+}

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 logging, variables, actions, and alerts for Lumia Stream plugins.",
+  "main": "main.js",
+  "dependencies": {
+    "@lumiastream/plugin-sdk": "^0.1.0"
+  }
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+	"name": "lumia-plugin",
+	"version": "0.1.4",
+	"description": "Command-line tools for creating, building, and validating Lumia Stream plugins.",
+	"bin": {
+		"lumia-plugin": "scripts/cli.js"
+	},
+	"files": [
+		"scripts",
+		"examples/base-plugin",
+		"README.md",
+		"LICENSE"
+	],
+	"keywords": [
+		"lumia",
+		"stream",
+		"plugin",
+		"cli"
+	],
+	"author": "Lumia Stream",
+	"license": "MIT",
+	"dependencies": {
+		"jszip": "3.10.1"
+	}
+}

package/scripts/build-plugin.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+const path = require("path");
+const fs = require("fs");
+const {
+	readManifest,
+	validateManifest,
+	collectFiles,
+	createPluginArchive,
+} = require("./utils");
+
+function parseArgs() {
+	const args = process.argv.slice(2);
+	const options = { dir: process.cwd(), outFile: null };
+	while (args.length) {
+		const arg = args.shift();
+		switch (arg) {
+			case "--dir":
+			case "-d":
+				options.dir = path.resolve(args.shift() || ".");
+				break;
+			case "--out":
+			case "-o":
+				options.outFile = path.resolve(args.shift() || "");
+				break;
+			case "--help":
+			case "-h":
+				printHelp();
+				process.exit(0);
+			default:
+				// treat as directory if first positional
+				if (!options._positional) {
+					options.dir = path.resolve(arg);
+					options._positional = true;
+				} else {
+					console.warn(`Ignoring unknown argument: ${arg}`);
+				}
+				break;
+		}
+	}
+	return options;
+}
+
+function printHelp() {
+	console.log(`Build a .lumiaplugin archive for distribution.
+
+Usage: npx @lumiastream/plugin-cli build [options]
+
+Options:
+  --dir, -d   Plugin directory (defaults to cwd)
+  --out, -o   Output file path (defaults to ./<id>-<version>.lumiaplugin)
+  --help, -h  Show this help message
+`);
+}
+
+async function main() {
+	const options = parseArgs();
+	const pluginDir = options.dir;
+
+	try {
+		await fs.promises.access(pluginDir, fs.constants.R_OK);
+	} catch (error) {
+		console.error(`✖ Unable to access plugin directory: ${pluginDir}`);
+		process.exit(1);
+	}
+
+	try {
+		const { manifest } = await readManifest(pluginDir);
+		const errors = validateManifest(manifest);
+		if (errors.length) {
+			console.error("✖ Plugin manifest validation failed:");
+			errors.forEach((err) => console.error(`  • ${err}`));
+			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?)"
+			);
+			process.exit(1);
+		}
+
+		const filename = `${manifest.id}-${manifest.version}.lumiaplugin`;
+		const outputPath = options.outFile
+			? options.outFile
+			: path.resolve(filename);
+		await createPluginArchive(pluginDir, outputPath, files);
+
+		console.log("✔ Plugin package created");
+		console.log(`  - output: ${outputPath}`);
+		console.log(`  - files: ${files.length}`);
+	} catch (error) {
+		console.error(`✖ Build failed: ${error.message}`);
+		process.exit(1);
+	}
+}
+
+main();

package/scripts/cli.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+const { spawn } = require("child_process");
+const path = require("path");
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+const commands = {
+	create: "create-plugin.js",
+	build: "build-plugin.js",
+	validate: "validate-plugin.js",
+};
+
+const scriptArgs = args.slice(1);
+
+if (!command || !commands[command]) {
+	console.log(`Lumia Stream Plugin CLI
+
+Usage: lumia-plugin <command> [options]
+
+Commands:
+  create [directory]     Create a new plugin from template
+  build [directory]      Build a plugin into .lumiaplugin package
+  validate [file]        Validate a .lumiaplugin package
+
+Examples:
+  lumia-plugin create my-plugin
+  lumia-plugin build ./my-plugin
+  lumia-plugin validate my-plugin.lumiaplugin
+`);
+	process.exit(command ? 1 : 0);
+}
+
+const scriptPath = path.join(__dirname, commands[command]);
+
+const child = spawn("node", [scriptPath, ...scriptArgs], {
+	stdio: "inherit",
+	cwd: process.cwd(),
+});
+
+child.on("exit", (code) => {
+	process.exit(code || 0);
+});

package/scripts/create-plugin.js

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+const path = require("path");
+const fs = require("fs");
+
+const TEMPLATE_DIR = path.resolve(__dirname, "..", "examples", "base-plugin");
+
+function toKebabCase(value) {
+  return (
+    value
+      .trim()
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "") || "my-plugin"
+  );
+}
+
+function toDisplayName(id) {
+  return id
+    .split("-")
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(" ");
+}
+
+function printHelp() {
+  console.log(`Scaffold a new Lumia Stream plugin directory using the showcase template.\n\nUsage: npx @lumiastream/plugin-cli create [target-directory]\n\nExamples:\n  npx @lumiastream/plugin-cli create ./plugins/my-plugin\n  npx @lumiastream/plugin-cli create my-awesome-plugin\n`);
+}
+
+async function ensureEmptyDir(targetDir) {
+  try {
+    const stats = await fs.promises.stat(targetDir);
+    if (!stats.isDirectory()) {
+      throw new Error("Target path exists and is not a directory");
+    }
+    const contents = await fs.promises.readdir(targetDir);
+    if (contents.length > 0) {
+      throw new Error("Target directory must be empty");
+    }
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      await fs.promises.mkdir(targetDir, { recursive: true });
+      return;
+    }
+    throw error;
+  }
+}
+
+async function copyTemplate(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 copyTemplate(path.join(src, entry), path.join(dest, entry));
+    }
+  } else if (stats.isFile()) {
+    await fs.promises.copyFile(src, dest);
+  }
+}
+
+function ensureArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+async function updateManifest(manifestPath, pluginId, displayName) {
+  const raw = await fs.promises.readFile(manifestPath, "utf8");
+  const manifest = JSON.parse(raw);
+
+  manifest.id = pluginId;
+  manifest.name = displayName;
+  manifest.description = manifest.description?.trim()
+    ? manifest.description
+    : `Describe what ${displayName} does.`;
+  manifest.longDescription = manifest.longDescription || "";
+  manifest.repository = manifest.repository || "";
+  manifest.website = manifest.website || "";
+  manifest.email = manifest.email || "";
+  manifest.icon = manifest.icon || "";
+  manifest.screenshots = ensureArray(manifest.screenshots);
+  manifest.changelog = manifest.changelog || "";
+  manifest.keywords = ensureArray(manifest.keywords);
+
+  if (!manifest.keywords.includes(pluginId)) {
+    manifest.keywords.push(pluginId);
+  }
+
+  if (!manifest.main) {
+    manifest.main = "main.js";
+  }
+
+  if (manifest.config && typeof manifest.config === "object") {
+    const { settings, actions, variables } = manifest.config;
+
+    const welcomeSetting = ensureArray(settings).find(
+      (setting) => setting?.key === "welcomeMessage"
+    );
+    if (welcomeSetting) {
+      welcomeSetting.defaultValue = `Hello from ${displayName}!`;
+    }
+
+    const logAction = ensureArray(actions).find(
+      (action) => action?.type === "log_message"
+    );
+    if (logAction && Array.isArray(logAction.fields)) {
+      const messageField = logAction.fields.find((field) => field?.key === "message");
+      if (messageField) {
+        messageField.defaultValue = `Hello from ${displayName}!`;
+      }
+    }
+
+    for (const variable of ensureArray(variables)) {
+      if (!variable || typeof variable !== "object") continue;
+      if (variable.origin) {
+        variable.origin = pluginId;
+      }
+      if (variable.name === "last_message" && "example" in variable) {
+        variable.example = `Hello from ${displayName}!`;
+      }
+    }
+  }
+
+  await fs.promises.writeFile(manifestPath, JSON.stringify(manifest, null, 2));
+}
+
+async function updateMain(mainPath, pluginId, className, displayName) {
+  let source = await fs.promises.readFile(mainPath, "utf8");
+  source = source.replace(
+    /class\s+ShowcasePluginTemplate\s+extends\s+Plugin/,
+    `class ${className} extends Plugin`
+  );
+  source = source.replace(
+    /module\.exports\s*=\s*ShowcasePluginTemplate;/,
+    `module.exports = ${className};`
+  );
+  source = source.replace(/Hello from Showcase Plugin!/g, `Hello from ${displayName}!`);
+  source = source.replace(/Showcase Plugin/g, displayName);
+  source = source.replace(/showcase-plugin/g, pluginId);
+  await fs.promises.writeFile(mainPath, source);
+}
+
+async function updatePackageJson(packagePath, pluginId, displayName) {
+  if (!fs.existsSync(packagePath)) return;
+  const pkg = JSON.parse(await fs.promises.readFile(packagePath, "utf8"));
+  pkg.name = `lumia-plugin-${pluginId}`;
+  pkg.description = pkg.description || `${displayName} for Lumia Stream`;
+  await fs.promises.writeFile(packagePath, JSON.stringify(pkg, null, 2));
+}
+
+async function updateReadme(readmePath, displayName) {
+  if (!fs.existsSync(readmePath)) return;
+  let content = await fs.promises.readFile(readmePath, "utf8");
+  content = content.replace(/^# .*$/m, `# ${displayName}`);
+  await fs.promises.writeFile(readmePath, content);
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.includes("--help") || args.includes("-h")) {
+    printHelp();
+    return;
+  }
+
+  if (!fs.existsSync(TEMPLATE_DIR)) {
+    console.error("✖ Template directory not found:", TEMPLATE_DIR);
+    process.exit(1);
+  }
+
+  const targetDir = path.resolve(args[0] || "my-plugin");
+  const pluginId = toKebabCase(path.basename(targetDir));
+  const displayName = toDisplayName(pluginId) || "My Plugin";
+  const className = displayName.replace(/[^a-zA-Z0-9]/g, "") || "MyPlugin";
+
+  try {
+    await ensureEmptyDir(targetDir);
+    await copyTemplate(TEMPLATE_DIR, targetDir);
+
+    await updateManifest(
+      path.join(targetDir, "manifest.json"),
+      pluginId,
+      displayName
+    );
+    await updateMain(
+      path.join(targetDir, "main.js"),
+      pluginId,
+      className,
+      displayName
+    );
+    await updatePackageJson(
+      path.join(targetDir, "package.json"),
+      pluginId,
+      displayName
+    );
+    await updateReadme(path.join(targetDir, "README.md"), displayName);
+
+    console.log("✔ Plugin scaffold created");
+    console.log(`  - directory: ${targetDir}`);
+    console.log("  - manifest.json");
+    console.log("  - main.js");
+    if (fs.existsSync(path.join(targetDir, "README.md"))) {
+      console.log("  - README.md");
+    }
+    if (fs.existsSync(path.join(targetDir, "package.json"))) {
+      console.log("  - package.json");
+    }
+  } catch (error) {
+    console.error(`✖ Failed to create plugin: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+main();

package/scripts/utils.js

@@ -0,0 +1,109 @@
+const fs = require('fs');
+const path = require('path');
+const JSZip = require('jszip');
+
+const DEFAULT_IGNORE = new Set([
+  '.git',
+  '.DS_Store',
+  'Thumbs.db',
+  'package-lock.json',
+  'yarn.lock',
+  '.npmrc',
+  '.gitignore',
+]);
+
+function toPosix(p) {
+  return p.split(path.sep).join('/');
+}
+
+async function readManifest(pluginDir) {
+  const manifestPath = path.join(pluginDir, 'manifest.json');
+  const raw = await fs.promises.readFile(manifestPath, 'utf8');
+  return { manifest: JSON.parse(raw), manifestPath };
+}
+
+function validateManifest(manifest) {
+  const errors = [];
+  const requiredStringFields = ['id', 'name', 'version', 'author', 'description', 'license', 'lumiaVersion'];
+  for (const field of requiredStringFields) {
+    const value = manifest[field];
+    if (typeof value !== 'string' || value.trim().length === 0) {
+      errors.push(`Missing or invalid manifest field: ${field}`);
+    }
+  }
+
+  if (!manifest.category || (typeof manifest.category !== 'string' && !Array.isArray(manifest.category))) {
+    errors.push('Manifest must declare a category string');
+  }
+
+  if (!manifest.config || typeof manifest.config !== 'object') {
+    errors.push('Manifest config must be an object');
+  }
+
+  if (manifest.config) {
+    if (manifest.config.settings && !Array.isArray(manifest.config.settings)) {
+      errors.push('config.settings must be an array when provided');
+    }
+    if (manifest.config.actions && !Array.isArray(manifest.config.actions)) {
+      errors.push('config.actions must be an array when provided');
+    }
+    if (manifest.config.variables && !Array.isArray(manifest.config.variables)) {
+      errors.push('config.variables must be an array when provided');
+    }
+    if (manifest.config.alerts && !Array.isArray(manifest.config.alerts)) {
+      errors.push('config.alerts must be an array when provided');
+    }
+  }
+
+  return errors;
+}
+
+async function collectFiles(pluginDir, ignore = DEFAULT_IGNORE) {
+  const entries = [];
+
+  async function walk(currentDir) {
+    const list = await fs.promises.readdir(currentDir, { withFileTypes: true });
+    for (const entry of list) {
+      if (ignore.has(entry.name)) continue;
+      const absolute = path.join(currentDir, entry.name);
+      const relative = path.relative(pluginDir, absolute);
+      if (!relative || relative.startsWith('..')) continue;
+
+      // Skip bundled Lumia packages in node_modules
+      if (relative === 'node_modules/@lumiastream'
+          || relative.startsWith('node_modules/@lumiastream/plugin-sdk')
+          || relative.startsWith('node_modules/@lumiastream/plugin-cli')) {
+        continue;
+      }
+
+      if (entry.isDirectory()) {
+        await walk(absolute);
+      } else if (entry.isFile()) {
+        entries.push({ absolute, relative: toPosix(relative) });
+      }
+    }
+  }
+
+  await walk(pluginDir);
+  return entries;
+}
+
+async function createPluginArchive(pluginDir, outputFile, files) {
+  const zip = new JSZip();
+  for (const file of files) {
+    const data = await fs.promises.readFile(file.absolute);
+    zip.file(file.relative, data);
+  }
+  const content = await zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE', compressionOptions: { level: 9 } });
+  await fs.promises.mkdir(path.dirname(outputFile), { recursive: true });
+  await fs.promises.writeFile(outputFile, content);
+  return outputFile;
+}
+
+module.exports = {
+  readManifest,
+  validateManifest,
+  collectFiles,
+  createPluginArchive,
+  DEFAULT_IGNORE,
+};

package/scripts/validate-plugin.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+const path = require('path');
+const fs = require('fs');
+const { readManifest, validateManifest } = require('./utils');
+
+async function main() {
+  const target = process.argv[2] ? path.resolve(process.argv[2]) : process.cwd();
+
+  try {
+    await fs.promises.access(target, fs.constants.R_OK);
+  } catch (error) {
+    console.error(`✖ Unable to access plugin directory: ${target}`);
+    process.exit(1);
+  }
+
+  try {
+    const { manifest, manifestPath } = await readManifest(target);
+    const errors = validateManifest(manifest);
+
+    const mainFile = manifest.main || 'main.js';
+    const mainPath = path.join(target, mainFile);
+    if (!fs.existsSync(mainPath)) {
+      errors.push(`Main file not found: ${mainFile}`);
+    }
+
+    if (manifest.config?.actions) {
+      manifest.config.actions.forEach((action, index) => {
+        if (!action.type) {
+          errors.push(`config.actions[${index}] is missing required field "type"`);
+        }
+        if (!Array.isArray(action.fields)) {
+          errors.push(`config.actions[${index}].fields must be an array`);
+        }
+      });
+    }
+
+    if (manifest.config?.settings) {
+      manifest.config.settings.forEach((setting, index) => {
+        if (!setting.key) {
+          errors.push(`config.settings[${index}] is missing required field "key"`);
+        }
+        if (!setting.type) {
+          errors.push(`config.settings[${index}] is missing required field "type"`);
+        }
+      });
+    }
+
+    if (errors.length) {
+      console.error('✖ Plugin validation failed:');
+      errors.forEach((err) => console.error(`  • ${err}`));
+      process.exit(1);
+    }
+
+    console.log('✔ Plugin manifest passed validation');
+    console.log(`  - manifest: ${manifestPath}`);
+    console.log(`  - main: ${mainFile}`);
+  } catch (error) {
+    console.error(`✖ Validation error: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+main();