@executablemd/runtime 0.11.0 → 0.12.0

package/esm/launcher.js

@@ -27,7 +27,8 @@
  * document help and inspection free of any of this.
  */
 import { createApi } from "@effectionx/context-api";
-import { ensure, race, resource, scoped, until, withResolvers } from "effection";
+import { ensure, race, resource, scoped, until } from "effection";
+import { once } from "@effectionx/node/events";
 import { spawn as spawnChild } from "node:child_process";
 import process from "node:process";
 export const NATIVE_LAUNCHER_UNAVAILABLE = "no native launcher is installed — this host does not hand a native agent UI " +
@@ -141,8 +142,6 @@ function runForeground(request) {
         if (command === undefined) {
             throw new Error("native launch: command must not be empty");
         }
-        const settled = withResolvers();
-        const failed = withResolvers();
         let child;
         // Interrupt, then insist. A cancelled document may not continue — or
         // finish tearing down — while a child still holds the terminal, so this
@@ -153,28 +152,42 @@ function runForeground(request) {
         // `inherit` is the whole point: the child reads this terminal and draws on
         // it directly, so nothing between it and the person using it can buffer,
         // reorder, capture or journal what passes.
-        child = spawnChild(command, args, {
+        const started = spawnChild(command, args, {
             cwd: request.cwd,
             env: request.env,
             stdio: "inherit",
         });
-        child.once("error", (error) => failed.reject(error));
-        child.once("exit", (code, signal) => {
-            const outcome = {};
-            if (code !== null) {
-                outcome.exitCode = code;
-            }
-            if (signal !== null) {
-                outcome.signal = signal;
-            }
-            settled.resolve(outcome);
-        });
-        return yield* race([settled.operation, failed.operation]);
+        child = started;
+        // Raced inline, in the same synchronous run as the spawn, so both arms are
+        // attached before the child can report anything — a spawned race attaches
+        // a turn later. Whichever loses is halted, which is what detaches it.
+        return yield* race([
+            (function* () {
+                const [code, signal] = yield* once(started, "exit");
+                const outcome = {};
+                if (code !== null) {
+                    outcome.exitCode = code;
+                }
+                if (signal !== null) {
+                    outcome.signal = signal;
+                }
+                return outcome;
+            })(),
+            (function* () {
+                const [error] = yield* once(started, "error");
+                throw error;
+            })(),
+        ]);
     });
 }
 /**
  * End one foreground child and wait for it to be gone.
  *
+ * Exported for `packages/runtime/tests/native-launcher.test.ts` and not from
+ * `mod.ts`: the listener this installs belongs to a bounded Promise, and the
+ * only way to observe that it is released on every settlement path is to hold
+ * the child.
+ *
  * Deliberately one promise rather than an Effection race: this runs while the
  * scope is already being dismantled, and the cheapest correct thing to do
  * there is to wait on the process's own events instead of starting more
@@ -184,7 +197,7 @@ function runForeground(request) {
  * is spent — a native UI holding the terminal is not something a cancelled run
  * can afford to wait on indefinitely.
  */
-function reap(child) {
+export function reap(child) {
     const pid = child.pid;
     if (pid === undefined || child.exitCode !== null || child.signalCode !== null) {
         return Promise.resolve();
@@ -206,6 +219,10 @@ function reap(child) {
             clearInterval(poll);
             clearTimeout(escalation);
             clearTimeout(deadline);
+            // The one funnel every settlement goes through — the exit event, the
+            // reachability poll, the escalation deadline, and the refusal that
+            // rejects — so the handler comes off however this ends.
+            child.off("exit", onExit);
             // Deno's `node:child_process` stops reporting a child's exit once a
             // signal that child ignored has been delivered, and holds the runtime
             // open on the handle it will now never settle. Dropping the reference is
@@ -223,7 +240,8 @@ function reap(child) {
             }
             resolve();
         };
-        child.once("exit", () => done());
+        const onExit = () => done();
+        child.on("exit", onExit);
         // Reachability rather than the exit event, because that is the fact this
         // has to establish and the event is not dependable across runtimes here.
         const poll = setInterval(() => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@executablemd/runtime",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Runtime host APIs for executable.md documents.",
   "homepage": "https://executable.md",
   "repository": {
@@ -38,9 +38,9 @@
     "@effectionx/context-api": "0.6.0",
     "@effectionx/fetch": "0.2.1",
     "@effectionx/fs": "0.3.0",
+    "@effectionx/node": "0.2.5",
     "@effectionx/process": "0.8.1",
-    "effection": "4.1.0",
-    "@effectionx/node": "0.2.4"
+    "effection": "4.1.0"
   },
   "_generatedBy": "dnt@dev"
 }

package/types/launcher.d.ts

@@ -28,6 +28,7 @@
  */
 import { type Api } from "@effectionx/context-api";
 import type { Operation } from "effection";
+import type { ChildProcess } from "node:child_process";
 /**
  * What a provider asks the host to run.
  *
@@ -86,6 +87,24 @@ interface ForegroundLauncherOptions {
  * own its exit status, or continue after the UI closes.
  */
 export declare function installForegroundLauncher(options?: ForegroundLauncherOptions): Operation<void>;
+/**
+ * End one foreground child and wait for it to be gone.
+ *
+ * Exported for `packages/runtime/tests/native-launcher.test.ts` and not from
+ * `mod.ts`: the listener this installs belongs to a bounded Promise, and the
+ * only way to observe that it is released on every settlement path is to hold
+ * the child.
+ *
+ * Deliberately one promise rather than an Effection race: this runs while the
+ * scope is already being dismantled, and the cheapest correct thing to do
+ * there is to wait on the process's own events instead of starting more
+ * structured work beside them.
+ *
+ * A child that ignores the interrupt is killed outright once the grace period
+ * is spent — a native UI holding the terminal is not something a cancelled run
+ * can afford to wait on indefinitely.
+ */
+export declare function reap(child: ChildProcess): Promise<void>;
 /**
  * A launcher a host installs when it has no terminal to give away, and no
  * intention of starting a native UI.