ripplo 0.9.8 → 0.11.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.
Files changed (101) hide show
  1. package/README.md +105 -47
  2. package/dist/assets/rrweb-replay.js +1 -1
  3. package/dist/assets/rrweb.js +1 -1
  4. package/dist/capture-worker.js +20 -14
  5. package/dist/chunk-3HAQCJRK.js +4 -0
  6. package/dist/{chunk-5E62BCS7.js → chunk-47LLHHJH.js} +2 -2
  7. package/dist/chunk-4YAC72LW.js +7 -0
  8. package/dist/chunk-5HFJIZLI.js +4 -0
  9. package/dist/chunk-6U2LNGSV.js +51 -0
  10. package/dist/{chunk-2GFHB4LD.js → chunk-6WFJZ5L6.js} +1 -1
  11. package/dist/chunk-7JKCHASU.js +4 -0
  12. package/dist/{chunk-3UZZBLVA.js → chunk-7RREARGA.js} +2 -2
  13. package/dist/{chunk-WNAVYV4P.js → chunk-AXROBTLA.js} +1 -1
  14. package/dist/chunk-BGY5F3IU.js +5 -0
  15. package/dist/{chunk-IPSXNIXC.js → chunk-C7SV6AR2.js} +4 -4
  16. package/dist/chunk-CI6273ZU.js +107 -0
  17. package/dist/chunk-DY7ZW6QZ.js +9 -0
  18. package/dist/chunk-E6ZBZIIS.js +4 -0
  19. package/dist/chunk-G6J2WIHJ.js +4 -0
  20. package/dist/{chunk-64OQXBRG.js → chunk-GYBY7EOO.js} +1 -1
  21. package/dist/{chunk-LOEAZGYO.js → chunk-HEOMRXZE.js} +1 -1
  22. package/dist/chunk-IK3ROREL.js +6 -0
  23. package/dist/{chunk-7W237JFM.js → chunk-JS3DLVVI.js} +1 -1
  24. package/dist/{chunk-TPHOSZAK.js → chunk-KH4QH23U.js} +1 -1
  25. package/dist/{chunk-OES7HGNF.js → chunk-LEFODI2H.js} +1 -1
  26. package/dist/{chunk-7EL64XR6.js → chunk-LWMXGWS2.js} +1 -1
  27. package/dist/chunk-O45YB6YY.js +354 -0
  28. package/dist/{chunk-YQ2RBEOJ.js → chunk-PXXURBGC.js} +2 -2
  29. package/dist/{chunk-OAU4HUD2.js → chunk-PYDYI3AA.js} +2 -2
  30. package/dist/{chunk-R3DZ6JPY.js → chunk-RIASQHPG.js} +1 -1
  31. package/dist/chunk-S2K5KILQ.js +8 -0
  32. package/dist/chunk-SXVWB7TZ.js +6 -0
  33. package/dist/chunk-UH5CQF5R.js +6 -0
  34. package/dist/{chunk-GZ3M7PNW.js → chunk-VKAZQPJJ.js} +1 -1
  35. package/dist/chunk-WAGXAEB4.js +13 -0
  36. package/dist/chunk-WBKSJU63.js +83 -0
  37. package/dist/{chunk-AGK6XOX2.js → chunk-XAMVRZJH.js} +2 -2
  38. package/dist/chunk-ZHDR7LXB.js +56 -0
  39. package/dist/{cli-error-TS4FNZ6F.js → cli-error-6PUIWNIT.js} +1 -1
  40. package/dist/{compile-write-BLJH647I.js → compile-write-KUUFWSI4.js} +1 -1
  41. package/dist/daemon-2ZTZXQW6.js +4 -0
  42. package/dist/daemon-GP3EIISA.js +152 -0
  43. package/dist/{daemon-lock-OAARBZ4O.js → daemon-lock-RPKO5SNE.js} +1 -1
  44. package/dist/dsl-loader-WPAKMON7.js +4 -0
  45. package/dist/dsl-typecheck-worker.js +6 -0
  46. package/dist/{exit-plan-gate-HSTV7UO4.js → exit-plan-gate-44YWEKYS.js} +1 -1
  47. package/dist/hook.js +1 -1
  48. package/dist/index.js +207 -260
  49. package/dist/{plan-reminder-RBCRBCKC.js → plan-reminder-PP5DQAQZ.js} +1 -1
  50. package/dist/post-edit-R7KN424T.js +4 -0
  51. package/dist/post-edit-analyze-UURDL3AH.js +4 -0
  52. package/dist/post-edit-flag-stubs-I7AUGN4D.js +4 -0
  53. package/dist/pre-bash-run-gate-MIEM2DBB.js +4 -0
  54. package/dist/pre-edit-C4MGURNO.js +4 -0
  55. package/dist/pre-edit-ripplo-skill-gate-A6ETC3QN.js +4 -0
  56. package/dist/pre-edit-scope-gate-M5IQSVGF.js +4 -0
  57. package/dist/{pre-edit-watch-gate-SJ3RCYH5.js → pre-edit-watch-gate-ORQP7MSW.js} +1 -1
  58. package/dist/prompt-submit-6KNOFK4W.js +4 -0
  59. package/dist/scope-reminder-A6GVTTVE.js +4 -0
  60. package/dist/session-preamble-IZQPIWST.js +4 -0
  61. package/dist/status-PG4EBZRM.js +4 -0
  62. package/dist/{stop-enforce-VWOM5EZY.js → stop-enforce-CO5GYI3G.js} +9 -9
  63. package/dist/tasks-reminder-TDWPD3KV.js +4 -0
  64. package/dist/{track-skill-load-CJ74GD3Q.js → track-skill-load-SXSDMHFO.js} +1 -1
  65. package/dist/{track-skill-prompt-YSB6OOQN.js → track-skill-prompt-7N4TQAD2.js} +1 -1
  66. package/package.json +3 -6
  67. package/dist/chunk-22JUAYHM.js +0 -4
  68. package/dist/chunk-7IIRERCW.js +0 -8
  69. package/dist/chunk-7VGCLQGP.js +0 -7
  70. package/dist/chunk-7YQOAAKF.js +0 -224
  71. package/dist/chunk-AWPZTNYU.js +0 -6
  72. package/dist/chunk-CB74TAUC.js +0 -5
  73. package/dist/chunk-CTTC4KKQ.js +0 -83
  74. package/dist/chunk-GI65FUDI.js +0 -6
  75. package/dist/chunk-IDPJESOE.js +0 -9
  76. package/dist/chunk-IKYR3UCU.js +0 -55
  77. package/dist/chunk-LB65USNP.js +0 -73
  78. package/dist/chunk-MOI4L3EX.js +0 -4
  79. package/dist/chunk-N2OBRCPQ.js +0 -6
  80. package/dist/chunk-NY6EIQR4.js +0 -4
  81. package/dist/chunk-OQ4TDIP3.js +0 -55
  82. package/dist/chunk-OQS63V7U.js +0 -7
  83. package/dist/chunk-OWN4P2K7.js +0 -4
  84. package/dist/chunk-SNU66GSR.js +0 -4
  85. package/dist/chunk-TOBC3SQA.js +0 -8
  86. package/dist/daemon-QKBWYQJA.js +0 -4
  87. package/dist/daemon-UMZJZ7BY.js +0 -152
  88. package/dist/dsl-loader-NGW4V4A3.js +0 -4
  89. package/dist/post-edit-MVGQGAW4.js +0 -4
  90. package/dist/post-edit-analyze-XWTZMQCB.js +0 -4
  91. package/dist/post-edit-flag-stubs-4MQZATJE.js +0 -4
  92. package/dist/pre-bash-run-gate-B42YNDQF.js +0 -4
  93. package/dist/pre-edit-YF6WNE6G.js +0 -4
  94. package/dist/pre-edit-ripplo-skill-gate-QHUD7QGU.js +0 -4
  95. package/dist/pre-edit-scope-gate-2YIFSEDY.js +0 -4
  96. package/dist/prompt-submit-YX7GMTC4.js +0 -4
  97. package/dist/scope-reminder-DIDCHDAA.js +0 -4
  98. package/dist/session-preamble-ZYVRDSGA.js +0 -4
  99. package/dist/solve-worker.js +0 -4
  100. package/dist/status-HPMHJBKH.js +0 -4
  101. package/dist/tasks-reminder-SDS6RNLP.js +0 -4
