@bonsae/create-nrg 0.1.0

package/README.md

@@ -0,0 +1,65 @@
+<p align="center">
+  <img alt="nrg-icon" src="https://gist.githubusercontent.com/AllanOricil/84412df273de46b28c5d6945b391afd4/raw/0c9cdb994c40ab3d7b7ad06dcee162145d77d531/nrg-icon.svg" style="width: 200px"/>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@bonsae/create-nrg"><img src="https://img.shields.io/npm/v/@bonsae/create-nrg.svg" alt="npm package"></a>
+  <a href="https://github.com/bonsaedev/create-nrg/actions/workflows/ci.yaml"><img src="https://github.com/bonsaedev/create-nrg/actions/workflows/ci.yaml/badge.svg?branch=main" alt="build status"></a>
+</p>
+
+# create-nrg
+
+Scaffold a new [NRG](https://github.com/bonsaedev/nrg) project for Node-RED.
+
+## Usage
+
+```bash
+pnpm create @bonsae/nrg my-project
+```
+
+```bash
+npm create @bonsae/nrg my-project
+```
+
+```bash
+npx @bonsae/create-nrg my-project
+```
+
+The CLI will prompt you for:
+
+- **Project name**
+- **First node name**
+- **Node category**
+- **Node color** (hex, default `#1A1A1A`)
+- **Node inputs** (0 or 1)
+- **Node outputs**
+
+## Generated project structure
+
+```
+my-project/
+├── .vscode/extensions.json
+├── .husky/
+├── .gitignore
+├── .prettierrc.json
+├── eslint.config.js
+├── commitlint.config.js
+├── package.json
+├── tsconfig.json
+├── vite.config.ts
+└── src/
+    ├── server/
+    │   ├── index.ts
+    │   ├── nodes/<node>.ts
+    │   ├── schemas/<node>.ts
+    │   └── tsconfig.json
+    ├── locales/
+    │   ├── labels/<node>/en-US.json
+    │   └── docs/<node>/en-US.md
+    ├── icons/
+    └── examples/
+```
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+import * as p from "@clack/prompts";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { dashCase, scaffoldProject } from "./scaffold.js";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const TEMPLATES_DIR = path.resolve(__dirname, "../templates");
+async function main() {
+    p.intro("Create a new NRG project");
+    const args = process.argv.slice(2);
+    const positionalName = args.find((a) => !a.startsWith("-"));
+    const project = await p.group({
+        projectName: () => p.text({
+            message: "What would you like to name your project?",
+            placeholder: "nrg-project",
+            defaultValue: positionalName || "nrg-project",
+            initialValue: positionalName,
+            validate: (value) => {
+                if (!value?.trim())
+                    return "Project name is required.";
+            },
+        }),
+        nodeName: () => p.text({
+            message: "What would you like to name your first node?",
+            placeholder: "node-1",
+            defaultValue: "node-1",
+            validate: (value) => {
+                if (!value?.trim())
+                    return "Node name is required.";
+            },
+        }),
+        nodeCategory: () => p.text({
+            message: "Which category should your node belong to?",
+            placeholder: "new category",
+            defaultValue: "new category",
+        }),
+        nodeColor: () => p.text({
+            message: "What color should represent your node? (hex)",
+            placeholder: "#1A1A1A",
+            defaultValue: "#1A1A1A",
+            validate: (value) => {
+                if (!value || !/^#([0-9A-F]{3}|[0-9A-F]{6})$/i.test(value)) {
+                    return "Please enter a valid hex color code (e.g., #1A1A1A or #000)";
+                }
+            },
+        }),
+        nodeInputs: () => p.text({
+            message: "How many inputs should your node have? (0 or 1)",
+            placeholder: "1",
+            defaultValue: "1",
+            validate: (value) => {
+                const n = parseInt(value || "", 10);
+                if (n !== 0 && n !== 1)
+                    return "Inputs must be either 0 or 1.";
+            },
+        }),
+        nodeOutputs: () => p.text({
+            message: "How many outputs should your node have?",
+            placeholder: "1",
+            defaultValue: "1",
+            validate: (value) => {
+                const n = parseInt(value || "", 10);
+                if (isNaN(n) || n < 0)
+                    return "Outputs must be 0 or more.";
+            },
+        }),
+    }, {
+        onCancel: () => {
+            p.cancel("Operation cancelled.");
+            process.exit(0);
+        },
+    });
+    const projectName = project.projectName;
+    const nodeName = project.nodeName;
+    const nodeCategory = project.nodeCategory;
+    const nodeColor = project.nodeColor;
+    const nodeInputs = project.nodeInputs;
+    const nodeOutputs = project.nodeOutputs;
+    const projectDir = path.resolve(process.cwd(), dashCase(projectName));
+    if (fs.existsSync(projectDir)) {
+        p.cancel(`Directory "${dashCase(projectName)}" already exists.`);
+        process.exit(1);
+    }
+    const s = p.spinner();
+    s.start("Scaffolding project...");
+    scaffoldProject(projectDir, TEMPLATES_DIR, {
+        projectName,
+        nodeName,
+        nodeCategory,
+        nodeColor,
+        nodeInputs,
+        nodeOutputs,
+    });
+    s.stop("Project scaffolded.");
+    p.note([`cd ${dashCase(projectName)}`, `pnpm install`, `pnpm run dev`].join("\n"), "Next steps");
+    p.outro("Happy coding!");
+}
+main().catch((err) => {
+    p.cancel("Something went wrong.");
+    console.error(err);
+    process.exit(1);
+});

package/dist/scaffold.js

@@ -0,0 +1,65 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+export function dashCase(str) {
+    return str
+        .replace(/([a-z])([A-Z])/g, "$1-$2")
+        .replace(/[\s_]+/g, "-")
+        .toLowerCase();
+}
+export function pascalCase(str) {
+    return dashCase(str)
+        .split("-")
+        .map((s) => s.charAt(0).toUpperCase() + s.slice(1))
+        .join("");
+}
+export function renderTemplate(content, vars) {
+    return content.replace(/\{\{(\w+)\}\}/g, (_, key) => vars[key] ?? _);
+}
+export function copyTemplateDir(srcDir, destDir, vars) {
+    const entries = fs.readdirSync(srcDir, { withFileTypes: true });
+    for (const entry of entries) {
+        const srcPath = path.join(srcDir, entry.name);
+        const renderedName = renderTemplate(entry.name, vars);
+        const destPath = path.join(destDir, renderedName);
+        if (entry.isDirectory()) {
+            fs.mkdirSync(destPath, { recursive: true });
+            copyTemplateDir(srcPath, destPath, vars);
+        }
+        else if (entry.name.endsWith(".hbs")) {
+            const outPath = destPath.replace(/\.hbs$/, "");
+            const content = fs.readFileSync(srcPath, "utf-8");
+            fs.writeFileSync(outPath, renderTemplate(content, vars));
+        }
+        else {
+            fs.copyFileSync(srcPath, destPath);
+        }
+    }
+}
+export function renderTemplateFile(templatePath, destPath, vars) {
+    const content = fs.readFileSync(templatePath, "utf-8");
+    fs.mkdirSync(path.dirname(destPath), { recursive: true });
+    fs.writeFileSync(destPath, renderTemplate(content, vars));
+}
+export function scaffoldProject(destDir, templatesDir, options) {
+    const vars = {
+        projectName: dashCase(options.projectName),
+        nodeName: options.nodeName,
+        dashCaseNodeName: dashCase(options.nodeName),
+        pascalCaseNodeName: pascalCase(options.nodeName),
+        nodeCategory: options.nodeCategory,
+        nodeColor: options.nodeColor,
+        nodeInputs: options.nodeInputs,
+        nodeOutputs: options.nodeOutputs,
+    };
+    fs.mkdirSync(destDir, { recursive: true });
+    // Copy project-level templates (includes directory structure with READMEs)
+    copyTemplateDir(path.join(templatesDir, "project"), destDir, vars);
+    // Place node-specific files into the correct locations
+    const nodeTemplatesDir = path.join(templatesDir, "node");
+    const srcDir = path.join(destDir, "src");
+    renderTemplateFile(path.join(nodeTemplatesDir, "server-node.ts.hbs"), path.join(srcDir, "server", "nodes", `${vars.dashCaseNodeName}.ts`), vars);
+    renderTemplateFile(path.join(nodeTemplatesDir, "schema.ts.hbs"), path.join(srcDir, "server", "schemas", `${vars.dashCaseNodeName}.ts`), vars);
+    renderTemplateFile(path.join(nodeTemplatesDir, "server-index.ts.hbs"), path.join(srcDir, "server", "index.ts"), vars);
+    renderTemplateFile(path.join(nodeTemplatesDir, "labels.json.hbs"), path.join(srcDir, "locales", "labels", vars.dashCaseNodeName, "en-US.json"), vars);
+    renderTemplateFile(path.join(nodeTemplatesDir, "docs.md.hbs"), path.join(srcDir, "locales", "docs", vars.dashCaseNodeName, "en-US.md"), vars);
+}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@bonsae/create-nrg",
+  "version": "0.1.0",
+  "description": "Scaffold a new NRG project for Node-RED",
+  "author": "Allan Oricil <allanoricil@duck.com>",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "create-nrg": "./dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "templates/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bonsaedev/create-nrg"
+  },
+  "keywords": [
+    "node-red",
+    "nrg",
+    "scaffold",
+    "create",
+    "bonsae"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\"",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepare": "husky"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.0.1"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^20.5.0",
+    "@commitlint/config-conventional": "^20.5.0",
+    "@eslint/js": "^9.27.0",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^11.0.0",
+    "@types/node": "^22.15.18",
+    "@typescript-eslint/eslint-plugin": "^8.32.1",
+    "@typescript-eslint/parser": "^8.32.1",
+    "eslint": "^9.27.0",
+    "eslint-config-prettier": "^10.1.8",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.4.0",
+    "prettier": "^3.5.3",
+    "semantic-release": "^24.2.4",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.32.1",
+    "vitest": "^4.1.5"
+  },
+  "lint-staged": {
+    "src/**/*.ts": [
+      "eslint --fix",
+      "prettier --write"
+    ]
+  }
+}

