staysfixed 0.1.0

package/examples/guards/the-sidebar-still-collapses.js

@@ -0,0 +1,91 @@
+/**
+ * A guard, written the way guards are meant to be written.
+ *
+ * A guard is one check per bug that has already been fixed once. Its only job is
+ * to fail on the day that bug comes back. It is not a unit test and it is not a
+ * spec — nobody adds a guard for behaviour that has never broken.
+ *
+ * Drop files like this one into `.staysfixed/guards/`. They are plain JavaScript
+ * modules; the default export is the guard. A file may also export an array of
+ * guards, or several named ones.
+ */
+
+/** @type {import('../../src/types.js').Guard} */
+const guard = {
+  // The name is the whole handover. It is what prints when the guard fails, what
+  // goes in the report, and what an agent reads before deciding whether it broke
+  // something. Write what the app is supposed to do, in the words you would say
+  // out loud. `sidebar_collapse_test` would be refused, and rightly.
+  name: 'the sidebar still collapses',
+
+  // When it was fixed. Free text — a date, a version, whatever you would say.
+  fixed: '2026-08-14',
+
+  // The story of the bug, in one or two sentences. This is printed underneath
+  // the failure, so the person who has never seen this bug knows in five seconds
+  // what they are looking at and whether it matters.
+  because:
+    'A CSS refactor renamed .sidebar--open to .sidebar-open everywhere except the toggle handler, ' +
+    'so the collapse button did nothing and the sidebar was stuck open on every screen under 900px wide. ' +
+    'It shipped and nobody noticed for four days.',
+
+  // Where to read more. An issue, a commit, a session note — anything.
+  link: 'https://github.com/asadev/staysfixed/issues/12',
+
+  // How long this guard gets before it is called failed. Default 30000.
+  timeoutMs: 20_000,
+
+  // Set `skip: true` to park a guard without deleting it. `check` reports it as
+  // left out on purpose, so nobody mistakes it for passing.
+  // skip: true,
+
+  /**
+   * Everything the guard needs is on `app`: the full page, shorthands for the
+   * two things guards do most, `expect` for assertions, `run` for a shell
+   * command, `read` for a project file.
+   *
+   * @param {import('../../src/types.js').GuardApi} app
+   */
+  async run(app) {
+    const { page, expect } = app;
+
+    await app.open('/');
+    await page.waitFor('.sidebar');
+
+    // Assertions are a sentence plus a check, never a bare comparison. When this
+    // fails the person reading the terminal sees
+    //   expected: the sidebar starts open
+    // which anyone can act on, six months from now, at one in the morning.
+    await expect('the sidebar starts open', () => page.visible('.sidebar'));
+
+    await app.click('[data-action="toggle-sidebar"]');
+    await page.waitForGone('.sidebar--open');
+
+    await expect('clicking the toggle hides the sidebar', async () => !(await page.visible('.sidebar')));
+
+    // The bug was that the class name and the handler disagreed. Check the thing
+    // that actually broke, not only the thing you can see — a future refactor
+    // could hide the sidebar a different way and this guard should still hold.
+    await expect('the collapsed sidebar keeps its collapsed class', async () => {
+      const classes = await page.evaluate('document.querySelector(".sidebar").className');
+      return String(classes).includes('sidebar--collapsed');
+    });
+
+    // And that it comes back, because a collapse you cannot undo is a worse bug
+    // than the one we were fixing.
+    await app.click('[data-action="toggle-sidebar"]');
+    await page.waitFor('.sidebar--open');
+    await expect('clicking the toggle again brings the sidebar back', () => page.visible('.sidebar'));
+
+    // Guards do not have to be about the screen at all. This one is, but a guard
+    // can equally run a command or read a file:
+    //
+    //   const { code } = await app.run('npm run build');
+    //   await expect('the production build still succeeds', () => code === 0);
+    //
+    //   const css = await app.read('src/styles/sidebar.css');
+    //   await expect('the collapsed class is still defined', () => css.includes('.sidebar--collapsed'));
+  },
+};
+
+export default guard;

package/examples/staysfixed.config.electron.js