package/README.md CHANGED
@@ -1,102 +1,160 @@
1
1
  # ripplo
2
2
 
3
- Describe how your app should behave. Ripplo proves it does.
4
-
5
- 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.
3
+ Model a critical user journey once. Ripplo synthesizes valid starting state, drives the browser,
4
+ and verifies the complete visible and application-state result.
6
5
 
7
6
  ```ts
8
- export const createTask = test("Create a task", () => {
9
- const { me, project } = ownedProject();
7
+ const projectActions = surface(menu("Project actions"), { overlay: true });
8
+
9
+ export const renameProject = workflow("Rename a project", () => {
10
+ const project = required(projects, {});
11
+ const nextName = arbitrary(projects.name);
12
+ const selectedProject = select(projects, { id: project.id });
13
+
10
14
  return {
11
- given: [me, project],
15
+ given: [viewport.desktop, project],
12
16
  steps: [
13
- goto`/projects/${project.id}/tasks`.expect(visible(button("New"))),
14
- click(button("New")).expect(visible(textbox("Title"))),
15
- fill(textbox("Title"), "Buy milk"),
16
- click(button("Create")).expect(Task.created({ title: "Buy milk", projectId: project.id })),
17
+ goto`/projects/${project.id}/dashboard`.expect(
18
+ visible(heading(project.name)),
19
+ visible(button("Project actions")),
20
+ ),
21
+ click(button("Project actions")).expect(
22
+ visible(projectActions),
23
+ visible(inside(projectActions, link("Settings"))),
24
+ ),
25
+ click(inside(projectActions, link("Settings"))).expect(
26
+ not(visible(projectActions)),
27
+ url.path.is`/projects/${project.id}/settings`,
28
+ visible(heading("General settings")),
29
+ visible(button("Edit project name")),
30
+ ),
31
+ click(button("Edit project name")).expect(
32
+ visible(textbox("Project name")),
33
+ visible(button("Save")),
34
+ disabled(button("Save")),
35
+ ),
36
+ fill(textbox("Project name"), nextName).expect(
37
+ value(textbox("Project name"), nextName),
38
+ enabled(button("Save")),
39
+ ),
40
+ click(button("Save")).expect(
41
+ visible(status("Saved")),
42
+ visible(heading(nextName)),
43
+ updated(selectedProject, {
44
+ name: transform(({ after, before }) =>
45
+ and(equals(after, nextName), not(equals(after, before))),
46
+ ),
47
+ }),
48
+ ),
17
49
  ],
18
50
  };
19
51
  });
20
52
  ```