package/templates/node/docs.md.hbs

@@ -0,0 +1,3 @@
+# {{dashCaseNodeName}}
+
+{{nodeName}}

package/templates/node/labels.json.hbs

@@ -0,0 +1,6 @@
+{
+  "label": "{{nodeName}}",
+  "configs": {
+    "name": "Name"
+  }
+}

package/templates/node/schema.ts.hbs

@@ -0,0 +1,40 @@
+import { SchemaType, defineSchema } from "@bonsae/nrg/server";
+
+const ConfigsSchema = defineSchema(
+  {
+    name: SchemaType.String({ default: "{{dashCaseNodeName}}" }),
+  },
+  {
+    $id: "{{pascalCaseNodeName}}ConfigsSchema",
+  },
+);
+
+const CredentialsSchema = defineSchema(
+  {},
+  {
+    $id: "{{pascalCaseNodeName}}CredentialsSchema",
+  },
+);
+
+const InputSchema = defineSchema(
+  {},
+  {
+    $id: "{{pascalCaseNodeName}}InputSchema",
+  },
+);
+
+const OutputSchema = defineSchema(
+  {},
+  {
+    $id: "{{pascalCaseNodeName}}OutputSchema",
+  },
+);
+
+const SettingsSchema = defineSchema(
+  {},
+  {
+    $id: "{{pascalCaseNodeName}}SettingsSchema",
+  },
+);
+
+export { ConfigsSchema, CredentialsSchema, InputSchema, OutputSchema, SettingsSchema };

