staysfixed 0.1.0

package/src/freeze/settle.js

@@ -0,0 +1,178 @@
+/**
+ * Waiting until the screen stops moving.
+ *
+ * Everything else in the freeze layer removes a *reason* for the page to change. This is
+ * the safety net for reasons we did not think of: a late render, a font swap, a chart
+ * drawing itself, a layout that reflows once the scrollbar decides whether to exist.
+ *
+ * The rule is simple and it is the whole reason picture checks can be trusted: take the
+ * photo, take it again, and only accept it once two photos in a row agree.
+ */
+
+import { PNG } from 'pngjs';
+import { StaysFixedError } from '../core/errors.js';
+import { detail } from '../core/log.js';
+
+/**
+ * @param {import('../types.js').PageHandle} page
+ * @param {{frames?: number, intervalMs?: number, timeoutMs?: number, maxDriftPixels?: number, capture: () => Promise<Buffer>}} opts
+ * @returns {Promise<{report: import('../types.js').SettleReport, png: Buffer}>}
+ */
+export async function settle(page, opts) {
+  const frames = Math.max(1, opts.frames ?? 2);
+  const intervalMs = Math.max(0, opts.intervalMs ?? 250);
+  const timeoutMs = Math.max(0, opts.timeoutMs ?? 10_000);
+  const maxDriftPixels = Math.max(0, opts.maxDriftPixels ?? 0);
+  const capture = opts.capture;
+
+  // Host-side Date.now, not the page's — the page's clock is frozen on purpose.
+  const started = Date.now();
+
+  await waitUntilQuiet(page, Math.min(timeoutMs, 5000));
+
+  /** @type {Buffer|null} */
+  let previous = null;
+  /** @type {unknown} */
+  let lastError = null;
+  let stable = 0;
+  let attempts = 0;
+  let lastDrift = 0;
+
+  for (;;) {
+    /** @type {Buffer|null} */
+    let shot = null;
+    try {
+      shot = await capture();
+      attempts += 1;
+    } catch (e) {
+      lastError = e;
+    }
+
+    if (shot) {
+      if (!previous) {
+        stable = 1;
+        lastDrift = 0;
+      } else {
+        lastDrift = driftBetween(previous, shot);
+        stable = lastDrift <= maxDriftPixels ? stable + 1 : 1;
+      }
+      previous = shot;
+
+      if (stable >= frames) {
+        return {
+          report: { settled: true, attempts, lastDriftPixels: lastDrift, waitedMs: Date.now() - started },
+          png: shot,
+        };
+      }
+    }
+
+    if (Date.now() - started >= timeoutMs) break;
+    if (intervalMs > 0) await sleep(intervalMs);
+  }
+
+  if (!previous) {
+    // Nothing to hand back. This is the one case we do throw: a caller cannot decide
+    // anything about a photo that does not exist.
+    if (lastError instanceof Error) throw lastError;
+    throw new StaysFixedError('I could not take a picture of this screen at all.', {
+      hint: 'The window may have closed, or the app may have crashed mid-run.',
+    });
+  }
+
+  detail('settle: gave up after', String(attempts), 'tries;', String(lastDrift), 'pixels still moving');
+  return {
+    report: { settled: false, attempts, lastDriftPixels: lastDrift, waitedMs: Date.now() - started },
+    png: previous,
+  };
+}
+
+/**
+ * How many pixels differ between two photos.
+ *
+ * The fast path is the one that runs almost every time: two settled photos are byte-for-
+ * byte identical, and comparing the compressed bytes costs nothing. Only when they differ
+ * do we pay to decode both.
+ *
+ * @param {Buffer} a
+ * @param {Buffer} b
+ * @returns {number}
+ */
+function driftBetween(a, b) {
+  if (a.length === b.length && a.equals(b)) return 0;
+  try {
+    const pa = PNG.sync.read(a);
+    const pb = PNG.sync.read(b);
+    if (pa.width !== pb.width || pa.height !== pb.height) {
+      // The window resized between shots. That is movement by any definition.
+      return Number.MAX_SAFE_INTEGER;
+    }
+    const da = pa.data;
+    const db = pb.data;
+    let differing = 0;
+    for (let i = 0; i < da.length; i += 4) {
+      if (da[i] !== db[i] || da[i + 1] !== db[i + 1] || da[i + 2] !== db[i + 2] || da[i + 3] !== db[i + 3]) {
+        differing += 1;
+      }
+    }
+    return differing;
+  } catch {
+    // A truncated photo from a window that closed mid-capture. Treat it as maximum
+    // movement so we try again rather than accepting it.
+    return Number.MAX_SAFE_INTEGER;
+  }
+}
+
+/**
+ * Let the page finish what it was already doing before the first photo. Skipping this
+ * means the first two shots differ every time and the whole settle loop pays for it.
+ *
+ * @param {import('../types.js').PageHandle} page
+ * @param {number} timeoutMs
+ * @returns {Promise<void>}
+ */
+async function waitUntilQuiet(page, timeoutMs) {
+  const source = `(async () => {
+  const LIMIT = ${Math.max(0, Math.round(timeoutMs))};
+
+  if (document.readyState !== 'complete') {
+    await Promise.race([
+      new Promise(function (r) { window.addEventListener('load', r, { once: true }); }),
+      new Promise(function (r) { setTimeout(r, LIMIT); })
+    ]);
+  }
+
+  // Anything the freeze layer missed gets a short grace period to end on its own. The
+  // count is bounded rather than timed because the page clock is frozen.
+  if (typeof document.getAnimations === 'function') {
+    for (var i = 0; i < 20; i++) {
+      var running = 0;
+      try { running = document.getAnimations().length; } catch (e) { running = 0; }
+      if (running === 0) break;
+      await new Promise(function (r) { setTimeout(r, 25); });
+    }
+  }
+
+  // Two frames, not one: the first lets the browser run whatever was scheduled, the
+  // second only arrives after that work has actually been painted.
+  await new Promise(function (r) {
+    requestAnimationFrame(function () { requestAnimationFrame(function () { r(undefined); }); });
+  });
+  return true;
+})()`;
+
+  try {
+    await page.evaluate(source);
+  } catch {
+    // Not being able to ask the page is not a reason to skip the photo.
+  }
+}
+
+/**
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+function sleep(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}

package/src/guard/api.js

@@ -0,0 +1,197 @@
+/**
+ * The surface a guard is handed.
+ *
+ * Everything here exists to make a failure readable a long time after the person
+ * who wrote it has forgotten the bug. That is why assertions are a sentence plus
+ * a check, and never a bare comparison: `expect('the sidebar is hidden', ...)`
+ * fails with "expected: the sidebar is hidden", which anyone can act on.
+ */
+
+import { exec } from 'node:child_process';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import { StaysFixedError } from '../core/errors.js';
+
+/** A plain-language expectation that did not hold. */
+export class ExpectationFailed extends Error {
+  /** @param {string} claim  The sentence the guard wrote. */
+  constructor(claim) {
+    super(`expected: ${claim}`);
+    this.name = 'ExpectationFailed';
+    /** @type {string} */
+    this.claim = claim;
+  }
+}
+
+const DEFAULT_RUN_TIMEOUT = 60_000;
+
+/** Commands can print a lot; 10MB before we cut them off. */
+const MAX_OUTPUT = 10 * 1024 * 1024;
+
+/**
+ * Build the object passed to a guard's `run`.
+ *
+ * @param {import('../types.js').PageApi} page
+ * @param {import('../types.js').Project} project
+ * @returns {import('../types.js').GuardApi}
+ */
+export function makeGuardApi(page, project) {
+  const root = project.paths.root;
+
+  return {
+    page,
+    project,
+
+    /**
+     * @param {string} to
+     * @returns {Promise<void>}
+     */
+    open(to) {
+      return page.goto(to);
+    },
+
+    /**
+     * @param {string} selector
+     * @returns {Promise<void>}
+     */
+    click(selector) {
+      return page.click(selector);
+    },
+
+    /**
+     * @param {string} claim
+     * @param {() => unknown | Promise<unknown>} check
+     * @returns {Promise<void>}
+     */
+    async expect(claim, check) {
+      if (typeof claim !== 'string' || claim.trim() === '') {
+        throw new StaysFixedError('An expectation needs a sentence in front of it.', {
+          hint: 'Write it the way you would say it: expect("the sidebar is hidden", () => ...). That sentence is what a person reads when the guard fails.',
+        });
+      }
+      if (typeof check !== 'function') {
+        throw new StaysFixedError(`The expectation "${claim}" was not given anything to check.`, {
+          hint: 'Pass a function as the second argument: expect("the sidebar is hidden", async () => !(await page.visible(".sidebar"))).',
+        });
+      }
+
+      let result;
+      try {
+        result = await check();
+      } catch (cause) {
+        // A nested expectation already reads well — do not bury it in another layer.
+        if (cause instanceof ExpectationFailed) throw cause;
+        throw new Error(`while checking '${claim}': ${cause instanceof Error ? cause.message : String(cause)}`, {
+          cause,
+        });
+      }
+
+      if (isNegative(result)) throw new ExpectationFailed(claim);
+    },
+
+    /**
+     * Run a shell command. Guards that are not about the screen — a build that
+     * must still succeed, a file that must still be generated — live here.
+     *
+     * A non-zero exit is returned, never thrown: whether it means failure is the
+     * guard's decision, not ours.
+     *
+     * @param {string} cmd
+     * @param {{cwd?: string, timeoutMs?: number}} [runOpts]
+     * @returns {Promise<{code: number, stdout: string, stderr: string}>}
+     */
+    run(cmd, runOpts = {}) {
+      const cwd = runOpts.cwd ? path.resolve(root, runOpts.cwd) : root;
+      const timeoutMs = runOpts.timeoutMs ?? DEFAULT_RUN_TIMEOUT;
+
+      /** @type {Promise<{code: number, stdout: string, stderr: string}>} */
+      const finished = new Promise((resolve) => {
+        exec(
+          cmd,
+          { cwd, timeout: timeoutMs, maxBuffer: MAX_OUTPUT, encoding: 'utf8' },
+          (error, stdout, stderr) => {
+            const out = String(stdout ?? '');
+            let err = String(stderr ?? '');
+            let code = 0;
+
+            if (error) {
+              const e = /** @type {any} */ (error);
+              if (e.killed || e.signal) {
+                // 124 is what `timeout(1)` uses, so a guard can spot it.
+                code = 124;
+                err += `\n(the command was stopped after ${humanTime(timeoutMs)})`;
+              } else {
+                code = typeof e.code === 'number' ? e.code : 1;
+              }
+            }
+
+            resolve({ code, stdout: out, stderr: err });
+          },
+        );
+      });
+      return finished;
+    },
+
+    /**
+     * Read a file from the project.
+     *
+     * @param {string} file
+     * @returns {Promise<string>}
+     */
+    async read(file) {
+      const full = path.resolve(root, file);
+      const relative = path.relative(root, full);
+      // A guard belongs to one project; reading outside it makes the guard depend
+      // on whoever's machine it happens to be running on.
+      if (relative === '' || relative.startsWith('..') || path.isAbsolute(relative)) {
+        throw new StaysFixedError(`A guard can only read files inside the project, and "${file}" is outside it.`, {
+          hint: 'Use a path relative to the project root, like "package.json" or "src/app.js".',
+        });
+      }
+
+      try {
+        return await fsp.readFile(full, 'utf8');
+      } catch (cause) {
+        const code = /** @type {any} */ (cause)?.code;
+        if (code === 'ENOENT') {
+          throw new StaysFixedError(`There is no file called "${relative}" in the project.`, { cause });
+        }
+        if (code === 'EISDIR') {
+          throw new StaysFixedError(`"${relative}" is a folder, not a file.`, { cause });
+        }
+        throw new StaysFixedError(`Could not read "${relative}": ${cause instanceof Error ? cause.message : String(cause)}`, {
+          cause,
+        });
+      }
+    },
+  };
+}
+
+/**
+ * What counts as "no".
+ *
+ * The empty array is in here because a check that gathers matches and finds none
+ * has not proved anything — `expect('the rows are there', () => findRows())`
+ * must fail on an empty list, not quietly pass. NaN is in here for the same
+ * reason: a measurement that went wrong must never be mistaken for a good one.
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isNegative(value) {
+  if (value === false || value === null || value === undefined) return true;
+  if (value === 0 || value === '') return true;
+  if (typeof value === 'number' && Number.isNaN(value)) return true;
+  if (Array.isArray(value) && value.length === 0) return true;
+  return false;
+}
+
+/**
+ * @param {number} ms
+ * @returns {string}
+ */
+function humanTime(ms) {
+  if (ms < 1000) return `${Math.round(ms)} milliseconds`;
+  const seconds = Math.round(ms / 1000);
+  return seconds === 1 ? '1 second' : `${seconds} seconds`;
+}

