staysfixed 0.1.1 → 0.2.1

package/README.md

@@ -186,6 +186,8 @@ Looked through 3 markers.
 ### And the rest
 
 ```
+staysfixed check --watch             watch the run in a panel beside your app
+staysfixed check --profile           where the time went, printed at the end
 staysfixed status                    what is set up here, and how the last check went
 staysfixed flake                     checks that have changed their mind
 staysfixed doctor                    what is missing before any of this can run
@@ -211,6 +213,27 @@ Stays Fixed
 
 ---
 
+## Watch it work
+
+A check is normally something you start and then look away from. `--watch` opens
+a slim panel beside your app and draws the run as it happens: every screen and
+guard ticking over from waiting to done, a thumbnail of each picture the moment
+it is taken, the approved one and the new one side by side for anything that
+changed, and how long each check took.
+
+```
+staysfixed check --watch
+```
+
+It opens behind whatever you are using and keeps working there, and it only
+reads the run — it never touches the app being photographed, so the pictures come
+out the same whether you watch or not. If no browser will open it, you get one
+line saying so and the run carries on without it. There is also `--profile`,
+which needs no window at all and prints where the seconds went when the run ends:
+[docs/watching.md](docs/watching.md).
+
+---
+
 ## How it keeps pictures stable
 
 A picture check is only worth having if it is silent when nothing changed. The

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "staysfixed",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Prove that what already worked still works after an agent changed the code. Picture checks, guards for fixed bugs, a pre-release walkthrough, and known-good markers — as a CLI and as an MCP server.",
   "type": "module",
   "license": "MIT",

package/src/cli/check.js

@@ -3,13 +3,24 @@
  *
  * Results are printed the moment each one lands, because a run that goes quiet
  * for two minutes feels broken. The summary at the end is the part that matters.
+ *
+ * With `--watch` the same run is also drawn in a panel beside the app. The panel
+ * is a listener and nothing more: it reads the event stream, it never touches the
+ * app being photographed, and if it fails to open the run carries on without it.
+ *
+ * The app it belongs beside is opened inside the run, so the run hands it over
+ * through `onApp` and the panel snaps itself flush against that window. Moving
+ * windows around a desk is all that is: `--no-snap` turns even that off.
  */
 
 import { loadProject } from '../core/config.js';
 import { runCheck } from '../run.js';
+import { makeEvents, makeTimings } from '../core/events.js';
+import { attachWatcher, watchOptionsFrom } from '../watch/index.js';
 import { printPictureResult, printGuardResult, printRunSummary } from '../report/console.js';
-import { setLogLevel } from '../core/log.js';
-import { EXIT } from '../core/errors.js';
+import { setLogLevel, warn } from '../core/log.js';
+import { EXIT, messageOf } from '../core/errors.js';
+import { watchFlags, watchSettings } from './index.js';
 
 /**
  * @param {import('./index.js').CliContext} ctx
@@ -24,6 +35,24 @@ export async function run(ctx) {
 
   const onlyGuards = ctx.bool('guards');
   const onlyPictures = ctx.bool('pictures');
+  const profile = ctx.bool('profile');
+
+  /**
+   * `--no-snap` is read here rather than in the shared flag reader because it is
+   * the only panel flag that says "change nothing at all", and it has to reach
+   * the panel from both commands identically.
+   * @type {import('../watch/index.js').WatchFlags}
+   */
+  const wanted = { ...watchFlags(ctx) };
+  if (ctx.flags.snap !== undefined) wanted.snap = ctx.flags.snap === true;
+
+  let watching = wanted.enabled === true;
+  if (watching && asJson) {
+    // One asks for a window to look at, the other asks for output a script can
+    // read. Saying so is better than quietly picking one.
+    warn('--watch and --json want opposite things: a window to look at, and output for a script. Carrying on without the panel.');
+    watching = false;
+  }
 
   /** Printed once, whether it arrived live or only in the summary. */
   const shown = new Set();
@@ -44,6 +73,25 @@ export async function run(ctx) {
     if (!asJson) printGuardResult(result);
   };
 
+  const events = makeEvents();
+  const timings = makeTimings();
+
+  // The panel has to be listening before the run starts, or it misses the plan
+  // and the first screen. A panel that will not open is a disappointment, never
+  // a failed check: the whole point of the run is the pictures.
+  /** @type {import('../watch/index.js').Watcher|null} */
+  let watcher = null;
+  if (watching) {
+    try {
+      watcher = await attachWatcher(events, { project, watch: watchOptionsFrom(watchSettings(project), wanted) });
+    } catch (error) {
+      watching = false;
+      warn(`The panel could not open, so the run is going ahead without it. ${messageOf(error)}`);
+    }
+  }
+  // Held as a const so the run's callback below cannot be handed a null later.
+  const panel = watcher;
+
   const opts = /** @type {any} */ ({
     only: ctx.list('only'),
     // These names are the contract runCheck reads. They were `pictures` and `guards`
@@ -55,18 +103,37 @@ export async function run(ctx) {
     writeReport: ctx.flags.report !== false && !asJson,
     onPicture: showPicture,
     onGuard: showGuard,
+    events,
+    timings,
+    // Only true when a panel really is up: it is what tells the run whether the
+    // extra work of making thumbnails is worth doing.
+    watching,
+    // How the panel meets the app: called once, the moment the app is open and
+    // before anything is photographed.
+    onApp: panel ? (/** @type {import('../types.js').LaunchedApp} */ app) => panel.snapTo(app) : undefined,
     tool: ctx.version,
   });
 
   /** @type {import('../types.js').RunSummary} */
-  const summary = await runCheck(project, opts);
+  let summary;
+  try {
+    summary = await runCheck(project, opts);
+  } finally {
+    if (watcher) {
+      try {
+        await watcher.stop();
+      } catch {
+        // A panel that will not close is not a reason to change the verdict.
+      }
+    }
+  }
 
   if (asJson) {
     process.stdout.write(JSON.stringify(summary, null, 2) + '\n');
   } else {
     for (const picture of summary.pictures ?? []) showPicture(picture);
     for (const guard of summary.guards ?? []) showGuard(guard);
-    printRunSummary(summary, project);
+    printRunSummary(summary, project, { profile, timings: profile ? timings.get() : undefined });
   }
 
   return summary.ok ? EXIT.ok : EXIT.failed;

package/src/cli/index.js

@@ -68,6 +68,25 @@ const GLOBAL_SPEC = {
 /** Flags that swallow the next word, needed before we know which command it is. */
 const GLOBAL_VALUE_FLAGS = new Set(['--config', '--cwd']);
 
+/**
+ * The live panel and the profiler. Both `check` and `walk` take them, and they
+ * are declared once here so the two commands cannot drift apart.
+ */
+const WATCH_SPEC = {
+  booleans: ['watch', 'watch-front', 'keep-open', 'profile'],
+  strings: ['watch-side', 'watch-width'],
+};
+
+/** @type {[string, string][]} */
+const WATCH_OPTIONS = [
+  ['--watch', 'Open a small panel beside your app and watch the run happen.'],
+  ['--watch-side <side>', 'Which side of the app the panel sits on: left or right. Default right.'],
+  ['--watch-width <n>', 'How wide the panel is, in pixels. Default 460.'],
+  ['--no-keep-open', 'Close the panel as soon as the run finishes.'],
+  ['--watch-front', 'Bring the panel to the front. By default it opens behind your work.'],
+  ['--profile', 'Print where the time went when the run is over.'],
+];
+
 /** @type {Record<string, CommandEntry>} */
 const COMMANDS = {
   init: {
@@ -85,7 +104,7 @@ const COMMANDS = {
   },
   check: {
     summary: 'Photograph the screens and run the guards. This is the one you run.',
-    usage: 'staysfixed check [--only <name>] [--guards] [--pictures] [--json]',
+    usage: 'staysfixed check [--only <name>] [--guards] [--pictures] [--watch] [--json]',
     describe:
       'Opens the real app, takes a picture of every screen you named, compares each one\nagainst the picture a human approved, and runs every guard. It stops on nothing:\nyou get the whole list of what changed, and the exact command to accept it.',
     options: [
@@ -95,9 +114,19 @@ const COMMANDS = {
       ['--record', 'Save the network replies this run, so later runs can replay them.'],
       ['--no-report', 'Skip writing the side-by-side HTML report.'],
       ['--json', 'Print the result as JSON and nothing else. For CI.'],
+      ...WATCH_OPTIONS,
+    ],
+    examples: [
+      'staysfixed check',
+      'staysfixed check --only sessions-empty',
+      'staysfixed check --guards',
+      'staysfixed check --watch',
     ],
-    examples: ['staysfixed check', 'staysfixed check --only sessions-empty', 'staysfixed check --guards'],
-    spec: { booleans: ['guards', 'pictures', 'record', 'report', 'json'], arrays: ['only'] },
+    spec: {
+      booleans: ['guards', 'pictures', 'record', 'report', 'json', ...WATCH_SPEC.booleans],
+      strings: [...WATCH_SPEC.strings],
+      arrays: ['only'],
+    },
     load: () => import('./check.js'),
   },
   approve: {
@@ -115,15 +144,20 @@ const COMMANDS = {
   },
   walk: {
     summary: 'Open the real app and photograph every screen, in order, before you ship.',
-    usage: 'staysfixed walk [--only <name>] [--open]',
+    usage: 'staysfixed walk [--only <name>] [--open] [--watch]',
     describe:
       'A walk is not a test. It opens the app you are about to release, visits each screen\nand photographs it into one page you can scroll — the last look before a release,\nwithout clicking through the app yourself.',
     options: [
       ['--only <name>', 'Just this screen. Repeat it for several.'],
       ['--open', 'Open the contact sheet when it is done.'],
+      ...WATCH_OPTIONS,
     ],
-    examples: ['staysfixed walk --open'],
-    spec: { booleans: ['open'], arrays: ['only'] },
+    examples: ['staysfixed walk --open', 'staysfixed walk --watch'],
+    spec: {
+      booleans: ['open', ...WATCH_SPEC.booleans],
+      strings: [...WATCH_SPEC.strings],
+      arrays: ['only'],
+    },
     load: () => import('./walk.js'),
   },
   mark: {
@@ -265,6 +299,74 @@ function contextFor(parsed, cwd, configFile) {
   };
 }
 
+/**
+ * What the panel flags on the command line asked for. Anything the person did
+ * not mention is left undefined on purpose, so the settings file still decides it.
+ *
+ * @typedef {object} WatchFlags
+ * @property {boolean} enabled          Whether --watch was asked for at all.
+ * @property {'left'|'right'} [side]
+ * @property {number} [width]
+ * @property {boolean} [keepOpen]
+ * @property {boolean} [foreground]
+ */
+
+/**
+ * Read the panel flags. Shared by `check` and `walk` so the two behave the same.
+ * @param {CliContext} ctx
+ * @returns {WatchFlags}
+ */
+export function watchFlags(ctx) {
+  /** @type {WatchFlags} */
+  const flags = { enabled: ctx.bool('watch') };
+
+  const side = ctx.str('watch-side');
+  if (side !== undefined) {
+    if (side !== 'left' && side !== 'right') {
+      throw new StaysFixedError(`--watch-side has to be left or right, not "${side}".`, {
+        hint: 'Write it as `--watch-side left` or `--watch-side right`.',
+      });
+    }
+    flags.side = side;
+  }
+
+  const width = ctx.str('watch-width');
+  if (width !== undefined) {
+    const n = Number(width);
+    // A panel narrower than this cannot show the before-and-after pictures side
+    // by side, which is the only reason to open it.
+    if (!Number.isFinite(n) || n < 240) {
+      throw new StaysFixedError(`--watch-width has to be a number of pixels, 240 or more — I got "${width}".`, {
+        hint: 'Write it as `--watch-width 520`.',
+      });
+    }
+    flags.width = Math.round(n);
+  }
+
+  // Only mention these when they were actually typed, so --no-keep-open turns the
+  // panel off at the end without a bare --watch turning it on against the settings.
+  if (ctx.flags['keep-open'] !== undefined) flags.keepOpen = ctx.flags['keep-open'] === true;
+  if (ctx.bool('watch-front')) flags.foreground = true;
+
+  return flags;
+}
+
+/**
+ * The panel settings a project's settings file carries, if it carries any.
+ *
+ * A settings file may hold a `watch` block, and the resolved config type does not
+ * describe one, so it is read through a shape that names exactly what is being
+ * looked for rather than reaching in through `any`.
+ *
+ * @param {import('../types.js').Project} project
+ * @returns {{watch?: import('../types.js').WatchOptions|boolean}}
+ */
+export function watchSettings(project) {
+  return /** @type {{watch?: import('../types.js').WatchOptions|boolean}} */ (
+    /** @type {unknown} */ (project.config ?? {})
+  );
+}
+
 /**
  * Change into `--cwd` so every relative path in the run means the same thing.
  * @param {string|boolean|string[]|undefined} value
@@ -484,6 +586,7 @@ function printHelp() {
   out('  staysfixed check                    check every screen and guard');
   out('  staysfixed approve sessions-empty   accept one new picture as correct');
   out('  staysfixed walk --open              photograph the whole app before a release');
+  out('  staysfixed check --watch            watch it work in a panel beside your app');
   out('');
   out('It answers with 0 when nothing changed, 1 when something changed or broke,');
   out('and 2 when it could not run at all.');

package/src/cli/walk.js

@@ -1,13 +1,21 @@
 /**
  * `staysfixed walk` — the last look before a release.
+ *
+ * `--watch` opens the same live panel `check` uses, which is worth more here than
+ * anywhere else: a walk is something you sit and look at. The panel snaps itself
+ * flush against the app once the walk has opened it, so the two read as one
+ * window; `--no-snap` leaves both where they are.
  */
 
 import { spawn } from 'node:child_process';
 import { loadProject } from '../core/config.js';
 import { runWalk } from '../run.js';
-import { printWalkReport } from '../report/console.js';
+import { makeEvents, makeTimings } from '../core/events.js';
+import { attachWatcher, watchOptionsFrom } from '../watch/index.js';
+import { printWalkReport, printTimings } from '../report/console.js';
 import { say, warn, paint, shortPath } from '../core/log.js';
-import { EXIT } from '../core/errors.js';
+import { EXIT, messageOf } from '../core/errors.js';
+import { watchFlags, watchSettings } from './index.js';
 
 /**
  * @param {import('./index.js').CliContext} ctx
@@ -16,10 +24,65 @@ import { EXIT } from '../core/errors.js';
 export async function run(ctx) {
   const project = await loadProject({ cwd: ctx.cwd, configFile: ctx.configFile });
 
+  const profile = ctx.bool('profile');
+
+  /**
+   * `--no-snap` is read here rather than in the shared flag reader because it is
+   * the only panel flag that says "change nothing at all", and it has to reach
+   * the panel from both commands identically.
+   * @type {import('../watch/index.js').WatchFlags}
+   */
+  const wanted = { ...watchFlags(ctx) };
+  if (ctx.flags.snap !== undefined) wanted.snap = ctx.flags.snap === true;
+
+  let watching = wanted.enabled === true;
+
+  const events = makeEvents();
+  const timings = makeTimings();
+
+  // Listening has to start before the walk does, or the panel misses the first
+  // screen. It never gets to stop the walk: a panel is a nice-to-have.
+  /** @type {import('../watch/index.js').Watcher|null} */
+  let watcher = null;
+  if (watching) {
+    try {
+      watcher = await attachWatcher(events, { project, watch: watchOptionsFrom(watchSettings(project), wanted) });
+    } catch (error) {
+      watching = false;
+      warn(`The panel could not open, so the walk is going ahead without it. ${messageOf(error)}`);
+    }
+  }
+  // Held as a const so the walk's callback below cannot be handed a null later.
+  const panel = watcher;
+
   /** @type {import('../types.js').WalkReport} */
-  const report = await runWalk(project, /** @type {any} */ ({ only: ctx.list('only'), tool: ctx.version }));
+  let report;
+  try {
+    report = await runWalk(
+      project,
+      /** @type {any} */ ({
+        only: ctx.list('only'),
+        events,
+        timings,
+        watching,
+        // How the panel meets the app: called once, the moment the app is open
+        // and before anything is photographed.
+        onApp: panel ? (/** @type {import('../types.js').LaunchedApp} */ app) => panel.snapTo(app) : undefined,
+        tool: ctx.version,
+      }),
+    );
+  } finally {
+    if (watcher) {
+      try {
+        await watcher.stop();
+      } catch {
+        // A panel that will not close is not a reason to change the verdict.
+      }
+    }
+  }
 
   printWalkReport(report);
+  if (profile) printTimings(timings.get(), (report.steps ?? []).length);
 
   const sheet = report.reportFile || report.dir;
   if (ctx.bool('open')) {

package/src/core/events.js

@@ -0,0 +1,199 @@
+/**
+ * What a run says about itself while it is happening.
+ *
+ * A run used to tell the terminal what it was doing and tell nobody else, so
+ * anything that also wanted to watch — the live window, and whatever comes after
+ * it — had to be threaded through the engine as another callback. Instead a run
+ * now describes itself once, into this stream, and anyone who cares listens.
+ *
+ * Two rules hold the whole thing up. A listener that throws must never break the
+ * run: watching is a convenience, and a convenience that can take down a check is
+ * not worth having. And a listener that arrives late is handed everything that
+ * already happened, in order, which is what lets a window open in the middle of a
+ * run and still draw the screens that were photographed before it opened.
+ */
+
+import { pathToFileURL } from 'node:url';
+import { detail } from './log.js';
+import { messageOf } from './errors.js';
+
+/** @typedef {import('../types.js').RunEvent} RunEvent */
+/** @typedef {import('../types.js').RunEvents} RunEvents */
+/** @typedef {import('../types.js').Timings} Timings */
+
+/**
+ * An event on its way in. Everything a `RunEvent` carries except `at`, which the
+ * stream stamps, so no caller has to hold a clock of its own.
+ * @typedef {Omit<RunEvent, 'at'> & {at?: number}} DraftEvent
+ */
+
+/**
+ * The parts of a run whose time we can name. `other` and `total` are worked out
+ * at the end rather than measured, so they can never disagree with the rest.
+ * @typedef {'launch'|'steps'|'prepare'|'settle'|'compare'|'guards'} TimingKey
+ */
+
+/**
+ * A fresh event stream. One per run.
+ *
+ * @returns {RunEvents}
+ */
+export function makeEvents() {
+  const born = process.hrtime.bigint();
+  /** @type {RunEvent[]} */
+  const history = [];
+  /** @type {Set<(event: RunEvent) => void>} */
+  const listeners = new Set();
+
+  /** @returns {number} Milliseconds since this stream was made. */
+  function elapsed() {
+    return Math.round(Number(process.hrtime.bigint() - born) / 1e6);
+  }
+
+  /**
+   * Hand one event to one listener, and swallow whatever it does with it.
+   *
+   * The message goes to `detail` on purpose: a watcher misbehaving is worth
+   * knowing about when somebody asks for detail, and is never worth a warning in
+   * the middle of a clean run.
+   *
+   * @param {(event: RunEvent) => void} listener
+   * @param {RunEvent} event
+   */
+  function hand(listener, event) {
+    try {
+      listener(event);
+    } catch (e) {
+      detail(`Something watching this run failed on a "${event.type}" event. ${messageOf(e)}`);
+    }
+  }
+
+  /** @param {DraftEvent} event */
+  function emit(event) {
+    /** @type {RunEvent} */
+    const stamped =
+      typeof event.at === 'number' ? /** @type {RunEvent} */ (event) : { ...event, at: elapsed() };
+    history.push(stamped);
+    // A copy, because a listener is allowed to unsubscribe — or subscribe
+    // somebody else — while it is being called.
+    for (const listener of [...listeners]) hand(listener, stamped);
+  }
+
+  /**
+   * @param {(event: RunEvent) => void} listener
+   * @returns {() => void} Call it to stop listening.
+   */
+  function on(listener) {
+    // Catch-up first, then live. A copy again: a listener that emits while it is
+    // catching up would otherwise grow the array it is being read from.
+    for (const past of [...history]) hand(listener, past);
+    listeners.add(listener);
+    return () => {
+      listeners.delete(listener);
+    };
+  }
+
+  return { emit, on, elapsed, history: () => [...history] };
+}
+
+/**
+ * Emit, when there may be nobody to emit to.
+ *
+ * Every place in the engine that describes itself is optional — a run with no
+ * watcher is the normal case — and this keeps that from being an `if` at every
+ * call site.
+ *
+ * @param {RunEvents|undefined} events
+ * @param {DraftEvent} event
+ * @returns {void}
+ */
+export function emitEvent(events, event) {
+  if (!events) return;
+  events.emit(/** @type {RunEvent} */ (event));
+}
+
+/**
+ * A file on disk, as an address a local page can load.
+ *
+ * The watch panel is itself a local `file://` page, which means it can open the real
+ * full-resolution PNGs this run just wrote instead of a shrunken copy pasted into the
+ * event. That is the difference between a picture you can zoom into and a picture you
+ * cannot read — and it costs nothing to send, because the address is a few dozen
+ * characters and the pixels never move.
+ *
+ * Hands back `undefined` rather than a broken address for anything that is not a real
+ * path: an <img> pointed at a file that is not there draws the browser's torn-page
+ * icon, which looks like the tool is broken. Nothing at all looks like nothing at all.
+ *
+ * @param {string|undefined|null} file  An absolute path to a file that EXISTS. Callers
+ *   pass the path they have just written, or one they have just read — this function
+ *   does not touch the disk, so it cannot tell the difference itself.
+ * @returns {string|undefined}
+ */
+export function fileUrl(file) {
+  if (typeof file !== 'string' || file === '') return undefined;
+  try {
+    return pathToFileURL(file).href;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Where a run spent its time.
+ *
+ * Deliberately dumb: a few numbers added up, `process.hrtime.bigint()` for the
+ * clock, and nothing allocated while a screen is being photographed. A profiler
+ * that shows up in its own measurements is worse than no profiler.
+ *
+ * @returns {{add: (key: TimingKey, ms: number) => void, mark: (key: TimingKey) => () => void, get: () => Timings}}
+ */
+export function makeTimings() {
+  const born = process.hrtime.bigint();
+  /** @type {Record<TimingKey, number>} */
+  const spent = { launch: 0, steps: 0, prepare: 0, settle: 0, compare: 0, guards: 0 };
+
+  /**
+   * @param {TimingKey} key
+   * @param {number} ms
+   * @returns {void}
+   */
+  function add(key, ms) {
+    if (!Number.isFinite(ms) || ms <= 0) return;
+    spent[key] += ms;
+  }
+
+  /**
+   * Start the clock on one part of the run; the function it hands back stops it.
+   * @param {TimingKey} key
+   * @returns {() => void}
+   */
+  function mark(key) {
+    const from = process.hrtime.bigint();
+    return () => {
+      spent[key] += Number(process.hrtime.bigint() - from) / 1e6;
+    };
+  }
+
+  /** @returns {Timings} */
+  function get() {
+    const total = Number(process.hrtime.bigint() - born) / 1e6;
+    const named =
+      spent.launch + spent.steps + spent.prepare + spent.settle + spent.compare + spent.guards;
+    return {
+      launch: Math.round(spent.launch),
+      steps: Math.round(spent.steps),
+      prepare: Math.round(spent.prepare),
+      settle: Math.round(spent.settle),
+      compare: Math.round(spent.compare),
+      guards: Math.round(spent.guards),
+      // Everything nobody claimed: reading and writing pictures, git, the report.
+      // Clamped, because two parts of the run can overlap and the leftovers must
+      // never be printed as a negative number of milliseconds.
+      other: Math.round(Math.max(0, total - named)),
+      total: Math.round(total),
+    };
+  }
+
+  return { add, mark, get };
+}

package/src/core/paths.js

@@ -132,4 +132,11 @@ export async function clearResults(paths) {
 /**
  * The .gitignore lines a project needs. Written by `init`, checked by `doctor`.
  */
-export const GITIGNORE_LINES = ['# Stays Fixed — evidence from the last run, not the promise', '.staysfixed/results/', '.staysfixed/report.html'];
+export const GITIGNORE_LINES = [
+  '# Stays Fixed — evidence from the last run, not the promise',
+  '.staysfixed/results/',
+  '.staysfixed/report.html',
+  // Where one person dragged the watch panel on one screen. Nobody else's business,
+  // and it would otherwise turn up in their commits.
+  '.staysfixed/watch-window.json',
+];