onepipeline-cli 0.95.3 → 0.95.4

package/README.md

@@ -8,7 +8,13 @@ onepipeline --help
 ```
 
 The binary ships inside a per-platform package that npm selects by `os`/`cpu`, so
-there is no compile step and no Rust toolchain to install. The same binary is on
+there is no compile step and no Rust toolchain to install.
+
+On Linux and macOS the `onepipeline` command *becomes* the binary's process
+(`process.execve`), so it needs Node.js 22.15+ or 23.11+ and refuses an older
+one. On Windows, which has no exec, it runs the binary under a small keeper
+process that passes its exit status and console interrupts through and never
+leaves it running once the command has ended. The same binary is on
 [PyPI](https://pypi.org/project/onepipeline-cli/) (`pip install
 onepipeline-cli`) and [crates.io](https://crates.io/crates/onepipeline)
 (`cargo install onepipeline`).

package/bin/onepipeline.js

@@ -7,15 +7,30 @@
 // compile, no download at install time. The platform-specific binary ships
 // inside a per-platform package (`onepipeline-cli-<platform>-<arch>`) declared
 // in this package's `optionalDependencies`; npm installs only the one whose
-// `os`/`cpu` match the host, and this shim resolves it and execs it with the
-// caller's argv.
+// `os`/`cpu` match the host, and this shim resolves it and starts it with the
+// caller's argv, stdin, stdout and stderr.
+//
+// How it starts it is the point of this file. On Linux and macOS it *replaces
+// itself* with the binary (`process.execve`), so the process the caller started
+// is the engine: the PID the caller holds is the engine's, a signal sent to it
+// reaches the engine, and a process the engine starts sees the engine as its
+// parent — the process tree a PyPI or cargo install gives. A caller that marks
+// itself by the PID that execs the engine depends on exactly that, so a Node.js
+// without `process.execve` (before 22.15 / 23.11) is refused there rather than
+// given a child process in the engine's place.
+//
+// Windows has no exec. There the engine runs under a keeper process this one
+// starts (`supervise` below): this process exits with the engine's status, the
+// Ctrl+C and Ctrl+Break a console delivers reach the engine as they are, and the
+// engine is ended rather than orphaned when this process is ended — abruptly too.
 //
 // This file is committed source; the version and the optionalDependency versions
 // are stamped from Cargo.toml at publish time by scripts/npm-build.mjs, which
 // also generates the per-platform packages from the release binaries.
 
+const fs = require("node:fs");
 const path = require("node:path");
-const { spawnSync } = require("node:child_process");
+const { spawn } = require("node:child_process");
 
 // process.platform-process.arch -> the platform package that carries the binary.
 // The keys mirror the targets release/release.py builds, the TARGETS table in
@@ -82,16 +97,120 @@ function binaryPath() {
   }
 }
 
-const result = spawnSync(binaryPath(), process.argv.slice(2), { stdio: "inherit" });
+// The interrupts a Windows console delivers to every process attached to it,
+// the engine included. The engine already has each one, as itself, so this
+// process and the keeper hold on through them and report what the engine does.
+const CONSOLE_EVENTS = ["SIGINT", "SIGBREAK"];
+
+// The keeper, a Node process this one starts with an IPC channel to it. It
+// starts the engine as its own child, so it knows the engine the moment the
+// engine exists, and tells this process the engine's status. The channel breaks
+// however this process ends — TerminateProcess included, where no handler of
+// this process runs — and the keeper then ends the engine: there is no moment
+// at which the engine runs and nothing that would end it knows it, however
+// early in its start this process is ended. A message the keeper cannot
+// deliver is the same break, seen first: this process ended before the keeper
+// ran, and the failed send ends the engine rather than the keeper alone.
+const KEEPER = `
+const { spawn } = require("node:child_process");
+const [binary, ...args] = JSON.parse(process.argv[1]);
+for (const signal of ${JSON.stringify(CONSOLE_EVENTS)}) process.on(signal, () => {});
+const engine = spawn(binary, args, { stdio: "inherit" });
+const end = () => {
+  engine.kill("SIGKILL");
+  process.exit(0);
+};
+process.on("disconnect", end);
+const send = (message, then = () => {}) =>
+  process.send(message, (error) => (error ? end() : then()));
+if (engine.pid !== undefined) send({ engine: engine.pid });
+engine.on("error", (error) => send({ error: error.message }, () => process.exit(0)));
+engine.on("exit", (code) => send({ status: code ?? 1 }, () => process.exit(0)));
+`;
 
-if (result.error) {
-  fail(`failed to launch the onepipeline binary: ${result.error.message}`);
+function supervise(binary, args) {
+  for (const signal of CONSOLE_EVENTS) process.on(signal, () => {});
+  const keeper = spawn(process.execPath, ["-e", KEEPER, JSON.stringify([binary, ...args])], {
+    stdio: ["inherit", "inherit", "inherit", "ipc"],
+  });
+  // Without a keeper nothing would end the engine if this process were ended,
+  // so no engine is started: the command refuses instead.
+  keeper.on("error", (error) =>
+    fail(
+      `could not start the process that keeps the onepipeline binary from outliving ` +
+        `this command, so the binary was not started: ${error.message}`,
+    ),
+  );
+  let engine = null;
+  const endEngine = () => {
+    if (engine !== null) {
+      try {
+        process.kill(engine, "SIGKILL");
+      } catch {}
+    }
+  };
+  // The keeper's messages cross a process boundary, so each is read as exactly
+  // one of its three envelopes; anything else ends the engine and the command.
+  const isCount = (value) => Number.isInteger(value) && value >= 0;
+  // A Windows exit code is 32 bits; process.exit would wrap a larger one, 2^32 to 0.
+  const isStatus = (value) => isCount(value) && value <= 0xffffffff;
+  keeper.on("message", (message) => {
+    const keys = message !== null && typeof message === "object" ? Object.keys(message) : [];
+    const [key] = keys;
+    if (keys.length === 1 && key === "engine" && isCount(message.engine) && message.engine > 0) {
+      engine = message.engine;
+      return;
+    }
+    if (keys.length === 1 && key === "error" && typeof message.error === "string") {
+      fail(`failed to launch the onepipeline binary: ${message.error}`);
+    }
+    // The engine's exit code verbatim — the contract assigns meaning to 1 and 2,
+    // and a caller reads them.
+    if (keys.length === 1 && key === "status" && isStatus(message.status)) {
+      process.exit(message.status);
+    }
+    endEngine();
+    fail(
+      `the process keeping the onepipeline binary sent an unreadable message: ` +
+        JSON.stringify(message),
+    );
+  });
+  // A keeper gone without the engine's status has left the engine with
+  // nothing to end it, so this process ends it before saying so.
+  keeper.on("disconnect", () => {
+    endEngine();
+    fail("the process keeping the onepipeline binary ended without reporting its status");
+  });
 }
 
-// Re-raise a terminating signal so callers observe the true cause; otherwise
-// propagate the child's exit code verbatim — the contract assigns meaning to 1
-// and 2, and a caller reads them.
-if (result.signal) {
-  process.kill(process.pid, result.signal);
+const binary = binaryPath();
+const args = process.argv.slice(2);
+
+if (process.platform === "win32") {
+  supervise(binary, args);
+} else {
+  if (typeof process.execve !== "function") {
+    fail(
+      `Node.js ${process.version} cannot run onepipeline from npm on ${process.platform}: ` +
+        "the command has to become the onepipeline binary's own process, which needs " +
+        `process.execve (Node.js ${require("../package.json").engines.node}). Upgrade Node.js, or ` +
+        `${OTHER_INSTALLS.charAt(0).toLowerCase()}${OTHER_INSTALLS.slice(1)}`,
+    );
+  }
+  // Node ignores SIGXFSZ, and an ignored signal survives exec while a handled
+  // one returns to its default: handle it so the engine, and every program it
+  // starts, begins with the disposition a shell would give it. (Node ignores
+  // SIGPIPE too, but the engine's runtime ignores that itself and restores it
+  // for what it starts.)
+  process.on("SIGXFSZ", () => {});
+  // On Node.js 22 an execve that fails aborts this process rather than
+  // throwing, so the binary is checked first: a missing or non-executable one
+  // is refused here with the same message a throwing execve would get.
+  try {
+    if (!fs.statSync(binary).isFile()) throw new Error(`${binary} is not a file`);
+    fs.accessSync(binary, fs.constants.X_OK);
+    process.execve(binary, [binary, ...args], process.env);
+  } catch (error) {
+    fail(`failed to launch the onepipeline binary: ${error.message}`);
+  }
 }
-process.exit(result.status === null ? 1 : result.status);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "onepipeline-cli",
-  "version": "0.95.3",
+  "version": "0.95.4",
   "description": "Execute a task DAG over oneagentgraph and onevcs, merging their event streams into one.",
   "keywords": [
     "orchestration",
@@ -24,12 +24,12 @@
     "bin/onepipeline.js"
   ],
   "engines": {
-    "node": ">=18"
+    "node": "^22.15.0 || >=23.11.0"
   },
   "optionalDependencies": {
-    "onepipeline-cli-linux-x64": "0.95.3",
-    "onepipeline-cli-linux-arm64": "0.95.3",
-    "onepipeline-cli-darwin-arm64": "0.95.3",
-    "onepipeline-cli-win32-x64": "0.95.3"
+    "onepipeline-cli-linux-x64": "0.95.4",
+    "onepipeline-cli-linux-arm64": "0.95.4",
+    "onepipeline-cli-darwin-arm64": "0.95.4",
+    "onepipeline-cli-win32-x64": "0.95.4"
   }
 }