pochade-node-red 0.1.0

package/README.md

@@ -0,0 +1,71 @@
+![Pochade Node-RED Splash Image](./pochade-js-logo.jpg)
+
+# Pochade Node-RED
+## For Writing Node-RED Plugins with Passion
+
+Pochade Node-RED is a lightweight, opinionated generator for building Node-RED nodes (plugins) with modern standards but without the bloat. It sets up a clean, vanilla JavaScript environment so you can focus on writing the logic for your node.
+
+## Features
+
+- **Instant Scaffolding** - Generates a complete, ready-to-deploy Node-RED node project.
+- **Auto Reload and Install** - Work in the nodes home directory, our watch script auto-installs and auto-reloads node-red when you make changes in the folder.
+- **Interactive Setup** - easy-to-use CLI questionnaire to configure your node.
+- **Vanilla JS** - No complex build pipelines by default, just standard Node.js and HTML.
+- **Developer Experience** - Includes helper scripts to easily install your plugin into your local Node-RED instance for testing.
+- **AI Ready** - Includes documentation to help AI assistants (`LLM.md`, `AGENTS.md`) understand your project structure.
+
+---
+
+## Quick Start
+
+Create a new Node-RED node project with a single command:
+
+```sh
+npx pochade-node-red my-node-red-plugin
+```
+
+cd into the new directory. 
+
+### Installing to Local Node-RED
+
+To test your node, you need to install it into your local Node-RED environment. We've included a handy script for this:
+
+```sh
+npm run install-plugin
+```
+
+### Watch Mode
+
+If you are making frequent changes, you can use:
+
+```sh
+npm run watch
+```
+
+This will start node-red and on every text change will re-install the plugin to the ~/.node-red node_modules directory and restart node-red. 
+
+---
+
+## Project Structure
+
+```
+my-node-red-plugin/
+├── src/
+│   ├── my-node.js         # The Node.js runtime logic
+│   └── my-node.html       # The Editor UI and help text
+├── bin/                   # Utility scripts
+├── package.json           # Node-RED module metadata
+└── README.md              # Documentation for your user
+```
+
+---
+
+## License
+
+Unlicense (Public Domain)
+
+---
+
+## Contributing
+
+Issues and pull requests welcome at [github.com/lnsy-dev/pochade-node-red](https://github.com/lnsy-dev/pochade-node-red)

package/bin/create-pochade-js.js

@@ -0,0 +1,286 @@
+#!/usr/bin/env node
+
+/**
+ * pochade-node-red
+ * 
+ * Creates a new Pochade Node-RED project from the template.
+ * 
+ * Usage: npx pochade-node-red my-node
+ * 
+ * @module pochade-node-red
+ */
+
+const spawn = require('cross-spawn');
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+/**
+ * Creates a readline interface for user input
+ * 
+ * @returns {readline.Interface} The readline interface
+ */
+function createReadlineInterface() {
+  return readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+}
+
+/**
+ * Prompts the user with a question and returns their answer
+ * 
+ * @param {readline.Interface} rl - The readline interface
+ * @param {string} question - The question to ask
+ * @param {string} defaultValue - Optional default value
+ * @returns {Promise<string>} The user's answer
+ */
+function ask(rl, question, defaultValue = '') {
+  return new Promise((resolve) => {
+    const prompt = defaultValue
+      ? `${question} (${defaultValue}): `
+      : `${question}: `;
+
+    rl.question(prompt, (answer) => {
+      resolve(answer.trim() || defaultValue);
+    });
+  });
+}
+
+/**
+ * Prompts the user with a question and validates the answer
+ * 
+ * @param {readline.Interface} rl - The readline interface
+ * @param {string} question - The question to ask
+ * @param {function} validator - Function that returns true if valid, or a string error message
+ * @param {string} defaultValue - Optional default value
+ * @returns {Promise<string>} The user's answer
+ */
+async function askWithValidation(rl, question, validator, defaultValue = '') {
+  while (true) {
+    const answer = await ask(rl, question, defaultValue);
+    const validation = validator(answer);
+    if (validation === true) {
+      return answer;
+    }
+    console.log(`❌ ${validation}`);
+  }
+}
+
+/**
+ * Validates a package/project name (URL-friendly, no spaces)
+ * @param {string} name 
+ * @returns {boolean|string}
+ */
+function validatePackageName(name) {
+  if (!name) return "Name cannot be empty";
+  if (!/^[a-z0-9-_]+$/.test(name)) {
+    return "Name must only contain lowercase letters, numbers, hyphens, and underscores";
+  }
+  return true;
+}
+
+/**
+ * Validates a node name (safe for filenames)
+ * @param {string} name 
+ * @returns {boolean|string}
+ */
+function validateNodeName(name) {
+  if (!name) return "Name cannot be empty";
+  if (!/^[a-z0-9-]+$/.test(name)) {
+    return "Name must only contain lowercase letters, numbers, and hyphens";
+  }
+  return true;
+}
+
+
+
+/**
+ * Collects project configuration from user input
+ * 
+ * @param {string} projectName - The project name
+ * @returns {Promise<object>} Configuration object with all project details
+ */
+async function collectProjectInfo(projectName) {
+  const rl = createReadlineInterface();
+
+  const logo = ".-. .-. .-. . . .-. .-. .-.   . .-.\r\n|-\' | | |   |-| |-| |  )|-    | `-.\r\n\'   `-\' `-\' \' ` ` \' `-\' `-\' `-\' `-\'\r\n       Node-RED Plugins with Passion\r\n             By LNSY\r\n"
+  console.log(logo);
+
+  console.log('\n📝 Let\'s set up your Node-RED Plugin project!\n');
+
+  // Default node name derived from project name
+  const defaultNodeName = projectName.replace(/^node-red-contrib-/, '');
+
+  const config = {
+    project_name: projectName,
+    project_description: await ask(rl, 'Project description', 'A Node-RED node'),
+    node_sidebar_title: await ask(rl, 'Sidebar title (category)', 'function'),
+    node_name: await askWithValidation(rl, 'Node name', validateNodeName, defaultNodeName),
+    node_purpose: await ask(rl, 'Node purpose', 'Processes messages'),
+    author_name: await ask(rl, 'Author name', ''),
+    license: await ask(rl, 'License', 'MIT')
+  };
+
+
+
+  rl.close();
+
+  return config;
+}
+
+/**
+ * Replaces template variables in a file content
+ * 
+ * @param {string} content - The content with template variables
+ * @param {object} config - Configuration object with values
+ * @returns {string} Content with variables replaced
+ */
+function replaceTemplateVariables(content, config) {
+  return content
+    .replace(/\$\{\s*project_description\s*\}/g, config.project_description)
+    .replace(/\$\{\s*node_sidebar_title\s*\}/g, config.node_sidebar_title)
+    .replace(/\$\{\s*node_name\s*\}/g, config.node_name)
+    .replace(/\$\{\s*node_purpose\s*\}/g, config.node_purpose);
+}
+
+/**
+ * Recursively updates files in the project directory
+ * 
+ * @param {string} dir - Directory to process
+ * @param {object} config - Configuration object
+ */
+function updateFiles(dir, config) {
+  const files = fs.readdirSync(dir);
+
+  for (const file of files) {
+    const filePath = path.join(dir, file);
+    const stats = fs.statSync(filePath);
+
+    if (stats.isDirectory()) {
+      updateFiles(filePath, config);
+    } else {
+      // Only process text files
+      if (['.js', '.html', '.json', '.md'].includes(path.extname(file))) {
+        let content = fs.readFileSync(filePath, 'utf-8');
+        content = replaceTemplateVariables(content, config);
+        fs.writeFileSync(filePath, content, 'utf-8');
+      }
+    }
+  }
+}
+
+/**
+ * Main function to create a new Pochade Node-RED project
+ * 
+ * @returns {Promise<void>}
+ */
+async function createProject() {
+  const projectName = process.argv[2];
+
+  // Validate project name
+  if (!projectName) {
+    console.error('Error: Please specify the project name.');
+    console.log('Usage: npx pochade-node-red <project-name>');
+    process.exit(1);
+  }
+
+  const nameValidation = validatePackageName(projectName);
+  if (nameValidation !== true) {
+    console.error(`Error: Invalid project name "${projectName}".`);
+    console.error(nameValidation);
+    process.exit(1);
+  }
+
+  const currentDir = process.cwd();
+  const projectDir = path.resolve(currentDir, projectName);
+
+  if (fs.existsSync(projectDir)) {
+    console.error(`Error: Directory "${projectName}" already exists.`);
+    process.exit(1);
+  }
+
+  const config = await collectProjectInfo(projectName);
+
+  console.log(`\n🚀 Creating a new Node-RED node in ${projectDir}...`);
+
+  fs.mkdirSync(projectDir, { recursive: true });
+
+  const templateDir = path.resolve(__dirname, '..', 'template');
+
+  if (!fs.existsSync(templateDir)) {
+    console.error('Error: Template directory not found.');
+    process.exit(1);
+  }
+
+  // Copy template
+  fs.cpSync(templateDir, projectDir, { recursive: true });
+
+  // Rename dotfiles
+  const dotfiles = [
+    { from: 'gitignore', to: '.gitignore' },
+    { from: 'npmignore', to: '.npmignore' }
+  ];
+
+  dotfiles.forEach(({ from, to }) => {
+    const fromPath = path.join(projectDir, from);
+    const toPath = path.join(projectDir, to);
+    if (fs.existsSync(fromPath)) {
+      fs.renameSync(fromPath, toPath);
+    }
+  });
+
+  // Rename node files
+  const srcDir = path.join(projectDir, 'src');
+  if (fs.existsSync(srcDir)) {
+    const nodeJsPath = path.join(srcDir, 'sample.js');
+    const nodeHtmlPath = path.join(srcDir, 'sample.html');
+
+    if (fs.existsSync(nodeJsPath)) {
+      fs.renameSync(nodeJsPath, path.join(srcDir, `${config.node_name}.js`));
+    }
+    if (fs.existsSync(nodeHtmlPath)) {
+      fs.renameSync(nodeHtmlPath, path.join(srcDir, `${config.node_name}.html`));
+    }
+  }
+
+  // Update file contents
+  updateFiles(projectDir, config);
+
+  // Update package.json specifically
+  const packageJsonPath = path.join(projectDir, 'package.json');
+  const projectPackageJson = require(packageJsonPath);
+  projectPackageJson.name = config.project_name;
+  projectPackageJson.author = config.author_name;
+  projectPackageJson.license = config.license;
+
+  // Ensure the node-red section points to the correct file
+  if (projectPackageJson['node-red'] && projectPackageJson['node-red'].nodes) {
+    // Reconstruct the nodes object with the new key and value
+    projectPackageJson['node-red'].nodes = {};
+    projectPackageJson['node-red'].nodes[config.node_name] = `src/${config.node_name}.js`;
+  }
+
+  fs.writeFileSync(packageJsonPath, JSON.stringify(projectPackageJson, null, 2));
+
+  console.log('\n📦 Installing dependencies...');
+
+  const installResult = spawn.sync('npm', ['install'], {
+    cwd: projectDir,
+    stdio: 'inherit'
+  });
+
+  if (installResult.status !== 0) {
+    console.error('\n❌ Error: npm install failed.');
+    process.exit(1);
+  }
+
+  console.log('\n✨ Success!');
+  console.log(`\nTo get started:\n`);
+  console.log(`  cd ${projectName}`);
+  console.log(`  npm run install-plugin  # Installs this node to your local Node-RED`);
+  console.log(`  npm run watch           # Develop with auto-restart`);
+  console.log('\n🎨 Happy coding!');
+}
+
+createProject();

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "pochade-node-red",
+  "version": "0.1.0",
+  "description": "A lightweight generator for Node-RED nodes and plugins.",
+  "bin": {
+    "pochade-node-red": "bin/create-pochade-js.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lnsy-dev/pochade-node-red.git"
+  },
+  "keywords": [
+    "node-red",
+    "template",
+    "starter",
+    "vanilla-js",
+    "rspack",
+    "dataroom-js",
+    "custom-elements"
+  ],
+  "author": "LNSY",
+  "license": "Unlicense",
+  "bugs": {
+    "url": "https://github.com/lnsy-dev/pochade-node-red/issues"
+  },
+  "homepage": "https://github.com/lnsy-dev/pochade-node-red#readme",
+  "dependencies": {
+    "cross-spawn": "^7.0.6"
+  },
+  "files": [
+    "bin/",
+    "template/"
+  ]
+}

