frontend-go-live-check 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 1.5.0
+
+- **One folder for everything**: `go-live-check/` holds the settings (`config.json`), the test passwords (`.env`), the API files (`api/`), the design baseline (`baseline/`), the report (`report/`) and a saved sign-in (`session.json`), with its own `.gitignore`. `init` creates it. Projects with the older root files keep working; the README shows how to move.
+- Every section of the HTML report opens and closes (accordion), with **Expand all** and **Collapse all**.
+- The date and time the report was created are at the top of the HTML report, on the PDF and Word cover, and in the page header.
+- Visual changes show the real pages: **Before** (the approved look), **Now** and **Changes** side by side; in each finding, Actual is the page now and Expected is the approved look.
+
+## 1.4.1
+
+- Problems are grouped **by type** (Functionality, Design, Accessibility, Performance, Sign-in, APIs, Security, SEO, Code) in the HTML report, the PDF and the Word file, most serious first in each group.
+- Every problem has **Steps to reproduce** and **Test again**: the shortest command that checks only that problem after the fix.
+- README: new *How it works* and *Built with* sections.
+
 ## 1.4.0
 
 - New layout checks on every page at every screen size, each with Actual and Expected pictures where possible:

package/README.md

@@ -18,11 +18,14 @@
 
 <p align="center">
   <a href="#quick-start">Quick start</a> ·
+  <a href="#files-everything-in-one-folder">Files</a> ·
   <a href="#sign-in-email-google-microsoft-uae-pass">Sign-in</a> ·
   <a href="#what-it-checks">What it checks</a> ·
+  <a href="#how-it-works">How it works</a> ·
   <a href="#the-report">The report</a> ·
   <a href="#pipelines-approve-or-reject-the-merge">Pipelines</a> ·
   <a href="#settings">Settings</a> ·
+  <a href="#built-with">Built with</a> ·
   <a href="#faq">FAQ</a>
 </p>
 
