ripplo 0.6.0 → 0.7.0

package/LICENSE.md

@@ -0,0 +1 @@
+© Ripplo LLC. All rights reserved. Use is subject to Ripplo's [Terms of Service](https://ripplo.ai/terms).

package/README.md

@@ -1,12 +1,29 @@
 # ripplo
 
-CLI for [Ripplo](https://ripplo.ai). Typed end-to-end tests with real backend state.
+Describe how your app should behave. Ripplo proves it does.
 
-Run via `npx ripplo <command>` so you always pick up the latest version. No global install needed.
+You declare your app's state model and user flows in TypeScript. Ripplo seeds real data, drives a real browser, and checks the result against the model: the UI you asserted on and the rows that should have changed underneath it.
 
-## Recommended setup: Claude Code plugin
+```ts
+export const createTask = test("Create a task", () => {
+  const { me, project } = ownedProject();
+  return {
+    given: [me, project],
+    steps: [
+      goto`/projects/${project.id}/tasks`.expect(visible(button("New"))),
+      click(button("New")).expect(visible(textbox("Title"))),
+      fill(textbox("Title"), "Buy milk"),
+      click(button("Create")).expect(Task.created({ title: "Buy milk", projectId: project.id })),
+    ],
+  };
+});
+```
+
+`ownedProject()` describes the starting state; Ripplo seeds it fresh for every run. `Task.created(...)` is checked against your actual database through a small engine you write once per entity.
 
-If you use Claude Code, this is the shortest path. The plugin handles auth, scaffolding, and adapter wiring, and adds hooks that keep tests in sync with code changes.
+## Setup with Claude Code
+
+If you use Claude Code, this is the shortest path. The plugin handles auth, scaffolding, and adapter wiring, and adds hooks that keep tests in sync as the agent changes your code.
 
 ```
 /plugin marketplace add ripplo/claude-plugin
@@ -14,62 +31,74 @@ If you use Claude Code, this is the shortest path. The plugin handles auth, scaf
 /ripplo:setup
 ```
 
-That's it. Skip the rest of this README unless you want to know what `/ripplo:setup` is doing under the hood, or you're not on Claude Code.
+Skip the rest of this section unless you want to know what `/ripplo:setup` does, or you're not on Claude Code.
 
-## Manual setup
+## Setup by hand
 
-Three steps: authenticate, scaffold, mount the adapter in your app server.
+Three steps: authenticate, scaffold, mount the engine adapter in your app server.
 
 ```sh
 npx ripplo auth login   # device-code flow, opens a browser
 npx ripplo init         # scaffolds .ripplo/ and writes RIPPLO_* env vars
 ```
 
-`ripplo init` is interactive. It creates `.ripplo/{index.ts, project.json, preconditions/, observers/, tests/}`, appends `RIPPLO_APP_URL`, `RIPPLO_ENGINE_URL`, and `RIPPLO_WEBHOOK_SECRET` to your env file, and installs `@ripplo/testing`.
+`ripplo init` creates `.ripplo/` (entities, worlds, tests, plus a `project.json`), appends `RIPPLO_APP_URL`, `RIPPLO_ENGINE_URL`, and `RIPPLO_WEBHOOK_SECRET` to your env file, and installs [`@ripplo/testing`](https://www.npmjs.com/package/@ripplo/testing).
 
-Then mount the adapter in your app server. Next.js App Router:
+Then mount the adapter. This is the one piece of code that lives in your app: a signed-webhook endpoint Ripplo calls to seed and read state, active only when you flip the env var.
 
 ```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,
-});
+// Express
+import { createEngineHandler } from "@ripplo/testing/express";
+import { engine } from "./test/engine.js";
+
+app.use(
+  "/ripplo",
+  createEngineHandler({ enabled: process.env.ENABLE_RIPPLO_TESTING === "true", engine }),
+);
 ```
 
-For Express, Fastify, Hono, Koa, NestJS, or Elysia, see [`@ripplo/testing`](https://www.npmjs.com/package/@ripplo/testing).
+`engine` is where you implement `seed` and `read` for each entity you declared; TypeScript flags any entity you forgot. More framework adapters are coming; any server that can mount an Express router works today.
+
+Last, preload [`@ripplo/instrument`](https://www.npmjs.com/package/@ripplo/instrument) in your dev server so test runs capture your backend spans alongside browser actions:
 
-`engine` is what you write in `src/test/engine.ts` to provide the implementations for the preconditions and observers you defined in `.ripplo/`. The DSL reference covers it.
+```sh
+node --import @ripplo/instrument server.js   # or NODE_OPTIONS="--import @ripplo/instrument" next dev
+```
+
+It exports spans to the local daemon during runs and stays dormant otherwise, so it's safe to leave in your dev script permanently.
 
 ## Running tests
 
-In one terminal, start the local executor:
+Start the daemon in one terminal and leave it running next to your dev server:
 
 ```sh
-npx ripplo watch
+npx ripplo daemon
 ```
 
-Leave it running alongside your dev server. It subscribes to run requests and drives Playwright against your local app.
-
-In another, run tests:
+It keeps a warm browser pool and executes runs in parallel as they come in. Then:
 
 ```sh
-npx ripplo run            # scope + dirty tests
+npx ripplo run            # tests in scope + tests affected by your changes
 npx ripplo run --all      # everything
-npx ripplo run my-test    # by id
+npx ripplo run my-test    # one test by id
 ```
 
-Commit `.ripplo/ripplo.lock`. The Ripplo server reads it on every push webhook; `ripplo compile --check` in a pre-commit hook keeps it fresh.
+`run` connects to the daemon and streams results; if a daemon is absent it starts one for you.
+
+## The lockfile
+
+`.ripplo/` compiles to `.ripplo/ripplo.lock`. Commit it. The Ripplo server reads the lockfile on every push, so your dashboard and CI always reflect what's actually in the branch. `npx ripplo compile --check` in a pre-commit hook (installed by setup) keeps it fresh.
 
 ## Worktrees
 
-Ripplo is built for parallel feature work via `git worktree`. Each worktree gets its own dev session, scope, debug artifacts, and lockfile checkout — your auth token, projectId, and webhook secret are shared globally, so a fresh worktree needs no re-auth or re-init. Spin up as many as you want and run them concurrently.
+Ripplo is built for parallel feature work via `git worktree`. Each worktree gets its own dev session, scope, debug artifacts, and lockfile checkout, while auth and project config are shared globally, so a fresh worktree is ready to run as-is.
 
-Two things to know: env files are usually gitignored, so copy your `.env.local` into the new worktree (or point `envFiles` in `.ripplo/project.json` at a shared file outside the tree), and pick a distinct dev-server port — update both `RIPPLO_APP_URL` and `RIPPLO_ENGINE_URL` to match. `ripplo doctor` flags both.
+Two things to handle per worktree: copy your gitignored env file in (or point `envFiles` in `.ripplo/project.json` at a shared path outside the tree), and pick a distinct dev-server port, updating `RIPPLO_APP_URL` and `RIPPLO_ENGINE_URL` to match. `ripplo doctor` flags both if you forget.
 
 ## Other commands
 
-`npx ripplo --help` lists everything. The ones you'll use beyond setup: `lint` (compile + typecheck), `doctor` (auth/env/lockfile health), `scope` (manage what the current session is testing), `flake-detect` (run a test in parallel N times).
+`npx ripplo --help` lists everything. Beyond setup you'll mostly use `lint` (compile + typecheck your `.ripplo/`), `doctor` (auth, env, and lockfile health), and `scope` (manage which flows the current session is responsible for).
+
+## License
+
+© Ripplo LLC. All rights reserved. Use is subject to Ripplo's [Terms of Service](https://ripplo.ai/terms).

package/dist/assets/browser-trace.js

@@ -0,0 +1 @@
+"use strict";(()=>{var o=globalThis.fetch;function a(n){return Array.from(crypto.getRandomValues(new Uint8Array(n)),r=>r.toString(16).padStart(2,"0")).join("")}globalThis.fetch=(n,r)=>{let e=new Headers(r?.headers);e.has("traceparent")||e.set("traceparent",`00-${a(16)}-${a(8)}-01`);let t=globalThis.__ripploRunId;return t!=null&&!e.has("baggage")&&e.set("baggage",`ripplo.run=${encodeURIComponent(t)}`),o(n,{...r,headers:e})};})();