package/src/guard/load.js

@@ -0,0 +1,324 @@
+/**
+ * Finding and loading a project's guards.
+ *
+ * Every problem found here is reported at once. Fixing guard names one error at
+ * a time, re-running between each, is the kind of chore that makes people delete
+ * the guards instead of naming them properly.
+ */
+
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { StaysFixedError } from '../core/errors.js';
+import { shortPath } from '../core/log.js';
+import { checkGuardName, NAME_RULE_EXPLAINER } from './name.js';
+
+/**
+ * @typedef {object} GuardProblem
+ * @property {string} file
+ * @property {string} label     What the guard called itself, quoted back.
+ * @property {string} why
+ * @property {string} [suggestion]
+ * @property {boolean} [naming]
+ */
+
+/**
+ * Load every guard in the project.
+ *
+ * A missing guards folder is not a problem — plenty of projects start with
+ * pictures only and add guards the first time something comes back.
+ *
+ * @param {import('../types.js').Project} project
+ * @param {{only?: string}} [opts]
+ * @returns {Promise<import('../types.js').Guard[]>}
+ */
+export async function loadGuards(project, opts = {}) {
+  const dir = project.paths.guards;
+  const files = (await collectFiles(dir)).sort();
+  if (files.length === 0) return [];
+
+  /** @type {import('../types.js').Guard[]} */
+  const guards = [];
+  /** @type {GuardProblem[]} */
+  const problems = [];
+
+  for (const file of files) {
+    const exported = await importGuards(file);
+    for (const raw of exported) {
+      const named = /** @type {any} */ (raw);
+      const label = typeof named.name === 'string' && named.name.trim() !== '' ? named.name : '(no name)';
+
+      const verdict = checkGuardName(named.name);
+      if (!verdict.ok) {
+        problems.push({
+          file,
+          label,
+          why: verdict.why ?? 'That name cannot be used.',
+          suggestion: verdict.suggestion,
+          naming: true,
+        });
+        continue;
+      }
+
+      if (typeof named.run !== 'function') {
+        problems.push({
+          file,
+          label,
+          why: 'This guard has no "run" function, so there is nothing for it to do. Give it `async run(app) { ... }`.',
+        });
+        continue;
+      }
+
+      guards.push(/** @type {import('../types.js').Guard} */ ({ ...named, file }));
+    }
+  }
+
+  // Two guards with the same name make a failure ambiguous: the report says the
+  // name, and nobody can tell which of the two actually broke.
+  /** @type {Map<string, string|undefined>} */
+  const seen = new Map();
+  /** @type {Set<string>} */
+  const reported = new Set();
+  for (const guard of guards) {
+    const first = seen.get(guard.name);
+    if (first === undefined) {
+      seen.set(guard.name, guard.file);
+      continue;
+    }
+    if (reported.has(guard.name)) continue;
+    reported.add(guard.name);
+    const where =
+      first === guard.file
+        ? 'Both are in this file.'
+        : `One is in ${shortPath(String(first))} and one is in ${shortPath(String(guard.file))}.`;
+    problems.push({
+      file: guard.file ?? first,
+      label: guard.name,
+      why: `Two guards share this name. ${where} When it fails nobody could tell which one broke, so give them different names.`,
+    });
+  }
+
+  if (problems.length > 0) throw problemsError(problems);
+
+  const only = typeof opts.only === 'string' ? opts.only.trim().toLowerCase() : '';
+  const chosen = only === '' ? guards : guards.filter((g) => g.name.toLowerCase().includes(only));
+
+  // A stable order, so two runs of the same project read the same way.
+  return chosen.sort((a, b) => {
+    const byFile = String(a.file).localeCompare(String(b.file));
+    return byFile !== 0 ? byFile : a.name.localeCompare(b.name);
+  });
+}
+
+/**
+ * Every `.js` / `.mjs` file under a folder, skipping `_`-prefixed and hidden
+ * entries (a handy way to park a guard) and anything inside node_modules.
+ *
+ * @param {string} dir
+ * @returns {Promise<string[]>}
+ */
+async function collectFiles(dir) {
+  /** @type {string[]} */
+  const out = [];
+  let entries = /** @type {import('node:fs').Dirent[]} */ ([]);
+  try {
+    entries = await fsp.readdir(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+
+  for (const entry of entries) {
+    if (entry.name.startsWith('_') || entry.name.startsWith('.')) continue;
+    if (entry.name === 'node_modules') continue;
+    const full = path.join(dir, entry.name);
+
+    let isDir = entry.isDirectory();
+    let isFile = entry.isFile();
+    if (entry.isSymbolicLink()) {
+      try {
+        const target = await fsp.stat(full);
+        isDir = target.isDirectory();
+        isFile = target.isFile();
+      } catch {
+        continue;
+      }
+    }
+
+    if (isDir) out.push(...(await collectFiles(full)));
+    else if (isFile && /\.(js|mjs)$/i.test(entry.name)) out.push(full);
+  }
+  return out;
+}
+
+/**
+ * Import one guard file and pull the guard objects out of it.
+ *
+ * @param {string} file
+ * @returns {Promise<unknown[]>}
+ */
+async function importGuards(file) {
+  /** @type {any} */
+  let mod = undefined;
+  try {
+    // The modified time is part of the import url so a long-lived process — the
+    // MCP server, mostly — picks up an edited guard instead of a cached one,
+    // while an unchanged file still hits the module cache.
+    const stat = await fsp.stat(file);
+    mod = await import(`${pathToFileURL(file).href}?v=${Math.round(stat.mtimeMs)}`);
+  } catch (cause) {
+    throw new StaysFixedError(`The guard file ${shortPath(file)} could not be loaded: ${messageOfCause(cause)}`, {
+      cause,
+      hint: 'Guard files are plain JavaScript modules. Open the file and check it runs on its own — a typo or a bad import will stop the whole run.',
+    });
+  }
+
+  const fallback = mod?.default;
+  if (Array.isArray(fallback)) return fallback;
+  if (looksLikeGuard(fallback)) return [fallback];
+
+  /** @type {unknown[]} */
+  const found = [];
+  for (const [key, value] of Object.entries(mod ?? {})) {
+    if (key === 'default') continue;
+    if (Array.isArray(value)) {
+      for (const item of value) if (looksLikeGuard(item)) found.push(item);
+    } else if (looksLikeGuard(value)) {
+      found.push(value);
+    }
+  }
+
+  if (found.length === 0 && fallback !== undefined) {
+    throw new StaysFixedError(`The guard file ${shortPath(file)} does not export a guard.`, {
+      hint: 'Export the guard as the default: `export default { name: "the sidebar still collapses", async run(app) { ... } }`. An array of guards, or several named exports, work too.',
+    });
+  }
+
+  return found;
+}
+
+/**
+ * Loose enough to catch a half-written guard so we can explain what is missing,
+ * strict enough to ignore an exported constant that happens to sit alongside.
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function looksLikeGuard(value) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return false;
+  const obj = /** @type {Record<string, unknown>} */ (value);
+  return 'run' in obj || 'name' in obj;
+}
+
+/**
+ * @param {unknown} cause
+ * @returns {string}
+ */
+function messageOfCause(cause) {
+  return cause instanceof Error ? cause.message : String(cause);
+}
+
+/**
+ * One error carrying every problem, so a person fixes them in a single pass.
+ *
+ * @param {GuardProblem[]} problems
+ * @returns {StaysFixedError}
+ */
+function problemsError(problems) {
+  const count = problems.length;
+  const lines = [
+    `${count} guard${count === 1 ? '' : 's'} cannot run yet.`,
+    '',
+  ];
+
+  /** @type {Map<string, GuardProblem[]>} */
+  const byFile = new Map();
+  for (const p of problems) {
+    const list = byFile.get(p.file);
+    if (list) list.push(p);
+    else byFile.set(p.file, [p]);
+  }
+
+  for (const [file, list] of byFile) {
+    lines.push(`  ${shortPath(file)}`);
+    for (const p of list) {
+      lines.push(`    "${p.label}"`);
+      lines.push(`    ${p.why}`);
+      if (p.suggestion) lines.push(`    Try instead: "${p.suggestion}"`);
+      lines.push('');
+    }
+  }
+
+  const naming = problems.some((p) => p.naming);
+  return new StaysFixedError(lines.join('\n').trimEnd(), {
+    hint: naming ? NAME_RULE_EXPLAINER : undefined,
+  });
+}
+
+/**
+ * The starter guard file written by `staysfixed init`, and the example in the docs.
+ *
+ * It is deliberately a whole worked example rather than a stub: the first guard
+ * somebody writes sets the tone for every guard after it.
+ *
+ * @param {{name?: string, because?: string, fixed?: string}} [opts]
+ * @returns {string}
+ */
+export function guardTemplate(opts = {}) {
+  const name = opts.name && opts.name.trim() !== '' ? opts.name : 'the sidebar still collapses';
+  const fixed = opts.fixed && opts.fixed.trim() !== '' ? opts.fixed : today();
+  const because =
+    opts.because && opts.because.trim() !== ''
+      ? opts.because
+      : 'Clicking the collapse arrow left the sidebar half open, so the main panel never got its width back. It came back twice after being fixed, which is why this guard exists.';
+
+  return `/**
+ * One guard per bug that has already been fixed. Its only job is to fail the day
+ * that bug comes back.
+ *
+ * The name is the whole point. Write what should still be true, in the words you
+ * would say out loud — six months from now that sentence is the only thing that
+ * will tell you what broke.
+ */
+
+export default {
+  name: ${JSON.stringify(name)},
+
+  // When it was fixed. Handy when you are trying to remember the release.
+  fixed: ${JSON.stringify(fixed)},
+
+  // The story of the original bug. This gets printed when the guard fails, and
+  // it is usually the most useful line in the whole report.
+  because:
+    ${JSON.stringify(because)},
+
+  // link: 'https://github.com/you/your-app/issues/482',
+
+  async run({ open, click, expect, page }) {
+    await open('/');
+
+    // Put the app back in the state where the bug used to happen.
+    await click('[data-sf="sidebar-toggle"]');
+
+    // Then say, in plain words, what must still be true. If one of these turns
+    // out false, the failure reads as the sentence you wrote here.
+    await expect('the sidebar is hidden', async () => !(await page.visible('.sidebar')));
+
+    await expect('the main panel fills the window', async () => {
+      const box = await page.boxOf('.main');
+      return box !== null && box.width > 900;
+    });
+  },
+};
+`;
+}
+
+/**
+ * Today where the person is sitting, not in UTC — somebody running `init` late
+ * at night should not see yesterday's date in their first guard.
+ * @returns {string}
+ */
+function today() {
+  const now = new Date();
+  const pad = (/** @type {number} */ n) => String(n).padStart(2, '0');
+  return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
+}