@bonsae/nrg 0.25.1 → 0.26.0

package/server/index.cjs

@@ -1,2 +1,1413 @@
-'use strict';
-module.exports = require("@bonsae/nrg-runtime/server");
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/core/server/index.ts
+var index_exports = {};
+__export(index_exports, {
+  CompletePortSchema: () => CompletePortSchema,
+  ConfigNode: () => ConfigNode,
+  ErrorPortSchema: () => ErrorPortSchema,
+  IONode: () => IONode,
+  Node: () => Node,
+  NodeSourceSchema: () => NodeSourceSchema,
+  NrgError: () => NrgError,
+  SchemaType: () => SchemaType,
+  StatusPortSchema: () => StatusPortSchema,
+  defineConfigNode: () => defineConfigNode,
+  defineIONode: () => defineIONode,
+  defineModule: () => defineModule,
+  defineSchema: () => defineSchema,
+  registerType: () => registerType,
+  registerTypes: () => registerTypes
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/core/errors.ts
+var NrgError = class _NrgError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "NrgError";
+    Object.setPrototypeOf(this, _NrgError.prototype);
+  }
+};
+
+// src/core/server/typed-input.ts
+var TypedInput = class {
+  constructor(RED, node, input) {
+    this.RED = RED;
+    this.node = node;
+    this.input = input;
+  }
+  resolvers = {
+    // evaluateNodeProperty returns the node ID string for "node" type —
+    // resolve it to the actual node instance via RED.nodes.getNode,
+    // then surface the NRG wrapper if available.
+    node: (raw) => {
+      if (typeof raw === "string") {
+        const node = this.RED.nodes.getNode(raw);
+        return node?._node ?? node ?? raw;
+      }
+      return raw?._node ?? raw;
+    }
+  };
+  get type() {
+    return this.input.type;
+  }
+  get value() {
+    return this.input.value;
+  }
+  resolve(msg) {
+    return new Promise((resolve, reject) => {
+      this.RED.util.evaluateNodeProperty(
+        this.input.value,
+        this.input.type,
+        this.node,
+        msg,
+        (err, raw) => {
+          if (err) return reject(err);
+          const post = this.resolvers[this.input.type];
+          resolve(post ? post(raw) : raw);
+        }
+      );
+    });
+  }
+};
+
+// src/core/server/nodes/proxy.ts
+function setupConfigProxy(opts) {
+  const { RED, node, config, schema } = opts;
+  const SKIP_PROPS = /* @__PURE__ */ new Set(["id", "_id", "_users"]);
+  const nodeRefProps = /* @__PURE__ */ new Set();
+  const typedInputProps = /* @__PURE__ */ new Set();
+  if (schema?.properties) {
+    for (const [key, propSchema] of Object.entries(schema.properties)) {
+      const s = propSchema;
+      if (s?.["x-nrg-node-type"]) nodeRefProps.add(key);
+      if (s?.["x-nrg-typed-input"]) typedInputProps.add(key);
+    }
+  }
+  const cache = /* @__PURE__ */ new WeakMap();
+  const createProxy = (obj) => {
+    const cached = cache.get(obj);
+    if (cached) return cached;
+    if (Array.isArray(obj)) {
+      const mapped = obj.map(
+        (item) => item && typeof item === "object" ? createProxy(item) : item
+      );
+      cache.set(obj, mapped);
+      return mapped;
+    }
+    const proxy = new Proxy(obj, {
+      get(target, prop) {
+        if (typeof prop === "symbol") return target[prop];
+        if (SKIP_PROPS.has(prop)) return target[prop];
+        const value = target[prop];
+        if (typeof value === "string" && value.length > 0 && nodeRefProps.has(prop)) {
+          return RED.nodes.getNode(value)?._node ?? value;
+        }
+        if (typedInputProps.has(prop) && value && typeof value === "object" && "type" in value && "value" in value) {
+          let ref = cache.get(value);
+          if (!ref) {
+            ref = new TypedInput(RED, node, value);
+            cache.set(value, ref);
+          }
+          return ref;
+        }
+        if (value && typeof value === "object") {
+          return createProxy(value);
+        }
+        return value;
+      },
+      set(_target, prop) {
+        throw new NrgError(
+          `Cannot set property '${String(prop)}' on read-only node config`
+        );
+      }
+    });
+    cache.set(obj, proxy);
+    return proxy;
+  };
+  return createProxy(config);
+}
+
+// src/core/server/utils.ts
+function getCredentialsFromSchema(schema) {
+  const result = {};
+  for (const [key, value] of Object.entries(schema.properties)) {
+    const property = value;
+    result[key] = {
+      // NOTE: required is always false because it is controlled by the JSON Schema and AJV validation instead of using node-red client core
+      required: false,
+      type: property.format === "password" ? "password" : "text",
+      value: property.default ?? void 0
+    };
+  }
+  return result;
+}
+
+// src/core/server/nodes/symbols.ts
+var WIRE_HANDLERS = Symbol.for("nrg.wireHandlers");
+
+// src/core/server/nodes/node.ts
+var cachedSettingsMap = /* @__PURE__ */ new WeakMap();
+var Node = class _Node {
+  static type;
+  static category;
+  static configSchema;
+  static credentialsSchema;
+  static settingsSchema;
+  static validateSettings(RED) {
+    if (!this.settingsSchema) return;
+    RED.log.info("Validating settings");
+    const prefix = this.type.replace(/-./g, (x) => x[1].toUpperCase());
+    const properties = this.settingsSchema.properties;
+    const settings = {};
+    for (const key of Object.keys(properties)) {
+      const settingKey = prefix + key.charAt(0).toUpperCase() + key.slice(1);
+      const value = RED.settings[settingKey];
+      if (value !== void 0) {
+        settings[key] = value;
+      }
+    }
+    for (const [key, prop] of Object.entries(properties)) {
+      if (settings[key] === void 0) {
+        const defaultValue = prop.default ?? prop._default;
+        if (defaultValue !== void 0) {
+          settings[key] = defaultValue;
+        }
+      }
+    }
+    RED.validator.validate(settings, this.settingsSchema, {
+      cacheKey: this.settingsSchema.$id || `${this.type}:settings`,
+      throwOnError: true
+    });
+    cachedSettingsMap.set(this, settings);
+    RED.log.info("Settings are valid");
+  }
+  static #buildSettings(NC) {
+    if (!NC.settingsSchema) return;
+    const settings = {};
+    const prefix = NC.type.replace(/-./g, (x) => x[1].toUpperCase());
+    for (const [key, prop] of Object.entries(NC.settingsSchema.properties)) {
+      const settingKey = prefix + key.charAt(0).toUpperCase() + key.slice(1);
+      settings[settingKey] = {
+        value: prop.default,
+        exportable: prop.exportable ?? false
+      };
+    }
+    return settings;
+  }
+  /**
+   * Registers this node class with Node-RED. Handles instance creation,
+   * event handler wiring, settings validation, and the user's registered() hook.
+   */
+  static async register(RED) {
+    const NodeClass = this;
+    if (NodeClass.color && !/^#[0-9A-Fa-f]{6}$/.test(NodeClass.color)) {
+      throw new NrgError(
+        `Invalid color for ${NodeClass.type}: ${NodeClass.color} color must be in hex format`
+      );
+    }
+    RED.nodes.registerType(
+      NodeClass.type,
+      function(config) {
+        RED.nodes.createNode(this, config);
+        const node = new NodeClass(RED, this, config, this.credentials);
+        Object.defineProperty(this, "_node", {
+          value: node,
+          writable: false,
+          configurable: false,
+          enumerable: false
+        });
+        const createdPromise = Promise.resolve(node.created?.()).catch(
+          (error) => {
+            const message = error instanceof Error ? error.message : String(error);
+            this.error("Error during created hook: " + message);
+            throw error;
+          }
+        );
+        createdPromise.catch(() => {
+        });
+        node[WIRE_HANDLERS](this, createdPromise);
+      },
+      {
+        credentials: NodeClass.credentialsSchema ? getCredentialsFromSchema(NodeClass.credentialsSchema) : {},
+        settings: _Node.#buildSettings(this)
+      }
+    );
+    NodeClass.validateSettings(RED);
+    try {
+      await Promise.resolve(NodeClass.registered?.(RED));
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      RED.log.error(
+        `Error during registered hook for ${NodeClass.type}: ${message}`
+      );
+    }
+  }
+  RED;
+  node;
+  context;
+  config;
+  timers = /* @__PURE__ */ new Set();
+  intervals = /* @__PURE__ */ new Set();
+  constructor(RED, node, config, credentials) {
+    this.RED = RED;
+    this.node = node;
+    const constructor = this.constructor;
+    if (constructor.configSchema) {
+      this.log("Validating configs");
+      const configResult = this.RED.validator.validate(
+        config,
+        constructor.configSchema,
+        {
+          cacheKey: constructor.configSchema.$id || `${constructor.type}:configs-schema`,
+          throwOnError: false
+        }
+      );
+      if (!configResult.valid && configResult.errors?.length) {
+        this.warn(
+          `Config validation errors: ${configResult.errors.map((e) => `${e.instancePath} ${e.message}`).join("; ")}`
+        );
+      }
+    }
+    this.config = setupConfigProxy({
+      RED,
+      node,
+      config,
+      schema: constructor.configSchema
+    });
+    if (constructor.credentialsSchema && credentials) {
+      this.log("Validating credentials");
+      const credResult = this.RED.validator.validate(
+        credentials,
+        constructor.credentialsSchema,
+        {
+          cacheKey: constructor.credentialsSchema.$id || `${constructor.type}:credentials-schema`,
+          throwOnError: false
+        }
+      );
+      if (!credResult.valid && credResult.errors?.length) {
+        this.warn(
+          `Credentials validation errors: ${credResult.errors.map((e) => `${e.instancePath} ${e.message}`).join("; ")}`
+        );
+      }
+    }
+  }
+  [WIRE_HANDLERS](nodeRedNode, createdPromise) {
+    nodeRedNode.on(
+      "close",
+      async (removed, done) => {
+        try {
+          this.log("Calling closed");
+          await this.#closed(removed);
+          this.log("Node was closed");
+          done();
+        } catch (error) {
+          if (error instanceof Error) {
+            this.error("Error while closing node: " + error.message);
+            done(error);
+          } else {
+            this.error("Unknown error occurred while closing node");
+            done(new Error("Unknown error occurred while closing node"));
+          }
+        }
+      }
+    );
+  }
+  async #closed(removed) {
+    try {
+      await Promise.resolve(this.closed?.(removed));
+    } finally {
+      this.log("clearing timers and intervals");
+      this.timers.forEach((t) => clearTimeout(t));
+      this.intervals.forEach((i) => clearInterval(i));
+      this.timers.clear();
+      this.intervals.clear();
+      this.log("timers and intervals cleared");
+    }
+  }
+  i18n(key, substitutions) {
+    const nodeType = this.constructor.type;
+    return this.RED._(`${nodeType}.${key}`, substitutions);
+  }
+  setTimeout(fn, ms) {
+    const timer = setTimeout(() => {
+      this.timers.delete(timer);
+      fn();
+    }, ms);
+    this.timers.add(timer);
+    return timer;
+  }
+  setInterval(fn, ms) {
+    const interval = setInterval(fn, ms);
+    this.intervals.add(interval);
+    return interval;
+  }
+  clearTimeout(timer) {
+    clearTimeout(timer);
+    this.timers.delete(timer);
+  }
+  clearInterval(interval) {
+    clearInterval(interval);
+    this.intervals.delete(interval);
+  }
+  on(event, callback) {
+    this.node.on(event, callback);
+  }
+  log(msg) {
+    this.node.log(msg);
+  }
+  warn(message) {
+    this.node.warn(message);
+  }
+  error(message, msg) {
+    this.node.error(message, msg);
+  }
+  get id() {
+    return this.node.id;
+  }
+  get name() {
+    return this.node.name;
+  }
+  get z() {
+    return this.node.z;
+  }
+  get credentials() {
+    return this.node.credentials;
+  }
+  get settings() {
+    const constructor = this.constructor;
+    return cachedSettingsMap.get(constructor) ?? {};
+  }
+};
+
+// src/core/server/nodes/io-node.ts
+var import_typebox = require("@sinclair/typebox");
+
+// src/core/server/nodes/context.ts
+var updateLocks = /* @__PURE__ */ new WeakMap();
+function setupContext(context, store) {
+  const get = (key) => new Promise(
+    (resolve, reject) => context.get(
+      key,
+      store,
+      (error, value) => error ? reject(error) : resolve(value)
+    )
+  );
+  const set = (key, value) => new Promise(
+    (resolve, reject) => context.set(
+      key,
+      value,
+      store,
+      (error) => error ? reject(error) : resolve()
+    )
+  );
+  const keys = () => new Promise(
+    (resolve, reject) => context.keys(store, (error, k) => error ? reject(error) : resolve(k))
+  );
+  const nativeUpdate = context.update;
+  const nativeIncrement = context.increment;
+  const update = (key, fn) => {
+    if (nativeUpdate) {
+      return new Promise(
+        (resolve, reject) => nativeUpdate(
+          key,
+          fn,
+          store,
+          (error, value) => error ? reject(error) : resolve(value)
+        )
+      );
+    }
+    let chains = updateLocks.get(context);
+    if (!chains) updateLocks.set(context, chains = /* @__PURE__ */ new Map());
+    const lockKey = JSON.stringify([store ?? null, key]);
+    const task = async () => {
+      const next = await fn(await get(key));
+      await set(key, next);
+      return next;
+    };
+    const run = (chains.get(lockKey) ?? Promise.resolve()).then(task, task);
+    chains.set(
+      lockKey,
+      run.then(
+        () => void 0,
+        () => void 0
+      )
+    );
+    return run;
+  };
+  const increment = (key, by = 1) => {
+    if (nativeIncrement) {
+      return new Promise(
+        (resolve, reject) => nativeIncrement(
+          key,
+          by,
+          store,
+          (error, value) => error ? reject(error) : resolve(value)
+        )
+      );
+    }
+    return update(
+      key,
+      (current) => typeof current === "number" ? current + by : by
+    );
+  };
+  return { get, set, keys, update, increment };
+}
+
+// src/core/server/nodes/io-node.ts
+var import_node_async_hooks = require("node:async_hooks");
+function isSchemaLike(obj) {
+  return obj != null && typeof obj === "object" && import_typebox.Kind in obj;
+}
+var RETURN_PROPERTY_PATTERN = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+var INPUT_KEY = "input";
+var IONode = class _IONode extends Node {
+  static align;
+  static color;
+  static inputSchema;
+  // outputsSchema accepts any schema shape: the raw sent value (per port) is
+  // validated, and results are frequently non-objects.
+  static outputsSchema;
+  static validateInput = false;
+  static validateOutput = false;
+  static get inputs() {
+    return this.inputSchema ? 1 : 0;
+  }
+  static get outputs() {
+    const s = this.outputsSchema;
+    if (!s) return 0;
+    if (Array.isArray(s)) return s.length;
+    if (isSchemaLike(s)) return 1;
+    const keys = Object.keys(s);
+    for (const key of keys) {
+      if (/^\d+$/.test(key)) {
+        throw new NrgError(
+          `outputsSchema record key "${key}" in ${this.type} looks numeric. Use descriptive string names (e.g. "success", "failure") to avoid JavaScript object key ordering issues.`
+        );
+      }
+      if (key === "error" || key === "complete" || key === "status") {
+        throw new NrgError(
+          `outputsSchema record key "${key}" in ${this.type} is reserved for built-in ports. Use a different name (e.g. "failed" instead of "error").`
+        );
+      }
+    }
+    return keys.length;
+  }
+  /**
+   * The names of the base output ports when `outputsSchema` is a record of
+   * named ports (`{ success, failure }`), in declaration order — otherwise
+   * `undefined` (a single schema or a positional array). Resolved here, where
+   * TypeBox's `Kind` symbol is intact, so the editor reads the names directly
+   * instead of guessing them from a serialized (symbol-stripped) schema.
+   */
+  static get outputPortNames() {
+    const s = this.outputsSchema;
+    if (!s || Array.isArray(s) || isSchemaLike(s)) return void 0;
+    return Object.keys(s);
+  }
+  /**
+   * Per-`input()`-invocation context, scoped via AsyncLocalStorage. One store
+   * per class, shared by every instance: each `.run()` isolates one input()
+   * call (and everything it `await`s, including detached `.then`/timer
+   * continuations it schedules) into its own session, so concurrent inputs on a
+   * node never clobber each other's context and a deferred send keeps the
+   * context of the input that scheduled it. Real Node-RED never awaits an async
+   * input handler before delivering the next message, so two inputs can be in
+   * flight at once. `getStore()` is `undefined` only for a send made entirely
+   * outside any `input()` (e.g. a timer set up in `created()`): it carries no
+   * inherited context and delivers via `node.send`. Server-only — this is part
+   * of the node runtime and is never imported in a browser.
+   */
+  static #invocation = new import_node_async_hooks.AsyncLocalStorage();
+  context;
+  constructor(RED, node, config, credentials) {
+    super(RED, node, config, credentials);
+    const context = node.context();
+    const resolve = (scope, store) => {
+      const target = scope === "global" ? context.global : scope === "flow" ? context.flow : context;
+      return setupContext(target, store);
+    };
+    this.context = Object.assign(resolve, {
+      node: setupContext(context),
+      flow: setupContext(context.flow),
+      global: setupContext(context.global)
+    });
+    const outputReturnProperties = this.config.outputReturnProperties;
+    if (outputReturnProperties) {
+      for (const [port, key] of Object.entries(outputReturnProperties)) {
+        if (typeof key === "string" && key.trim() && !RETURN_PROPERTY_PATTERN.test(key.trim())) {
+          throw new NrgError(
+            `Invalid return property "${key}" for output port ${port} in ${this.constructor.type} \u2014 it must be a valid JavaScript identifier (letters, digits, _, $; not starting with a digit)`
+          );
+        }
+      }
+    }
+  }
+  [WIRE_HANDLERS](nodeRedNode, createdPromise) {
+    super[WIRE_HANDLERS](nodeRedNode, createdPromise);
+    const NC = this.constructor;
+    nodeRedNode.on(
+      "input",
+      async (msg, send, done) => {
+        try {
+          await createdPromise;
+        } catch {
+          done(new Error("Node failed to initialize"));
+          return;
+        }
+        try {
+          nodeRedNode.log("Calling input");
+          const result = await this.#input(msg, send);
+          this.#sendToPort("complete", {
+            ...msg,
+            ...result !== void 0 ? { output: result } : {},
+            complete: {
+              source: this.#nodeSource()
+            },
+            [INPUT_KEY]: msg
+          });
+          done();
+          nodeRedNode.log("Input processed");
+        } catch (error) {
+          const errorMsg = error instanceof Error ? error.message : "Unknown error during input handling";
+          const errorData = error && typeof error === "object" ? { ...error } : {};
+          this.#sendToPort("error", {
+            ...msg,
+            error: {
+              ...errorData,
+              name: error?.name ?? "Error",
+              message: errorMsg,
+              source: this.#nodeSource()
+            },
+            [INPUT_KEY]: msg
+          });
+          if (error instanceof Error) {
+            nodeRedNode.error(
+              "Error while processing input: " + error.message,
+              msg
+            );
+            done(error);
+          } else {
+            nodeRedNode.error(
+              "Unknown error occurred during input handling",
+              msg
+            );
+            done(new Error(errorMsg));
+          }
+        }
+      }
+    );
+  }
+  input(msg) {
+    return void 0;
+  }
+  async #input(msg, send) {
+    const NodeClass = this.constructor;
+    const shouldValidateInput = this.config.validateInput ?? NodeClass.validateInput;
+    if (shouldValidateInput && NodeClass.inputSchema) {
+      this.log("Validating input");
+      this.RED.validator.validate(msg, NodeClass.inputSchema, {
+        cacheKey: NodeClass.inputSchema.$id || `${NodeClass.type}:input-schema`,
+        throwOnError: true
+      });
+      this.log("Input is valid");
+    }
+    return await _IONode.#invocation.run(
+      { inputMsg: msg, send },
+      () => Promise.resolve(this.input(msg))
+    );
+  }
+  send(msg) {
+    const multi = this.baseOutputs > 1 && Array.isArray(msg);
+    const values = multi ? msg.slice(0, this.baseOutputs) : [msg];
+    const out = values.map((m, port) => {
+      if (m == null) return m;
+      this.#validatePort(m, port);
+      return this.#wrapOutgoing(m, this.#resolveContextMode(port), port);
+    });
+    this.#deliver(out);
+  }
+  #deliver(out) {
+    const send = _IONode.#invocation.getStore()?.send;
+    if (send) {
+      send(out);
+    } else {
+      this.node.send(out);
+    }
+  }
+  /**
+   * Per-port output validation. A port validates when its flow-author flag
+   * (`config.validateOutputs[port]`) — or the node's static `validateOutput`
+   * fallback — is on and a schema exists for that port.
+   */
+  #validatePort(value, port) {
+    const NodeClass = this.constructor;
+    const configured = this.config.validateOutputs?.[port];
+    if (!(configured ?? NodeClass.validateOutput)) return;
+    const schema = this.#outputSchemaForPort(port);
+    if (!schema) return;
+    this.log("Validating output");
+    this.RED.validator.validate(value, schema, {
+      cacheKey: schema.$id || `${NodeClass.type}:output-schema:${port}`,
+      throwOnError: true
+    });
+    this.log("Output is valid");
+  }
+  /** Resolves the output schema for a base-output port: array → `[port]`,
+   * record → the port-th value, single schema → itself. */
+  #outputSchemaForPort(port) {
+    const raw = this.constructor.outputsSchema;
+    if (!raw) return void 0;
+    if (Array.isArray(raw)) return raw[port];
+    if (isSchemaLike(raw)) return raw;
+    return Object.values(raw)[port];
+  }
+  /**
+   * The return key for an output port — `"output"` unless a custom one is set
+   * via `outputReturnProperties[port]` (author default and/or flow-author
+   * override, only possible when the node declares `outputReturnProperties`).
+   * `this.send(x)` always means "x is the value at this port's return key",
+   * never "x is the whole outgoing message".
+   */
+  #returnPropertyKey(port) {
+    const configured = this.config.outputReturnProperties?.[port];
+    if (typeof configured === "string" && configured.trim()) {
+      return configured.trim();
+    }
+    return "output";
+  }
+  /**
+   * Resolves the context mode for a base-output port from the flow author's
+   * per-port config (`config.outputContextModes[port]`, written by the editor
+   * when the node declares `outputContextModes`), falling back to `"carry"`.
+   */
+  #resolveContextMode(port) {
+    return this.config.outputContextModes?.[port] ?? "carry";
+  }
+  /**
+   * Merges a sent value into the incoming message at the returnProperty key so
+   * upstream message properties propagate. A fresh base is built per call so
+   * multi-port sends never share an object.
+   */
+  #wrapOutgoing(value, mode, port) {
+    const key = this.#returnPropertyKey(port);
+    const input = _IONode.#invocation.getStore()?.inputMsg ?? {};
+    if (mode === "reset") {
+      return { [key]: value };
+    }
+    if (mode === "trace") {
+      return { ...input, [key]: value, [INPUT_KEY]: input };
+    }
+    return { ...input, [key]: value };
+  }
+  // --- Built-in port management ---
+  get baseOutputs() {
+    return this.constructor.outputs ?? 0;
+  }
+  get totalOutputs() {
+    let count = this.baseOutputs;
+    if (this.config.errorPort) count++;
+    if (this.config.completePort) count++;
+    if (this.config.statusPort) count++;
+    return count;
+  }
+  /**
+   * Send a message to a specific output port by index or name.
+   * Custom named ports are resolved from `outputsSchema` when it is a record.
+   * Numeric indices refer to the base output ports (0-based).
+   *
+   * Built-in ports (`"error"`, `"complete"`, `"status"`) are managed by the
+   * framework and cannot be sent to directly. Use `this.status()` for status,
+   * throw an error or call `this.error()` for the error port, and the complete
+   * port is sent automatically on successful input processing.
+   */
+  sendToPort(port, msg) {
+    if (port === "error" || port === "complete" || port === "status") {
+      throw new NrgError(
+        `sendToPort("${port}") is not allowed. Built-in ports are managed by the framework.`
+      );
+    }
+    const portIndex = typeof port === "number" ? port : this.#getNamedPortIndex(port);
+    const mode = this.#resolveContextMode(portIndex ?? 0);
+    this.#sendToPort(
+      port,
+      msg == null ? msg : this.#wrapOutgoing(msg, mode, portIndex ?? 0)
+    );
+  }
+  #sendToPort(port, msg) {
+    let portIndex;
+    if (typeof port === "number") {
+      portIndex = port;
+    } else if (port === "error" || port === "complete" || port === "status") {
+      portIndex = this.#getBuiltinPortIndex(port);
+      if (portIndex === null) return;
+    } else {
+      portIndex = this.#getNamedPortIndex(port);
+      if (portIndex === null) return;
+    }
+    const out = new Array(this.totalOutputs);
+    out[portIndex] = msg;
+    this.node.send(out);
+  }
+  #getNamedPortIndex(name) {
+    const schema = this.constructor.outputsSchema;
+    if (!schema || Array.isArray(schema) || isSchemaLike(schema)) return null;
+    const idx = Object.keys(schema).indexOf(name);
+    return idx === -1 ? null : idx;
+  }
+  #getBuiltinPortIndex(name) {
+    if (name === "error") {
+      return this.config.errorPort ? this.baseOutputs : null;
+    }
+    let idx = this.baseOutputs;
+    if (this.config.errorPort) idx++;
+    if (name === "complete") {
+      return this.config.completePort ? idx : null;
+    }
+    if (this.config.completePort) idx++;
+    return this.config.statusPort ? idx : null;
+  }
+  #nodeSource() {
+    return {
+      id: this.id,
+      type: this.constructor.type,
+      name: this.name
+    };
+  }
+  status(status) {
+    this.node.status(status);
+    this.#sendToPort("status", {
+      status,
+      source: this.#nodeSource()
+    });
+  }
+  error(message, msg) {
+    super.error(message, msg);
+    if (msg) {
+      this.#sendToPort("error", {
+        ...msg,
+        error: {
+          message,
+          source: this.#nodeSource()
+        },
+        [INPUT_KEY]: msg
+      });
+    }
+  }
+  updateWires(wires) {
+    this.node.updateWires(wires);
+  }
+  receive(msg) {
+    this.node.receive(msg);
+  }
+  get x() {
+    return this.node.x;
+  }
+  get y() {
+    return this.node.y;
+  }
+  get g() {
+    return this.node.g;
+  }
+  get wires() {
+    return this.node.wires;
+  }
+  get credentials() {
+    return this.node.credentials;
+  }
+};
+
+// src/core/server/nodes/config-node.ts
+var ConfigNode = class extends Node {
+  static category = "config";
+  context;
+  constructor(RED, node, config, credentials) {
+    super(RED, node, config, credentials);
+    const context = node.context();
+    const resolve = (scope, store) => {
+      const target = scope === "global" ? context.global : context;
+      return setupContext(target, store);
+    };
+    this.context = Object.assign(resolve, {
+      node: setupContext(context),
+      global: setupContext(context.global)
+    });
+  }
+  get userIds() {
+    return this.config._users;
+  }
+  get users() {
+    return this.userIds.map((id) => this.RED.nodes.getNode(id)?._node).filter((node) => node != null);
+  }
+  getUser(index) {
+    const id = this.userIds[index];
+    if (!id) return void 0;
+    return this.RED.nodes.getNode(id)?._node;
+  }
+  get credentials() {
+    return this.node.credentials;
+  }
+};
+
+// src/core/server/nodes/factories.ts
+function defineIONode(def) {
+  const NodeClass = class extends IONode {
+    static type = def.type;
+    static category = def.category ?? "function";
+    static color = def.color ?? "#a6bbcf";
+    static align = def.align;
+    static configSchema = def.configSchema;
+    static credentialsSchema = def.credentialsSchema;
+    static settingsSchema = def.settingsSchema;
+    static inputSchema = def.inputSchema;
+    static outputsSchema = def.outputsSchema;
+    static validateInput = def.validateInput ?? false;
+    static validateOutput = def.validateOutput ?? false;
+    static registered(RED) {
+      return def.registered?.(RED);
+    }
+    async input(msg) {
+      if (def.input) return def.input.call(this, msg);
+    }
+    async created() {
+      if (def.created) return def.created.call(this);
+    }
+    async closed(removed) {
+      if (def.closed) return def.closed.call(this, removed);
+    }
+  };
+  Object.defineProperty(NodeClass, "name", {
+    value: def.type.replace(
+      /(^|-)(\w)/g,
+      (_, __, c) => c.toUpperCase()
+    ),
+    configurable: true
+  });
+  return NodeClass;
+}
+function defineConfigNode(def) {
+  const NodeClass = class extends ConfigNode {
+    static type = def.type;
+    static configSchema = def.configSchema;
+    static credentialsSchema = def.credentialsSchema;
+    static settingsSchema = def.settingsSchema;
+    static registered(RED) {
+      return def.registered?.(RED);
+    }
+    async created() {
+      if (def.created) return def.created.call(this);
+    }
+    async closed(removed) {
+      if (def.closed) return def.closed.call(this, removed);
+    }
+  };
+  Object.defineProperty(NodeClass, "name", {
+    value: def.type.replace(
+      /(^|-)(\w)/g,
+      (_, __, c) => c.toUpperCase()
+    ),
+    configurable: true
+  });
+  return NodeClass;
+}
+
+// src/core/validator.ts
+var import_ajv = __toESM(require("ajv"), 1);
+var import_ajv_formats = __toESM(require("ajv-formats"), 1);
+var import_ajv_errors = __toESM(require("ajv-errors"), 1);
+var Validator = class {
+  ajv;
+  constructor(options) {
+    const { customKeywords, customFormats, ...ajvOptions } = options || {};
+    this.ajv = new import_ajv.default({
+      allErrors: true,
+      code: {
+        source: false
+      },
+      coerceTypes: true,
+      removeAdditional: false,
+      strict: false,
+      strictSchema: false,
+      useDefaults: true,
+      validateFormats: true,
+      // NOTE: typebox handles validation via typescript
+      // NOTE: if true, types that are not serializable JSON, like Function, would not work
+      validateSchema: false,
+      verbose: true,
+      ...ajvOptions
+    });
+    (0, import_ajv_formats.default)(this.ajv);
+    (0, import_ajv_errors.default)(this.ajv);
+    this.addCustomKeywords(customKeywords || []);
+    this.addCustomFormats(customFormats || {});
+  }
+  /**
+   * Add custom keywords to the validator
+   */
+  addCustomKeywords(keywords) {
+    if (!keywords) return;
+    keywords.forEach((keyword) => {
+      this.ajv.addKeyword(keyword);
+    });
+  }
+  /**
+   * Add custom formats to the validator
+   */
+  addCustomFormats(formats) {
+    if (!formats) return;
+    Object.entries(formats).forEach(([name, validator]) => {
+      if (validator instanceof RegExp) {
+        this.ajv.addFormat(name, validator);
+      } else {
+        this.ajv.addFormat(name, { validate: validator });
+      }
+    });
+  }
+  /**
+   * Create a validator function with caching
+   * @param schema - JSON Schema to validate against
+   * @param cacheKey - Optional cache key for reusing validators
+   */
+  createValidator(schema, cacheKey) {
+    if (cacheKey && !schema.$id) {
+      schema.$id = cacheKey;
+    }
+    if (schema.$id) {
+      const cached = this.ajv.getSchema(schema.$id);
+      if (cached) return cached;
+    }
+    const validator = this.ajv.compile(schema);
+    return validator;
+  }
+  /**
+   * Validate data against a schema and return a structured result
+   */
+  validate(data, schema, options) {
+    const validator = this.createValidator(schema, options?.cacheKey);
+    const valid = validator(data);
+    if (!valid) {
+      const errorMessage = this.formatErrors(validator.errors);
+      if (options?.throwOnError) {
+        throw new ValidationError(errorMessage, validator.errors || []);
+      }
+      return {
+        valid: false,
+        errors: validator.errors || void 0,
+        errorMessage
+      };
+    }
+    return {
+      valid: true,
+      data
+    };
+  }
+  /**
+   * Format errors into a human-readable string
+   */
+  formatErrors(errors, options) {
+    if (!errors || errors.length === 0) {
+      return "No errors";
+    }
+    return this.ajv.errorsText(errors, {
+      separator: "; ",
+      dataVar: "data",
+      ...options
+    });
+  }
+  /**
+   * Get detailed error information
+   */
+  getDetailedErrors(errors) {
+    if (!errors || errors.length === 0) return [];
+    return errors.map((error) => ({
+      field: error.instancePath || "/",
+      message: error.message || "Validation failed",
+      keyword: error.keyword,
+      params: error.params,
+      schemaPath: error.schemaPath
+    }));
+  }
+  /**
+   * Add a schema to the validator for reference
+   */
+  addSchema(schema, key) {
+    this.ajv.addSchema(schema, key);
+    return this;
+  }
+  /**
+   * Remove a schema from the validator
+   */
+  removeSchema(key) {
+    this.ajv.removeSchema(key);
+    return this;
+  }
+};
+var ValidationError = class _ValidationError extends Error {
+  constructor(message, errors) {
+    super(message);
+    this.errors = errors;
+    this.name = "ValidationError";
+    Object.setPrototypeOf(this, _ValidationError.prototype);
+  }
+};
+
+// src/core/server/validation.ts
+function initValidator(RED) {
+  if (RED.validator) return;
+  const nrg = {
+    validator: new Validator({
+      customKeywords: [
+        {
+          keyword: "x-nrg-skip-validation",
+          schemaType: "boolean",
+          valid: true
+        },
+        {
+          keyword: "x-nrg-node-type",
+          type: "string",
+          validate: (schemaValue, dataValue) => {
+            if (!dataValue) return true;
+            const node = RED.nodes.getNode(dataValue);
+            return node?.type === schemaValue;
+          }
+        }
+      ],
+      customFormats: {
+        "node-id": /^[a-zA-Z0-9-_]+$/,
+        "flow-id": /^[a-f0-9]{16}$/,
+        "topic-path": (data) => /^[a-zA-Z0-9/_-]+$/.test(data)
+      }
+    })
+  };
+  Object.defineProperty(RED, "_nrg", {
+    value: nrg,
+    writable: false,
+    enumerable: false,
+    configurable: false
+  });
+  Object.defineProperty(RED, "validator", {
+    get: () => nrg.validator,
+    enumerable: false,
+    configurable: false
+  });
+}
+
+// src/core/server/api/assets.ts
+var import_path = __toESM(require("path"), 1);
+var import_fs = __toESM(require("fs"), 1);
+var import_module = require("module");
+function serveFile(filePath) {
+  return (_req, res, next) => {
+    if (!import_fs.default.existsSync(filePath)) return next();
+    res.setHeader("Content-Type", "application/javascript");
+    import_fs.default.createReadStream(filePath).pipe(res);
+  };
+}
+function initAssetsRoutes(router) {
+  const resourcesDir = import_path.default.resolve(__dirname, "./resources");
+  if (!import_fs.default.existsSync(resourcesDir)) return;
+  const _require = (0, import_module.createRequire)(import_path.default.join(__dirname, "package.json"));
+  const vueFile = process.env.NODE_ENV !== "production" ? _require.resolve("vue/dist/vue.esm-browser.js") : _require.resolve("vue/dist/vue.esm-browser.prod.js");
+  router.get(
+    "/nrg/assets/nrg-client.js",
+    serveFile(import_path.default.join(resourcesDir, "nrg-client.js"))
+  );
+  router.get("/nrg/assets/vue.esm-browser.prod.js", serveFile(vueFile));
+  router.get("/nrg/assets/vue.esm-browser.js", serveFile(vueFile));
+}
+
+// src/core/server/api/routes.ts
+var _initialized = false;
+function initRoutes(RED) {
+  if (_initialized) return;
+  _initialized = true;
+  initAssetsRoutes(RED.httpAdmin);
+}
+
+// src/core/server/registration.ts
+async function registerType(RED, NodeClass) {
+  RED.log.debug(`Registering Type: ${NodeClass.type}`);
+  if (!(NodeClass.prototype instanceof Node)) {
+    throw new NrgError(
+      `${NodeClass.name} must extend IONode or ConfigNode classes`
+    );
+  }
+  if (!NodeClass.type) {
+    throw new NrgError("type must be provided when registering the node");
+  }
+  await NodeClass.register(RED);
+  RED.log.debug(`Type registered: ${NodeClass.type}`);
+}
+function registerTypes(nodes) {
+  const fn = Object.assign(
+    async function(RED) {
+      initValidator(RED);
+      initRoutes(RED);
+      try {
+        RED.log.info("Registering node types in series");
+        for (const NodeClass of nodes) {
+          await registerType(RED, NodeClass);
+        }
+        RED.log.info("All node types registered in series");
+      } catch (error) {
+        RED.log.error("Error registering node types:", error);
+        throw error;
+      }
+    },
+    { nodes }
+  );
+  return fn;
+}
+
+// src/core/constants.ts
+var TYPED_INPUT_TYPES = [
+  "msg",
+  "flow",
+  "global",
+  "str",
+  "num",
+  "bool",
+  "json",
+  "bin",
+  "re",
+  "jsonata",
+  "date",
+  "env",
+  "node",
+  "cred"
+];
+
+// src/core/server/schemas/type.ts
+var import_typebox2 = require("@sinclair/typebox");
+var import_rules = require("ajv/dist/compile/rules");
+function NodeRef(nodeClass, options) {
+  return {
+    ...import_typebox2.Type.String({
+      description: options?.description || `Reference to ${nodeClass.type}`,
+      format: "node-id"
+    }),
+    "x-nrg-node-type": nodeClass.type,
+    ...options,
+    [import_typebox2.Kind]: "NodeRef"
+  };
+}
+function TypedInput2(options) {
+  return {
+    ...TypedInputSchema,
+    "x-nrg-typed-input": true,
+    ...options,
+    [import_typebox2.Kind]: "TypedInput"
+  };
+}
+function NrgString(options) {
+  return import_typebox2.Type.String(options);
+}
+function OutputReturnProperties(options) {
+  return import_typebox2.Type.Record(
+    import_typebox2.Type.Number(),
+    import_typebox2.Type.String({ pattern: "^[A-Za-z_$][A-Za-z0-9_$]*$" }),
+    {
+      description: "Per-port return property, keyed by output port index. A missing entry falls back to `output`.",
+      default: {},
+      ...options
+    }
+  );
+}
+function OutputContextModes(options) {
+  return import_typebox2.Type.Record(
+    import_typebox2.Type.Number(),
+    import_typebox2.Type.Union([
+      import_typebox2.Type.Literal("carry"),
+      import_typebox2.Type.Literal("trace"),
+      import_typebox2.Type.Literal("reset")
+    ]),
+    {
+      description: "Per-port context mode, keyed by output port index. A missing entry falls back to `carry`.",
+      default: {},
+      ...options
+    }
+  );
+}
+var SchemaType = Object.assign({}, import_typebox2.Type, {
+  String: NrgString,
+  NodeRef,
+  TypedInput: TypedInput2,
+  OutputReturnProperties,
+  OutputContextModes
+});
+function markNonValidatable(schema) {
+  const type = schema.type;
+  const hasInvalidType = type !== void 0 && (Array.isArray(type) ? !type.every(import_rules.isJSONType) : !(0, import_rules.isJSONType)(type));
+  if (hasInvalidType) {
+    schema["x-nrg-skip-validation"] = true;
+    if (schema.default !== void 0) {
+      schema._default = schema.default;
+      delete schema.default;
+    }
+    delete schema.type;
+  }
+  if (schema.properties) {
+    for (const prop of Object.values(schema.properties)) {
+      markNonValidatable(prop);
+    }
+  }
+  if (schema.items) {
+    markNonValidatable(schema.items);
+  }
+  if (schema.anyOf) {
+    schema.anyOf.forEach((s) => markNonValidatable(s));
+  }
+  if (schema.allOf) {
+    schema.allOf.forEach((s) => markNonValidatable(s));
+  }
+  if (schema.oneOf) {
+    schema.oneOf.forEach((s) => markNonValidatable(s));
+  }
+  return schema;
+}
+function defineSchema(properties, options) {
+  const schema = SchemaType.Object(properties, options);
+  return markNonValidatable(schema);
+}
+
+// src/core/server/schemas/base.ts
+var NodeConfigSchema = SchemaType.Object({
+  id: SchemaType.String(),
+  type: SchemaType.String(),
+  name: SchemaType.String(),
+  z: SchemaType.Optional(SchemaType.String())
+});
+var ConfigNodeConfigSchema = SchemaType.Object({
+  ...NodeConfigSchema.properties,
+  _users: SchemaType.Array(SchemaType.String())
+});
+var IONodeConfigSchema = SchemaType.Object({
+  ...NodeConfigSchema.properties,
+  wires: SchemaType.Array(
+    SchemaType.Array(SchemaType.String(), { default: [] }),
+    {
+      default: [[]]
+    }
+  ),
+  x: SchemaType.Number(),
+  y: SchemaType.Number(),
+  g: SchemaType.Optional(SchemaType.String())
+});
+var TypedInputSchema = SchemaType.Object(
+  {
+    value: SchemaType.Union(
+      [
+        SchemaType.String(),
+        SchemaType.Number(),
+        SchemaType.Boolean(),
+        SchemaType.Null()
+      ],
+      {
+        description: "The actual value entered or selected.",
+        default: ""
+      }
+    ),
+    type: SchemaType.Union(
+      TYPED_INPUT_TYPES.map((type) => SchemaType.Literal(type)),
+      {
+        description: "The type of the value (string, number, message property, etc.)",
+        default: "str"
+      }
+    )
+  },
+  {
+    description: "Represents a Node-RED TypedInput value and its type.",
+    default: {
+      type: "str",
+      value: ""
+    }
+  }
+);
+var NodeSourceSchema = SchemaType.Object({
+  id: SchemaType.String(),
+  type: SchemaType.String(),
+  name: SchemaType.String()
+});
+var ErrorPortSchema = SchemaType.Object({
+  error: SchemaType.Object({
+    message: SchemaType.String(),
+    source: NodeSourceSchema
+  })
+});
+var CompletePortSchema = SchemaType.Object({
+  complete: SchemaType.Object({
+    source: NodeSourceSchema
+  })
+});
+var StatusPortSchema = SchemaType.Object({
+  status: SchemaType.Union([
+    SchemaType.Object({
+      fill: SchemaType.Optional(
+        SchemaType.Union([
+          SchemaType.Literal("red"),
+          SchemaType.Literal("green")
+        ])
+      ),
+      shape: SchemaType.Optional(
+        SchemaType.Union([
+          SchemaType.Literal("dot"),
+          SchemaType.Literal("string")
+        ])
+      ),
+      text: SchemaType.Optional(SchemaType.String())
+    }),
+    SchemaType.String()
+  ]),
+  source: NodeSourceSchema
+});
+
+// src/core/server/index.ts
+function defineModule(definition) {
+  return definition;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CompletePortSchema,
+  ConfigNode,
+  ErrorPortSchema,
+  IONode,
+  Node,
+  NodeSourceSchema,
+  NrgError,
+  SchemaType,
+  StatusPortSchema,
+  defineConfigNode,
+  defineIONode,
+  defineModule,
+  defineSchema,
+  registerType,
+  registerTypes
+});