staysfixed 0.11.1 → 0.13.0

package/src/v2/doctor.js

@@ -39,6 +39,8 @@ import { surveyBrowsers, INSTALL_COMMAND, PORT_NEVER_USE } from './browsers.js';
 import { POWERSHELL_PATHS, describeRemote } from './remote.js';
 import { deviceToMake } from './adapters/android.js';
 import { describeWindows } from './adapters/windows.js';
+import { describeLinuxDesktop } from './adapters/linux.js';
+import { describeMacos } from './adapters/macos.js';
 import { messageOf, EXIT } from '../core/errors.js';
 import { say, ok, warn, fail, blank, heading, paint, mark, shortPath, setLogLevel } from '../core/log.js';
 import { loadPlaywright } from './adapters/web-driver.js';
@@ -906,7 +908,7 @@ function findDesktopApp(cwd) {
  *
  * @param {string} root
  * @param {string|null} settingsText
- * @returns {Promise<{android: FoundApp|null, ios: FoundApp|null, windows: FoundApp|null}>}
+ * @returns {Promise<{android: FoundApp|null, ios: FoundApp|null, windows: FoundApp|null, linux: FoundApp|null, macos: FoundApp|null}>}
  */
 async function phoneApps(root, settingsText) {
   // Comments taken away first, for the same reason `findDesktopApp` does it: a
@@ -923,15 +925,35 @@ async function phoneApps(root, settingsText) {
   };
 
   /**
-   * A named key whose value has to look right, so one settings word cannot be mistaken for
-   * another block's.
+   * A named key looked for INSIDE one settings block, never across the whole file.
+   *
+   * `remoteExe` means "the built program on that machine" under `windows:` and exactly the
+   * same thing under `linux:`, so a flat search finds one and reports it as the other — and
+   * doctor would tell somebody with a GTK app that they have a native Windows program.
+   * Written the day the Linux surface landed, 2026-08-31, before it could be true.
+   *
+   * @param {string} block
    * @param {string} key
-   * @param {(value: string) => boolean} looksRight
+   * @param {(value: string) => boolean} [looksRight]
    * @returns {FoundApp|null}
    */
-  const namedPath = (key, looksRight) => {
-    const found = new RegExp(`["']?${key}["']?\\s*:\\s*["'\`]([^"'\`]+)["'\`]`).exec(settings);
-    return found && looksRight(found[1]) ? { where: found[1], how: `your settings name it under ${key}` } : null;
+  const inBlock = (block, key, looksRight) => {
+    const at = new RegExp(`["']?${block}["']?\\s*:\\s*\\{`).exec(settings);
+    if (!at) return null;
+    let depth = 0;
+    let end = at.index + at[0].length;
+    for (; end < settings.length; end += 1) {
+      if (settings[end] === '{') depth += 1;
+      else if (settings[end] === '}') {
+        if (depth === 0) break;
+        depth -= 1;
+      }
+    }
+    const inside = settings.slice(at.index + at[0].length, end);
+    const found = new RegExp(`["']?${key}["']?\\s*:\\s*["'\`]([^"'\`]+)["'\`]`).exec(inside);
+    if (!found) return null;
+    if (looksRight && !looksRight(found[1])) return null;
+    return { where: found[1], how: `your settings name it under ${block}.${key}` };
   };
 
   /**
@@ -974,7 +996,11 @@ async function phoneApps(root, settingsText) {
     // name one" about a project whose settings named one. Measured 2026-08-31 against a real
     // TerminalDeck.app. The value has to end in `.app` so a bare `app:` belonging to some
     // other block can never be mistaken for this one.
-    namedPath('app', (v) => v.endsWith('.app')) ??
+    // Scoped to the `ios` block, not searched across the whole file. `app` means an iPhone
+    // bundle under `ios:` and a Mac bundle under `macos:` — both end in `.app`, so a flat
+    // search finds one and announces the other. Written the day the Mac surface landed,
+    // 2026-08-31, before it could be true.
+    inBlock('ios', 'app', (v) => v.endsWith('.app')) ??
     named('xcworkspace') ??
     built(['dist', 'out', 'build', 'release'], (name) => name.endsWith('.app')) ??
     (there(path.join('ios', 'Podfile')) || readdirSafe(path.join(root, 'ios')).some((n) => n.endsWith('.xcodeproj') || n.endsWith('.xcworkspace'))
@@ -983,9 +1009,11 @@ async function phoneApps(root, settingsText) {
         ? { where: root, how: 'there is an Xcode project here, but nothing says where the built app is' }
         : null);
 
-  const windows = named('remoteExe') ?? namedPath('exe', (v) => /\.exe$/i.test(v));
+  const windows = inBlock('windows', 'remoteExe') ?? inBlock('windows', 'exe', (v) => /\.exe$/i.test(v));
+  const linux = inBlock('linux', 'remoteExe') ?? inBlock('linux', 'exe');
+  const macos = inBlock('macos', 'app', (v) => v.endsWith('.app'));
 
-  return { android, ios, windows };
+  return { android, ios, windows, linux, macos };
 }
 
 /**
@@ -1071,9 +1099,9 @@ function couldNotAsk(name, why) {
 /**
  * The platforms that arrive as an adapter of their own, and know their own requirements.
  * The built-in five are described by hand above, because they are older than this
- * mechanism and their wording is tested; these three answer for themselves.
+ * mechanism and their wording is tested; these four answer for themselves.
  */
-const ADAPTERS_THAT_ANSWER_FOR_THEMSELVES = ['android', 'ios', 'windows'];
+const ADAPTERS_THAT_ANSWER_FOR_THEMSELVES = ['android', 'ios', 'windows', 'linux', 'macos'];
 
 /**
  * Ask each separate adapter what IT is missing, in its own words.
@@ -1189,7 +1217,7 @@ async function whatThisCopyCanDrive() {
     // file that would not load, so a check on this copy is not running at all — and both
     // the command line and the MCP surface say that in their own words already.
     const why = `This copy could not be asked what it can drive: ${messageOf(e)}`;
-    for (const surface of ['android', 'ios', 'windows']) out.push({ surface, present: false, why });
+    for (const surface of ['android', 'ios', 'windows', 'linux', 'macos']) out.push({ surface, present: false, why });
   }
   return out;
 }
@@ -1550,6 +1578,7 @@ function settingsFromText(text) {
     // as a result: it could not see the machine the settings named, nor the built program,
     // so it asked for both while both were sitting in the file.
     windows: ['host', 'remoteExe', 'exe'],
+    linux: ['host', 'remoteExe', 'exe'],
   };
   for (const [block, keys] of Object.entries(wanted)) {
     const at = new RegExp(`["']?${block}["']?\\s*:\\s*\\{`).exec(clean);
@@ -1679,7 +1708,7 @@ async function findReference(root) {
  * @param {import('./browsers.js').BrowserSurvey} browsers
  * @param {{where: string, how: string}|null} desktopApp
  * @param {DriverReport[]} drivers      What this copy of the tool can drive at all.
- * @param {{android: FoundApp|null, ios: FoundApp|null, windows: FoundApp|null}} phones
+ * @param {{android: FoundApp|null, ios: FoundApp|null, windows: FoundApp|null, linux: FoundApp|null, macos: FoundApp|null}} phones
  * @param {Map<string, Need[]>} asked   What each separate adapter says IT is missing.
  * @param {{commands: number, imports: number}} [wires]
  *   What this project's own settings wire for the command-line surface. A surface with
@@ -1728,7 +1757,7 @@ function describeSurfaces(tools, hosts, configured, browsers, desktopApp, driver
     name: 'command-line tools and libraries',
     status: wiredForCli ? 'ready' : 'partial',
     summary: wiredForCli
-      ? 'Fully covered here. What it printed, what it exited with, what it wrote, what it called out to, and what it exports.'
+      ? 'What it printed, what it exited with, what it wrote, what it called out to, what it exports, and what each exported function answers when it is called with a fixed list of inputs. Not covered: any input outside that list, and any function whose name says it deletes, sends, publishes or charges — those are never called. A clean result covers what was walked; `staysfixed coverage` lists what was not.'
       : configured
         ? 'This machine can cover it in full — what a command printed, what it exited with, what it wrote, what it called out to, what it exports — but these settings wire no command to run and nothing to import, so a check runs none of it and a clean result says nothing about any of it.'
         : 'This machine can cover it in full, but nothing is set up in this folder yet, so a check cannot run here at all.',
@@ -1861,7 +1890,7 @@ function describeSurfaces(tools, hosts, configured, browsers, desktopApp, driver
         : !canDrive('android')
           ? `An Android app is here (${phones.android.how}), and this copy of Stays Fixed cannot drive one. ${noDriver('android')}`
           : androidReady
-            ? `Covered against the stored record. It installs ${phones.android.where} on a virtual device, walks it, and reads what each control on the screen is and does. Whether two emulator snapshots restore identically is still unproven, so a paired run is not offered — and the run says which mode it used.`
+            ? `Covered against the stored record. It installs ${phones.android.where} on a virtual device, walks it, and reads what each control on the screen is and does. Whether a snapshot restore repeats was measured on 2026-08-31: one build walked ten times with a restore between every walk, 301 of 309 addresses agreeing in all five pairs, and the eight that moved were the app's own freshly-made identity code — ordinary wobble, which this tool already subtracts. So a paired run is offered. It also needs a copy of the OLD build's package, because an APK is a build output that no checkout of the old commit contains: name it with {"reference": "path/to/the-old.apk"} under "android" in the settings. Without it the run falls back to the stored record and says so.`
             : androidPartly
               ? `Most of your Android app can be checked: every screen another app can reach is opened and read. What is missing is ${plainList(androidMissing)}, and without ${androidMissing.length === 1 ? 'it' : 'them'} nothing is typed, pressed or saved — so a clean result covers the screens and not what the app DOES.`
               : `An Android app is here (${phones.android.how}), and ${plainList(androidMissing)} ${androidMissing.length === 1 ? 'is' : 'are'} still missing. ${androidWants.every((n) => n.automatic) ? `${androidMissing.length === 1 ? 'It installs' : 'They all install'} without anybody clicking anything, so nobody needs to be asked.` : 'Some of it needs a person, and each one says what it is and what it unlocks.'}`,
@@ -2039,6 +2068,84 @@ function describeSurfaces(tools, hosts, configured, browsers, desktopApp, driver
   if (windowsHost && !windowsDriver) {
     impossible.set('windows', `${noDriver('windows')} Nothing you install on that machine changes it. Update Stays Fixed to a copy that has it.`);
   }
+
+  // ── native Mac apps ───────────────────────────────────────────────────────────────────
+  //
+  // No remote option here, unlike Windows and Linux: the Accessibility API only answers
+  // inside a signed-in graphical session on the machine itself, so a Mac app is checked on
+  // the Mac it is on or not at all. And one person has to allow it once — macOS will not let
+  // any program grant itself permission to read another app's window.
+  const macDriver = canDrive('macos');
+  const onAMacHere = process.platform === 'darwin';
+  const macNeeds = asked.get('macos') ?? [];
+  const macAllowed = onAMacHere && macDriver && !macNeeds.some((n) => /permission/i.test(String(n.what)));
+  const macUsable = phones.macos !== null && macAllowed;
+  surfaces.push({
+    id: 'macos',
+    name: 'native Mac apps',
+    status: macUsable ? 'ready' : 'unavailable',
+    summary: phones.macos === null
+      ? 'Nothing to check: this project names no native Mac app in its settings. Most Mac products are Electron, and those are covered over their debug port from any machine.'
+      : !onAMacHere
+        ? 'Cannot run here: a native Mac window can only be read from a Mac.'
+        : !macDriver
+          ? `A Mac app is named in the settings, and this copy of Stays Fixed cannot drive one. ${noDriver('macos')}`
+          // The adapter's own paragraph, not a second one written here. It knows whether this
+          // Mac has been allowed to read another app's window, and that changes the answer
+          // completely.
+          : describeMacos({ darwin: true, allowed: macAllowed }),
+    canCheck: macUsable ? [...withoutADriver, 'meaning', 'pixels'] : [],
+    cannotCheck: macUsable ? [] : CHANNELS.map((c) => c.id),
+    needs: onAMacHere && macDriver && phones.macos !== null ? macNeeds : [],
+  });
+  if (phones.macos === null) {
+    notInThisProject.add('macos');
+    impossible.set('macos', 'This project names no native Mac app in its settings, so there is nothing to open. If yours is built somewhere else, name the built .app under macos.app. Most Mac products are Electron, and those are covered over their debug port from any machine.');
+  } else if (!onAMacHere) {
+    impossible.set('macos', 'A native Mac window can only be read from a Mac. Everything else on this list is unaffected — check the Mac app from a Mac, and let this machine cover the rest.');
+  } else if (!macDriver) {
+    impossible.set('macos', `${noDriver('macos')} Nothing you install on this machine changes it. Update Stays Fixed to a copy that has it.`);
+  }
+
+  // ── native Linux desktop apps ─────────────────────────────────────────────────────────
+  //
+  // The project is asked before the machine, the same as everywhere else: a repository with
+  // no native Linux program named in it does not need a Linux desktop, and telling somebody
+  // to go and find one is work that changes nothing.
+  const linuxDriver = canDrive('linux');
+  const linuxHost = hosts.find((h) => h.reachable && h.windows !== true);
+  const linuxUsable = phones.linux !== null && linuxHost !== undefined && linuxDriver;
+  surfaces.push({
+    id: 'linux',
+    name: 'native Linux desktop apps',
+    status: linuxUsable ? 'partial' : 'unavailable',
+    summary: phones.linux === null
+      ? 'Nothing to check: this project names no native Linux program in its settings. Most Linux desktop products are Electron, and those are covered over their debug port from any machine.'
+      : !linuxDriver
+        ? `A native Linux program is named (${phones.linux.how}), and this copy of Stays Fixed cannot drive one. ${noDriver('linux')}`
+        : !linuxHost
+          ? nobodyWasDialled
+            ? 'No machine was dialled, so whether a Linux desktop can be reached from here is unknown. Name one under `linux: { host: "..." }` in your settings and it is asked every time, or run `staysfixed doctor --machines`.'
+            : 'No Linux desktop is reachable from here. A native Linux window can only be read from the desktop it is running on.'
+          // The adapter's own paragraph, never a second one written here — it knows whether
+          // that machine has a desktop session at all, and a summary kept in this file could
+          // only guess at it.
+          : linuxHost.detail
+            ? describeLinuxDesktop(linuxHost.detail)
+            : `A Linux machine answers through "${linuxHost.name}". A native Linux app is read through the accessibility bus every screen reader already uses, and nothing has to be installed there.`,
+    canCheck: linuxUsable ? withoutADriver : [],
+    cannotCheck: linuxUsable ? ['meaning', 'pixels'] : CHANNELS.map((c) => c.id),
+    needs: linuxUsable ? (asked.get('linux') ?? []) : [],
+  });
+  if (phones.linux === null) {
+    notInThisProject.add('linux');
+    impossible.set(
+      'linux',
+      'This project has no native Linux program named in its settings, so there is nothing to open on a Linux desktop. '
+      + 'If yours is built somewhere else, name it under linux.remoteExe (already on that machine) or linux.exe (copied over each run). '
+      + 'Most Linux desktop products are Electron, and those are covered over their debug port from any machine.'
+    );
+  }
   if (!windowsHost) {
     impossible.set(
       'windows',
@@ -2119,9 +2226,9 @@ function whatThisRunActuallyCovers(surfaces, setUpHere = true) {
   if (!setUpHere) {
     out.canRunHere = false;
     parts.push('Nothing is set up in this folder, so a check cannot run here at all and would cover nothing. Run `staysfixed init` first.');
-    parts.push(full.length > 0 ? `Once it is set up, this machine could cover ${plainList(out.covered)} in full.` : 'Even set up, this machine could cover nothing in full.');
+    parts.push(full.length > 0 ? `Once it is set up, this machine can drive ${plainList(out.covered)}.` : 'Even set up, this machine can drive none of these.');
   } else {
-    parts.push(full.length > 0 ? `A check here covers ${plainList(out.covered)} in full.` : 'A check here covers nothing in full.');
+    parts.push(full.length > 0 ? `A check here can drive ${plainList(out.covered)}. That is what this machine is able to walk, not what any run has walked.` : 'A check here can drive none of these.');
   }
   if (some.length > 0) parts.push(`It covers ${plainList(some.map((s) => s.name))} only partly — read the summary for each before treating a clean result as proof.`);
   if (missing.length > 0) {

package/src/v2/escalate.js

@@ -437,7 +437,7 @@ export async function rememberCheck(store, what) {
  *
  * @typedef {object} Escalation
  * @property {string} id
- * @property {'sealed'|'budget'|'unpredictable'|'blocked'|'no-reference'} kind
+ * @property {'sealed'|'difference'|'budget'|'unpredictable'|'blocked'|'no-reference'} kind
  * @property {string} what   What changed.
  * @property {string} why    Why no agent could wave it through.
  * @property {string} todo   What to do about it.
@@ -500,11 +500,26 @@ export async function escalationsFor(store, product) {
  * @returns {Escalations}
  */
 function buildEscalations(product, record, verdict) {
+  // TWO PILES, AND THE ORDER BETWEEN THEM IS THE FIX.
+  //
+  // `real` is everything that is the product behaving differently, or the check not having
+  // happened at all. `steadiness` is the one item that is neither: addresses that used to
+  // give the same answer every run and now do not. That is worth a person's attention and it
+  // is NOT a difference — nothing in it has a wrong value.
+  //
+  // WHAT WENT WRONG, 2026-08-31. A run caught one real change correctly and also measured 242
+  // addresses as newly unsteady. Only the second reached this block, because an ordinary
+  // difference has never been put in here at all — so the only sentence the owner read told
+  // him to hold the release over a wobble measurement, and never mentioned the change the
+  // tool had actually found. Piling them separately makes that ordering structural instead of
+  // accidental, and `crowdedOut` below makes sure a real change is never the thing left out.
   /** @type {Escalation[]} */
-  const items = [];
+  const real = [];
+  /** @type {Escalation[]} */
+  const steadiness = [];
 
   if (verdict.blocked === true) {
-    items.push({
+    real.push({
       id: 'blocked',
       kind: 'blocked',
       what: `Stays Fixed could not check ${product} at all on this run, so nothing about it has been proved either way.`,
@@ -512,7 +527,7 @@ function buildEscalations(product, record, verdict) {
       todo: `Something is in the way and it needs clearing — the run said: ${oneLine(verdict.summary, 200)}`,
     });
   } else if (!verdict.reference || verdict.reference.id === '') {
-    items.push({
+    real.push({
       id: 'no-reference',
       kind: 'no-reference',
       what: `There is no build of ${product} on record as working yet, so this run had nothing to compare against.`,
@@ -527,7 +542,7 @@ function buildEscalations(product, record, verdict) {
 
   for (const f of record.findings) {
     if (f.unwaivable !== true) continue;
-    items.push({
+    real.push({
       id: f.id,
       kind: 'sealed',
       what: oneLine(f.title, 220),
@@ -542,7 +557,7 @@ function buildEscalations(product, record, verdict) {
   }
 
   if (record.accounting.left === 0 && record.accounting.reported > record.accounting.unwaivable) {
-    items.push({
+    real.push({
       id: 'budget',
       kind: 'budget',
       what: `The agent has used all ${record.accounting.budget} of the differences it is allowed to record as intended on ${product}, and there are still differences left over.`,
@@ -553,7 +568,7 @@ function buildEscalations(product, record, verdict) {
 
   if (record.newlyUnstable.length > 0) {
     const n = record.newlyUnstable.length;
-    items.push({
+    steadiness.push({
       id: 'unpredictable',
       kind: 'unpredictable',
       what: `${n} ${n === 1 ? 'thing in' : 'things in'} ${product} used to give the same answer every single run and now ${n === 1 ? 'does' : 'do'} not: ${record.newlyUnstable.slice(0, 3).join(', ')}${n > 3 ? ', and more' : ''}.`,
@@ -561,15 +576,36 @@ function buildEscalations(product, record, verdict) {
       todo: 'Have it looked into before shipping. Something in the change made the product unpredictable.',
       paths: record.newlyUnstable.slice(0, 6),
     });
+    // A REAL CHANGE IS NEVER THE THING LEFT OUT.
+    //
+    // An ordinary difference is the agent's problem and does not get its own item — that is
+    // deliberate, and it stops a handful of items a month becoming a feed nobody reads. But it
+    // stops being right the moment the ONLY thing in this block is a wobble measurement,
+    // because then the sentence a person reads is an alarm about a non-difference with no
+    // mention of the difference the tool did find. So a real change gets one line here, and it
+    // goes first, exactly when it would otherwise have been the thing crowded out.
+    const crowdedOut = record.findings.filter((f) => f.waivedBy === undefined && f.unwaivable !== true);
+    if (real.length === 0 && crowdedOut.length > 0) {
+      const worst = crowdedOut[0];
+      real.push({
+        id: 'differences',
+        kind: 'difference',
+        what: `${product} behaves differently from the build you were happy with in ${crowdedOut.length} ${crowdedOut.length === 1 ? 'place' : 'places'}: ${oneLine(worst.title, 180)}${crowdedOut.length > 1 ? ', and more' : ''}.`,
+        why: 'This is a real change in the product, which is what the check is for — it is named before the steadiness note below so it cannot be read past.',
+        todo: 'The agent has to deal with each one: fix it, or record it as intended and say why. Nothing is the new normal until you ship.',
+        paths: (worst.paths ?? []).slice(0, 6),
+      });
+    }
   }
 
+  const all = [...real, ...steadiness];
   return {
     product,
     at: record.at,
-    items,
+    items: all,
     waived: record.accounting.waived,
     expiredWaivers: record.accounting.expiredWaivers,
-    note: summaryNote(product, items, record),
+    note: summaryNote(product, all, record),
   };
 }
 
@@ -595,11 +631,21 @@ function sealedTodo(f) {
  * @returns {string}
  */
 function summaryNote(product, items, record) {
+  // NOTHING NEEDING YOUR WORD IS NOT THE SAME AS NOTHING BEING WRONG.
+  //
+  // This line used to read "nothing on X needs your word" on a run that had found real
+  // differences the agent had not dealt with — true about who has to decide, and read by
+  // anybody skimming as an all-clear. One clause fixes it, and it is added rather than the
+  // sentence replaced, because who has to decide is still the thing this block is about.
+  const left = record.accounting.reported;
+  const outstanding = left > 0
+    ? ` The agent still has ${left} ${left === 1 ? 'difference' : 'differences'} of its own to deal with on this build.`
+    : '';
   if (items.length === 0) {
     const waived = record.accounting.waived;
     return waived > 0
-      ? `Stays Fixed: nothing on ${product} needs your word. ${waived} ${waived === 1 ? 'difference was' : 'differences were'} recorded as intended by the agent and ${waived === 1 ? 'is' : 'are'} waiting on your next ship.`
-      : `Stays Fixed: nothing on ${product} needs your word.`;
+      ? `Stays Fixed: nothing on ${product} needs your word.${outstanding} ${waived} ${waived === 1 ? 'difference was' : 'differences were'} recorded as intended by the agent and ${waived === 1 ? 'is' : 'are'} waiting on your next ship.`
+      : `Stays Fixed: nothing on ${product} needs your word.${outstanding}`;
   }
   return `Stays Fixed: ${items.length} ${items.length === 1 ? 'thing needs' : 'things need'} your word on ${product}.`;
 }