waygraph 0.15.52 → 0.15.53

package/templates/skills/waygraph-convention.skill.md

@@ -68,10 +68,14 @@ against a live site, use `--skill-pilot-blind`.
 
 ## Flows, stubs and config (the scaffold's shape)
 
-- **Build flows with `map()`** (`.start().gotoPage(Nav).method(B).assert(A).end({ ... })`; `.gotoExternal` for another origin),
-  not a raw `defineFlow([start, ...])` array. Flow settings go in `.end`'s options:
-  `.end({ title: "Shop", memStub: true, sessionReset: true })`. Never `withMemStub(withTitle(withSessionReset(...)))`.
-  (`defineFlow(blocks, options)` takes the same options.)
+- **Build flows with `map()`** (`engine.map({ memStub }).start().gotoPage(Nav).method(B, { pace }).assert(A).end()`;
+  `.gotoExternal` for another origin), never a raw `defineFlow([start, ...])`. Flow settings go in `map({ … })` before the chain
+  and `.end()` takes nothing. The flow's title is `ctx.title(...)` in a stub. **Nest flows with `.flow(sub, { reset: true })`**,
+  not `chainFlow` / `withSessionReset`. No `withMemStub(withTitle(...))` wrappers.
+- **`src/flows/` holds use cases and mirrors the front end's endpoints**: a folder per page (`flows/auth/login/`) with one
+  file per scenario named for its outcome (`success.flow.ts`, `wrong-password.flow.ts`, `empty-fields.flow.ts`), and
+  `(user-stories)/` (any `(group)`) for flows that cross pages. Export names are `<page><Outcome>Flow`. Not one file per
+  Block chain, not a flat folder of unrelated flows.
 - **Blocks carry no stubs; the flow does.** Demo highlights are ctx stubs chained on the Block where the flow uses it:
   `AddItemBlock.stubAfter((ctx) => { ctx.ring("cart", { selector: DemoSel.cartCount, label: "AC · item in cart" }); })`.
   Not a static `withHighlightFixtures({ "add-item": { stubAfter: {...} } })` map, and not an inline
@@ -79,19 +83,23 @@ against a live site, use `--skill-pilot-blind`.
 - **Reading a value into `mem` happens in `act`** (`mem.set(Key, value)`), like Mailpit's `extract-email-link`.
   `observe` is only for a Block that branches (it feeds `resolve`); an empty `act(){}` plus an `observe` that
   writes `mem` is a misuse.
+- **Demo pace is a map option or config, never a wrapper.** `.method(SetBearerTokenBlock, { pace: "blitz" })` speeds one step,
+  `map({ demoPace: "fast" })` a flow, `demo: { pace, typingMs, slowMo }` in the config the whole project. Not `withBlockPace(...)`.
 - **Per-environment values** (a different `baseUrl` for staging) come from `.env` files read in the config function:
   `defineConfig(({ env }) => ({ baseUrl: env.BASE_URL }))`; `--env staging` loads `.env.staging`. Never edit the config to switch.
