ripplo 0.0.11 → 0.1.0

package/README.md

@@ -4,7 +4,15 @@ CLI for [Ripplo](https://ripplo.ai) — AI-powered end-to-end testing.
 
 ## Quick Start
 
-Run this in your project directory:
+### 1. Install the CLI
+
+```sh
+npm install -g ripplo
+```
+
+Or use `npx ripplo` directly.
+
+### 2. Authenticate and set up
 
 ```sh
 npx ripplo
@@ -12,30 +20,91 @@ npx ripplo
 
 This will:
 
-- Authenticate and connect your project
-- Auto-install the MCP server for your coding agent
-- Scaffold a `.ripplo/` directory for your test graph
-- Start dev mode — build locally, deploy to cloud when ready
+- Authenticate via device code flow
+- Let you select a project
+- Scaffold a `.ripplo/` directory with starter files
+- Start the dev dashboard
+
+### 3. Install the Claude Code plugin
+
+In Claude Code, run:
+
+```
+/plugin marketplace add ripplo/claude-plugin
+/plugin install ripplo
+```
+
+The plugin hooks into your agent's workflow to create a tight validation loop — linting workflow specs on every edit, and automatically validating and running all tests before each session ends. Your agent writes deterministic, parallelizable tests that verify your app works end-to-end.
+
+**Skills:**
+
+| Skill                  | Description                                           |
+| ---------------------- | ----------------------------------------------------- |
+| `/ripplo:explore`      | Crawl your codebase and generate workflow specs       |
+| `/ripplo:create`       | Create a new workflow spec                            |
+| `/ripplo:run`          | Run workflows in parallel                             |
+| `/ripplo:debug`        | Debug failures using DOM snapshots and network traces |
+| `/ripplo:flake-detect` | Run N parallel executions to detect flaky tests       |
 
-Your agent will handle the rest — no manual test writing required.
+**Hooks:**
 
-Then paste `/mcp` into Claude Code (or your coding agent) to activate the Ripplo MCP.
+| Hook        | What it does                                                                |
+| ----------- | --------------------------------------------------------------------------- |
+| Post-edit   | Lints workflow specs on every file change — your agent fixes issues in-line |
+| Session end | Validates all workflows, flags unimplemented specs, and runs the full suite |
+
+### 4. Add `@ripplo/testing` to your project
+
+```sh
+npm install @ripplo/testing
+```
+
+This is the DSL your `.ripplo/` files use to define workflows and preconditions.
 
 ## How It Works
 
-**Finding your key user flows** — Your agent reads through your app to find the important things users do — signing up, logging in, creating content. It maps these into a test graph so every flow can be tested independently.
+**Define tests as code** — Tests are TypeScript files using a typed DSL. Your agent writes them, or you write them by hand. Each test defines its preconditions, starting URL, and interaction steps.
 
-**Every test gets a clean slate** — Each test defines its own preconditions like a fresh user, sample data, and the right permissions. No shared data or ordering dependencies. Scale to thousands of tests without flakes.
+**Every test gets a clean slate** — Each test defines its own preconditions (fresh user, sample data, permissions). No shared state or ordering dependencies.
 
-**Dev mode to cloud** — Your agent builds and runs tests locally as you develop. When you merge, workflows sync from your repo and run in the cloud against your deployed environment.
+**Dev mode to cloud** — The dashboard runs tests locally as you develop. When you merge, tests sync and run in the cloud against your deployed environment.
 
-**Secure by default** — Every request to your app is cryptographically signed so you know it's from Ripplo. Test endpoints are gated behind an environment variable — they're never exposed in production.
+**Secure by default** — Every precondition request is cryptographically signed. Test endpoints are gated behind a webhook secret.
 
 ## Commands
 
-| Command          | Description                                          |
-| ---------------- | ---------------------------------------------------- |
-| `ripplo`         | Launch the interactive dashboard                     |
-| `generate-types` | Generate Zod schemas + TS types for precondition API |
+| Command                      | Description                            |
+| ---------------------------- | -------------------------------------- |
+| `ripplo`                     | Launch the interactive dashboard       |
+| `ripplo run [slugs..]`       | Run tests in parallel                  |
+| `ripplo lint [slugs..]`      | Compile and lint workflows             |
+| `ripplo list`                | List all tests with status             |
+| `ripplo doctor`              | Check project health                   |
+| `ripplo flake-detect <slug>` | Run a test N times to detect flakiness |
+| `ripplo sync`                | Sync tests to the dev session          |
+
+## Project Structure
+
+After setup, your project will have:
+
+```
+.ripplo/
+├── ripplo.ts          # Config: createRipplo({ projectId, appUrl, ... })
+├── index.ts           # Entry point
+├── preconditions.ts   # Test data setup/teardown
+└── workflows/         # One file per user flow
+    └── example.ts     # Starter workflow
+```
+
+Configuration lives in `ripplo.ts` via `createRipplo()`:
+
+```ts
+const ripplo = createRipplo({
+  appUrl: "http://localhost:3000",
+  preconditionsUrl: "http://localhost:3000/ripplo/preconditions",
+  projectId: "your-project-id",
+  webhookSecret: process.env["RIPPLO_WEBHOOK_SECRET"] ?? "",
+});
+```
 
 Learn more at [ripplo.ai](https://ripplo.ai).