@tbrandenburg/node-red-cli 0.2.14 → 0.2.16

package/README.md

@@ -290,6 +290,15 @@ deterministic **named Docker volume** (derived from the `--user-dir` value)
 mounted inside the container, never a host bind mount — so "no stray host
 files" holds even for persistent installs.
 
+For images/derived images that pre-install Node-RED node packages into
+their own conventional userDir, setting the `NODE_RED_CLI_DEFAULT_USERDIR`
+environment variable (inside the image, e.g. via `ENV`) to that path lets
+`--docker` discover it automatically whenever `--user-dir` isn't given —
+that directory is used as `userDir` and, like an explicit `--user-dir`,
+never deleted afterward. If the path doesn't exist or isn't a directory,
+`--docker` logs a warning and falls back to the normal ephemeral `userDir`
+rather than failing the invocation.
+
 Fails fast with a clear `node-red-cli: docker unavailable: ...` error if
 the Docker CLI/daemon isn't reachable, or `node-red-cli: docker build
 failed: ...` if the image build fails (e.g. the local version isn't yet
@@ -320,10 +329,9 @@ 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; `--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):
+Node-RED only discovers node types from a userDir it actually loaded, and
+`--docker` doesn't yet reuse an image's own pre-populated default userDir —
+see [#31](https://github.com/tbrandenburg/node-red-cli/issues/31)):
 
 ```bash
 echo '{"payload":"Summarize this repo in one sentence.","cwd":"/repo"}' \

package/bin/node-red-cli-sandbox-entry.js

@@ -7,6 +7,12 @@
  * envelope as JSON from stdin, runs it against a real Node-RED runtime via
  * the shared `runFlowInvocation` (the exact same logic the host CLI uses
  * for its non-Docker path), and writes the formatted result to stdout.
+ *
+ * The `NODE_RED_CLI_DEFAULT_USERDIR` env-var convention (see #31), which
+ * lets an image's own pre-populated default userDir be discovered when
+ * `--user-dir` isn't given, is resolved entirely inside the shared
+ * `runFlowInvocation` (`src/run-envelope.js`) -- nothing to do here beyond
+ * the existing pass-through of `envelope.options`.
  */
 
 const { runFlowInvocation } = require("../src/run-envelope");

package/bin/node-red-cli.js

@@ -74,7 +74,9 @@ const HELP_TEXT = [
   "network access independent of installing any package), --read-only",
   "rootfs with a /tmp tmpfs, --cap-drop=ALL, --security-opt=no-new-privileges.",
   "When combined with --user-dir, persistence uses a named Docker volume,",
-  "never a host bind mount.",
+  "never a host bind mount. Image authors can set",
+  "NODE_RED_CLI_DEFAULT_USERDIR=<path> so a pre-installed userDir is",
+  "discovered automatically when --user-dir isn't given.",
   "",
   "Example:",
   '  echo \'{"payload":{"x":4,"y":5}}\' | node-red-cli flows.json calculate',

package/package.json

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

package/src/run-envelope.js

@@ -34,6 +34,43 @@ 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.
  *
@@ -55,20 +92,39 @@ function stderrLogHandler() {
  * 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) => {
-    const onStarted = () => {
+    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")
       ) {
-        RED.events.removeListener("flows:started", onStarted);
-        resolve();
+        setTimeout(finish, 0);
       }
     };
     RED.events.once("flows:started", onStarted);
@@ -76,6 +132,34 @@ function waitForFlowsSettled(RED) {
   });
 }
 
+/**
+ * Resolves the image/host-provided default `userDir` from the
+ * `NODE_RED_CLI_DEFAULT_USERDIR` environment variable (see #31): community
+ * Docker images that pre-install Node-RED node packages into their own
+ * conventional userDir can set this variable so `--docker` (without an
+ * explicit `--user-dir`) discovers it automatically. Returns `undefined` if
+ * unset. Fails open, not closed: if the path doesn't exist, isn't a
+ * directory, or isn't accessible, logs a one-line stderr warning and returns
+ * `undefined` so the caller falls back to its normal ephemeral tmpdir,
+ * rather than aborting the invocation.
+ */
+function resolveDefaultUserDir() {
+  const configuredPath = process.env.NODE_RED_CLI_DEFAULT_USERDIR;
+  if (!configuredPath) return undefined;
+
+  try {
+    if (fs.statSync(configuredPath).isDirectory()) return configuredPath;
+    console.error(
+      `node-red-cli: NODE_RED_CLI_DEFAULT_USERDIR='${configuredPath}' is not usable (not a directory), falling back to an ephemeral userDir`
+    );
+  } catch (error) {
+    console.error(
+      `node-red-cli: NODE_RED_CLI_DEFAULT_USERDIR='${configuredPath}' is not usable (${error.message}), falling back to an ephemeral userDir`
+    );
+  }
+  return undefined;
+}
+
 /**
  * Runs a single link-call invocation against a real, freshly booted
  * Node-RED runtime: installs any missing `--node-modules`, boots RED with
@@ -90,8 +174,13 @@ function waitForFlowsSettled(RED) {
  *
  * `options.userDir`, when set, is treated as a persistent directory and is
  * never removed afterward (host: an explicit `--user-dir`; container: the
- * fixed mount path of a named Docker volume). When omitted, an ephemeral
- * tmpdir is created and removed again after the call.
+ * fixed mount path of a named Docker volume). When omitted, and the
+ * `NODE_RED_CLI_DEFAULT_USERDIR` environment variable points at an existing
+ * directory (see `resolveDefaultUserDir`), that directory is used instead —
+ * also treated as persistent and never removed afterward, letting a Docker
+ * image's own pre-populated default userDir be discovered automatically
+ * (see #31). Otherwise an ephemeral tmpdir is created and removed again
+ * after the call.
  */
 async function runFlowInvocation({ flow, flowFile, msg, options }) {
   const {
@@ -104,7 +193,10 @@ async function runFlowInvocation({ flow, flowFile, msg, options }) {
   } = options;
 
   const persistentUserDir = Boolean(fixedUserDir);
-  const userDir = fixedUserDir || fs.mkdtempSync(path.join(os.tmpdir(), "node-red-cli-"));
+  const imageDefaultUserDir = !persistentUserDir ? resolveDefaultUserDir() : undefined;
+  const userDir =
+    fixedUserDir || imageDefaultUserDir || fs.mkdtempSync(path.join(os.tmpdir(), "node-red-cli-"));
+  const managedUserDir = !persistentUserDir && !imageDefaultUserDir;
 
   try {
     if (nodeModules.length > 0) {
@@ -113,7 +205,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,
@@ -138,8 +230,8 @@ async function runFlowInvocation({ flow, flowFile, msg, options }) {
       await RED.stop();
     }
   } finally {
-    if (!persistentUserDir) fs.rmSync(userDir, { recursive: true, force: true });
+    if (managedUserDir) fs.rmSync(userDir, { recursive: true, force: true });
   }
 }
 
-module.exports = { runFlowInvocation, stderrLogHandler };
+module.exports = { runFlowInvocation, stderrLogHandler, resolveDefaultUserDir };