@reventlessdev/reventless-gwt 1.0.0-alpha.74

package/src/PlatformRunner.res

@@ -0,0 +1,160 @@
+// Local platform runner (features plan Phase 9). Spawns an app's reventless-local
+// platform as a managed child with the LocalBus NDJSON event tap enabled, on
+// per-session free ports, classifies its stdout into structured lifecycle/event
+// callbacks, and tears the child down on cancellation. The CLI (`reventless-gwt
+// platform`) wires the callbacks to FormatterVsCode; tests drive `classifyLine`
+// directly.
+//
+// Channels (Spike A/B): commands in / state out go to the platform's GraphQL
+// server (the runner just reports its endpoint); the live event stream comes from
+// the tap on stdout — one sentinel-prefixed JSON line per published event.
+
+let tapSentinel = "@@RVLESS_EVT@@ "
+
+type lineClass =
+  | Domain(JSON.t) // a tap line; the parsed `{event:"domainEvent",…}` payload
+  | Ready // the Domain GraphQL server's "listening on …" line
+  | Log(string) // any other stdout/stderr line (the platform's human logs)
+
+// Pure line classifier — the unit-tested core. ANSI escapes around bracketed
+// component tags survive substring checks, so readiness is detected structurally.
+// The human-log payload is passed through **with its ANSI intact**: the extension
+// renders it in a VS Code Pseudoterminal (xterm), which interprets colour/bold so
+// the runner log reads exactly as on the command line. (Plain non-terminal sinks
+// that want stripped text — CloudWatch etc. — are the framework's concern; see
+// docs/plans/logging-output-optimization.md.)
+let classifyLine = (line: string): lineClass =>
+  if line->String.startsWith(tapSentinel) {
+    let jsonStr = line->String.slice(~start=tapSentinel->String.length, ~end=line->String.length)
+    switch JSON.parseOrThrow(jsonStr) {
+    | exception _ => Log(line)
+    | json => Domain(json)
+    }
+  } else if line->String.includes("GraphQL:Domain") && line->String.includes("listening on") {
+    Ready
+  } else {
+    Log(line)
+  }
+
+type callbacks = {
+  onStart: (~package: string, ~dir: string, ~domainPort: int, ~platformPort: int) => unit,
+  onReady: (~domainEndpoint: string) => unit,
+  onDomainEvent: JSON.t => unit,
+  onLog: string => unit,
+  onStop: option<int> => unit,
+}
+
+// ── Free-port allocation ────────────────────────────────────────────────────
+// One platform child per app folder; default ports (4000/4001/3001/3002) collide
+// with a developer's own `dev:full`, so the runner binds ephemeral ports and
+// passes them to the child via the env overrides added in Phase 1.
+type netServer
+@module("node:net") external _createServer: unit => netServer = "createServer"
+@send external _listen: (netServer, int, string, unit => unit) => unit = "listen"
+@send external _address: netServer => {"port": int} = "address"
+@send external _close: (netServer, unit => unit) => unit = "close"
+
+let openEphemeral = (): promise<(netServer, int)> =>
+  Promise.make((resolve, _reject) => {
+    let s = _createServer()
+    s->_listen(0, "127.0.0.1", () => resolve((s, (s->_address)["port"])))
+  })
+
+// Hold all n open while collecting ports so they're guaranteed distinct, then
+// release them just before the child binds.
+let allocFreePorts = async (n: int): array<int> => {
+  let servers = []
+  let ports = []
+  for _i in 1 to n {
+    let (s, p) = await openEphemeral()
+    servers->Array.push(s)
+    ports->Array.push(p)
+  }
+  servers->Array.forEach(s => s->_close(() => ()))
+  ports
+}
+
+// The platform child's default ports (Platform.startServers): domain / platform /
+// domain-MCP / platform-MCP. `~fixedPorts` pins to these instead of allocating
+// ephemeral ones — the VS Code extension uses it when launching the host-shell UI,
+// whose Vite proxy hardcodes localhost:4000/4001. The caller is responsible for
+// ensuring they're free (it pre-checks and toasts on conflict).
+let fixedPlatformPorts = [4000, 4001, 3001, 3002]
+
+// Discover the platform package under `roots`, spawn it with the tap + per-session
+// ports + in-memory backend, stream its events through `callbacks`, and stay alive
+// until cancelled (the child is killed via its process group on SIGTERM/SIGINT).
+let run = async (
+  ~roots: array<string>,
+  ~backend: string,
+  ~fixedPorts: bool=false,
+  ~callbacks: callbacks,
+): int => {
+  let pkgs = await PlatformScan.scan(roots)
+  switch pkgs->Array.get(0) {
+  | None =>
+    callbacks.onLog(
+      "no reventless-local platform package (src/Main.res.mjs + @reventlessdev/reventless-local) found under: " ++
+      roots->Array.join(", "),
+    )
+    1
+  | Some(pkg) =>
+    let ports = fixedPorts ? fixedPlatformPorts : await allocFreePorts(4)
+    let dPort = ports->Array.getUnsafe(0)
+    let pPort = ports->Array.getUnsafe(1)
+    let dMcp = ports->Array.getUnsafe(2)
+    let pMcp = ports->Array.getUnsafe(3)
+    let env = Dict.fromArray([
+      ("REVENTLESS_EVENT_TAP", "ndjson"),
+      ("REVENTLESS_LOCAL_BACKEND", backend),
+      ("REVENTLESS_DOMAIN_PORT", Int.toString(dPort)),
+      ("REVENTLESS_PLATFORM_PORT", Int.toString(pPort)),
+      ("REVENTLESS_DOMAIN_MCP_PORT", Int.toString(dMcp)),
+      ("REVENTLESS_PLATFORM_MCP_PORT", Int.toString(pMcp)),
+      ("NODE_OPTIONS", "--disable-warning=ExperimentalWarning"),
+      // The gwt bin defaults LOG_LEVEL=silent so its OWN stdout stays pure NDJSON;
+      // the platform child is a separate process whose stdout we parse, so it needs
+      // real logs — the "listening on" line drives readiness and the rest becomes
+      // platformLog. Override the inherited silent.
+      ("LOG_LEVEL", "info"),
+      // The child's stdout is a pipe (we line-parse it), so the framework's sink
+      // detection would auto-pick JSON (non-TTY). But every consumer of `onLog`
+      // renders ANSI — the CLI forwards to the developer's terminal, the extension
+      // to an xterm Pseudoterminal — so force human text mode for bold/colour.
+      // (Tap event lines stay JSON regardless: they're sentinel-prefixed.)
+      ("REVENTLESS_LOG_FORMAT", "text"),
+    ])
+
+    callbacks.onStart(~package=pkg.name, ~dir=pkg.dir, ~domainPort=dPort, ~platformPort=pPort)
+
+    // Run the compiled entrypoint directly with `node`. `src/Main.res.mjs` is plain
+    // ESM, so it needs no tsx/loader, and spawning a single process (vs `pnpm run
+    // serve` → `pnpm run serve` → `npx tsx`) keeps the child's stdout piped straight
+    // to us — nested pnpm buffers a long-running grandchild's output, so the event
+    // tap never streams through it. cwd = the package dir so `PackageVersion.fromCwd`
+    // and relative paths resolve. We set the backend + tap + ports via env directly,
+    // so the package's own serve script (which would otherwise pick them) is bypassed.
+    let proc = ChildProcess.spawn("node", ["src/Main.res.mjs"], ~cwd=pkg.dir, ~env)
+    Cancellation.onCancel(() => ChildProcess.killTree(proc, "SIGTERM"))
+
+    let readyEmitted = ref(false)
+    let handle = line =>
+      switch classifyLine(line) {
+      | Domain(json) => callbacks.onDomainEvent(json)
+      | Ready =>
+        if !readyEmitted.contents {
+          readyEmitted := true
+          callbacks.onReady(~domainEndpoint="http://localhost:" ++ Int.toString(dPort) ++ "/graphql")
+        }
+      | Log(l) => callbacks.onLog(l)
+      }
+    ChildProcess.onStdoutLine(proc, handle)
+    ChildProcess.onStderrLine(proc, handle)
+    ChildProcess.onClose(proc, code => callbacks.onStop(code))
+
+    // Keep the process alive until cancelled — like runWatch, returning here would
+    // let the bin wrapper process.exit and tear down the child immediately.
+    await Promise.make((resolve, _reject) => Cancellation.onCancel(() => resolve()))
+    0
+  }
+}