package/templates/node/server-index.ts.hbs

@@ -0,0 +1,5 @@
+import {{pascalCaseNodeName}} from "./nodes/{{dashCaseNodeName}}";
+
+export default {
+  nodes: [{{pascalCaseNodeName}}],
+};

package/templates/node/server-node.ts.hbs

@@ -0,0 +1,51 @@
+import type { Schema, Infer, RED } from "@bonsae/nrg/server";
+import { IONode } from "@bonsae/nrg/server";
+import {
+  ConfigsSchema,
+  CredentialsSchema,
+  InputSchema,
+  OutputSchema,
+  SettingsSchema,
+} from "../schemas/{{dashCaseNodeName}}";
+
+export type Config = Infer<typeof ConfigsSchema>;
+export type Credentials = Infer<typeof CredentialsSchema>;
+export type Input = Infer<typeof InputSchema>;
+export type Output = Infer<typeof OutputSchema>;
+export type Settings = Infer<typeof SettingsSchema>;
+
+export default class {{pascalCaseNodeName}} extends IONode<
+  Config,
+  Credentials,
+  Input,
+  Output,
+  Settings
+> {
+  public static override readonly type: string = "{{dashCaseNodeName}}";
+  public static override readonly category: string = "{{nodeCategory}}";
+  public static override readonly color: `#${string}` = "{{nodeColor}}";
+  public static override readonly inputs: number = {{nodeInputs}};
+  public static override readonly outputs: number = {{nodeOutputs}};
+
+  public static override readonly configSchema: Schema = ConfigsSchema;
+  public static override readonly credentialsSchema: Schema = CredentialsSchema;
+  public static override readonly inputSchema: Schema = InputSchema;
+  public static override readonly outputsSchema: Schema = OutputSchema;
+  public static override readonly settingsSchema: Schema = SettingsSchema;
+
+  public static override async registered(RED: RED): Promise<void> {
+    RED.log.info(`${this.type} registered`);
+  }
+
+  public override created(): void {
+    this.log(`{{pascalCaseNodeName}} ${this.id} created`);
+  }
+
+  public override async input(msg: Input): Promise<void> {
+    this.send(msg as unknown as Output);
+  }
+
+  public override async closed(): Promise<void> {
+    this.log(`{{pascalCaseNodeName}} ${this.id} closed`);
+  }
+}

