@tbrandenburg/node-red-cli 0.2.3

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@tbrandenburg/node-red-cli",
+  "version": "0.2.3",
+  "description": "Call existing Node-RED flows from Node.js and the command line",
+  "main": "src/link-call.js",
+  "bin": {
+    "node-red-cli": "bin/node-red-cli.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "lint": "eslint .",
+    "format": "prettier --check .",
+    "format:write": "prettier --write .",
+    "prepublishOnly": "make ci"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tbrandenburg/node-red-cli.git"
+  },
+  "homepage": "https://github.com/tbrandenburg/node-red-cli#readme",
+  "bugs": {
+    "url": "https://github.com/tbrandenburg/node-red-cli/issues"
+  },
+  "author": "Tom Brandenburg",
+  "keywords": [
+    "node-red",
+    "cli",
+    "link-in",
+    "link-out",
+    "automation",
+    "workflow",
+    "flow"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=24"
+  },
+  "dependencies": {
+    "commander": "^15.0.0",
+    "node-red": "5.0.6"
+  },
+  "overrides": {
+    "qs": "6.16.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.9.1",
+    "prettier": "^3.9.6"
+  }
+}

package/src/cli-params.js

@@ -0,0 +1,129 @@
+"use strict";
+
+/**
+ * Parses a single `key=value` pair as used by `--set key=value`.
+ *
+ * The value is JSON-parsed when possible (numbers, booleans, null, objects,
+ * arrays), so `--set x=4` yields the number `4`, not the string `"4"`. Values
+ * that aren't valid JSON (e.g. `--set name=alice`) are kept as plain strings.
+ */
+function parseSetParam(pair) {
+  if (typeof pair !== "string") {
+    throw new Error("--set requires a key=value argument");
+  }
+  const eq = pair.indexOf("=");
+  if (eq <= 0) {
+    throw new Error(`invalid --set value '${pair}', expected key=value`);
+  }
+  const key = pair.slice(0, eq);
+  const raw = pair.slice(eq + 1);
+  try {
+    return { key, value: JSON.parse(raw) };
+  } catch {
+    return { key, value: raw };
+  }
+}
+
+/**
+ * Maps `--set key=value` CLI params onto `msg.payload` attributes.
+ *
+ * Existing payload attributes are kept; `--set` params are applied on top,
+ * in the given order, so later params win on key collisions. If the current
+ * payload isn't a plain object (e.g. absent, a primitive, or an array), it is
+ * replaced by a fresh object built from the params.
+ */
+function applySetParams(payload, pairs) {
+  if (pairs.length === 0) return payload;
+
+  const base = payload && typeof payload === "object" && !Array.isArray(payload) ? payload : {};
+  const merged = { ...base };
+  for (const pair of pairs) {
+    const { key, value } = parseSetParam(pair);
+    merged[key] = value;
+  }
+  return merged;
+}
+
+/**
+ * Resolves a `--flow-json <value>` CLI option into a parsed flow array.
+ *
+ * Supports three forms:
+ * - `-`: read the flow JSON from stdin, via the injected `readStdin()`.
+ * - `@<path>`: read the flow JSON from the file at `<path>` (resolved
+ *   relative to `cwd`), mirroring the positional `<flows.json>` argument.
+ * - anything else: treated as an inline JSON string.
+ *
+ * Throws a clear `Error` when the value isn't valid JSON, or when it parses
+ * to something other than an array (Node-RED flow files are JSON arrays of
+ * node configs).
+ */
+async function parseFlowJsonParam(value, { readStdin, cwd = process.cwd() } = {}) {
+  let raw;
+  let source;
+  if (value === "-") {
+    if (typeof readStdin !== "function") {
+      throw new Error("--flow-json - requires stdin support");
+    }
+    raw = await readStdin();
+    source = "stdin";
+  } else if (value.startsWith("@")) {
+    const fs = require("node:fs");
+    const path = require("node:path");
+    const filePath = path.resolve(cwd, value.slice(1));
+    source = filePath;
+    try {
+      raw = fs.readFileSync(filePath, "utf8");
+    } catch (error) {
+      throw new Error(`could not read --flow-json file '${filePath}': ${error.message}`, { cause: error });
+    }
+  } else {
+    raw = value;
+    source = "--flow-json value";
+  }
+
+  let flows;
+  try {
+    flows = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`invalid JSON from ${source}: ${error.message}`, { cause: error });
+  }
+
+  if (!Array.isArray(flows)) {
+    throw new Error(`the flow JSON from ${source} must be an array of node configs`);
+  }
+
+  return flows;
+}
+
+const VALID_FORMATS = ["json", "plain"];
+
+/**
+ * Validates the `--format` CLI option value.
+ *
+ * Returns the format unchanged when valid (`"json"` or `"plain"`); throws
+ * otherwise so the CLI can report a clear error and exit non-zero.
+ */
+function parseFormatParam(format) {
+  if (!VALID_FORMATS.includes(format)) {
+    throw new Error(`invalid --format value '${format}', expected one of: ${VALID_FORMATS.join(", ")}`);
+  }
+  return format;
+}
+
+/**
+ * Renders a link-out result for `--format=plain`: just the raw payload,
+ * as text. Strings are printed as-is; other JSON-compatible values
+ * (numbers, booleans, null, objects, arrays) are JSON-stringified.
+ */
+function formatPlain(payload) {
+  return typeof payload === "string" ? payload : JSON.stringify(payload);
+}
+
+module.exports = {
+  parseSetParam,
+  applySetParams,
+  parseFlowJsonParam,
+  parseFormatParam,
+  formatPlain,
+  VALID_FORMATS
+};

