staysfixed 0.7.2 → 0.9.0

package/CHANGELOG.md

@@ -4,6 +4,435 @@ All notable changes to this project are recorded here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the version
 numbers follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+Nothing yet.
+
+## [0.9.0] — 2026-08-30
+
+Found the same way as 0.8.0 and one better: the published build was installed as a stranger
+installs it and used on real throwaway products — a café API, a static site, a library, a
+server that spawns its own child — until it said something untrue. And this time the repo's
+own CI was read, which had been **red for ten releases** while every summary said the tests
+passed. It was red for two real reasons, both below.
+
+**The tool was breaking the products it was sent to protect**, and on some shapes it never
+came back at all. Those two are why this release exists.
+
+### Fixed — it broke the product, or itself
+
+- **Refusing a connection killed the program that made it.** The refusal was delivered by
+  emitting `'error'` on the socket; at that instant nothing is listening, and in Node an
+  `'error'` with no listener is a thrown exception. `http.get` on Node 22 — the floor this
+  package declares — and a bare `net.connect` on every version died with exit 1, and the run
+  then reported the user's product as broken. The refusal is real now rather than simulated,
+  so the operating system produces it through Node's own plumbing.
+- **`check` printed its whole answer and never exited.** A start command runs through a
+  shell, so the server is a grandchild; killing the shell left it alive holding the output
+  pipe, so the event loop never emptied. It also orphaned the server. The shell is started as
+  its own process group now and the whole group is signalled.
+- **Two agents shipping at once lost what "working" means.** Six ships, all reporting
+  success, four records, and the "already the reference" path never firing. The whole cut is
+  one at a time per product now.
+- **Every killed run left a whole copy of the project in the temporary folder, for ever** —
+  777 MB of them on an ordinary machine. Abandoned copies are reclaimed; a copy a live run
+  owns is never touched.
+
+### Fixed — it said things that were not true
+
+- **The agent was told "everything that worked before still works"** about a run that
+  compared nothing at all, while the terminal correctly called it no answer. The engine's
+  verdict is the floor for the machine surface now, so this class cannot come back one reason
+  at a time.
+- **A sealed money change reached the agent labelled `"ordinary"`** — the human text said
+  sealed, `waive` refused it, and the JSON said it was waivable.
+- **The seal that exists because somebody was burned before could never fire.** Guard names
+  were never passed to the decision, so that class was empty on every run this tool has ever
+  done. And a check on a project with a guard in `.staysfixed/guards` printed the word
+  "guard" zero times: not run, not counted, not mentioned.
+- **A guard that asks nothing was reported as holding.** An empty `run()` came back as
+  "still holds", and would have said so every day for ever.
+- **The library journey never imported anything.** `init` writes `module: "index.js"`; the
+  probe treated that as a package name, failed identically on both builds, and the check said
+  "Nothing that worked has changed" for ever.
+- **`ship` blessed a build nothing had looked at.** It matched by git commit, so an
+  uncommitted edit resolved to an earlier build that had been checked and was clean.
+- **`doctor` said a check "here" covers things in a folder where a check cannot run at all.**
+- **`--only` printed "everything that worked still works"** about a slice.
+- **`init` and `doctor` both offered `check --paired` as the way to record a reference.** It
+  cannot; only shipping cuts one, on purpose. `doctor` also marked it as something the agent
+  could do — the single thing an agent must never do.
+- **`status` said nothing had happened** one command after a check and a ship.
+- **It called the person's own browser "a separate application from the browser you use"**,
+  which is the one case where that sentence matters and the one case it was false.
+
+### Fixed — it could not see, or would not run
+
+- **Full Chrome was invisible on Linux and Windows.** Playwright and Puppeteer both unpack
+  into `chrome-linux64` and `chrome-win64`; only macOS uses the names this looked for. On
+  Linux, the very command this tool tells people to run left a browser it could not find.
+- **`status`, `walk`, `flake`, `approve`, `mark` and `trace` told a website it had no
+  screen** — they only knew version 1's `app:`, and `init` writes version 2's `web:`.
+- **The sign-in example `init` writes used two words the tool does not know**, and a step made
+  only of unknown words was skipped in silence — so the form was never filled, every page
+  behind the login photographed the login page, and the run came back clean.
+- **A browser's throwaway profile outlived an interrupted run.**
+
+### Fixed — it was noisy or unhelpful
+
+- **Renaming one heading came back as five findings**, none of them saying "renamed". A thing
+  addressed by its own words is now recognised when it is renamed, and its children travel
+  with it.
+- **`doctor` connected to every machine in your ssh config, unasked, on the first run.** Nine
+  connections on a brand-new scratch project. It is asked for now, and the machines are still
+  listed either way.
+- **Every command-line check wrote two rows** to the log `ship` reads.
+- **The `.gitignore` lines `init` writes matched nothing version 2 writes** — 151 untracked
+  files and 1.9 MB of run evidence in `git status` after nine checks.
+- `check --json` now carries `notChecked` and `doorsNeverOpened`, which the README had
+  promised and only the MCP reply had.
+- `init` no longer names `staysfixed check --product <name>`, which is not an option.
+- The docs said the self-check builds seventeen products; it builds twenty.
+- `process.alsoWatch` is documented.
+
+## [0.8.0] — 2026-08-30
+
+The night this was pointed at itself. Everything below was found the same way:
+the published build was installed the way a stranger installs it, and used on
+throwaway products — a plain-Node server, an Express API, a Flask app, a static
+site, a Vite app, a bare Gradle project, an empty Xcode project, a CLI that
+reaches the internet three ways — until it said something untrue. Reading the
+code found none of it.
+
+**Two of them were the tool lying about itself**, which is the worst thing this
+product can do: it told every agent that asked that it could read web pages and
+then could not open one, and it reported a clean run over an entire uncovered
+HTTP surface. Both are closed.
+
+### Changed
+
+- **`staysfixed init` now runs version 2's setup.** It ran version 1's picture
+  setup until now. Version 2's `init` had been written and tested and was wired
+  to nothing — the command table deliberately left it out, on the grounds that
+  somebody might have `staysfixed init` in a setup script and would get a
+  different file. True, and not a reason: version 1's `init` writes settings for
+  photographing screens, which is not what this tool does any more, so a new
+  project got the wrong shape of file and was told it was set up. `init --json`
+  now answers with the fields `docs/getting-started.md` tells an agent to read —
+  `plan.project`, `plan.readiness`, `plan.needs.person`, `plan.journeys`,
+  `plan.covers.short`.
+
+- **`staysfixed check --watch` opens version 2's panel, not version 1's.** This
+  is the one flag whose meaning moved, and it is written down here because
+  nothing else said so. The panel draws what a difference engine finds —
+  journeys, wobble, findings, a verdict — where version 1's drew approved
+  pictures, which this tool no longer has. `--pictures --watch` and `--guards
+  --watch` still open version 1's panel over version 1's run, so the only person
+  whose command changed meaning is the one who typed `--watch` on its own.
+
+- **The scratch copy is cloned, not copied.** Every run works in a throwaway copy
+  of the project so it can write anywhere it likes without touching the real one,
+  and that copy used to be made byte by byte. On the project this was built
+  against — twelve gigabytes, most of it an iOS build folder — that is twelve
+  gigabytes of real disk per build and twenty-four per check, before a single
+  journey is walked. It now asks the filesystem to clone instead: on a Mac that is
+  one call per file that copies no bytes at all and shares the blocks until
+  something writes to them, and on Linux the same where the filesystem supports
+  it. Measured on that tree: **41.5 seconds and no bytes moved.** It falls back to
+  a real copy wherever cloning is not available, so a filesystem without it is
+  slower here and never wrong. Never a symlink and never a hardlink — both point
+  back at the real project, which is the one thing the copy exists to protect.
+
+### Added
+
+- **`process.skip` — folders to leave out of that copy.** A project can name
+  folders that are not worth copying, and a copy that takes over twenty seconds
+  now says so and points at the setting. **The bar is deliberately high: only
+  things regenerated on demand and read by nothing.** Anything skipped that turns
+  out to matter makes a run pass for the wrong reason, and a false pass is the one
+  failure this whole tool exists to prevent. It can only ever add to the built-in
+  list — `.git`, `.staysfixed`, `.turbo`, `.nyc_output`, `coverage`,
+  `.pytest_cache`, `__pycache__`, `.DS_Store` — because a setting that could
+  switch one of those back on would only ever make runs slower.
+
+- **`docs/settings.md` — every option, and what each surface needs on the machine.**
+  None of the roughly ninety settings keys the adapters read was written down
+  anywhere: the README said the reference "lives with the code it configures",
+  which is no help at all to somebody who is not going to read the code. Nor was
+  anything the code needs installed: the exact commands for Xcode, the iOS
+  runtime, the Android SDK and its emulator, and the two separate ways a browser
+  can be missing were all sitting in the source as `howToGet` strings and in none
+  of the documentation. It also names the things that quietly cost you coverage —
+  an Android Play Store image, which refuses root forever so the files an app
+  writes cannot be seen; a `web.start` or `http.start` that hard-codes its port; a
+  Windows desktop nobody is signed in to.
+
+- **The README now lists the silences that are still open,** beside the table of
+  the ones that were found and closed. A table of closed bugs on its own reads as
+  though nothing is left. Twelve rows, each with the file that would close it.
+
+- **`staysfixed browsers` is reachable.** It was written, tested, given a finished
+  command entry with a comment saying "wiring it up is one line" — and that line
+  was never written. README.md told people to run `npx staysfixed browsers` and
+  `npx staysfixed browsers --clean` to clear up after an interrupted run, and both
+  answered *"There is no command called browsers"*. Somebody whose disk was
+  filling with abandoned browser profiles had no way to clear them and no reason
+  to doubt the page telling them there was.
+
+### Fixed
+
+- **`staysfixed ship --version 0.14.0` printed `0.7.2` and shipped nothing.**
+  `--version` is a global flag meaning "print the tool's version", and it is also
+  one of `ship`'s own options meaning "the release that went out was called this".
+  The two lists were concatenated, the parser reads switches before values, so the
+  global one won: the release script got the tool's version number on standard
+  output, exit code 0, and no reference cut. A command's own flags now win any name
+  they share with a global one.
+
+- **`staysfixed walk --no-snap` answered "I do not know the option --no-snap".**
+  `--no-snap` — leave both windows where they are instead of putting them side by
+  side — was read by `walk` and declared by nobody. It is now in `walk`'s options
+  and in its help, so `docs/watching.md` saying both commands take every panel flag
+  is true again.
+
+- **The very first run on a project answered `ok: true` to a machine.** With no
+  build on record there is nothing to compare against, so the run proves nothing.
+  It said exactly that, in words, in the summary, and the command line exited 2 on
+  it — but `--json` and the MCP reply both carried `ok: true`, with no `blocked`
+  and none of the `NOTHING WAS ACTUALLY COMPARED` wording. An agent reads the
+  fields, not the sentence, so the two interfaces that matter most reported a pass
+  over a run that compared nothing. That is the exact failure this tool exists to
+  prevent, produced by the tool itself. `comparedNothing` fired only on
+  per-journey gaps, which a true cold start never records; it now fires on an
+  empty `reference.id` as well, and the rest of the codebase was swept for the
+  same shape — `ok` computed from "were there findings" rather than from "was
+  anything compared at all".
+
+- **The README said a fresh install pulls two packages under a megabyte.** It
+  pulls three: `playwright-core` became a runtime dependency, which is the browser
+  driver without a browser in it — about 13MB, and still nothing that takes
+  minutes. The install section now says what actually happens, including that a
+  browser already on the machine is found and used before anything is downloaded,
+  and that a project already using the full `playwright` is never asked for a
+  second copy of the same driver.
+
+- **`staysfixed check --guards-only` does not exist and never did.**
+  `docs/guards.md` had told people to run it since it was written. The flag is
+  `--guards`.
+
+- **`staysfixed rules` and `staysfixed browsers` were both named in the README and
+  neither existed.** `browsers` has been wired up; there is no `rules` command, so
+  the README now says where the rules actually are — one file,
+  `.staysfixed/rules.json`, read like any other file in a pull request.
+
+- **`--watch-width 100` is refused, not quietly widened.** `docs/watching.md` said
+  anything under 240 or over 900 was brought back to the nearest of the two. Under
+  240 is an error with a message; over 900 is brought down.
+
+- **`--profile` prints nothing on a difference-engine check.** It works on
+  `staysfixed walk` and on the version 1 picture check. The flag is accepted by the
+  new check and the timings are not kept, so `docs/watching.md` no longer claims
+  otherwise.
+
+- **`staysfixed doctor --json` does not fill the project path into its MCP wiring
+  block** — `staysfixed init --json` does. `docs/mcp.md` had said both did.
+
+- **`docs/design-v2.md` named four tools that were never used.** It is a plan
+  rather than a description and says so at the top, but it is also the only
+  per-platform prose in the repository, and it told anybody reading it that
+  Android needs Appium, UiAutomator2 and a Java runtime, iOS needs WebDriverAgent
+  and Windows needs a .NET probe built on FlaUI. None of those is used. What
+  shipped needs none of them, and the section now says so before the list rather
+  than after it.
+
+- **`--color` was accepted by every command and did nothing.** Colour is settled
+  before anything else loads, so by the time a command is parsed the answer is
+  already fixed and nothing on the command line could turn it back on. `--no-color`
+  works and always did — it is handled first thing, before the logging module
+  decides. `--color` has been taken away rather than left as a switch that turns
+  nothing on.
+
+### Added — products it could not see before
+
+- **A hand-written `node:http` server is read.** A product with `createServer`, a
+  chain of `req.url === '/x'` and `.listen(PORT)` was reported as "one thing: the
+  `notes` command", found zero routes, left the `http` block commented out, and
+  said **"a check here covers the `notes` command in full. Nothing is being left
+  out."** over an entire uncovered surface. The same product written with Express
+  was handled perfectly, so the machinery worked and the reading stopped at
+  frameworks. Eight hand-rolled routing shapes are now read — `req.url === '/x'`,
+  `.startsWith`, a `switch` on a pathname, `new URL(req.url, base).pathname`,
+  `url.parse`, the `split('?')[0]` variant, `if`/`else if` chains, and a path held
+  in a constant — and a method is claimed only where the code checks one, `ANY`
+  otherwise, never `GET`.
+
+- **Python products are checkable.** A Flask app was told "a Python project is not
+  being checked… in a language nothing here drives". The honesty was right and the
+  conclusion was wrong: the two adapters that would run it read no source at all.
+  The process adapter runs a command and compares what it printed, exited with and
+  touched; the http adapter boots a server and asks it for routes. Flask, FastAPI
+  (including an `APIRouter` prefix) and Django `urlpatterns` are now read, and
+  their path parameters become the same "somebody has to give a real value" flow
+  every other route uses. Go, Rust, Ruby and PHP get the boot and the command
+  without the routes — and every one of them says, **by name**, that the source
+  channel is blind for that language, so none can reach "covered in full".
+
+- **`--journeys suite` walks the project's own test suite.** It was written,
+  tested and reachable by nothing. Each test file runs twice inside the scratch
+  copy with the same frozen clock, seed and watcher as everything else, and every
+  check is reported by name, along with why each failure failed and a fingerprint
+  of the test file itself — so an edited test says plainly that the change is
+  yours. It earns its keep: take the penny-rounding out of a `total()` and the
+  product's own output does not move by one character, the discovered journeys say
+  nothing has changed, and the harvest names the check that turned red. Off unless
+  asked for, held to `suite: { budgetMs }` (90 seconds by default, `0` for none),
+  and **every file the budget did not reach is named one by one** rather than
+  summarised as "some tests were skipped".
+
+- **`keepBuilds` — how much of the record is kept.** The store grew for ever: one
+  build folder per commit, in your git history, with the function that would have
+  stopped it written and called by nothing. Three tiers now, capped by count and
+  not by age, and it refuses to remove anything at all if any record could not be
+  read.
+
+### Fixed — the tool being wrong about itself
+
+- **It could not open a single web page, and said it could.** `playwright` was
+  dropped from the dependencies on the reasonable-looking grounds that nothing
+  under `src/` imported it. Nothing does — the web adapter reaches it through
+  `await import()`, which no search for an import statement can see. So every
+  website check on a fresh install answered "Playwright is not installed, so no
+  web page can be opened", while `staysfixed_capabilities` told the calling agent
+  that web apps and sites could be checked *here and now*. The dependency is back
+  as `playwright-core` — the driver without a browser in it, 13MB and no download,
+  because this tool already knows how to find Chrome for Testing, Chrome, Edge or
+  Chromium and deliberately prefers one that is not the browser you use. A test
+  holds it in place by name, and holds `doctor` and the walk to the same answer.
+
+- **An Android project with no APK built was reported as covered in full,** and
+  then could not be walked at all. iOS already named the missing build and the
+  exact `xcodebuild` line; Android now names the Gradle one. A Tauri app read as
+  ready on any machine with no Windows host, because `doctor` returns no Windows
+  needs precisely when there is no Windows to ask about.
+
+- **Version 1 passed a page with a letter missing from its heading.** The picture
+  check's default allowed 0.05% of a picture through, described in a comment as
+  "enough for font hinting noise, nowhere near enough to hide a missing
+  stylesheet". On a 2880×1800 screenshot that is **2,592 pixels**; taking one
+  letter out of an `h1` moves **593**. The replacement was measured rather than
+  chosen — ten fresh takes of the same build differ by **zero** pixels — so the
+  default is now zero, and a project that sets `tolerance.pixels` is told, per
+  screen, how many pixels its setting just swallowed.
+
+- **The network boundary let everything out.** The watcher injected into every run
+  read the host off the first argument, but Node normalises `Socket.connect` to
+  `[options, callback]` — so the host read as an empty string, which was in the
+  loopback allow-list. `fetch`, `http.get` and `net.connect` to the open internet
+  all succeeded and the report came back empty, while the tool's loudest safety
+  claim said every outbound connection had been refused. All three are now refused
+  and recorded by host and port.
+
+- **`npm run start` died silently** — the default start command `init` writes for
+  every Node server. The watcher wrapped `process.env` in a Proxy with only `get`
+  and `has` traps, so `process.env.X = 'y'` quietly failed, npm could not pass
+  `npm_lifecycle_event` to the script, and it exited 1 without printing a word.
+  Every trap now forwards through `Reflect`, with `set` taking the target as the
+  receiver.
+
+- **Every route, and every command, read as never walked.** A door is addressed
+  `route.<VERB>.<url>` and `cli.<the command>`; the adapters wrote `api.<journey>`
+  and `cli.<journey name>`. So the coverage ledger — the one part of this tool
+  that must never be optimistic — was instead permanently and wrongly pessimistic,
+  and a genuinely uncovered door was invisible in the noise.
+
+- **A normalisation-rules caveat fired on every run, for ever.** A per-run
+  temporary folder was baked into a rule pattern and collided with the real
+  project-root rule, so the rule set contained a fresh random pattern every run —
+  and the real rule was silently deleted, meaning absolute paths under your
+  checkout were never normalised at all.
+
+- **A committed change could not be ranked.** "The change" meant the working tree
+  and nothing else, so the moment an agent committed its work — which is what an
+  agent does at the end of a task — the distance measure went blind and every
+  finding carried "nothing in the working tree has changed, so there is no edit to
+  measure this against" over a change that was perfectly well known.
+
+- **The scratch copy copied every byte.** On the project this was built against —
+  twelve gigabytes, most of it an iOS build folder — that is twelve gigabytes of
+  real disk per build and twenty-four per check. It now asks the filesystem to
+  clone: **41.5 seconds and no bytes moved**, measured on that tree. Never a
+  symlink and never a hardlink, because both point back at the project this exists
+  to protect.
+
+### Fixed — caps that decided things quietly
+
+- **A finding's nearby files were cut to five, and the sealed classes are searched
+  in that list.** A finding whose sixth file was `src/billing/refund.js` was
+  classified `ordinary` — precisely the class an agent may close on its own.
+
+- **A waiver was pinned to the first 40 differences and 20 addresses of a
+  finding.** A waiver written over a three-hundred-address finding went on
+  covering it after the value at address 41, 150 or 299 became something else.
+
+- **A wobble storm needed twelve addresses before it counted,** so ten of eleven
+  wobbling was not a storm: ten real differences subtracted, and the run passed.
+
+- **Eight address truncations with no fingerprint,** across four files. Two long
+  labels, two journey names, two log lines or two checkpoints that agreed for the
+  first 60 to 200 characters landed on one address and one of the two answers was
+  thrown away at the door. Two of them were screenshot filenames, so the picture
+  offered as evidence for a finding could be a photograph of a different screen.
+
+- **`trimForStorage` cut in characters against a byte limit.** On box-drawing or
+  CJK output, 90,000 bytes in produced 180,061 bytes stored — the whole text twice
+  — under a marker claiming 24,464 bytes had been left out of the middle.
+
+- **Files over 8MB were compared by a size bracket, not a fingerprint,** so a
+  build that wrote a different 40MB file compared equal. They are stream-hashed
+  now, and the remaining ceiling is named in the ledger.
+
+- **An adapter that did not answer in time made its surface READY.** The race
+  resolved an empty needs list, and no needs meant covered — so an Android adapter
+  hanging for sixteen seconds produced "Covered against the stored record."
+
+### Changed — words a person reads
+
+- **The watch window opened on a fifteen-line paragraph.** Its headline was right
+  and the engine's entire summary sat underneath it as one grey block. Nothing is
+  dropped — the summary is split at sentence ends, two are shown, and the rest sit
+  behind one control.
+
+- **A finding titled with the tool's own word.** A renamed route read as
+  `"declared" is gone`. Twenty-seven such words are now recognised, so it reads
+  `"/notes / declared" is gone` instead.
+
+- **A sentence that said a thing was now what it already was.** When both sides of
+  a change summarised to the same words, the summary was the wrong thing to print.
+  The flagship case now reads: *"GET /invoice / body" now has "line" reading "A
+  desk lamp ......... 49.99 GBP" where it read "A desk lamp ......... £49.99"*.
+
+- **The first error anybody meets writing a guard was raw JavaScript** —
+  `page.goto is not a function`. It now says what the object it was handed
+  actually has, in one sentence, and suggests a name only when exactly one is
+  close.
+
+- **The shipped examples were for a shape the tool no longer uses.** Both said
+  "copy this to the root of your project"; doing that today gets you a settings
+  file the difference engine rejects. Each now says which half it belongs to, and
+  points at `staysfixed init` — which beats any example, because it reads the
+  project in front of it.
+
+### Removed
+
+- **Fourteen exports nothing called.** Ten were genuinely dead. Two were missing
+  features and are now wired: `treeMovedSince`, the one thing `intent.js` promised
+  and nothing checked, and `RUNNER_KINDS`, which validated nothing while an unknown
+  runner kind was silently treated as posix. Two were kept and wired because
+  deleting them would have quietly broken a promise the documentation makes.
+
+- **`ios.suite` was advertised in a message telling somebody how to switch
+  something on.** Nothing anywhere read it.
+
 ## [0.7.2] — 2026-08-30
 
 Found the same way as 0.7.1, one step further along: install from npm into an