package/templates/project/.gitignore.hbs

@@ -0,0 +1,6 @@
+.DS_Store
+*.log
+dist
+build
+node_modules
+node-red*

package/templates/project/.husky/commit-msg.hbs

@@ -0,0 +1 @@
+npx commitlint --edit $1

package/templates/project/.husky/pre-commit.hbs

@@ -0,0 +1 @@
+npx lint-staged

package/templates/project/.prettierrc.json.hbs

@@ -0,0 +1,5 @@
+{
+  "semi": true,
+  "singleQuote": false,
+  "trailingComma": "all"
+}

package/templates/project/.vscode/extensions.json

@@ -0,0 +1,7 @@
+{
+  "recommendations": [
+    "dbaeumer.vscode-eslint",
+    "esbenp.prettier-vscode",
+    "vue.volar"
+  ]
+}

package/templates/project/README.md.hbs

@@ -0,0 +1,8 @@
+# {{projectName}}
+
+Built with [@bonsae/nrg](https://github.com/bonsaedev/nrg).
+
+## Getting started
+
+1. Install dependencies: `pnpm install`
+2. Start dev server: `pnpm run dev`

package/templates/project/commitlint.config.js.hbs

@@ -0,0 +1 @@
+export default { extends: ["@commitlint/config-conventional"] };

package/templates/project/eslint.config.js.hbs

@@ -0,0 +1,38 @@
+import eslint from "@eslint/js";
+import eslintConfigPrettier from "eslint-config-prettier";
+import eslintPluginVue from "eslint-plugin-vue";
+import globals from "globals";
+import typescriptEslint from "typescript-eslint";
+
+export default typescriptEslint.config(
+  {
+    ignores: ["**/*.d.ts", "**/coverage", "**/dist", "**/build"],
+  },
+  {
+    extends: [
+      eslint.configs.recommended,
+      ...typescriptEslint.configs.recommended,
+      ...eslintPluginVue.configs["flat/recommended"],
+    ],
+    files: ["src/**/*.{ts,vue}"],
+    languageOptions: {
+      ecmaVersion: "latest",
+      sourceType: "module",
+      globals: { ...globals["shared-node-browser"] },
+      parserOptions: {
+        parser: typescriptEslint.parser,
+      },
+    },
+    rules: {
+      "@typescript-eslint/no-explicit-any": "off",
+      "vue/no-mutating-props": "off",
+      "@typescript-eslint/consistent-type-imports": [
+        "error",
+        {
+          prefer: "type-imports",
+        },
+      ],
+    },
+  },
+  eslintConfigPrettier,
+);

package/templates/project/package.json.hbs

@@ -0,0 +1,61 @@
+{
+  "name": "{{projectName}}",
+  "version": "0.0.0",
+  "description": "",
+  "author": "",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22",
+    "pnpm": ">=10.11.0"
+  },
+  "keywords": [
+    "node-red",
+    "nrg"
+  ],
+  "scripts": {
+    "debug": "NODE_OPTIONS='--inspect-brk' NODE_ENV=development vite",
+    "dev": "NODE_ENV=development vite",
+    "build:dev": "NODE_ENV=development vite build",
+    "build": "NODE_ENV=production vite build",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "format": "prettier --write \"src/**/*.{ts,vue,json}\"",
+    "format:check": "prettier --check \"src/**/*.{ts,vue,json}\"",
+    "tsc:client": "tsc -p src/client/tsconfig.json",
+    "tsc:server": "tsc -p src/server/tsconfig.json",
+    "prepare": "husky"
+  },
+  "lint-staged": {
+    "src/**/*.{ts,vue}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "src/**/*.json": [
+      "prettier --write"
+    ]
+  },
+  "dependencies": {
+    "@bonsae/nrg": "latest",
+    "@sinclair/typebox": "^0.34.49"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^20.5.0",
+    "@commitlint/config-conventional": "^20.5.0",
+    "@eslint/js": "^9.27.0",
+    "@types/node": "^22.15.18",
+    "@typescript-eslint/eslint-plugin": "^8.32.1",
+    "@typescript-eslint/parser": "^8.32.1",
+    "eslint": "^9.27.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-vue": "^10.1.0",
+    "globals": "^16.1.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.4.0",
+    "prettier": "^3.5.3",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.32.1",
+    "vite": "^6.3.4",
+    "vue": "^3.5.14"
+  }
+}

