staysfixed 0.7.2 → 0.9.0

package/src/v2/ci.js

@@ -415,7 +415,12 @@ export async function referenceForCI(opts = {}) {
   }
 
   // ---- released ----------------------------------------------------------
-  const released = await releasedCommit(cwd, opts.product);
+  // Anything the store could not read travels with the answer and is said out loud, whether
+  // the answer was found or not. A run that says "this project has nothing on record as
+  // working" while a build folder sat there unreadable is stating a fact it does not have.
+  const releasedLook = await releasedCommit(cwd, opts.product);
+  const released = releasedLook.found;
+  const storeTrouble = releasedLook.trouble;
   if (released) {
     const found = await resolveCommit(cwd, released.sha);
     const sha = notThisBuild(found);
@@ -443,11 +448,12 @@ export async function referenceForCI(opts = {}) {
           'The fork point of this branch could not be worked out, so this was compared against the last shipped build instead. Anything else that was merged since that release will show up here as well, even though this branch did not do it.';
         result.unlockedBy = deepen;
       }
+      if (storeTrouble) result.caveat = result.caveat ? `${result.caveat} ${storeTrouble}` : storeTrouble;
       return result;
     }
-    else missed('released', `The project's reference points at ${short(released.sha)}, and that commit is not in this checkout.`, shallow ? deepen : 'Make sure the commit that was shipped is still in this repository.');
+    else missed('released', withTrouble(`The project's reference points at ${short(released.sha)}, and that commit is not in this checkout.`, storeTrouble), shallow ? deepen : 'Make sure the commit that was shipped is still in this repository.');
   } else {
-    missed('released', 'This project has no build on record as working. Only its owner can set one, by shipping.');
+    missed('released', withTrouble('This project has no build on record as working. Only its owner can set one, by shipping.', storeTrouble));
   }
 
   // ---- last tag ----------------------------------------------------------