21
53
 
22
- `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.
54
+ Workflows describe the widest starting-state constraints valid for the whole journey, not fixed
55
+ fixtures. Schema-derived handles keep generated names, ids, and relations connected through later
56
+ actions and effects. Undeclared observed state changes are frame violations.
23
57
 
24
58
  ## Setup with Claude Code
25
59
 
26
- If you use Claude Code, this is the shortest path. One command installs the plugin and opens a guided session that handles auth, project creation, scaffolding, and adapter wiring, and adds hooks that keep tests in sync as the agent changes your code.
60
+ One command installs the Claude Code plugin and opens guided setup:
27
61
 
28
62
  ```sh
29
63
  npx ripplo setup
30
64
  ```
31
65
 
32
- Skip the rest of this section unless you want to know what setup does, or you're not on Claude Code.
66
+ The session signs you in, creates or selects a project, scaffolds `.ripplo/`, mounts state-source
67
+ adapters, starts the daemon, and authors the first critical journey.
33
68
 
34
69
  ## Setup by hand
35
70
 
36
- Three steps: authenticate, scaffold, mount the engine adapter in your app server.
37
-
38
71
  ```sh
39
- npx ripplo auth login # device-code flow, opens a browser
40
- npx ripplo init # scaffolds .ripplo/ and writes RIPPLO_* env vars
72
+ npx ripplo auth login
73
+ npx ripplo init
41
74
  ```
42
75
 
43
- `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).
76
+ `npx ripplo init` creates:
77
+
78
+ - `.ripplo/state.ts` with one root Zod state schema
79
+ - `.ripplo/workflows/` for typed user journeys
80
+ - `.ripplo/project.json` for project and environment pointers
81
+ - `.ripplo/ripplo.lock`, the committed compiled model
44
82
 
45
- 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.
83
+ Each top-level state key is one source. A source reads one validated state fragment and implements
84
+ only the setup operations derived from its schema:
46
85
 
