staysfixed 0.7.2 → 0.9.0

package/src/v2/adapters/android.js

@@ -73,6 +73,100 @@ const CLEAN_SNAPSHOT = 'staysfixed-clean';
 /** The journey that needs no device at all. */
 const DECLARED = 'what the app declares';
 
+// ---------------------------------------------------------------------------
+// The virtual device this tool asks for
+// ---------------------------------------------------------------------------
+
+/**
+ * The API level to build a virtual device at when nothing says otherwise.
+ *
+ * Newer is the safe direction and it is the only direction that is safe. A device must be at
+ * least as new as the app's `minSdkVersion` or the app cannot be installed on it at all; an app
+ * that TARGETS something older installs on a newer device and runs under compatibility rules.
+ * So the failure from picking too high is a behaviour difference the tool would report, and the
+ * failure from picking too low is "it would not install", which looks like a broken product.
+ *
+ * When there is an APK in hand its own minSdk is read and this is raised to match — see
+ * `deviceFor`. This number is only the answer for somebody who has not built anything yet.
+ */
+export const EMULATOR_API = 35;
+
+/**
+ * The processor the image has to be built for.
+ *
+ * Both files that recommended an image used to hardcode `arm64-v8a`, so the command handed to
+ * anybody on an Intel Mac or an x86 Linux box named an image that does not exist for their
+ * machine and failed with a message about the image rather than about the architecture.
+ *
+ * @returns {string|null} null when this machine's architecture has no emulator image at all.
+ */
+export function emulatorAbi() {
+  // Only three answers exist, and anything else has to say so rather than pick one.
+  //
+  // This used to be arm64 or x86_64, with x86_64 as the fallback for every other
+  // architecture. On a 32-bit Intel machine, or an s390x, or anything else Node runs on, that
+  // names an emulator image Google does not publish — so the command handed over as "the tool
+  // can do this itself" fails with an error about a package that does not exist, and the
+  // person is left looking for a typo in a line this tool wrote for them.
+  if (process.arch === 'arm64') return 'arm64-v8a';
+  if (process.arch === 'x64') return 'x86_64';
+  if (process.arch === 'ia32') return 'x86';
+  return null;
+}
+
+/**
+ * What to install, and the two commands that install it — kept together on purpose.
+ *
+ * The warning is part of the answer, not a footnote beside it. A Play Store image refuses root
+ * permanently, and without root the files an app writes are invisible, so a person who follows
+ * a command printed without this sentence ends up with a device that silently checks less than
+ * they think. That happened because two files each had their own copy of the command and only
+ * one carried the warning. There is one copy now, and the warning cannot be separated from it.
+ *
+ * `google_apis` and NOT `google_apis_playstore` is the whole of the rule.
+ *
+ * @param {{api?: number, name?: string}} [opts]
+ * @returns {{image: string|null, install: string|null, create: string|null, why: string, both: string}}  image, install and create are null where this machine has no emulator image at all; `why` and `both` then say so.
+ */
+export function deviceToMake(opts = {}) {
+  const api = Math.max(EMULATOR_API, opts.api ?? 0);
+  const name = opts.name ?? 'staysfixed';
+  const abi = emulatorAbi();
+  const warning = 'Pick a plain Google APIs image, NOT a Play Store one: a Play Store device refuses root forever, and without root the files an app writes cannot be seen.';
+
+  // No image exists for this machine, and saying so beats naming one that does not exist.
+  //
+  // Google publishes emulator images for arm64, x86_64 and x86 and nothing else. Handing
+  // somebody a command that fails on a package nobody has ever published sends them looking
+  // for a typo in a line this tool wrote for them, which is a worse place to be than being
+  // told plainly that their machine cannot run one.
+  if (!abi) {
+    const cannot = `No Android emulator image is published for a ${process.arch} machine, so an emulator cannot be created here. Plug in a real Android device, or run the check from a machine on arm64, x86_64 or x86.`;
+    return { image: null, install: null, create: null, why: cannot, both: cannot };
+  }
+
+  const image = `system-images;android-${api};google_apis;${abi}`;
+  const install = `sdkmanager --install "${image}"`;
+  const create = `avdmanager create avd -n ${name} -k "${image}"`;
+  return {
+    image,
+    install,
+    create,
+    why: warning,
+    both: `${install} then ${create}. ${warning}`,
+  };
+}
+
+/**
+ * The same answer, raised to whatever the app in front of us actually needs.
+ *
+ * @param {{minSdk?: number|null}|null} apk
+ * @returns {ReturnType<typeof deviceToMake>}
+ */
+export function deviceFor(apk) {
+  return deviceToMake({ api: apk?.minSdk ?? 0 });
+}
+
 // ---------------------------------------------------------------------------
 // Finding the APK
 // ---------------------------------------------------------------------------