@@ -0,0 +1,172 @@
+/**
+ * An Electron desktop app, checked end to end.
+ *
+ * The difference from a web app is small on purpose: instead of an address, you
+ * give it the executable to launch. Everything after that — screens, freezing,
+ * masks, guards — works exactly the same way, because an Electron window is a
+ * Chromium window with a different frame around it.
+ */
+
+import path from 'node:path';
+
+/**
+ * Point this at the app you actually ship, not at `electron .`. A packaged build
+ * loads the real bundle, the real stylesheets and the real assets; running from
+ * source loads whatever the dev server felt like serving that second.
+ *
+ * On macOS the executable is inside the bundle:
+ *   /Applications/Your App.app/Contents/MacOS/Your App
+ * On Linux it is the AppImage or the binary in the unpacked folder.
+ * On Windows it is the .exe. (Windows is untested — see the README.)
+ */
+const APP_BINARY =
+  process.platform === 'darwin'
+    ? path.resolve('dist/mac-arm64/Your App.app/Contents/MacOS/Your App')
+    : path.resolve('dist/linux-unpacked/your-app');
+
+/** @type {import('../src/types.js').StaysFixedConfig} */
+const config = {
+  app: {
+    kind: 'electron',
+    binary: APP_BINARY,
+
+    // Extra argv the app is launched with. A flag that puts the app into a
+    // known state is worth more than any amount of tolerance tuning.
+    args: ['--staysfixed', '--skip-onboarding'],
+
+    // Working directory for the launched process.
+    cwd: '.',
+
+    // A separate data directory is not optional. Without it the run opens YOUR
+    // installed copy's settings, your real sessions and your real window size —
+    // and then writes to them. Point the app at a throwaway folder and every run
+    // starts from the same place.
+    env: {
+      YOUR_APP_DATA_DIR: '.staysfixed/tmp/app-data',
+      YOUR_APP_TELEMETRY: 'off',
+    },
+
+    // An Electron app usually opens more than one window: a splash, a hidden
+    // background window, sometimes a devtools window. This picks the one whose
+    // title or url contains this text, so the tool never photographs the splash.
+    windowMatch: 'Your App',
+
+    // How long to wait for the window to appear.
+    startTimeoutMs: 60_000,
+
+    // Leave `debugPort` out and a free port is chosen. Set it if your app opens
+    // its remote debugging port itself and you have already fixed the number.
+    // debugPort: 9333,
+
+    // Or attach to an app that is already running with a debugging port open,
+    // instead of launching one. Nothing you attach to is ever closed by the tool.
+    // attach: 'http://127.0.0.1:9333',
+  },
+
+  // A desktop window is usually smaller than a browser viewport. Pick a size
+  // once — changing it later means re-approving every picture.
+  viewport: {
+    width: 1280,
+    height: 800,
+    deviceScaleFactor: 2,
+  },
+
+  freeze: {
+    clock: '2026-01-01T12:00:00.000Z',
+    timezone: 'UTC',
+    locale: 'en-US',
+    motion: true,
+    random: 'seeded',
+    fonts: true,
+
+    // Desktop apps talk to their own backend constantly — updates, licence
+    // checks, sync. 'replay' records each reply once and then serves the same
+    // bytes forever, which is usually the only way a desktop app renders the
+    // same screen twice. The recordings live in .staysfixed/fixtures and belong
+    // in git.
+    network: 'replay',
+    networkAllow: ['file://**', 'app://**'],
+  },
+
+  tolerance: {
+    pixels: 0.0005,
+    threshold: 0.12,
+    antialiasing: true,
+  },
+
+  // Window chrome, an update banner and a clock in the status bar are all
+  // allowed to change. The layout underneath is not.
+  masks: ['.titlebar-buttons', '#update-banner', '[data-clock]'],
+
+  screens: [
+    {
+      name: 'welcome',
+      describe: 'The first window a new user sees',
+      steps: [{ waitFor: '[data-view="welcome"]' }],
+    },
+    {
+      name: 'workspace-empty',
+      describe: 'An open workspace with nothing in it yet',
+      steps: [
+        { click: '[data-action="new-workspace"]' },
+        { type: 'input[name="workspace-name"]', text: 'Demo' },
+        { press: 'Enter' },
+        { waitFor: '[data-view="workspace"]' },
+        { waitForGone: '.spinner' },
+      ],
+    },
+    {
+      name: 'settings-appearance',
+      describe: 'Settings, on the Appearance tab',
+      async do(page) {
+        await page.press('Escape');
+        await page.click('[data-action="open-settings"]');
+        await page.click('[data-tab="appearance"]');
+        await page.waitFor('[data-settings-pane="appearance"]');
+        // Scroll the pane so the theme picker is on screen, then let the list
+        // finish settling before the shutter.
+        await page.scrollTo('[data-setting="theme"]');
+      },
+      masks: ['[data-setting="version"]'],
+    },
+    {
+      name: 'sidebar-collapsed',
+      describe: 'The workspace with the sidebar collapsed',
+      steps: [
+        { click: '[data-action="toggle-sidebar"]' },
+        { waitForGone: '.sidebar--open' },
+      ],
+    },
+  ],
+
+  guards: '.staysfixed/guards',
+
+  walk: {
+    describe: 'What a reviewer clicks through before a release goes out',
+    steps: [
+      { name: 'walk-welcome', describe: 'Welcome window', steps: [{ waitFor: '[data-view="welcome"]' }] },
+      {
+        name: 'walk-workspace',
+        describe: 'A workspace, opened',
+        steps: [{ click: '[data-action="new-workspace"]' }, { press: 'Enter' }, { waitFor: '[data-view="workspace"]' }],
+      },
+      {
+        name: 'walk-settings',
+        describe: 'Settings',
+        steps: [{ click: '[data-action="open-settings"]' }, { waitFor: '[data-view="settings"]' }],
+      },
+    ],
+  },
+
+  mcp: {
+    allowApprove: false,
+    allowMark: false,
+  },
+
+  dir: '.staysfixed',
+  flakeLimit: 2,
+  retries: 1,
+  concurrency: 1,
+};
+
+export default config;