47
86
  ```ts
48
- // Express
49
- import { createEngineHandler } from "@ripplo/testing/express";
50
- import { engine } from "./test/engine.js";
51
-
52
- app.use(
53
- "/ripplo",
54
- createEngineHandler({ enabled: process.env.ENABLE_RIPPLO_TESTING === "true", engine }),
55
- );
87
+ import { createStateSourceEngine } from "@ripplo/testing/engine";
88
+ import { state } from "../../../.ripplo/state.js";
89
+
90
+ export const coreEngine = createStateSourceEngine(state.core, {
91
+ read: ({ runId }) => readCoreState(runId),
92
+ setup: {
93
+ records: {
94
+ tasks: ({ input, runId }) => createTask({ input, runId }),
95
+ },
96
+ fields: ({ input, runId }) => setCoreFields({ input, runId }),
97
+ },
98
+ teardown: ({ runId }) => clearRunState(runId),
99
+ });
56
100
  ```
57
101
 
58
- `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.
102
+ Mount each source engine behind `RIPPLO_ENGINE_URL` with the adapter for Express, Fastify, Koa,
103
+ NestJS, Next.js, Hono, Elysia, or Vite. Authentication uses a separate schema-derived engine because
104
+ signing in creates and verifies a browser session. The Claude setup skill wires the exact adapter
105
+ for your application.
59
106
 
60
- 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:
107
+ Preload `@ripplo/instrument` in server-side development processes to capture application spans:
61
108
 
62
109
  ```sh
63
- node --import @ripplo/instrument server.js # or NODE_OPTIONS="--import @ripplo/instrument" next dev
110
+ node --import @ripplo/instrument server.js
64
111
  ```
65
112
 
66
- It exports spans to the local daemon during runs and stays dormant otherwise, so it's safe to leave in your dev script permanently.
67
-
68
- ## Running tests
113
+ ## Compile and run
69
114
 
70
- Start the daemon in one terminal and leave it running next to your dev server:
115
+ Start the app dev server and daemon separately:
71
116
 
72
117
  ```sh
73
118
  npx ripplo daemon
74
119
  ```
75
120
 
76
- It keeps a warm browser pool and executes runs in parallel as they come in. Then:
121
+ Then run:
77
122
 
78
123
  ```sh
79
- npx ripplo run # tests in scope + tests affected by your changes
80
- npx ripplo run --all # everything
81
- npx ripplo run my-test # one test by id
124
+ npx ripplo compile
125
+ npx ripplo run
126
+ npx ripplo run <workflow-slug>
127
+ npx ripplo run <workflow-slug>/<test-slug>
128
+ npx ripplo run --all
82
129
  ```
83
130
 
84
- `run` connects to the daemon and streams results; if a daemon is absent it starts one for you.
131
+ `npx ripplo run` connects to the daemon and runs Testing Scope. It does not start or stop the
132
+ daemon. Use `npx ripplo doctor` when the app, adapter, or daemon is unavailable.
85
133
 
86
- ## The lockfile
134
+ Start a workflow from the widest state the full path permits:
87
135
 
88
- `.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.
136
+ - Use `required`, `optional`, `absent`, `closed`, and relations for meaningful state shape.
137
+ - Use `arbitrary(field)` for schema-valid workflow inputs and reuse the binding.
138
+ - Use `exact(value)` only when that concrete value drives behavior.
139
+ - Use named `when` branches when starting state changes the outcome but intent and path stay the
140
+ same.
141
+ - Declare every visible outcome and complete state effect, including cascades.
142
+ - Make every effect provably change state.
89
143
 
90
- ## Worktrees
144
+ The full authoring reference ships at `node_modules/@ripplo/testing/DSL.md`.
91
145
 
92
- 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.
146
+ ## Lockfile
93
147
 
94
- 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.
148
+ Commit `.ripplo/ripplo.lock`. The server reads it on every push. Regenerate it with
149
+ `npx ripplo compile`. Never edit it by hand.
95
150
 
96
- ## Other commands
151
+ ## Worktrees
97
152
 
98
- `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).
153
+ Each working directory gets its own daemon, Testing Scope, debug artifacts, and lockfile checkout.
154
+ Copy or share the ignored environment file and use distinct app and engine ports.
155
+ `npx ripplo doctor` reports mismatches.
99
156
 
100
157
  ## License
101
158
 
102
- © Ripplo LLC. All rights reserved. Use is subject to Ripplo's [Terms of Service](https://ripplo.ai/terms).
159
+ © Ripplo LLC. All rights reserved. Use is subject to Ripplo's
160
+ [Terms of Service](https://ripplo.ai/terms).