@tbrandenburg/node-red-cli 0.2.13 → 0.2.15

package/README.md

@@ -319,8 +319,11 @@ The same flow runs sandboxed via `--docker <image>` against an image that
 already ships `opencode` + `node-red-agents`, e.g.
 [`ghcr.io/tbrandenburg/agentic-workflow-dev-env`](https://github.com/tbrandenburg/agentic-workflow-dev-env)
 (`--network` is required for network access, since the agent calls out to
-its own API — the package is already in the image, so `--node-modules` is
-not needed here):
+its own API; `--node-modules`/`--user-dir` are still required too, since
+Node-RED only discovers node types from a userDir it actually loaded —
+see [#24](https://github.com/tbrandenburg/node-red-cli/issues/24) for a
+currently-tracked compatibility gap when the image's own default userDir
+already ships the package):
 
 ```bash
 echo '{"payload":"Summarize this repo in one sentence.","cwd":"/repo"}' \
@@ -332,7 +335,8 @@ echo '{"payload":"Summarize this repo in one sentence.","cwd":"/repo"}' \
        "cwd":"cwd","cwdType":"msg","wires":[["return"],[]]},
       {"id":"return","type":"link out","z":"tab","name":"return","mode":"return"}
     ]' ask --docker ghcr.io/tbrandenburg/agentic-workflow-dev-env:latest \
-    --network --timeout=120000 --format=json
+    --node-modules @tbrandenburg/node-red-agents --user-dir --network \
+    --timeout=120000 --format=json
 ```
 
 ## Host API 🛠️

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tbrandenburg/node-red-cli",
-  "version": "0.2.13",
+  "version": "0.2.15",
   "description": "Call existing Node-RED flows from Node.js and the command line",
   "main": "src/link-call.js",
   "bin": {

package/src/node-modules-install.js

@@ -74,7 +74,13 @@ function checkNpmAvailable() {
   });
 }
 