package/src/flow-storage.js

@@ -0,0 +1,34 @@
+"use strict";
+
+/**
+ * Builds a Node-RED `storageModule` that serves an in-memory flow array
+ * instead of reading/writing a flow file on disk.
+ *
+ * Implements the minimal `storageModule` contract used by
+ * `@node-red/runtime/lib/storage`: `init`, `getFlows`, `saveFlows`,
+ * `getCredentials`/`saveCredentials`, `getSettings`/`saveSettings`. Since the
+ * CLI never persists anything, all save operations are no-ops and settings
+ * are not backed by storage.
+ *
+ * `saveFlows` is a no-op by design: this CLI never mutates the caller's
+ * in-memory flow definition or persists it anywhere.
+ */
+function createMemoryStorageModule(flows) {
+  return {
+    async init() {},
+    async getFlows() {
+      return flows;
+    },
+    async saveFlows() {},
+    async getCredentials() {
+      return {};
+    },
+    async saveCredentials() {},
+    async getSettings() {
+      return null;
+    },
+    async saveSettings() {}
+  };
+}
+
+module.exports = { createMemoryStorageModule };

package/src/link-call.js

@@ -0,0 +1,326 @@
+"use strict";
+
+const crypto = require("node:crypto");
+
+function getConfigs(RED, errors) {
+  const configs = new Map();
+  RED.nodes.eachNode((config) => {
+    if (configs.has(config.id)) errors.push(`duplicate node id '${config.id}'`);
+    configs.set(config.id, config);
+  });
+  return configs;
+}
+
+/** Resolve a Node-RED workspace tab by id or label. */
+function resolveFlow(RED, flowSelector) {
+  const errors = [];
+  const configs = getConfigs(RED, errors);
+  const flows = [...configs.values()].filter((config) => config.type === "tab");
+
+  if (typeof flowSelector === "undefined" || flowSelector === null || flowSelector === "") {
+    if (flows.length === 1) {
+      return { ok: errors.length === 0, errors, flow: flows[0], configs, selectedBy: "fallback" };
+    }
+    errors.push(
+      flows.length === 0
+        ? "the loaded flow configuration contains no workspace tabs"
+        : `flow must be specified because ${flows.length} workspace tabs are present`
+    );
+    return { ok: false, errors, configs };
+  }
+
+  if (typeof flowSelector !== "string") {
+    errors.push("flow must be a workspace tab id or label");
+    return { ok: false, errors, configs };
+  }
+
+  let matches = flows.filter((flow) => flow.id === flowSelector);
+  let selectedBy = "id";
+  if (matches.length === 0) {
+    matches = flows.filter((flow) => flow.label === flowSelector);
+    selectedBy = "label";
+  }
+  if (matches.length === 1) {
+    return { ok: errors.length === 0, errors, flow: matches[0], configs, selectedBy };
+  }
+  errors.push(
+    matches.length === 0
+      ? `flow '${flowSelector}' was not found`
+      : `flow label '${flowSelector}' is ambiguous`
+  );
+  return { ok: false, errors, configs };
+}
+
+/** Find `link in` nodes, optionally restricted to a single flow tab. */
+function findLinkIns(configs, flowId) {
+  return [...configs.values()].filter(
+    (config) => config.type === "link in" && (typeof flowId === "undefined" || config.z === flowId)
+  );
+}
+
+function resolveTargetFallback(configs, flows, flowSelector) {
+  const flowOmitted = typeof flowSelector === "undefined" || flowSelector === null || flowSelector === "";
+  if (!flowOmitted) return null; // caller resolves the flow normally and scopes the fallback to it
+
+  const allLinkIns = findLinkIns(configs);
+  if (allLinkIns.length === 1) {
+    const targetConfig = allLinkIns[0];
+    const flow = configs.get(targetConfig.z);
+    const warnings = [];
+    if (flows.length > 1) {
+      warnings.push(
+        `flow not specified; inferred flow '${flow?.label || flow?.id || targetConfig.z}' and target ` +
+          `'${targetConfig.name || targetConfig.id}' from the only link-in node in the configuration`
+      );
+    }
+    return { ok: true, flow, targetConfig, warnings };
+  }
+  if (allLinkIns.length === 0) {
+    return { ok: false, errors: ["no link-in nodes found in the flow configuration"], warnings: [] };
+  }
+  // allLinkIns.length > 1
+  if (flows.length <= 1) {
+    return {
+      ok: false,
+      errors: [`target must be specified because ${allLinkIns.length} link-in nodes are present`],
+      warnings: []
+    };
+  }
+  return {
+    ok: false,
+    errors: [
+      `flow must be specified because ${flows.length} workspace tabs are present`,
+      `target must be specified because ${allLinkIns.length} link-in nodes are present across those tabs`
+    ],
+    warnings: []
+  };
+}
+
+function validateTarget(RED, targetSelector, { flow } = {}) {
+  const errors = [];
+  const configs = getConfigs(RED, errors);
+  const flows = [...configs.values()].filter((config) => config.type === "tab");
+  const targetOmitted =
+    typeof targetSelector === "undefined" || targetSelector === null || targetSelector === "";
+
+  const fallback = targetOmitted ? resolveTargetFallback(configs, flows, flow) : null;
+
+  let selectedFlow;
+  let targetConfig;
+  let selectedFlowBy;
+  let warnings = [];
+
+  if (fallback) {
+    warnings = fallback.warnings;
+    if (fallback.ok) {
+      selectedFlow = fallback.flow;
+      targetConfig = fallback.targetConfig;
+      selectedFlowBy = "fallback-via-target";
+    } else {
+      errors.push(...fallback.errors);
+    }
+  } else {
+    const flowResolution = resolveFlow(RED, flow);
+    errors.push(...flowResolution.errors);
+    selectedFlow = flowResolution.flow;
+    selectedFlowBy = flowResolution.selectedBy;
+
+    if (targetOmitted && selectedFlow) {
+      const candidates = findLinkIns(configs, selectedFlow.id);
+      if (candidates.length === 1) {
+        targetConfig = candidates[0];
+      } else if (candidates.length === 0) {
+        errors.push(`no link-in nodes found in flow '${selectedFlow.id}'`);
+      } else {
+        errors.push(
+          `target must be specified because ${candidates.length} link-in nodes are present in flow '${selectedFlow.id}'`
+        );
+      }
+    }
+  }
+
+  if (!targetOmitted && (typeof targetSelector !== "string" || targetSelector.length === 0)) {
+    errors.push("target must be a non-empty link-in id or name");
+  }
+
+  // Validate all ordinary wires before following the requested target.
+  for (const config of configs.values()) {
+    for (const output of config.wires || []) {
+      for (const destinationId of output || []) {
+        if (!configs.has(destinationId)) {
+          errors.push(`node '${config.id}' wires to missing node '${destinationId}'`);
+        }
+      }
+    }
+  }
+
+  if (!targetOmitted) {
+    targetConfig = configs.get(targetSelector);
+    if (targetConfig && selectedFlow && targetConfig.z !== selectedFlow.id) {
+      errors.push(`target '${targetSelector}' does not belong to flow '${selectedFlow.id}'`);
+      targetConfig = undefined;
+    }
+    if (!targetConfig && selectedFlow && typeof targetSelector === "string") {
+      const matches = [...configs.values()].filter(
+        (config) =>
+          config.type === "link in" && config.z === selectedFlow.id && config.name === targetSelector
+      );
+      if (matches.length === 1) targetConfig = matches[0];
+      else if (matches.length > 1)
+        errors.push(`link in name '${targetSelector}' is ambiguous in flow '${selectedFlow.id}'`);
+    }
+    if (!targetConfig && selectedFlow)
+      errors.push(`target '${targetSelector}' is not present in flow '${selectedFlow.id}'`);
+  }
+  if (targetConfig && targetConfig.type !== "link in") {
+    errors.push(`target '${targetConfig.id}' has type '${targetConfig.type}', expected 'link in'`);
+  }
+
+  const targetNode = targetConfig && RED.nodes.getNode(targetConfig.id);
+  if (targetConfig && !targetNode)
+    errors.push(`target '${targetConfig.id}' is not instantiated in the runtime`);
+  else if (targetNode && targetNode.type !== "link in")
+    errors.push(`runtime target '${targetConfig.id}' is not a 'link in' node`);
+
+  const reachable = new Set();
+  const returnIds = new Set();
+  function walk(id) {
+    if (reachable.has(id)) return;
+    reachable.add(id);
+    const config = configs.get(id);
+    if (!config) return;
+    if (config.type === "link out" && config.mode === "return") returnIds.add(id);
+    for (const output of config.wires || []) {
+      for (const destinationId of output || []) walk(destinationId);
+    }
+  }
+  if (targetConfig) walk(targetConfig.id);
+
+  if (targetConfig && (!targetConfig.wires || targetConfig.wires.every((output) => !output?.length))) {
+    errors.push(`target '${targetConfig.id}' has no outgoing wires`);
+  }
+  if (targetConfig && returnIds.size === 0) {
+    errors.push(`target '${targetConfig.id}' has no reachable link out with mode 'return'`);
+  }
+  for (const returnId of returnIds) {
+    if (!RED.nodes.getNode(returnId))
+      errors.push(`return node '${returnId}' is not instantiated in the runtime`);
+  }
+
+  if (!RED.hooks || typeof RED.hooks.add !== "function" || typeof RED.hooks.remove !== "function") {
+    errors.push("Node-RED runtime hooks are not available");
+  }
+
+  return {
+    ok: errors.length === 0,
+    flowId: selectedFlow?.id,
+    flowLabel: selectedFlow?.label,
+    selectedFlowBy,
+    targetId: targetConfig?.id,
+    targetName: targetConfig?.name,
+    errors: [...new Set(errors)],
+    warnings: [...new Set(warnings)],
+    reachableNodeIds: [...reachable],
+    returnLinkOutIds: [...returnIds]
+  };
+}
+
+/**
+ * Adapter for Node-RED 5.0.x link-in/link-out(return) flows.
+ *
+ * This intentionally uses Node-RED's current internal message convention
+ * (_linkSource) and the documented runtime onReceive hook. Keep it isolated
+ * and covered by integration tests; it is not a public Node-RED call API.
+ */
+function createHostLinkCaller(RED) {
+  const callerId = `__node-red-cli-host-${crypto.randomBytes(8).toString("hex")}`;
+  const pending = new Map();
+  const returnLinkOutIds = new Set();
+  const hookId = `onReceive.${callerId}`;
+
+  // RED.nodes is internal. We only read the deployed node configuration;
+  // no node is added, rewired, deployed or removed.
+  RED.nodes.eachNode((config) => {
+    if (config.type === "link out" && config.mode === "return") {
+      returnLinkOutIds.add(config.id);
+    }
+  });
+
+  RED.hooks.add(hookId, ({ msg, destination }) => {
+    if (!returnLinkOutIds.has(destination.id)) return;
+
+    const stack = msg?._linkSource;
+    const source = stack?.[stack.length - 1];
+    if (source?.node !== callerId) return;
+
+    // Mirror LinkCallNode/FunctionNode cleanup before returning the result.
+    stack.pop();
+    if (stack.length === 0) delete msg._linkSource;
+
+    const operation = pending.get(source.id);
+    if (operation) {
+      pending.delete(source.id);
+      clearTimeout(operation.timer);
+      operation.resolve(msg);
+    }
+
+    // Do not let LinkOutNode continue: it would try RED.nodes.getNode(callerId),
+    // but the host intentionally is not a configured Node-RED node.
+    return false;
+  });
+
+  function call(target, msg, { flow, timeout = 5000, clone = true, onWarning } = {}) {
+    const validation = validateTarget(RED, target, { flow });
+    if (!validation.ok) {
+      return Promise.reject(new Error(`preflight validation failed:\n- ${validation.errors.join("\n- ")}`));
+    }
+    if (typeof onWarning === "function") {
+      for (const warning of validation.warnings) onWarning(warning);
+    }
+    if (!Number.isFinite(timeout) || timeout <= 0) {
+      return Promise.reject(new TypeError("timeout must be a positive number of milliseconds"));
+    }
+    if (!msg || typeof msg !== "object" || Array.isArray(msg)) {
+      return Promise.reject(new TypeError("msg must be an object"));
+    }
+
+    const targetNode = RED.nodes.getNode(validation.targetId);
+    if (!targetNode || targetNode.type !== "link in") {
+      return Promise.reject(new Error(`link in '${validation.targetId}' not found`));
+    }
+
+    const callId = crypto.randomBytes(14).toString("hex");
+    const input = clone ? RED.util.cloneMessage(msg) : msg;
+    input._linkSource ??= [];
+    input._linkSource.push({ node: callerId, id: callId });
+
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        pending.delete(callId);
+        reject(new Error(`link call timed out after ${timeout} ms`));
+      }, timeout);
+
+      pending.set(callId, { resolve, reject, timer });
+      try {
+        targetNode.receive(input);
+      } catch (error) {
+        pending.delete(callId);
+        clearTimeout(timer);
+        reject(error);
+      }
+    });
+  }
+
+  function close(reason = new Error("host link caller closed")) {
+    RED.hooks.remove(hookId);
+    for (const operation of pending.values()) {
+      clearTimeout(operation.timer);
+      operation.reject(reason);
+    }
+    pending.clear();
+  }
+
+  return { call, close };
+}
+
+module.exports = { createHostLinkCaller, resolveFlow, validateTarget };

