staysfixed 0.1.0 → 0.2.0

package/src/run.js

@@ -16,13 +16,14 @@ import { ensureDirs, clearResults, resultPicture, safeName } from './core/paths.
 import { gitInfo } from './core/git.js';
 import { loadHistory, saveHistory, foldRun, condemned } from './core/history.js';
 import { warn, detail, shortPath } from './core/log.js';
+import { makeTimings, emitEvent } from './core/events.js';
 import { launchApp } from './drive/launch.js';
 import { platformTag } from './drive/find.js';
 import { runPictures } from './picture/run.js';
 import { approveFromResult, listApproved } from './picture/store.js';
 import { loadGuards } from './guard/load.js';
 import { runGuards } from './guard/run.js';
-import { walkApp, writeWalkContactSheet } from './walk/run.js';
+import { walkApp, writeWalkContactSheet, countWalkSteps } from './walk/run.js';
 import { listMarkers } from './marker/mark.js';
 import { writeRunReport } from './report/html.js';
 import { printPictureResult, printGuardResult } from './report/console.js';
@@ -83,6 +84,10 @@ const LAST_RUN = 'last-run.json';
  *   onPicture?: (result: import('./types.js').PictureResult) => void,
  *   onGuard?: (result: import('./types.js').GuardResult) => void,
  *   writeReport?: boolean,
+ *   events?: import('./types.js').RunEvents,
+ *   watching?: boolean,
+ *   onApp?: (app: import('./types.js').LaunchedApp) => Promise<void>,
+ *   timings?: ReturnType<typeof makeTimings>,
  * }} [opts]
  * @returns {Promise<import('./types.js').RunSummary>}
  */
@@ -90,6 +95,12 @@ export async function runCheck(project, opts = {}) {
   const { config, paths } = project;
   const startedAt = new Date();
   const started = Date.now();
+  const events = opts.events;
+  const watching = opts.watching === true;
+  // A run always knows where its time went, whether or not anybody asked. It
+  // costs two numbers per phase, and the alternative is being unable to answer
+  // "why did that take three minutes" without running it all again.
+  const timings = opts.timings ?? makeTimings();
 
   await ensureDirs(paths);
   // Yesterday's evidence goes in the bin before today's is taken. A stale diff
@@ -117,6 +128,17 @@ export async function runCheck(project, opts = {}) {
     });
   }
 
+  emitEvent(events, {
+    type: 'run:start',
+    plan: {
+      screens: screens.length,
+      guards: guards.length,
+      app: describeApp(config.app),
+      project: path.basename(paths.root),
+      watching,
+    },
+  });
+
   const onPicture = opts.onPicture ?? (opts.quiet ? undefined : (/** @type {import('./types.js').PictureResult} */ r) => printPictureResult(r));
   const onGuard = opts.onGuard ?? (opts.quiet ? undefined : (/** @type {import('./types.js').GuardResult} */ r) => printGuardResult(r));
 
