lumia-plugin 0.1.5 → 0.1.6

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/package.json

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

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 lumia-plugin create [target-directory]\n\nExamples:\n  npx lumia-plugin create ./plugins/my-plugin\n  npx lumia-plugin 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();