@@ -36,11 +39,11 @@ npx frontend-go-live-check init
 npm run go-live
 ```
 
-That's it. The result is `go-live-report/index.html`, plus a PDF and a Word file to share with your team.
+That's it. The result is `go-live-check/report/index.html`, plus a PDF and a Word file to share with your team.
 
 `init` adds the `go-live` scripts and a settings file, and downloads the test browser. It never overwrites anything.
 
-Have an API? Save your Postman collection as **`api/postman_collection.json`** (or your OpenAPI file as `api/openapi.json`) and the API tests run too.
+Have an API? Save your Postman collection as **`go-live-check/api/postman_collection.json`** (or your OpenAPI file as `go-live-check/api/openapi.json`) and the API tests run too.
 
 <p align="center">
   <img src="https://unpkg.com/frontend-go-live-check@1/docs/terminal.png" alt="Terminal output: NOT READY, 2 blocker, 7 major, 5 minor, with a score per area" width="760">
@@ -48,6 +51,53 @@ Have an API? Save your Postman collection as **`api/postman_collection.json`** (
 
 ---
 
+## Files: everything in one folder
+
+Everything the tool uses or makes is in **one `go-live-check/` folder** at the root of your project. `init` creates it.
+
+```text
+my-project/
+├── go-live-check/
+│   ├── config.json            ← the settings (all optional)
+│   ├── .env                   ← test passwords (Git ignores it)
+│   ├── .env.example           ← the names to fill in (committed)
+│   ├── api/
+│   │   ├── postman_collection.json   ← your Postman collection
+│   │   ├── postman_environment.json  ← optional: its environment
+│   │   └── openapi.json              ← or/and your OpenAPI file
+│   ├── baseline/              ← the approved look of every page (commit it)
+│   ├── report/                ← the results: HTML, PDF, Word, zip (Git ignores it)
+│   ├── session.json           ← a saved sign-in, after `login` (Git ignores it)
+│   └── .gitignore             ← keeps .env, report/ and session.json out of Git
+├── src/
+└── package.json
+```
+
+| Commit | Never commit (already ignored) |
+| --- | --- |
+| `config.json`, `.env.example`, `api/`, `baseline/` | `.env`, `report/`, `session.json` |
+
+<details>
+<summary><b>Set up with an older version?</b></summary>
+
+Projects with `go-live-check.config.json`, `go-live-check.env`, `api/`, `go-live-baseline/` and `go-live-report/` at the root keep working. To move to the folder:
+
+```bash
+mkdir -p go-live-check
+git mv go-live-check.config.json go-live-check/config.json
+git mv go-live-check.env.example go-live-check/.env.example
+git mv api go-live-check/api
+git mv go-live-baseline go-live-check/baseline
+mv go-live-check.env go-live-check/.env
+printf '.env\nreport/\nsession.json\n' > go-live-check/.gitignore
+```
+
+In `go-live-check/config.json`, change `$schema` to `../node_modules/frontend-go-live-check/schema.json`. Remove the old `go-live-report/` folder and its `.gitignore` lines.
+
+</details>
+
+---
+
 ## Why
 
 | Without it | With it |
@@ -97,7 +147,7 @@ npx frontend-go-live-check login
 What happens:
 
 - A normal browser window opens on your app. Sign in the way your users do (approve UAE PASS on your phone), wait for a signed-in page, then press Enter in the terminal.
-- The session (cookies and browser storage) is saved in **`go-live-check.session.json`**. Treat it like a password: Git ignores it, never share it.
+- The session (cookies and browser storage) is saved in **`go-live-check/session.json`**. Treat it like a password: Git ignores it, never share it.
 - When it expires, the report says ***"The saved sign-in session has expired"*** (also when the app's API starts answering 401), and `doctor` tells you before you run. Run `login` again.
 
 **Pipelines (`ciLogin`)**: a pipeline has no one to approve a sign-in, so it uses `ciLogin` instead of `login`. Pick one of these:
@@ -145,7 +195,7 @@ The report lists every sign-in method found (*email and password · Google · UA
 | 🧭 | **Functionality** | JavaScript errors, console errors, failed requests, broken links, images and anchors, blank pages, buttons covered by something else, unfinished text (`undefined`, `NaN`, `[object Object]`, translation keys, lorem ipsum, TODO), loading spinners that never stop, the production build, the "page not found" page |
 | 🛟 | **Resilience** | Each page opened again with its API calls failing: does it crash, go blank, or tell the user? |
 | 📱 | **Design and responsive layout** | Every page at every screen size: sideways scrolling, text that spills out of its box (a button too small for its label), text on top of other text, content cut off at the screen edge, text cut off inside its box, overlapping buttons, stretched or squashed images, tiny text on phones, right-to-left layout (Arabic, Hebrew…), fonts that fail to load, too many fonts and sizes |
-| 🖼️ | **Visual changes** | A pixel comparison of every page with the saved baseline, with the changed areas in red |
+| 🖼️ | **Visual changes** | Every page compared with its approved look (the baseline): **Before**, **Now** and the changed areas side by side |
 | ♿ | **Accessibility** | axe-core against WCAG 2.0 / 2.1 / 2.2 A and AA; keyboard-only use: visible focus, no traps, nothing that only a mouse can click; form field types |
 | ⚡ | **Performance** | Size, JavaScript, requests, load time, LCP, layout shift and frozen-page time for every page, against budgets; Lighthouse as a phone and as a desktop |
 | 🔌 | **API calls made by the pages** | Slow, very large, repeated, too many, uncompressed or uncached calls |
@@ -160,6 +210,24 @@ The report's **What was checked** table says exactly what ran on your project, a
 
 ---
 
+## How it works
+
+```text
+ ① Detect  ──▶  ② Build & start  ──▶  ③ Sign in  ──▶  ④ Find pages  ──▶  ⑤ Test  ──▶  ⑥ Report  ──▶  ⑦ Verdict
+```
+
+| Step | What happens |
+| :-: | --- |
+| **1. Detect** | Reads `package.json`: the framework, the package manager, the sign-in libraries, and your files in `go-live-check/` |
+| **2. Build & start** | Builds the app and starts it **the way it runs in production**, plus any services you listed (a backend or a mock API) |
+| **3. Sign in** | With the test account, the saved session (`login`) or a test token, so the signed-in pages are tested too |
+| **4. Find pages** | Follows every link, reads your routes in the source code and your `sitemap.xml` |
+| **5. Test** | Opens every page at every screen size in a real browser and runs every check in [What it checks](#what-it-checks); then calls every API endpoint from your Postman or OpenAPI file |
+| **6. Report** | Writes the HTML report with Actual and Expected pictures, plus the PDF, the Word file and the zip |
+| **7. Verdict** | **READY**, **NEEDS ATTENTION** or **NOT READY**; in a pipeline, the run fails on blockers and the merge is rejected |
+
+---
+
 ## Works with
 
 **Next.js** · **React** (Vite, Create React App) · **Vue** · **Nuxt** · **Angular** · **Svelte / SvelteKit** · **Astro** · **Remix / React Router** · **Gatsby** · **Solid** · **Preact** · **Qwik** · **plain HTML**. Anything else, in any language, works with a start command or `--url`.
@@ -194,10 +262,11 @@ The framework and the package manager (npm, pnpm, yarn, bun) are detected. The a
 
 The report has:
 
-- the **verdict** and a **score per area** (click an area to filter);
-- every problem, with where it is and at which screen sizes;
+- when it was created, the **verdict** and a **score per area** (click an area to jump to it);
+- every section opens and closes, with **Expand all** and **Collapse all**;
+- **problems by type**: Functionality, Design, Accessibility, Performance, Sign-in, APIs, Security, SEO, Code, each with its score, worst problems first;
 - the API results, the speed of every page, and the load test;
-- screenshots of every page at every size.
+- screenshots of every page at every size, for the design review.
 
 ### Every problem: Actual next to Expected
 
@@ -206,7 +275,9 @@ Each problem is shown so a developer understands it at a glance, without knowing
 - **one sentence** on what is wrong, in plain words;
 - **Actual**: a close-up of the page as it is now, with the problem outlined in red, at the screen size where it happens;
 - **Expected**: the same spot as it should be, outlined in green. For visual problems the tool corrects the page in the browser for this one picture: a visible focus ring, readable contrast, text that fits, a page that fits the screen, right-to-left layout. Other problems (APIs, security, sign-in) get one sentence saying what is expected;
-- **where** (page, screen size, the element by name and CSS selector), **who it affects**, and **how to see it yourself**.
+- **where** (page, screen size, the element by name and CSS selector) and **who it affects**;
+- **steps to reproduce** it yourself;
+- **test again**: the shortest command that checks only this problem after the fix (copy button included), for example `npx frontend-go-live-check --only pages --pages /login --max-pages 1`.
 
 <p align="center">
   <img src="https://unpkg.com/frontend-go-live-check@1/docs/finding.png" alt="A problem card: Actual (focus not visible, outlined in red) next to Expected (a clear focus ring, outlined in green)" width="860">
@@ -314,18 +385,18 @@ The short name `go-live-check` works too. After `init`, use `npm run go-live`, `
 
 ## Settings
 