+- **More than one config** (staging, another app) is another file, `config/waygraph.<name>.config.ts`, chosen with `--config <name>`.
+  The engine a config exports, and every engine in a flow, follows the selected config.
 - **A browser dialog (`confirm`, `beforeunload`) is answered with `withDialog(block, { accept, into })`**, not inside the
   Block's `act`; the click Block stays a plain click.
 - **Project settings live in `config/waygraph.config.ts`** (`defineConfig({ baseUrl, testDir, webServer,
-  extensions, playwright: {...} })`). Flows import it and build the Engine from it (`new Engine(config)`); a project needs no
+  extensions, playwright: {...} })`). The config file also exports `engine = new Engine(config)`; flows `import { engine } from "../../config/waygraph.config.js"`; a project needs no
   `playwright.config.ts` - `waygraph test` builds one from it. A leftover `playwright.config.*` is deprecated.
 - **Another origin the test needs is a Map external** under `src/map/(external)/<tool>/`. For REST API
   tests, `(external)/hoppscotch` (list `extensions: ["hoppscotch"]` in the config) drives hoppscotch.io's client
   with the extension, so requests skip CORS: `set-method`, `set-url`, `set-headers`, `set-json-body`,
   `send-request`, `assert-status`, `read-response-body`, `assert-response-body`.
 - **Updating an older project:** `npm install waygraph@latest`, then `waygraph upgrade` (dry run) to see new
-  and differing scaffold files; copy the paths you want with `--apply`.
+  and differing scaffold files; copy the paths you want with `--apply`. `waygraph upgrade --skills` refreshes these skills.
 
 ## Block kinds (file convention)
 

package/templates/scaffold/src/flows/hoppscotch-auth.flow.ts

@@ -1,35 +0,0 @@
-import { Engine } from "waygraph";
-import config from "../../config/waygraph.config.js";
-import { NavHoppscotchSettingsBlock } from "../map/(external)/hoppscotch/settings/_nav.block.js";
-import { PickExtensionInterceptorBlock } from "../map/(external)/hoppscotch/_methods/pick-extension-interceptor.method.block.js";
-import { NavHoppscotchRestBlock } from "../map/(external)/hoppscotch/_nav.block.js";
-import { SetQueryParamsBlock } from "../map/(external)/hoppscotch/_methods/set-query-params.method.block.js";
-import { SetUrlBlock } from "../map/(external)/hoppscotch/_methods/set-url.method.block.js";
-import { SetBearerTokenBlock } from "../map/(external)/hoppscotch/_methods/set-bearer-token.method.block.js";
-import { SendRequestBlock } from "../map/(external)/hoppscotch/_methods/send-request.method.block.js";
-import { AssertStatusBlock } from "../map/(external)/hoppscotch/_methods/assert-status.method.block.js";
-import { ReadResponseHeadersBlock } from "../map/(external)/hoppscotch/_methods/read-response-headers.method.block.js";
-import { AssertResponseHeaderBlock } from "../map/(external)/hoppscotch/_methods/assert-response-header.method.block.js";
-import { ReadResponseBodyBlock } from "../map/(external)/hoppscotch/_methods/read-response-body.method.block.js";
-import { AssertResponseBodyBlock } from "../map/(external)/hoppscotch/_methods/assert-response-body.method.block.js";
-import "../map/(external)/hoppscotch/_page.block.js";
-
-const engine = new Engine(config);
-
-/** GET with query params and a bearer token, check the status, that the API received them, and a response header. Needs `extensions: ["hoppscotch"]`. */
-export const hoppscotchAuthFlow = engine
-  .map()
-  .start()
-  .gotoExternal(NavHoppscotchSettingsBlock)
-  .method(PickExtensionInterceptorBlock)
-  .gotoExternal(NavHoppscotchRestBlock)
-  .method(SetUrlBlock)
-  .method(SetQueryParamsBlock)
-  .method(SetBearerTokenBlock)
-  .method(SendRequestBlock)
-  .assert(AssertStatusBlock)
-  .method(ReadResponseBodyBlock)
-  .assert(AssertResponseBodyBlock)
-  .method(ReadResponseHeadersBlock)
-  .assert(AssertResponseHeaderBlock)
-  .end({ title: "Scaffold: Hoppscotch GET with query params and bearer token" });

package/templates/scaffold/src/flows/hoppscotch-get.flow.ts

@@ -1,23 +0,0 @@
-import { Engine } from "waygraph";
-import config from "../../config/waygraph.config.js";
-import { NavHoppscotchSettingsBlock } from "../map/(external)/hoppscotch/settings/_nav.block.js";
-import { PickExtensionInterceptorBlock } from "../map/(external)/hoppscotch/_methods/pick-extension-interceptor.method.block.js";
-import { NavHoppscotchRestBlock } from "../map/(external)/hoppscotch/_nav.block.js";
-import { SetUrlBlock } from "../map/(external)/hoppscotch/_methods/set-url.method.block.js";
-import { SendRequestBlock } from "../map/(external)/hoppscotch/_methods/send-request.method.block.js";
-import { AssertStatusBlock } from "../map/(external)/hoppscotch/_methods/assert-status.method.block.js";
-import "../map/(external)/hoppscotch/_page.block.js";
-
-const engine = new Engine(config);
-
-/** GET a URL and check the status. Needs `extensions: ["hoppscotch"]` in waygraph.config.ts. */
-export const hoppscotchGetFlow = engine
-  .map()
-  .start()
-  .gotoExternal(NavHoppscotchSettingsBlock)
-  .method(PickExtensionInterceptorBlock)
-  .gotoExternal(NavHoppscotchRestBlock)
-  .method(SetUrlBlock)
-  .method(SendRequestBlock)
-  .assert(AssertStatusBlock)
-  .end({ title: "Scaffold: Hoppscotch GET" });

package/templates/scaffold/src/flows/hoppscotch-post.flow.ts

@@ -1,33 +0,0 @@
-import { Engine } from "waygraph";
-import config from "../../config/waygraph.config.js";
-import { NavHoppscotchSettingsBlock } from "../map/(external)/hoppscotch/settings/_nav.block.js";
-import { PickExtensionInterceptorBlock } from "../map/(external)/hoppscotch/_methods/pick-extension-interceptor.method.block.js";
-import { NavHoppscotchRestBlock } from "../map/(external)/hoppscotch/_nav.block.js";
-import { SetMethodBlock } from "../map/(external)/hoppscotch/_methods/set-method.method.block.js";
-import { SetUrlBlock } from "../map/(external)/hoppscotch/_methods/set-url.method.block.js";
-import { SetHeadersBlock } from "../map/(external)/hoppscotch/_methods/set-headers.method.block.js";
-import { SetJsonBodyBlock } from "../map/(external)/hoppscotch/_methods/set-json-body.method.block.js";
-import { SendRequestBlock } from "../map/(external)/hoppscotch/_methods/send-request.method.block.js";
-import { AssertStatusBlock } from "../map/(external)/hoppscotch/_methods/assert-status.method.block.js";
-import { ReadResponseBodyBlock } from "../map/(external)/hoppscotch/_methods/read-response-body.method.block.js";
-import { AssertResponseBodyBlock } from "../map/(external)/hoppscotch/_methods/assert-response-body.method.block.js";
-import "../map/(external)/hoppscotch/_page.block.js";
-
-const engine = new Engine(config);
-
-/** POST JSON with a header, check the status and the response body. Needs `extensions: ["hoppscotch"]`. */
-export const hoppscotchPostFlow = engine
-  .map()
-  .start()
-  .gotoExternal(NavHoppscotchSettingsBlock)
-  .method(PickExtensionInterceptorBlock)
-  .gotoExternal(NavHoppscotchRestBlock)
-  .method(SetMethodBlock)
-  .method(SetUrlBlock)
-  .method(SetHeadersBlock)
-  .method(SetJsonBodyBlock)
-  .method(SendRequestBlock)
-  .assert(AssertStatusBlock)
-  .method(ReadResponseBodyBlock)
-  .assert(AssertResponseBodyBlock)
-  .end({ title: "Scaffold: Hoppscotch POST with header and JSON body" });

package/templates/scaffold/src/flows/mail-verify.flow.ts

@@ -1,46 +0,0 @@
-import { Engine } from "waygraph";
-import config from "../../config/waygraph.config.js";
-import { NavMailpitInboxBlock } from "../map/(external)/mailpit/_nav.block.js";
-import { AssertEmailReceivedBlock } from "../map/(external)/mailpit/_methods/assert-email-received.method.block.js";
-import { OpenMessageBlock } from "../map/(external)/mailpit/_methods/open-message.method.block.js";
-import { AssertEmailContentBlock } from "../map/(external)/mailpit/_methods/assert-email-content.method.block.js";
-import { ExtractEmailLinkBlock } from "../map/(external)/mailpit/_methods/extract-email-link.method.block.js";
-import { NavVerificationLinkBlock } from "../map/(app_base)/home/nav-verification-link.block.js";
-import "../map/(external)/mailpit/_page.block.js";
-import { MailpitSel } from "../map/(external)/mailpit/_sel.js";
-
-const engine = new Engine(config);
-
-/** Needs a Mailpit at WAYGRAPH_MAIL_URL (default http://127.0.0.1:8025); tests/mail-verify.spec.ts starts one. */
-export const mailVerifyFlow = engine
-  .map()
-  .start()
-  .gotoExternal(NavMailpitInboxBlock)
-  .assert(
-    AssertEmailReceivedBlock.stubAfter((ctx) => {
-      ctx.ring("note", {
-        selector: MailpitSel.messageRow,
-        label: "AC · email arrived",
-        detail: "Confirmed before opening anything.",
-        tag: "AC",
-      });
-    }),
-  )
-  .method(OpenMessageBlock)
-  .assert(
-    AssertEmailContentBlock.stubAfter((ctx) => {
-      ctx.ring("note", { selector: MailpitSel.previewIframe, label: "AC · email body matches expected copy", tag: "AC" });
-    }),
-  )
-  .method(
-    ExtractEmailLinkBlock.stubAfter((ctx) => {
-      ctx.ring("note", {
-        selector: MailpitSel.previewIframe,
-        label: "AC · link found",
-        detail: "Read from the message preview iframe.",
-        tag: "AC",
-      });
-    }),
-  )
-  .gotoPage(NavVerificationLinkBlock)
-  .end({ title: "Scaffold: Cross-origin mail verification (QA-rich)" });