@ripplo/testing 0.3.10 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # @ripplo/testing
 
-Typed TypeScript DSL for defining end-to-end tests with [Ripplo](https://ripplo.ai).
+Typed TypeScript DSL for end-to-end tests with real backend state. Powers [Ripplo](https://ripplo.ai).
 
 ## Install
 
@@ -8,57 +8,20 @@ Typed TypeScript DSL for defining end-to-end tests with [Ripplo](https://ripplo.
 npm install @ripplo/testing
 ```
 
-## Quick Start
-
-1. Run `npx ripplo` to authenticate and scaffold a `.ripplo/` directory in your project
-2. Define preconditions in `.ripplo/preconditions/index.ts` — export each handle and collect them into a `preconditions` registry
-3. (Optional) Define observers in `.ripplo/observers/index.ts` the same way
-4. Write tests in `.ripplo/tests/` — each file exports a `TestDefinition`; `.ripplo/tests/index.ts` composes them into a `tests` array
-5. Wire everything into `.ripplo/ripplo.ts` by passing the three registries to `createRipplo(config, { preconditions, observers, tests })`
-6. In your app server, call `createEngine(ripplo, { preconditions, observers })` to provide implementations — TypeScript enforces that every handle is implemented exactly once
-7. Run `npx ripplo lint` to validate, `npx ripplo run` to execute
-8. Commit the generated `.ripplo/ripplo.lock` alongside your DSL changes (see Lockfile below)
-
-Every test gets a clean slate via preconditions — no shared state, no ordering dependencies, fully parallelizable. Observers let tests verify backend side effects (async jobs, DB rows, webhooks) without polling or sleeps in test code.
+This package provides the DSL and engine adapters. The [`ripplo`](https://www.npmjs.com/package/ripplo) CLI scaffolds `.ripplo/`, runs tests, and writes the lockfile.
 
 ## Architecture
 
-`@ripplo/testing` has two halves that hand off through two "funnels":
-
-- **Definitions funnel into `createRipplo`.** The pure top-level factories `precondition(...)`, `observer(...)`, `test(...)` return plain handle/definition values. They have no side effects — no global builder. You gather them into registry objects and pass all three to `createRipplo(config, { preconditions, observers, tests })` in `.ripplo/ripplo.ts`. That call is the single point where the DSL graph is registered.
-- **Implementations funnel into `createEngine`.** In your app server, `createEngine(ripplo, { preconditions: {...}, observers: {...} })` wires every handle to its setup/teardown/run function. The impls object is exhaustiveness-checked at compile time: missing a key is a type error, adding an unknown key is a type error.
-
-The resulting `engine` is what adapters (`@ripplo/testing/express`, `/fastify`, `/nextjs`) mount under a path prefix (default `/ripplo`) — serving three routes: `PUT /execute-preconditions`, `PUT /execute-observer`, `PUT /teardown-preconditions`. Every request is HMAC-signed; the adapter is gated behind `ENABLE_RIPPLO_TESTING` so it can't ship to production by accident.
-
-Your precondition and observer implementations live in the server package where they have access to your DB/ORM. The DSL package never runs that code — it just orchestrates execution over signed HTTP.
+Two halves, two funnels:
 
-## Lockfile
-
-`npx ripplo compile` (and `ripplo lint`, and the dashboard's file watcher) writes `.ripplo/ripplo.lock` — a JSON artifact containing the compiled graph + tests, plus a `lockfileVersion` field. **Commit it.**
-
-The Ripplo server reads the lockfile on every GitHub push webhook. If the lockfile is missing or out of date, the branch does not sync and the webhook returns 422.
+- **Definitions** → `createRipplo({ preconditions, observers, tests })` in `.ripplo/index.ts`. Pure factories (`precondition()`, `observer()`, `test()`) return plain handles; you collect them into registries and pass all three. No global builder, no side effects.
+- **Implementations** → `createEngine(ripplo, { preconditions, observers })` in your app server. Wires every handle to its setup/teardown/run function. **Exhaustiveness-checked** — missing or extra keys are TypeScript errors.
 
-- `ripplo compile` — compile + write (default).
-- `ripplo compile --check` — exit non-zero if the lockfile is missing or stale. Use in pre-commit hooks or CI.
-- `ripplo doctor` — surfaces stale lockfiles and a missing pre-commit hook.
+The resulting `engine` is mounted by an adapter (`@ripplo/testing/express`, `/fastify`, `/nextjs`, `/hono`, `/koa`, `/nestjs`, `/elysia`) at a path prefix (default `/ripplo`). It exposes three signed routes: `PUT /execute-preconditions`, `PUT /execute-observer`, `PUT /teardown-preconditions`.
 
-## Project Layout
-
-```
-.ripplo/
-  ripplo.ts              # createRipplo(config, { preconditions, observers, tests })
-  index.ts               # re-exports the default ripplo instance + registries
-  preconditions/index.ts # export each handle + a `preconditions` registry
-  observers/index.ts     # export each handle + an `observers` registry
-  tests/
-    index.ts             # compose all tests into a `tests` array
-    <test-id>.ts         # each file exports a TestDefinition
-
-<your-server>/src/test/
-  engine.ts              # createEngine(ripplo, { preconditions, observers }) — impls live here
-```
+Implementations live server-side where they have DB access. The DSL package never runs that code — it orchestrates execution over signed HTTP.
 
-## DSL API
+## DSL
 
 ### Test
 
@@ -81,17 +44,19 @@ export const inviteATeammate = test("invite-a-teammate")
     click(role("button", "Send invite")).as("send"),
     assert.visible(role("status", "Invite sent")).as("confirm toast"),
     assert
-      .backend(invitePendingForEmail, {
-        workspaceId: workspace.id,
-        email: "jamie@example.com",
-      })
+      .backend(invitePendingForEmail, { workspaceId: workspace.id, email: "jamie@example.com" })
       .as("confirm invite recorded"),
-  ]);
+  ])
+  .coverage(
+    "src/components/members/InviteDialog.tsx#InviteDialog.click[Invite member]",
+    "src/components/members/InviteDialog.tsx#InviteDialog.input[Email]",
+    "src/components/members/InviteDialog.tsx#InviteDialog.click[Send invite]",
+  );
 ```
 
-**Chain:** `test(id)` → `.name(display)` → `.requires(preconditions)` → `.expectedOutcome(text)` → `.startsAt(urlFn)` → `.steps(stepsFn)`
+`test(id)` → `.name()` → `.description()?` → `.requires()` → `.expectedOutcome()` → `.startsAt()` → `.steps()` → `.coverage(...ids)`. Use `.notImplemented()` instead of `.startsAt() / .steps() / .coverage()` to stub during planning.
 
-Use `.notImplemented()` in place of `.startsAt() + .steps()` to stub a test during planning.
+`.coverage(...)` ids come from the generated `.ripplo/coverage.d.ts` and ambiently augment `CoverageRegistry`, so the call autocompletes and type-errors on stale ids. Stubs skip it; implemented tests must include every interaction they exercise. The `stop-enforce` hook blocks on net-new interactions in the diff that no test claims.
 
 ### Preconditions
 
@@ -103,16 +68,14 @@ export const authLoggedIn = precondition("auth:logged-in")
   .contract<{ userId: string }>();
 
 export const dataProject = precondition("data:project")
-  .description("A project exists and the user is an admin member")
+  .description("Project exists; user is admin")
   .requires({ auth: authLoggedIn })
   .contract<{ orgId: string; projectId: string }>();
 
 export const preconditions = { authLoggedIn, dataProject };
 ```
 
-**Chain:** `precondition(name)` → `.description(text)` → `.requires(deps)` → `.contract<TData>()`
-
-The generic on `.contract<T>()` describes the shape of the data the precondition setup must return. Each field must be a `string` (run-scoped test values).
+`precondition(name)` → `.description()` → `.requires()` (optional) → `.contract<T>()`. Each field in `T` must be a `string` (run-scoped value).
 
 ### Observers
 
@@ -120,61 +83,60 @@ The generic on `.contract<T>()` describes the shape of the data the precondition
 import { observer } from "@ripplo/testing";
 
 export const orgNameIs = observer("org:name-is")
-  .description("Org with the given id has the given name in the DB")
+  .description("Org has the given name in the DB")
   .input<{ orgId: string; expectedName: string }>()
-  .budget("fast") // optional; "fast" is default
+  .budget("fast")
   .contract();
 
 export const observers = { orgNameIs };
 ```
 
-**Chain:** `observer(name)` → `.description(text)` → `.input<TInput>()` → `.budget(tier)` (optional) → `.contract()`
-
-**Budget tiers** (framework-defined, not numeric):
+**Budget tiers** (poll behavior, not numeric timeouts):
 
-- `"fast"` — ~5s with 100→1000ms backoff. Default. Synchronous DB reads.
-- `"slow"` — ~30s with 250→2000ms backoff. Queue drains, replication settling.
-- `"async"` — ~120s with 500→5000ms backoff. Webhooks, queue workers, LLM calls.
+| Tier    | Window | Backoff    | Use for                            |
+| ------- | ------ | ---------- | ---------------------------------- |
+| `fast`  | ~5s    | 100→1000ms | Synchronous DB reads (default)     |
+| `slow`  | ~30s   | 250→2000ms | Queue drains, replication settling |
+| `async` | ~120s  | 500→5000ms | Webhooks, queue workers, LLM calls |
 
 ### Locators
 
-Only two locator types are available. ARIA roles are strongly preferred.
+ARIA roles strongly preferred; `testId()` is a fallback only.
 
 ```typescript
 import { role, testId } from "@ripplo/testing/locators";
 
-role("button", "Save"); // ARIA role + accessible name (preferred)
-role("heading", "Settings"); // role without interaction
-role("textbox", "Email"); // input by role
-role("combobox", "Country"); // select/dropdown by role
-testId("workflow-checkbox"); // data-testid (fallback only)
+role("button", "Save");
+role("textbox", "Email");
+role("combobox", "Country");
+testId("workflow-checkbox");
 ```
 
-**Available ARIA roles:** `alert`, `alertdialog`, `button`, `checkbox`, `combobox`, `dialog`, `form`, `grid`, `heading`, `img`, `link`, `list`, `listbox`, `listitem`, `menu`, `menuitem`, `navigation`, `option`, `progressbar`, `radio`, `region`, `row`, `searchbox`, `separator`, `slider`, `spinbutton`, `status`, `switch`, `tab`, `tabpanel`, `textbox`, `toolbar`, `tooltip`, `tree`, `treeitem`
+**Roles:** `alert`, `alertdialog`, `button`, `checkbox`, `combobox`, `dialog`, `form`, `grid`, `heading`, `img`, `link`, `list`, `listbox`, `listitem`, `menu`, `menuitem`, `navigation`, `option`, `progressbar`, `radio`, `region`, `row`, `searchbox`, `separator`, `slider`, `spinbutton`, `status`, `switch`, `tab`, `tabpanel`, `textbox`, `toolbar`, `tooltip`, `tree`, `treeitem`.
 
-**Type-safe constraints:**
+Type-narrowed locators reject the wrong role at compile time:
 
-- `InputLocator` accepts: `role("textbox")`, `role("searchbox")`, `role("combobox")`, `role("spinbutton")`, `testId()`
-- `SelectLocator` accepts: `role("combobox")`, `role("listbox")`, `testId()`
-- `CheckLocator` accepts: `role("checkbox")`, `role("switch")`, `testId()`
+- `InputLocator` — `textbox`, `searchbox`, `combobox`, `spinbutton`, `testId()`
+- `SelectLocator` — `combobox`, `listbox`, `testId()`
+- `CheckLocator` — `checkbox`, `switch`, `testId()`
 
 ### Actions
 
 ```typescript
 import {
   click,
+  dblclick,
+  rightClick,
+  hover,
+  focus,
+  press,
   fill,
+  clear,
+  typeText,
   select,
   check,
   uncheck,
-  hover,
-  press,
   navigate,
-  dblclick,
-  focus,
-  clear,
-  typeText,
-  rightClick,
   scrollIntoView,
   drag,
   upload,
@@ -184,19 +146,14 @@ import {
   setViewport,
 } from "@ripplo/testing/actions";
 
-navigate("/settings"); // Go to URL
-click(role("button", "Save")); // Click element
-fill(role("textbox", "Email"), "test@x.com"); // Clear + type into input
-select(role("combobox", "Role"), "admin"); // Select option
-check(role("checkbox", "Terms")); // Check checkbox/switch
-uncheck(role("switch", "Notifications")); // Uncheck
-hover(role("button", "Info")); // Hover
-press("Enter"); // Press key
-focus(role("searchbox", "Search")); // Focus element
-dblclick(role("button", "Edit")); // Double click
-clear(role("textbox", "Search")); // Clear input
-upload(testId("file-input"), "./test.png"); // Upload file
-drag(role("row", "Item 1"), role("row", "Item 2")); // Drag and drop
+navigate("/settings");
+click(role("button", "Save"));
+fill(role("textbox", "Email"), "test@x.com"); // clear + type
+select(role("combobox", "Role"), "admin");
+check(role("checkbox", "Terms"));
+press("Enter");
+upload(testId("file-input"), "./test.png");
+drag(role("row", "Item 1"), role("row", "Item 2"));
 ```
 
 ### Assertions
@@ -204,100 +161,69 @@ drag(role("row", "Item 1"), role("row", "Item 2")); // Drag and drop
 ```typescript
 import { assert } from "@ripplo/testing/assert";
 
-assert.visible(role("heading", "Settings")); // Element visible
-assert.not.visible(role("dialog")); // Element not visible
-assert.text(role("status"), "3 / 5 runs"); // Exact text match
-assert.url("/projects/abc/settings"); // Exact URL match
-assert.enabled(role("button", "Submit")); // Element enabled
-assert.disabled(role("button", "Submit")); // Element disabled
-assert.checked(role("checkbox", "Terms")); // Checked
-assert.not.checked(role("switch", "Dark mode")); // Not checked
-assert.focused(role("textbox", "Search")); // Has focus
-assert.not.focused(role("textbox", "Search")); // No focus
-assert.count(testId("row"), 5); // Element count
-assert.attribute(role("link", "Docs"), "href", "/docs"); // Attribute value
-assert.value(role("textbox", "Email"), "test@x.com"); // Input value
-assert.backend(observerHandle, { ... });                // Backend state (see Observers)
+assert.visible(role("heading", "Settings"));
+assert.not.visible(role("dialog"));
+assert.text(role("status"), "3 / 5 runs"); // exact match
+assert.url("/projects/abc/settings");
+assert.enabled(role("button", "Submit"));
+assert.checked(role("checkbox", "Terms"));
+assert.focused(role("textbox", "Search"));
+assert.count(testId("row"), 5);
+assert.attribute(role("link", "Docs"), "href", "/docs");
+assert.value(role("textbox", "Email"), "test@x.com");
+assert.backend(observerHandle, { ...params }); // see Observers
 ```
 
-All text/URL assertions use **exact matching only** (`equals` operator). No `contains`, `startsWith`, or regex.
+All text/URL assertions are **exact match only**. No `contains`, `startsWith`, or regex.
+
+### Variables
 
-### Variables & Extraction
+Capture values at runtime, then reuse them:
 
 ```typescript
 import { extract, variable } from "@ripplo/testing/control";
 
 const token = variable("token");
 extract(testId("token-value"), token).as("capture token");
-// pass the token anywhere a string value is accepted:
 fill(role("textbox", "Paste here"), token).as("paste token");
 assert.value(role("textbox", "Paste here"), token).as("assert token");
 ```
 
-Never reference a runtime variable with a literal `"{{vars.name}}"` string — always pass the `Variable` token so TypeScript verifies the reference.
+### Step labels
 
-### Step Labels
-
-Every step **must** have a `.as("description")` label:
+Every step **must** have `.as("description")`. No duplicates within a test.
 
 ```typescript
 click(role("button", "Save")).as("save the form");
-assert.visible(role("status", "Saved")).as("verify save confirmation");
 ```
 
-## Data Flow
+## Data flow
 
-Precondition data flows into tests via destructuring:
+Precondition data flows in via destructuring. **Always destructure — never hardcode values that come from preconditions:**
 
 ```typescript
 test("delete-project")
-  .name("Delete project")
   .requires({ project: dataProject })
-  .expectedOutcome("project no longer exists")
   .startsAt(({ project }) => `/projects/${project.projectId}/settings`)
   .steps(({ project }) => [
-    // project.projectId, project.orgId available here
     navigate(`/projects/${project.projectId}/settings`).as("go to settings"),
     // ...
   ]);
 ```
 
-**Always destructure and use precondition data.** Never hardcode values that come from preconditions — if a precondition implementation changes, the test should not break.
-
-**Never write `"{{namespace.key}}"` as a string literal.** Pass the destructured proxy value directly. Internally the proxy stringifies to `{{namespace.key}}`, but writing the literal bypasses TypeScript so typos (`{{tabel.name}}`) silently compile and silently fail at runtime. The `no-literal-template-strings` lint rule enforces this.
+**Never write `"{{namespace.key}}"` as a string literal.** The proxy stringifies internally, but writing the literal bypasses TypeScript so typos compile and fail at runtime. The `no-literal-template-strings` lint rule blocks this.
 
 ```typescript
-// ❌ WRONG — literal template string, no type-checking
-.steps(({ table }) => [
-  assert.value(role("textbox", "Table name"), "{{table.name}}").as("name visible"),
-])
-
-// ✅ CORRECT — proxy value, type-checked against requires()
-.steps(({ table }) => [
-  assert.value(role("textbox", "Table name"), table.name).as("name visible"),
-])
-```
+// ❌ literal — no type-checking
+assert.value(role("textbox", "Table name"), "{{table.name}}").as("name visible");
 
-Runtime variables (captured via `clipboard`, `extract`, etc.) follow the same rule. Create a token with `variable("name")` and pass it anywhere a value is accepted:
-
-```typescript
-import { variable } from "@ripplo/testing/control";
-
-.steps(() => {
-  const copied = variable("copied");
-  return [
-    click(role("button", "Copy")).as("copy"),
-    clipboard({ action: "read", target: copied, value: undefined }).as("read clipboard"),
-    assert.value(role("button", "Copy"), copied).as("match clipboard"),
-  ];
-})
+// ✅ proxy — checked against requires()
+assert.value(role("textbox", "Table name"), table.name).as("name visible");
 ```
 
-Never write `"{{vars.copied}}"` as a string literal — use the token.
-
-## Wiring it together
+## Wiring
 
-### `.ripplo/ripplo.ts` — the definitions funnel
+### `.ripplo/index.ts` — definitions
 
 ```typescript
 import { createRipplo } from "@ripplo/testing";
@@ -305,25 +231,15 @@ import { preconditions } from "./preconditions/index.js";
 import { observers } from "./observers/index.js";
 import { tests } from "./tests/index.js";
 
-const ripplo = createRipplo(
-  {
-    appUrl: "https://localhost:3001",
-    engineUrl: "https://localhost:3001/ripplo",
-    projectId: "<your-project-id>",
-  },
-  { preconditions, observers, tests },
-);
-
-export default ripplo;
+export default createRipplo({ preconditions, observers, tests });
 ```
 
-`webhookSecret` is read from `RIPPLO_WEBHOOK_SECRET` in `.ripplo/.env` (auto-loaded by the CLI before each compile). You can still pass it explicitly to `createRipplo` if you need to.
+Runtime config (`RIPPLO_APP_URL`, `RIPPLO_ENGINE_URL`, `RIPPLO_WEBHOOK_SECRET`) lives in your host app's env file — `ripplo init` writes the initial values. Project id and env-file pointers live in `.ripplo/project.json`.
 
-### App server — the implementations funnel
+### `<app>/src/test/engine.ts` — implementations
 
 ```typescript
-// <your-server>/src/test/engine.ts
-import { createEngine } from "@ripplo/testing";
+import { createEngine, notImplemented } from "@ripplo/testing";
 import ripplo from "../../../../.ripplo/index.js";
 import { prisma } from "../lib/prisma.js";
 
@@ -338,16 +254,7 @@ export const engine = createEngine(ripplo, {
         // clean up using ctx.data.userId
       },
     },
-    dataProject: {
-      setup: async (ctx, { auth }) => {
-        // use auth.userId to create a project
-        return {
-          orgId: ctx.fixed("..."),
-          projectId: ctx.fixed("..."),
-        };
-      },
-      teardown: async () => {},
-    },
+    dataProject: notImplemented("awaiting prisma seed helper"), // stub for planning
   },
   observers: {
     orgNameIs: async (ctx, { orgId, expectedName }) => {
@@ -356,116 +263,64 @@ export const engine = createEngine(ripplo, {
         where: { id: orgId },
       });
       if (org == null) return ctx.retry(`organization "${orgId}" not found yet`);
-      if (org.name !== expectedName) {
-        return ctx.retry(`name is "${org.name}", expected "${expectedName}"`);
-      }
+      if (org.name !== expectedName) return ctx.retry(`name is "${org.name}"`);
       return ctx.pass();
     },
   },
 });
 ```
 
-**Exhaustiveness:** the `preconditions` and `observers` keys in this object must exactly match the registries you passed to `createRipplo`. Missing a key is a TypeScript error; adding an unknown key is a TypeScript error.
-
-**Stubbing an impl:** use the `notImplemented` sentinel to keep planning-mode placeholders while the surrounding code still compiles.
-
-```typescript
-import { createEngine, notImplemented } from "@ripplo/testing";
-
-createEngine(ripplo, {
-  preconditions: {
-    authLoggedIn: { setup, teardown },
-    dataProject: notImplemented("awaiting prisma seed helper"),
-  },
-  observers: { orgNameIs: notImplemented() },
-});
-```
-
-The engine returns a "not implemented" failure outcome at runtime for any stub, and `ripplo lint` can be configured to block CI on unimplemented entries.
-
-### SetupContext
+### Setup context
 
-`ctx` passed to each precondition `setup` provides:
+`ctx` passed to each precondition `setup`:
 
-- `ctx.runId` — unique 12-char id for this test run
+- `ctx.runId` — unique 12-char id for this run
 - `ctx.fixed(value)` — static test value
-- `ctx.uniqueId(prefix)` — generate unique ID (e.g., `ripplo-test-<prefix>-<runId>`)
-- `ctx.uniqueEmail()` — generate unique email (`ripplo-test-<runId>@test.ripplo.ai`)
-- `ctx.setCookie(name, value, options?)` — inject auth cookies; forwarded as `Set-Cookie` to the test browser
+- `ctx.uniqueId(prefix)` — `ripplo-test-<prefix>-<runId>`
+- `ctx.uniqueEmail()` — `ripplo-test-<runId>@test.ripplo.ai`
+- `ctx.setCookie(name, value, options?)` — forwarded to the test browser as `Set-Cookie`
 
-### ObserverContext
+### Observer context
 
-`ctx` passed to each observer impl provides:
+- `ctx.pass()` — assertion satisfied; stop polling.
+- `ctx.retry(reason)` — **default.** Anything that might succeed on a later poll: row not found yet, status not transitioned, queue not drained. Last `reason` surfaces in failure detail.
+- `ctx.fail(reason)` — **narrow.** Only when polling cannot help: invariant violated, contradictory value. Stops immediately. Tempted to use `fail` for "not found"? It's `retry`.
+- Thrown exceptions are treated as `fail`.
 
-- `ctx.pass()` → assertion satisfied; stop polling.
-- `ctx.retry(reason)` → **default**. Use for anything that might succeed on a later poll: row not found yet, status not transitioned, queue not drained, side effect still in flight. Runtime polls until the budget expires; the last `reason` surfaces in the failure detail.
-- `ctx.fail(reason)` → **narrow**. Only when further polling cannot help — an invariant has been violated (wrong shape, contradictory value, forbidden state). Stops immediately. If you're tempted to use `fail` for "not found" or "not yet X", it should be `retry`.
-- Any thrown exception is treated as `fail` with the error message.
+## Observer coverage
 
-## Observer Usage in Tests
+Lint enforces backend assertions on mutation flows:
 
-```typescript
-import { orgNameIs } from "../observers/index.js";
+- **`mutation-without-observer-coverage`** — flags save/create/delete/update clicks (and uploads, accepted dialogs) not followed by an `assert.backend(...)`. Fix is always to **add an observer**.
+- **`observer-params-reference-variables`** — flags assertions whose params are all hardcoded strings while the test declares precondition variables.
 
-test("update-org-name")
-  .name("Update org name")
-  .requires({ project: dataProject })
-  .expectedOutcome("org name persisted")
-  .startsAt(({ project }) => `/projects/${project.projectId}/settings`)
-  .steps(({ project }) => [
-    fill(role("textbox", "Organization name"), "New Name").as("fill new name"),
-    click(role("button", "Save")).as("click save"),
-    assert
-      .backend(orgNameIs, { orgId: project.orgId, expectedName: "New Name" })
-      .as("assert org name in db"),
-  ]);
-```
-
-### Observer lint rules
-
-- **`mutation-without-observer-coverage`** — flags save/create/delete/update/etc. clicks, uploads, and accepted dialogs that are not followed by an `assert.backend(...)` before the next mutation or end of test. The expected fix is always to **add an observer**.
-- **`observer-params-reference-variables`** — flags observer assertions whose params are all hardcoded strings while the test declares precondition variables; use precondition data instead of literals.
-
-### Opting out (`uiOnly`)
-
-For steps that genuinely don't touch server state (cancel dialogs, toggle a display-only control, pick a client-side sort option) pass `{ uiOnly: true }` to the step factory:
+For steps that genuinely don't touch server state (cancel dialogs, client-side sort), pass `{ uiOnly: true }`:
 
 ```typescript
 click(role("button", "Cancel"), { uiOnly: true }).as("close dialog");
+test("filter-sort", { uiOnly: true }).name("Filter & sort");
 ```
 
-For entire presentation-only flows, pass the flag to `test`:
-
-```typescript
-test("filter-sort-user-flows", { uiOnly: true }).name("Filter & sort");
-```
+`uiOnly` is for **zero backend effect**. Mutations and optimistic UI need an observer — never use `uiOnly` with a `// TODO: add observer` comment.
 
-`uiOnly: true` is only valid for steps with zero backend effect (pure view transitions). If the step triggers a mutation, background job, or optimistic UI update, `uiOnly` is wrong — write an observer. The `mutation-without-observer-coverage` lint rule is a backstop, not a ceiling: authoring a test without backend assertions on a mutation flow is a mistake regardless of whether lint catches this particular click label. **Never use `uiOnly: true` with a `// TODO: add observer` comment as a placeholder.** That's a false green — the observer is in-scope work, not follow-up.
+## Determinism rules
 
-## Determinism Rules
+1. `role()` locators only; `testId()` only when no role applies.
+2. Exact-match assertions only.
+3. Destructure precondition data; never hardcode names/IDs/emails.
+4. Every step has `.as("description")`. No duplicates.
+5. End with assertions that verify `expectedOutcome`.
+6. Cover backend mutations with observers (or `uiOnly: true`).
 
-1. **Use `role()` locators exclusively.** Only use `testId()` when no ARIA role is available.
-2. **All text assertions use exact matching.** No `contains`, `startsWith`, or regex.
-3. **Destructure precondition data in `steps()`.** Never hardcode names, IDs, or emails that come from preconditions.
-4. **Every step must have `.as("description")`.** No unlabeled steps.
-5. **No duplicate labels** within a test.
-6. **End with assertions** that verify the `expectedOutcome`.
-7. **Cover backend mutations with observers.** Any save/create/delete/update click (or upload, or accepted dialog) must be verified with `assert.backend(observerHandle, params)` unless it truly has no server effect — in which case mark the step `{ uiOnly: true }`.
+## Server adapters
 
-## CLI Commands
+Every adapter takes the `engine` from `createEngine(...)` and a required `enabled: boolean`. Bind `enabled` to an env var so the routes can't ship to production:
 
-```bash
-ripplo                              # Launch interactive dashboard
-ripplo lint [ids..]                 # Compile + lint tests (all or specific ids)
-ripplo run [ids..]                  # Run tests in parallel
-ripplo flake-detect <id> --runs=10  # Run N times in parallel to detect flakiness
+```ts
+enabled: process.env.ENABLE_RIPPLO_TESTING === "true";
 ```
 
-## Server Setup
-
-Pick the adapter that matches your framework — each handles webhook signature verification, cookie forwarding, and request parsing for you. Every adapter takes a required `enabled: boolean` flag — bind it to an env var (e.g. `process.env.ENABLE_RIPPLO_TESTING === "true"`) so the endpoints never ship to production. When `enabled` is false the adapter mounts a no-op handler.
-
-All adapters take the `engine` produced by `createEngine(ripplo, impls)` — not the bare `ripplo` instance.
+When `enabled` is false the adapter mounts a no-op handler.
 
 ### Express
 
@@ -475,13 +330,7 @@ import { createExpressHandler } from "@ripplo/testing/express";
 import { engine } from "./test/engine.js";
 
 const app = express();
-app.use(
-  "/ripplo",
-  createExpressHandler({
-    enabled: process.env.ENABLE_RIPPLO_TESTING === "true",
-    engine,
-  }),
-);
+app.use("/ripplo", createExpressHandler({ enabled, engine }));
 ```
 
 ### Fastify
@@ -492,32 +341,21 @@ import { registerFastifyHandler } from "@ripplo/testing/fastify";
 import { engine } from "./test/engine.js";
 
 const app = Fastify();
-await app.register(
-  registerFastifyHandler({
-    enabled: process.env.ENABLE_RIPPLO_TESTING === "true",
-    engine,
-  }),
-  { prefix: "/ripplo" },
-);
+await app.register(registerFastifyHandler({ enabled, engine }), { prefix: "/ripplo" });
 ```
 
 ### Next.js (App Router)
 
-The Next.js adapter exports a single catch-all handler. Create one dynamic route file:
+A single catch-all route — runs on Node and Edge.
 
 ```ts
 // app/ripplo/[action]/route.ts
 import { createNextHandler } from "@ripplo/testing/nextjs";
 import { engine } from "@/server/test/engine";
 
-export const PUT = createNextHandler({
-  enabled: process.env.ENABLE_RIPPLO_TESTING === "true",
-  engine,
-});
+export const PUT = createNextHandler({ enabled, engine });
 ```
 
-The handler dispatches on the last URL segment (`execute-preconditions`, `execute-observer`, `teardown-preconditions`) and returns 404 for anything else. It depends only on the Web `Request` / `Response` types, so it runs on both the Node and Edge runtimes — no `next` import required.
-
 ### Hono
 
 ```ts
@@ -526,16 +364,10 @@ import { createHonoHandler } from "@ripplo/testing/hono";
 import { engine } from "./test/engine.js";
 
 const app = new Hono();
-app.route(
-  "/ripplo",
-  createHonoHandler({
-    enabled: process.env.ENABLE_RIPPLO_TESTING === "true",
-    engine,
-  }),
-);
+app.route("/ripplo", createHonoHandler({ enabled, engine }));
 ```
 
-The Hono adapter uses the Web `Request` / `Response` standard and runs on Node, Bun, Deno, and Cloudflare Workers.
+Web-standard `Request`/`Response`; runs on Node, Bun, Deno, Cloudflare Workers.
 
 ### Koa
 
@@ -546,18 +378,10 @@ import { createKoaHandler } from "@ripplo/testing/koa";
 import { engine } from "./test/engine.js";
 
 const app = new Koa();
-app.use(
-  mount(
-    "/ripplo",
-    createKoaHandler({
-      enabled: process.env.ENABLE_RIPPLO_TESTING === "true",
-      engine,
-    }),
-  ),
-);
+app.use(mount("/ripplo", createKoaHandler({ enabled, engine })));
 ```
 
-The Koa adapter reads the raw request body itself — do not mount a body-parser in front of it. Mount it at any prefix with `koa-mount`.
+The Koa adapter reads the raw body itself — don't mount a body-parser in front of it.
 
 ### NestJS
 
@@ -567,18 +391,12 @@ import { RipploTestingModule } from "@ripplo/testing/nestjs";
 import { engine } from "./test/engine.js";
 
 @Module({
-  imports: [
-    RipploTestingModule.forRoot({
-      enabled: process.env.ENABLE_RIPPLO_TESTING === "true",
-      engine,
-      path: "ripplo",
-    }),
-  ],
+  imports: [RipploTestingModule.forRoot({ enabled, engine, path: "ripplo" })],
 })
 export class AppModule {}
 ```
 
-Requires the Express platform adapter (`@nestjs/platform-express`) and `reflect-metadata` at the entry point. `path` defaults to `"ripplo"`.
+Requires `@nestjs/platform-express` and `reflect-metadata`. `path` defaults to `"ripplo"`.
 
 ### Elysia
 
@@ -587,19 +405,12 @@ import { Elysia } from "elysia";
 import { createElysiaHandler } from "@ripplo/testing/elysia";
 import { engine } from "./test/engine.js";
 
-const app = new Elysia().group("/ripplo", (app) =>
-  app.use(
-    createElysiaHandler({
-      enabled: process.env.ENABLE_RIPPLO_TESTING === "true",
-      engine,
-    }),
-  ),
-);
+const app = new Elysia().group("/ripplo", (g) => g.use(createElysiaHandler({ enabled, engine })));
 ```
 
-### Custom integration (raw engine)
+### Custom (raw engine)
 
-If your framework isn't covered above, use the engine directly. The adapters are thin wrappers over the same API.
+For unsupported frameworks. The adapters above are thin wrappers over this API.
 
 ```ts
 import { buildSetCookieHeader, serializeCookie, verifyWebhookSignature } from "@ripplo/testing";
@@ -607,7 +418,6 @@ import { engine } from "./test/engine.js";
 
 const webhookSecret = engine.getConfig().webhookSecret;
 
-// PUT /ripplo/execute-preconditions
 async function executePreconditions(req: Request): Promise<Response> {
   const body = await req.text();
   const verified = verifyWebhookSignature(
@@ -628,34 +438,39 @@ async function executePreconditions(req: Request): Promise<Response> {
   const result = await engine.executePreconditions(preconditions, { appUrl });
 
   const headers = new Headers({ "content-type": "application/json" });
-  result.cookies.forEach((c) => {
-    headers.append("Set-Cookie", buildSetCookieHeader(serializeCookie(c)));
-  });
+  result.cookies.forEach((c) =>
+    headers.append("Set-Cookie", buildSetCookieHeader(serializeCookie(c))),
+  );
   return new Response(JSON.stringify(result), { headers });
 }
-
-// PUT /ripplo/teardown-preconditions — same verify pattern, then engine.teardown(...)
-// PUT /ripplo/execute-observer      — same verify pattern, then engine.executeObserver(...)
+// teardown-preconditions and execute-observer follow the same verify-then-dispatch pattern.
 ```
 
-**You're responsible for:**
+You're responsible for: webhook verification (always before invoking the engine), routing the three endpoints, forwarding `result.cookies` to the test browser as `Set-Cookie` headers, and reading the raw body for signature verification before `JSON.parse`.
 
-- **Webhook verification.** Always call `verifyWebhookSignature` before invoking the engine.
-- **Routing.** Dispatch the three endpoints (`execute-preconditions`, `execute-observer`, `teardown-preconditions`) however your framework handles routes.
-- **Cookie forwarding.** `result.cookies` contains the cookies preconditions set during setup — they must reach the test browser as `Set-Cookie` headers, or login/session preconditions will silently fail.
-- **Body parsing.** Use the raw text body for signature verification, then `JSON.parse` for the engine call.
+## Security & parallelism
 
-### Webhook Signing
+- All requests signed via Standard Webhooks (HMAC-SHA256). Headers: `webhook-id`, `webhook-timestamp`, `webhook-signature`. **Always verify before executing.**
+- `ENABLE_RIPPLO_TESTING` gates every adapter. Never expose in production.
+- Use `ctx.uniqueId(prefix)` / `ctx.uniqueEmail()` so parallel runs don't collide.
+- Return created entity IDs in the data contract; teardown deletes only that run's data using the captured `runId`. Never bulk-delete.
 
-All requests are signed using Standard Webhooks (HMAC-SHA256). Headers: `webhook-id`, `webhook-timestamp`, `webhook-signature`. Verify before executing.
+## Lockfile
+
+`ripplo compile` (and `ripplo lint`, and `ripplo watch`) writes `.ripplo/ripplo.lock`. **Commit it.** The Ripplo server reads it on every push webhook; missing or stale returns 422.
 
-### Environment Guard
+- `ripplo compile` — write.
+- `ripplo compile --check` — non-zero if stale. Use in pre-commit hooks and CI.
+- `ripplo doctor` — surfaces stale lockfiles and missing pre-commit hooks.
 
-Wrap all precondition routes behind `ENABLE_RIPPLO_TESTING=true`. Never expose in production.
+## CLI
 
-### Parallel Safety
+The CLI lives in [`ripplo`](https://www.npmjs.com/package/ripplo). Most-used commands:
 
-- Use `ctx.uniqueId(prefix)` / `ctx.uniqueEmail()` in precondition setup so names/emails don't collide across parallel runs
-- Return created entity IDs in the data contract so teardown can scope deletion precisely
-- Teardown only deletes that run's data (use the `runId` captured at setup)
-- Never hardcode entity names or use bulk deletion
+```bash
+ripplo auth login       # authenticate
+ripplo init             # scaffold .ripplo/ + write env vars
+ripplo watch            # local executor — wire into your dev script
+ripplo lint [ids..]     # compile + lint
+ripplo run [ids..]      # run tests in parallel
+```