-Everything is optional. `init` writes `go-live-check.config.json`, and your editor autocompletes it through `$schema`.
+Everything is optional. `init` writes `go-live-check/config.json`, and your editor autocompletes it through `$schema`.
 
 ```json
 {
-  "$schema": "./node_modules/frontend-go-live-check/schema.json",
+  "$schema": "../node_modules/frontend-go-live-check/schema.json",
   "login": { "page": "/login", "username": "test.user", "password": "$GO_LIVE_PASSWORD" },
   "services": [{ "command": "npm run api", "url": "http://localhost:4000/health" }],
   "failOn": "blocker"
 }
 ```
 
-API tests need no settings when your files are in `api/` ([see API tests](#settings)). Passwords are written as `"$NAME"`. Put their values in `go-live-check.env` (Git ignores it) or in your pipeline's secrets. They are replaced with `‹secret›` in every report.
+API tests need no settings when your files are in `go-live-check/api/` (see *API tests from Postman or OpenAPI* below). Passwords are written as `"$NAME"`. Put their values in `go-live-check/.env` (Git ignores it) or in your pipeline's secrets. They are replaced with `‹secret›` in every report.
 
 <details>
 <summary><b>🔐 Sign-in forms that need help</b></summary>
@@ -354,19 +425,16 @@ An external single sign-on page usually can't be automated. Point `login` at a t
 <details>
 <summary><b>🧪 API tests from Postman or OpenAPI</b></summary>
 
-Put your API description in an **`api/`** folder at the root of your project, with **exactly these names**:
+Put your API description in **`go-live-check/api/`**, with **exactly these names**:
 
 ```text
-my-project/
-├── api/
-│   ├── postman_collection.json     ← the Postman collection (v2.1)
-│   ├── postman_environment.json    ← optional: its environment ({{baseUrl}} and other variables)
-│   └── openapi.json                ← or/and the OpenAPI / Swagger file (openapi.yaml works too)
-├── go-live-check.config.json
-└── package.json
+go-live-check/api/
+├── postman_collection.json     ← the Postman collection (v2.1)
+├── postman_environment.json    ← optional: its environment ({{baseUrl}} and other variables)
+└── openapi.json                ← or/and the OpenAPI / Swagger file (openapi.yaml works too)
 ```
 
-That's all: no settings are needed. Postman export names (`My API.postman_collection.json`) need renaming to `postman_collection.json`. If both a Postman collection and an OpenAPI file are there, they are combined: OpenAPI gives the rules, Postman the examples. `init` creates `api/README.md` with these instructions. `frontend-go-live-check doctor` shows what it found.
+That's all: no settings are needed. Postman export names (`My API.postman_collection.json`) need renaming to `postman_collection.json`. If both a Postman collection and an OpenAPI file are there, they are combined: OpenAPI gives the rules, Postman the examples. `init` creates `go-live-check/api/README.md` with these instructions. `frontend-go-live-check doctor` shows what it found.
 
 Never put real passwords or tokens in these files: use `$NAMES` (see below).
 
@@ -394,7 +462,7 @@ To test roles and ownership, add test users. Include a **second user of the same
 <details>
 <summary><b>🖼️ Visual changes</b></summary>
 
-The first run saves a picture of every page at every size in `go-live-baseline/`. Commit that folder. Later runs report pages that look different, with the changed areas in red.
+The first run saves a picture of every page at every size in `go-live-check/baseline/`. Commit that folder. Later runs report pages that look different, with the changed areas in red.
 
 After an intended design change, save the new look:
 
@@ -433,7 +501,7 @@ Hide parts that change on their own (clocks, live data) with `"visualMask": [".c
 ## Safety and privacy
 
 - **Everything runs on your machine** or your own pipeline. Nothing is sent anywhere except to the app being tested.
-- **Test passwords** come from `go-live-check.env` or pipeline secrets, and never appear in a report or log.
+- **Test passwords** come from `go-live-check/.env` or pipeline secrets, and never appear in a report or log.
 - **Use test accounts on a test environment.** Browser checks only read pages and submit forms empty.
 - **API writes and the load test** run only against this computer or the hosts you list. Every record the tests create is deleted afterwards.
 - **Closed networks.** Point `PLAYWRIGHT_DOWNLOAD_HOST` at your mirror, or `GO_LIVE_CHROMIUM` at an existing Chromium.
@@ -451,6 +519,28 @@ console.log(summary.verdict); // READY · NEEDS ATTENTION · NOT READY
 
 ---
 
+## Built with
+
+Trusted open-source tools, used by thousands of teams, do the heavy lifting. The checks, the sign-in handling, the layout and content checks and the reports are this package's own code on top of them.
+
+| Job | Tool | What it does here |
+| --- | --- | --- |
+| 🌐 **Real browser** | [Playwright](https://playwright.dev) | Opens every page in Chromium (Firefox and WebKit with `--all-browsers`) at every screen size; clicks, types, uses the keyboard, signs in, takes the screenshots and prints the PDF |
+| ♿ **Accessibility** | [axe-core](https://github.com/dequelabs/axe-core) (`@axe-core/playwright`) | The accessibility rules (WCAG 2.0 / 2.1 / 2.2, A and AA) used by most accessibility tools |
+| ⚡ **Speed and quality** | [Lighthouse](https://developer.chrome.com/docs/lighthouse) | Google's performance, best-practice and SEO scores, as a phone and as a desktop |
+| | [chrome-launcher](https://github.com/GoogleChrome/chrome-launcher) · [puppeteer-core](https://pptr.dev) | Start and control Chrome for Lighthouse, including signed-in pages |
+| 🖼️ **Visual changes** | [pixelmatch](https://github.com/mapbox/pixelmatch) · [pngjs](https://github.com/pngjs/pngjs) | Compare every screenshot with the saved baseline, pixel by pixel, and mark the changes in red |
+| 🧪 **API tests** | [Ajv](https://ajv.js.org) · [ajv-formats](https://github.com/ajv-validator/ajv-formats) | Check every API answer against your OpenAPI or Postman schema, including formats (email, date, URL, ID) |
+| | [Faker](https://fakerjs.dev) | Realistic test data (names, emails, numbers) for the requests that create records |
+| | [yaml](https://eemeli.org/yaml) | Reads OpenAPI files written in YAML |
+| 📄 **Documents** | [docx](https://docx.js.org) | Writes the Word report |
+| | [JSZip](https://stuk.github.io/jszip) | Packs the full report, screenshots, PDF and Word file into one zip |
+| 🛡️ **Dependencies** | `npm audit` (comes with npm) | Known security problems in your project's libraries |
+
+No other services: nothing is uploaded, and no account is needed.
+
+---
+
 ## FAQ
 
 <details>
@@ -490,7 +580,7 @@ Security headers, compression and caching usually come from your web server or C
 | You see | Fix |
 | --- | --- |
 | `Executable doesn't exist` | `npx playwright install chromium` |
-| `Not set: GO_LIVE_PASSWORD` | Copy `go-live-check.env.example` to `go-live-check.env` and fill it in |
+| `Not set: GO_LIVE_PASSWORD` | Copy `go-live-check/.env.example` to `go-live-check/.env` and fill it in |
 | `login-failed` | Check `login`; name the fields (`usernameField`, `passwordField`, `submit`) if the form is unusual |
 | *Signed-in pages were not tested* | Set `login`, or run `npx frontend-go-live-check login` (Google, UAE PASS…) |
 | *The saved sign-in session has expired* | Run `npx frontend-go-live-check login` again |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frontend-go-live-check",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Is your frontend ready to go live? One command tests any web frontend (React, Next.js, Vue, Angular, Svelte, plain HTML…): pages, responsive design, accessibility, keyboard, performance and load, API calls, security, SEO, sign-in and APIs from Postman/OpenAPI. Report with evidence, PDF and Word, and a pipeline gate that approves or rejects the merge.",
   "homepage": "https://www.npmjs.com/package/frontend-go-live-check",
   "repository": {

package/schema.json

@@ -154,7 +154,7 @@
         },
         "password": {
           "type": "string",
-          "description": "Use \"$NAME\" and put NAME in go-live-check.env."
+          "description": "Use \"$NAME\" and put NAME in go-live-check/.env."
         },
         "usernameField": {
           "type": "string",
@@ -207,7 +207,7 @@
         },
         "sessionFile": {
           "type": "string",
-          "description": "Where the saved session is kept. Default go-live-check.session.json (never commit it)."
+          "description": "Where the saved session is kept. Default go-live-check/session.json (never commit it)."
         }
       },
       "description": "How the tool signs in. Email/password: page + username + password. Google, Microsoft, Apple, UAE PASS\u2026: \"method\": \"session\" and run frontend-go-live-check login once. Pipelines: see ciLogin."

package/src/api/model.mjs

@@ -242,6 +242,6 @@ export async function loadApiMap(api, dir) {
     }
   }
   const baseUrl = sources.find((s) => s.baseUrl)?.baseUrl;
