ripplo 0.3.17 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +50 -91
- package/dist/index.js +364 -457
- package/package.json +6 -17
package/README.md
CHANGED
|
@@ -1,123 +1,82 @@
|
|
|
1
1
|
# ripplo
|
|
2
2
|
|
|
3
|
-
CLI for [Ripplo](https://ripplo.ai) —
|
|
3
|
+
CLI for [Ripplo](https://ripplo.ai) — typed end-to-end tests with real backend state.
|
|
4
4
|
|
|
5
|
-
##
|
|
6
|
-
|
|
7
|
-
### 1. Install the CLI
|
|
5
|
+
## Install
|
|
8
6
|
|
|
9
7
|
```sh
|
|
10
8
|
npm install -g ripplo
|
|
9
|
+
# or: npx ripplo <subcommand>
|
|
11
10
|
```
|
|
12
11
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
### 2. Authenticate and set up
|
|
12
|
+
## Setup
|
|
16
13
|
|
|
17
14
|
```sh
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
This will:
|
|
22
|
-
|
|
23
|
-
- Authenticate via device code flow
|
|
24
|
-
- Let you select a project
|
|
25
|
-
- Scaffold a `.ripplo/` directory with starter files
|
|
26
|
-
- Start the dev dashboard
|
|
27
|
-
|
|
28
|
-
### 3. Install the Claude Code plugin
|
|
29
|
-
|
|
30
|
-
In Claude Code, run:
|
|
31
|
-
|
|
15
|
+
ripplo auth login # device-code flow; opens a browser
|
|
16
|
+
ripplo init # scaffolds .ripplo/ and writes RIPPLO_* env vars
|
|
32
17
|
```
|
|
33
|
-
/plugin marketplace add ripplo/claude-plugin
|
|
34
|
-
/plugin install ripplo
|
|
35
|
-
```
|
|
36
|
-
|
|
37
|
-
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.
|
|
38
18
|
|
|
39
|
-
|
|
19
|
+
`init` is interactive (or pass `--project`, `--env-file`, `--app-url`, `--engine-url`). It scaffolds `.ripplo/{index.ts, project.json, preconditions/, observers/, tests/}`, appends `RIPPLO_APP_URL` / `RIPPLO_ENGINE_URL` / `RIPPLO_WEBHOOK_SECRET` to your env file, and installs `@ripplo/testing`.
|
|
40
20
|
|
|
41
|
-
|
|
42
|
-
| ---------------------- | ----------------------------------------------------- |
|
|
43
|
-
| `/ripplo:explore` | Crawl your codebase and generate workflow specs |
|
|
44
|
-
| `/ripplo:create` | Create a new workflow spec |
|
|
45
|
-
| `/ripplo:run` | Run workflows in parallel |
|
|
46
|
-
| `/ripplo:debug` | Debug failures using DOM snapshots and network traces |
|
|
47
|
-
| `/ripplo:flake-detect` | Run N parallel executions to detect flaky tests |
|
|
21
|
+
Add `ripplo watch` to your dev script — it's the local executor that subscribes to run requests and runs tests against your dev server:
|
|
48
22
|
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
| Hook | What it does |
|
|
52
|
-
| ----------- | --------------------------------------------------------------------------- |
|
|
53
|
-
| Post-edit | Lints workflow specs on every file change — your agent fixes issues in-line |
|
|
54
|
-
| Session end | Validates all workflows, flags unimplemented specs, and runs the full suite |
|
|
55
|
-
|
|
56
|
-
### 4. Add `@ripplo/testing` to your project
|
|
57
|
-
|
|
58
|
-
```sh
|
|
59
|
-
npm install @ripplo/testing
|
|
23
|
+
```json
|
|
24
|
+
"dev": "concurrently -k -n app,ripplo \"next dev\" \"ripplo watch\""
|
|
60
25
|
```
|
|
61
26
|
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
## How It Works
|
|
27
|
+
Then mount the engine adapter into your app server (Express, Fastify, Next.js, Hono, Koa, NestJS, Elysia) — see [`@ripplo/testing`](https://www.npmjs.com/package/@ripplo/testing) for the adapter snippets.
|
|
65
28
|
|
|
66
|
-
|
|
29
|
+
For a guided setup, install the [Claude Code plugin](https://www.npmjs.com/package/@ripplo/claude-plugin) and run `/ripplo:setup`.
|
|
67
30
|
|
|
68
|
-
|
|
31
|
+
## Worktrees
|
|
69
32
|
|
|
70
|
-
|
|
33
|
+
Each git worktree is its own self-contained Ripplo project: own DevSession, scope, debug artifacts, and lockfile checkout. Auth token, Playwright browser, projectId, and webhook secret are shared globally — no re-auth or re-init needed when you create a new worktree.
|
|
71
34
|
|
|
72
|
-
|
|
35
|
+
Two things won't carry over automatically:
|
|
73
36
|
|
|
74
|
-
**
|
|
37
|
+
- **Env files are usually gitignored.** A fresh worktree won't have your `.env.local` (or whichever file `ripplo init` wrote `RIPPLO_*` vars to). Copy it from the main checkout, or point all worktrees at a shared file outside the working tree (e.g. `envFiles: ["../.shared.env"]` in `.ripplo/project.json`). `ripplo doctor` flags missing env files explicitly.
|
|
38
|
+
- **Dev server port + URL vars.** Two sibling worktrees can't both run `pnpm dev` on the same port. Pick a distinct port for this worktree, **and update both `RIPPLO_APP_URL` and `RIPPLO_ENGINE_URL`** in this worktree's env file to match — e.g. main on `:3000` → this worktree on `:3001` → set `RIPPLO_APP_URL=http://localhost:3001` and `RIPPLO_ENGINE_URL=http://localhost:3001/ripplo`. If the URL vars stay pointing at main's port, `ripplo watch` talks to the wrong dev server.
|
|
75
39
|
|
|
76
40
|
## Commands
|
|
77
41
|
|
|
78
|
-
| Command | Description
|
|
79
|
-
| -------------------------- |
|
|
80
|
-
| `ripplo`
|
|
81
|
-
| `ripplo
|
|
82
|
-
| `ripplo
|
|
83
|
-
| `ripplo
|
|
84
|
-
| `ripplo
|
|
85
|
-
| `ripplo
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
42
|
+
| Command | Description |
|
|
43
|
+
| -------------------------- | ---------------------------------------------------------------------------------------------- |
|
|
44
|
+
| `ripplo auth login` | Authenticate via device code flow |
|
|
45
|
+
| `ripplo auth status` | Show current authentication |
|
|
46
|
+
| `ripplo auth logout` | Remove the saved token |
|
|
47
|
+
| `ripplo init` | Scaffold `.ripplo/` and write `RIPPLO_*` env vars |
|
|
48
|
+
| `ripplo watch` | Subscribe to run requests; execute tests against your dev server |
|
|
49
|
+
| `ripplo run [ids..]` | Run tests in parallel (all if no ids) |
|
|
50
|
+
| `ripplo lint [ids..]` | Compile and lint; writes `.ripplo/ripplo.lock` |
|
|
51
|
+
| `ripplo compile [--check]` | Rebuild the lockfile (`--check` = exit non-zero if stale; for CI/hooks) |
|
|
52
|
+
| `ripplo sync` | Push the compiled `.ripplo/` resources to the server (no run; useful for debugging sync state) |
|
|
53
|
+
| `ripplo doctor` | Check lockfile freshness, auth, env |
|
|
54
|
+
| `ripplo status` | Report unimplemented tests and preconditions |
|
|
55
|
+
| `ripplo cover` | Audit coverage statements across the whole tree |
|
|
56
|
+
| `ripplo scope <sub>` | Manage testing scope (`add`, `link`, `remove`, `status`) |
|
|
57
|
+
| `ripplo flake-detect <id>` | Run a test N times in parallel to detect flakiness |
|
|
58
|
+
|
|
59
|
+
`init` flags: `--project <id> --env-file <path> --app-url <url> --engine-url <url>`. `--env-file` is **relative to `.ripplo/`** (e.g. `../.env.local` for a repo-root file, `../apps/server/.env` for a monorepo). `--engine-url` defaults to `<app-url>/ripplo`; override it when the adapter mounts at a different prefix or your backend runs on a different port than your frontend.
|
|
60
|
+
|
|
61
|
+
## Project layout
|
|
90
62
|
|
|
91
63
|
```
|
|
92
64
|
.ripplo/
|
|
93
|
-
├──
|
|
94
|
-
├──
|
|
95
|
-
├──
|
|
96
|
-
├── preconditions/index.ts
|
|
97
|
-
├── observers/index.ts
|
|
65
|
+
├── index.ts # createRipplo({ preconditions, observers, tests })
|
|
66
|
+
├── project.json # projectId + envFile pointers
|
|
67
|
+
├── ripplo.lock # generated + committed; read by the Ripplo server on push
|
|
68
|
+
├── preconditions/index.ts # handles + `preconditions` registry
|
|
69
|
+
├── observers/index.ts # handles + `observers` registry
|
|
98
70
|
└── tests/
|
|
99
|
-
|
|
100
|
-
└── <test-id>.ts # Each file exports one TestDefinition
|
|
71
|
+
└── <test-id>.ts # one TestDefinition per file
|
|
101
72
|
```
|
|
102
73
|
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
import { observers } from "./observers/index.js";
|
|
109
|
-
import { tests } from "./tests/index.js";
|
|
110
|
-
|
|
111
|
-
export default createRipplo(
|
|
112
|
-
{
|
|
113
|
-
appUrl: "http://localhost:3000",
|
|
114
|
-
engineUrl: "http://localhost:3000/ripplo",
|
|
115
|
-
projectId: "your-project-id",
|
|
116
|
-
},
|
|
117
|
-
{ preconditions, observers, tests },
|
|
118
|
-
);
|
|
119
|
-
```
|
|
74
|
+
Test definitions live in `.ripplo/`. **Implementations** (precondition setup/teardown, observer functions) live in your app server via `createEngine(ripplo, { preconditions, observers })`. Both halves are exhaustiveness-checked at compile time.
|
|
75
|
+
|
|
76
|
+
See [`@ripplo/testing`](https://www.npmjs.com/package/@ripplo/testing) for the DSL reference and adapter wiring.
|
|
77
|
+
|
|
78
|
+
## Lockfile
|
|
120
79
|
|
|
121
|
-
|
|
80
|
+
`ripplo compile` writes `.ripplo/ripplo.lock`. **Commit it.** The Ripplo server reads it on every GitHub push webhook; stale or missing returns 422.
|
|
122
81
|
|
|
123
|
-
|
|
82
|
+
In a pre-commit hook, run `ripplo compile --check` on staged `.ripplo/**/*.ts`.
|