@@ -522,7 +616,7 @@ export const androidAdapter = defineAdapter({
       missing.push({
         what: 'a virtual device for the emulator to run',
         unlocks: 'having somewhere to install the app',
-        howToGet: 'sdkmanager --install "system-images;android-33;google_apis;arm64-v8a" then avdmanager create avd -n staysfixed -k "system-images;android-33;google_apis;arm64-v8a". Pick a plain Google APIs image, NOT a Play Store one: a Play Store device refuses root forever, and without root the files an app writes cannot be seen.',
+        howToGet: deviceFor(apk).both,
       });
     }
 
@@ -531,7 +625,8 @@ export const androidAdapter = defineAdapter({
       missing.push({
         what: 'a virtual device built from a plain Google APIs image rather than a Play Store one',
         unlocks: 'seeing the files the app writes, and stopping the clock. A Play Store device refuses root permanently, and both of those need it',
-        howToGet: 'avdmanager create avd -n staysfixed -k "system-images;android-33;google_apis;arm64-v8a"',
+        // Null on a machine with no emulator image at all; `why` then carries the reason.
+        howToGet: deviceFor(apk).create ?? deviceFor(apk).why,
       });
     }
     if (usable.some((d) => !d.emulator)) {

package/src/v2/adapters/child.js

@@ -0,0 +1,101 @@
+/**
+ * Starting and stopping the product's own server.
+ *
+ * A start command is run through a shell, because that is what people write: `npm run dev`,
+ * `sh dev.sh`, `poetry run uvicorn ...`. So the thing that is spawned is the SHELL, and the
+ * server is its child — often its grandchild, since `npm run dev` is npm, which runs next,
+ * which runs node.
+ *
+ * Killing the shell therefore does not kill the server. And because the shell's stdout and
+ * stderr are pipes, every survivor inherits the writing end of them — so the pipes never
+ * close, this process's event loop never empties, and `staysfixed check` prints its whole
+ * answer and then hangs for ever at nothing per cent of a CPU. Measured on 2026-08-30 on a
+ * start command that spawns its server and waits, which is the shape `npm run dev` has: the
+ * verdict appeared in about thirty seconds and the command never returned.
+ *
+ * So the shell is started as its own process GROUP and the whole group is signalled. And
+ * after that, the pipes are torn down here rather than trusted to close, because a survivor
+ * this file did not start — a stray `node` somebody's dev server left behind — must not be
+ * able to hold a finished check open.
+ */
+
+import { spawn } from 'node:child_process';
+
+/**
+ * Start the product, in a group of its own.
+ *
+ * @param {string} command
+ * @param {{cwd: string, env: any, stdio?: any}} opts
+ * @returns {import('node:child_process').ChildProcess}
+ */
+export function spawnServer(command, opts) {
+  return spawn(String(command), {
+    shell: true,
+    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',
+  });
+}
+
+/**
+ * Stop it, and everything it started.
+ *
+ * @param {import('node:child_process').ChildProcess|null|undefined} child
+ * @param {{graceMs?: number}} [opts]
+ * @returns {Promise<void>}
+ */
+export async function stopServer(child, opts = {}) {
+  if (!child) return;
+  const pid = child.pid;
+  const graceMs = opts.graceMs ?? 500;
+
+  /** @param {NodeJS.Signals} 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.
+      }
+    }
+  };
+
+  if (child.exitCode === null && child.signalCode === null) {
+    tellTheGroup('SIGTERM');
+    await new Promise((done) => {
+      let settled = false;
+      const finish = () => {
+        if (settled) return;
+        settled = true;
+        done(undefined);
+      };
+      child.once('exit', finish);
+      const timer = setTimeout(finish, graceMs);
+      if (typeof timer.unref === 'function') timer.unref();
+    });
+    if (child.exitCode === null && child.signalCode === null) tellTheGroup('SIGKILL');
+  }
+
+  // And never let what it left behind hold this process open.
+  for (const stream of [child.stdout, child.stderr, child.stdin]) {
+    try {
+      stream?.destroy();
+    } catch {
+      // Nothing to close.
+    }
+  }
+  try {
+    child.unref();
+  } catch {
+    // Not every child can be unreferenced. It has been signalled either way.
+  }
+}

package/src/v2/adapters/contract.js

@@ -611,11 +611,21 @@ export function undoOurFootprint(text, footprint) {
  * @returns {{text: string, truncated: boolean, bytes: number}}
  */
 export function trimForStorage(text, limit = 64 * 1024) {
-  const bytes = Buffer.byteLength(text, 'utf8');
-  if (bytes <= limit) return { text, truncated: false, bytes };
+  const whole = Buffer.from(String(text), 'utf8');
+  const bytes = whole.length;
+  if (bytes <= limit) return { text: String(text), truncated: false, bytes };
   const keep = Math.floor(limit / 2);
-  const head = text.slice(0, keep);
-  const tail = text.slice(-keep);
+  // Cut in BYTES, which is what the limit is counted in. This used to cut in characters, and
+  // on anything that is not plain ASCII the two are not the same number: a screenful of
+  // box-drawing or CJK is three bytes a character, so 90,000 bytes of it is only 30,000
+  // characters, both halves took the WHOLE text, and the stored value came out at 180,000
+  // bytes — the entire output twice, under a marker claiming 24,464 bytes had been left out
+  // of the middle. Three lies at once: the limit was not applied, the count was wrong, and
+  // the observation was marked not-fully-covered when in fact nothing had been dropped.
+  const headEnd = backToACharacter(whole, keep);
+  const tailStart = onToACharacter(whole, bytes - keep);
+  const head = whole.subarray(0, headEnd).toString('utf8');
+  const tail = whole.subarray(tailStart).toString('utf8');
   // The marker used to carry a COARSE size bucket, and the doc above it claimed a fingerprint
   // of the whole that was never actually computed. Both halves of that were wrong, and the
   // result was the worst thing this tool can produce: a change that happened entirely in the
@@ -636,8 +646,35 @@ export function trimForStorage(text, limit = 64 * 1024) {
   // as not fully covered, the coverage ledger states the hole, and the whole text is written
   // to the evidence folder so anybody can look.
   return {
-    text: `${head}\n... exactly ${bytes - keep * 2} bytes left out of the middle of ${bytes} ...\n${tail}`,
+    text: `${head}\n... exactly ${tailStart - headEnd} bytes left out of the middle of ${bytes} ...\n${tail}`,
     truncated: true,
     bytes,
   };
 }
+
+/**
+ * Cutting a multi-byte character in half turns it into a replacement character, which is a
+ * difference nobody made and which would then move about between runs. These two walk the cut
+ * to the nearest place a character actually starts — backwards for the head, forwards for the
+ * tail, so the two halves can never grow into each other.
+ *
+ * @param {Buffer} buffer
+ * @param {number} at
+ * @returns {number}
+ */
+function backToACharacter(buffer, at) {
+  let cut = at;
+  while (cut > 0 && (buffer[cut] & 0xC0) === 0x80) cut -= 1;
+  return cut;
+}
+
+/**
+ * @param {Buffer} buffer
+ * @param {number} at
+ * @returns {number}
+ */
+function onToACharacter(buffer, at) {
+  let cut = at;
+  while (cut < buffer.length && (buffer[cut] & 0xC0) === 0x80) cut += 1;
+  return cut;
+}

package/src/v2/adapters/electron.js

@@ -597,6 +597,20 @@ export async function openApp(opts) {
   };
 }
 
+/**
+ * A name a picture can be saved under, cut with a fingerprint of the whole on the end so two
+ * long names can never land on one file.
+ *
+ * @param {string} name
+ * @returns {string}
+ */
+function pictureName(name) {
+  const clean = String(name).replace(/[^a-zA-Z0-9._-]+/g, '-');
+  if (clean === '') return 'a-walk';
+  if (clean.length <= 60) return clean;
+  return `${clean.slice(0, 51)}-${crypto.createHash('sha256').update(clean).digest('hex').slice(0, 8)}`;
+}
+
 /**
  * Would this request leave the machine?
  *
@@ -640,6 +654,17 @@ export function asAddress(text, limit = 110) {
   return `${clean.slice(0, limit - 12)}… (${mark})`;
 }
 
+/**
+ * How much of one control's own text is kept at its address.
+ *
+ * It protects the store and the diff: a text area holding a whole document would otherwise put
+ * that document into every capture and into every sentence written about it. Two hundred bytes
+ * is enough to recognise a field by. What breaks if it is wrong is nothing silent — the two
+ * ends and the exact byte count are kept either way, so getting this number wrong makes the
+ * record bigger or smaller, never quieter.
+ */
+const CONTROL_TEXT_BYTES = 200;
+
 /**
  * The states worth writing down.
  *
@@ -665,21 +690,37 @@ const ROLES_WORTH_NOTHING = new Set(['generic', 'none', 'presentation', 'InlineT
  * identical, while a button that lost its label, went missing or went grey all show up as
  * exactly one difference each.
  *
+ * NOTHING HERE IS CUT WITHOUT SAYING SO. A control's own text used to be kept as its first
+ * two hundred characters and nothing else — no length, no fingerprint — so two builds whose
+ * text differed only past character two hundred recorded the same string and compared equal.
+ * A total, a message or an error at the end of a long field could change completely and the
+ * run would report that nothing had changed. `trimForStorage` had already solved this exactly
+ * once, for the output of a command: keep both ends and the EXACT number of bytes discarded,
+ * because a length survives normalisation while a digest of the whole text would not. It was
+ * never applied here. It is now, and what is still not covered — a change in the middle that
+ * leaves the length identical — is counted on `trimmed` and reported as a hole by the caller.
+ *
+ * The NAME is no longer cut here at all. It is part of an address, and cutting an address
+ * merges two things into one: two paragraphs sharing their first hundred and twenty
+ * characters became one address, so an edit further along either of them was invisible.
+ * `asAddress` already cuts addresses properly, leaving a fingerprint of the whole behind, and
+ * the caller passes every address through it.
+ *
  * @param {any[]} nodes    Straight from Accessibility.getFullAXTree.
  * @param {(text: string) => string} [tidy]   Rubs our own footprint out of the names.
- * @returns {{address: string, role: string, name: string, state: Record<string, string|number|boolean>}[]}
+ * @returns {{address: string, role: string, name: string, state: Record<string, string|number|boolean>, trimmed: boolean}[]}
  */
 export function readMeaning(nodes, tidy = (t) => t) {
   /** @type {Map<string, number>} */
   const seen = new Map();
-  /** @type {{address: string, role: string, name: string, state: Record<string, string|number|boolean>}[]} */
+  /** @type {{address: string, role: string, name: string, state: Record<string, string|number|boolean>, trimmed: boolean}[]} */
   const rows = [];
 
   for (const node of nodes ?? []) {
     if (!node || node.ignored) continue;
     const role = String(node.role?.value ?? '');
     if (!role || ROLES_WORTH_NOTHING.has(role)) continue;
-    const name = tidy(String(node.name?.value ?? '')).trim().replace(/\s+/g, ' ').slice(0, 120);
+    const name = tidy(String(node.name?.value ?? '')).trim().replace(/\s+/g, ' ');
 
     /** @type {Record<string, string|number|boolean>} */
     const state = {};
@@ -690,9 +731,18 @@ export function readMeaning(nodes, tidy = (t) => t) {
       if (value === undefined || value === false || value === 'false') continue;
       state[key] = typeof value === 'object' ? String(value) : value;
     }
+    let trimmed = false;
     const own = node.value?.value;
-    if (own !== undefined && own !== null && String(own) !== '') state.value = tidy(String(own)).slice(0, 200);
-    if (node.description?.value) state.described = tidy(String(node.description.value)).slice(0, 200);
+    if (own !== undefined && own !== null && String(own) !== '') {
+      const kept = trimForStorage(tidy(String(own)), CONTROL_TEXT_BYTES);
+      state.value = kept.text;
+      trimmed = trimmed || kept.truncated;
+    }
+    if (node.description?.value) {
+      const kept = trimForStorage(tidy(String(node.description.value)), CONTROL_TEXT_BYTES);
+      state.described = kept.text;
+      trimmed = trimmed || kept.truncated;
+    }
 
     // A control with no name is only worth an address when it says something else about
     // itself; an anonymous, stateless box is noise in every reading it appears in.
@@ -706,6 +756,7 @@ export function readMeaning(nodes, tidy = (t) => t) {
       role,
       name,
       state,
+      trimmed,
     });
   }
   return rows;
@@ -931,6 +982,18 @@ export function describeApp(input) {
       surface: 'electron',
     }));
   }
+  const tooLong = meaning.filter((row) => row.trimmed).length;
+  if (tooLong > 0) {
+    out.push(notCovered({
+      channel: 'meaning',
+      path: joinPath('count', id, 'controls holding more text than is kept'),
+      reason: 'too big',
+      says:
+        `${tooLong} control${tooLong === 1 ? '' : 's'} on this screen ${tooLong === 1 ? 'holds' : 'hold'} more text than is kept at one address. ` +
+        'Both ends of it are compared and so is the exact number of bytes in between, so a change to either end, or one that makes the text longer or shorter, is still caught. ' +
+        'A change buried in the middle that leaves the length exactly the same is not, and that is a hole rather than a pass.',
+    }));
+  }
   out.push(observation({
     channel: 'counters',
     path: joinPath('count', id, 'things on screen'),
@@ -1572,7 +1635,10 @@ async function takePicture(app, journey, ctx) {
     const shot = await app.browser.send('Page.captureScreenshot', { format: 'png' }, app.sessionId);
     const bytes = Buffer.from(String(shot?.data ?? ''), 'base64');
     if (bytes.length === 0) throw new Error('the app sent back an empty picture');
-    const file = path.join(ctx.evidenceDir, `${journey.name.replace(/[^a-zA-Z0-9._-]+/g, '-').slice(0, 60)}.png`);
+    // Fingerprinted rather than simply cut. Two journeys whose names agreed for sixty
+    // characters saved their pictures over each other, and the evidence offered for one
+    // finding was then a photograph of a different window, with nothing about it looking wrong.
+    const file = path.join(ctx.evidenceDir, `${pictureName(journey.name)}.png`);
     await fsp.mkdir(ctx.evidenceDir, { recursive: true });
     await fsp.writeFile(file, bytes);
     return observation({

package/src/v2/adapters/http.js

@@ -31,7 +31,6 @@
 import fsp from 'node:fs/promises';
 import net from 'node:net';
 import path from 'node:path';
-import { spawn } from 'node:child_process';
 import {
   defineAdapter, joinPath, notCovered, observation, sizeBucket, stableValue,
   howLongItTook, timeBucket, trimForStorage, undoOurFootprint,
@@ -40,6 +39,7 @@ import {
   compareTrees, copyForScratch, frozenEnvironment, readWatcher, snapshotTree, watcherScript,
 } from './process.js';
 import { readContract, readFileRoutes } from './source.js';
+import { spawnServer, stopServer } from './child.js';
 
 // ---------------------------------------------------------------------------
 // Headers
@@ -371,7 +371,13 @@ export const httpAdapter = defineAdapter({
         surface: 'server',
         from: route.file,
         channels: ['results', 'complaints', 'effects', 'counters'],
-        steps: [{ act: 'request', method, route: route.name, url, unfilled }],
+        // `door` and `doorDetail` are how the coverage ledger learns that this journey walked
+        // that route. Without them a route counted as opened only if an observation happened to
+        // land at its own address, and this adapter writes its observations under `api.<journey
+        // name>` — so every route on every server read as never walked, on runs that had just
+        // asked the server for all of them. The verb is part of it: GET /basket and POST
+        // /basket are two doors.
+        steps: [{ act: 'request', method, route: route.name, url, unfilled, door: route.name, kind: 'route', doorDetail: route.detail ?? method }],
         // A route that changes something is walked — against a restored fixture, that is
         // the whole point. Only a route the project itself marks as irreversible is held
         // back, and even then only when nothing is watching to refuse the effect.
@@ -389,7 +395,10 @@ export const httpAdapter = defineAdapter({
         surface: 'server',
         from: 'the project config',
         channels: ['results', 'complaints', 'effects', 'counters'],
-        steps: [{ act: 'request', method: String(extra.method ?? 'GET'), route: String(extra.url), url, unfilled, headers: extra.headers, body: extra.body }],
+        // A request written by hand in the settings names its own route, so it opens the same
+        // door the code reader found — as long as the url is the route's pattern rather than a
+        // filled-in one, which is the shape the settings ask for.
+        steps: [{ act: 'request', method: String(extra.method ?? 'GET'), route: String(extra.url), url, unfilled, headers: extra.headers, body: extra.body, door: String(extra.route ?? extra.url), kind: 'route', doorDetail: String(extra.method ?? 'GET') }],
         irreversible: extra.irreversible === true,
       });
     }
@@ -447,7 +456,7 @@ export const httpAdapter = defineAdapter({
         notes.push(verdict.why);
       } else {
         const result = await new Promise((resolve) => {
-          const child = spawn(String(config.restore), { shell: true, cwd: work, env, stdio: ['ignore', 'pipe', 'pipe'] });
+          const child = spawnServer(String(config.restore), { cwd: work, env });
           /** @type {Buffer[]} */
           const err = [];
           child.stderr?.on('data', (c) => err.push(c));
@@ -474,7 +483,7 @@ export const httpAdapter = defineAdapter({
     /** @type {Buffer[]} */
     const bootOut = [];
     let exited = /** @type {string|null} */ (null);
-    const child = spawn(String(config.start), { shell: true, cwd: work, env, stdio: ['ignore', 'pipe', 'pipe'] });
+    const child = spawnServer(String(config.start), { cwd: work, env });
     child.stdout?.on('data', (c) => bootOut.push(c));
     child.stderr?.on('data', (c) => bootErr.push(c));
     child.on('close', (code, signal) => {
@@ -487,11 +496,11 @@ export const httpAdapter = defineAdapter({
     });
 
     if (!up.up) {
-      child.kill('SIGTERM');
+      await stopServer(child);
       return {
         build, root: work, ready: false,
         why: `${up.why} What it printed while trying: ${trimForStorage(Buffer.concat(bootErr).toString('utf8') || Buffer.concat(bootOut).toString('utf8'), 1500).text || '(nothing)'}`,
-        dispose: async () => { child.kill('SIGKILL'); await fsp.rm(base, { recursive: true, force: true }); },
+        dispose: async () => { await stopServer(child); await fsp.rm(base, { recursive: true, force: true }); },
       };
     }
 
@@ -513,9 +522,7 @@ export const httpAdapter = defineAdapter({
         if (!held) return;
         // Only ever the process we started. Somebody else's server on this machine is
         // somebody else's business.
-        held.child.kill('SIGTERM');
-        await new Promise((r) => setTimeout(r, 500));
-        if (held.child.exitCode === null) held.child.kill('SIGKILL');
+        await stopServer(held.child);
         await fsp.rm(base, { recursive: true, force: true });
       },
     };
@@ -603,7 +610,7 @@ export const httpAdapter = defineAdapter({
 
   async teardown() {
     for (const [, held] of running) {
-      held.child.kill('SIGTERM');
+      await stopServer(held.child);
     }
     running.clear();
   },