-  if (!sources.length) notes.push('No API file given: set "api": { "file": "postman_collection.json" } (or "openapi") in go-live-check.config.json, or --api <file>.');
+  if (!sources.length) notes.push('No API file given: set "api": { "file": "postman_collection.json" } (or "openapi") in go-live-check/config.json, or put the file in go-live-check/api/, or --api <file>.');
   return { endpoints: [...map.values()], baseUrl, basePath: sources.find((s) => s.basePath)?.basePath, title: sources.find((s) => s.title)?.title, sources: sources.map((s) => s.kind), notes };
 }

package/src/checks/auth.mjs

@@ -95,7 +95,7 @@ export async function runAuthChecks({ base, config, pages, network, log }) {
           const landed = new URL(page.url()).pathname;
           const asksToSignIn = (await page.locator('input[type=password]').count()) > 0;
           if (landed === new URL(target.url).pathname && !asksToSignIn) {
-            add({ ruleId: 'page-without-sign-in', page: target.key, detail: `${target.key} opened without signing in. If it is public on purpose, add it to "publicPages" in go-live-check.config.json.` });
+            add({ ruleId: 'page-without-sign-in', page: target.key, detail: `${target.key} opened without signing in. If it is public on purpose, add it to "publicPages" in the settings (go-live-check/config.json).` });
           }
         }
         await context.close();