package/src/node-modules-install.js

@@ -0,0 +1,148 @@
+"use strict";
+
+/**
+ * Disk-diffing and npm install logic for `--node-modules`.
+ *
+ * Installation is done by shelling out to the npm CLI bundled as a
+ * transitive dependency of `node-red` (the same binary Node-RED's own
+ * palette manager uses, see `@node-red/registry/lib/installer.js`),
+ * rather than going through `RED.nodes.installModule()`. That API only
+ * works reliably once `RED.start()` has fully completed (it needs
+ * runtime settings that aren't available until then), but by that point
+ * the target flow has already been deployed with any node types it
+ * references unresolved, and Node-RED does not hot-swap a "missing" node
+ * into a freshly installed one without a fresh deploy. Installing via a
+ * plain `npm install` into `userDir` before `RED.init()`/`RED.start()` is
+ * simpler and avoids that ordering problem entirely: Node-RED's own
+ * `localfilesystem` node loader always scans `<userDir>/node_modules` on
+ * disk regardless of which flow storage module is used, so a module
+ * installed this way is picked up like any other palette-installed node.
+ */
+
+const fs = require("node:fs");
+const path = require("node:path");
+const childProcess = require("node:child_process");
+
+/**
+ * Checks whether `<userDir>/node_modules/<name>` is already present and
+ * consistent (has a readable `package.json` with a `node-red` key, and
+ * matches `version` when given). Returns `false` for a partially-written
+ * or otherwise inconsistent module directory so it gets (re)installed
+ * rather than treated as already installed.
+ */
+function isModuleInstalled(userDir, name, version) {
+  const pkgPath = path.join(userDir, "node_modules", name, "package.json");
+  let pkg;
+  try {
+    pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+  } catch {
+    return false;
+  }
+  if (!pkg || typeof pkg !== "object" || !pkg["node-red"]) {
+    return false;
+  }
+  if (version && pkg.version !== version) {
+    return false;
+  }
+  return true;
+}
+
+/** Returns the subset of `modules` not already present/consistent in `userDir`. */
+function diffMissingModules(userDir, modules) {
+  return modules.filter(({ name, version }) => !isModuleInstalled(userDir, name, version));
+}
+
+function npmCliPath() {
+  return path.join(path.dirname(require.resolve("npm/package.json")), "bin", "npm-cli.js");
+}
+
+/**
+ * Verifies the bundled npm CLI is usable, mirroring
+ * `@node-red/registry/lib/installer.js`'s own `checkPrereq()` npm-version
+ * check. Throws a clear error otherwise (e.g. missing/broken `npm` install
+ * or unusable Node.js binary).
+ */
+function checkNpmAvailable() {
+  return new Promise((resolve, reject) => {
+    childProcess.execFile(process.execPath, [npmCliPath(), "-v"], (error) => {
+      if (error) {
+        reject(new Error(`npm is not available (required by --node-modules): ${error.message}`));
+        return;
+      }
+      resolve();
+    });
+  });
+}
+
+/** Runs `npm install <name>[@version]` into `userDir`, returns on success, throws a clear error otherwise. */
+function npmInstall(userDir, { name, version }, timeoutMs = 5 * 60 * 1000) {
+  const installName = version ? `${name}@${version}` : name;
+  const args = [
+    npmCliPath(),
+    "install",
+    "--no-audit",
+    "--no-update-notifier",
+    "--no-fund",
+    "--save",
+    "--omit=dev",
+    "--",
+    installName
+  ];
+  return new Promise((resolve, reject) => {
+    childProcess.execFile(
+      process.execPath,
+      args,
+      { cwd: userDir, timeout: timeoutMs },
+      (error, stdout, stderr) => {
+        if (error) {
+          if (error.killed || error.signal) {
+            reject(
+              new Error(
+                `failed to install --node-modules '${installName}': npm install timed out after ${timeoutMs}ms ` +
+                  "(is the npm registry reachable?)"
+              )
+            );
+            return;
+          }
+          const detail = (stderr || stdout || error.message).trim().split("\n").slice(-20).join("\n");
+          reject(new Error(`failed to install --node-modules '${installName}': ${detail}`));
+          return;
+        }
+        resolve();
+      }
+    );
+  });
+}
+
+/**
+ * Installs every module in `modules` that is missing/inconsistent in
+ * `<userDir>/node_modules`, skipping any already present and consistent.
+ * Installs run sequentially so a shared `userDir` isn't hit by concurrent
+ * npm invocations from within a single CLI run. Throws on the first
+ * failure (no partial-success reporting) and re-validates the module is a
+ * genuine Node-RED node module afterwards.
+ */
+async function installMissingNodeModules(userDir, modules, { timeoutMs } = {}) {
+  const missing = diffMissingModules(userDir, modules);
+  if (missing.length === 0) return { installed: [], skipped: modules };
+
+  await checkNpmAvailable();
+  fs.mkdirSync(userDir, { recursive: true });
+
+  for (const module of missing) {
+    await npmInstall(userDir, module, timeoutMs);
+    if (!isModuleInstalled(userDir, module.name, module.version)) {
+      throw new Error(
+        `failed to install --node-modules '${module.name}': installed package is not a valid Node-RED node module (missing "node-red" key in its package.json)`
+      );
+    }
+  }
+  return { installed: missing, skipped: modules.filter((m) => !missing.includes(m)) };
+}
+
+module.exports = {
+  isModuleInstalled,
+  diffMissingModules,
+  installMissingNodeModules,
+  checkNpmAvailable
+};