@ripplo/testing 0.5.1 → 0.5.2

package/README.md

@@ -1,25 +1,24 @@
 # @ripplo/testing
 
-Typed TypeScript DSL for end-to-end tests with real backend state. Powers [Ripplo](https://ripplo.ai).
-
-## Install
+Typed TypeScript DSL for end-to-end tests with real backend state, used by [Ripplo](https://ripplo.ai).
 
 ```sh
 npm install @ripplo/testing
 ```
 
-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.
+This package ships the DSL and the server adapters. The companion [`ripplo`](https://www.npmjs.com/package/ripplo) CLI scaffolds `.ripplo/`, runs tests, and writes the lockfile.
 
 ## Architecture
 
-Two halves, two funnels:
+Definitions and implementations are kept in separate files.
+
+`createRipplo({ preconditions, observers, tests })` in `.ripplo/index.ts` collects the handles returned by `precondition()`, `observer()`, and `test()`. These factories have no side effects.
 
-- **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.
+`createEngine(ripplo, { preconditions, observers })` in your app server wires every handle to its setup, teardown, or observer function. Missing or extra keys are TypeScript errors.
 
-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`.
+Mount the resulting `engine` with one of the adapters (`@ripplo/testing/express`, `/fastify`, `/nextjs`, `/hono`, `/koa`, `/nestjs`, `/elysia`) at a path prefix (default `/ripplo`). The adapter exposes three signed routes: `PUT /execute-preconditions`, `PUT /execute-observer`, `PUT /teardown-preconditions`.
 
-Implementations live server-side where they have DB access. The DSL package never runs that code — it orchestrates execution over signed HTTP.
+Implementations run server-side where they have DB access. The DSL package never invokes them; it dispatches over signed HTTP.
 
 ## DSL
 
@@ -56,7 +55,7 @@ export const inviteATeammate = test("invite-a-teammate")
 
 `test(id)` → `.name()` → `.description()?` → `.requires()` → `.expectedOutcome()` → `.startsAt()` → `.steps()` → `.coverage(...ids)`. Use `.notImplemented()` instead of `.startsAt() / .steps() / .coverage()` to stub 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.
+`.coverage(...)` ids come from the generated `.ripplo/coverage.d.ts`, which augments `CoverageRegistry` so the call autocompletes and breaks the build on stale ids. Implemented tests must list every interaction they exercise; stubs skip it. A pre-commit hook blocks net-new interactions in the diff that no test claims.
 
 ### Preconditions
 
@@ -75,18 +74,18 @@ export const dataProject = precondition("data:project")
 export const preconditions = { authLoggedIn, dataProject };
 ```
 
-`precondition(name)` → `.description()` → `.requires()` (optional) → `.contract<T>()`. Each field in `T` must be a primitive — `string`, `number`, or `boolean` (run-scoped value).
+`precondition(name)` → `.description()` → `.requires()` (optional) → `.contract<T>()`. Each field in `T` must be a primitive (`string`, `number`, or `boolean`) and is run-scoped.
 
 #### Preconditions are create-only
 
-Precondition setups must be **additive**: insert new rows, don't `update` or `delete` existing ones. Concurrent runs share a database, and a `WHERE` clause that looks scoped to the current run can match rows that belong to another run in flight. Even when writes are reliably scoped, mutating a row another precondition produced creates ordering dependencies that break under composition.
+Precondition setups must only insert. No `update`, no `delete`. Parallel runs share a database, so a `WHERE` clause that looks run-scoped can still match another run's rows. And mutating something a parent precondition produced couples them in an order that breaks the moment they're composed differently.
 
-If a test needs a non-default state, the precondition that **creates** the underlying row should accept that state as input — don't seed a default and mutate it from a downstream precondition.
+If a test needs a non-default state, accept that state as input on the precondition that creates the row. Don't seed a default and patch it later.
 
-Allowed exceptions:
+Two exceptions:
 
-- `upsert` on a row whose primary key makes it a 1:1 settings record for the current run (e.g. a per-`(userId, resourceId)` view). Treat it as create-with-default.
-- Teardown may delete — but only data the precondition itself created.
+- `upsert` on a row whose primary key is per-run (e.g. a `(userId, resourceId)` settings record). Treat it as create-with-default.
+- Teardown may delete, but only rows this precondition created.
 
 ### Observers
 
@@ -102,26 +101,9 @@ export const orgNameIs = observer("org:name-is")
 export const observers = { orgNameIs };
 ```
 
-Observer `.input<T>()` and precondition `.contract<T>()` fields can be any primitive — `string`, `number`, or `boolean`. Model each field as the type it actually is; no stringification at the boundary.
-
-```typescript
-export const orgOverageCapIs = observer("org:overage-cap-is")
-  .description("Org has the given overageCapCents")
-  .budget("fast")
-  .input<{ orgId: string; expectedCapCents: number }>()
-  .contract();
-
-export const orgHasLogo = observer("org:has-logo")
-  .description("Organization logo is set / unset")
-  .budget("fast")
-  .input<{ orgId: string; expectLogo: boolean }>()
-  .contract();
-
-assert.backend(orgOverageCapIs, { orgId: project.orgId, expectedCapCents: 2500 });
-assert.backend(orgHasLogo, { orgId: project.orgId, expectLogo: true });
-```
+Observer `.input<T>()` and precondition `.contract<T>()` fields are typed primitives: `string`, `number`, or `boolean`. The wire codec preserves the type, so a `number` field arrives as a `number` in your impl.
 
-**Budget tiers** (poll behavior, not numeric timeouts):
+`.budget(tier)` controls how long the runtime polls before giving up. The tiers describe poll behavior, not numeric timeouts:
 
 | Tier    | Window | Backoff    | Use for                            |
 | ------- | ------ | ---------- | ---------------------------------- |
@@ -131,16 +113,7 @@ assert.backend(orgHasLogo, { orgId: project.orgId, expectLogo: true });
 
 ### Locators
 
-ARIA roles strongly preferred; `testId()` is a fallback only.
-
-```typescript
-import { role, testId } from "@ripplo/testing/locators";
-
-role("button", "Save");
-role("textbox", "Email");
-role("combobox", "Country");
-testId("workflow-checkbox");
-```
+`role(name, accessibleName)` matches by ARIA role and accessible name. `testId(id)` matches a `data-testid` attribute and exists for elements that genuinely have no semantic role.
 
 **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`.
 
@@ -152,76 +125,33 @@ Type-narrowed locators reject the wrong role at compile time:
 
 ### Actions
 
-```typescript
-import {
-  click,
-  dblclick,
-  rightClick,
-  hover,
-  focus,
-  press,
-  fill,
-  clear,
-  typeText,
-  select,
-  check,
-  uncheck,
-  navigate,
-  scrollIntoView,
-  drag,
-  fixture,
-  upload,
-  handleDialog,
-  clipboard,
-  setPermission,
-  setViewport,
-} from "@ripplo/testing/actions";
-
-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"), fixture("logo.png"));
-drag(role("row", "Item 1"), role("row", "Item 2"));
-```
-
-### Upload fixtures
+Imported from `@ripplo/testing/actions`. Every action takes a locator and produces a step:
 
-`upload()` requires a `fixture()` reference. Fixture files live in `.ripplo/fixtures/` (committed). Limits: 10 MB per file, 50 MB total.
+- **Pointer:** `click`, `dblclick`, `rightClick`, `hover`, `focus`
+- **Keyboard:** `press` (single key or chord), `typeText` (no clear), `fill` (clear + type), `clear`
+- **Form controls:** `select`, `check`, `uncheck`
+- **Navigation:** `navigate`, `scrollIntoView`
+- **Composite:** `drag`, `upload`, `handleDialog`, `clipboard`
+- **Browser context:** `setPermission`, `setViewport`
 
-```ts
-// .ripplo/fixtures/logo.png exists
-upload(testId("logo-input"), fixture("logo.png"));
+### Upload fixtures
 
-// Multiple files
-upload(testId("attachments"), [fixture("a.pdf"), fixture("b.pdf")]);
-```
+`upload(locator, fixture("name"))` is the only way to attach files. Fixture files live in `.ripplo/fixtures/` and are committed to git so cloud runs see byte-identical inputs. Limits: 10 MB per file, 50 MB total. Pass an array to `upload` for multi-file inputs.
 
 ### Assertions
 
-```typescript
-import { assert } from "@ripplo/testing/assert";
-
-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
-```
+Imported from `@ripplo/testing/assert`. Every assertion is exact-match; there is no `contains`, `startsWith`, or regex.
 
-All text/URL assertions are **exact match only**. No `contains`, `startsWith`, or regex.
+- **Visibility:** `assert.visible(loc)`, `assert.not.visible(loc)`
+- **Content:** `assert.text(loc, exact)`, `assert.value(loc, exact)`, `assert.attribute(loc, name, exact)`
+- **State:** `assert.enabled(loc)`, `assert.checked(loc)`, `assert.focused(loc)`
+- **Counting:** `assert.count(loc, n)`
+- **Routing:** `assert.url(path)`
+- **Backend:** `assert.backend(observer, params)` — see [Observers](#observers).
 
 ### Variables
 
-Capture values at runtime, then reuse them:
+`variable(name)` declares a placeholder. `extract(locator, variable)` captures the element's text or value at run time; later steps that take a string accept the variable in its place.
 
 ```typescript
 import { extract, variable } from "@ripplo/testing/control";
@@ -234,15 +164,11 @@ assert.value(role("textbox", "Paste here"), token).as("assert token");
 
 ### Step labels
 
-Every step **must** have `.as("description")`. No duplicates within a test.
-
-```typescript
-click(role("button", "Save")).as("save the form");
-```
+Every step ends with `.as("short description")`. Labels appear in the run UI and in failure detail, and duplicate labels within a test are a compile error. Describe intent ("open invite dialog"), not mechanics ("click button").
 
 ## Data flow
 
-Precondition data flows in via destructuring. **Always destructure — never hardcode values that come from preconditions:**
+Precondition output reaches steps by destructuring the argument to `.startsAt()` and `.steps()`. Always destructure; never hardcode a value that came from a precondition.
 
 ```typescript
 test("delete-project")
@@ -254,13 +180,13 @@ test("delete-project")
   ]);
 ```
 
-**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.
+Never write `"{{namespace.key}}"` as a string literal. The proxy stringifies internally, but writing the literal bypasses the type checker, so typos compile and fail at run time. The `no-literal-template-strings` rule blocks this.
 
 ```typescript
-// ❌ literal — no type-checking
+// literal: bypasses type-checking
 assert.value(role("textbox", "Table name"), "{{table.name}}").as("name visible");
 
-// ✅ proxy — checked against requires()
+// proxy: checked against requires()
 assert.value(role("textbox", "Table name"), table.name).as("name visible");
 ```
 
@@ -277,7 +203,7 @@ import { tests } from "./tests/index.js";
 export default createRipplo({ preconditions, observers, tests });
 ```
 
-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`.
+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>/src/test/engine.ts` — implementations
 
@@ -289,8 +215,8 @@ import { prisma } from "../lib/prisma.js";
 export const engine = createEngine(ripplo, {
   preconditions: {
     authLoggedIn: {
-      // setup receives a *batch* of items — one per concurrent run that requires this precondition.
-      // Issue one bulk write (createMany) and return one result per item, in input order.
+      // setup receives one item per concurrent run that needs this precondition.
+      // Issue one bulk write and return results in input order.
       setup: async (items) => {
         const seeds = items.map(({ ctx }) => ({
           id: ctx.uniqueId("user"),
@@ -322,61 +248,46 @@ export const engine = createEngine(ripplo, {
 });
 ```
 
-`setup` and `teardown` are **batched**: the runtime collects all concurrent runs that need a precondition within a 200ms window and calls the impl once with the full batch. Use `createMany` / `deleteMany` over per-item `create` / `delete` to keep DB load proportional to wall-clock time, not run count. The result array length must equal the input array length and order must be preserved (the engine zips by index back to runs).
+`setup` and `teardown` run in batches. The runtime groups concurrent runs that need the same precondition inside a 200ms window and calls your impl once for the whole batch. Use `createMany` / `deleteMany` so database load scales with wall-clock time rather than run count. Return one result per input item, in input order; the engine zips them back to runs by index.
 
 ### Setup context
 
-`item.ctx` available inside each batched setup item:
+Each batched setup item exposes `ctx`:
 
-- `ctx.runId` — unique 12-char id for this run
-- `ctx.fixed<T extends string | number | boolean>(value: T)` — static test value (any primitive)
-- `ctx.uniqueId(prefix)` — `ripplo-test-<prefix>-<runId>`
-- `ctx.uniqueEmail()` — `ripplo-test-<runId>@test.ripplo.ai`
-- `ctx.setCookie(name, value, options?)` — applied to the run's browser context before the test starts
+- `ctx.runId` — 12-char run id.
+- `ctx.fixed(value)` — static test value, type-branded so the engine can tell it apart from a raw literal.
+- `ctx.uniqueId(prefix)` returns `ripplo-test-<prefix>-<runId>`.
+- `ctx.uniqueEmail()` returns `ripplo-test-<runId>@test.ripplo.ai`.
+- `ctx.setCookie(name, value, options?)` applies to that run's browser context before the test starts.
 
-Helpers return plain primitives — interpolate, JSON.stringify, or pass through observer params directly. The return type is type-branded, so a hardcoded literal in a `setup` return fails at compile time.
+Helpers return plain primitives, but the return type is branded — a bare string literal in a `setup` return fails at compile time, which is what stops tests from accidentally seeding identical-looking data across runs.
 
 ### Observer context
 
+The observer impl returns one of three terminal states:
+
 - `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.retry(reason)` — the default; use it for anything that might succeed on a later poll (row not yet written, status not yet transitioned, queue not yet drained). The last `reason` is surfaced in failure detail. "Not found" belongs here, not in `fail`.
+- `ctx.fail(reason)` — narrow; only when polling cannot help (invariant violated, contradictory value). Stops immediately.
 
-## Observer coverage
+Thrown exceptions are treated as `fail`.
 
-Lint enforces backend assertions on mutation flows:
+## Observer coverage
 
-- **`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.
+Two lint rules enforce backend assertions on mutation flows. `mutation-without-observer-coverage` flags save / create / update / delete clicks, uploads, and accepted dialogs that aren't followed by an `assert.backend(...)`. `observer-params-reference-variables` flags assertions whose params are all string literals while the test declares precondition variables.
 
-For steps that genuinely don't touch server state (cancel dialogs, client-side sort), pass `{ uiOnly: true }`:
+Steps that genuinely touch no server state (cancel dialogs, client-side sort) opt out with `{ uiOnly: true }`:
 
 ```typescript
 click(role("button", "Cancel"), { uiOnly: true }).as("close dialog");
 test("filter-sort", { 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.
-
-## 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`).
+`uiOnly` means zero backend effect. Mutations and optimistic UI need an observer.
 
 ## Server adapters
 
-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:
-
-```ts
-enabled: process.env.ENABLE_RIPPLO_TESTING === "true";
-```
-
-When `enabled` is false the adapter mounts a no-op handler.
+Every adapter takes the `engine` from `createEngine(...)` and a required `enabled: boolean`. Bind `enabled` to `process.env.ENABLE_RIPPLO_TESTING === "true"` so the routes can't ship to production; when it's false the adapter mounts a no-op handler.
 
 ### Express
 
@@ -402,7 +313,7 @@ await app.register(registerFastifyHandler({ enabled, engine }), { prefix: "/ripp
 
 ### Next.js (App Router)
 
-A single catch-all route — runs on Node and Edge.
+A single catch-all route. Works on Node and Edge.
 
 ```ts
 // app/ripplo/[action]/route.ts
@@ -423,7 +334,7 @@ const app = new Hono();
 app.route("/ripplo", createHonoHandler({ enabled, engine }));
 ```
 
-Web-standard `Request`/`Response`; runs on Node, Bun, Deno, Cloudflare Workers.
+Web-standard `Request`/`Response`. Runs on Node, Bun, Deno, and Cloudflare Workers.
 
 ### Koa
 
@@ -437,7 +348,7 @@ const app = new Koa();
 app.use(mount("/ripplo", createKoaHandler({ enabled, engine })));
 ```
 
-The Koa adapter reads the raw body itself — don't mount a body-parser in front of it.
+The Koa adapter reads the raw body itself; don't mount a body-parser in front of it.
 
 ### NestJS
 
@@ -466,7 +377,7 @@ const app = new Elysia().group("/ripplo", (g) => g.use(createElysiaHandler({ ena
 
 ### Custom (raw engine)
 
-For unsupported frameworks. The adapters above are thin wrappers over this API.
+For frameworks not listed above. The adapters above are thin wrappers over this API. A custom adapter reads the raw request body, verifies the signature with `verifyWebhookSignature`, dispatches the three routes to `engine.executePreconditions`, `engine.executeObserver`, and `engine.teardownPreconditions`, and shapes responses with `toBatchRunResults` / `toTeardownResults`. Cookies travel inside the JSON response body, not `Set-Cookie` headers; the runtime parses them out and applies them to the browser context.
 
 ```ts
 import {
@@ -493,48 +404,38 @@ async function executePreconditions(req: Request): Promise<Response> {
     return new Response(JSON.stringify({ error: "Invalid signature" }), { status: 401 });
   }
 
-  // Request body is a batch: { batch: [{ runId, preconditions: [...names] }, ...] }
   const { batch } = JSON.parse(body);
   const appUrl = `${req.headers.get("x-forwarded-proto") ?? "http"}://${req.headers.get("host")}`;
   const results = await engine.executePreconditions(
     batch.map((b) => ({ runId: b.runId, names: b.preconditions })),
     { appUrl },
   );
-
-  // Response body: { results: [{ runId, ok, cookies, data, executed } | { runId, ok: false, error }] }
   return new Response(JSON.stringify({ results: toBatchRunResults(results) }), {
     headers: { "content-type": "application/json" },
   });
 }
-// teardown-preconditions and execute-observer follow the same verify-then-dispatch pattern.
-// teardown's request shape is { batch: [{ runId, preconditions, data }, ...] }, response { results: [{ runId, ok, error? }] }.
 ```
 
-You're responsible for: webhook verification (always before invoking the engine), routing the three endpoints, calling `toBatchRunResults` / `toTeardownResults` to shape the response body, and reading the raw body for signature verification before `JSON.parse`. Cookies travel inside the JSON response body — never as `Set-Cookie` headers; the runtime parses them out and applies them to the test browser context.
+`executeObserver` and `teardownPreconditions` follow the same verify-then-dispatch shape. Request bodies: `{ batch: [{ runId, preconditions, data }] }` for teardown, `{ runId, name, params }` for observers.
 
 ## Security & parallelism
 
-- 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 data this run created. Bulk operations are fine — and encouraged — as long as the `WHERE` is scoped to the batch's own ids (`deleteMany({ where: { id: { in: items.map((it) => it.ctx.data.userId) } } })`). Never write a `WHERE` that could match another run's rows.
+Every request is signed with Standard Webhooks (HMAC-SHA256) over the `webhook-id`, `webhook-timestamp`, and `webhook-signature` headers; verify before executing. `ENABLE_RIPPLO_TESTING` gates every adapter and must never be true in production.
 
-## Lockfile
+For parallel runs, use `ctx.uniqueId(prefix)` and `ctx.uniqueEmail()` to avoid collisions, return the created entity ids in the data contract, and scope teardown's `WHERE` to those ids. `deleteMany` is fine and preferred, as long as the predicate can only match this batch's rows.
 
-`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.
+## Lockfile
 
-- `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.
+`ripplo compile`, `ripplo lint`, and `ripplo watch` all write `.ripplo/ripplo.lock`. Commit it; the Ripplo server reads it on every push webhook and returns 422 if it's missing or stale. `ripplo compile --check` exits non-zero on a stale lockfile and belongs in pre-commit and CI. `ripplo doctor` surfaces stale lockfiles and missing pre-commit hooks.
 
 ## CLI
 
-The CLI lives in [`ripplo`](https://www.npmjs.com/package/ripplo). Most-used commands:
-
 ```bash
 ripplo auth login       # authenticate
-ripplo init             # scaffold .ripplo/ + write env vars
-ripplo watch            # local executor — run as a standalone background process
+ripplo init             # scaffold .ripplo/ and write env vars
+ripplo watch            # local executor (run as a background process)
 ripplo lint [ids..]     # compile + lint
 ripplo run [ids..]      # run tests in parallel
 ```
+
+Full command reference at [`ripplo`](https://www.npmjs.com/package/ripplo).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ripplo/testing",
   "description": "TypeScript DSL for defining and running Ripplo e2e workflow tests",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "type": "module",
   "files": [
     "dist"