@ripplo/testing 0.0.11 → 0.1.1

package/README.md

@@ -11,12 +11,22 @@ npm install @ripplo/testing
 ## Quick Start
 
 1. Run `npx ripplo` to authenticate and scaffold a `.ripplo/` directory in your project
-2. Define preconditions in `.ripplo/preconditions/`, then add `import "./preconditions/<file>.js";` to `.ripplo/index.ts`. Exports set up test data (users, projects, etc.)
-3. Write tests in `.ripplo/tests/`, then add `import "./tests/<id>.js";` to `.ripplo/index.ts`. The CLI only loads what that file imports.
-4. Run `npx ripplo lint` to validate, `npx ripplo run` to execute
-5. Commit the generated `.ripplo/ripplo.lock` alongside your DSL changes (see Lockfile below)
+2. Define preconditions in `.ripplo/preconditions/`, then add `import "./preconditions/<file>.js";` to `.ripplo/index.ts`. Exports set up test data (users, workspaces, etc.)
+3. (Optional) Define observers in `.ripplo/observers/` for backend state assertions (`assert.backend(...)`), then add `import "./observers/<file>.js";` to `.ripplo/index.ts`
+4. Write tests in `.ripplo/tests/`, then add `import "./tests/<id>.js";` to `.ripplo/index.ts`. The CLI only loads what that file imports.
+5. Run `npx ripplo lint` to validate, `npx ripplo run` to execute
+6. Commit the generated `.ripplo/ripplo.lock` alongside your DSL changes (see Lockfile below)
 
-Every test gets a clean slate via preconditions — no shared state, no ordering dependencies, fully parallelizable.
+Every test gets a clean slate via preconditions — no shared state, no ordering dependencies, fully parallelizable. Observers let tests verify backend side effects (async jobs, DB rows, webhooks) without polling or sleeps in test code.
+
+## Architecture
+
+`@ripplo/testing` has two halves:
+
+- **DSL** — the typed builder (`ripplo.test(...)`, `ripplo.precondition(...)`, `ripplo.observer(...)`, locators, actions, `assert.*`) that your `.ripplo/*.ts` files use. Pure TypeScript, compiles to a JSON lockfile.
+- **Engine** — the adapter (`@ripplo/testing/express`, `/fastify`, `/nextjs`) mounted into your app server. It hosts three routes under a single prefix (default `/ripplo`): `PUT /execute-preconditions`, `PUT /execute-observer`, `PUT /teardown-preconditions`. Every request is HMAC-signed; the adapter is gated behind `ENABLE_RIPPLO_TESTING` so it can't ship to production by accident.
+
+Your precondition and observer implementations live in the server package where they have access to your DB/ORM. The DSL package never runs that code — it just orchestrates execution over signed HTTP.
 
 ## Lockfile
 
@@ -34,16 +44,29 @@ The Ripplo server reads the lockfile on every GitHub push webhook. If the lockfi
 
 ```typescript
 import ripplo from "../ripplo.js";
-import { dataProject } from "../preconditions/index.js";
+import { dataWorkspace } from "../preconditions/index.js";
+import { invitePendingForEmail } from "../observers/index.js";
+import { click, fill } from "@ripplo/testing/actions";
+import { assert } from "@ripplo/testing/assert";
+import { role } from "@ripplo/testing/locators";
 
 ripplo
-  .test("delete-project")
-  .name("Delete a project")
-  .requires({ project: dataProject })
-  .expectedOutcome("Project deleted and user redirected to connect page")
-  .startsAt(({ project }) => `/projects/${project.projectId}/settings`)
-  .steps(({ project }) => [
-    // steps here
+  .test("invite-a-teammate")
+  .name("Invite a teammate")
+  .requires({ workspace: dataWorkspace })
+  .expectedOutcome("Invite appears in the pending list and an invite record is created")
+  .startsAt(({ workspace }) => `/workspaces/${workspace.id}/members`)
+  .steps(({ workspace }) => [
+    click(role("button", "Invite member")).as("open invite dialog"),
+    fill(role("textbox", "Email"), "jamie@example.com").as("enter email"),
+    click(role("button", "Send invite")).as("send"),
+    assert.visible(role("status", "Invite sent")).as("confirm toast"),
+    assert
+      .backend(invitePendingForEmail, {
+        workspaceId: workspace.id,
+        email: "jamie@example.com",
+      })
+      .as("confirm invite recorded"),
   ]);
 ```
 
