clearotron 0.2.2 → 0.2.4

package/shared/listen.mjs

@@ -65,9 +65,11 @@
 // WHAT THIS DELIBERATELY DOES NOT DO: look up who holds the port. Node cannot see another user's
 // process without privilege, and a probe that usually cannot look would print "no other instance" when
 // it means "could not check" — which is the same class of lie this whole issue is about. The EADDRINUSE
-// message already tells the operator `ss -ltnp`, which is the instruction that works.
+// message already tells the operator how to find the holder, in the shell they are actually in.
 
 /** The environment variable a shared box sets once to ban silent defaults for every service on it. */
+import { whatHoldsPort, stopThatProcess } from "./os-advice.mjs";
+
 export const REQUIRE_EXPLICIT_PORTS = "CLEAROTRON_REQUIRE_EXPLICIT_PORTS";
 
 /**
@@ -124,6 +126,40 @@ export function explicitPortRequiredMessage({ what, port, portVar }) {
  *             response-body and bundle assertion in the suite, so naming it is free and correct.
  *  `portFlag` an optional CLI equivalent, for the entry points that take one.
  */
+/**
+ * The first free port at or after `from`, or `null` when nothing in range is free — owner ruling,
+ * 2026-09-09.
+ *
+ * WHAT THIS IS FOR AND WHAT IT IS NOT. A collision on a DEFAULT port is this process discovering it
+ * guessed somebody else's address: nobody stated that number and nothing outside is addressed to it,
+ * so stepping to the next free one loses nothing. A collision on a port the reader SET is an address
+ * conflict they can reason about, and moving it silently would take the product away from where they
+ * pointed it. The caller decides which case it is; this only walks.
+ *
+ * AND IT IS ONLY EVER SAFE WHERE NOTHING FRONTS THESE DOORS. A proxy, an Access team or an OIDC issuer
+ * means something outside this process is addressed to these numbers, and a door that moved would be
+ * up and unreachable — the worst of the three outcomes, because it looks like success. That is the
+ * caller's question too, for the same reason: only it knows which deployment shape it is.
+ *
+ * `isFree` IS INJECTED and may be sync or async. A walker testable only by occupying real ports would
+ * be tested against whichever ports happened to be free on the machine that ran it, which is not a
+ * test of the rule.
+ *
+ * NULL RATHER THAN A GUESS when the range is exhausted. The caller then refuses on the port that was
+ * actually asked for, and the reader is told the truth — that address is taken — instead of being sent
+ * to one this could not prove was free either.
+ */
+export async function nextFreePort(from, isFree, { limit = 64, claimed = new Set() } = {}) {
+  for (let p = from + 1; p <= 65535 && p < from + limit; p += 1) {
+    // CLAIMED PORTS ARE NOT FREE, even though nothing is listening on them yet. The doors are chosen
+    // one after another and bound later, so two of them landing on one number is the same collision
+    // deferred — and the second to bind would be the one that failed.
+    if (claimed.has(p)) continue;
+    if (await isFree(p)) return p;
+  }
+  return null;
+}
+
 export function listenErrorMessage(err, { what, host, port, portVar, portFlag = null, portSource = null,
   portFile = null }) {
   const at = `${host}:${port}`;
@@ -160,8 +196,24 @@ export function listenErrorMessage(err, { what, host, port, portVar, portFlag =
             + `address — and had it been down just now, this process would have taken it silently. `
             + `Set ${portVar ?? "the port variable"} for this instance.\n`
           : "")
-        + `  See what holds it:  ss -ltnp 'sport = :${port}'   (or: lsof -i :${port})\n`
-        + `  Then stop that process${move ? `, or ${move}` : ""}.\n`
+        // ── THE HOLDER IS NOT ALWAYS SOMETHING TO KILL, AND THIS USED TO ASSUME IT WAS ─────────────
+        //
+        // "Then stop that process" is right for a stray second copy and wrong for the other common
+        // holder: an editor's port forward. A reader working over a remote session has the port
+        // forwarded to their laptop by the editor itself, so the thing holding it is the tool they are
+        // reading this message in — and stopping it drops the session that printed the advice.
+        //
+        // So the holder is named as a question rather than a verdict, moving THIS instance comes
+        // first among the remedies, and stopping the holder is offered second and only as the
+        // reader's own call. Nothing here claims to know which it is: that cannot be seen from
+        // inside this process, and the previous wording claimed it by implication.
+        + `  See what holds it:  ${whatHoldsPort(port)}\n`
+        + "  A forwarded port counts: an editor forwarding this port to your machine holds it exactly "
+        + "as a second copy would, and stopping that would end the session you are reading this in.\n"
+        + (move
+          ? `  Move this instance instead — ${move} — or, once you know what the holder is and that you `
+            + `do not need it, ${stopThatProcess()}.\n`
+          : `  Once you know what the holder is and that you do not need it, ${stopThatProcess()}.\n`)
         + whichFile
         + `  Refusing to start — it will NOT quietly move to another port, because whatever is in front `
         + `of it is still addressed to ${at}.`;

package/shared/names-in-force.mjs

@@ -8,7 +8,9 @@
 //
 //   node scripts/mint-names-in-force.mjs
 //
-// driver/test/retired-env-spellings.test.mjs regenerates this and refuses a stale copy.
+// CI refuses a stale copy, from the guards job: scripts/generated-files-are-current.mjs runs every
+// minter in scripts/ with --check. (This line used to name a test file that does not exist in this
+// tree, so the only thing that ever caught this drifting was a private control refusing to start.)
 
 export const NAMES_IN_FORCE = Object.freeze([
   "CLEAROTRON_ACCESS_DOMAIN",
@@ -43,6 +45,7 @@ export const NAMES_IN_FORCE = Object.freeze([
   "CLEAROTRON_DEFAULT_AGENT",
   "CLEAROTRON_DELIVERY",
   "CLEAROTRON_DEMO",
+  "CLEAROTRON_DEMO_PROFILES",
   "CLEAROTRON_DISPATCH_RECORD",
   "CLEAROTRON_DOCTOR_ASSUME_PINNED",
   "CLEAROTRON_DUMP_JSON",
@@ -67,6 +70,7 @@ export const NAMES_IN_FORCE = Object.freeze([
   "CLEAROTRON_GATHER_SESSION_KEY",
   "CLEAROTRON_HARD_MS",
   "CLEAROTRON_HTTP_TIMEOUT_MS",
+  "CLEAROTRON_IDENTIFIER_BLOCKLIST",
   "CLEAROTRON_INSTRUCTIONS_DIR",
   "CLEAROTRON_INVOKED_AS",
   "CLEAROTRON_JX_",
@@ -162,6 +166,7 @@ export const NAMES_IN_FORCE = Object.freeze([
   "CLEAROTRON_SUITE_TELEMETRY_DIR",
   "CLEAROTRON_SYNTHESIS_MODEL",
   "CLEAROTRON_TAINT_CHAIN",
+  "CLEAROTRON_TEST_FIXTURE_PROFILES",
   "CLEAROTRON_TURN_CAP",
   "CLEAROTRON_TURN_LOCK_POLL_MS",
   "CLEAROTRON_UNREACHABLE_SENIOR",

package/shared/node-floor.mjs

@@ -0,0 +1,97 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026 Cordillera Sàrl. Additional terms under section 7 of the AGPL-3.0 apply — see ADDITIONAL-TERMS.md
+//
+// THE MINIMUM NODE VERSION, READ FROM THE ONE PLACE THAT DECLARES IT.
+//
+// `package.json` says `engines: { node: ">=22.13.0" }`. npm reads that field, and so does everything
+// here. Nothing restates the number.
+//
+// WHY THIS FILE EXISTS RATHER THAN A CONSTANT. There was a constant: `NODE_FLOOR = 22` in bin/onboard.mjs,
+// compared as `Number(process.versions.node.split(".")[0]) >= NODE_FLOOR`. A major-only comparison
+// STRUCTURALLY CANNOT SEE A MINOR FLOOR, so 22.9.0 passed a check written for a 22.13.0 floor — the check said
+// `node 22.9.0` and a tick while npm, reading the same requirement from the same repository, printed
+// EBADENGINE for it. One requirement, two spellings, already disagreeing.
+//
+// The cost was a first-run failure nobody could diagnose: an engine door exited 1 on a machine below the
+// floor, and every check the product offers said the runtime was fine.
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { join, dirname } from "node:path";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/** The declared range, verbatim, e.g. `">=22.13.0"`. Throws if the field is gone — an absent floor is a
+ *  packaging fault, not a licence to run on anything. */
+export function declaredRange(root = join(HERE, "..")) {
+  const range = JSON.parse(readFileSync(join(root, "package.json"), "utf8"))?.engines?.node;
+  if (!range) throw new Error("package.json declares no engines.node — the runtime floor has no source");
+  return String(range);
+}
+
+/**
+ * `">=22.13.0"` → [22, 13, 0]. `">=22"` and `">=22.13"` are accepted too, with the absent parts read as
+ * zero, because that is what they mean and not a guess — and because the field is edited by whoever
+ * changes the floor, who should not have to know which spelling this reader was written against. A
+ * coordination failure between two people editing one number is the defect this whole file exists for.
+ *
+ * ONLY the `>=` family. A caret or tilde range, or an `||` union, THROWS rather than being interpreted:
+ * a floor read wrongly is worse than one not read at all, because it would silently pass every version
+ * and take every check built on it with it.
+ */
+export function floorOf(range) {
+  const m = /^>=\s*(\d+)(?:\.(\d+))?(?:\.(\d+))?\s*$/.exec(String(range).trim());
+  if (!m) throw new Error(`engines.node is ${range}, which this reader does not understand — expected ">=x", ">=x.y" or ">=x.y.z"`);
+  return [Number(m[1]), Number(m[2] ?? 0), Number(m[3] ?? 0)];
+}
+
+/**
+ * `"22.16.0"` → [22, 16, 0], ignoring any pre-release or build suffix. NULL when it cannot be read.
+ *
+ * Null rather than zeroes, and the difference is the whole of it: `[0, 0, 0]` compares as below every
+ * floor, so a version string this reader did not understand would REFUSE — and this file would become
+ * the reason an install fails on a Node that is probably fine. A parser gap must not become an outage.
+ * Found in review, 2026-09-08.
+ */
+export const partsOf = (v) => {
+  // THE `v` IS OPTIONAL AND MUST BE, because both spellings are in reach: `process.versions.node` has
+  // no prefix and `process.version` does. Without it a caller handed the prefixed form gets null,
+  // null passes, and an out-of-date runtime is waved through by the guard written to stop it — the
+  // permissive half of the same asymmetry, which is the direction that fails silently.
+  const m = /^v?(\d+)\.(\d+)\.(\d+)/.exec(String(v).trim());
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+};
+
+/** Is `current` at or above `floor`? ALL THREE PARTS, in order — the defect this replaces compared one. */
+export function meetsFloor(current, floor) {
+  const c = partsOf(current);
+  // AN UNREADABLE RUNNING VERSION PASSES, and that asymmetry is deliberate. The DECLARED range is our
+  // own manifest and throws loudly when it cannot be read, because that is a packaging fault we own.
+  // The running version is whatever the runtime reports, and refusing one we failed to parse would
+  // stop a working install over our own gap. Refuse only what we can show is below the floor.
+  if (!c) return true;
+  for (let i = 0; i < 3; i += 1) {
+    if (c[i] > floor[i]) return true;
+    if (c[i] < floor[i]) return false;
+  }
+  return true;
+}
+
+/**
+ * The whole answer, for a caller that wants to refuse.
+ *
+ * `current` and `root` are injected so a check can drive every side of this without a second Node
+ * installation — a floor guard that can only be exercised by running on an old runtime is one nobody
+ * ever sees fail.
+ */
+export function nodeFloorVerdict({ current = process.versions.node, root } = {}) {
+  const range = declaredRange(root);
+  const floor = floorOf(range);
+  return { ok: meetsFloor(current, floor), current, required: floor.join("."), range };
+}
+
+/** What a person is told, in one sentence, naming both versions. No stack, no advice they cannot act on. */
+export function nodeFloorRefusal(v) {
+  return `This needs Node ${v.required} or newer, and this is Node ${v.current}. `
+    + "Upgrade Node and run the command again — nothing else here will work until you do.";
+}

package/shared/os-advice.mjs

@@ -0,0 +1,91 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026 Cordillera Sàrl. Additional terms under section 7 of the AGPL-3.0 apply — see ADDITIONAL-TERMS.md
+//
+// THE COMMANDS WE TELL A READER TO TYPE, IN THE SHELL THEY ARE ACTUALLY IN.
+//
+// Three surfaces print a command for the reader to run: the port-in-use refusal, the client door's
+// version of the same, and the demo's "remove it later" line. All three printed POSIX commands
+// unconditionally — `ss`, `lsof`, `rm -rf` — and the demo is supported on native Windows, where none
+// of them exist. A reader who follows the instruction gets "not recognized as a cmdlet", which reads
+// as a broken product rather than as advice written for somebody else's machine.
+//
+// Reported from the owner's own Windows run, 2026-09-09.
+//
+// ONE PLACE, BECAUSE THREE COPIES OF A RULE DRIFT. The alternative was a ternary at each call site,
+// which is how the first one ends up saying `Remove-Item` while the second still says `rm -rf`.
+//
+// `platform` IS INJECTABLE ON EVERY FUNCTION, and that is the whole testability story: the population
+// this protects is the one that cannot run this suite to find out. An arm on a Linux runner has to be
+// able to ask what a Windows reader would be shown, or the Windows text is asserted by nobody.
+//
+// WHAT THIS DOES NOT DO: it does not detect a shell. A reader in Git Bash on Windows has POSIX
+// commands and will be shown PowerShell ones. That is the right way round — `process.platform` is a
+// fact and the shell is a guess, and being shown a command for the OS you are on is recoverable in a
+// way that being shown one for an OS you are not on is not.
+
+/** Is this the platform whose shell has none of the POSIX tools these messages used to name? */
+const isWindows = (platform) => platform === "win32";
+
+/**
+ * How to see which process holds a TCP port.
+ *
+ * The POSIX form keeps both spellings it always had: `ss` is on every modern Linux and `lsof` is the
+ * one a macOS reader has. The Windows form names the cmdlet AND how to turn its answer into a process,
+ * because `Get-NetTCPConnection` reports an owning PID and stops there — a reader given only that has
+ * been handed a number and no way to act on it.
+ */
+export function whatHoldsPort(port, { platform = process.platform } = {}) {
+  return isWindows(platform)
+    ? `Get-NetTCPConnection -LocalPort ${port} | Select-Object -ExpandProperty OwningProcess | `
+      + "ForEach-Object { Get-Process -Id $_ }"
+    : `ss -ltnp 'sport = :${port}'   (or: lsof -i :${port})`;
+}
+
+/** How to stop the process that turned up, once the reader has found it. */
+export const stopThatProcess = ({ platform = process.platform } = {}) =>
+  (isWindows(platform) ? "Stop-Process -Id <the PID above>" : "kill <the pid above>");
+
+/**
+ * How to remove one directory and everything under it.
+ *
+ * `-Recurse -Force` is the pair, and both are needed: without `-Recurse` PowerShell prompts for a
+ * non-empty directory, and a reader who is told to remove a directory and then asked to confirm each
+ * child has been given a command that does not do what the sentence said it would.
+ */
+export const removeDirectory = (dir, { platform = process.platform } = {}) =>
+  (isWindows(platform) ? `Remove-Item -Recurse -Force "${dir}"` : `rm -rf ${dir}`);
+
+/**
+ * Set one environment variable for the length of one command.
+ *
+ * `VAR=value cmd` is a POSIX shell construct with no PowerShell equivalent — there it is a statement of
+ * its own, so the pair has to be separated rather than juxtaposed. A reader who pastes the POSIX form
+ * into PowerShell is told the variable name is not a recognised cmdlet, which names the wrong half of
+ * the line as the problem.
+ */
+export const envPrefix = (name, value, { platform = process.platform } = {}) =>
+  (isWindows(platform) ? `$env:${name}="${value}"; ` : `${name}=${value} `);
+
+/**
+ * Move to a directory, then run what follows.
+ *
+ * `&&` IS THE PART THAT FAILS, not the path. Windows PowerShell 5.1 — still the default shell on a
+ * stock machine — has no `&&` operator at all, so `cd X && npx …` is a parse error there before the
+ * backslashes matter. `;` runs in both 5.1 and 7, and quoting the directory covers the spaces a
+ * Windows home path routinely carries.
+ *
+ * The POSIX form keeps `&&` deliberately: it is not a separator there, it is a guard, and running the
+ * command from the wrong directory because the `cd` failed is worse than not running it.
+ */
+export const chdirPrefix = (dir, { platform = process.platform } = {}) =>
+  (isWindows(platform) ? `cd "${dir}"; ` : `cd ${dir} && `);
+
+/**
+ * What keeps a background instance alive, named for the thing that actually does it.
+ *
+ * `null` where this platform has no such mechanism in the product, so a caller prints nothing rather
+ * than naming a service manager the reader does not have. Windows was told the background form was
+ * "managed by systemd", which is not on the machine and cannot be installed onto it.
+ */
+export const backgroundManager = ({ platform = process.platform } = {}) =>
+  (isWindows(platform) ? null : "systemd");

package/shared/reap-on-exit.mjs

@@ -36,8 +36,27 @@
 //
 // IDEMPOTENT, and unregistering is the caller's normal path: a child that exits on its own drops out,
 // so the reaper never signals a pid that has been recycled onto somebody else's process.
+//
+// ── WHY DIRECTORY REMOVAL LIVES IN THIS FILE AND NOT BESIDE IT ────────────────────────────────────
+//
+// A browser run's temp root can only be removed AFTER its process group is dead. Chrome's renderer,
+// GPU and zygote children keep writing the profile while they live, so a removal that runs first
+// races them and throws ENOTEMPTY — a race three of the call sites below already carry a comment
+// about, on their own success paths.
+//
+// Two separate exit handlers cannot express that ordering: Node runs `exit` listeners in
+// registration order, so the guarantee would depend on which module a caller happened to import
+// first. One handler doing both, in the order written here, is the whole reason `removeOnExit` is
+// not its own module.
+//
+// The removal is best-effort for the same reason the kill is: a handler that throws on the way out
+// of a crashing script replaces one problem with a worse one. `maxRetries` covers ENOTEMPTY, which
+// is the error the surviving-children race actually produces.
+
+import { rmSync } from "node:fs";
 
 const groups = new Set();
+const dirs = new Set();
 let installed = false;
 
 function reapAll() {
@@ -49,6 +68,11 @@ function reapAll() {
     try { process.kill(-pid, "SIGKILL"); } catch { try { process.kill(pid, "SIGKILL"); } catch { /* already gone */ } }
   }
   groups.clear();
+  // ONLY NOW, with the groups signalled, is the temp root removable. See the note above.
+  for (const dir of dirs) {
+    try { rmSync(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 200 }); } catch { /* a stray temp root is not worth failing an exit over */ }
+  }
+  dirs.clear();
 }
 
 function install() {
@@ -77,7 +101,25 @@ export function reapOnExit(child) {
   return stop;
 }
 
+/**
+ * Remove `dir` when THIS process exits, by any route it can observe, and only after every watched
+ * process group has been signalled.
+ *
+ * @returns {() => void} stop watching, for a caller that removes the directory itself.
+ */
+export function removeOnExit(dir) {
+  if (typeof dir !== "string" || dir === "") return () => {};
+  dirs.add(dir);
+  install();
+  return () => dirs.delete(dir);
+}
+
 /** The pids currently watched. For arms — a reaper nobody can inspect is a reaper nobody can test. */
 export function watchedGroups() {
   return [...groups];
 }
+
+/** The directories currently watched, for the same reason. */
+export function watchedDirs() {
+  return [...dirs];
+}