package/src/PlatformRunner.res.mjs

@@ -0,0 +1,155 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Nodenet from "node:net";
+import * as Cancellation$ReventlessGwt from "./Cancellation.res.mjs";
+import * as ChildProcess$ReventlessGwt from "./ChildProcess.res.mjs";
+import * as PlatformScan$ReventlessGwt from "./PlatformScan.res.mjs";
+
+let tapSentinel = "@@RVLESS_EVT@@ ";
+
+function classifyLine(line) {
+  if (!line.startsWith(tapSentinel)) {
+    if (line.includes("GraphQL:Domain") && line.includes("listening on")) {
+      return "Ready";
+    } else {
+      return {
+        TAG: "Log",
+        _0: line
+      };
+    }
+  }
+  let jsonStr = line.slice(tapSentinel.length, line.length);
+  let json;
+  try {
+    json = JSON.parse(jsonStr);
+  } catch (exn) {
+    return {
+      TAG: "Log",
+      _0: line
+    };
+  }
+  return {
+    TAG: "Domain",
+    _0: json
+  };
+}
+
+function openEphemeral() {
+  return new Promise((resolve, _reject) => {
+    let s = Nodenet.createServer();
+    s.listen(0, "127.0.0.1", () => resolve([
+      s,
+      s.address().port
+    ]));
+  });
+}
+
+async function allocFreePorts(n) {
+  let servers = [];
+  let ports = [];
+  for (let _i = 1; _i <= n; ++_i) {
+    let match = await openEphemeral();
+    servers.push(match[0]);
+    ports.push(match[1]);
+  }
+  servers.forEach(s => {
+    s.close(() => {});
+  });
+  return ports;
+}
+
+let fixedPlatformPorts = [
+  4000,
+  4001,
+  3001,
+  3002
+];
+
+async function run(roots, backend, fixedPortsOpt, callbacks) {
+  let fixedPorts = fixedPortsOpt !== undefined ? fixedPortsOpt : false;
+  let pkgs = await PlatformScan$ReventlessGwt.scan(roots);
+  let pkg = pkgs[0];
+  if (pkg !== undefined) {
+    let ports = fixedPorts ? fixedPlatformPorts : await allocFreePorts(4);
+    let dPort = ports[0];
+    let pPort = ports[1];
+    let dMcp = ports[2];
+    let pMcp = ports[3];
+    let env = Object.fromEntries([
+      [
+        "REVENTLESS_EVENT_TAP",
+        "ndjson"
+      ],
+      [
+        "REVENTLESS_LOCAL_BACKEND",
+        backend
+      ],
+      [
+        "REVENTLESS_DOMAIN_PORT",
+        dPort.toString()
+      ],
+      [
+        "REVENTLESS_PLATFORM_PORT",
+        pPort.toString()
+      ],
+      [
+        "REVENTLESS_DOMAIN_MCP_PORT",
+        dMcp.toString()
+      ],
+      [
+        "REVENTLESS_PLATFORM_MCP_PORT",
+        pMcp.toString()
+      ],
+      [
+        "NODE_OPTIONS",
+        "--disable-warning=ExperimentalWarning"
+      ],
+      [
+        "LOG_LEVEL",
+        "info"
+      ],
+      [
+        "REVENTLESS_LOG_FORMAT",
+        "text"
+      ]
+    ]);
+    callbacks.onStart(pkg.name, pkg.dir, dPort, pPort);
+    let proc = ChildProcess$ReventlessGwt.spawn("node", ["src/Main.res.mjs"], pkg.dir, env);
+    Cancellation$ReventlessGwt.onCancel(() => ChildProcess$ReventlessGwt.killTree(proc, "SIGTERM"));
+    let readyEmitted = {
+      contents: false
+    };
+    let handle = line => {
+      let json = classifyLine(line);
+      if (typeof json !== "object") {
+        if (!readyEmitted.contents) {
+          readyEmitted.contents = true;
+          return callbacks.onReady("http://localhost:" + dPort.toString() + "/graphql");
+        } else {
+          return;
+        }
+      } else if (json.TAG === "Domain") {
+        return callbacks.onDomainEvent(json._0);
+      } else {
+        return callbacks.onLog(json._0);
+      }
+    };
+    ChildProcess$ReventlessGwt.onStdoutLine(proc, handle);
+    ChildProcess$ReventlessGwt.onStderrLine(proc, handle);
+    ChildProcess$ReventlessGwt.onClose(proc, code => callbacks.onStop(code));
+    await new Promise((resolve, _reject) => Cancellation$ReventlessGwt.onCancel(() => resolve()));
+    return 0;
+  }
+  callbacks.onLog("no reventless-local platform package (src/Main.res.mjs + @reventlessdev/reventless-local) found under: " + roots.join(", "));
+  return 1;
+}
+
+export {
+  tapSentinel,
+  classifyLine,
+  openEphemeral,
+  allocFreePorts,
+  fixedPlatformPorts,
+  run,
+}
+/* node:net Not a pure module */

