@ia-qa/self-healing 0.5.1 → 0.7.0

package/README.md

@@ -6,6 +6,23 @@ Self-healing E2E toolkit: a **local MCP server** for AI agents, a guided **CLI**
 
 **It runs entirely on the end user's machine.** It brings its own headless Chromium, so it sees `localhost`, staging, or an app behind a VPN — and **no data ever leaves the machine**. Nothing is hosted.
 
+## Quick start
+
+```bash
+npx -y -p @ia-qa/self-healing ia-qa-heal init      # wizard → .ia-qa/config.json
+npx -y -p @ia-qa/self-healing ia-qa-heal map      # → .ia-qa/mapping/<page>.json + .md
+npx -y -p @ia-qa/self-healing ia-qa-heal baseline # → .ia-qa/baseline/ — the reference. Commit it.
+#   …change the app, then `map` again…
+npx -y -p @ia-qa/self-healing ia-qa-heal diff     # baseline/ vs mapping/ → PASS / FIX / BLOCK
+```
+
+Install it in the project that holds your tests to drop the `-p` dance — and to get the `aiClick` / `aiFill` runtime helpers, which are imported, not run:
+
+```bash
+npm i -D @ia-qa/self-healing
+npx ia-qa-heal init
+```
+
 ## Two front doors, one engine
 
 | | For | Entry point |
@@ -24,8 +41,8 @@ Agent config (Claude Code / Desktop, Cursor…):
   }
 }
 ```
-`-p` is required, not cosmetic: the package ships **two** bins (`ia-qa-heal`, `ia-qa-heal-mcp`), so `npx @ia-qa/self-healing …` cannot resolve which to run and silently starts nothing. Verified against a packed tarball.
-The MCP server is a dependency-free JSON-RPC 2.0 stdio implementation (`src/mcp/server.ts`) — no SDK, matching the repo's zero-dep client ethos. It does **not** require the separate Playwright MCP: it drives its own browser. stdout is the protocol channel; logs go to stderr.
+`-p` is required, not cosmetic: the package ships **two** bins (`ia-qa-heal`, `ia-qa-heal-mcp`), so `npx @ia-qa/self-healing …` cannot resolve which to run and silently starts nothing.
+The MCP server is a dependency-free JSON-RPC 2.0 stdio implementation (`src/mcp/server.ts`) — no SDK. It does **not** require the separate Playwright MCP: it drives its own browser. stdout is the protocol channel; logs go to stderr.
 
 ### Browser reuse — no second Chromium (`src/launcher.ts`)
 Playwright's browser cache is **machine-wide and shared** (`%LOCALAPPDATA%\ms-playwright`, `~/.cache/ms-playwright`). If the user already has *any* Playwright install — their own tests or the Playwright MCP — the bundled Chromium is already there and we reuse it for free. There is no "second Chromium" to avoid; the only real cost is **revision skew** (a different Playwright version pins a different Chromium revision). For that case, and for machines that forbid the download, the launcher resolves in this order:
@@ -53,32 +70,30 @@ Only if all four fail does it error, listing the three fixes. `map_app` exposes
    ```
    The `<page>.md` groups elements by role and carries a self-describing header telling a model exactly how to use it. **The CI auto-heal loop:** when a UI test fails, hand the failing test file + the current `<page>.md` to an LLM — it finds the element by role + accessible name, reads the current selector, and rewrites the test in **whatever framework and language** it is written in (Cypress, Playwright, Selenium; JS or Python). The contract is the source of truth; the model handles the syntax. The same contract is downloadable from the zero-install **Selector Drift Detector** page on ia-qa.com.
 
