@testmuai/rook 0.1.0

package/bin/rook.cjs

@@ -0,0 +1,288 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * Entry point. Resolves a bundled Node runtime (@testmuai/rook-node-*,
+ * Task 3) when one is installed alongside this package — public npm/brew
+ * installs carry it via optionalDependencies, internal installs don't
+ * declare it at all. Falls back to the invoking process's own Node
+ * otherwise, which is the only path internal @lambdatestincprivate/rook
+ * installs ever take.
+ */
+
+const { spawn } = require("node:child_process");
+const { join } = require("node:path");
+const { existsSync } = require("node:fs");
+const { pathToFileURL } = require("node:url");
+
+// Every platform LISTENS for all three signals — that part does not vary.
+// On Windows this matters even for signals we never forward (see
+// shouldForward below): a signal with zero listeners falls through to
+// Windows' own default console-control handler, which calls ExitProcess()
+// on the trampoline near-instantly. libuv assigns every non-detached
+// spawned child (this one included — confirmed directly against libuv's
+// uv_spawn source) to a Job Object with JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE,
+// so that ExitProcess() closes the job and force-kills the child too — the
+// same abrupt-kill-cuts-off-graceful-shutdown problem this file exists to
+// avoid, just relocated from `child.kill()` to the OS and, since no JS runs
+// first, likely to land faster. A registered listener — even one whose
+// body does nothing — suppresses that default handler and keeps the
+// trampoline (and therefore the job) alive long enough for the child,
+// which received the same native event independently, to actually finish
+// its own shutdown and hit this file's normal 'exit' handling.
+const OBSERVED_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
+
+// What differs on win32 is whether the listener's body actually calls
+// child.kill() once invoked:
+//  - SIGINT: Windows' console already broadcasts Ctrl-C (CTRL_C_EVENT) to
+//    every process sharing the console, parent and child alike, so the
+//    child already gets its own native chance to shut down. Windows'
+//    child.kill() is always an unconditional TerminateProcess (confirmed
+//    against Node's child_process docs) — never something the child could
+//    catch — so actually calling it here would only force a redundant hard
+//    kill over whatever graceful handling the child was already doing on
+//    its own. Listen (see OBSERVED_SIGNALS above), but don't forward.
+//  - SIGHUP: not in libuv's supported set on win32 at all — child.kill()
+//    would throw synchronously (UV_EINVAL/UV_ENOSYS) instead of failing
+//    softly. Node only emits SIGHUP on Windows when the console window
+//    closes, and unconditionally tears the whole process tree down ~10s
+//    later regardless of any handler, so there's nothing to gain by
+//    forwarding it even if it didn't throw. Listen, don't forward.
+//  - SIGTERM: Node's own docs are explicit that "'SIGTERM' is not
+//    supported on Windows, it can be listened on" — there is no native OS
+//    mechanism that delivers a real, externally-triggered SIGTERM to a
+//    Windows process's JS layer at all (docker stop / taskkill / a
+//    supervisor targeting just this PID all fall back to TerminateProcess,
+//    which bypasses every JS handler, this one included). The one case
+//    where this listener can still genuinely fire is a cooperating
+//    Node.js parent that spawned this trampoline as its own tracked child
+//    and later calls that child handle's own `.kill('SIGTERM')` — for
+//    that narrow case, forwarding is still the only way the bundled child
+//    would ever learn of it, and a hard kill still beats leaving it
+//    orphaned. Forward it; it's harmless when it doesn't fire and correct
+//    when it does.
+const WINDOWS_PASSIVE_SIGNALS = new Set(["SIGINT", "SIGHUP"]);
+
+function shouldForward(signal, platform) {
+  return !(platform === "win32" && WINDOWS_PASSIVE_SIGNALS.has(signal));
+}
+
+function platformTag() {
+  const plat = process.platform;
+  const arch = process.arch;
+  if (plat === "darwin" && (arch === "arm64" || arch === "x64"))
+    return arch === "arm64" ? "darwin-arm64" : "darwin-x64";
+  if (plat === "linux" && (arch === "arm64" || arch === "x64"))
+    return arch === "arm64" ? "linux-arm64" : "linux-x64";
+  if (plat === "win32" && arch === "x64") return "win-x64";
+  return null;
+}
+
+function findBundledNode() {
+  if (process.env.ROOK_SYSTEM_NODE === "1") return null;
+  const tag = platformTag();
+  if (!tag) return null;
+  const binName = tag === "win-x64" ? "node.exe" : "node";
+  try {
+    const nodePath = require.resolve(
+      `@testmuai/rook-node-${tag}/bin/${binName}`,
+    );
+    // require.resolve() caches a successful resolution and keeps returning
+    // it even after the file is deleted (verified directly against Node's
+    // module resolver) — existsSync() here is the actual guard against a
+    // stale path, not a redundant check.
+    return existsSync(nodePath) ? nodePath : null;
+  } catch {
+    return null;
+  }
+}
+
+function main() {
+  const entry = join(__dirname, "..", "dist", "cli.js");
+  const bundledNode = findBundledNode();
+
+  if (bundledNode) {
+    runViaBundledNode(bundledNode, entry);
+    return;
+  }
+
+  runViaSystemNode(entry);
+}
+
+// spawnSync (the original implementation) blocks the whole event loop for
+// as long as the child runs. Node's signal handling is event-loop-driven
+// (libuv delivers the OS signal via a self-pipe that a process.on(signal)
+// listener only sees once the loop is free to process it) — so no JS
+// signal handler could ever run while blocked inside spawnSync, and a
+// SIGTERM sent to just this process's PID (docker stop, systemd
+// KillMode=process, timeout(1), a supervisor targeting the advertised PID
+// rather than the whole process group) killed the trampoline via default
+// disposition while the bundled-node child kept running, orphaned, with
+// inherited stdio. Reproduced directly: sending SIGTERM to the trampoline's
+// own PID left the child alive and running afterward. Async spawn() keeps
+// the event loop alive so a listener can actually fire and forward the
+// same signal down to the child before this process itself goes away.
+function runViaBundledNode(bundledNode, entry) {
+  const child = spawn(bundledNode, [entry, ...process.argv.slice(2)], {
+    stdio: "inherit",
+  });
+  wireSignalForwarding(child, {
+    bundledNode,
+    entry,
+    platform: process.platform,
+    proc: process,
+    onSpawnFailure: runViaSystemNode,
+  });
+}
+
+// Split out from runViaBundledNode so tests can exercise this control flow
+// against a fake child/process double — main() and runViaBundledNode()
+// call process.exit()/process.kill() on real failure paths, which would
+// take down the test runner itself if driven in-process (see the real
+// subprocess tests further down, and rook.test.mjs's own note on why they
+// spawn a genuine OS process instead of calling main() directly). `proc`
+// and `onSpawnFailure` default to the real globals in production and are
+// swapped for doubles in tests.
+function wireSignalForwarding(
+  child,
+  { bundledNode, entry, platform, proc, onSpawnFailure },
+) {
+  // Only set once child.kill() has genuinely been attempted for a signal
+  // that shouldForward() approved — the platform-passive no-op signals
+  // (SIGINT/SIGHUP on win32) never touch this. Together with `spawned`
+  // below, it lets the 'error' handler tell a real kill failure (child
+  // exists, may still be alive) apart from a genuine spawn failure (child
+  // never existed) — see that handler for why conflating them is unsafe.
+  let signaled = false;
+  // A kill that failed once and left the child unresponsive would
+  // otherwise swallow every later signal forever (report-and-wait, with
+  // no guaranteed 'exit' ever coming). Bound that: once a kill attempt has
+  // failed, the next forwarded signal gives up on the graceful path
+  // entirely and force-exits the trampoline itself, mirroring the
+  // press-Ctrl-C-twice-to-force-quit convention most CLIs already use.
+  let killFailed = false;
+  // 'spawn' (Node 15+) fires only once the OS process genuinely exists —
+  // unlike 'error', which fires for a spawn failure too. Gating the
+  // 'error' handler's "this was probably a failed kill" branch on this
+  // closes a real race: an async spawn failure (the exec pipe reporting a
+  // truncated/corrupted bundled binary, for instance) can be detected in
+  // the same event-loop turn a signal happens to arrive in, which would
+  // otherwise set `signaled` first and make a genuine spawn failure look
+  // like a failed kill — and since no process ever existed, the 'exit'
+  // that branch waits for would then never come, hanging the trampoline
+  // forever instead of falling back.
+  let spawned = false;
+  child.on("spawn", () => {
+    spawned = true;
+  });
+
+  const forward = (signal) => {
+    if (!shouldForward(signal, platform)) return;
+    if (killFailed) {
+      proc.exit(1);
+    }
+    signaled = true;
+    try {
+      child.kill(signal);
+    } catch (err) {
+      // A signal libuv doesn't support on this platform (e.g. SIGHUP on
+      // win32, on Node versions where that still throws instead of
+      // failing softly) throws synchronously. The child is still alive;
+      // report rather than crash the trampoline uncaught.
+      killFailed = true;
+      proc.stderr.write(
+        `Failed to deliver ${signal} to the bundled Node runtime (${bundledNode}): ${err.message}\n`,
+      );
+    }
+  };
+  for (const signal of OBSERVED_SIGNALS) proc.on(signal, forward);
+
+  let settled = false;
+  const stopForwarding = () => {
+    for (const signal of OBSERVED_SIGNALS) proc.removeListener(signal, forward);
+  };
+
+  // Node's docs warn 'exit' may or may not also fire after 'error' —
+  // settled guards against handling either failure/completion path twice.
+  child.on("error", (err) => {
+    if (settled) return;
+    if (signaled && spawned) {
+      // The child definitely exists (confirmed via 'spawn'), so this
+      // 'error' can only be a failed child.kill(), not a spawn failure —
+      // the child may still be alive, and its real 'exit' event is still
+      // to come. Report and return without marking settled, so that
+      // eventual 'exit' still drives normal cleanup (re-raising the
+      // signal / exiting with the child's code) instead of a second CLI
+      // instance getting launched alongside a first one that never
+      // actually died.
+      killFailed = true;
+      proc.stderr.write(
+        `Failed to deliver a signal to the bundled Node runtime (${bundledNode}): ${err.message}\n`,
+      );
+      return;
+    }
+    settled = true;
+    stopForwarding();
+    proc.stderr.write(
+      `Failed to run the bundled Node runtime (${bundledNode}): ${err.message}\n`,
+    );
+    // fall through to the system-Node path instead of exiting — an
+    // unusable bundled runtime (lost exec bit, truncated install, dangling
+    // symlink) should not silently kill the CLI with no message
+    onSpawnFailure(entry);
+  });
+
+  child.on("exit", (code, signal) => {
+    if (settled) return;
+    settled = true;
+    stopForwarding();
+    if (signal) {
+      // The child died from a signal (forwarded from above, or one it hit
+      // on its own — an internal crash, OOM-kill), not a normal exit —
+      // code is null in this case. Re-raise the same signal against
+      // ourselves rather than collapsing to exit code 1: default
+      // disposition then terminates this process the same way, so a
+      // caller inspecting our exit status (or a shell's $?/WIFSIGNALED)
+      // sees the real cause instead of an indistinguishable generic
+      // failure. process.kill() isn't a guaranteed terminator by itself —
+      // nothing stops a future change from registering a handler for this
+      // same signal elsewhere in the process — so the explicit return
+      // makes this function's own control flow correct regardless,
+      // instead of relying on the process dying before the next line runs.
+      proc.kill(proc.pid, signal);
+      return;
+    }
+    proc.exit(code === null ? 1 : code);
+  });
+}
+
+function runViaSystemNode(entry) {
+  const major = Number(process.versions.node.split(".")[0]);
+  if (major < 20) {
+    process.stderr.write(
+      `rook requires Node 20 or newer (found ${process.versions.node}).\n`,
+    );
+    process.exit(1);
+  }
+
+  import(pathToFileURL(entry).href).catch((err) => {
+    process.stderr.write(
+      `Failed to start rook: ${err && err.stack ? err.stack : err}\n`,
+    );
+    process.exit(1);
+  });
+}
+
+// Guards main()'s process.exit()/dynamic-import side effects so this file
+// can be import()'d from rook.test.mjs (or anything else) without actually
+// launching the CLI — only a direct invocation (the npm bin symlink, or
+// `node bin/rook.cjs`) has require.main === module.
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  platformTag,
+  findBundledNode,
+  shouldForward,
+  wireSignalForwarding,
+};