package/src/PlatformScan.res

@@ -0,0 +1,138 @@
+// Discovers the local-platform package(s) the runner can launch (features plan
+// Phase 9). A platform package is one that (a) depends on
+// `@reventlessdev/reventless-local` and (b) carries a compiled run entrypoint at
+// `src/Main.res.mjs` (what `tsx`/`node` execute). This mirrors PackageScan's
+// role for the watch session, but keys off the run entrypoint rather than test
+// files. The matching predicate is pure so it can be unit-tested without a real
+// workspace tree.
+
+type platformPkg = {
+  // Package name from package.json (may be "" if absent).
+  name: string,
+  // Absolute package directory (the one containing package.json + src/).
+  dir: string,
+  // Absolute path to the compiled run entrypoint (src/Main.res.mjs).
+  mainPath: string,
+  // The npm-script name to launch, preferring an in-memory variant: "serve:memory"
+  // if declared, else "serve". None ⇒ no serve script (runner falls back to running
+  // src/Main.res.mjs via tsx directly).
+  serveScript: option<string>,
+}
+
+type dirent = {
+  name: string,
+  @as("isDirectory") _isDirectory: unit => bool,
+}
+type readdirOpts = {withFileTypes: bool}
+@module("node:fs/promises")
+external _readdir: (string, readdirOpts) => promise<array<dirent>> = "readdir"
+@module("node:fs") external _existsSync: string => bool = "existsSync"
+@module("node:fs") external _readFileSync: (string, string) => string = "readFileSync"
+@module("node:path") external join: (string, string) => string = "join"
+
+let localPlatformDep = "@reventlessdev/reventless-local"
+let ignoreNames = ["node_modules", ".git", "dist", "lib", ".history"]
+
+// Pure predicate: given a package.json's text and whether src/Main.res.mjs exists,
+// decide whether this is a launchable platform package and surface its name +
+// serve script. Depends on reventless-local appearing in any dependency block.
+let matchPlatform = (
+  ~pkgJsonText: string,
+  ~mainExists: bool,
+): option<(string, option<string>)> => {
+  if !mainExists {
+    None
+  } else {
+    switch JSON.parseOrThrow(pkgJsonText) {
+    | exception _ => None
+    | json =>
+      switch json->JSON.Decode.object {
+      | None => None
+      | Some(obj) =>
+        let name = switch obj->Dict.get("name") {
+        | Some(String(n)) => n
+        | _ => ""
+        }
+        let depsHave = key =>
+          switch obj->Dict.get(key)->Option.flatMap(JSON.Decode.object) {
+          | Some(deps) => deps->Dict.get(localPlatformDep)->Option.isSome
+          | None => false
+          }
+        let dependsOnLocal =
+          depsHave("dependencies") ||
+          depsHave("devDependencies") ||
+          depsHave("optionalDependencies")
+        if dependsOnLocal {
+          let serveScript =
+            switch obj->Dict.get("scripts")->Option.flatMap(JSON.Decode.object) {
+            | Some(scripts) =>
+              if scripts->Dict.get("serve:memory")->Option.isSome {
+                Some("serve:memory")
+              } else if scripts->Dict.get("serve")->Option.isSome {
+                Some("serve")
+              } else {
+                None
+              }
+            | None => None
+            }
+          Some((name, serveScript))
+        } else {
+          None
+        }
+      }
+    }
+  }
+}
+
+// Inspect a single directory: is it a platform package?
+let inspectDir = (dir: string): option<platformPkg> => {
+  let pkgJson = join(dir, "package.json")
+  let mainPath = join(join(dir, "src"), "Main.res.mjs")
+  if !_existsSync(pkgJson) {
+    None
+  } else {
+    let text = try _readFileSync(pkgJson, "utf8") catch {
+    | _ => ""
+    }
+    switch matchPlatform(~pkgJsonText=text, ~mainExists=_existsSync(mainPath)) {
+    | Some((name, serveScript)) => Some({name, dir, mainPath, serveScript})
+    | None => None
+    }
+  }
+}
+
+// Walk the roots, returning every platform package found (deduped by dir,
+// declaration order preserved). Prunes node_modules/lib/.git like Discovery.
+let rec walk = async (dir: string, acc: array<platformPkg>): array<platformPkg> => {
+  switch inspectDir(dir) {
+  | Some(pkg) => acc->Array.push(pkg) // a platform package — record, don't descend into its src
+  | None => ()
+  }
+  let entries = try await _readdir(dir, {withFileTypes: true}) catch {
+  | _ => []
+  }
+  for i in 0 to entries->Array.length - 1 {
+    let entry = entries->Array.getUnsafe(i)
+    if entry._isDirectory() && !Array.includes(ignoreNames, entry.name) {
+      let _ = await walk(join(dir, entry.name), acc)
+    }
+  }
+  acc
+}
+
+let scan = async (roots: array<string>): array<platformPkg> => {
+  let seen = Dict.make()
+  let out = []
+  for i in 0 to roots->Array.length - 1 {
+    let found = await walk(roots->Array.getUnsafe(i), [])
+    found->Array.forEach(pkg =>
+      switch seen->Dict.get(pkg.dir) {
+      | Some(_) => ()
+      | None =>
+        seen->Dict.set(pkg.dir, true)
+        out->Array.push(pkg)
+      }
+    )
+  }
+  out
+}