@@ -491,7 +497,8 @@ export async function referenceForCI(opts = {}) {
   missed('previous-commit', 'There is no earlier commit in this checkout.', shallow ? deepen : undefined);
 
   // ---- stored record -----------------------------------------------------
-  const stored = await storedRecord(cwd, opts.product);
+  const storedLook = await storedRecord(cwd, opts.product);
+  const stored = storedLook.found;
   if (stored) {
     considered.push({ mode: 'stored-record', available: true, why: `There are stored observations for ${stored.buildId}.` });
     const same = stored.machine === 'same';
@@ -513,9 +520,14 @@ export async function referenceForCI(opts = {}) {
       machine: stored.machine,
     };
   }
-  missed('stored-record', 'There are no stored observations in this checkout either.', 'Commit the .staysfixed folder, or restore it from a cache written by a job on your main branch.');
+  missed('stored-record', withTrouble('There are no stored observations in this checkout either.', storedLook.trouble), 'Commit the .staysfixed folder, or restore it from a cache written by a job on your main branch.');
 
   // ---- nothing -----------------------------------------------------------
+  // The last line of this file is the one that says a whole checkout holds nothing to
+  // compare against, and it is read as final. It must not be said over the top of a store
+  // that was sitting right there with records nobody could open, so whatever the two looks
+  // in the store could not see is repeated here where a person will actually meet it.
+  const blindSpots = [storeTrouble, storedLook.trouble].filter((t) => t !== '');
   return {
     mode: 'none',
     against: null,
@@ -523,13 +535,27 @@ export async function referenceForCI(opts = {}) {
     strength: 'none',
     how: 'Nothing was found to compare against.',
     why: 'No named commit, no pull request base, no reference, no tag, no earlier commit and no stored record. There is nothing in this checkout that says what this product used to do.',
-    caveat: 'This run proves nothing about your product either way. It is not a pass.',
-    unlockedBy: deepen,
+    caveat:
+      blindSpots.length === 0
+        ? 'This run proves nothing about your product either way. It is not a pass.'
+        : `This run proves nothing about your product either way. It is not a pass. AND IT COULD NOT SEE EVERYTHING THERE IS: ${[...new Set(blindSpots)].join(' ')}`,
+    unlockedBy: blindSpots.length === 0 ? deepen : `${deepen} And repair or delete the build records named above, so the next run can read them.`,
     considered,
     shallow,
   };
 }
 
+/**
+ * Add what could not be seen to a sentence about what was not found.
+ *
+ * @param {string} said
+ * @param {string} trouble
+ * @returns {string}
+ */
+function withTrouble(said, trouble) {
+  return trouble ? `${said} ${trouble}` : said;
+}
+
 /**
  * The commit this branch forked from.
  *
@@ -585,6 +611,19 @@ async function findMergeBase(cwd, ci) {
   return null;
 }
 
+/**
+ * What a look in the store found, and what it could not see while looking.
+ *
+ * `trouble` is empty almost always. It carries a sentence when a build folder had to be
+ * skipped, or when the store would not open at all — and that sentence has to travel,
+ * because both of those turn "this project has nothing on record as working" into a claim
+ * the code is in no position to make. The build being asked for may well be one of the ones
+ * that could not be read.
+ *
+ * @template T
+ * @typedef {{found: T|null, trouble: string}} LookedInTheStore
+ */
+
 /**
  * The commit this project's own reference points at — the build somebody shipped.
  *
@@ -592,23 +631,35 @@ async function findMergeBase(cwd, ci) {
  *
  * @param {string} cwd
  * @param {string} [product]
- * @returns {Promise<{sha: string, note: string}|null>}
+ * @returns {Promise<LookedInTheStore<{sha: string, note: string}>>}
  */
 async function releasedCommit(cwd, product) {
+  /** @type {string[]} */
+  const skipped = [];
   try {
     const store = openStore({ root: cwd });
     const name = product ?? (await productName(cwd));
-    if (!name) return null;
+    if (!name) return { found: null, trouble: '' };
     const pointer = await referencePointer(store, name);
-    if (!pointer) return null;
-    const builds = await listBuilds(store, { product: name });
+    if (!pointer) return { found: null, trouble: '' };
+    // Until 2026-08-30 nothing was passed here, so a build folder that could not be read was
+    // simply not in the list — and "not in the list" is how this file spells "never existed".
+    // The build the reference pointer names is exactly the one most likely to have been
+    // written to most recently, and so exactly the one most likely to be the damaged folder.
+    const builds = await listBuilds(store, { product: name, onProblem: (m) => skipped.push(m) });
     const hit = builds.find((b) => b.fingerprint.id === pointer.buildId);
     const sha = hit?.fingerprint.gitSha ?? shaFromBuildId(pointer.buildId);
-    if (!sha) return null;
-    return { sha, note: hit?.fingerprint.version ? `version ${hit.fingerprint.version}` : '' };
-  } catch {
-    // A store that will not open is a reason to try the next mode, never a reason to fail.
-    return null;
+    if (!sha) return { found: null, trouble: troubleFrom(skipped, '') };
+    return {
+      found: { sha, note: hit?.fingerprint.version ? `version ${hit.fingerprint.version}` : '' },
+      // Named even on the way to a good answer. A reference found without the record that
+      // was supposed to describe it is a weaker answer than one found with it.
+      trouble: hit ? troubleFrom(skipped, '') : troubleFrom(skipped, `The record of build ${pointer.buildId} itself was not among them.`),
+    };
+  } catch (e) {
+    // A store that will not open is a reason to try the next mode, never a reason to fail —
+    // but it is never a reason to then say this project has nothing on record either.
+    return { found: null, trouble: troubleFrom(skipped, `The store here could not be read at all: ${messageOf(e)}`) };
   }
 }
 
@@ -617,26 +668,47 @@ async function releasedCommit(cwd, product) {
  *
  * @param {string} cwd
  * @param {string} [product]
- * @returns {Promise<{buildId: string, machine: 'same'|'different'|'unknown'}|null>}
+ * @returns {Promise<LookedInTheStore<{buildId: string, machine: 'same'|'different'|'unknown'}>>}
  */
 async function storedRecord(cwd, product) {
+  /** @type {string[]} */
+  const skipped = [];
   try {
     const store = openStore({ root: cwd });
     const name = product ?? (await productName(cwd));
-    if (!name) return null;
+    if (!name) return { found: null, trouble: '' };
     const pointer = await referencePointer(store, name);
-    const builds = await listBuilds(store, { product: name });
-    if (builds.length === 0) return null;
+    const builds = await listBuilds(store, { product: name, onProblem: (m) => skipped.push(m) });
+    if (builds.length === 0) return { found: null, trouble: troubleFrom(skipped, '') };
     const hit = (pointer && builds.find((b) => b.fingerprint.id === pointer.buildId)) || builds[0];
     const here = `${process.platform}-${process.arch}`;
     /** @type {'same'|'different'|'unknown'} */
     const machine = !hit.fingerprint.platform ? 'unknown' : hit.fingerprint.platform === here ? 'same' : 'different';
-    return { buildId: hit.fingerprint.id, machine };
-  } catch {
-    return null;
+    return { found: { buildId: hit.fingerprint.id, machine }, trouble: troubleFrom(skipped, '') };
+  } catch (e) {
+    return { found: null, trouble: troubleFrom(skipped, `The store here could not be read at all: ${messageOf(e)}`) };
   }
 }
 
+/**
+ * One sentence about what could not be seen, or nothing at all when everything could.
+ *
+ * @param {string[]} skipped
+ * @param {string} extra
+ * @returns {string}
+ */
+function troubleFrom(skipped, extra) {
+  /** @type {string[]} */
+  const parts = [];
+  if (skipped.length > 0) {
+    parts.push(
+      `${skipped.length} stored build ${skipped.length === 1 ? 'record was' : 'records were'} skipped because ${skipped.length === 1 ? 'it' : 'they'} could not be read, so what is on record here may be more than this run could see: ${skipped.join(' ')}`,
+    );
+  }
+  if (extra) parts.push(extra);
+  return parts.join(' ');
+}
+
 // ---------------------------------------------------------------------------
 // The report
 // ---------------------------------------------------------------------------
@@ -816,23 +888,31 @@ function findingLines(f) {
 /**
  * Append the report to the job summary, when the build server has one.
  *
- * Returns the file it wrote to, or null when there is nowhere to write. Null is a normal
- * answer on GitLab and CircleCI, neither of which has a summary page.
+ * TWO ANSWERS THAT USED TO BE ONE NULL. "This server has no summary page" is the normal
+ * state on GitLab and CircleCI and needs saying to nobody. "This server HAS one and the
+ * report did not reach it" is a report that has vanished — the person opens the job, sees
+ * the tab they expect, finds nothing under it, and concludes the check did not run. Both
+ * came back as null, so nothing anywhere could tell them apart or mention the second.
+ *
+ * The exit code is untouched either way. Losing the page must never cost the half that
+ * actually stops the merge.
  *
  * @param {CIReport} report
  * @param {CIEnvironment} [env]
- * @returns {Promise<string|null>}
+ * @returns {Promise<{file: string|null, why: string}>}  `why` is empty unless there was a
+ *   page to write to and writing failed.
  */
 export async function writeJobSummary(report, env) {
   const where = (env ?? detectCI()).summaryFile;
-  if (!where) return null;
+  if (!where) return { file: null, why: '' };
   try {
     await fsp.appendFile(where, `${report.markdown}\n`);
-    return where;
-  } catch {
-    // A summary page is a nicety. Losing it must never cost the exit code, which is the
-    // half that actually stops the merge.
-    return null;
+    return { file: where, why: '' };
+  } catch (e) {
+    return {
+      file: null,
+      why: `The report could not be written to this job's summary page (${where}): ${messageOf(e)}. The answer below is the whole of it.`,
+    };
   }
 }
 
@@ -931,12 +1011,27 @@ export async function runCI(opts = {}) {
 
   /** @type {string|null} */
   let evidence = null;
+  /** @type {string[]} */
+  const lost = [];
   try {
     evidence = await saveEvidence({ cwd, dir: opts.evidenceDir, verdict, reference, report, env: where });
-  } catch {
-    // Losing the attachment must never change the answer.
+  } catch (e) {
+    // Losing the attachment must never change the answer — and it must never be lost in
+    // silence either, because the report above says in so many words that the rest of the
+    // gaps are "in the evidence attached to this run". A run that swallowed this printed
+    // that sentence pointing at a folder that was never written.
+    lost.push(`THE EVIDENCE FOR THIS RUN WAS NOT SAVED: ${messageOf(e)} Anything the report says is in the attached evidence is not there, so what you can read above is all there is.`);
+  }
+  const summaryPage = await writeJobSummary(report, where);
+  if (summaryPage.why) lost.push(summaryPage.why);
+
+  // Onto the report itself, both shapes of it, rather than only into a log line. The
+  // markdown is what a person opens later and the text is what the job log keeps.
+  if (lost.length > 0) {
+    const said = lost.join(' ');
+    report.markdown = `${report.markdown}\n\n> **${said}**\n`;
+    report.text = `${report.text}\n${said}\n`;
   }
-  await writeJobSummary(report, where);
 
   if (opts.quiet !== true) process.stdout.write(`${report.text}\n`);
   return { exitCode: report.exitCode, report, reference, verdict, evidence };

package/src/v2/cli.js

@@ -35,7 +35,9 @@ import { escalationBlock, escalationsFor, productFor, writeEscalations } from '.
 // to mean two different things depending on which check you ran. src/cli/index.js imports
 // this file in turn; that circle is safe because nothing here touches it while either
 // module is still being evaluated.
-import { watchFlags } from '../cli/index.js';
+import { watchFlags } from '../cli/watch-flags.js';
+import { INIT_COMMANDS } from './init.js';
+import { whatWasNotChecked } from './check.js';
 
 /**
  * What comes back from a check. Everything that did not change never appears
@@ -102,35 +104,42 @@ const V1_OPTIONS = [
   ['--pictures', 'The version 1 picture check, unchanged.'],
   ['--guards', 'The version 1 guards, unchanged.'],
   ['--only <name>', 'Just this journey, screen or guard. Repeat it for several.'],
+  ['--record', 'The version 1 run that records network fixtures.'],
+  ['--report / --no-report', 'Write the version 1 HTML report. Version 1 checks only.'],
+  ['--profile', 'Print where the time went. Version 1 checks only.'],
 ];
 
 /**
- * The commands version 2 replaces, in exactly the shape `src/cli/index.js`
- * already uses for its own. Merging this over the existing table is the whole
- * of the wiring:
- *
- *     import { V2_COMMANDS } from '../v2/cli.js';
- *     Object.assign(COMMANDS, V2_COMMANDS);
- *
- * @type {Record<string, {summary: string, usage: string, describe: string, options: [string,string][], examples: string[], spec: {booleans?: string[], strings?: string[], arrays?: string[]}, load: () => Promise<{run: (ctx: any) => Promise<number>}>}>}
+ * Flags only version 1's check reads, by the name the parser knows them under.
+ *
+ * They are accepted on every `check` because the two halves share one spec — which is right,
+ * since `--pictures --profile` has to work. What was wrong is that typing one WITHOUT
+ * `--pictures` or `--guards` did nothing at all and said nothing at all: `staysfixed check
+ * --profile` ran a perfectly ordinary difference-engine check, printed no profile, and gave
+ * no hint that the flag had been ignored. A flag that is accepted and does nothing is the
+ * same lie as a flag that does not exist, and a slower one to find.
+ */
+const V1_ONLY_FLAGS = [
+  ['profile', '--profile'],
+  ['report', '--report'],
+  ['record', '--record'],
+];
+
+/**
+ * The commands version 2 contributes. `src/cli/index.js` merges these over version 1's,
+ * so `check` and `doctor` become the difference engine while everything version 1 did
+ * stays reachable behind `--pictures`, `--guards` and `--watch`.
  */
 export const V2_COMMANDS = {
-  // `staysfixed ship` comes from src/v2/ship.js. It is merged in here rather than into the
-  // version 1 command table so that wiring version 2 into the front door stays the one
-  // import it has always been.
-  //
-  // `staysfixed init` from src/v2/init.js is deliberately NOT merged in yet, and this is
-  // the same call as the MCP server: version 2's init is a BREAKING change. Version 1's
-  // init writes settings for any folder; version 2's reads the project first and writes
-  // nothing when it cannot tell what the project is, which is better and is not what the
-  // three tests in test/cli.test.js describe. Somebody installed this last week and has
-  // `staysfixed init` in a setup script. Adding one line here —
+  // Version 2's init replaces version 1's.
   //
-  //     import { INIT_COMMANDS } from './init.js';   ...INIT_COMMANDS,
-  //
-  // switches it over, and those three tests have to be rewritten in the same change to
-  // say what the new one does. That is a decision, not an oversight, and it belongs in a
-  // change of its own rather than arriving as a side effect of wiring up the phones.
+  // It was held back on the grounds that somebody might have `staysfixed init` in a
+  // setup script and would get a different file. True, and not a reason: the old one
+  // writes settings for photographing screens, which is not what this tool does any
+  // more, so leaving it in place hands a new project the wrong shape and calls it done.
+  // The three tests in test/cli.test.js were rewritten in the same change to say what
+  // the new one actually does.
+  ...INIT_COMMANDS,
   ...SHIP_COMMANDS,
 
   check: {
@@ -159,16 +168,17 @@ export const V2_COMMANDS = {
 
   doctor: {
     summary: 'What this tool can and cannot check on this machine, and what would unlock more.',
-    usage: 'staysfixed doctor [--json] [--offline] [--fix]',
+    usage: 'staysfixed doctor [--json] [--machines] [--offline] [--fix]',
     describe:
-      'Looks at this machine rather than at your project: what is installed, which other\nmachines it can already reach, what each of those lets it watch, and what exactly\nis in the way of the rest. It never asks you to set up something that already\nworks — everything it lists as missing failed a real check first.\n\n--json is the same answer as an object, and it is the first thing an agent\nshould call. --fix repairs the small things version 1 could repair.',
+      'Looks at this machine rather than at your project: what is installed, which other\nmachines it can already reach, what each of those lets it watch, and what exactly\nis in the way of the rest. It never asks you to set up something that already\nworks — everything it lists as missing failed a real check first.\n\n--json is the same answer as an object, and it is the first thing an agent\nshould call. --fix repairs the small things version 1 could repair.\n\nIt does not connect to the machines in your ssh config unless this project has a\ndesktop app that might need one, or you pass --machines. They are still listed.',
     options: [
       ['--json', 'The whole answer as one JSON object. For agents.'],
+      ['--machines', 'Also dial the machines in your ssh config, to find a runner for a desktop app.'],
       ['--offline', 'Do not dial any other machine. Faster, and reports no runners.'],
       ['--fix', 'Repair the small local things that can be repaired safely.'],
     ],
     examples: ['staysfixed doctor', 'staysfixed doctor --json'],
-    spec: { booleans: ['json', 'offline', 'fix'] },
+    spec: { booleans: ['json', 'offline', 'fix', 'machines'] },
     load: async () => ({ run: doctorRun }),
   },
 };
@@ -203,6 +213,16 @@ export async function run(ctx) {
     return await v1.run(ctx);
   }
 
+  // Say so when a flag was accepted and will do nothing.
+  //
+  // This goes to standard error, so it cannot corrupt --json, and it is a warning rather
+  // than a refusal: the person asked for a real check and they should still get one.
+  for (const [flag, written] of V1_ONLY_FLAGS) {
+    if (ctx.flags[flag] !== undefined) {
+      warn(`${written} only applies to the version 1 check. This run is the difference engine, so it was ignored — add --pictures or --guards if that is what you wanted.`);
+    }
+  }
+
   // --json means the answer belongs to a machine. Every line meant for a person
   // is switched off before anything else runs, rather than trusted not to
   // print: one stray sentence on standard output and the JSON will not parse.
@@ -225,23 +245,26 @@ export async function run(ctx) {
   // checks on the command line and then ships is told their build was "never
   // checked", and the safeguard fires on the honest case instead of the careless
   // one. The agent surface records its own; this is the command line's half.
-  try {
-    const { recordCheck } = await import('./reference.js');
-    const { openStore } = await import('./store.js');
-    await recordCheck(openStore({ root: ctx.cwd ?? process.cwd() }), {
-      buildId: verdict.candidate?.id,
-      product: verdict.product,
-      ok: verdict.ok,
-      blocked: /** @type {any} */ (verdict).blocked === true,
-      findings: verdict.findings.length,
-      by: 'staysfixed check',
-    });
-  } catch {
-    // Never let bookkeeping cost somebody the result they came for.
-  }
+  // NOT recorded again here. The engine writes this line itself, for every surface, inside
+  // `rememberCheck` — and with more in it than this ever had: what was waived, what was
+  // sealed, how much went unaccounted for. This block was added on the belief that only the
+  // agent surface recorded, so every command-line check wrote TWO near-identical rows two
+  // milliseconds apart. Measured 2026-08-30: eight rows for four checks, and `ship` reads
+  // this log to decide whether the last check was clean.
 
   if (asJson) {
-    process.stdout.write(JSON.stringify(verdict) + '\n');
+    // The README promises these as fields of their own — "a number an agent can read"
+    // rather than a sentence it has to parse — and only the MCP reply had them. So a human
+    // asking for JSON on the command line got a strictly worse answer about what was NOT
+    // checked than an agent asking over MCP, about the very same run.
+    const coverage = verdict.coverage ?? null;
+    process.stdout.write(
+      JSON.stringify({
+        ...verdict,
+        notChecked: whatWasNotChecked(coverage),
+        doorsNeverOpened: Math.max(0, (coverage?.doorsKnown ?? 0) - (coverage?.doorsWalked ?? 0)),
+      }) + '\n',
+    );
   } else {
     report(verdict);
   }