-/** Runs `npm install <name>[@version]` into `userDir`, returns on success, throws a clear error otherwise. */
+/**
+ * Runs `npm install <name>[@version]` into `userDir`, returns on success,
+ * throws a clear error otherwise. Passes an explicit `--prefix <userDir>`
+ * so npm's own project-root/workspace detection can't walk up to an
+ * ancestor directory's `node_modules` when `userDir` is fresh/empty
+ * (see issue #24); `cwd` is kept as-is for the npm CLI invocation itself.
+ */
 function npmInstall(userDir, { name, version }, timeoutMs = 5 * 60 * 1000) {
   const installName = version ? `${name}@${version}` : name;
   const args = [
@@ -85,6 +91,8 @@ function npmInstall(userDir, { name, version }, timeoutMs = 5 * 60 * 1000) {
     "--no-fund",
     "--save",
     "--omit=dev",
+    "--prefix",
+    userDir,
     "--",
     installName
   ];
@@ -144,5 +152,6 @@ module.exports = {
   isModuleInstalled,
   diffMissingModules,
   installMissingNodeModules,
-  checkNpmAvailable
+  checkNpmAvailable,
+  npmInstall
 };

package/src/run-envelope.js

@@ -34,6 +34,104 @@ function stderrLogHandler() {
   };
 }
 
+/**
+ * Node-RED's flow parser (`@node-red/runtime/lib/flows/util.js`) classifies
+ * *any* node lacking both `x` and `y` properties as a global config node --
+ * regardless of its actual `type` -- since those coordinates are otherwise
+ * only ever used by the editor canvas. A real, editor-exported flow always
+ * has them on every wired node, so this never matters there. But hand-authored
+ * `--flow-json` flows (this tool's own core use case; see the README's
+ * `agent` example) commonly omit them, since they carry no runtime meaning.
+ * A wired node misclassified as a config node undergoes `Flow.js`'s
+ * config-node circular-dependency scan instead of normal instantiation,
+ * which scans every one of its own property values against other node ids
+ * and throws "Circular config node dependency detected" the moment any
+ * property value happens to equal another node's id -- including its own,
+ * e.g. a node whose `name` equals its own `id` (an extremely natural thing
+ * to write by hand, and exactly what the README's own agent example does).
+ * That aborts the whole flow's instantiation, so downstream preflight
+ * validation reports the target/return nodes as "not instantiated" even
+ * though the flow is otherwise entirely valid (see issue #28).
+ *
+ * Fix: assign synthetic coordinates to every node that is unambiguously a
+ * regular (wired) node -- i.e. it already declares a `wires` array, or is a
+ * `link out` node (which routes via `links` instead of `wires`) -- so
+ * Node-RED's parser classifies it correctly. Nodes without either (real
+ * config nodes) are left untouched.
+ */
+function withDeployCoordinates(flow) {
+  let n = 0;
+  return flow.map((node) => {
+    const isWired = Object.prototype.hasOwnProperty.call(node, "wires") || node.type === "link out";
+    const hasCoords =
+      Object.prototype.hasOwnProperty.call(node, "x") && Object.prototype.hasOwnProperty.call(node, "y");
+    if (!isWired || hasCoords) return node;
+    n += 1;
+    return { ...node, x: n * 100, y: 100 };
+  });
+}
+
+/**
+ * Waits for Node-RED to finish attempting to start the deployed flows.
+ *
+ * `RED.start()` resolves as soon as the runtime itself has booted, but the
+ * actual flow deploy happens asynchronously afterward and normally signals
+ * completion via a one-off `flows:started` event. However, when the flow
+ * references a node type that isn't registered (or another deploy-blocking
+ * condition applies, e.g. missing external modules or safe mode), Node-RED's
+ * `Flow.start()` logs the problem and returns *without* ever emitting
+ * `flows:started` (see `@node-red/runtime/lib/flows/index.js`). Awaiting
+ * only `flows:started` would then hang forever; since nothing else keeps
+ * the event loop alive, the process exits silently with code 0 once the
+ * loop drains, abandoning the pending call.
+ *
+ * Node-RED does always emit a `runtime-event` with id `runtime-state` in
+ * both cases: `payload.state === "start"` on success, and
+ * `payload.state === "stop"` / `"safe"` on any of the early-return failure
+ * paths. Racing both events lets us return as soon as Node-RED has settled
+ * either way; if the flows never actually started, the target/return nodes
+ * simply won't be instantiated and the existing preflight validation in
+ * `createHostLinkCaller` reports the real, specific error instead.
+ *
+ * A `stop`/`safe` `runtime-state` event and a real `flows:started` are
+ * mutually exclusive outcomes of the same deploy attempt in the installed
+ * `@node-red/runtime` (each early-return failure path returns before ever
+ * reaching the code that emits `flows:started`), so this never races in
+ * practice today. Still, resolving on `stop`/`safe` is deferred by one
+ * macrotask (`setImmediate`) rather than immediately, so that if a
+ * `flows:started` for the same attempt is already scheduled to fire right
+ * after, it wins instead -- cheap insurance against exactly the kind of
+ * premature-resolution regression reported in issue #28, without delaying
+ * genuine failures beyond a single negligible tick.
+ *
+ * (Uses `setTimeout(fn, 0)` rather than `setImmediate` purely because the
+ * latter isn't part of this project's configured ESLint globals; both defer
+ * to the next macrotask.)
+ */
+function waitForFlowsSettled(RED) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      RED.events.removeListener("flows:started", onStarted);
+      RED.events.removeListener("runtime-event", onRuntimeEvent);
+      resolve();
+    };
+    const onStarted = () => finish();
+    const onRuntimeEvent = (event) => {
+      if (
+        event?.id === "runtime-state" &&
+        (event.payload?.state === "stop" || event.payload?.state === "safe")
+      ) {
+        setTimeout(finish, 0);
+      }
+    };
+    RED.events.once("flows:started", onStarted);
+    RED.events.on("runtime-event", onRuntimeEvent);
+  });
+}
+
 /**
  * Runs a single link-call invocation against a real, freshly booted
  * Node-RED runtime: installs any missing `--node-modules`, boots RED with
@@ -71,7 +169,7 @@ async function runFlowInvocation({ flow, flowFile, msg, options }) {
 
     let caller;
     RED.init({
-      ...(flow ? { storageModule: createMemoryStorageModule(flow) } : { flowFile }),
+      ...(flow ? { storageModule: createMemoryStorageModule(withDeployCoordinates(flow)) } : { flowFile }),
       userDir,
       httpAdminRoot: false,
       httpNodeRoot: false,
@@ -80,9 +178,9 @@ async function runFlowInvocation({ flow, flowFile, msg, options }) {
     });
 
     try {
-      const flowsStarted = new Promise((resolve) => RED.events.once("flows:started", resolve));
+      const flowsSettled = waitForFlowsSettled(RED);
       await RED.start();
-      await flowsStarted;
+      await flowsSettled;
 
       caller = createHostLinkCaller(RED);
       const result = await caller.call(target, msg, {