@tbrandenburg/node-red-cli 0.2.11 → 0.2.13

package/README.md

@@ -54,6 +54,7 @@ make install-global
   - [Passing flow JSON inline](#passing-flow-json-inline)
   - [Installing additional Node-RED node packages](#installing-additional-node-red-node-packages)
   - [Running sandboxed in Docker](#running-sandboxed-in-docker-)
+  - [Agentic workflows](#agentic-workflows-)
 - [Host API](#host-api-)
 - [Technical approach](#technical-approach-)
 - [Preflight and limitations](#preflight-and-limitations-)
@@ -277,7 +278,9 @@ Sandboxing defaults applied to every `--docker` run:
 
 - `--rm -i` (always disposable)
 - `--network none`, unless `--node-modules` is also given (needs registry
-  access) — narrowest network exposure by default
+  access) or `--network` is passed explicitly (enables network access for a
+  flow that needs to call out, independent of installing any package) —
+  narrowest network exposure by default
 - `--read-only` root filesystem + a `/tmp` tmpfs mount
 - `--cap-drop=ALL`
 - `--security-opt=no-new-privileges`
@@ -293,6 +296,45 @@ failed: ...` if the image build fails (e.g. the local version isn't yet
 published to npm — use `--docker <image>` or `--docker @path` as an
 escape hatch in that case).
 
+### Agentic workflows 🤖
+
+Node-RED nodes such as [`agent`](https://www.npmjs.com/package/@tbrandenburg/node-red-agents)
+(OpenCode, `pi`) turn a `link in -> agent -> link out (return)` flow into a
+callable AI step, invoked like any other target — a JSON flow with an
+inline multiline prompt, in one command:
+
+```bash
+echo '{"payload":"Summarize this repo in one sentence.","cwd":"/repo"}' \
+  | node-red-cli --flow-json '[
+      {"id":"tab","type":"tab","label":"Agent"},
+      {"id":"ask","type":"link in","z":"tab","name":"ask","wires":[["agent"]]},
+      {"id":"agent","type":"agent","z":"tab","name":"opencode","agent":"opencode",
+       "runtime":"direct","prompt":"payload","promptType":"msg",
+       "cwd":"cwd","cwdType":"msg","wires":[["return"],[]]},
+      {"id":"return","type":"link out","z":"tab","name":"return","mode":"return"}
+    ]' ask --node-modules @tbrandenburg/node-red-agents --user-dir --timeout=120000 --format=json
+```
+
+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):
+
+```bash
+echo '{"payload":"Summarize this repo in one sentence.","cwd":"/repo"}' \
+  | node-red-cli --flow-json '[
+      {"id":"tab","type":"tab","label":"Agent"},
+      {"id":"ask","type":"link in","z":"tab","name":"ask","wires":[["agent"]]},
+      {"id":"agent","type":"agent","z":"tab","name":"opencode","agent":"opencode",
+       "runtime":"direct","prompt":"payload","promptType":"msg",
+       "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
+```
+
 ## Host API 🛠️
 
 The core interface is intentionally small:

package/bin/node-red-cli.js

@@ -70,10 +70,11 @@ const HELP_TEXT = [
   "  - '@<path>' or an http(s) URL: build from a Dockerfile (local file or",
   "    fetched URL), cached by content hash.",
   "Sandboxing defaults: --network none (unless --node-modules is also set,",
-  "which needs registry access), --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.",
+  "which needs registry access, or --network is passed explicitly to enable",
+  "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.",
   "",
   "Example:",
   '  echo \'{"payload":{"x":4,"y":5}}\' | node-red-cli flows.json calculate',
@@ -231,7 +232,10 @@ async function run(args, options) {
     let result;
     try {
       image = await resolveImage(options.docker, { version });
-      result = await runContainer(image, envelope, { networkNeeded: nodeModules.length > 0, volumeName });
+      result = await runContainer(image, envelope, {
+        networkNeeded: nodeModules.length > 0 || options.network,
+        volumeName
+      });
     } catch (error) {
       console.error(error.message);
       process.exitCode = 1;
@@ -296,6 +300,10 @@ program
     "run the invocation sandboxed in a disposable Docker container; bare = cached default image, " +
       "'<image[:tag]>' = explicit image (installed into if missing), '@path'/URL = build from a Dockerfile"
   )
+  .option(
+    "--network",
+    "enable network access in --docker mode, independent of --node-modules (default: --network none)"
+  )
   .addHelpText("after", HELP_TEXT)
   .version(version, "-v, --version", "print the installed node-red-cli version and exit")
   .action(run);

package/package.json

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

package/src/docker-image.js

@@ -87,9 +87,16 @@ function derivedDockerfile(image, version) {
   // The derived image is left running as root - restoring the original
   // image's default user would require inspecting the base image at build
   // time, which is out of scope here.
+  //
+  // Force the npm global prefix to /usr/local regardless of what the base
+  // image's own NPM_CONFIG_PREFIX/.npmrc sets: SANDBOX_ENTRY_PATH is
+  // hardcoded to /usr/local, so an install that lands elsewhere would
+  // silently succeed at build time but fail with MODULE_NOT_FOUND at
+  // `docker run`.
   return [
     `FROM ${image}`,
     "USER root",
+    "ENV NPM_CONFIG_PREFIX=/usr/local",
     `RUN npm install -g @tbrandenburg/node-red-cli@${version}`,
     `ENTRYPOINT ["node", "${SANDBOX_ENTRY_PATH}"]`,
     ""

package/src/docker-run.js

@@ -8,8 +8,11 @@
  *
  * Sandboxing defaults (always applied):
  * - `--rm -i` (always disposable, interactive stdin)
- * - `--network none`, unless `networkNeeded` (i.e. `--node-modules` is set)
+ * - `--network none`, unless `networkNeeded` (i.e. `--node-modules` and/or
+ *   the CLI's `--network` flag is set)
  * - `--read-only` root filesystem + a `/tmp` tmpfs mount
+ * - `-e HOME=/tmp`, so tools needing a writable `$HOME` (config/cache dirs)
+ *   land on the writable `/tmp` tmpfs instead of the read-only rootfs
  * - `--cap-drop=ALL`
  * - `--security-opt=no-new-privileges`
  *
@@ -35,6 +38,7 @@ function buildRunArgs(image, { networkNeeded, volumeName }) {
   const args = ["run", "--rm", "-i"];
   if (!networkNeeded) args.push("--network", "none");
   args.push("--read-only", "--tmpfs", "/tmp", "--cap-drop=ALL", "--security-opt=no-new-privileges");
+  args.push("-e", "HOME=/tmp");
   if (networkNeeded) {
     // --node-modules runs a real `npm install`, which needs a writable cache
     // dir; point it at the /tmp tmpfs since the root filesystem is read-only.