package/src/PlatformScan.res.mjs

@@ -0,0 +1,131 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Nodefs from "node:fs";
+import * as Nodepath from "node:path";
+import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Promises from "node:fs/promises";
+
+let localPlatformDep = "@reventlessdev/reventless-local";
+
+let ignoreNames = [
+  "node_modules",
+  ".git",
+  "dist",
+  "lib",
+  ".history"
+];
+
+function matchPlatform(pkgJsonText, mainExists) {
+  if (!mainExists) {
+    return;
+  }
+  let json;
+  try {
+    json = JSON.parse(pkgJsonText);
+  } catch (exn) {
+    return;
+  }
+  let obj = Stdlib_JSON.Decode.object(json);
+  if (obj === undefined) {
+    return;
+  }
+  let match = obj["name"];
+  let name = typeof match === "string" ? match : "";
+  let depsHave = key => {
+    let deps = Stdlib_Option.flatMap(obj[key], Stdlib_JSON.Decode.object);
+    if (deps !== undefined) {
+      return Stdlib_Option.isSome(deps[localPlatformDep]);
+    } else {
+      return false;
+    }
+  };
+  let dependsOnLocal = depsHave("dependencies") || depsHave("devDependencies") || depsHave("optionalDependencies");
+  if (!dependsOnLocal) {
+    return;
+  }
+  let scripts = Stdlib_Option.flatMap(obj["scripts"], Stdlib_JSON.Decode.object);
+  let serveScript = scripts !== undefined ? (
+      Stdlib_Option.isSome(scripts["serve:memory"]) ? "serve:memory" : (
+          Stdlib_Option.isSome(scripts["serve"]) ? "serve" : undefined
+        )
+    ) : undefined;
+  return [
+    name,
+    serveScript
+  ];
+}
+
+function inspectDir(dir) {
+  let pkgJson = Nodepath.join(dir, "package.json");
+  let mainPath = Nodepath.join(Nodepath.join(dir, "src"), "Main.res.mjs");
+  if (!Nodefs.existsSync(pkgJson)) {
+    return;
+  }
+  let text;
+  try {
+    text = Nodefs.readFileSync(pkgJson, "utf8");
+  } catch (exn) {
+    text = "";
+  }
+  let match = matchPlatform(text, Nodefs.existsSync(mainPath));
+  if (match !== undefined) {
+    return {
+      name: match[0],
+      dir: dir,
+      mainPath: mainPath,
+      serveScript: match[1]
+    };
+  }
+}
+
+async function walk(dir, acc) {
+  let pkg = inspectDir(dir);
+  if (pkg !== undefined) {
+    acc.push(pkg);
+  }
+  let entries;
+  try {
+    entries = await Promises.readdir(dir, {
+      withFileTypes: true
+    });
+  } catch (exn) {
+    entries = [];
+  }
+  for (let i = 0, i_finish = entries.length; i < i_finish; ++i) {
+    let entry = entries[i];
+    if (entry.isDirectory() && !ignoreNames.includes(entry.name)) {
+      await walk(Nodepath.join(dir, entry.name), acc);
+    }
+  }
+  return acc;
+}
+
+async function scan(roots) {
+  let seen = {};
+  let out = [];
+  for (let i = 0, i_finish = roots.length; i < i_finish; ++i) {
+    let found = await walk(roots[i], []);
+    found.forEach(pkg => {
+      let match = seen[pkg.dir];
+      if (match !== undefined) {
+        return;
+      } else {
+        seen[pkg.dir] = true;
+        out.push(pkg);
+        return;
+      }
+    });
+  }
+  return out;
+}
+
+export {
+  localPlatformDep,
+  ignoreNames,
+  matchPlatform,
+  inspectDir,
+  walk,
+  scan,
+}
+/* node:fs Not a pure module */

