lumia-plugin 0.1.4 → 0.1.6

package/README.md

@@ -1,13 +1,13 @@
 # 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.
+The `lumia-plugin` 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>
+npx lumia-plugin create <directory>
+npx lumia-plugin build [--dir <path>] [--out <file>]
+npx lumia-plugin validate <plugin-directory>
 ```
 
 Run any command with `--help` to see detailed options.

package/examples/base-plugin/GETTING_STARTED.md

@@ -0,0 +1,243 @@
+# Getting Started with Showcase Plugin Template
+
+Welcome to your new Lumia Stream plugin! This guide will help you understand the plugin structure and start building your custom functionality.
+
+## Project Structure
+
+```
+your-plugin/
+├── manifest.json    # Plugin metadata and configuration
+├── main.js          # Your plugin's main code
+├── package.json     # npm dependencies (optional)
+└── README.md        # Plugin documentation
+```
+
+## Understanding the Files
+
+### 📋 manifest.json
+
+This file defines your plugin's metadata and capabilities:
+
+- **id**: Unique identifier (kebab-case, e.g., "my-awesome-plugin")
+- **name**: Display name shown to users
+- **description**: Short description for the plugin marketplace
+- **main**: Entry point file (usually "main.js")
+- **config**: Defines settings, actions, and variables
+
+**Key sections:**
+- `settings`: User-configurable options for your plugin
+- `actions`: Functions users can trigger (e.g., send a message, change color)
+- `variables`: Data your plugin exposes to Lumia Stream
+
+### 🔧 main.js
+
+Your plugin's logic lives here. The main class extends the `Plugin` base class:
+
+```javascript
+class YourPlugin extends Plugin {
+  constructor(props) {
+    super(props);
+    // Initialize your plugin
+  }
+
+  async onload() {
+    // Called when plugin is loaded
+  }
+
+  async onsettingsupdate() {
+    // Called when settings change
+  }
+
+  async onunload() {
+    // Called when plugin is unloaded
+  }
+}
+```
+
+## Common Tasks
+
+### Adding a New Setting
+
+1. Edit `manifest.json` in the `config.settings` array:
+
+```json
+{
+  "key": "myNewSetting",
+  "label": "My New Setting",
+  "type": "text",
+  "defaultValue": "default value",
+  "required": false
+}
+```
+
+2. Access in `main.js`:
+
+```javascript
+const value = this.getSetting('myNewSetting');
+```
+
+### Adding a New Action
+
+1. Define in `manifest.json` under `config.actions`:
+
+```json
+{
+  "type": "my_custom_action",
+  "label": "Do Something Cool",
+  "fields": [
+    {
+      "key": "message",
+      "label": "Message",
+      "type": "text",
+      "required": true
+    }
+  ]
+}
+```
+
+2. Handle in `main.js`:
+
+```javascript
+async onAction(action) {
+  if (action.type === 'my_custom_action') {
+    const message = action.fields.message;
+    // Your logic here
+  }
+}
+```
+
+### Creating Variables
+
+Variables let other Lumia features access your plugin's data:
+
+1. Define in `manifest.json` under `config.variables`:
+
+```json
+{
+  "name": "my_variable",
+  "key": "myVariable",
+  "origin": "your-plugin-id",
+  "type": "string",
+  "example": "Sample value"
+}
+```
+
+2. Update in `main.js`:
+
+```javascript
+this.setVariable('myVariable', 'new value');
+```
+
+## Testing Your Plugin
+
+1. **Install dependencies** (if using package.json):
+   ```bash
+   npm install
+   ```
+
+2. **Load in Lumia Stream**:
+   - Open Lumia Stream
+   - Go to Plugins section
+   - Load your plugin directory
+   - Enable your plugin
+
+3. **Check logs**:
+   ```javascript
+   this.log('Debug message');
+   this.error('Error message');
+   ```
+
+## Next Steps
+
+- [ ] Customize `manifest.json` with your plugin details
+- [ ] Update the plugin name and description
+- [ ] Add your custom settings
+- [ ] Implement your actions
+- [ ] Test your plugin in Lumia Stream
+- [ ] Write tests (optional)
+- [ ] Update README.md with usage instructions
+
+## API Reference
+
+### Plugin Methods
+
+- `this.getSetting(key)` - Get a setting value
+- `this.setVariable(key, value)` - Update a variable
+- `this.log(message)` - Log info message
+- `this.error(message)` - Log error message
+- `this.sendAlert(type, data)` - Trigger an alert
+
+### Lifecycle Hooks
+
+- `onload()` - Plugin initialization
+- `onunload()` - Cleanup when plugin is disabled
+- `onsettingsupdate()` - Respond to setting changes
+- `onAction(action)` - Handle triggered actions
+
+## Common Patterns
+
+### Making HTTP Requests
+
+```javascript
+const response = await fetch('https://api.example.com/data');
+const data = await response.json();
+```
+
+### Using Timers
+
+```javascript
+async onload() {
+  this.interval = setInterval(() => {
+    // Do something periodically
+  }, 5000);
+}
+
+async onunload() {
+  if (this.interval) {
+    clearInterval(this.interval);
+  }
+}
+```
+
+### Error Handling
+
+```javascript
+try {
+  // Your code
+} catch (error) {
+  this.error(`Something went wrong: ${error.message}`);
+}
+```
+
+## Troubleshooting
+
+**Plugin not loading?**
+- Check manifest.json syntax (use a JSON validator)
+- Ensure the `main` field points to the correct file
+- Check Lumia Stream logs for errors
+
+**Settings not showing?**
+- Verify the `settings` array in manifest.json
+- Ensure required fields are filled
+
+**Actions not working?**
+- Check the action type matches your handler
+- Verify field keys match what you're accessing
+
+## Resources
+
+- [Lumia Stream Documentation](https://docs.lumiastream.com)
+- [Plugin API Reference](https://docs.lumiastream.com/plugins/api)
+- [Example Plugins](https://github.com/lumiastream/plugins)
+- [Community Discord](https://discord.gg/lumiastream)
+
+## Need Help?
+
+- Join the Lumia Stream Discord community
+- Check the documentation
+- Review example plugins
+- Ask questions in the developer channel
+
+---
+
+Happy coding! 🚀

package/examples/base-plugin/README.md

@@ -11,7 +11,7 @@ This template demonstrates a handful of common Lumia Stream plugin capabilities:
 Use the CLI to copy and customise the template:
 
 ```
