frontend-go-live-check 0.0.0-stage → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+## 1.1.0
+
+- **Sign-in with Google, Microsoft, Apple, UAE PASS and any OpenID Connect server.**
+  - `frontend-go-live-check login`: sign in once by hand; the session is saved (`go-live-check.session.json`, ignored by Git) and reused.
+  - `"method": "token"`: a test token (header, cookie, localStorage or sessionStorage).
+  - `ciLogin`: a separate sign-in for pipelines.
+  - Expired sessions are reported, including when the app's API answers 401.
+- **Every sign-in button is found and checked, whatever it says.** It is found by its text, label, logo, where a click leads (the provider is never contacted), the provider's script, or the libraries in the code. The checks: HTTPS, `state`, PKCE instead of the token flow, the return address, the UAE PASS environment (staging or production) and `acr_values`, and what users see after a cancelled sign-in.
+- The report, the PDF and the Word file list every sign-in method found. `doctor` shows how the tool will sign in and when the saved session expires.
+- The README has a new *Sign-in* section.
+
+## 1.0.0
+
+First release.
+
+- One command for any web frontend: Next.js, React, Vue, Angular, Svelte/SvelteKit, Nuxt, Astro, Remix, Gatsby, Solid, Preact, Qwik, plain HTML, or any running site with `--url`.
+- Pages found by following links, from sitemap.xml, and from the routes in the source code.
+- Checks: functionality and errors, resilience when the server fails, responsive layout, right-to-left layout, visual changes against a baseline, accessibility (axe-core, WCAG 2.2 AA), keyboard use, speed of every page with budgets, Lighthouse, sign-in and access, forms, security, SEO, code.
+- API tests from Postman collections (with environments), OpenAPI 3 and Swagger 2.
+- Automatic sign-in for common forms, including two-step forms.
+- Commands: `init`, `doctor`, `plan`, and the check itself with `--quick`, `--only`, `--skip`, `--update-baseline`, `--open`.
+- Report: HTML, JSON, JUnit and Markdown, with a "what was checked" table.
+- Shareable Word (.docx) and PDF documents after every run: cover, document control, sign-off table, contents, executive summary, findings with IDs, evidence and fixes, appendices with screenshots. `frontend-go-live-check export` writes them again.
+- A *Share this report* bar in the HTML report: download the PDF, the Word file, or everything as a .zip, or print.
+- Evidence pictures with the problem elements outlined, plus elements, steps to reproduce and how to check the fix for every problem; problems per page and a fix checklist in the documents.
+- Every request the app makes: slow, large, repeated, too many, uncompressed, not cached, sensitive values in addresses.
+- Lag: how long scripts freeze each page; a light load test (several users at once, GET only).
+- Design consistency: web fonts that fail, too many fonts and sizes; broken in-page anchors; form field types.
+- Evidence pictures in the HTML report too; npm README with pictures; GitLab pipeline that publishes to npm with trusted publishing.
+- `frontend-go-live-check ci github|gitlab|azure|bitbucket|jenkins`: a pipeline that approves or rejects the merge.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ahmed Khedr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,503 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="https://unpkg.com/frontend-go-live-check@1/docs/banner.jpg" alt="frontend-go-live-check: is your frontend ready to go live? One command tells you." width="100%">
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">
+  <a href="https://www.npmjs.com/package/frontend-go-live-check"><img src="https://img.shields.io/npm/v/frontend-go-live-check?color=2f6bff&label=npm" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/frontend-go-live-check"><img src="https://img.shields.io/npm/dm/frontend-go-live-check?color=10b981" alt="downloads per month"></a>
+  <img src="https://img.shields.io/node/v/frontend-go-live-check?color=555" alt="Node.js version">
+  <img src="https://img.shields.io/badge/WCAG-2.2%20AA-8a2be2" alt="WCAG 2.2 AA">
+  <img src="https://img.shields.io/npm/l/frontend-go-live-check?color=555" alt="MIT license">
+</p>
+
+<p align="center">
+  <b>One command. Every page, every screen size, every API. One verdict.</b><br>
+  Builds your app like production, tests it in a real browser, and tells you whether it is ready to go live,<br>
+  with a picture of every problem and how to fix it. No tests to write.
+</p>
+
+<p align="center">
+  <a href="#quick-start">Quick start</a> ·
+  <a href="#sign-in-email-google-microsoft-uae-pass">Sign-in</a> ·
+  <a href="#what-it-checks">What it checks</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="#faq">FAQ</a>
+</p>
+
+---
+
+## Quick start
+
+```bash
+npm install --save-dev frontend-go-live-check
+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.
+
+`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.
+
+<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">
+</p>
+
+---
+
+## Why
+
+| Without it | With it |
+| --- | --- |
+| "Looks fine on my screen" | Every page at phone, tablet and desktop size, in a real browser |
+| Accessibility, security and speed are checked by different people, if at all | One run, one report, one verdict: **READY**, **NEEDS ATTENTION** or **NOT READY** |
+| Bugs reported as "the page is broken" | A picture of the problem outlined in red, the CSS selector, steps to see it, and how to fix it |
+| Writing and maintaining end-to-end tests for every page | Nothing to write: pages are found by following links, your routes and your sitemap |
+| Releases go out on hope | A pipeline step that **blocks the merge** when there are blocking problems |
+
+---
+
+## Sign-in: email, Google, Microsoft, UAE PASS…
+
+> ### ⚠️ Read this first: sign-in decides what gets tested
+> Most of an app is behind its sign-in. **If the tool can't sign in, only the public pages are tested**, and the report says so: *"Signed-in pages were not tested"*.
+>
+> The tool **finds every sign-in method by itself**: email and password, Google, Microsoft, Apple, UAE PASS, or any OpenID Connect server.
+>
+> It **never signs in with a real Google or UAE PASS account on its own.** Those sign-ins block automated browsers or need approval on a phone, and automating them would break their rules. Instead you choose one of the ways below. It takes a minute.
+
+### How the tool signs in
+
+| Your app signs in with | On your computer | In the pipeline (`ciLogin`) |
+| --- | --- | --- |
+| **Email or user name + password** | Automatic: set `login` with a **test** account | The same, with the password from a pipeline secret |
+| **Google · Microsoft · Apple** | Run `npx frontend-go-live-check login` **once** and sign in by hand in the window that opens; the session is saved and reused | A test sign-in on the **test environment** (see below), or a test token |
+| **UAE PASS** | The same: sign in once with a **UAE PASS staging** test account and approve on your phone | A test sign-in on the test environment, or a test token: never a real UAE PASS account |
+| **Several of these** | Pick one for the test run; every sign-in button is still checked (below) | The same |
+
+**Email and password**: the tool finds the fields and the button itself, including two-step forms and Arabic buttons.
+
+```json
+"login": { "page": "/login", "username": "test.user@example.com", "password": "$GO_LIVE_PASSWORD" }
+```
+
+**Google, Microsoft, Apple, UAE PASS**: sign in once by hand, then every run reuses that session.
+
+```bash
+npx frontend-go-live-check login
+```
+
+```json
+"login": { "method": "session", "page": "/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.
+- 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:
+
+```json
+"ciLogin": { "page": "/login", "username": "ci.test@example.com", "password": "$CI_TEST_PASSWORD" }
+```
+
+```json
+"ciLogin": { "method": "token", "token": { "header": "Bearer $CI_TEST_TOKEN" } }
+```
+
+- **Test sign-in (recommended):** the test environment offers a test email/password sign-in, or a mock identity provider (Keycloak, a mock OpenID Connect server). Never offer it in production.
+- **Test token:** a token for a test user, from a pipeline secret. `token` can also set `cookies`, `localStorage` or `sessionStorage` values, wherever your app keeps its token. The header is only sent to your app, never to other sites.
+
+### Every sign-in button is checked, whatever it says
+
+The tool finds Google, Microsoft, Apple, Facebook, GitHub, LinkedIn, **UAE PASS**, Auth0, Okta, Cognito and any OpenID Connect server. The button can say anything, *"Use Google"*, *"Continue"*, Arabic text, or show only an icon. It uses four signals:
+
+1. the button's text, label or logo;
+2. **where a click leads**: every button on the sign-in page is clicked in a throwaway window, and the provider address is caught and **stopped**, so Google and UAE PASS are never contacted;
+3. the provider's script on the page;
+4. sign-in libraries in your code (Auth.js, MSAL, Firebase, Keycloak, oidc-client…).
+
+| Checked | Why it matters |
+| --- | --- |
+| The button starts a sign-in | A dead *"Sign in with UAE PASS"* button locks users out |
+| HTTPS | Sign-in data must never travel unencrypted |
+| `state` is sent | Protects against forged sign-ins (CSRF) |
+| Code flow with **PKCE**, not the old token flow | The current OAuth security best practice |
+| The return address (`redirect_uri`) is HTTPS and yours | The user and the code must come back to your app |
+| **UAE PASS environment**: staging (`stg-id.uaepass.ae`) or production (`id.uaepass.ae`), and `acr_values` | Production must never point at staging |
+| **Cancelled sign-in**: your return page with `error=access_denied` | Users who press *Cancel* must see a clear message, not a crash or a blank page |
+
+The report lists every sign-in method found (*email and password · Google · UAE PASS (staging)*), and the PDF and Word files include it.
+
+> **💡 Before going live:** sign in once by hand with each real provider on the production site. No automated tool can do that last step for you.
+
+---
+
+## What it checks
+
+| | Area | What is checked |
+| :-: | --- | --- |
+| 🧭 | **Functionality** | JavaScript errors, console errors, failed requests, broken links, images and anchors, blank pages, 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, cut-off or overlapping text and buttons, 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 |
+| ♿ | **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 |
+| 📈 | **Load** | 10 users at the same time on the main pages and the app's own read requests |
+| 🔐 | **Sign-in and access** | Every sign-in method found (email, Google, Microsoft, Apple, UAE PASS, OpenID Connect) and its buttons; wrong password, unknown user, empty sign-in; a cancelled sign-in; signed-in pages and APIs opened without signing in; tokens in web storage; every form submitted empty |
+| 🧪 | **API tests** | From your **Postman collection or OpenAPI/Swagger file**: every endpoint with valid and invalid data, without a token, with the wrong role, and with another user's records |
+| 🛡️ | **Security** | Security headers, cookies, private files (`.env`, `.git`), source maps, secrets in the JavaScript or the source, passwords in addresses, outside scripts without integrity, `npm audit` |
+| 🔎 | **SEO and sharing** | Titles, descriptions, headings, language, duplicate titles, favicon, link previews, robots.txt and sitemap.xml |
+| 🧹 | **Code** | TypeScript errors, your own ESLint rules, leftover `console.log` |
+
+The report's **What was checked** table says exactly what ran on your project, and why anything was skipped.
+
+---
+
+## 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`.
+
+The framework and the package manager (npm, pnpm, yarn, bun) are detected. The app is built and started **the way it runs in production**.
+
+<details>
+<summary><b>How each framework is started</b></summary>
+
+| Project | Started for the check with |
+| --- | --- |
+| Next.js | `next build` → `next start` (static export: the `out/` folder) |
+| React / Vue / Svelte / Solid with Vite | build → `vite preview` (keeps your preview proxy to the API) |
+| Create React App, Vue CLI, Parcel, webpack, Gatsby | build → the output folder |
+| Nuxt | build → `.output/server` (or `.output/public`) |
+| Angular | `ng build` → `dist/<app>/browser` |
+| SvelteKit | build → `node build`, `build/` or `vite preview` |
+| Astro | build → `dist/` or the Node adapter's server |
+| Remix / React Router 7 | build → `npm start` |
+| Plain HTML | the folder itself |
+| Anything else | `"start": "your command"` in the settings, or `--url https://your-test-site` |
+
+</details>
+
+---
+
+## The report
+
+<p align="center">
+  <img src="https://unpkg.com/frontend-go-live-check@1/docs/overview.png" alt="The HTML report: share bar, verdict and a score per area" width="900">
+</p>
+
+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;
+- the API results, the speed of every page, and the load test;
+- screenshots of every page at every size.
+
+### Every problem comes with evidence
+
+The page is shown at the screen size where the problem happens, with the problem **outlined in red**. Each problem also lists the element's CSS selector, the steps to see it, and how to fix it.
+
+<p align="center">
+  <img src="https://unpkg.com/frontend-go-live-check@1/docs/finding.png" alt="A finding with its evidence picture: the clickable box is outlined in red" width="820">
+</p>
+
+### Share it as PDF or Word
+
+The **Share this report** bar downloads:
+
+- **PDF**, to read, print or attach to an email;
+- **Word**, for comments and sign-off;
+- **Everything (.zip)**, the full report with all screenshots.
+
+Both documents follow a standard test-report layout:
+
+- a cover and document control;
+- a review-and-approval table;
+- contents;
+- an executive summary;
+- results by area;
+- every finding with an ID, its evidence and how to fix it;
+- problems per page;
+- a fix checklist;
+- appendices with screenshots.
+
+<p align="center">
+  <img src="https://unpkg.com/frontend-go-live-check@1/docs/documents.png" alt="The PDF: cover, executive summary, and a finding with its evidence" width="900">
+</p>
+
+| Verdict | When |
+| --- | --- |
+| ✖ **NOT READY** | at least one **blocker** |
+| ⚠ **NEEDS ATTENTION** | no blockers, at least one **major** problem |
+| ✔ **READY** | no blockers and no major problems |
+
+---
+
+## Pipelines: approve or reject the merge
+
+One command writes a ready-to-use pipeline file. It runs the full check on every pull or merge request, and the run **fails when there are blockers**. Make the check *required*, and the merge is blocked until they are fixed.
+
+```bash
+npx frontend-go-live-check ci gitlab
+npx frontend-go-live-check ci github
+npx frontend-go-live-check ci azure
+npx frontend-go-live-check ci bitbucket
+npx frontend-go-live-check ci jenkins
+```
+
+| Provider | File | Where the result shows |
+| --- | --- | --- |
+| GitLab CI | `.gitlab/go-live-check.gitlab-ci.yml` | merge request test report and artifacts |
+| GitHub Actions | `.github/workflows/go-live-check.yml` | a check plus a summary comment on the pull request |
+| Azure DevOps | `azure-pipelines.go-live-check.yml` | Tests tab, build summary, report artifact |
+| Bitbucket | `bitbucket-pipelines.go-live-check.yml` | pull request build status and artifacts |
+| Jenkins | `Jenkinsfile.go-live-check` | test results and archived report |
+
+The top of each file says:
+
+- which secrets to add (the `$NAMES` from your settings);
+- how to make the check required.
+
+Use `"failOn": "major"` for stricter merges.
+
+---
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `frontend-go-live-check` | The full check of the project in this folder |
+| `frontend-go-live-check --quick` | A fast check while you work: desktop and phone, no Lighthouse, load test or visual comparison |
+| `frontend-go-live-check --url <address>` | Check a site that is already running (a test server, any technology) |
+| `frontend-go-live-check init` | Set the project up: scripts, settings, `.gitignore`, test browser |
+| `frontend-go-live-check login` | Sign in once by hand (Google, UAE PASS…); the session is saved and reused |
+| `frontend-go-live-check doctor` | Check that everything is ready; changes nothing |
+| `frontend-go-live-check plan` | List every API test case; calls nothing |
+| `frontend-go-live-check export` | Write the PDF and Word files again from the last report |
+| `frontend-go-live-check ci <provider>` | Add a pipeline that gates the merge |
+
+The short name `go-live-check` works too. After `init`, use `npm run go-live`, `npm run go-live:quick` and `npm run go-live:api`.
+
+<details>
+<summary><b>All options</b></summary>
+
+| Option | What it does |
+| --- | --- |
+| `--only pages,security` | Only these areas: `pages`, `lighthouse`, `auth`, `security`, `resilience`, `load`, `api`, `code` |
+| `--skip lighthouse,load` | Everything except these |
+| `--api-only` | Only the API tests (backend projects) |
+| `--api <file or URL>` | The Postman collection or OpenAPI/Swagger file (found automatically in the project) |
+| `--pages /,/about` | Where to start looking for pages |
+| `--max-pages <n>` | Stop after this many pages (default 50) |
+| `--viewports phone,desktop` | `small-phone` 320 · `phone` 390 · `tablet` 768 · `laptop` 1280 · `desktop` 1440 · `wide` 1920 |
+| `--all-browsers` | Also Firefox and Safari (WebKit) |
+| `--no-lighthouse` · `--no-build` · `--no-export` | Skip Lighthouse · use the existing build · no PDF/Word |
+| `--format pdf` | Only one of the documents |
+| `--update-baseline` | Save the current look of every page as the new design baseline |
+| `--fail-on major` | What fails the command: `blocker` (default) · `major` · `minor` · `never` |
+| `--open` · `--out <folder>` · `--config <file>` · `--quiet` · `--ci` | Open the report · report folder · settings file · less output · pipeline mode |
+
+</details>
+
+---
+
+## Settings
+
+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",
+  "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.
+
+<details>
+<summary><b>🔐 Sign-in forms that need help</b></summary>
+
+All the sign-in methods are explained in [Sign-in](#sign-in-email-google-microsoft-uae-pass). Most sign-in forms work with only `page`, `username` and `password`. The check finds the password field, the user name field before it, and the button (English and Arabic texts are recognised). Two-step forms (user name, *Next*, then password) work too.
+
+For an unusual page, name each part by its label, placeholder, field name, or a CSS selector written as `css=…`:
+
+```json
+"login": {
+  "page": "/auth/sign-in",
+  "username": "test.user",
+  "password": "$GO_LIVE_PASSWORD",
+  "usernameField": "Email or ID",
+  "passwordField": "css=#pwd",
+  "submit": "Continue",
+  "fields": { "Organisation": "Test organisation" },
+  "expect": "/dashboard"
+}
+```
+
+An external single sign-on page usually can't be automated. Point `login` at a test environment's sign-in page.
+
+</details>
+
+<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**:
+
+```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
+```
+
+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.
+
+Never put real passwords or tokens in these files: use `$NAMES` (see below).
+
+To test roles and ownership, add test users. Include a **second user of the same role**, so the check can test that users can't read each other's records:
+
+```json
+"api": {
+  "baseUrl": "http://localhost:4000",
+  "users": {
+    "user":  { "username": "user.one",   "password": "$USER_PASSWORD",  "role": "user" },
+    "user2": { "username": "user.two",   "password": "$USER2_PASSWORD", "role": "user" },
+    "admin": { "username": "admin.test", "password": "$ADMIN_PASSWORD", "role": "admin" }
+  }
+}
+```
+
+**Test data.** It is generated from the schema (or from your Postman examples). Records the run creates are tagged and deleted afterwards.
+
+**Writes.** POST, PUT, PATCH and DELETE happen only on `localhost` or on hosts you list in `api.writeHosts`.
+
+**Before you run.** `frontend-go-live-check plan` lists every case without calling anything.
+
+</details>
+
+<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.
+
+After an intended design change, save the new look:
+
+```bash
+npx frontend-go-live-check --update-baseline
+```
+
+Hide parts that change on their own (clocks, live data) with `"visualMask": [".clock"]`.
+
+</details>
+
+<details>
+<summary><b>📋 All settings</b></summary>
+
+| Key | Meaning |
+| --- | --- |
+| `pages`, `maxPages`, `routeParams` | Where to start; how many pages; values for routes like `/orders/:id` (`{ "id": "1" }`) |
+| `publicPages`, `publicApis` | Pages and APIs meant to open without signing in (pages linked from the sign-in page count automatically) |
+| `viewports`, `browsers` | Screen sizes (names or `{ "name", "width", "height", "mobile" }`); `chromium`, `firefox`, `webkit` |
+| `services` | Commands started first (a backend, a mock API), each ready when its `url` answers |
+| `build`, `start`, `url` | `false` or your own build command · your own start command (`{port}` / `$PORT`) · check a running site |
+| `budgets` | `pageKB` 3000 · `jsKB` 1000 · `requests` 120 · `loadMs` 4000 · `apiMs` 1000 · `apiCalls` 30 |
+| `load` | `{ "users": 10, "seconds": 10, "maxTargets": 8, "hosts": [] }`, or `false` (GET only; this computer or listed hosts) |
+| `keyboard`, `resilience`, `visual`, `evidence`, `formChecks`, `lighthouse`, `discoverRoutes` | All on by default; `false` turns one off |
+| `visualThreshold`, `visualMask`, `baselineDir` | How much may change (0.1%); parts to hide; where the baseline lives |
+| `report` | `organisation`, `classification` (default *Internal*), `preparedFor`, `approvers`: shown in the PDF and Word |
+| `export` | `["pdf", "docx"]` (default) or `false` |
+| `failOn` | `blocker` (default) · `major` · `minor` · `never` |
+| `login` | `page`, `username`, `password` (email/password) · `"method": "session"` (after `login`) · `"method": "token"` with `token` · `usernameField`, `passwordField`, `submit`, `fields`, `expect` |
+| `ciLogin` | Replaces `login` in pipelines: a test sign-in or a test token |
+
+</details>
+
+---
+
+## 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.
+- **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.
+
+---
+
+## Use it from code
+
+```js
+import { goLiveCheck } from 'frontend-go-live-check';
+
+const { summary, failed } = await goLiveCheck({ dir: process.cwd(), quick: true, quiet: true });
+console.log(summary.verdict); // READY · NEEDS ATTENTION · NOT READY
+```
+
+---
+
+## FAQ
+
+<details>
+<summary><b>Does it replace unit and end-to-end tests?</b></summary>
+
+No. It checks what every web app needs before going live, without any test code. Your own tests still cover your business rules.
+
+</details>
+
+<details>
+<summary><b>How long does a run take?</b></summary>
+
+About 2 minutes for a small app with Lighthouse. `--quick` takes under a minute. Bigger apps take longer, depending on the number of pages (`maxPages`) and screen sizes.
+
+</details>
+
+<details>
+<summary><b>Why are header findings marked "local server"?</b></summary>
+
+Security headers, compression and caching usually come from your web server or CDN, not from the app. On a local run they are information only. Check a test environment with `--url` for the real values.
+
+</details>
+
+<details>
+<summary><b>What still needs a person?</b></summary>
+
+- whether the design matches what was intended (the screenshots make this quick);
+- business rules;
+- a full load test before a big launch;
+- a penetration test.
+
+</details>
+
+<details>
+<summary><b>Troubleshooting</b></summary>
+
+| 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 |
+| `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 |
+| `start-failed` | Run the build and start yourself and fix the error, set `start`, or use `--url` |
+| A public page "opens without signing in" | Add it to `publicPages` |
+| Many visual changes after a font or OS change | `--update-baseline` (create baselines on the same kind of machine that compares) |
+| `EBADENGINE` | Node.js 22.19 or newer is needed |
+
+</details>
+
+---
+
+<p align="center">
+  <b>Requirements:</b> Node.js 22.19+ · <b>License:</b> MIT · <a href="https://unpkg.com/frontend-go-live-check@1/CHANGELOG.md">Changelog</a>
+</p>

package/bin/frontend-go-live-check.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from '../src/cli/main.mjs';
+
+process.exitCode = await main(process.argv.slice(2));