package/src/ProcessManager.res

@@ -0,0 +1,91 @@
+// Owns the `rescript build -w` watchers a watch session spawns — one per
+// package that owns tests (PackageScan), at most one per directory,
+// reference-counted by `dir`. Registered with Cancellation so SIGINT/SIGTERM
+// tears down every spawned watcher; never orphans a compiler.
+
+type managed = {
+  dir: string,
+  proc: ChildProcess.t,
+}
+
+let running: Dict.t<managed> = Dict.make()
+
+let isManaging = (dir: string): bool =>
+  switch running->Dict.get(dir) {
+  | Some(_) => true
+  | None => false
+  }
+
+// Spawn `pnpm run start` (the package's `rescript build -w`) in `pkg.dir`,
+// unless one is already managed there. `onStdout` receives each output line so
+// the caller can classify compiler markers (Phase 5).
+let spawnWatcher = (pkg: PackageScan.pkg, ~onStdout: (string, string) => unit): unit =>
+  switch running->Dict.get(pkg.dir) {
+  | Some(_) => ()
+  | None => {
+      let proc = ChildProcess.spawn("pnpm", ["run", "start"], ~cwd=pkg.dir)
+      ChildProcess.onStdoutLine(proc, line => onStdout(pkg.dir, line))
+      running->Dict.set(pkg.dir, {dir: pkg.dir, proc})
+    }
+  }
+
+// Stop just the watcher managed for `dir` (if any), tearing down its process
+// group. Returns true when one was running — i.e. the caller *owned* this
+// package's build (vs. an adopted external watcher, which we can't stop).
+let stop = (dir: string): bool =>
+  switch running->Dict.get(dir) {
+  | Some(m) => {
+      ChildProcess.killTree(m.proc, "SIGTERM")
+      running->Dict.delete(dir)
+      true
+    }
+  | None => false
+  }
+
+// Force a full re-emit of `pkg` after a structural change — a module relocation
+// that incremental compilation can't detect, since it keys invalidation on
+// source + dependency-interface hashes, never on a dependency's filesystem
+// location (see plan Phase 12). Drives a deterministic one-shot `rescript clean`
+// → `rescript build` to completion (the `clean` is what forces every dependent
+// `.res.mjs` to be re-emitted against the new layout; the `build` is essential
+// even on the adopted path — an external watcher won't rebuild after a clean
+// without a fresh source change, so a bare clean would strand the package with
+// no outputs). If we *owned* the package's watcher we stop it first (no lock
+// contention) and respawn it afterward to resume incremental watching; on the
+// adopted path the developer's own watcher keeps running untouched. `onStdout`
+// streams the clean/build output (compiler markers) to the caller; `onDone`
+// fires once the build completes, gating the test re-run.
+let cleanRebuild = (
+  pkg: PackageScan.pkg,
+  ~onStdout: (string, string) => unit,
+  ~onDone: unit => unit,
+): unit => {
+  let wasManaged = stop(pkg.dir)
+  let step = (cmd: string, args: array<string>, next: unit => unit): unit => {
+    let proc = ChildProcess.spawn(cmd, args, ~cwd=pkg.dir)
+    ChildProcess.onStdoutLine(proc, line => onStdout(pkg.dir, line))
+    ChildProcess.onClose(proc, _ => next())
+  }
+  step("pnpm", ["exec", "rescript", "clean"], () =>
+    step("pnpm", ["exec", "rescript", "build"], () => {
+      if wasManaged {
+        spawnWatcher(pkg, ~onStdout)
+      }
+      onDone()
+    })
+  )
+}
+
+// SIGTERM, not SIGINT: a POSIX shell sets background children to ignore SIGINT,
+// so SIGINT can leak a watcher; SIGTERM tears down the whole group reliably
+// (verified across foreground and background process-tree shapes).
+let killAll = (): unit => {
+  running
+  ->Dict.valuesToArray
+  ->Array.forEach(m => ChildProcess.killTree(m.proc, "SIGTERM"))
+  running
+  ->Dict.keysToArray
+  ->Array.forEach(k => running->Dict.delete(k))
+}
+
+let managedCount = (): int => running->Dict.keysToArray->Array.length