@ripplo/testing 0.0.1 → 0.0.2

package/README.md

@@ -11,8 +11,8 @@ 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.ts` — these set up test data (users, projects, etc.)
-3. Write tests in `.ripplo/tests/` — each file defines one user flow to test
+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
 
 Every test gets a clean slate via preconditions — no shared state, no ordering dependencies, fully parallelizable.
@@ -23,7 +23,7 @@ Every test gets a clean slate via preconditions — no shared state, no ordering
 
 ```typescript
 import ripplo from "../ripplo.js";
-import { dataProject } from "../preconditions.js";
+import { dataProject } from "../preconditions/index.js";
 
 ripplo
   .test("delete-project")
@@ -221,25 +221,27 @@ ripplo.implement(authLoggedIn, {
 
 ```bash
 ripplo                              # Launch interactive dashboard
-ripplo lint [slugs..]               # Compile + lint tests (all or specific slugs)
-ripplo run [slugs..]                # Run tests in parallel
-ripplo list                         # List tests with status
-ripplo flake-detect <slug> --runs=10  # Run N times in parallel to detect flakiness
+ripplo lint [ids..]                 # Compile + lint tests (all or specific ids)
+ripplo run [ids..]                  # Run tests in parallel
+ripplo flake-detect <id> --runs=10  # Run N times in parallel to detect flakiness
 ```
 
 ## 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. Wrap the mount point behind an env guard (e.g. `ENABLE_RIPPLO_TESTING=true`) so it never ships to production.
+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.
 
 ### Express
 
 ```ts
 import express from "express";
 import { createExpressHandler } from "@ripplo/testing/express";
-import ripplo from "../.ripplo/ripplo.js";
+import ripplo from "<path to .ripplo/ripplo>"; // import the existing instance — never call createRipplo() outside .ripplo/ripplo.ts
 
 const app = express();
-app.use("/api/test/preconditions", createExpressHandler({ ripplo }));
+app.use(
+  "/ripplo/preconditions",
+  createExpressHandler({ enabled: process.env.ENABLE_RIPPLO_TESTING === "true", ripplo }),
+);
 ```
 
 Mounts both `PUT /execute-batch` and `PUT /teardown` under the prefix you choose.
@@ -249,12 +251,13 @@ Mounts both `PUT /execute-batch` and `PUT /teardown` under the prefix you choose
 ```ts
 import Fastify from "fastify";
 import { registerFastifyHandler } from "@ripplo/testing/fastify";
-import ripplo from "../.ripplo/ripplo.js";
+import ripplo from "<path to .ripplo/ripplo>"; // import the existing instance — never call createRipplo() outside .ripplo/ripplo.ts
 
 const app = Fastify();
-await app.register(registerFastifyHandler({ ripplo }), {
-  prefix: "/api/test/preconditions",
-});
+await app.register(
+  registerFastifyHandler({ enabled: process.env.ENABLE_RIPPLO_TESTING === "true", ripplo }),
+  { prefix: "/ripplo/preconditions" },
+);
 ```
 
 ### Next.js (App Router)
@@ -262,11 +265,14 @@ await app.register(registerFastifyHandler({ ripplo }), {
 The Next.js adapter exports a single catch-all handler. Create one dynamic route file:
 
 ```ts
-// app/api/test/preconditions/[action]/route.ts
+// app/ripplo/preconditions/[action]/route.ts
 import { createNextHandler } from "@ripplo/testing/nextjs";
 import ripplo from "@/.ripplo/ripplo";
 
-export const PUT = createNextHandler({ ripplo });
+export const PUT = createNextHandler({
+  enabled: process.env.ENABLE_RIPPLO_TESTING === "true",
+  ripplo,
+});
 ```
 
 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.
@@ -282,12 +288,12 @@ import {
   serializeCookie,
   verifyWebhookSignature,
 } from "@ripplo/testing";
-import ripplo from "../.ripplo/ripplo.js";
+import ripplo from "<path to .ripplo/ripplo>"; // import the existing instance — never call createRipplo() outside .ripplo/ripplo.ts
 
 const engine = createEngine(ripplo);
 const webhookSecret = ripplo.getConfig().webhookSecret;
 
-// PUT /api/test/preconditions/execute-batch
+// PUT /ripplo/preconditions/execute-batch
 async function executeBatch(req: Request): Promise<Response> {
   const body = await req.text();
   const verified = verifyWebhookSignature(
@@ -314,7 +320,7 @@ async function executeBatch(req: Request): Promise<Response> {
   return new Response(JSON.stringify(result), { headers });
 }
 
-// PUT /api/test/preconditions/teardown
+// PUT /ripplo/preconditions/teardown
 async function teardown(req: Request): Promise<Response> {
   // ... same verify pattern, then:
   // await engine.teardown(parsed.preconditions, parsed.data);
@@ -338,7 +344,7 @@ import { createRipplo } from "@ripplo/testing";
 
 export default createRipplo({
   appUrl: process.env.APP_URL,
-  preconditionsUrl: `${process.env.APP_URL}/api/test/preconditions`,
+  preconditionsUrl: `${process.env.APP_URL}/ripplo/preconditions`,
   projectId: "...",
   webhookSecret: process.env.RIPPLO_WEBHOOK_SECRET,
 });

package/dist/express.d.ts

@@ -5,8 +5,9 @@ import './step-DLfkKI3V.js';
 import '@ripplo/spec';
 
 interface CreateExpressHandlerParams {
+    readonly enabled: boolean;
     readonly ripplo: RipploBuilder;
 }
-declare function createExpressHandler({ ripplo }: CreateExpressHandlerParams): Router;
+declare function createExpressHandler({ enabled, ripplo }: CreateExpressHandlerParams): Router;
 
 export { type CreateExpressHandlerParams, createExpressHandler };

package/dist/express.js

@@ -8,10 +8,13 @@ import {
 
 // src/adapters/express.ts
 import { Router, json } from "express";
-function createExpressHandler({ ripplo }) {
+function createExpressHandler({ enabled, ripplo }) {
+  const router = Router();
+  if (!enabled) {
+    return router;
+  }
   const engine = createEngine(ripplo);
   const webhookSecret = ripplo.getConfig().webhookSecret;
-  const router = Router();
   router.use(json());
   router.use((req, res, next) => {
     if (webhookSecret.length === 0) {

package/dist/fastify.d.ts

@@ -5,8 +5,9 @@ import './step-DLfkKI3V.js';
 import '@ripplo/spec';
 
 interface RegisterFastifyHandlerParams {
+    readonly enabled: boolean;
     readonly ripplo: RipploBuilder;
 }
-declare function registerFastifyHandler({ ripplo, }: RegisterFastifyHandlerParams): (fastify: FastifyInstance) => Promise<void>;
+declare function registerFastifyHandler({ enabled, ripplo, }: RegisterFastifyHandlerParams): (fastify: FastifyInstance) => Promise<void>;
 
 export { type RegisterFastifyHandlerParams, registerFastifyHandler };

package/dist/fastify.js

@@ -9,8 +9,13 @@ import {
 
 // src/adapters/fastify.ts
 function registerFastifyHandler({
+  enabled,
   ripplo
 }) {
+  if (!enabled) {
+    return async () => {
+    };
+  }
   const engine = createEngine(ripplo);
   const webhookSecret = ripplo.getConfig().webhookSecret;
   return async (fastify) => {

package/dist/nextjs.d.ts

@@ -4,9 +4,10 @@ import './step-DLfkKI3V.js';
 import '@ripplo/spec';
 
 interface CreateNextHandlerParams {
+    readonly enabled: boolean;
     readonly ripplo: RipploBuilder;
 }
 type NextHandler = (req: Request) => Promise<Response>;
-declare function createNextHandler({ ripplo }: CreateNextHandlerParams): NextHandler;
+declare function createNextHandler({ enabled, ripplo }: CreateNextHandlerParams): NextHandler;
 
 export { type CreateNextHandlerParams, createNextHandler };

package/dist/nextjs.js

@@ -8,7 +8,10 @@ import {
 } from "./chunk-KWUKVAGI.js";
 
 // src/adapters/nextjs.ts
-function createNextHandler({ ripplo }) {
+function createNextHandler({ enabled, ripplo }) {
+  if (!enabled) {
+    return async () => jsonResponse({ error: "Not found" }, 404);
+  }
   const engine = createEngine(ripplo);
   const webhookSecret = ripplo.getConfig().webhookSecret;
   return async function handler(req) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ripplo/testing",
   "description": "TypeScript DSL for defining and running Ripplo e2e workflow tests",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "type": "module",
   "files": [
     "dist"