package/src/checks/browser.mjs

@@ -414,7 +414,7 @@ export async function runBrowserChecks({ base, config, reportDir, log, starts =
             mkdirSync(join(reportDir, 'visual', 'now'), { recursive: true });
             const taken = await page.screenshot({ path: shotPath, fullPage: true, type: 'png', animations: 'disabled', caret: 'hide', mask }).then(() => true).catch(() => false);
             if (taken) {
-              const result = compareWithBaseline({ shotPath, baselineDir, diffDir: join(reportDir, 'visual', 'diff'), name, update: updateBaseline, threshold: config.visualThreshold ?? 0.001 });
+              const result = compareWithBaseline({ shotPath, baselineDir, diffDir: join(reportDir, 'visual', 'diff'), beforeDir: join(reportDir, 'visual', 'before'), name, update: updateBaseline, threshold: config.visualThreshold ?? 0.001 });
               visualResults.push({ page: landedKey, view: tag, name, ...result });
               if (result.status === 'changed') {
                 add({
@@ -423,6 +423,10 @@ export async function runBrowserChecks({ base, config, reportDir, log, starts =
                   view: tag,
                   detail: `${(result.ratio * 100).toFixed(1)}% of the page looks different from the saved baseline${result.sizeChanged ? ` (size ${result.before} → ${result.after})` : ''}.`,
                   link: `visual/diff/${name}`,
+                  // Actual = the page now; Expected = the approved look (the baseline).
+                  evidence: `visual/now/${name}`,
+                  expected: `visual/before/${name}`,
+                  evidenceView: tag,
                 });
               }
             }

package/src/checks/code.mjs

@@ -10,7 +10,7 @@ import { SECRET_PATTERNS } from './security.mjs';
 function sourceFiles(dir, out = [], depth = 0) {
   if (depth > 8 || out.length > 3000) return out;
   for (const name of readdirSync(dir)) {
-    if (['node_modules', 'dist', 'build', '.next', 'out', 'coverage', 'reports', 'go-live-report', '.git', 'test-results'].includes(name)) continue;
+    if (['node_modules', 'dist', 'build', '.next', 'out', 'coverage', 'reports', 'go-live-report', 'go-live-check', '.git', 'test-results'].includes(name)) continue;
     const path = join(dir, name);
     const stat = statSync(path);
     if (stat.isDirectory()) sourceFiles(path, out, depth + 1);

package/src/checks/sso.mjs

@@ -124,7 +124,7 @@ export function scanProject(dir) {
       continue;
     }
     for (const name of names) {
-      if (['node_modules', 'dist', 'build', '.next', '.git', 'go-live-report', 'coverage'].includes(name)) continue;
+      if (['node_modules', 'dist', 'build', '.next', '.git', 'go-live-report', 'go-live-check', 'coverage'].includes(name)) continue;
       const path = join(current, name);
       const stat = statSync(path);
       if (stat.isDirectory()) stack.push(path);

package/src/checks/visual.mjs

@@ -1,6 +1,6 @@
 /**
  * Design changes between runs. The first run saves a picture of every page at every screen size
- * in go-live-baseline/ (commit it). Later runs compare with it and report pages that look
+ * in go-live-check/baseline/ (commit it). Later runs compare with it and report pages that look
  * different, with a picture that shows the changed area in red.
  * After an intended design change: frontend-go-live-check --update-baseline.
  */
@@ -9,7 +9,7 @@ import { join } from 'node:path';
 import pixelmatch from 'pixelmatch';
 import { PNG } from 'pngjs';
 
-export function compareWithBaseline({ shotPath, baselineDir, diffDir, name, update, threshold = 0.001 }) {
+export function compareWithBaseline({ shotPath, baselineDir, diffDir, beforeDir, name, update, threshold = 0.001 }) {
   mkdirSync(baselineDir, { recursive: true });
   const baselinePath = join(baselineDir, name);
   if (update || !existsSync(baselinePath)) {
@@ -33,5 +33,10 @@ export function compareWithBaseline({ shotPath, baselineDir, diffDir, name, upda
   if (ratio <= threshold && !sizeChanged) return { status: 'same', ratio };
   mkdirSync(diffDir, { recursive: true });
   writeFileSync(join(diffDir, name), PNG.sync.write(diff));
+  // The approved look, next to the report, so Before and Now can be shown side by side.
+  if (beforeDir) {
+    mkdirSync(beforeDir, { recursive: true });
+    copyFileSync(baselinePath, join(beforeDir, name));
+  }
   return { status: 'changed', ratio, sizeChanged, before: `${a.width}×${a.height}`, after: `${b.width}×${b.height}` };
 }

package/src/cli/main.mjs

@@ -29,16 +29,16 @@ What to check
   --update-baseline      save the current look of every page as the new design baseline
 
 Output
-  --out <folder>         where the report goes (default go-live-report)
+  --out <folder>         where the report goes (default go-live-check/report)
   --open                 open the report when done
   --fail-on <level>      blocker (default) | major | minor | never: what makes the command fail
-  --config <file>        the settings file (default go-live-check.config.json)
+  --config <file>        the settings file (default go-live-check/config.json)
   --quiet                print only the result
   --ci                   pipeline mode: build summary, no prompts (the pipeline files use it)
   --format pdf,docx      which documents to write (default both)
   --no-export            no Word or PDF document
 
-Settings: go-live-check.config.json (all optional). Test passwords: go-live-check.env (never committed).
+Files: go-live-check/ (config.json settings, .env test passwords never committed, api/ Postman or OpenAPI, report/).
 Docs: https://www.npmjs.com/package/go-live-check
 `;
 
@@ -64,7 +64,7 @@ export function parseArgs(argv) {
   return { options, positional };
 }
 
-const isProject = (folder) => ['package.json', 'go-live-check.config.json', 'index.html'].some((f) => existsSync(join(folder, f)));
+const isProject = (folder) => ['package.json', 'go-live-check/config.json', 'go-live-check.config.json', 'index.html'].some((f) => existsSync(join(folder, f)));
 
 export async function main(argv) {
   let parsed;
@@ -148,7 +148,7 @@ export async function main(argv) {
 
   const projectFolder = isProject(folder) ? folder : undefined;
   if (!projectFolder && !options.url) {
-    console.error(`✖ ${folder} is not a web project (no package.json, index.html or go-live-check.config.json).\n  Give a project folder, or --url <address> to check a site that is already running.`);
+    console.error(`✖ ${folder} is not a web project (no package.json, index.html or go-live-check/config.json).\n  Give a project folder, or --url <address> to check a site that is already running.`);
     return 2;
   }
   const { runCheck } = await import('../commands/run.mjs');

package/src/commands/ci.mjs

@@ -3,17 +3,17 @@
  * Writes a pipeline file that runs the full check on every pull / merge request. The run fails
  * (and the merge is blocked once the check is required) when the verdict reaches "failOn".
  * The test passwords come from the pipeline's secret variables: the file lists the names found
- * in go-live-check.config.json ("$NAME").
+ * in the settings ("$NAME").
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { CONFIG_FILE } from '../core/config.mjs';
+import { layout } from '../core/config.mjs';
 
 const PLAYWRIGHT = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).dependencies.playwright;
 const IMAGE = `mcr.microsoft.com/playwright:v${PLAYWRIGHT}-noble`;
 
 function secretNames(dir) {
-  const path = join(dir, CONFIG_FILE);
+  const path = join(dir, layout(dir).config);
   if (!existsSync(path)) return ['GO_LIVE_PASSWORD'];
   const names = new Set();
   const walk = (v) => {
@@ -31,7 +31,7 @@ function secretNames(dir) {
 const TEMPLATES = {
   github: {
     file: '.github/workflows/go-live-check.yml',
-    text: (secrets) => `# Go-live check: runs on every pull request and blocks the merge when it fails.
+    text: (secrets, report) => `# Go-live check: runs on every pull request and blocks the merge when it fails.
 # 1. Settings > Secrets and variables > Actions: add ${secrets.join(', ') || 'your test passwords'}.
 # 2. Settings > Branches (or Rules) > protect your main branch > Require status checks: "frontend-go-live-check".
 name: Go-live check
@@ -74,7 +74,7 @@ ${secrets.length ? `        env:\n${secrets.map((s) => `          ${s}: \${{ sec
         uses: actions/upload-artifact@v4
         with:
           name: go-live-report
-          path: go-live-report
+          path: ${report}
           retention-days: 30
 
       - name: Comment the result on the pull request
@@ -84,7 +84,7 @@ ${secrets.length ? `        env:\n${secrets.map((s) => `          ${s}: \${{ sec
           script: |
             const fs = require('fs');
             const marker = '<!-- frontend-go-live-check -->';
-            const summary = fs.existsSync('go-live-report/summary.md') ? fs.readFileSync('go-live-report/summary.md', 'utf8') : 'The go-live check did not finish: open the job log.';
+            const summary = fs.existsSync('${report}/summary.md') ? fs.readFileSync('${report}/summary.md', 'utf8') : 'The go-live check did not finish: open the job log.';
             const run = \`\${context.serverUrl}/\${context.repo.owner}/\${context.repo.repo}/actions/runs/\${context.runId}\`;
             const body = \`\${marker}\\n\${summary}\\n\\nFull report, PDF and Word: the **go-live-report** artifact of [this run](\${run}).\`;
             const { data: comments } = await github.rest.issues.listComments({ ...context.repo, issue_number: context.issue.number });
@@ -95,7 +95,7 @@ ${secrets.length ? `        env:\n${secrets.map((s) => `          ${s}: \${{ sec
   },
   gitlab: {
     file: '.gitlab/go-live-check.gitlab-ci.yml',
-    text: (secrets) => `# Go-live check: runs on every merge request and blocks the merge when it fails.
+    text: (secrets, report) => `# Go-live check: runs on every merge request and blocks the merge when it fails.
 # 1. Add to .gitlab-ci.yml:   include: '.gitlab/go-live-check.gitlab-ci.yml'
 # 2. Settings > CI/CD > Variables: add ${secrets.join(', ') || 'your test passwords'} (Masked, Protected as needed).
 # 3. Settings > Merge requests > "Pipelines must succeed".
@@ -117,14 +117,14 @@ frontend-go-live-check:
   artifacts:
     when: always
     expire_in: 30 days
-    paths: [go-live-report/]
+    paths: [${report}/]
     reports:
-      junit: go-live-report/junit.xml
+      junit: ${report}/junit.xml
 `,
   },
   azure: {
     file: 'azure-pipelines.go-live-check.yml',
-    text: (secrets) => `# Go-live check: runs on every pull request and blocks the merge when it fails.
+    text: (secrets, report) => `# Go-live check: runs on every pull request and blocks the merge when it fails.
 # 1. Pipelines > New pipeline > your repo > Existing YAML file > azure-pipelines.go-live-check.yml
 # 2. Edit > Variables: add ${secrets.join(', ') || 'your test passwords'}, tick "Keep this value secret".
 # 3. Project settings > Repositories > the repo > Policies > main > Build validation: add this pipeline, Required.
@@ -156,21 +156,21 @@ ${secrets.length ? `    env:\n${secrets.map((s) => `      ${s}: $(${s})`).join('
     condition: always()
     inputs:
       testResultsFormat: JUnit
-      testResultsFiles: go-live-report/junit.xml
+      testResultsFiles: ${report}/junit.xml
       testRunTitle: Go-live check
     displayName: Problems in the Tests tab
 
   - task: PublishPipelineArtifact@1
     condition: always()
     inputs:
-      targetPath: go-live-report
+      targetPath: ${report}
       artifact: go-live-report
     displayName: Keep the report (HTML, PDF, Word)
 `,
   },
   bitbucket: {
     file: 'bitbucket-pipelines.go-live-check.yml',
-    text: (secrets) => `# Go-live check for Bitbucket. Copy the "frontend-go-live-check" step into bitbucket-pipelines.yml.
+    text: (secrets, report) => `# Go-live check for Bitbucket. Copy the "frontend-go-live-check" step into bitbucket-pipelines.yml.
 # 1. Repository settings > Repository variables: add ${secrets.join(', ') || 'your test passwords'} (Secured).
 # 2. Repository settings > Branch restrictions > main > "Minimum successful builds": 1.
 image: ${IMAGE}
@@ -186,12 +186,12 @@ pipelines:
             - npm ci
             - npx frontend-go-live-check --ci
           artifacts:
-            - go-live-report/**
+            - ${report}/**
 `,
   },
   jenkins: {
     file: 'Jenkinsfile.go-live-check',
-    text: (secrets) => `// Go-live check for Jenkins (multibranch pipeline: runs on every pull request).
+    text: (secrets, report) => `// Go-live check for Jenkins (multibranch pipeline: runs on every pull request).
 // 1. Manage Jenkins > Credentials: add ${secrets.map((s) => `"${s.toLowerCase().replace(/_/g, '-')}"`).join(', ') || 'your test passwords'} as "Secret text".
 // 2. Point the pipeline's Script Path to Jenkinsfile.go-live-check, and require it in your Git server's merge rules.
 pipeline {
@@ -206,8 +206,8 @@ ${secrets.map((s) => `    ${s} = credentials('${s.toLowerCase().replace(/_/g, '-
   }
   post {
     always {
-      junit allowEmptyResults: true, testResults: 'go-live-report/junit.xml'
-      archiveArtifacts artifacts: 'go-live-report/**', allowEmptyArchive: true
+      junit allowEmptyResults: true, testResults: '${report}/junit.xml'
+      archiveArtifacts artifacts: '${report}/**', allowEmptyArchive: true
     }
   }
 }
@@ -230,7 +230,7 @@ export function addPipeline(dir, provider, log = console.log) {
   }
   const secrets = secretNames(dir);
   mkdirSync(dirname(target), { recursive: true });
-  writeFileSync(target, template.text(secrets));
+  writeFileSync(target, template.text(secrets, layout(dir).report));
   log(`✔ added ${template.file}`);
   log(`  Read the lines at the top of the file: the secret${secrets.length === 1 ? '' : 's'} to add (${secrets.join(', ') || 'none'}) and how to make the check required for merging.`);
   return true;

package/src/commands/doctor.mjs

@@ -6,7 +6,7 @@ import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { chromium } from 'playwright';
 import { loadApiMap } from '../api/model.mjs';
-import { CONFIG_FILE, ENV_FILE, loadConfig } from '../core/config.mjs';
+import { loadConfig } from '../core/config.mjs';
 import { detectProject } from '../core/detect.mjs';
 import { normaliseLogin } from '../core/login.mjs';
 import { readSession, sessionExpiry } from '../core/session.mjs';
@@ -41,11 +41,12 @@ export async function doctor(dir, options = {}, log = console.log) {
     bad(error.message);
     return problems;
   }
-  const { config, configFile, envFile, missingSecrets, hasApi } = loaded;
-  if (configFile) ok(`Settings: ${CONFIG_FILE}`);
-  else warn(`No ${CONFIG_FILE}: the defaults are used (run frontend-go-live-check init to create one)`);
-  if (envFile) ok(`Test passwords file: ${ENV_FILE}`);
-  if (missingSecrets.length) bad(`Not set: ${missingSecrets.join(', ')} (put them in ${ENV_FILE}, or the environment)`);
+  const { config, configFile, envFile, missingSecrets, hasApi, paths } = loaded;
+  if (configFile) ok(`Settings: ${paths.config}`);
+  else warn(`No ${paths.config}: the defaults are used (run frontend-go-live-check init to create one)`);
+  if (envFile) ok(`Test passwords file: ${paths.env}`);
+  if (missingSecrets.length) bad(`Not set: ${missingSecrets.join(', ')} (put them in ${paths.env}, or the environment)`);
+  if (paths.legacy) warn('Files are at the project root (older layout). It still works; to move them into one go-live-check/ folder, see the README (Files).');
   else if (configFile) ok('Every $NAME in the settings has a value');
 
   if (config.url) ok(`Checks the running site ${config.url}`);
@@ -81,9 +82,9 @@ export async function doctor(dir, options = {}, log = console.log) {
     } catch (error) {
       bad(`API file: ${error.message}`);
     }
-  } else warn('No API file: put your Postman collection at api/postman_collection.json (or OpenAPI at api/openapi.json) to add the API tests');
+  } else warn(`No API file: put your Postman collection at ${paths.api}/postman_collection.json (or OpenAPI at ${paths.api}/openapi.json) to add the API tests`);
 
-  if (!existsSync(join(dir, '.gitignore'))) warn('No .gitignore: make sure go-live-check.env is never committed');
+  if (!existsSync(join(dir, paths.legacy ? '.gitignore' : 'go-live-check/.gitignore'))) warn(`No .gitignore: make sure ${paths.env} is never committed (run frontend-go-live-check init)`);
   log(problems ? `\n✖ ${problems} problem(s) to fix first.\n` : '\n✔ Ready: run npm run go-live\n');
   return problems;
 }