@@ -128,24 +150,41 @@ export async function runCheck(project, opts = {}) {
   // Nothing to look at means nothing to open. Starting a browser to check zero
   // screens is thirty seconds of somebody's life for no answer.
   if (screens.length > 0 || guards.length > 0) {
-    await withApp(project, async (app) => {
-      if (screens.length > 0) {
-        pictures = await runPictures(project, app, {
-          only: screens.map((s) => s.name),
-          record: opts.record ?? false,
-          retries: config.retries,
-          tool: TOOL,
-          onResult: onPicture,
-          signal: opts.signal,
-        });
-      }
-      if (guards.length > 0) {
-        guardResults = await runGuards(project, app, guards, {
-          onResult: onGuard,
-          signal: opts.signal,
-        });
-      }
-    });
+    await withApp(
+      project,
+      async (app) => {
+        if (screens.length > 0) {
+          emitEvent(events, { type: 'phase', message: 'photographing' });
+          pictures = await runPictures(project, app, {
+            only: screens.map((s) => s.name),
+            record: opts.record ?? false,
+            retries: config.retries,
+            tool: TOOL,
+            onResult: onPicture,
+            signal: opts.signal,
+            events,
+            timings,
+            // Small pictures cost time to make, so they are only made when there
+            // is a window open to show them in.
+            thumbnail: Boolean(events && watching),
+          });
+        }
+        if (guards.length > 0) {
+          emitEvent(events, { type: 'phase', message: 'running the guards' });
+          const stopGuards = timings.mark('guards');
+          try {
+            guardResults = await runGuards(project, app, guards, {
+              onResult: onGuard,
+              signal: opts.signal,
+              events,
+            });
+          } finally {
+            stopGuards();
+          }
+        }
+      },
+      { events, timings, onApp: opts.onApp },
+    );
   }
 
   const git = await gitInfo(paths.root);
@@ -171,7 +210,7 @@ export async function runCheck(project, opts = {}) {
 
   const totals = countUp(pictures, guardResults);
 
-  /** @type {import('./types.js').RunSummary} */
+  /** @type {import('./types.js').RunSummary & {timings?: import('./types.js').Timings}} */
   const summary = {
     id: runId(startedAt),
     startedAt: startedAt.toISOString(),
@@ -187,6 +226,9 @@ export async function runCheck(project, opts = {}) {
     tool: TOOL,
     platform: platformTag(),
     condemned: condemnedNames,
+    // Read here rather than at the very end: what follows is writing files, and
+    // where the run spent its time is a fact about the run, not about the report.
+    timings: timings.get(),
   };
 
   if (opts.writeReport !== false) {
@@ -204,6 +246,10 @@ export async function runCheck(project, opts = {}) {
     warn(`The run finished, but its result could not be saved for \`staysfixed status\`. ${messageOf(e)}`);
   }
 
+  // Last, so anything watching that closes on the verdict does not race the
+  // report being written.
+  emitEvent(events, { type: 'run:done', summary });
+
   return summary;
 }
 
@@ -222,7 +268,15 @@ export async function runCheck(project, opts = {}) {
  *
  * @param {import('./types.js').Project} project
  * @param {string} screenName
- * @param {{record?: boolean, retries?: number, signal?: AbortSignal, onResult?: (r: import('./types.js').PictureResult) => void}} [opts]
+ * @param {{
+ *   record?: boolean,
+ *   retries?: number,
+ *   signal?: AbortSignal,
+ *   onResult?: (r: import('./types.js').PictureResult) => void,
+ *   events?: import('./types.js').RunEvents,
+ *   watching?: boolean,
+ *   timings?: ReturnType<typeof makeTimings>,
+ * }} [opts]
  * @returns {Promise<{png: Buffer, result: import('./types.js').PictureResult, path: string}>}
  */
 export async function captureOne(project, screenName, opts = {}) {
@@ -240,17 +294,47 @@ export async function captureOne(project, screenName, opts = {}) {
 
   await ensureDirs(paths);
 
-  const results = await withApp(project, (app) =>
-    runPictures(project, app, {
-      only: [screen.name],
-      record: opts.record ?? false,
-      retries: opts.retries ?? config.retries,
-      tool: TOOL,
-      onResult: opts.onResult,
-      signal: opts.signal,
-    }),
+  const events = opts.events;
+  const watching = opts.watching === true;
+  const timings = opts.timings ?? makeTimings();
+
+  // One screen is still a run as far as anyone watching is concerned, so it
+  // describes itself the same way. This is what lets an agent's own capture be
+  // watched in the same window as a full check.
+  emitEvent(events, {
+    type: 'run:start',
+    plan: {
+      screens: 1,
+      guards: 0,
+      app: describeApp(config.app),
+      project: path.basename(paths.root),
+      watching,
+    },
+  });
+
+  const results = await withApp(
+    project,
+    (app) => {
+      emitEvent(events, { type: 'phase', message: 'photographing' });
+      return runPictures(project, app, {
+        only: [screen.name],
+        record: opts.record ?? false,
+        retries: opts.retries ?? config.retries,
+        tool: TOOL,
+        onResult: opts.onResult,
+        signal: opts.signal,
+        events,
+        timings,
+        thumbnail: Boolean(events && watching),
+      });
+    },
+    { events, timings },
   );
 
+  // Said as soon as the app is shut. What is left is reading a file off disk,
+  // and a watcher should not be left with a spinner turning through it.
+  emitEvent(events, { type: 'run:done' });
+
   const result = results[0];
   if (!result) {
     throw new StaysFixedError(`"${screen.name}" was not photographed.`, {
@@ -281,21 +365,58 @@ export async function captureOne(project, screenName, opts = {}) {
  *   signal?: AbortSignal,
  *   onStep?: (update: import('./walk/run.js').WalkProgress) => void,
  *   writeReport?: boolean,
+ *   events?: import('./types.js').RunEvents,
+ *   watching?: boolean,
+ *   onApp?: (app: import('./types.js').LaunchedApp) => Promise<void>,
+ *   timings?: ReturnType<typeof makeTimings>,
  * }} [opts]
  * @returns {Promise<import('./types.js').WalkReport>}
  */
 export async function runWalk(project, opts = {}) {
   await ensureDirs(project.paths);
 
-  const report = await withApp(project, (app) =>
-    walkApp(project, app, {
-      only: opts.only,
-      record: opts.record ?? false,
-      onStep: opts.onStep,
-      signal: opts.signal,
-    }),
+  const events = opts.events;
+  const watching = opts.watching === true;
+  // The caller's stopwatch when it brought one — `--profile` reads it back out
+  // afterwards, so a walk that quietly kept its own would print all zeros.
+  const timings = opts.timings ?? makeTimings();
+
+  emitEvent(events, {
+    type: 'run:start',
+    plan: {
+      // Counted before anything is opened so the window can draw the whole list
+      // straight away. A walk with nothing to walk through says nothing here and
+      // fails a moment later, in one place, with a sentence a person can act on.
+      screens: countWalk(project.config, opts.only),
+      guards: 0,
+      app: describeApp(project.config.app),
+      project: path.basename(project.paths.root),
+      watching,
+    },
+  });
+
+  const report = await withApp(
+    project,
+    (app) => {
+      emitEvent(events, { type: 'phase', message: 'photographing' });
+      return walkApp(project, app, {
+        only: opts.only,
+        record: opts.record ?? false,
+        onStep: opts.onStep,
+        signal: opts.signal,
+        events,
+        thumbnail: Boolean(events && watching),
+        timings,
+      });
+    },
+    { events, timings, onApp: opts.onApp },
   );
 
+  // A walk has no verdict to hand over — the pictures are the point — so this
+  // says only that it is over. Said here, with the app shut and every photo
+  // taken; the page that shows them is written after.
+  emitEvent(events, { type: 'run:done' });
+
   if (opts.writeReport === false) return report;
 
   try {
@@ -441,16 +562,43 @@ export async function approveScreens(project, names, opts = {}) {
  * Electron window left running is a leaked process on somebody's machine, and
  * the next run will fight it for the debug port.
  *
+ * `onApp` is the one hook in here. It is handed the app the moment it is open
+ * and before a single picture is taken, which is what lets the watch panel put
+ * itself beside a window that did not exist when the panel opened. It moves
+ * windows around a desk; it never touches the page, and the picture comes from
+ * the viewport the capture sets, not from the window — so where the window ends
+ * up cannot change what was photographed.
+ *
  * @template T
  * @param {import('./types.js').Project} project
  * @param {(app: import('./types.js').LaunchedApp) => Promise<T>} work
+ * @param {{
+ *   events?: import('./types.js').RunEvents,
+ *   timings?: ReturnType<typeof makeTimings>,
+ *   onApp?: (app: import('./types.js').LaunchedApp) => Promise<void>,
+ * }} [ctx]
  * @returns {Promise<T>}
  */
-async function withApp(project, work) {
-  const app = await launchApp(project);
+async function withApp(project, work, ctx = {}) {
+  emitEvent(ctx.events, { type: 'phase', message: 'opening the app' });
+  const stopLaunch = ctx.timings?.mark('launch');
+  // Stopped even when the app never opened: a launch that gave up after fifty
+  // seconds is exactly the number somebody wants to see.
+  const app = await launchApp(project).finally(() => stopLaunch?.());
+  if (ctx.onApp) {
+    try {
+      await ctx.onApp(app);
+    } catch (e) {
+      // Whatever wanted a look at the app is a spectator. A spectator that
+      // trips over must not take the run down with it, and is not worth a
+      // warning in the middle of a clean one.
+      detail(`Something watching this run could not be shown the app. ${messageOf(e)}`);
+    }
+  }
   try {
     return await work(app);
   } finally {
+    emitEvent(ctx.events, { type: 'phase', message: 'closing' });
     try {
       await app.close();
     } catch (e) {
@@ -459,6 +607,48 @@ async function withApp(project, work) {
   }
 }
 
+/**
+ * How many screens a walk will visit, or none when there is nothing to walk.
+ *
+ * @param {import('./types.js').ResolvedConfig} config
+ * @param {string|string[]} [only]
+ * @returns {number}
+ */
+function countWalk(config, only) {
+  try {
+    return countWalkSteps(config, only);
+  } catch {
+    // Nothing to walk through. The walk itself says so properly, in one place.
+    return 0;
+  }
+}
+
+/**
+ * The app being opened, in a few words: what kind it is and which one it is.
+ *
+ * A watcher shows this at the top of a narrow panel, so the whole path or the
+ * whole address would be noise — the name of the binary, or the host being
+ * opened, is what a person recognises.
+ *
+ * @param {import('./types.js').AppConfig} app
+ * @returns {string}
+ */
+function describeApp(app) {
+  if (app.kind === 'electron') {
+    const binary = app.binary ?? app.attach ?? '';
+    return binary ? `electron — ${path.basename(binary)}` : 'electron';
+  }
+  const url = app.url ?? app.attach ?? '';
+  if (!url) return 'web';
+  try {
+    // A web address has no useful last part — "/" is not a name — so the host is
+    // what gets shown: "web — localhost:5173".
+    return `web — ${new URL(url).host || url}`;
+  } catch {
+    return `web — ${url}`;
+  }
+}
+
 /**
  * Flatten both kinds of result into the one shape the flake register folds.
  * @param {PictureRunResult[]} pictures

package/src/types.js

@@ -469,3 +469,71 @@ export {};
  * @property {number} markersSearched
  * @property {string} [message]
  */
+
+// ---------------------------------------------------------------------------
+// Live events — what a run tells anyone watching, as it happens
+// ---------------------------------------------------------------------------
+
+/**
+ * One thing that happened during a run.
+ *
+ * The terminal, the watch window and any future listener all read the same stream, so a
+ * run only has to describe itself once. Every event carries `at` (milliseconds since the
+ * run began) so a watcher can draw a timeline without keeping its own clock.
+ *
+ * @typedef {object} RunEvent
+ * @property {'run:start'|'screen:start'|'screen:shot'|'screen:done'|'guard:start'|'guard:done'|'phase'|'note'|'run:done'} type
+ * @property {number} at                      Milliseconds since the run started.
+ * @property {string} [name]                  Screen or guard name.
+ * @property {string} [describe]              The plain-language description.
+ * @property {number} [index]                 1-based position within its phase.
+ * @property {number} [total]                 How many there are in this phase.
+ * @property {CheckStatus} [status]
+ * @property {number} [durationMs]
+ * @property {number} [diffPixels]
+ * @property {number} [diffRatio]
+ * @property {string} [message]
+ * @property {string} [failedAt]              The plain-language expectation that failed.
+ * @property {string} [because]               Why a guard exists.
+ * @property {string} [thumbnail]             A small JPEG as a data: URI, for watching.
+ * @property {string} [approvedThumb]
+ * @property {string} [diffThumb]
+ * @property {RunSummary} [summary]           Only on 'run:done'.
+ * @property {{screens: number, guards: number, app: string, project: string, watching: boolean}} [plan]
+ *           Only on 'run:start'.
+ */
+
+/**
+ * @typedef {object} RunEvents
+ * @property {(event: RunEvent) => void} emit
+ * @property {(listener: (event: RunEvent) => void) => () => void} on
+ * @property {() => number} elapsed
+ * @property {() => RunEvent[]} history       Everything so far, so a late listener catches up.
+ */
+
+/**
+ * @typedef {object} WatchOptions
+ * @property {boolean} [enabled]
+ * @property {number} [width]                 Panel width in CSS pixels. Default 460.
+ * @property {number} [height]                Default: as tall as the app.
+ * @property {'right'|'left'} [side]          Which side of the app to sit on. Default 'right'.
+ * @property {boolean} [keepOpen]             Leave the panel up after the run. Default true.
+ * @property {boolean} [foreground]           Bring the panel to the front. Default false.
+ * @property {boolean} [snap]                 Pin the app to a screen edge and sit flush against it. Default true.
+ * @property {'dark'|'light'|'system'} [theme]  Default 'dark'. The panel opens on a brand new browser
+ *                                          profile, and a fresh profile insists the computer is in light
+ *                                          mode however it is really set — so the look is stated, not guessed.
+ */
+
+/**
+ * Where a run spent its time. Printed by `--profile`, and drawn in the watch window.
+ * @typedef {object} Timings
+ * @property {number} launch
+ * @property {number} steps
+ * @property {number} prepare
+ * @property {number} settle
+ * @property {number} compare
+ * @property {number} guards
+ * @property {number} other
+ * @property {number} total
+ */

package/src/walk/run.js

@@ -11,10 +11,12 @@
 import fsp from 'node:fs/promises';
 import path from 'node:path';
 import { captureScreen } from '../picture/capture.js';
+import { accountForCapture } from '../picture/run.js';
 import { settingsForScreen } from '../core/config.js';
 import { gitInfo } from '../core/git.js';
 import { StaysFixedError, messageOf } from '../core/errors.js';
 import { safeName } from '../core/paths.js';
+import { emitEvent } from '../core/events.js';
 
 /**
  * Progress handed to `opts.onStep`, once when a step starts and once when it is done.
@@ -37,12 +39,16 @@ import { safeName } from '../core/paths.js';
  *   only?: string|string[],
  *   signal?: AbortSignal,
  *   record?: boolean,
+ *   events?: import('../types.js').RunEvents,
+ *   thumbnail?: boolean,
+ *   timings?: ReturnType<typeof import('../core/events.js').makeTimings>,
  * }} [opts]
  * @returns {Promise<import('../types.js').WalkReport>}
  */
 export async function walkApp(project, app, opts = {}) {
   const { config, paths } = project;
   const chosen = chooseSteps(config, opts.only);
+  const events = opts.events;
 
   const id = walkId(new Date());
   const dir = await makeWalkDir(paths.results, id);
@@ -71,15 +77,43 @@ export async function walkApp(project, app, opts = {}) {
       ...(screen.describe !== undefined ? { describe: screen.describe } : {}),
     });
 
+    // A walk goes through the same events as a check, so the live window draws a
+    // walkthrough exactly the way it draws a run of picture checks.
+    emitEvent(events, {
+      type: 'screen:start',
+      name: screen.name,
+      describe: screen.describe,
+      index,
+      total: chosen.length,
+    });
+
+    /** @type {{shot?: string}} */
+    const thumbs = {};
     const step = await walkOneStep(page, screen, {
       index,
       dir,
       settings: settingsForScreen(config, screen),
       fixturesDir: paths.fixtures,
       record: opts.record ?? false,
+      events,
+      thumbnail: opts.thumbnail === true,
+      thumbs,
+      timings: opts.timings,
     });
     steps.push(step);
 
+    emitEvent(events, {
+      type: 'screen:done',
+      name: step.name,
+      describe: step.describe,
+      // A walk has nothing to compare against, so a step either happened or it
+      // did not. Anything the app complained about is said in the message.
+      status: step.error ? 'failed' : 'passed',
+      durationMs: step.durationMs,
+      message: stepMessage(step),
+      thumbnail: thumbs.shot,
+    });
+
     opts.onStep?.({
       phase: 'done',
       index,
@@ -115,6 +149,10 @@ export async function walkApp(project, app, opts = {}) {
  *   settings: ReturnType<typeof settingsForScreen>,
  *   fixturesDir: string,
  *   record: boolean,
+ *   events?: import('../types.js').RunEvents,
+ *   thumbnail?: boolean,
+ *   thumbs?: {shot?: string},
+ *   timings?: ReturnType<typeof import('../core/events.js').makeTimings>,
  * }} ctx
  * @returns {Promise<import('../types.js').WalkStep>}
  */
@@ -136,10 +174,16 @@ async function walkOneStep(page, screen, ctx) {
     const shot = await captureScreen(page, screen, ctx.settings, {
       fixturesDir: ctx.fixturesDir,
       record: ctx.record,
+      thumbnail: ctx.thumbnail === true,
     });
+    accountForCapture(ctx.timings, shot);
     await fsp.writeFile(target, shot.png);
     file = target;
     consoleErrors = shot.consoleErrors;
+    if (shot.thumbnail) {
+      if (ctx.thumbs) ctx.thumbs.shot = shot.thumbnail;
+      emitEvent(ctx.events, { type: 'screen:shot', name: screen.name, thumbnail: shot.thumbnail });
+    }
   } catch (cause) {
     error = messageOf(cause);
     consoleErrors = readConsole(page);
@@ -173,6 +217,38 @@ async function walkOneStep(page, screen, ctx) {
   return step;
 }
 
+/**
+ * How many screens a walk is about to visit.
+ *
+ * The engine needs this before it opens anything, so it can tell a watcher how
+ * long the list will be. It asks the same function the walk itself asks, because
+ * two places counting the same thing differently is how a progress bar starts
+ * lying.
+ *
+ * @param {import('../types.js').ResolvedConfig} config
+ * @param {string|string[]} [only]
+ * @returns {number}
+ */
+export function countWalkSteps(config, only) {
+  return chooseSteps(config, only).length;
+}
+
+/**
+ * What to say about a finished step, in plain language, or nothing when it went
+ * through cleanly.
+ *
+ * @param {import('../types.js').WalkStep} step
+ * @returns {string|undefined}
+ */
+function stepMessage(step) {
+  if (step.error) return step.error;
+  const complaints = (step.consoleErrors ?? []).length;
+  if (complaints === 0) return undefined;
+  return complaints === 1
+    ? 'The app logged one error while this screen was open.'
+    : `The app logged ${complaints} errors while this screen was open.`;
+}
+
 /**
  * Which screens the walk visits: `walk.steps` when the project spelled one out,
  * otherwise every screen it already checks, in the order they are written.