@ia-qa/pal 0.1.0 → 0.3.0

package/README.md

@@ -2,12 +2,14 @@
 
 **A QA pal next to your team — not instead of it.**
 
-One command walks your web app, maps every page, checks it, and compares it with the last tour. Then it tells you four things, in the order you act on them: what is **broken**, what **needs a decision**, what is **ready to repair**, and what it **could not see**.
+One command walks your web app, maps every page, checks it, and compares it with the last tour — and, when you declare your end-to-end suite, reads it too. Then it tells you four things, in the order you act on them: what is **broken**, what **needs a decision**, what is **ready to repair**, and what it **could not see**.
 
 - **Local.** A headless browser on your machine. Nothing is uploaded, no account, no LLM.
 - **Deterministic.** Verdicts come from [`@ia-qa/self-healing`](https://www.npmjs.com/package/@ia-qa/self-healing) — the same engine as `ia-qa-heal diff` and `ia-qa-heal check`, so the two can never disagree.
 - **Honest about coverage.** A tour that measured part of your app says which part. A first tour establishes a baseline; it is never reported as a pass.
 
+> **New here?** The [step-by-step tutorial](https://www.ia-qa.com/devtools/pal/tutorial) walks a first tour, reading the report, logins and CI.
+
 ## Install
 
 ```bash
@@ -15,26 +17,36 @@ npm i -D @ia-qa/pal
 npx playwright install chromium
 ```
 
-`ia-qa-pal` needs a `.ia-qa/config.json` with your `baseUrl` and pages. The setup wizard comes with the dependency:
+## Use
 
 ```bash
-npx ia-qa-heal init
+npx ia-qa-pal tour
 ```
 
-Behind a login? Either declare it in `init`, point at a Playwright `storageState` your suite already writes (`--session`), or log in once by hand with `npx ia-qa-heal login`.
+**Not set up yet?** In a terminal, the first `tour` asks where the app lives and how it logs in — and, when it finds a test suite in the project, whether to read it — then reads its pages from `sitemap.xml` (or, without one, follows its links: same host, GET only, at most 50 pages), shows you exactly what it will write, and writes it only when you say yes. Nothing it asks takes a password.
 
-## Use
+From CI or an agent, the same setup with flags:
 
 ```bash
-npx ia-qa-pal tour
+npx ia-qa-pal setup --url https://your-app.example --login none --yes
 ```
 
+| `--login` | |
+|---|---|
+| `none` | public pages |
+| `browser` | you log in by hand once — SSO, MFA, anything: `npx -p @ia-qa/self-healing ia-qa-heal login` |
+| `session --session <file>` | your test suite already saves a Playwright `storageState`; only its path is written |
+
+A login form filled from environment variables (`auth` in the config) is set up with `npx -p @ia-qa/self-healing ia-qa-heal init`.
+
 **First tour** — every page on the surface (no clicks), the first 10 pages that have closed menus, tabs or dialogs explored in depth, the checks, and a baseline.
 
 **Every tour after** — each page re-captured the way its baseline was captured, compared with it, checked.
 
 **`--more`** — explores the next batch in depth and adds it to the baseline. It refuses while the last tour ended on BLOCK: promoting those pages would accept drift nobody looked at.
 
+Illustrative report:
+
 ```
 ia-qa-pal tour — https://app.example · level 1 (with a login)
 ✅ PASS · 7937 ok · 1 renamed · 0 lost · 0 ambiguous · 0 rebound
@@ -48,11 +60,42 @@ ia-qa-pal tour — https://app.example · level 1 (with a login)
 
 The time estimate only appears once a batch has been explored on your app: it is the pace measured there, never a constant.
 
+## With your test suite
+
+Declare it at setup (`--tests tests/`, or answer yes when the tour finds it) and every tour also reads it:
+
+- **🔧 Ready to repair** — when a selector your tests write stops reaching its element while the element is still there, the rewrite is listed with `file:line` and the command that applies it after you review it. pal never edits your tests.
+- **⛔ To decide** — locator names your tests use that nothing on the mapped pages carries, and renamed labels your tests locate by name.
+- **🔍 Not seen** — `ia-qa-pal tour --suite` runs the `testCommand` from your config once, with the capture hook, and names the pages your suite **never visits**. The capture is kept apart from the tour's contracts. Your specs need the hook for this — one import:
+
+```js
+import { test, expect } from '@ia-qa/self-healing/capture';
+```
+
+Without it, the report says the suite ran but recorded no page — never that it visits nothing.
+
+## In the background, and for agents
+
+```bash
+npx ia-qa-pal tour --background   # returns at once
+npx ia-qa-pal status              # phase and progress, then the report
+```
+
+One tour runs per project; a second is refused while the first is alive, and a tour whose process died is reported as interrupted, never as running.
+
+`ia-qa-pal-mcp` is the same thing as a local stdio MCP server — `pal_project`, `pal_setup`, `pal_tour` (always in the background, so no client times out) and `pal_status`. No tool takes a command, and there is no login tool.
+
+```json
+{ "mcpServers": { "ia-qa-pal": { "command": "npx", "args": ["-y", "-p", "@ia-qa/pal", "ia-qa-pal-mcp"] } } }
+```
+
 ### Options
 
 | flag | |
 |---|---|
 | `--more` | explore the next batch in depth instead of a regression tour |
+| `--suite` | also run your test command once, with the capture hook |
+| `--background` | start detached and return at once |
 | `--batch <n>` | pages per depth batch (default 10) |
 | `--json` | the whole report as one JSON document on stdout; progress stays on stderr |
 | `--session <file>` | a Playwright `storageState` to reuse |
@@ -62,9 +105,9 @@ The time estimate only appears once a batch has been explored on your app: it is
 
 | code | meaning |
 |---|---|
-| `0` | nothing needs a decision (warnings never fail a tour) |
-| `1` | a dead link, or drift that blocks (an element lost, ambiguous, or a selector now pointing at another element) |
-| `2` | could not answer: no config, nothing could be mapped, or the tour refused to run |
+| `0` | nothing needs a decision (warnings and proposed repairs never fail a tour) |
+| `1` | a dead link, drift that blocks (an element lost, ambiguous, or a selector now pointing at another element), or your suite failed when run with `--suite` |
+| `2` | could not answer: not set up, nothing could be mapped, the tour refused to run, or one is already running |
 
 Read `2` as "no answer", never as "the app is broken".
 
@@ -73,8 +116,5 @@ Read `2` as "no answer", never as "the app is broken".
 - **Only your app.** Its pages load whatever they load in any browser.
 - **Exploration is read-only.** While menus, tabs and dialogs are opened, every non-GET request is blocked, and controls named like actions (log out, delete, pay…) are never clicked.
 - **The link check** requests your app's own links with GET, skipping any URL that acts (`/logout`, `/delete`…).
-- **Files** live in `.ia-qa/`: contracts, baseline, and `pal/state.json` (pace and already-reported findings). A saved session there holds live cookies — it is gitignored and never leaves your machine.
-
-## Not yet
-
-Reading your test suite (coverage of what it does not test, repairs proposed as a patch), a setup inside `ia-qa-pal` itself, a local MCP server for agents, and background exploration are planned next.
+- **Your test command** runs only with `--suite` (or `suite: true` from an agent), and it is always the one in your config — never a string passed on the call.
+- **Files** live in `.ia-qa/`: contracts, baseline, `usage.json` (your suite's locators), and `pal/` (the measured pace, findings already reported, the current run and its log). A saved session there holds live cookies — it is gitignored and never leaves your machine.

package/TUTORIAL.md

@@ -0,0 +1,375 @@
+# ia-qa-pal — tutorial
+
+`@ia-qa/pal` is a QA pal **next to** your team. It does the routine rounds nobody has time for — walk the whole app, map every page, check it, compare it with the last round — and hands a person only what needs a person.
+
+It is not a QA engineer. It does not know what your app *should* do, so it never judges business behaviour. It knows what your app *did* yesterday, what is broken in a way any app can be broken (a dead link, a control nobody can name), and — the part most tools leave out — **what it could not see**.
+
+Everything runs on your machine, in a headless browser. Nothing is uploaded. No LLM decides anything.
+
+---
+
+## 1. Install
+
+Node 18 or newer.
+
+```bash
+npm i -D @ia-qa/pal
+npx playwright install chromium
+```
+
+Check it answers:
+
+```bash
+npx ia-qa-pal --help
+```
+
+---
+
+## 2. The first tour
+
+In your project folder:
+
+```bash
+npx ia-qa-pal tour
+```
+
+The project is not set up yet, so the tour asks first: where the app lives, how it logs in, and — only when it finds a test suite in the folder — whether to read it (section 7).
+
+```
+This project is not set up yet — a few questions first.
+
+Where does the app live? (https://…) https://www.ia-qa.com
+Does the app ask you to log in?
+  1  no
+  2  yes — I log in by hand in a browser (SSO, MFA, anything)
+  3  yes — my test suite already saves a Playwright storageState file
+Choice [1-3]: 1
+🗺  Reading www.ia-qa.com/sitemap.xml (and robots.txt) — a plain fetch, nothing else.
+   Found 146 pages.
+
+📄 This writes /home/me/shop/.ia-qa/config.json
+   app      https://www.ia-qa.com
+   pages    146 from the sitemap: home, all-tools, method, resources, articles, veille, mcp-server, mcp-registry, +138 more
+   login    none
+   Nothing else is written. No field holds a secret.
+Write it? [y/N] y
+```
+
+- **The pages come from your `sitemap.xml`.** No sitemap? It follows the links from your home page instead — same host, GET only, at most 50 pages, never a link that acts (`/logout`, `/delete`…).
+- **It shows the file before writing it**, and what it shows is exactly what it writes. It never overwrites an existing config.
+- **No question takes a password.**
+
+Then the tour runs:
+
+1. **Surface** — every page, loaded, no clicks. On a real site this is about 1.7 s a page.
+2. **Depth** — the first 10 pages that have closed menus, tabs, accordions or dialogs are explored: each is opened, and what it reveals goes into the page's contract. About 20 s a page, and it grows with the number of controls.
+3. **Checks** — dead links, controls without an accessible name, names shared by several controls, pages nothing links to.
+4. **Baseline** — what the app is today becomes the reference for tomorrow.
+
+---
+
+## 3. Reading the first report
+
+A real first tour, on a 9-page app behind a login:
+
+```
+ia-qa-pal tour — https://www.nodemented.com · level 1 (with a login)
+📌 Baseline established — nothing to compare yet. The next tour measures drift against it.
+   9 of 9 pages under contract · 8 explored in depth of 8 pages with closed controls
+
+⛔ To decide
+   new     14 elements without an accessible name — e.g. alert #\31  on billing
+   new     7 names shared by several elements — e.g. button "🎥" ×10 on feature-manager
+   new     8 pages nothing links to — admin-dashboard, billing, cookies, …
+   Full list: ia-qa-heal check. Warnings never fail the tour.
+```
+
+Every page fit in the first batch, so nothing was left unexplored. On a larger app the report ends with what the tour did not reach — illustrative numbers:
+
+```
+🔍 Not seen
+   136 pages with closed controls not explored yet — about 47 min (3000 controls × 0.94 s, pace measured on 142 clicks)
+      ia-qa-pal tour --more    explores the next batch
+```
+
+The report has at most four sections, and each one appears only when it holds something:
+
+| section | what it holds | what you do |
+|---|---|---|
+| 🔴 **Broken in the app** | links your app itself answers with an error | fix the link |
+| ⛔ **To decide** | drift that blocks, and findings seen for the first time | a person looks |
+| 🔧 **Ready to repair** | *(coming with test-suite support)* | |
+| 🔍 **Not seen** | pages not explored, not mapped, only partly explored, links it could not verify | decide whether it matters |
+
+Three things are worth knowing about this first report:
+
+- **It is not a pass.** Nothing was compared — there was nothing to compare with. The headline says so.
+- **The denominator is always there.** `10 explored in depth of 146` is the honest number; `10 pages explored` would not be.
+- **The time estimate is measured, not assumed.** It only appears once a batch has run on *your* app, and it prints what it rests on.
+
+---
+
+## 4. The next tours
+
+Change nothing, or deploy something, and run it again:
+
+```bash
+npx ia-qa-pal tour
+```
+
+The same app, the next tour:
+
+```
+ia-qa-pal tour — https://www.nodemented.com · level 1 (with a login)
+✅ PASS · 358 ok · 0 renamed · 0 lost · 0 ambiguous · 0 rebound
+   9 of 9 pages under contract · 8 explored in depth of 8 pages with closed controls
+   29 warnings already reported — not listed again.
+```
+
+Each page is captured again **the way its baseline was captured** — on the surface, or opened in depth — and compared with it. A finding already reported is counted, not listed again: a list that never shrinks stops being read by the third tour.
+
+When something moved (illustrative):
+
+```
+⛔ BLOCK · 1937 ok · 0 renamed · 1 lost · 0 ambiguous · 0 rebound
+
+⛔ To decide
+   drift   settings: 1 lost · 0 ambiguous · 0 rebound
+```
+
+What the words mean:
+
+| word | meaning |
+|---|---|
+| `renamed` | the same control, relabelled. Reported, never blocking. |
+| `lost` | a control that is gone. |
+| `ambiguous` | several controls now answer to the same description — choosing would be guessing. |
+| `rebound` | a selector that used to reach one control now reaches **another**. A test using it would pass while clicking the wrong thing. |
+
+A label that changes on its own every run — a counter, a date, a generated value — comes back as `renamed` every time. Tell it apart once in `.ia-qa/config.json`:
+
+```json
+"nameMask": ["Cart (*)"]
+```
+
+The control stays under contract; only its label is no longer compared.
+
+### Exit codes
+
+| code | meaning |
+|---|---|
+| `0` | nothing needs a decision — warnings never fail a tour |
+| `1` | a dead link, or drift that blocks |
+| `2` | no answer: not set up, nothing could be mapped, or the tour refused to run |
+
+Read `2` as "could not answer", never as "the app is broken".
+
+---
+
+## 5. Exploring the rest
+
+```bash
+npx ia-qa-pal tour --more
+```
+
+```
+# illustrative
+🔍 10 pages explored in depth and promoted to the baseline: resources, articles, …
+```
+
+`--more` explores the next batch and adds those pages to the baseline. Run it when you have the time — the estimate told you how much. `--batch <n>` changes the batch size.
+
+It **refuses** when the last tour ended on BLOCK:
+
+```
+⏸  Did not run — The last tour ended on BLOCK. Exploring now would promote those pages as they are today and accept that drift unseen — resolve it, then run `ia-qa-pal tour` again.
+```
+
+Promoting a page to the baseline says "this is how it should be". Doing that while something unexplained changed would accept the change without anyone looking at it.
+
+---
+
+## 6. Behind a login
+
+The second setup question has three answers.
+
+**By hand in a browser** — for SSO, MFA, a consent screen, a magic link, anything:
+
+```bash
+npx -p @ia-qa/self-healing ia-qa-heal login
+```
+
+A visible browser opens, you log in, and the session is saved in `.ia-qa/session.json`. That file holds live cookies: it is gitignored and never leaves your machine. When it expires, the pages behind the login show up in **Not seen** — never as a pass.
+
+Pages found during setup were found without logging in. Once logged in, list the ones behind the login:
+
+```bash
+npx -p @ia-qa/self-healing ia-qa-heal discover --crawl --apply
+```
+
+**Your test suite already saves a session** — most authenticated Playwright suites write a `storageState` in `globalSetup`. Give its path; only the path is written:
+
+```bash
+npx ia-qa-pal setup --url https://staging.shop.example --login session --session playwright/.auth/user.json --yes
+```
+
+**A login form filled from environment variables** is set up with `npx -p @ia-qa/self-healing ia-qa-heal init`, which writes the variable *names*, never their values.
+
+---
+
+## 7. With your test suite
+
+A tour already tells you what changed in the app. With your end-to-end suite declared, it also tells you what that change does to **your tests**.
+
+Declare it once — the setup offers it when it finds a `tests/`, `e2e/` or `cypress/e2e/` folder with specs, or with flags:
+
+```bash
+npx ia-qa-pal setup --url https://staging.shop.example --login none --tests tests --yes
+```
+
+The command that runs the suite is detected from `package.json` (`test:e2e`, `e2e`…) or a `playwright.config`; set it yourself with `--test-command "npm run test:e2e"`.
+
+From then on, every tour reads the suite's locators before capturing, and the report gains three things.
+
+**🔧 Ready to repair.** A selector your tests write stopped reaching its element — the class changed, a `data-testid` was added — while the element itself is still on the page (illustrative):
+
+```
+🔧 Ready to repair (1 replacement in 1 file)
+   tests/settings.spec.js:17   .btn-primary → #prefs > button:nth-of-type(1)
+   Apply after review: npx -p @ia-qa/self-healing ia-qa-heal fix   (pal never edits your tests)
+```
+
+pal only lists it. `ia-qa-heal fix` computes the same rewrite and applies it — review it with `git diff` before committing. A rewrite that could break a passing test (two pages wanting the same string to become two different things, an XPath inside `By.xpath`) is left out and named, never guessed.
+
+**⛔ To decide.** Locator names your tests use that nothing on the mapped pages carries — `getByRole('button', { name: 'Save' })` when no button is called Save anymore — with `file:line`. It is advisory: the name may live on a page or in a state the tour did not map. And when a label your tests locate by name was renamed, the tour says so.
+
+**🔍 Which pages your suite never visits.** This one needs the suite to run:
+
+```bash
+npx ia-qa-pal tour --suite
+```
+
+It runs the `testCommand` from your config once, with the capture hook armed, and keeps only the list of pages the suite really opened — its capture never mixes with the tour's contracts. The answer stays in the report until the next `--suite` (illustrative):
+
+```
+🔍 Not seen
+   your suite never visits 14 of 17 pages (run of 2026-09-15): faq, jeu-galaxie, jeu-classement, …
+```
+
+Your specs need the capture hook — one import, a drop-in for Playwright's own:
+
+```js
+import { test, expect } from '@ia-qa/self-healing/capture';
+```
+
+Without it, the report says the suite ran but recorded no page, and names the import. It never says your suite visits nothing. If the suite fails during `--suite`, the tour reports it under **Broken** and exits `1`.
+
+---
+
+## 8. In the background
+
+A tour on a large app takes a while. Start it and get your terminal back:
+
+```bash
+npx ia-qa-pal tour --background
+npx ia-qa-pal status
+```
+
+```
+⏳ A tour is running (pid 34136, since 2026-09-15T14:04:32Z) — depth 4/10 · jeu-planete
+```
+
+When it is done, `status` prints the report. Only one tour runs per project: a second is refused while the first is alive, because two tours would write the same contracts. A tour whose process died before finishing is reported as **interrupted** — never as still running, never as a result. Its output is in `.ia-qa/pal/run.log`.
+
+---
+
+## 9. In CI
+
+Build the baseline on your machine, commit it, and let CI compare.
+
+```bash
+git add .ia-qa/config.json .ia-qa/baseline .ia-qa/pal/state.json
+git commit -m "ia-qa-pal baseline"
+```
+
+Never commit `.ia-qa/session.json`.
+
+```yaml
+- run: npm ci
+- run: npx playwright install chromium
+- run: npx ia-qa-pal tour --json > pal-report.json
+```
+
+- With the baseline committed, a tour in CI is a regression tour: it never grows the baseline. (Without one, it would run a first tour and write a baseline nobody reviewed — commit it first.) A green run over 10 pages and a green run over 20 do not say the same thing, so the reference changes only when a person runs `--more` or promotes it.
+- `--json` puts the whole report on stdout; progress stays on stderr.
+- Gate on the exit code: `1` fails the build, `2` means the job could not answer — report it as a broken job, not as a broken app.
+- Setting up from CI takes flags and never asks: `ia-qa-pal setup --url … --login none --yes`.
+
+---
+
+## 10. With an AI agent
+
+An agent can drive `ia-qa-pal` from a shell, or through its local MCP server:
+
+```json
+{ "mcpServers": { "ia-qa-pal": { "command": "npx", "args": ["-y", "-p", "@ia-qa/pal", "ia-qa-pal-mcp"] } } }
+```
+
+| tool | what it does |
+|---|---|
+| `pal_project` | is the project set up, its level, its baseline, a tour running? |
+| `pal_setup` | writes the config from **your** answers — never overwrites one |
+| `pal_tour` | starts a tour in the background and returns at once, so no client times out |
+| `pal_status` | progress, then the full report |
+
+No tool takes a command — your test command comes from your config, which you wrote — and there is no login tool.
+
+The rules the agent must follow are also in `ia-qa-pal --help`:
+
+- **Read "Not seen".** A clean tour over part of an app is not a clean app, and the agent must say which part was not seen.
+- **A first tour is not a pass.** It established the baseline.
+- **Never answer a setup question for you, and never run `ia-qa-heal login`.** That command waits for a person at a browser; the agent gives it to you instead.
+- **Never apply a proposed repair without your review, and never add `--suite` without asking** — it runs your suite on your machine.
+
+Asked to tour a project that is not set up, `ia-qa-pal tour --json` answers with what is missing rather than guessing:
+
+```json
+{
+  "refused": "This project is not set up yet — there is no .ia-qa/config.json.",
+  "setupRequired": {
+    "missing": ["url", "login"],
+    "command": "ia-qa-pal setup --url https://your-app.example --login none --yes"
+  },
+  "exitCode": 2
+}
+```
+
+---
+
+## 11. What it touches
+
+- **Only your app.** Its pages load whatever they load in any browser (fonts, analytics…).
+- **Exploration is read-only.** While menus, tabs and dialogs are opened, every non-GET request is blocked, and controls named like actions (log out, delete, pay, send…) are never clicked.
+- **The link check** requests your app's own links with GET and skips any URL that acts.
+- **Your test files are read, never written.** Your test command runs only with `--suite`.
+- **Files** live in `.ia-qa/`: `config.json`, `mapping/` (today), `baseline/` (the reference), `usage.json` (your suite's locators), `pal/state.json` (the measured pace, the findings already reported, the last `--suite` run), `pal/run.json` and `pal/run.log` (the current or last tour).
+
+---
+
+## 12. When something looks wrong
+
+**A page is "not mapped" with a timeout.** One slow page costs that page, not the tour. It stays in **Not seen**; if its drift is shown, the report marks it as an older capture.
+
+**Every page behind the login is "not mapped".** The session expired, or never worked. Log in again with `ia-qa-heal login`, then run the tour.
+
+**`renamed` on a label you did not touch.** A counter, a date or generated content. Add a `nameMask` for it (section 4).
+
+**"only partly explored (click budget reached)".** The page has more closed controls than one exploration opens (150 clicks). Its contract covers part of the page, and the report says so.
+
+**"A tour is already running" but nothing is.** Run `ia-qa-pal status`: a tour whose process died shows as interrupted, and the next tour starts normally.
+
+**"your suite ran but recorded no page".** Your specs do not import the capture hook (section 7).
+
+---
+
+`ia-qa-pal` is built on [`@ia-qa/self-healing`](https://www.npmjs.com/package/@ia-qa/self-healing): the verdicts it prints are the ones `ia-qa-heal diff` and `ia-qa-heal check` compute, so the two never disagree.