@@ -198,7 +221,7 @@ ripplo
 ### Precondition Implementation
 
 ```typescript
-ripplo.implement(authLoggedIn, {
+ripplo.implementPrecondition(authLoggedIn, {
   setup: async (ctx, deps) => {
     const email = ctx.uniqueEmail();
     // Create user, set cookies via ctx.setCookie()
@@ -218,6 +241,92 @@ ripplo.implement(authLoggedIn, {
 - `ctx.uniqueEmail()` — generate unique email
 - `ctx.setCookie(name, value, options?)` — inject auth cookies
 
+## Observer System
+
+Observers are backend state assertions evaluated mid-test. Use them when the UI is optimistic, the effect is async (jobs, webhooks, pubsub), or a load-bearing write needs independent verification. An observer is a named yes/no question about backend state — if a test needs to _read_ state for later reuse, that's a precondition, not an observer.
+
+### Declaration (`.ripplo/observers/*.ts`)
+
+```typescript
+import type { ObserverHandle } from "@ripplo/testing";
+import ripplo from "../ripplo.js";
+
+export const orgNameIs: ObserverHandle<{ orgId: string; expectedName: string }> = ripplo
+  .observer("org:name-is")
+  .description("Org with the given id has the given name in the DB")
+  .input<{ orgId: string; expectedName: string }>()
+  .budget("fast") // optional; "fast" is default
+  .contract();
+```
+
+**Chain:** `.observer(name)` → `.description(text)` → `.input<T>()` → `.budget(tier)` (optional) → `.contract()`
+
+**Budget tiers** (framework-defined, not numeric):
+
+- `"fast"` — ~5s with 100→1000ms backoff. Default. Synchronous DB reads.
+- `"slow"` — ~30s with 250→2000ms backoff. Queue drains, replication settling.
+- `"async"` — ~120s with 500→5000ms backoff. Webhooks, queue workers, LLM calls.
+
+### Implementation (server side)
+
+```typescript
+ripplo.implementObserver(orgNameIs, async (ctx, { orgId, expectedName }) => {
+  const org = await prisma.organization.findUnique({
+    select: { name: true },
+    where: { id: orgId },
+  });
+  if (org == null) return ctx.retry(`organization "${orgId}" not found yet`);
+  if (org.name !== expectedName)
+    return ctx.retry(`name is "${org.name}", expected "${expectedName}"`);
+  return ctx.pass();
+});
+```
+
+**ObserverContext provides:**
+
+- `ctx.pass()` → assertion satisfied; stop polling.
+- `ctx.retry(reason)` → **default**. Use for anything that might succeed on a later poll: row not found yet, status not transitioned, queue not drained, side effect still in flight. Runtime polls until the budget expires; the last `reason` surfaces in the failure detail.
+- `ctx.fail(reason)` → **narrow**. Only when further polling cannot help — an invariant has been violated (wrong shape, contradictory value, forbidden state). Stops immediately. If you're tempted to use `fail` for "not found" or "not yet X", it should be `retry`.
+- Any thrown exception is treated as `fail` with the error message.
+
+### Usage in tests
+
+```typescript
+import { orgNameIs } from "../observers/index.js";
+
+ripplo
+  .test("update-org-name")
+  .requires({ project: dataProject })
+  .steps(({ project }) => [
+    fill(role("textbox", "Organization name"), "New Name").as("fill new name"),
+    click(role("button", "Save")).as("click save"),
+    assert
+      .backend(orgNameIs, { orgId: project.orgId, expectedName: "New Name" })
+      .as("assert org name in db"),
+  ]);
+```
+
+### Observer lint rules
+
+- **`mutation-without-observer-coverage`** — flags save/create/delete/update/etc. clicks, uploads, and accepted dialogs that are not followed by an `assert.backend(...)` before the next mutation or end of test. The expected fix is always to **add an observer**.
+- **`observer-params-reference-variables`** — flags observer assertions whose params are all hardcoded strings while the test declares precondition variables; use precondition data instead of literals.
+
+### Opting out (`uiOnly`)
+
+For steps that genuinely don't touch server state (cancel dialogs, toggle a display-only control, pick a client-side sort option) pass `{ uiOnly: true }` to the step factory:
+
+```typescript
+click(role("button", "Cancel"), { uiOnly: true }).as("close dialog");
+```
+
+For entire presentation-only flows, pass the flag to `ripplo.test`:
+
+```typescript
+ripplo.test("filter-sort-user-flows", { uiOnly: true }).name("Filter & sort");
+```
+
+Treat `uiOnly` as a narrow escape hatch — default to writing an observer.
+
 ## Determinism Rules
 
 1. **Use `role()` locators exclusively.** Only use `testId()` when no ARIA role is available.
@@ -226,7 +335,7 @@ ripplo.implement(authLoggedIn, {
 4. **Every step must have `.as("description")`.** No unlabeled steps.
 5. **No duplicate labels** within a test.
 6. **End with assertions** that verify the `expectedOutcome`.
-7. **After a test passes, run flake detection** to verify determinism across parallel runs.
+7. **Cover backend mutations with observers.** Any save/create/delete/update click (or upload, or accepted dialog) must be verified with `assert.backend(observerHandle, params)` unless it truly has no server effect — in which case mark the step `{ uiOnly: true }`.
 
 ## CLI Commands
 
@@ -239,7 +348,7 @@ ripplo flake-detect <id> --runs=10  # Run N times in parallel to detect flakines
 
 ## Server Setup
 
-Your application server must expose the precondition endpoints under a single path prefix (the value you pass to `createRipplo({ preconditionsUrl })`). Pick the adapter that matches your framework — each handles webhook signature verification, cookie forwarding, and request parsing for you. Every adapter takes a required `enabled: boolean` flag — bind it to an env var (e.g. `process.env.ENABLE_RIPPLO_TESTING === "true"`) so the endpoints never ship to production. When `enabled` is false the adapter mounts a no-op handler.
+Your application server must expose the engine endpoint under a single path prefix (the value you pass to `createRipplo({ engineUrl })`). Pick the adapter that matches your framework — each handles webhook signature verification, cookie forwarding, and request parsing for you. Every adapter takes a required `enabled: boolean` flag — bind it to an env var (e.g. `process.env.ENABLE_RIPPLO_TESTING === "true"`) so the endpoints never ship to production. When `enabled` is false the adapter mounts a no-op handler.
 
 ### Express
 
@@ -250,12 +359,12 @@ import ripplo from "<path to .ripplo/ripplo>"; // import the existing instance
 
 const app = express();
 app.use(
-  "/ripplo/preconditions",
+  "/ripplo",
   createExpressHandler({ enabled: process.env.ENABLE_RIPPLO_TESTING === "true", ripplo }),
 );
 ```
 
-Mounts both `PUT /execute-batch` and `PUT /teardown` under the prefix you choose.
+Mounts both `PUT /execute-preconditions` and `PUT /teardown-preconditions` under the prefix you choose.
 
 ### Fastify
 
@@ -267,7 +376,7 @@ import ripplo from "<path to .ripplo/ripplo>"; // import the existing instance
 const app = Fastify();
 await app.register(
   registerFastifyHandler({ enabled: process.env.ENABLE_RIPPLO_TESTING === "true", ripplo }),
-  { prefix: "/ripplo/preconditions" },
+  { prefix: "/ripplo" },
 );
 ```
 
@@ -276,7 +385,7 @@ await app.register(
 The Next.js adapter exports a single catch-all handler. Create one dynamic route file:
 
 ```ts
-// app/ripplo/preconditions/[action]/route.ts
+// app/ripplo/[action]/route.ts
 import { createNextHandler } from "@ripplo/testing/nextjs";
 import ripplo from "@/.ripplo/ripplo";
 
@@ -286,7 +395,7 @@ export const PUT = createNextHandler({
 });
 ```
 
-The handler dispatches on the last URL segment (`execute-batch` or `teardown`) and returns 404 for anything else. It depends only on the Web `Request` / `Response` types, so it runs on both the Node and Edge runtimes — no `next` import required.
+The handler dispatches on the last URL segment (`execute-preconditions` or `teardown-preconditions`) and returns 404 for anything else. It depends only on the Web `Request` / `Response` types, so it runs on both the Node and Edge runtimes — no `next` import required.
 
 ### Custom integration (raw engine)
 
@@ -304,7 +413,7 @@ import ripplo from "<path to .ripplo/ripplo>"; // import the existing instance
 const engine = createEngine(ripplo);
 const webhookSecret = ripplo.getConfig().webhookSecret;
 
-// PUT /ripplo/preconditions/execute-batch
+// PUT /ripplo/execute-preconditions
 async function executeBatch(req: Request): Promise<Response> {
   const body = await req.text();
   const verified = verifyWebhookSignature(
@@ -331,7 +440,7 @@ async function executeBatch(req: Request): Promise<Response> {
   return new Response(JSON.stringify(result), { headers });
 }
 
-// PUT /ripplo/preconditions/teardown
+// PUT /ripplo/teardown
 async function teardown(req: Request): Promise<Response> {
   // ... same verify pattern, then:
   // await engine.teardown(parsed.preconditions, parsed.data);
@@ -341,7 +450,7 @@ async function teardown(req: Request): Promise<Response> {
 **You're responsible for:**
 
 - **Webhook verification.** Always call `verifyWebhookSignature` before invoking the engine.
-- **Routing.** Dispatch the two endpoints (`execute-batch`, `teardown`) however your framework handles routes.
+- **Routing.** Dispatch the two endpoints (`execute-preconditions`, `teardown-preconditions`) however your framework handles routes.
 - **Cookie forwarding.** `result.cookies` contains the cookies preconditions set during setup — they must reach the test browser as `Set-Cookie` headers, or login/session preconditions will silently fail.
 - **Body parsing.** Use the raw text body for signature verification, then `JSON.parse` for the engine call.
 
@@ -355,7 +464,7 @@ import { createRipplo } from "@ripplo/testing";
 
 export default createRipplo({
   appUrl: process.env.APP_URL,
-  preconditionsUrl: `${process.env.APP_URL}/ripplo/preconditions`,
+  engineUrl: `${process.env.APP_URL}/ripplo`,
   projectId: "...",
   webhookSecret: process.env.RIPPLO_WEBHOOK_SECRET,
 });
@@ -365,7 +474,7 @@ export default createRipplo({
 
 The app server exposes two endpoints for test data management:
 
-### Execute (`PUT {preconditionApiPath}/execute`)
+### Execute (`PUT {engineBaseUrl}/execute`)
 
 ```json
 // Request
@@ -377,7 +486,7 @@ The app server exposes two endpoints for test data management:
 
 Returns data that flows into test variables. Set-Cookie headers are captured automatically.
 
-### Teardown (`PUT {preconditionApiPath}/teardown`)
+### Teardown (`PUT {engineBaseUrl}/teardown`)
 
 ```json
 // Request

package/dist/actions.d.ts

@@ -1,4 +1,4 @@
-import { U as UnlabeledStep } from './step-DLfkKI3V.js';
+import { U as UnlabeledStep } from './step-De52hTLd.js';
 import { CheckLocator, InputLocator, AnyLocator, SelectLocator } from './locators.js';
 import '@ripplo/spec';
 
@@ -9,7 +9,10 @@ declare function navigate(url: string): UnlabeledStep<{
         value: string;
     };
 }>;
-declare function click(locator: AnyLocator): UnlabeledStep<{
+interface StepOptions {
+    readonly uiOnly?: boolean;
+}
+declare function click(locator: AnyLocator, options?: StepOptions): UnlabeledStep<{
     locator: {
         by: "testId";
         value: string;
@@ -19,6 +22,7 @@ declare function click(locator: AnyLocator): UnlabeledStep<{
         name?: string | undefined;
     };
     type: "click";
+    uiOnly: boolean | undefined;
 }>;
 declare function fill(locator: InputLocator, value: string): UnlabeledStep<{
     locator: {
@@ -87,7 +91,7 @@ declare function press(key: string): UnlabeledStep<{
     key: string;
     type: "press";
 }>;
-declare function upload(locator: AnyLocator, path: string): UnlabeledStep<{
+declare function upload(locator: AnyLocator, path: string, options?: StepOptions): UnlabeledStep<{
     files: string[];
     locator: {
         by: "testId";
@@ -98,6 +102,7 @@ declare function upload(locator: AnyLocator, path: string): UnlabeledStep<{
         name?: string | undefined;
     };
     type: "upload";
+    uiOnly: boolean | undefined;
 }>;
 declare function dblclick(locator: AnyLocator): UnlabeledStep<{
     locator: {
@@ -191,11 +196,13 @@ declare function drag(source: AnyLocator, target: AnyLocator): UnlabeledStep<{
 interface HandleDialogOptions {
     readonly action: "accept" | "dismiss";
     readonly promptText: string | undefined;
+    readonly uiOnly?: boolean;
 }
-declare function handleDialog({ action, promptText }: HandleDialogOptions): UnlabeledStep<{
+declare function handleDialog({ action, promptText, uiOnly }: HandleDialogOptions): UnlabeledStep<{
     action: "accept" | "dismiss";
     promptText: string | undefined;
     type: "handleDialog";
+    uiOnly: boolean | undefined;
 }>;
 interface ClipboardOptions {
     readonly action: "read" | "write";

package/dist/actions.js

@@ -10,8 +10,12 @@ import "./chunk-DCJBLS2U.js";
 function navigate(url) {
   return createStep({ type: "goto", url: { type: "static", value: url } });
 }
-function click(locator) {
-  return createStep({ locator: toSpecLocator(locator), type: "click" });
+function click(locator, options) {
+  return createStep({
+    locator: toSpecLocator(locator),
+    type: "click",
+    uiOnly: options?.uiOnly
+  });
 }
 function fill(locator, value) {
   return createStep({
@@ -39,11 +43,12 @@ function hover(locator) {
 function press(key) {
   return createStep({ key, type: "press" });
 }
-function upload(locator, path) {
+function upload(locator, path, options) {
   return createStep({
     files: [path],
     locator: toSpecLocator(locator),
-    type: "upload"
+    type: "upload",
+    uiOnly: options?.uiOnly
   });
 }
 function dblclick(locator) {
@@ -75,8 +80,8 @@ function drag(source, target) {
     type: "drag"
   });
 }
-function handleDialog({ action, promptText }) {
-  return createStep({ action, promptText, type: "handleDialog" });
+function handleDialog({ action, promptText, uiOnly }) {
+  return createStep({ action, promptText, type: "handleDialog", uiOnly });
 }
 function clipboard({ action, value, variable }) {
   return createStep({

package/dist/assert.d.ts

@@ -1,5 +1,7 @@
-import { U as UnlabeledStep } from './step-DLfkKI3V.js';
+import { O as ObserverHandle, a as ObserverInput, b as ObserverBudgetTier } from './types-oYS_Yv4G.js';
+import { U as UnlabeledStep } from './step-De52hTLd.js';
 import { CheckLocator, AnyLocator } from './locators.js';
+import 'zod';
 import '@ripplo/spec';
 
 declare const assert: {
@@ -66,6 +68,15 @@ declare const assert: {
         operator: "equals";
         type: "assertAttribute";
     }>;
+    backend<THandle extends ObserverHandle>(observer: THandle, params: ObserverInput<THandle> & Record<string, string>): UnlabeledStep<{
+        budget: ObserverBudgetTier;
+        observer: string;
+        params: Record<string, {
+            readonly type: "static";
+            readonly value: string;
+        }>;
+        type: "assertObserver";
+    }>;
     checked(locator: CheckLocator): UnlabeledStep<{
         locator: {
             by: "testId";

package/dist/assert.js

@@ -4,6 +4,10 @@ import {
 import {
   createStep
 } from "./chunk-MGATMMCZ.js";
+import {
+  readObserverBudget,
+  readObserverName
+} from "./chunk-3IL457A7.js";
 import "./chunk-DCJBLS2U.js";
 
 // src/steps/assert.ts
@@ -31,6 +35,14 @@ var assert = {
       type: "assertAttribute"
     });
   },
+  backend(observer, params) {
+    return createStep({
+      budget: readObserverBudget(observer),
+      observer: readObserverName(observer),
+      params: paramsToStringRefs(params),
+      type: "assertObserver"
+    });
+  },
   checked(locator) {
     return createStep({ locator: toSpecLocator(locator), type: "assertChecked" });
   },
@@ -78,6 +90,13 @@ var assert = {
     return createStep({ locator: toSpecLocator(locator), type: "assertVisible" });
   }
 };
+function paramsToStringRefs(params) {
+  const out = {};
+  Object.entries(params).forEach(([key, value]) => {
+    out[key] = { type: "static", value };
+  });
+  return out;
+}
 export {
   assert
 };

package/dist/builder-c7tXey03.d.ts

@@ -0,0 +1,80 @@
+import { O as ObserverHandle, P as Precondition, j as PreconditionData, k as TestValue, S as SetupContext, T as TeardownContext, f as DslConfig, h as ObserverDefinition, l as PreconditionDefinition, m as TestDefinition, U as UnimplementedItems, g as ObserverContext, c as ObserverOutcome, a as ObserverInput } from './types-oYS_Yv4G.js';
+import { ObserverBudget } from '@ripplo/spec';
+import { S as Step } from './step-De52hTLd.js';
+
+interface ObserverNeedsInput {
+    readonly budget: (tier: ObserverBudget) => ObserverNeedsInput;
+    readonly description: (text: string) => ObserverNeedsInput;
+    readonly input: <TInput extends Record<string, string>>() => ObserverReady<TInput>;
+}
+interface ObserverReady<TInput extends Record<string, string>> {
+    readonly contract: () => ObserverHandle<TInput>;
+    readonly notImplemented: () => ObserverHandle<TInput>;
+}
+
+type PreconditionRecord = Record<string, Precondition>;
+type ResolveDeps<TDeps extends PreconditionRecord> = {
+    readonly [K in keyof TDeps]: PreconditionData<TDeps[K]>;
+};
+type ResolveData<T extends Record<string, TestValue>> = {
+    readonly [K in keyof T]: string;
+};
+interface PreconditionNeedsSetup {
+    readonly contract: <TData extends Record<string, string>>() => Precondition<TData>;
+    readonly description: (text: string) => PreconditionNeedsSetup;
+    readonly notImplemented: () => Precondition<Record<string, never>>;
+    readonly requires: <TDeps extends PreconditionRecord>(deps: TDeps) => PreconditionNeedsSetupWithDeps<TDeps>;
+    readonly setup: <TData extends Record<string, TestValue>>(fn: (ctx: SetupContext) => Promise<TData>) => PreconditionHasSetup<ResolveData<TData>>;
+}
+interface PreconditionNeedsSetupWithDeps<TDeps extends PreconditionRecord> {
+    readonly contract: <TData extends Record<string, string>>() => Precondition<TData, ResolveDeps<TDeps>>;
+    readonly description: (text: string) => PreconditionNeedsSetupWithDeps<TDeps>;
+    readonly notImplemented: () => Precondition<Record<string, never>>;
+    readonly requires: <TDeps2 extends PreconditionRecord>(deps: TDeps2) => PreconditionNeedsSetupWithDeps<TDeps2>;
+    readonly setup: <TData extends Record<string, TestValue>>(fn: (ctx: SetupContext, deps: ResolveDeps<TDeps>) => Promise<TData>) => PreconditionHasSetup<ResolveData<TData>>;
+}
+interface PreconditionHasSetup<TData extends Record<string, string>> {
+    readonly teardown: (fn: (ctx: TeardownContext<TData>) => Promise<void>) => Precondition<TData>;
+}
+interface TestNeedsName {
+    readonly name: (displayName: string) => TestNeedsRequires;
+}
+interface TestNeedsRequires {
+    readonly description: (text: string) => TestNeedsRequires;
+    readonly requires: <TReqs extends PreconditionRecord>(reqs: TReqs) => TestNeedsOutcome<ResolveDeps<TReqs>>;
+}
+interface TestNeedsOutcome<TVars extends Record<string, Record<string, string>>> {
+    readonly description: (text: string) => TestNeedsOutcome<TVars>;
+    readonly expectedOutcome: (text: string) => TestNeedsStartsAt<TVars>;
+}
+interface TestNeedsStartsAt<TVars extends Record<string, Record<string, string>>> {
+    readonly notImplemented: () => void;
+    readonly startsAt: (fn: (vars: TVars) => string) => TestNeedsSteps<TVars>;
+}
+interface TestNeedsSteps<TVars extends Record<string, Record<string, string>>> {
+    readonly steps: (fn: (vars: TVars) => ReadonlyArray<Step>) => void;
+}
+
+interface PreconditionImpl<TData extends Record<string, string>, TDeps extends Record<string, Record<string, string>>> {
+    readonly setup: (ctx: SetupContext, deps: TDeps) => Promise<Record<string, TestValue>>;
+    readonly teardown: (ctx: TeardownContext<TData>) => Promise<void>;
+}
+type ObserverImplFn<TInput extends Record<string, string>> = (ctx: ObserverContext, params: TInput) => Promise<ObserverOutcome>;
+interface RipploBuilder {
+    readonly getConfig: () => DslConfig;
+    readonly getObservers: () => ReadonlyArray<ObserverDefinition>;
+    readonly getPreconditions: () => ReadonlyArray<PreconditionDefinition>;
+    readonly getTests: () => ReadonlyArray<TestDefinition>;
+    readonly getUnimplemented: () => UnimplementedItems;
+    readonly implementObserver: <THandle extends ObserverHandle>(handle: THandle, impl: ObserverImplFn<ObserverInput<THandle> & Record<string, string>>) => void;
+    readonly implementPrecondition: <TData extends Record<string, string>, TDeps extends Record<string, Record<string, string>>>(handle: Precondition<TData, TDeps>, impl: PreconditionImpl<TData, TDeps>) => void;
+    readonly observer: (name: string) => ObserverNeedsInput;
+    readonly precondition: (name: string) => PreconditionNeedsSetup;
+    readonly test: (id: string, options?: TestOptions) => TestNeedsName;
+}
+interface TestOptions {
+    readonly uiOnly?: boolean;
+}
+declare function createRipplo(rawConfig: DslConfig): RipploBuilder;
+
+export { type ObserverImplFn as O, type PreconditionImpl as P, type RipploBuilder as R, type PreconditionRecord as a, type ResolveDeps as b, createRipplo as c };

package/dist/chunk-3IL457A7.js

@@ -0,0 +1,60 @@
+// src/types.ts
+import { z } from "zod";
+var DEFAULT_WATCH_PATHS = [
+  "src/**",
+  "app/**",
+  "apps/**",
+  "pages/**",
+  "routes/**",
+  "components/**"
+];
+var DEFAULT_IGNORE_PATHS = [
+  "**/*.gen.*",
+  "**/generated/**",
+  "**/*.d.ts",
+  "**/*.test.*",
+  "**/*.spec.*",
+  "**/node_modules/**",
+  "**/dist/**",
+  "**/build/**",
+  ".ripplo/**",
+  "**/*.md"
+];
+var dslConfigSchema = z.object({
+  appUrl: z.string(),
+  engineUrl: z.string(),
+  ignorePaths: z.array(z.string()).optional(),
+  projectId: z.string(),
+  watchPaths: z.array(z.string()).optional(),
+  webhookSecret: z.string()
+});
+function readTestValue(value) {
+  return value.value;
+}
+function createTestValue(value) {
+  return { value };
+}
+function readPreconditionName(p) {
+  return p.name;
+}
+function readObserverName(o) {
+  return o.name;
+}
+function readObserverBudget(o) {
+  return o.budget;
+}
+function makeObserverHandle(name, budget) {
+  return { budget, name };
+}
+
+export {
+  DEFAULT_WATCH_PATHS,
+  DEFAULT_IGNORE_PATHS,
+  dslConfigSchema,
+  readTestValue,
+  createTestValue,
+  readPreconditionName,
+  readObserverName,
+  readObserverBudget,
+  makeObserverHandle
+};