staysfixed 0.12.0 → 0.13.0

package/src/drive/browser.js

@@ -14,6 +14,7 @@ import path from 'node:path';
 
 import { StaysFixedError, isExpected } from '../core/errors.js';
 import { detail } from '../core/log.js';
+import { stopTree, OWN_PROCESS_GROUP } from '../core/stop-tree.js';
 import { DEFAULT_VIEWPORT } from '../core/config.js';
 import { waitForEndpoint, listTargets, connect } from './cdp.js';
 import { requireChrome, freePort } from './find.js';
@@ -116,20 +117,17 @@ export function whenExited(child) {
 export async function stopProcess(child, graceMs) {
   if (isGone(child)) return;
   const exited = whenExited(child);
-  try {
-    child.kill('SIGTERM');
-  } catch {
-    // Already gone between the check and the signal. Nothing to do.
-  }
+  // The tree, not just this one process. A browser is never one process — it is a parent and
+  // a renderer for every page — and on Windows killing only the parent leaves the renderers
+  // running, still writing into the throwaway profile, so the profile folder cannot be
+  // deleted and outlives the run. That is the one thing "nothing it opened outlives the run"
+  // promises. Measured on a real Windows 11 machine on 2026-08-31.
+  stopTree(child.pid, 'SIGTERM', { child });
   const grace = raceTimer(graceMs, false);
   const stopped = await Promise.race([exited.then(() => true), grace.promise]);
   grace.cancel();
   if (stopped) return;
-  try {
-    child.kill('SIGKILL');
-  } catch {
-    // Same race as above.
-  }
+  stopTree(child.pid, 'SIGKILL', { child });
   const last = raceTimer(1000, false);
   await Promise.race([exited, last.promise]);
   last.cancel();
@@ -458,7 +456,11 @@ export async function startWebApp(app, opts = {}) {
     // Its own process group. A dev server is really a shell that spawns a
     // bundler that spawns a watcher; killing only the shell leaves the port held
     // and the next run fails for a reason nobody can see.
-    detached: true,
+    //
+    // Not on Windows, where `detached: true` means something else entirely — a console
+    // WINDOW of its own, flashing up on the person's screen in the middle of a check.
+    // Windows stops the tree a different way, in `stopTree`, and needs nothing at spawn time.
+    detached: OWN_PROCESS_GROUP,
     stdio: ['ignore', 'pipe', 'pipe'],
   });
   const output = keepOutput(child);
@@ -478,30 +480,17 @@ export async function startWebApp(app, opts = {}) {
     stopping ??= (async () => {
       if (isGone(child)) return;
       const exited = whenExited(child);
-      try {
-        // Negative pid means the whole group — the only way to take the
-        // watchers down with the server.
-        if (pid) process.kill(-pid, 'SIGTERM');
-      } catch {
-        try {
-          child.kill('SIGTERM');
-        } catch {
-          // Already gone.
-        }
-      }
+      // The whole tree, not just the shell. On Linux and a Mac that is the process group;
+      // on Windows it is `taskkill /T`, which is what `stopTree` reaches for. Before this,
+      // Windows killed `cmd.exe` and left the dev server holding the port, so the next run
+      // failed for a reason nobody could see — the exact outcome the comment above warns
+      // about, on the one operating system where the code did not do it. Found 2026-08-31.
+      stopTree(pid, 'SIGTERM', { child });
       const grace = raceTimer(5000, false);
       const gone = await Promise.race([exited.then(() => true), grace.promise]);
       grace.cancel();
       if (gone) return;
-      try {
-        if (pid) process.kill(-pid, 'SIGKILL');
-      } catch {
-        try {
-          child.kill('SIGKILL');
-        } catch {
-          // Already gone.
-        }
-      }
+      stopTree(pid, 'SIGKILL', { child });
       const last = raceTimer(1000, false);
       await Promise.race([exited, last.promise]);
       last.cancel();

package/src/drive/page.js

@@ -150,6 +150,73 @@ function removeStyleTagSource(token) {
   );
 }
 
+/**
+ * What somebody handed `evaluate`, turned into a piece of JavaScript the app can run.
+ *
+ * A STRING IS NOT THE OBVIOUS THING TO PASS. Every other tool in this space takes a
+ * function — `page.evaluate(() => document.title)` is what anybody who has driven a browser
+ * before writes first — and this took only text. Handing it a function put a function object
+ * where the debug protocol wanted a string, and what came back was, in full, measured while
+ * using the tool on 2026-08-31:
+ *
+ *     The app refused the request "Runtime.evaluate": Invalid parameters
+ *
+ * That is the machine's own words about its own wire format, said to somebody who has done
+ * nothing wrong except write the thing that works everywhere else. So a function is now
+ * accepted and turned into the call it obviously means, and text goes through untouched.
+ * Only what genuinely cannot be run says so — in a sentence naming what it was given and
+ * showing the one line that works.
+ *
+ * It runs with nothing passed to it, which is why a function that declares a parameter is
+ * refused rather than quietly given `undefined`: there is no way to send a value into the
+ * page here, and the alternative is a guard failing inside the app for a reason that has
+ * nothing to do with the app.
+ *
+ * @param {unknown} what   A piece of JavaScript as text, or a function to call in the page.
+ * @returns {string}
+ */
+export function asJavaScript(what) {
+  if (typeof what === 'string') return what;
+
+  if (typeof what === 'function') {
+    const source = String(what);
+    // A built-in — `page.evaluate(Math.max)`, `page.evaluate(document.querySelector)` — has
+    // no readable body, so there is nothing to send. Asked FIRST, before anything about the
+    // arguments: a built-in usually declares some, and being told to close over them is
+    // advice about a function nobody could have sent anyway. Said plainly, too, because
+    // "SyntaxError: Unexpected token" out of the page is a worse version of the message this
+    // whole function exists to replace.
+    if (/\{\s*\[native code\]\s*\}/.test(source)) {
+      throw new StaysFixedError('evaluate() was handed a built-in function, and the app cannot be sent one: it has no source to run.', {
+        hint: 'Wrap it in a function of your own: page.evaluate(() => document.querySelector(".total").textContent).',
+      });
+    }
+    if (what.length > 0) {
+      throw new StaysFixedError(
+        `evaluate() runs a function inside the app with nothing passed to it, and this one asks for ${what.length === 1 ? 'an argument' : `${what.length} arguments`}.`,
+        {
+          hint: 'Nothing can be sent into the page here. Close over what it needs, or write the value into the JavaScript itself: page.evaluate(`document.title === ${JSON.stringify(expected)}`).',
+        },
+      );
+    }
+    // Shorthand method syntax — `{ title() { ... } }` — is not an expression on its own, so
+    // the ordinary wrapping below would send the app something it cannot parse. Put back in
+    // the object it was written in and called by name.
+    //
+    // A leading `async` is taken off before the name is read, and it has to be: leave it on
+    // and the pattern happily reads `async () => 1` as a method called "async", because
+    // backtracking gives up the optional keyword and matches the word itself.
+    const shorthand = /^(?!function\b)([A-Za-z_$][\w$]*)\s*\(/.exec(source.replace(/^async\s+/, ''));
+    if (shorthand) return `({ ${source} }).${shorthand[1]}()`;
+    return `(${source})()`;
+  }
+
+  throw new StaysFixedError(
+    `evaluate() wants a piece of JavaScript written as text, or a function to run in the app. It was given ${what === null ? 'null' : typeof what}.`,
+    { hint: 'Either way round works: page.evaluate(\'document.title\') or page.evaluate(() => document.title).' },
+  );
+}
+
 /**
  * One line describing whatever the page threw.
  * @param {any} details  Runtime.ExceptionDetails
@@ -283,12 +350,17 @@ export async function createPage(cdp, opts) {
   // ---------------------------------------------------------------------------
 
   /**
-   * @param {string} js
+   * Run JavaScript in the page.
+   *
+   * Takes it as text, or as a function to call — see {@link asJavaScript} for why both, and
+   * for the message that used to come back when somebody wrote the function.
+   *
+   * @param {string|Function} js
    * @returns {Promise<any>}
    */
   async function evaluate(js) {
     const res = await send('Runtime.evaluate', {
-      expression: js,
+      expression: asJavaScript(js),
       awaitPromise: true,
       returnByValue: true,
       userGesture: true,

package/src/guard/api.js

@@ -19,6 +19,7 @@ import { spawn } from 'node:child_process';
 import fsp from 'node:fs/promises';
 import path from 'node:path';
 import { StaysFixedError } from '../core/errors.js';
+import { stopTree, OWN_PROCESS_GROUP } from '../core/stop-tree.js';
 
 /** A plain-language expectation that did not hold. */
 export class ExpectationFailed extends Error {
@@ -313,7 +314,7 @@ export function makeGuardApi(page, project, opts = {}) {
         const child = spawn(cmd, {
           cwd,
           shell: true,
-          detached: process.platform !== 'win32',
+          detached: OWN_PROCESS_GROUP,
           windowsHide: true,
         });
 
@@ -324,15 +325,19 @@ export function makeGuardApi(page, project, opts = {}) {
         let how = 'ran';
         let done = false;
 
-        /** Stop the shell AND everything it started. */
+        /**
+         * Stop the shell AND everything it started.
+         *
+         * This used to kill only the child on Windows, with a comment saying that was the
+         * best that could be done there. It is not: measured on a real Windows 11 machine on
+         * 2026-08-31, "kills a command that was still running when the run gave up" failed,
+         * because killing `cmd.exe` left the `node` underneath it running and it finished its
+         * work and wrote its file after the run had given up on it — the same defect Linux
+         * showed on 2026-08-31, on a different operating system's spelling of it. `stopTree`
+         * holds both spellings.
+         */
         const stopEverything = () => {
-          if (!child.pid) return;
-          try {
-            if (process.platform === 'win32') child.kill('SIGKILL');
-            else process.kill(-child.pid, 'SIGKILL');
-          } catch {
-            // Already gone, which is the good case.
-          }
+          stopTree(child.pid, 'SIGKILL', { child });
         };
 
         child.stdout?.setEncoding('utf8');

package/src/types.js

@@ -206,7 +206,7 @@
  * @property {(selector: string, opts?: {timeoutMs?: number}) => Promise<void>} waitForGone
  * @property {(selector: string) => Promise<void>} scrollTo
  * @property {(ms: number) => Promise<void>} wait
- * @property {(js: string) => Promise<any>} evaluate
+ * @property {(js: string|Function) => Promise<any>} evaluate   Text, or a function to run in the page.
  * @property {(selector: string) => Promise<boolean>} visible
  * @property {(selector: string) => Promise<boolean>} exists
  * @property {(selector: string) => Promise<string>} textOf

package/src/v2/adapters/child.js

@@ -21,6 +21,8 @@
 
 import { spawn } from 'node:child_process';
 
+import { stopTree, OWN_PROCESS_GROUP } from '../../core/stop-tree.js';
+
 /**
  * Start the product, in a group of its own.
  *
@@ -34,9 +36,10 @@ export function spawnServer(command, opts) {
     cwd: opts.cwd,
     env: opts.env,
     stdio: opts.stdio ?? ['ignore', 'pipe', 'pipe'],
-    // The whole point. On Windows there are no process groups of this kind, and killing the
-    // child is the best that can be done there.
-    detached: process.platform !== 'win32',
+    // The whole point. Windows has no process groups of this kind, and `detached` there means
+    // a console window of its own instead — so Windows is left alone at spawn time and gets
+    // its whole tree stopped by `stopTree` below, which walks the children itself.
+    detached: OWN_PROCESS_GROUP,
   });
 }
 
@@ -52,21 +55,16 @@ export async function stopServer(child, opts = {}) {
   const pid = child.pid;
   const graceMs = opts.graceMs ?? 500;
 
-  /** @param {NodeJS.Signals} signal */
+  /**
+   * @param {'SIGTERM'|'SIGKILL'} signal
+   */
   const tellTheGroup = (signal) => {
-    if (!pid) return;
-    try {
-      // A negative pid is the GROUP. This is the line that makes the difference.
-      if (process.platform === 'win32') child.kill(signal);
-      else process.kill(-pid, signal);
-    } catch {
-      // No group, or already gone. Ask the one process we definitely know about.
-      try {
-        child.kill(signal);
-      } catch {
-        // Already gone, which is the outcome wanted.
-      }
-    }
+    // The group on Linux and a Mac, the tree of children on Windows. Killing only the shell
+    // on Windows left the server running and holding the folder it was started in: measured
+    // on a real Windows 11 machine on 2026-08-31, where the whole of `waiting.test.js` failed
+    // on being unable to delete its own scratch folder afterwards, because the servers it had
+    // asked to stop were all still there.
+    stopTree(pid, signal, { child });
   };
 
   if (child.exitCode === null && child.signalCode === null) {

package/src/v2/adapters/contract.js

@@ -378,6 +378,10 @@ export function compareJson(a, b) {
  * @param {string} spec.says
  * @param {boolean} [spec.covered]        False means we did not really look. See `reason`.
  * @param {NotCoveredReason} [spec.reason]
+ * @param {string} [spec.detail]          What the thing itself said, in its own words, when it
+ *                                        said anything. Goes onto the refusal's reason, which
+ *                                        is where a person reads why a hole is a hole. Never
+ *                                        compared — see `whatItSaid` for why that matters.
  * @param {{file?: string, line?: number, url?: string}} [spec.where]
  * @param {string} [spec.evidence]
  * @param {string} [spec.journey]
@@ -414,7 +418,16 @@ export function observation(spec) {
     // — and never this flag. Written down on 2026-08-31 after the refusal lane found the two
     // meanings sharing one field.
     meta.refused = true;
-    meta.refusedWhy = `${NOT_COVERED_MEANING[spec.reason ?? 'refused']} (${spec.reason ?? 'refused'})`;
+    // The reason word stays first and stays in the fixed vocabulary, because the ledger counts
+    // these and a free-text reason cannot be counted. What the thing ITSELF said goes on the
+    // end. That position is deliberate: `staysfixed coverage` prints this line with a 400
+    // character budget and the sentence above it with 160, so this is the place where the real
+    // error — the `ModuleNotFoundError`, the `SyntaxError` — reliably survives being trimmed
+    // and reaches the person who has to go and fix it. Added 2026-08-31, after three broken
+    // products were checked and none of their owners was ever told what was wrong.
+    meta.refusedWhy = `${NOT_COVERED_MEANING[spec.reason ?? 'refused']} (${spec.reason ?? 'refused'})${
+      spec.detail ? ` — and this is what it said for itself: ${spec.detail}` : ''
+    }`;
   }
   return makeObservation(path, spec.channel, stableValue(spec.value), meta);
 }
@@ -431,6 +444,7 @@ export function observation(spec) {
  * @param {string|(string|number)[]} spec.path
  * @param {NotCoveredReason} spec.reason
  * @param {string} spec.says              What we would have looked at, and why we did not.
+ * @param {string} [spec.detail]          What the thing itself said about it, in its own words.
  * @param {{file?: string, line?: number, url?: string}} [spec.where]
  * @returns {Observation}
  */
@@ -438,10 +452,15 @@ export function notCovered(spec) {
   return observation({
     channel: spec.channel,
     path: spec.path,
+    // The VALUE stays the fixed sentence and never carries what the thing said. Two builds
+    // that fall over with two different messages would otherwise differ at this address, and
+    // the report would call a crash a change in the product. The words go in `says` and in the
+    // refusal's reason, neither of which is ever compared.
     value: `not checked — ${NOT_COVERED_MEANING[spec.reason]}`,
     says: spec.says,
     covered: false,
     reason: spec.reason,
+    detail: spec.detail,
     where: spec.where,
   });
 }
@@ -610,6 +629,108 @@ export function undoOurFootprint(text, footprint) {
   return out;
 }
 
+/**
+ * What a program said about itself, cut down to the part a person can act on.
+ *
+ * WHY THIS EXISTS. Measured on 2026-08-31, against three deliberately broken products: a Node
+ * server whose source has a syntax error, a Python command importing a module that is not
+ * installed, and a Node command importing a package that is not installed. All three were
+ * correctly refused — no false all-clear, and that half worked. But a grep of the whole reply,
+ * `--verbose` included, found no mention of `SyntaxError`, `ModuleNotFoundError` or
+ * `ERR_MODULE_NOT_FOUND` anywhere in it. Every owner was told "the thing being observed fell
+ * over before it could be read" and then had to go and find the reason themselves. Each
+ * product had printed the reason, in one line, on its own standard error, and this tool threw
+ * it away. Handing somebody a sentence they can act on is the whole design; this is the
+ * function that keeps the product's own sentence instead of a paraphrase of it.
+ *
+ * NOTHING IS INVENTED HERE. What comes out is the program's own words. What is dropped is only
+ * what carries nothing for the person reading: blank lines, the `at ...` frames of a stack
+ * trace, the caret lines that underline a column of a terminal that is not this one, "... 4
+ * more" frame counts, and Node's own version footer. What is left over the budget is dropped
+ * from the FRONT, because every runtime in use here — Node, Python, a shell — puts the
+ * sentence that says what went wrong at the END of what it printed.
+ *
+ * This is evidence, not noise, and it belongs in the reply. It is never compared: it goes into
+ * the sentence and into the refusal's reason, both of which live in `meta`, so a crash that
+ * words itself differently on two machines can never register as a difference in the product.
+ *
+ * @param {string} text            Whatever the thing printed. Run our own footprint out of it
+ *                                 first, or a scratch path ends up quoted at a person.
+ * @param {object} [opts]
+ * @param {number} [opts.mostLines]  How many lines of it to keep. Default 6.
+ * @param {number} [opts.mostChars]  How many characters of it to keep. Default 300.
+ * @returns {string}  One line, or '' when it said nothing worth repeating.
+ */
+export function whatItSaid(text, opts = {}) {
+  const mostLines = opts.mostLines ?? 6;
+  const mostChars = opts.mostChars ?? 300;
+  const lines = String(text ?? '')
+    // Colour codes are how a program makes an error red in a terminal. Printed into a
+    // sentence they are unreadable rubbish, and they are not part of what it said.
+    .replace(/\u001b\[[0-9;]*m/g, '')
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line !== '' && !NOT_WORTH_REPEATING.some((noise) => noise.test(line)));
+  if (lines.length === 0) return '';
+
+  // ONE LINE MEANS THE ONE THAT NAMES THE TROUBLE, not simply the last one.
+  //
+  // "The last line" was the first thing tried and it is wrong often enough to matter: measured
+  // 2026-08-31 on a Node command importing a package that is not installed, Node printed the
+  // whole error object after the message, so the last line was `}` and the headline read "It
+  // said: }." — which is worse than saying nothing. So the line that looks like a runtime
+  // naming a fault is preferred, and the last line is what happens when none does. Preferred,
+  // never required: nothing is dropped by this, it only decides which single line gets quoted
+  // where there is room for one, and the fuller quote sits directly underneath it.
+  if (mostLines === 1) {
+    const named = [...lines].reverse().find((line) => NAMES_THE_TROUBLE.test(line)) ?? lines[lines.length - 1];
+    return named.length > mostChars ? `${named.slice(0, mostChars - 3)}...` : named;
+  }
+
+  /** @type {string[]} */
+  const kept = [];
+  let used = 0;
+  for (let i = lines.length - 1; i >= 0 && kept.length < mostLines; i--) {
+    const line = lines[i];
+    if (kept.length > 0 && used + line.length + 3 > mostChars) break;
+    kept.unshift(line);
+    used += line.length + 3;
+  }
+  // One line longer than the whole budget is still the line that says what went wrong, so it
+  // is kept and cut rather than dropped for being too long.
+  if (kept.length === 1 && kept[0].length > mostChars) kept[0] = `${kept[0].slice(0, mostChars - 3)}...`;
+  const left = lines.length - kept.length;
+  // Said out loud rather than trimmed silently: a reader who is told six lines were left out
+  // knows to open the evidence file, and a reader who is not told assumes they have all of it.
+  return `${left > 0 ? `(${left} earlier ${left === 1 ? 'line' : 'lines'} left out) ` : ''}${kept.join(' / ')}`;
+}
+
+/**
+ * A line that reads like a runtime saying what went wrong.
+ *
+ * The three shapes measured on 2026-08-31, one from each broken product: `SyntaxError:
+ * Unexpected end of input`, `ModuleNotFoundError: No module named 'tabulate'`, and `Error
+ * [ERR_MODULE_NOT_FOUND]: Cannot find package 'chalk' imported from ...`. The second pattern is
+ * for the tools that write their trouble in lower case instead — a compiler, git, a shell.
+ */
+const NAMES_THE_TROUBLE =
+  /^[A-Za-z_$][A-Za-z0-9_$.]*(?:Error|Exception|Warning)(?:\s*\[[^\]]*\])?\s*:|^(?:fatal|error|panic|Traceback)\b/i;
+
+/**
+ * Lines that are in the way of the sentence rather than part of it.
+ *
+ * Deliberately short. Every pattern here has to be something that cannot possibly BE the
+ * reason a product fell over — a stack frame under the message, a caret underlining a column,
+ * a version footer. Anything else stays, because a rule that guesses which of a program's own
+ * lines matter is a rule that will one day drop the only line that did.
+ */
+const NOT_WORTH_REPEATING = [
+  /^at\s+\S/,                    // a stack frame under the message that already said it
+  /^[\^~]+$/,                    // the caret line underlining a column in somebody else's terminal
+  /^\.\.\.\s*\d+\s+more$/,        // "... 4 more", the frames a runtime left out itself
+  /^Node\.js v[\d.]+$/,          // Node's version footer, printed under every uncaught throw
+];
+
 /**
  * Keep a piece of text at a size worth storing.
  *