-npx @lumiastream/plugin-cli create my-plugin
+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

@@ -1,143 +1,150 @@
-const { Plugin } = require('@lumiastream/plugin-sdk');
+const { Plugin } = require("@lumiastream/plugin");
 
 const VARIABLE_NAMES = {
-  lastMessage: 'last_message',
-  lastAlertColor: 'last_alert_color',
+	lastMessage: "last_message",
+	lastAlertColor: "last_alert_color",
 };
 
 const DEFAULTS = {
-  welcomeMessage: 'Hello from Showcase Plugin!',
-  color: '#00c2ff',
-  alertDuration: 5,
+	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');
-    }
-  }
+	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/package.json

@@ -1,10 +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"
-  }
+	"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": "^0.1.0"
+	}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "lumia-plugin",
-	"version": "0.1.4",
+	"version": "0.1.6",
 	"description": "Command-line tools for creating, building, and validating Lumia Stream plugins.",
 	"bin": {
 		"lumia-plugin": "scripts/cli.js"

package/scripts/build-plugin.js

@@ -43,7 +43,7 @@ function parseArgs() {
 function printHelp() {
 	console.log(`Build a .lumiaplugin archive for distribution.
 
-Usage: npx @lumiastream/plugin-cli build [options]
+Usage: npx lumia-plugin build [options]
 
 Options:
   --dir, -d   Plugin directory (defaults to cwd)

package/scripts/create-plugin.js

@@ -5,207 +5,264 @@ 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"
-  );
+	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(" ");
+	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`);
+	console.log(
+		`Scaffold a new Lumia Stream plugin directory using the showcase template.\n\nUsage: npx lumia-plugin create [target-directory]\n\nExamples:\n  npx lumia-plugin create ./plugins/my-plugin\n  npx lumia-plugin 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;
-  }
+	try {
+		const stats = await fs.promises.stat(targetDir);
+		if (!stats.isDirectory()) {
+			throw new Error(
+				`Path '${path.basename(
+					targetDir
+				)}' exists and is not a directory.\n   Tip: Choose a different name or remove the existing file.`
+			);
+		}
+		const contents = await fs.promises.readdir(targetDir);
+		if (contents.length > 0) {
+			throw new Error(
+				`Directory '${path.basename(
+					targetDir
+				)}' already exists and is not empty.\n   Tip: Use a different name or remove existing files first.`
+			);
+		}
+	} 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);
-  }
+	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 : [];
+	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));
+	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);
+	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));
+	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);
+	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 updateGettingStarted(gettingStartedPath, displayName) {
+	if (!fs.existsSync(gettingStartedPath)) return;
+	let content = await fs.promises.readFile(gettingStartedPath, "utf8");
+	content = content.replace(
+		/^# Getting Started with .*$/m,
+		`# Getting Started with ${displayName}`
+	);
+	content = content.replace(/Showcase Plugin Template/g, displayName);
+	await fs.promises.writeFile(gettingStartedPath, 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);
-  }
+	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);
+		console.error("   Tip: Make sure lumia-plugin is properly installed.");
+		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 {
+		console.log("⏳ Creating plugin scaffold...\n");
+
+		console.log("  📁 Creating directory...");
+		await ensureEmptyDir(targetDir);
+
+		console.log("  📋 Copying template files...");
+		await copyTemplate(TEMPLATE_DIR, targetDir);
+
+		console.log("  ✏️  Updating manifest.json...");
+		await updateManifest(
+			path.join(targetDir, "manifest.json"),
+			pluginId,
+			displayName
+		);
+
+		console.log("  ✏️  Updating main.js...");
+		await updateMain(
+			path.join(targetDir, "main.js"),
+			pluginId,
+			className,
+			displayName
+		);
+
+		console.log("  ✏️  Updating package.json...");
+		await updatePackageJson(
+			path.join(targetDir, "package.json"),
+			pluginId,
+			displayName
+		);
+
+		console.log("  ✏️  Updating README.md...");
+		await updateReadme(path.join(targetDir, "README.md"), displayName);
+
+		console.log("  ✏️  Updating GETTING_STARTED.md...");
+		await updateGettingStarted(
+			path.join(targetDir, "GETTING_STARTED.md"),
+			displayName
+		);
+
+		console.log("\n✅ Plugin scaffold created successfully!\n");
+		console.log("📦 Created files:");
+		console.log(`  - ${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, "GETTING_STARTED.md"))) {
+			console.log("  - GETTING_STARTED.md");
+		}
+		if (fs.existsSync(path.join(targetDir, "package.json"))) {
+			console.log("  - package.json");
+		}
+
+		console.log("\n🚀 Next steps:");
+		console.log(`  1. cd ${path.basename(targetDir)}`);
+		console.log("  2. npm install");
+		console.log("  3. Read GETTING_STARTED.md for a complete guide");
+		console.log("  4. Edit manifest.json to configure your plugin");
+		console.log("  5. Start coding in main.js");
+		console.log("\n📖 Learn more: https://docs.lumiastream.com");
+	} catch (error) {
+		console.error(`\n✖ Failed to create plugin: ${error.message}`);
+		process.exit(1);
+	}
 }
 
 main();

package/scripts/utils.js

@@ -1,109 +1,129 @@
-const fs = require('fs');
-const path = require('path');
-const JSZip = require('jszip');
+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',
+	".git",
+	".DS_Store",
+	"Thumbs.db",
+	"package-lock.json",
+	"yarn.lock",
+	".npmrc",
+	".gitignore",
 ]);
 
 function toPosix(p) {
-  return p.split(path.sep).join('/');
+	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 };
+	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}`);
-    }
-  }
+	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.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 || 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');
-    }
-  }
+	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;
+	return errors;
 }
 
 async function collectFiles(pluginDir, ignore = DEFAULT_IGNORE) {
-  const entries = [];
+	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;
+	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;
-      }
+			// Skip bundled Lumia packages in node_modules
+			if (
+				relative === "node_modules/@lumiastream" ||
+				relative.startsWith("node_modules/@lumiastream/plugin") ||
+				relative.startsWith("node_modules/lumia-plugin")
+			) {
+				continue;
+			}
 
-      if (entry.isDirectory()) {
-        await walk(absolute);
-      } else if (entry.isFile()) {
-        entries.push({ absolute, relative: toPosix(relative) });
-      }
-    }
-  }
+			if (entry.isDirectory()) {
+				await walk(absolute);
+			} else if (entry.isFile()) {
+				entries.push({ absolute, relative: toPosix(relative) });
+			}
+		}
+	}
 
-  await walk(pluginDir);
-  return entries;
+	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;
+	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,
+	readManifest,
+	validateManifest,
+	collectFiles,
+	createPluginArchive,
+	DEFAULT_IGNORE,
 };