package/examples/staysfixed.config.web.js

@@ -0,0 +1,277 @@
+/**
+ * A web app, checked end to end.
+ *
+ * Copy this to the root of your project as `staysfixed.config.js`, point it at
+ * your dev server, and delete the parts you do not need. Every option here is
+ * optional except `app` and `screens` — the defaults are chosen so that a config
+ * of five lines already works.
+ */
+
+/** @type {import('../src/types.js').StaysFixedConfig} */
+const config = {
+  // ---------------------------------------------------------------------------
+  // What to open
+  // ---------------------------------------------------------------------------
+  app: {
+    kind: 'web',
+
+    // The address the app answers on. Relative screen urls hang off this, so
+    // `url: '/settings'` on a screen below means http://localhost:3000/settings.
+    url: 'http://localhost:3000',
+
+    // Optional: the command that starts the app. Leave it out if you start the
+    // server yourself — Stays Fixed simply waits for `url` to answer either way.
+    // Use a production-like build, not a hot-reloading dev server: a dev overlay
+    // that pops up for half a second is a picture that disagrees with itself.
+    start: 'npm run preview',
+    cwd: '.',
+
+    // Extra environment for the command above. Handy for pointing the app at a
+    // seeded database, which is the single biggest thing you can do to make
+    // pictures repeatable.
+    env: {
+      NODE_ENV: 'production',
+      DATABASE_URL: 'postgres://localhost:5432/myapp_pictures',
+    },
+
+    // How long to wait for the app to answer before giving up.
+    startTimeoutMs: 60_000,
+
+    // Leave `browser` out and the tool finds Chrome, Chromium, Edge or Brave on
+    // this machine. Set it to pin one exact binary, which is what you want when
+    // more than one person approves pictures.
+    // browser: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+
+    // Headless is the default. Turn it off while you are writing a screen recipe
+    // and want to watch the browser do it.
+    headless: true,
+  },
+
+  // ---------------------------------------------------------------------------
+  // How big the window is
+  //
+  // Change this and every approved picture stops matching, so pick a size once.
+  // deviceScaleFactor 2 gives retina-sharp pictures; it is still deterministic.
+  // ---------------------------------------------------------------------------
+  viewport: {
+    width: 1440,
+    height: 900,
+    deviceScaleFactor: 2,
+    mobile: false,
+  },
+
+  // ---------------------------------------------------------------------------
+  // Holding the app still
+  //
+  // These are the defaults spelled out. You can delete this whole block.
+  // docs/how-it-stays-stable.md explains what each one is protecting you from.
+  // ---------------------------------------------------------------------------
+  freeze: {
+    // The instant the app always believes it is. Timers still fire; only the
+    // reading of the clock is pinned. Set to false to leave time alone.
+    clock: '2026-01-01T12:00:00.000Z',
+    timezone: 'UTC',
+    locale: 'en-US',
+
+    // Stop animations, transitions, video and the blinking text cursor.
+    motion: true,
+
+    // Seed Math.random, crypto.getRandomValues and crypto.randomUUID, so a
+    // shuffled list is shuffled the same way every time.
+    random: 'seeded',
+    seed: 20260101,
+
+    // Wait for web fonts and images to land, and pin how text is rasterised.
+    fonts: true,
+
+    // 'block-external' lets the app's own origin and localhost through and
+    // blocks everybody else's servers — the usual choice.
+    // 'replay' records every reply once into .staysfixed/fixtures and then
+    // serves those same bytes forever, which is what you want when the app
+    // cannot render at all without its API.
+    // 'live' lets everything through, and your pictures then depend on the
+    // internet.
+    network: 'block-external',
+
+    // Globs that get out even in 'block-external'. The `*` stops at a path
+    // separator; `**` crosses them.
+    networkAllow: ['https://fonts.gstatic.com/**'],
+
+    hideScrollbars: true,
+    hideCaret: true,
+
+    // Take the photo, take it again, and only accept it once two in a row
+    // agree. This is the safety net for anything the rest of the list missed.
+    settle: {
+      frames: 2,
+      intervalMs: 250,
+      timeoutMs: 10_000,
+      maxDriftPixels: 0,
+    },
+  },
+
+  // ---------------------------------------------------------------------------
+  // How much difference is allowed
+  //
+  // 0.0005 is 0.05% of the pixels — on a 1440x900 at 2x picture that is about
+  // 1,300 pixels. Enough to absorb font hinting noise, nowhere near enough to
+  // hide a missing stylesheet or a shifted column.
+  // ---------------------------------------------------------------------------
+  tolerance: {
+    pixels: 0.0005,
+    threshold: 0.12,
+    antialiasing: true,
+    // maxPixels: 500,   // a hard cap, overrides `pixels` when set
+  },
+
+  // ---------------------------------------------------------------------------
+  // Things that are allowed to change
+  //
+  // A CSS selector paints over every element that matches; a rectangle paints
+  // over an exact area in CSS pixels. Mask a live clock, a session id, a
+  // "3 minutes ago" — never mask something just because it keeps failing.
+  // ---------------------------------------------------------------------------
+  masks: ['[data-live-clock]', '.session-id', { x: 0, y: 0, width: 240, height: 32 }],
+
+  // ---------------------------------------------------------------------------
+  // The screens
+  // ---------------------------------------------------------------------------
+  screens: [
+    // The simplest possible screen: a name and an address.
+    {
+      name: 'home',
+      describe: 'The landing page, signed out',
+      url: '/',
+    },
+
+    // Declarative steps. This form also works in staysfixed.config.json, so a
+    // project in any language can use it without writing JavaScript.
+    {
+      name: 'signed-in-dashboard',
+      describe: 'The dashboard after a normal sign-in',
+      steps: [
+        { goto: '/login' },
+        { type: 'input[name="email"]', text: 'demo@example.com' },
+        { type: 'input[name="password"]', text: 'demo-password' },
+        { click: 'button[type="submit"]' },
+        { waitFor: '[data-testid="dashboard"]' },
+        { note: 'The greeting shows the account name, which is seeded data.' },
+      ],
+      masks: ['[data-testid="last-seen"]'],
+    },
+
+    // Or write it as code, when the steps need a decision.
+    {
+      name: 'settings-notifications',
+      describe: 'Notification settings with the daily digest switched on',
+      async do(page) {
+        await page.goto('/settings');
+        await page.click('[data-tab="notifications"]');
+        await page.waitFor('#daily-digest');
+        const alreadyOn = await page.evaluate(
+          'document.querySelector("#daily-digest").checked === true',
+        );
+        if (!alreadyOn) await page.click('#daily-digest');
+        await page.waitFor('[data-saved="true"]');
+      },
+    },
+
+    // Capture one element instead of the whole window.
+    {
+      name: 'pricing-card-pro',
+      describe: 'The Pro pricing card on its own',
+      url: '/pricing',
+      clip: '[data-plan="pro"]',
+    },
+
+    // A long page, photographed all the way down. Full-page shots are more
+    // fragile than viewport shots: anything lazy-loading below the fold has to
+    // finish first, so give it a longer settle if it wobbles.
+    {
+      name: 'changelog-full',
+      describe: 'The whole changelog page, top to bottom',
+      url: '/changelog',
+      fullPage: true,
+      freeze: {
+        settle: { timeoutMs: 20_000 },
+      },
+    },
+
+    // A screen with its own size and its own tolerance.
+    {
+      name: 'home-narrow',
+      describe: 'The landing page at a narrow width, where the nav collapses',
+      url: '/',
+      viewport: { width: 720, height: 900 },
+      tolerance: { pixels: 0.001 },
+    },
+
+    // Leave a screen out for now without deleting it. `check` says it was left
+    // out on purpose, so nobody thinks it is passing.
+    {
+      name: 'billing-empty',
+      describe: 'Billing with no invoices yet',
+      url: '/billing',
+      skip: true,
+    },
+  ],
+
+  // ---------------------------------------------------------------------------
+  // Guards — one check per bug that was already fixed once.
+  //
+  // A folder of plain JavaScript files. See examples/guards/ and docs/guards.md.
+  // ---------------------------------------------------------------------------
+  guards: '.staysfixed/guards',
+
+  // ---------------------------------------------------------------------------
+  // The pre-release walk. Leave `steps` out and it walks every screen above.
+  // ---------------------------------------------------------------------------
+  walk: {
+    describe: 'The path a new customer takes, opened for real before a release',
+    steps: [
+      { name: 'walk-home', describe: 'Landing page', url: '/' },
+      { name: 'walk-pricing', describe: 'Pricing', url: '/pricing' },
+      {
+        name: 'walk-signup',
+        describe: 'Sign-up form, filled in but not submitted',
+        steps: [
+          { goto: '/signup' },
+          { type: 'input[name="email"]', text: 'demo@example.com' },
+        ],
+      },
+    ],
+  },
+
+  // ---------------------------------------------------------------------------
+  // What an AI agent is allowed to do through the MCP server.
+  //
+  // Both default to false and both should stay false. An agent that can approve
+  // its own pictures has no safety net at all: it edits the code, notices the
+  // picture moved, blesses the new picture, and reports success.
+  // ---------------------------------------------------------------------------
+  mcp: {
+    allowApprove: false,
+    allowMark: false,
+  },
+
+  // ---------------------------------------------------------------------------
+  // Housekeeping
+  // ---------------------------------------------------------------------------
+
+  // Where approved pictures, guards, markers and results live.
+  dir: '.staysfixed',
+
+  // How many times a check may change its mind before it is condemned and the
+  // tool starts saying so in red. Fix it or delete it — never tolerate it.
+  flakeLimit: 2,
+
+  // Re-photograph a failing screen this many times before calling it a real
+  // change. A screen that only passes on the retry is recorded as a flake.
+  retries: 1,
+
+  // Screens photographed at once. One, on purpose: two browsers competing for
+  // the same machine is exactly how pictures start disagreeing with themselves.
+  concurrency: 1,
+};
+
+export default config;

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "staysfixed",
+  "version": "0.1.0",
+  "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",
+  "author": "Asad Iqbal",
+  "homepage": "https://github.com/asadev/staysfixed",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/asadev/staysfixed.git"
+  },
+  "bugs": {
+    "url": "https://github.com/asadev/staysfixed/issues"
+  },
+  "keywords": [
+    "regression",
+    "visual-regression",
+    "screenshot-testing",
+    "snapshot",
+    "mcp",
+    "mcp-server",
+    "ai-agents",
+    "electron",
+    "testing"
+  ],
+  "bin": {
+    "staysfixed": "bin/staysfixed.js"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "src",
+    "examples",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "node --test --test-concurrency=1 \"test/*.test.js\"",
+    "test:determinism": "node --test test/determinism.test.js",
+    "check": "npm run typecheck && npm test",
+    "staysfixed": "node bin/staysfixed.js"
+  },
+  "dependencies": {
+    "pixelmatch": "^7.2.0",
+    "pngjs": "^7.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@types/pngjs": "^6.0.5",
+    "typescript": "^5.9.0"
+  }
+}