package/template/AGENTS.md

@@ -0,0 +1,140 @@
+# Node-RED Plugin Implementation Guide for AI Agents
+
+This document provides a comprehensive guide for Large Language Models (LLMs) on how to implement Node-RED plugins (nodes).
+
+## Project Structure
+
+A Node-RED node module typically has the following structure:
+
+```
+package.json
+nodes/
+  <node-name>.js    # Runtime behavior
+  <node-name>.html  # Editor UI and configuration
+```
+
+### package.json
+
+The `package.json` must include a `node-red` section that maps node names to their JavaScript files.
+
+```json
+{
+    "name": "node-red-contrib-example",
+    "version": "1.0.0",
+    "node-red": {
+        "nodes": {
+            "example-node": "nodes/example-node.js"
+        }
+    }
+}
+```
+
+## JavaScript File (.js)
+
+The JavaScript file defines the runtime behavior of the node. It must export a function that registers the node with the Node-RED runtime.
+
+### Template
+
+```javascript
+module.exports = function(RED) {
+    function ExampleNode(config) {
+        RED.nodes.createNode(this, config);
+        var node = this;
+        
+        // Retrieve configuration values
+        node.name = config.name;
+        
+        // Handle incoming messages
+        node.on('input', function(msg, send, done) {
+            // Process the message
+            msg.payload = msg.payload.toLowerCase();
+            
+            // Send the message
+            send(msg);
+            
+            // Signal completion
+            if (done) {
+                done();
+            }
+        });
+        
+        // Clean up on close
+        node.on('close', function() {
+            // Cleanup logic
+        });
+    }
+    
+    // Register the node type
+    RED.nodes.registerType("example-node", ExampleNode);
+}
+```
+
+### Key Concepts
+
+- **RED.nodes.createNode(this, config)**: Initializes the node instance.
+- **this.on('input', ...)**: Listener for incoming messages.
+- **send(msg)**: Sends a message to the next node(s). Configurable to support multiple outputs.
+- **done()**: Callback to signal that processing is complete (for pre-1.0 compatibility loops).
+
+## HTML File (.html)
+
+The HTML file defines the node's appearance in the Node-RED editor, its configuration dialog, and its help text. It contains three script blocks.
+
+### Template
+
+```html
+<!-- Registration and Configuration -->
+<script type="text/javascript">
+    RED.nodes.registerType('example-node', {
+        category: 'function',
+        color: '#a6bbcf',
+        defaults: {
+            name: { value: "" },
+            property: { value: "payload", required: true }
+        },
+        inputs: 1,
+        outputs: 1,
+        icon: "file.png",
+        label: function() {
+            return this.name || "example node";
+        }
+    });
+</script>
+
+<!-- Edit Dialog -->
+<script type="text/html" data-template-name="example-node">
+    <div class="form-row">
+        <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
+        <input type="text" id="node-input-name" placeholder="Name">
+    </div>
+    <div class="form-row">
+        <label for="node-input-property"><i class="fa fa-edit"></i> Property</label>
+        <input type="text" id="node-input-property">
+    </div>
+</script>
+
+<!-- Help Text -->
+<script type="text/html" data-help-name="example-node">
+    <p>A simple node that converts payload to lowercase.</p>
+</script>
+```
+
+### Key Concepts
+
+- **category**: The palette category (e.g., 'input', 'output', 'function', or custom).
+- **defaults**: Defines the configuration properties that are saved and restored.
+- **data-template-name**: Must match the registered type name.
+- **data-help-name**: Must match the registered type name.
+
+## Best Practices
+
+1.  **Error Handling**: Use `node.error("message", msg)` to log errors.
+2.  **Status**: Use `node.status({fill:"red",shape:"ring",text:"disconnected"})` to show status in the editor.
+3.  **Context**: Use `node.context()`, `flow.context()`, or `global.context()` to store state.
+4.  **Dependencies**: Declare any external libraries in `package.json`.
+
+## Development Cycle
+
+1.  **Install**: `npm install` in your node directory.
+2.  **Link**: `npm link` (or `npm install . -g`) to make it available to Node-RED.
+3.  **Restart**: Restart Node-RED to load changes.