package/templates/project/src/examples/README.md

@@ -0,0 +1 @@
+Use this directory to provide flow examples using your nodes.

package/templates/project/src/icons/README.md

@@ -0,0 +1 @@
+Use this directory to provide custom icons for your nodes.

package/templates/project/src/locales/README.md

@@ -0,0 +1 @@
+Use locales and docs directories to offer internationalization for your nodes.

package/templates/project/src/locales/docs/README.md

@@ -0,0 +1 @@
+Use this directory to add documentation for your nodes.

package/templates/project/src/locales/labels/README.md

@@ -0,0 +1 @@
+Use this directory to add label translations for your nodes.

package/templates/project/src/server/README.md

@@ -0,0 +1 @@
+Use this directory to write the server-side definition of your node.

package/templates/project/src/server/nodes/README.md

@@ -0,0 +1 @@
+Use this directory to define your server-side Node-RED nodes.

package/templates/project/src/server/schemas/README.md

@@ -0,0 +1 @@
+Use this directory to write JSON Schemas using [Typebox](https://github.com/sinclairzx81/typebox).

package/templates/project/src/server/tsconfig.json.hbs

@@ -0,0 +1,7 @@
+{
+  "extends": "@bonsae/nrg/tsconfig/server.json",
+  "compilerOptions": {
+    "rootDir": "."
+  },
+  "include": ["**/*.ts"]
+}

package/templates/project/tsconfig.json.hbs

@@ -0,0 +1,7 @@
+{
+  "extends": "@bonsae/nrg/tsconfig/base.json",
+  "compilerOptions": {
+    "rootDir": "."
+  },
+  "include": ["vite.config.ts"]
+}

package/templates/project/vite.config.ts.hbs

@@ -0,0 +1,6 @@
+import { defineConfig } from "vite";
+import { nodeRed } from "@bonsae/nrg/vite";
+
+export default defineConfig({
+  plugins: [nodeRed()],
+});