-   `map` also rebuilds **`.ia-qa/mapping/_overview.md`** — the app index, and the file to open first. Forty-seven page contracts answer "what is on this page?"; none of them answers "what is this app, and which contract do I need?". The overview does: every page with its URL, element count and a link to its contract; the shared layout; and the surface by role. It also surfaces two things no single contract can — same-origin destinations your app links to but your config never maps (the coverage gap), and the external domains you link out to. It is derived entirely from the mappings on disk (no extra page visit) and is rebuilt on every `map`, including `map <page>`, so it never drifts out of date.
-
-   When pages link to each other, `map` writes the **navigation graph** next to it, built from link `href`s: **`_navigation.md`** (a Mermaid fence — GitHub, GitLab and the VS Code preview render it natively) and **`_navigation.svg`** (the same graph, hand-rolled, opening in any browser offline — no mermaid.js, no CDN, nothing fetched).
+   Alongside the page contracts, `map` rebuilds the app index and the navigation graph — see [Map artifacts](#map-artifacts).
+3. **`ia-qa-heal baseline`** — promote `.ia-qa/mapping/` to `.ia-qa/baseline/`, the reference `diff` compares against. Commit it: a reference that is not in git cannot be reviewed or reverted, and accepting drift is a code-review decision like any other.
 
-   The graph draws **what a page table cannot tell you: pages that link to each other**. Three things are deliberately left out, on one principle — a picture should not spend ink on what the page list already says:
-   - **shell links** (navbar, footer) — in the overview, listed once, instead of an edge from every page to every navbar destination;
-   - **isolated pages** — a box with no arrow;
-   - **hub fans** — a page whose 144 spokes link nowhere else is stated in one sentence (`home` fans out to 144 pages) instead of drawn as 144 identical arrows crossing every other line. That is the catalogue shape, and no node-link diagram survives it.
+   Drift is a claim about **two moments**, and `map` only ever captures one. Promotion is the second half, and it is a separate verb on purpose — deliberately *not* a flag on `map`, because promoting in the same breath as capturing would make the reference incapable of ever being older than what it is compared to. `map` records what the app **is**; `baseline` says it is also what the app is **supposed to be**. That second claim is a human judgement.
 
-   What is left is the real structure: a checkout tunnel stays, its noise does not. If nothing survives, both files are removed rather than left stale — for that app, the page list genuinely is the whole story.
-3. **`ia-qa-heal diff <before.json> <after.json>`** — CI-gate verdict. Diffs two mappings (from `map` or the ia-qa.com browser snippet) and reports which selectors survived, which the runtime healer would recover, and which will hard-fail:
+   Skip it and the natural workaround is `cp current.json baseline.json && diff` — which compares a capture to a copy of itself and prints `PASS ✅ No drift`. That verdict is green because nothing was compared, not because nothing changed. `diff` now refuses it outright (exit `2`): every side carries a `capturedAt`, equal timestamps mean one `map` run, and one run cannot drift from itself. A gate that reports green without looking is worse than no gate, because it is trusted.
+4. **`ia-qa-heal diff [before.json] [after.json]`** — CI-gate verdict. With no arguments, diffs `baseline/` against `mapping/` — the everyday case. Diffs two mappings (from `map` or the ia-qa.com browser snippet) and reports which selectors survived, which the runtime healer would recover, and which will hard-fail:
    ```
    ⛔  BLOCK
       before.json → after.json  ·  3 ok · 2 healable · 1 lost · 2 new
       🔧 healable  button "Se connecter"      button#login-btn → button.btn-primary (exact name)
       ⛔ lost      button "Supprimer le compte"  button#delete → (no match)
    ```
-   Exit codes for pipelines: `0` = PASS or FIX, `1` = BLOCK — lost, ambiguous, or rebound (add `--strict` to fail on FIX too), `2` = bad input. Use `--json` for machine-readable output. Same diff engine as the web tool (`src/browser/match.js`).
+   Exit codes for pipelines: `0` = PASS or FIX, `1` = BLOCK — lost, ambiguous, or rebound (add `--strict` to fail on FIX too), `2` = bad input, no baseline, or nothing to compare. Use `--json` for machine-readable output. Same diff engine as the web tool (`src/browser/match.js`).
+
+   A contract that was **not re-mapped** since the baseline carries the baseline's own `capturedAt`, so it cannot show drift. Those are listed and left **out** of the verdict rather than counted as `ok` — padding a gate with comparisons that never happened is the same lie in smaller print. `--json` reports them as `staleExcluded`.
 
    Every element carries a **context** (nearest landmark + section heading) so two elements with the same role + accessible name (five "Delete" buttons) stay distinguishable. The diff classifies each baseline element as `ok`, `renamed` (same element, new accessible name — a *content* drift to eyeball), `healable` (deterministic old→new rewrite), `ambiguous` (several equal matches — the tool **refuses to guess**, a human decides), or `lost` (no match).
 
    Identity comes from the contract (role + accessible name), never from the selector string. A selector that still resolves only proves the *position* is still occupied: insert one button above a tab bar and every `nth-of-type` below it silently slides onto its neighbour. Any row where that happened is flagged `rebound` — the old selector resolves, but to a **different element**, so the suite is green while clicking the wrong thing. Rebound rows are rewritten like any other healable row, and they **BLOCK**: a `FIX` verdict exits `0`, which is exactly how this ships unnoticed.
-4. **`ia-qa-heal fix <before.json> <after.json> <test-paths…>`** — the deterministic half. Applies **only** the `healable` rewrites to your test files, replacing the selector only where it appears as a quoted string literal (`'…'`/`"…"`/`` `…` ``, quote-safe for attribute selectors), across any framework/language. Every rewrite is applied in a single pass against the selector each occurrence had in the file, so a *permuted* set (`nth-of-type(1)→(2)`, `(2)→(3)`) can never chain and drag `(1)` to `(3)`. LOST / AMBIGUOUS / RENAMED are printed but never touched — they need judgment. It **edits the working tree and never commits**: review with `git diff`, then push or discard. `--dry-run` previews the plan. This is "prepare the ground, the human decides" as a command.
+5. **`ia-qa-heal fix <before.json> <after.json> <test-paths…>`** — the deterministic half. Applies **only** the `healable` rewrites to your test files, replacing the selector only where it appears as a quoted string literal (`'…'`/`"…"`/`` `…` ``, quote-safe for attribute selectors), across any framework/language. Every rewrite is applied in a single pass against the selector each occurrence had in the file, so a *permuted* set (`nth-of-type(1)→(2)`, `(2)→(3)`) can never chain and drag `(1)` to `(3)`. LOST / AMBIGUOUS / RENAMED are printed but never touched — they need judgment. It **edits the working tree and never commits**: review with `git diff`, then push or discard. `--dry-run` previews the plan. This is "prepare the ground, the human decides" as a command.
 
    **`--locators`** rewrites to a Playwright role locator — `page.getByRole('button', { name: 'Validator' })` — instead of a selector, wherever role + accessible name identifies exactly one element. A repaired positional selector is only correct until the next insertion; a role locator is what the contract already means, so it does not drift at all. Applies to `.js`/`.ts` files and Playwright call shapes (`page.click('…')`, `page.locator('…')`, `page.fill('…', v)`, …); every other file and every element without an unambiguous role + name keeps the plain selector rewrite. `getByRole` is strict, so a locator is emitted only when it provably resolves to one element — otherwise the tool would trade a silent wrong click for a loud crash.
-5. **Runtime healing** — in your Playwright tests:
+6. **Runtime healing** — in your Playwright tests:
    ```ts
    import { aiClick, aiFill } from '@ia-qa/self-healing';
 
@@ -87,6 +102,21 @@ Only if all four fail does it error, listing the three fixes. `map_app` exposes
    ```
    If the selector fails, the helper re-scans the live page, matches the element by role + accessible name (exact, then fuzzy Dice ≥ 0.6 — or your own `llmResolver`), retries on the healed selector, and logs a warning telling you to update the test and re-map.
 
+## Map artifacts
+
+Beyond one contract per page, every `map` run rebuilds two views of the whole app. Both are derived entirely from the mappings on disk (no extra page visit) and rebuilt on every run, including `map <page>`, so they never drift out of date.
+
+**`.ia-qa/mapping/_overview.md`** — the app index, and the file to open first. Every page contract answers "what is on this page?"; none of them answers "what is this app, and which contract do I need?". The overview does: every page with its URL, element count and a link to its contract; the shared layout; and the surface by role. It also surfaces two things no single contract can — same-origin destinations your app links to but your config never maps (the coverage gap), and the external domains you link out to.
+
+**`_navigation.md` / `_navigation.svg`** — the navigation graph, written when pages link to each other, built from link `href`s. The `.md` is a Mermaid fence (GitHub, GitLab and the VS Code preview render it natively); the `.svg` is the same graph, hand-rolled, opening in any browser offline — no mermaid.js, no CDN, nothing fetched.
+
+The graph draws **what a page table cannot tell you: pages that link to each other**. Three things are deliberately left out, on one principle — a picture should not spend ink on what the page list already says:
+- **shell links** (navbar, footer) — in the overview, listed once, instead of an edge from every page to every navbar destination;
+- **isolated pages** — a box with no arrow;
+- **hub fans** — a page whose spokes link nowhere else is stated in one sentence (`home` fans out to 144 pages) instead of drawn as 144 identical arrows crossing every other line. That is the catalogue shape, and no node-link diagram survives it.
+
+What is left is the real structure: a checkout tunnel stays, its noise does not. If nothing survives, both files are removed rather than left stale — for that app, the page list genuinely is the whole story.
+
 ## Design notes
 
 - `page.accessibility.snapshot()` is deprecated **and returns no selectors**, so mapping walks the DOM directly and computes ARIA role + accname + a stable selector (`data-testid` → `id` → `name` → short structural path).
@@ -94,7 +124,15 @@ Only if all four fail does it error, listing the three fixes. `map_app` exposes
 - Secrets: never written to disk. `env` reads `process.env`; `aws-ssm` calls `GetParameter` with decryption using the AWS SDK default credential chain (needs `ssm:GetParameter`, plus `kms:Decrypt` for SecureString).
 - `llmResolverStub` in `src/playwright/healer.ts` is the extension point for a real LLM/embedding-based resolver (e.g. via `POST https://www.ia-qa.com/mcp/call`).
 
-## Build & run
+## Peer dependencies
+
+`playwright` is a peer dependency — the consuming test project provides it (`npx playwright install chromium` if needed). This is deliberate: bundling our own copy would let a project on a different Playwright version end up with two installs and a browser-revision skew, which is exactly what the shared launcher exists to avoid.
+
+`@aws-sdk/client-ssm` is an **optional** peer, needed only by the `aws-ssm` secret source. It is ~5 MB and imported lazily, so it is not a tax on installs that use the `env` source: `npm i @aws-sdk/client-ssm` if you want SSM, and the CLI tells you so if you pick it without.
+
+## Build from source
+
+For work on the package itself — installing from npm needs none of this.
 
 ```bash
 cd packages/self-healing
@@ -102,7 +140,3 @@ npm run build          # tsc → dist/
 node dist/cli/index.js init
 node dist/cli/index.js map
 ```
-
-`playwright` is a peer dependency — the consuming test project provides it (`npx playwright install chromium` if needed). This is deliberate: bundling our own copy would let a project on a different Playwright version end up with two installs and a browser-revision skew, which is exactly what the shared launcher exists to avoid.
-
-`@aws-sdk/client-ssm` is an **optional** peer, needed only by the `aws-ssm` secret source. It is ~5 MB and imported lazily, so it is not a tax on installs that use the `env` source: `npm i @aws-sdk/client-ssm` if you want SSM, and the CLI tells you so if you pick it without.

package/TUTORIAL.md

@@ -165,10 +165,12 @@ The agent launches a browser in the background and gives you back something like
 | Valider         | main › Paiement  | `button[data-testid="pay"]` |
 ```
 
-**That's your baseline.** Commit it — it lives in git like code:
+**That's a capture of what the app is right now.** To make it the reference everything is
+measured against, promote it — then commit both, they live in git like code:
 
 ```bash
-git add .ia-qa/mapping
+npx ia-qa-heal baseline          # .ia-qa/mapping → .ia-qa/baseline
+git add .ia-qa/mapping .ia-qa/baseline
 git commit -m "Add page contract baseline"
 ```
 
@@ -238,13 +240,28 @@ Commit them.
 Here's the loop you'll actually live in.
 
 ### Step 6.1 — You have a baseline
-From step 4.4 or 5.3, committed to git. Call it `checkout.baseline.json` (just copy it):
+From step 4.4 or 5.3: promoted with `ia-qa-heal baseline` and committed to git.
 
 ```bash
-cp .ia-qa/mapping/checkout.json .ia-qa/mapping/checkout.baseline.json
-git add .ia-qa/mapping && git commit -m "baseline"
+npx ia-qa-heal baseline
+git add .ia-qa/mapping .ia-qa/baseline && git commit -m "baseline"
 ```
 
+Promotion is its own step because **drift is a claim about two moments**, and `map` only
+ever captures one. `map` records what the app *is*; `baseline` says it is also what the app
+is *supposed to be*. That second claim is yours to make, so it gets its own command.
+
+Do it now and `diff` will refuse — correctly. Nothing has been re-mapped, so both sides are
+the same capture, and a capture cannot drift from itself:
+
+```
+❌ Nothing to compare: all 2 pairs are the same capture on both sides.
+```
+
+That refusal *is* the feature. The obvious shortcut — copy the file, diff against the copy —
+prints `PASS ✅ No drift — your suite is safe to run`, which sounds like an answer and is
+not one: nothing was compared. A green gate that never looked is worse than no gate.
+
 ### Step 6.2 — Someone changes the UI
 A developer ships a redesign. Your tests start failing. **Normal.**
 
@@ -256,18 +273,22 @@ Terminal: `npx ia-qa-heal map checkout`
 Agent: **"Diff the baseline against the new contract"**
 Terminal:
 ```bash
-npx ia-qa-heal diff .ia-qa/mapping/checkout.baseline.json .ia-qa/mapping/checkout.json
+npx ia-qa-heal diff          # baseline/ against mapping/ — no arguments needed
 ```
 
+Now there are two moments, so there is a verdict. Any page you did **not** re-map still
+carries the baseline's own timestamp; it is listed and left out of the verdict rather than
+counted as `ok`, because it was never compared either.
+
 ### Step 6.5 — Apply the safe fixes
 Agent: **"Fix my tests in the tests/ folder using that diff"**
 Terminal:
 ```bash
 # Preview first — nothing is written
-npx ia-qa-heal fix .ia-qa/mapping/checkout.baseline.json .ia-qa/mapping/checkout.json tests/ --dry-run
+npx ia-qa-heal fix .ia-qa/baseline/checkout.json .ia-qa/mapping/checkout.json tests/ --dry-run
 
 # Do it
-npx ia-qa-heal fix .ia-qa/mapping/checkout.baseline.json .ia-qa/mapping/checkout.json tests/
+npx ia-qa-heal fix .ia-qa/baseline/checkout.json .ia-qa/mapping/checkout.json tests/
 ```
 
 ### Step 6.5b — Stop fixing the same test twice (`--locators`)
@@ -351,9 +372,14 @@ jobs:
         run: npx ia-qa-heal map
 
       - name: Fail if selectors drifted with no safe fix
-        run: npx ia-qa-heal diff .ia-qa/mapping/checkout.baseline.json .ia-qa/mapping/checkout.json
+        run: npx ia-qa-heal diff
 ```
 
+`diff` with no arguments compares the committed `.ia-qa/baseline/` against the `.ia-qa/mapping/`
+the previous step just re-captured — which is why the baseline has to be in git for CI to have
+anything to check out. It exits `2` if there is no baseline, or if nothing was re-mapped, so a
+misconfigured job fails loudly instead of passing without comparing anything.
+
 Add `--strict` if you want **FIX** to fail the build too (forces tests to be updated, not just healed).
 
 ---
@@ -419,9 +445,11 @@ Yes, any URL your machine can reach.
 ```bash
 npx ia-qa-heal init                       # one-time setup
 npx ia-qa-heal map                        # scan → *.json + *.md + _overview.md + _navigation.md/.svg
-npx ia-qa-heal diff before.json after.json    # verdict: PASS / FIX / BLOCK
-npx ia-qa-heal fix before.json after.json tests/ --dry-run   # preview
-npx ia-qa-heal fix before.json after.json tests/             # apply (never commits)
+npx ia-qa-heal baseline                   # promote mapping/ → baseline/ (commit it)
+#   …change the app, then `map` again…
+npx ia-qa-heal diff                       # verdict: PASS / FIX / BLOCK (baseline/ vs mapping/)
+npx ia-qa-heal fix .ia-qa/baseline/checkout.json .ia-qa/mapping/checkout.json tests/ --dry-run   # preview
+npx ia-qa-heal fix .ia-qa/baseline/checkout.json .ia-qa/mapping/checkout.json tests/             # apply (never commits)
 ```
 
 Talking to an agent instead:

package/dist/aom.d.ts

@@ -23,6 +23,30 @@ export interface PageMapping {
     capturedAt: string;
     elements: MappedElement[];
 }
+/**
+ * Did these two mappings come out of the same `map` run?
+ *
+ * `capturedAt` is stamped once per page per run, so equality means one capture is being
+ * compared to a copy of itself. That is what a hand-rolled baseline (`cp current.json
+ * baseline.json && diff`) always produces on its first run, and the diff of a file against
+ * itself is `PASS · N ok · 0 healable` — printed under "✅ No drift — your suite is safe to
+ * run". Every word of that is false: nothing was compared, so nothing is known about the
+ * suite. A green gate that never looked is worse than no gate, because it is trusted.
+ *
+ * Two real `map` runs collide only if stamped on the same millisecond, which does not
+ * happen across the app changes a drift check exists to find. A *missing* timestamp is
+ * malformed input, not a self-comparison: two `undefined`s share nothing meaningful, and
+ * blocking on them would refuse a legitimate diff over a field the diff never reads.
+ *
+ * Lives here rather than beside either caller because both doors into the diff — the CLI
+ * and the MCP server — have to agree on what is not a comparison. One guarding and the
+ * other not would just move the false green to whichever door the user knocked on.
+ */
+export declare function isSameCapture(baseline: {
+    capturedAt?: string;
+} | null | undefined, current: {
+    capturedAt?: string;
+} | null | undefined): boolean;
 export declare function extractInteractiveElements(page: Page): Promise<MappedElement[]>;
 export declare function saveMapping(mapping: PageMapping, dir?: string): string;
 export declare function loadMapping(pageName: string, dir?: string): PageMapping;

package/dist/aom.js

@@ -33,12 +33,35 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSameCapture = isSameCapture;
 exports.extractInteractiveElements = extractInteractiveElements;
 exports.saveMapping = saveMapping;
 exports.loadMapping = loadMapping;
 const fs = __importStar(require("fs"));
 const config_1 = require("./config");
 const extract_1 = require("./browser/extract");
+/**
+ * Did these two mappings come out of the same `map` run?
+ *
+ * `capturedAt` is stamped once per page per run, so equality means one capture is being
+ * compared to a copy of itself. That is what a hand-rolled baseline (`cp current.json
+ * baseline.json && diff`) always produces on its first run, and the diff of a file against
+ * itself is `PASS · N ok · 0 healable` — printed under "✅ No drift — your suite is safe to
+ * run". Every word of that is false: nothing was compared, so nothing is known about the
+ * suite. A green gate that never looked is worse than no gate, because it is trusted.
+ *
+ * Two real `map` runs collide only if stamped on the same millisecond, which does not
+ * happen across the app changes a drift check exists to find. A *missing* timestamp is
+ * malformed input, not a self-comparison: two `undefined`s share nothing meaningful, and
+ * blocking on them would refuse a legitimate diff over a field the diff never reads.
+ *
+ * Lives here rather than beside either caller because both doors into the diff — the CLI
+ * and the MCP server — have to agree on what is not a comparison. One guarding and the
+ * other not would just move the false green to whichever door the user knocked on.
+ */
+function isSameCapture(baseline, current) {
+    return Boolean(baseline?.capturedAt) && baseline.capturedAt === current?.capturedAt;
+}
 async function extractInteractiveElements(page) {
     return page.evaluate(extract_1.extractInPage);
 }

package/dist/aom.js.map

@@ -1 +1 @@
-{"version":3,"file":"aom.js","sourceRoot":"","sources":["../src/aom.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,gEAEC;AAED,kCAKC;AAED,kCAQC;AAnDD,uCAAyB;AAEzB,qCAAmD;AACnD,+CAAkD;AA6B3C,KAAK,UAAU,0BAA0B,CAAC,IAAU;IACzD,OAAO,IAAI,CAAC,QAAQ,CAAC,uBAAa,CAA6B,CAAC;AAClE,CAAC;AAED,SAAgB,WAAW,CAAC,OAAoB,EAAE,MAAc,IAAA,mBAAU,GAAE;IAC1E,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACvC,MAAM,IAAI,GAAG,IAAA,oBAAW,EAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC5C,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC;IACxE,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAgB,WAAW,CAAC,QAAgB,EAAE,MAAc,IAAA,mBAAU,GAAE;IACtE,MAAM,IAAI,GAAG,IAAA,oBAAW,EAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IACxC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CACb,8BAA8B,QAAQ,MAAM,IAAI,2BAA2B,QAAQ,WAAW,CAC/F,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAgB,CAAC;AAClE,CAAC"}
+{"version":3,"file":"aom.js","sourceRoot":"","sources":["../src/aom.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmDA,sCAKC;AAED,gEAEC;AAED,kCAKC;AAED,kCAQC;AA7ED,uCAAyB;AAEzB,qCAAmD;AACnD,+CAAkD;AA6BlD;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAgB,aAAa,CAC3B,QAAoD,EACpD,OAAmD;IAEnD,OAAO,OAAO,CAAC,QAAQ,EAAE,UAAU,CAAC,IAAI,QAAS,CAAC,UAAU,KAAK,OAAO,EAAE,UAAU,CAAC;AACvF,CAAC;AAEM,KAAK,UAAU,0BAA0B,CAAC,IAAU;IACzD,OAAO,IAAI,CAAC,QAAQ,CAAC,uBAAa,CAA6B,CAAC;AAClE,CAAC;AAED,SAAgB,WAAW,CAAC,OAAoB,EAAE,MAAc,IAAA,mBAAU,GAAE;IAC1E,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACvC,MAAM,IAAI,GAAG,IAAA,oBAAW,EAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC5C,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC;IACxE,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAgB,WAAW,CAAC,QAAgB,EAAE,MAAc,IAAA,mBAAU,GAAE;IACtE,MAAM,IAAI,GAAG,IAAA,oBAAW,EAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IACxC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CACb,8BAA8B,QAAQ,MAAM,IAAI,2BAA2B,QAAQ,WAAW,CAC/F,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAgB,CAAC;AAClE,CAAC"}

package/dist/cli/baseline.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `ia-qa-heal baseline` — promote the current mappings to the reference `diff` compares against.
+ *
+ * Drift is a claim about two moments, so it needs a promoted "before". Without a command for
+ * it, everyone invents one, and the obvious invention — copy the current mapping, then diff
+ * against the copy — compares a capture to itself and reports `PASS  ✅ No drift`. The
+ * verdict is green because nothing was compared, which is the one failure mode a CI gate
+ * must never have. So the promotion is a command, and `diff` refuses a verdict when it
+ * catches the copy anyway (see `assertComparable` in `diff.ts`).
+ *
+ * Deliberately not a flag on `map`: promoting in the same breath as capturing would rebuild
+ * the trap, since the reference could then never be older than what it is compared to. The
+ * separation *is* the feature — `map` records what the app is now, `baseline` says it is
+ * also what the app is supposed to be. That second claim is a human judgement, and it gets
+ * its own verb.
+ *
+ * Copies `.json` only. `diff` reads nothing else, and the markdown contracts in `mapping/`
+ * already describe the app as it is today — a frozen second copy of them would be prose that
+ * silently goes stale, and twice the diff to review on every promotion.
+ */
+export declare function runBaseline(args?: string[]): Promise<void>;

package/dist/cli/baseline.js

@@ -0,0 +1,113 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runBaseline = runBaseline;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const config_1 = require("../config");
+/**
+ * `ia-qa-heal baseline` — promote the current mappings to the reference `diff` compares against.
+ *
+ * Drift is a claim about two moments, so it needs a promoted "before". Without a command for
+ * it, everyone invents one, and the obvious invention — copy the current mapping, then diff
+ * against the copy — compares a capture to itself and reports `PASS  ✅ No drift`. The
+ * verdict is green because nothing was compared, which is the one failure mode a CI gate
+ * must never have. So the promotion is a command, and `diff` refuses a verdict when it
+ * catches the copy anyway (see `assertComparable` in `diff.ts`).
+ *
+ * Deliberately not a flag on `map`: promoting in the same breath as capturing would rebuild
+ * the trap, since the reference could then never be older than what it is compared to. The
+ * separation *is* the feature — `map` records what the app is now, `baseline` says it is
+ * also what the app is supposed to be. That second claim is a human judgement, and it gets
+ * its own verb.
+ *
+ * Copies `.json` only. `diff` reads nothing else, and the markdown contracts in `mapping/`
+ * already describe the app as it is today — a frozen second copy of them would be prose that
+ * silently goes stale, and twice the diff to review on every promotion.
+ */
+async function runBaseline(args = []) {
+    const from = (0, config_1.mappingDir)();
+    const to = (0, config_1.baselineDir)();
+    if (!fs.existsSync(from)) {
+        console.error(`❌ No mappings found in ${rel(from)} — run \`ia-qa-heal map\` first.`);
+        process.exitCode = 2;
+        return;
+    }
+    const pages = jsonFilesIn(from);
+    const layouts = jsonFilesIn(path.join(from, config_1.LAYOUT_DIRNAME));
+    if (pages.length === 0 && layouts.length === 0) {
+        console.error(`❌ ${rel(from)} holds no mapping files — run \`ia-qa-heal map\` first.`);
+        process.exitCode = 2;
+        return;
+    }
+    const replaced = jsonFilesIn(to).length + jsonFilesIn(path.join(to, config_1.LAYOUT_DIRNAME)).length;
+    fs.mkdirSync(to, { recursive: true });
+    for (const file of pages) {
+        fs.copyFileSync(path.join(from, file), path.join(to, file));
+    }
+    if (layouts.length > 0) {
+        fs.mkdirSync(path.join(to, config_1.LAYOUT_DIRNAME), { recursive: true });
+        for (const file of layouts) {
+            fs.copyFileSync(path.join(from, config_1.LAYOUT_DIRNAME, file), path.join(to, config_1.LAYOUT_DIRNAME, file));
+        }
+    }
+    const total = pages.length + layouts.length;
+    console.log(`\n📌 Baseline promoted → ${rel(to)}`);
+    console.log(`   ${pages.length} ${pages.length === 1 ? 'page' : 'pages'}` +
+        (layouts.length > 0 ? ` · ${layouts.length} ${layouts.length === 1 ? 'layout' : 'layouts'}` : '') +
+        (replaced > 0 ? `  (replaced a baseline of ${replaced} ${replaced === 1 ? 'file' : 'files'})` : ''));
+    // Promoting over a reference that had drift in it accepts that drift as correct, silently
+    // and irreversibly outside of git. Saying so is the difference between "I meant that" and
+    // "I did not know that was what the command did".
+    if (replaced > 0) {
+        console.log(`   Any drift against the old baseline is now the expected state.`);
+    }
+    console.log(`\n   Commit it — a reference that is not in git cannot be reviewed or reverted:`);
+    console.log(`     git add ${rel(to).replace(/\\/g, '/')} && git commit -m "baseline: ${total} contracts"`);
+    console.log(`\n   Then change the app, \`ia-qa-heal map\` again, and \`ia-qa-heal diff\` has two`);
+    console.log(`   different moments to compare.\n`);
+    if (args.length > 0) {
+        console.log(`   (ignored: ${args.join(' ')} — \`baseline\` takes no arguments)\n`);
+    }
+}
+function jsonFilesIn(dir) {
+    if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory())
+        return [];
+    return fs.readdirSync(dir).filter((f) => f.endsWith('.json') && !f.startsWith('.'));
+}
+function rel(p) {
+    return path.relative(process.cwd(), p) || p;
+}
+//# sourceMappingURL=baseline.js.map

package/dist/cli/baseline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseline.js","sourceRoot":"","sources":["../../src/cli/baseline.ts"],"names":[],"mappings":"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"}

package/dist/cli/diff.d.ts

@@ -1,8 +1,10 @@
 /**
- * `ia-qa-heal diff <baseline.json> <current.json> [--strict] [--json] [--dir]`
+ * `ia-qa-heal diff [baseline] [current] [--strict] [--json] [--dir]`
  *
- * Two modes:
- *   file mode (default) — diffs two individual mapping files.
+ * Three modes:
+ *   no arguments — the everyday case: the promoted `baseline/` against what `map` just
+ *     wrote to `mapping/`. Implies `--dir`.
+ *   file mode — diffs two individual mapping files.
  *   directory mode (`--dir`) — both args are directories of mapping files.
  *     Finds matching pairs by filename, diffs each, and produces an aggregate
  *     verdict. Layouts in `_layouts/` are diffed first (once instead of N
@@ -11,6 +13,6 @@
  * Exit codes (so a pipeline can gate on it):
  *   0 — PASS, or FIX without `--strict`
  *   1 — BLOCK (a selector broke with no semantic match), or FIX with `--strict`
- *   2 — bad usage / unreadable input
+ *   2 — bad usage / unreadable input / nothing to compare
  */
 export declare function runDiff(args: string[]): Promise<void>;