create-pmos 0.26.0 → 0.28.0

package/workspace/test-run.js

@@ -0,0 +1,84 @@
+'use strict';
+/* test-run.js — THE ISOLATION A SUITE GETS BY CALLING ONE FUNCTION.
+ *
+ * Every suite in this workspace boots real servers, opens real PTYs and writes real state. The
+ * PM's live runtime state used to live at `workspace/state/`, INSIDE the directory the suites run
+ * from, so it was reachable BY CONSTRUCTION — by any verb, by any subprocess, by any stray shell
+ * command in the tree. `test.js#resetState()` removed sessions/, scratchpad/, workspaces.json,
+ * schedules.json, deliverables/ and skills/ from it five times a run, and the suite was safe in CI
+ * only because a fresh checkout has nothing there.
+ *
+ * The state has moved out (lib/state-root.js). What remains is to make sure a suite never resolves
+ * to the NEW per-user location either — an installed copy's state IS the PM's own, so "the app's
+ * own directory" was never the isolation boundary anybody thought it was. `configure()` points
+ * PMOS_STATE_DIR at a fresh scratch directory before `server.js` is ever required and before any
+ * child is spawned, so a run writes only into a directory it made.
+ *
+ * It also hands out a PRIVATE TMUX SOCKET (never the PM's own, `pmos`) and an EPHEMERAL PORT
+ * claimed from the kernel rather than a bet on 7599/7601-7606. The port is about collisions, not
+ * about state, and it is worth being exact about what it buys: it makes a collision RARE. It does
+ * not DETECT one — a suite that does collide still drives whatever answers, and proving whose
+ * server is on a port is a different defect with its own repair. Nothing here claims otherwise.
+ *
+ * It lives at the workspace root rather than under lib/ on purpose: lib/ is the SHIPPED server
+ * process, and no-network.test.js holds every file there to a standard this scaffolding does not
+ * need to meet. It belongs beside the suites.
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const HOST = '127.0.0.1';
+
+let state = null;   // set by configure(); this module is a no-op until then
+
+/** Bind :0, read the port back, release it. Synchronous because callers need PORT as a const. */
+function claimEphemeralPort() {
+  const src = "const s=require('net').createServer();s.listen(0,'127.0.0.1',()=>{process.stdout.write(String(s.address().port));s.close()});";
+  const out = execFileSync(process.execPath, ['-e', src], { encoding: 'utf8' });
+  const n = Number(String(out).trim());
+  if (!Number.isInteger(n) || n <= 0) throw new Error('could not claim an ephemeral port');
+  return n;
+}
+
+/**
+ * Arm a suite. MUST be called before `require('./server')` and before any child is spawned —
+ * server.js resolves its state root at require time, and a child inherits the environment as it
+ * stood when it was spawned.
+ *
+ * Returns, and also exposes on the module: PORT, HOST, BASE, STATE_DIR.
+ */
+function configure({ name = 'run', port = null } = {}) {
+  if (state) return state;
+  const stateDir = process.env.PMOS_STATE_DIR
+    ? path.resolve(process.env.PMOS_STATE_DIR)
+    : fs.mkdtempSync(path.join(os.tmpdir(), `pmos-state-${name}-`));
+  fs.mkdirSync(stateDir, { recursive: true });
+  // In the environment BEFORE server.js is required here and before any child inherits it. Every
+  // boot site in every suite goes through process.env, so this is a chokepoint by construction
+  // rather than a convention each call site has to remember — and a convention that must be
+  // remembered at hundreds of call sites is a convention that will be forgotten at one of them,
+  // which is exactly how this class of defect got in.
+  process.env.PMOS_STATE_DIR = stateDir;
+  // A private tmux socket, never the PM's own ('pmos'), so a suite cannot reach their sessions.
+  process.env.PMOS_TMUX_SOCK = process.env.PMOS_TMUX_SOCK || `pmos-${name}-${process.pid}`;
+
+  const chosen = Number(port) > 0 ? Number(port) : claimEphemeralPort();
+
+  state = {
+    PORT: chosen, HOST, BASE: `http://${HOST}:${chosen}`, STATE_DIR: stateDir,
+    /** Environment for a spawned server/launcher: this run's state dir and tmux socket. */
+    env(extra = {}) {
+      return { ...process.env, PMOS_STATE_DIR: stateDir, ...extra };
+    },
+    /** A port nobody else holds, for a suite that needs a second server. */
+    port: claimEphemeralPort,
+    /** Remove the scratch state directory. Safe by construction: this run made it. */
+    cleanup() { try { fs.rmSync(stateDir, { recursive: true, force: true }); } catch {} },
+  };
+  Object.assign(module.exports, state);
+  return state;
+}
+
+module.exports = { configure, claimEphemeralPort, HOST };