package/template/README.md

@@ -0,0 +1,39 @@
+# ${node_name}
+
+${node_purpose}
+
+A Node-RED node component.
+
+## Installation
+
+You can install this node directly from your Node-RED user directory (typically `~/.node-red`):
+
+```bash
+cd ~/.node-red
+npm install ${project_name}
+```
+
+Or if you are developing locally, run `npm run install-plugin` from the project directory.
+
+## Usage
+
+After installing and restarting Node-RED, you will find the **${node_name}** node in the **${node_sidebar_title}** category.
+
+Drag the node onto the canvas and configure it.
+
+
+### Watch Mode
+
+If you are making frequent changes, you can use:
+
+```sh
+npm run watch
+```
+
+This will start node-red and on every text change will re-install the plugin to the ~/.node-red node_modules directory and restart node-red. 
+
+
+
+## License
+
+${license}

package/template/cursor.md

@@ -0,0 +1,4 @@
+# Cursor Rules
+
+You are an expert Node-RED developer.
+Please refer to [AGENTS.md](./AGENTS.md) for specific guidelines on implementing Node-RED nodes in this project.

package/template/gemini.md

@@ -0,0 +1,4 @@
+# Gemini Context
+
+You are assisting with a Node-RED plugin project.
+Consult [AGENTS.md](./AGENTS.md) for the architectural patterns and implementation details required for this codebase.