waygraph 0.15.18 → 0.15.19

package/README.md

@@ -298,10 +298,26 @@ code, an autonomous agent authoring Blocks) - it warns, never fails the process.
 
 **`waygraph typecheck [project]`** runs `tsc --noEmit` then the same **bad-practice** scan
 (wildcard `Checkpoint<string>`, assert blocks missing type args, multi-`.fill()` Methods,
-fill+click in one Method). Practices warn only unless `tsc` fails; use `--no-practices` to
-skip the scan. Opt out per file: `// waygraph-ignore-practices` or
-`// waygraph-ignore: multi-input, combined-action`. Print full agent guidance:
-`waygraph --skill-convention`.
+fill+click in one Method, empty `verify` on a transition Block or `defineAssertBlock`).
+Practices warn only unless `tsc` fails; use `--no-practices` to skip the scan. Opt out per
+file: `// waygraph-ignore-practices` or `// waygraph-ignore: multi-input, combined-action,
+empty-verify`. Print full agent guidance: `waygraph --skill-convention`.
+
+**Empty verify is the one that matters most for codegen'd Blocks.** A framework can enforce
+that a check *exists* and stays structurally honest (typed, wired, right file) - it cannot
+author the semantic content of that check, since only someone who knows what "success" means
+for this specific app can write it. That's a correct place to draw the line, but it shifts
+all the risk onto whether anything catches a Block left with a placeholder `verify: []` by
+the time it ships - which would otherwise pass every static check, the orphan scan, and
+`tsc`, and run green in CI forever, because an empty array isn't a wrong check, it's the
+*absence* of one. `waygraph check`/`typecheck` now flag exactly that: a `defineMethodBlock`/
+`defineEffectBlock` whose `In`/`Out` Checkpoints actually differ (a real transition, not a
+self-loop like `fill-username`) with no `verify` key or a literal `verify: []`, and the same
+for `defineAssertBlock` (whose entire job is checking). Silence it deliberately, the same as
+any other practice warning, with `// waygraph-ignore: empty-verify` - e.g. when a downstream
+`defineAssertBlock` right after it in the `.flow.ts` is what actually confirms the transition
+(see `templates/scaffold`'s own `open-message.method.block.ts`, confirmed by
+`AssertEmailContentBlock` right after it, not by its own `verify`).
 
 ### Demo narration
 
@@ -998,25 +1014,22 @@ really a Nav/Page/Assert/Method from this package's own factories.
 |------|---------|
 | Watch Sauce Demo step-through (temp dir only) | `npx waygraph try demo` |
 | Interactive explore (Add/Remove/Open details from live page) | `cd examples/saucedemo && npm i && npx waygraph auto` |
-| Scaffold a new **offline** project (green `npm test` on local fixture `:4177`) | `npx create-waygraph my-app` **or** `npx waygraph init my-app` |
+| Scaffold a new **offline** project (green `npm test` on local fixture `:4177`) | `npx waygraph init my-app` |
 | Install coding-agent defs for diving an app into Blocks | `npx waygraph agent-dive --loop claude` (also `opencode` / `cursor` / `vscode`) |
 | Print a packaged agent skill to stdout | `npx waygraph --skill` (list) / `--skill-pilot` / `--skill-pilot-blind` / `--skill-convention` |
 | Add waygraph to an existing repo | `npm install waygraph @playwright/test` |
 
-**Scaffold is not hidden inside waygraph alone** - the offline starter also ships as
-[`create-waygraph`](https://github.com/deviate-dv8/create-waygraph) on npm (same template
-as `waygraph init` since 0.7.5). Use whichever entry you already have:
-`npx create-waygraph my-app` when reading the GitHub Pages docs, or `npx waygraph init my-app`
-when the CLI is already installed. After either:
-
 ```bash
+npx waygraph init my-app
 cd my-app && npm install && npx playwright install chromium && npm test
 ```
 
 `try demo` is different: live saucedemo.com, step-through **Sign In -> Shop & Checkout ->
 blocked Viewer login**, then headless tests. Permanent full example:
-[`examples/saucedemo`](./examples/saucedemo). Offline empty scaffold: `init` /
-`create-waygraph`.
+[`examples/saucedemo`](./examples/saucedemo). Offline empty scaffold: `init`.
+
+**`create-waygraph` (npm) is deprecated** - it was the identical `init` template shipped as
+a second package for no real benefit. Use `npx waygraph init my-app` instead.
 
 ```bash
 # From this checkout, after npm run build:
@@ -1090,8 +1103,8 @@ suite - it forwards to the local `node_modules/.bin/playwright` (falling back to
 `npx playwright` if the project hasn't installed it locally yet), so `waygraph test` behaves
 exactly like `playwright test`, and anything after it (`--grep`, a spec path, `--headed`, …)
 passes straight through. `waygraph test ui` (or `waygraph test --ui`) launches Playwright's
-interactive UI Mode the same way. Scaffolded projects (`waygraph init`/`create-waygraph`)
-wire this up as `npm test` / `npm run test:ui`, and ship `trace: "retain-on-failure"` plus
+interactive UI Mode the same way. Scaffolded projects (`waygraph init`) wire this up as
+`npm test` / `npm run test:ui`, and ship `trace: "retain-on-failure"` plus
 the `html` reporter in `playwright.config.ts`, so a failing `waygraph test` already has a
 trace waiting - `waygraph test report` opens the HTML report, and
 `waygraph test show-trace <trace.zip>` opens one trace directly (both forward to Playwright's
@@ -1321,7 +1334,7 @@ src/
   index.ts                           public barrel
 examples/saucedemo/         live Sauce Demo (Page + methods/ + Sel)
 templates/quickstart/       try demo / init template (mirrors sauce)
-templates/scaffold/         offline init/create-waygraph scaffold template
+templates/scaffold/         offline waygraph init scaffold template
 templates/agents/           waygraph agent-dive coding-agent definitions
 docs/                       GitHub Pages static HTML + docs/proposals/ RFCs
 openspec/                   spec-driven planning: specs/ (current), changes/ (in-flight),

package/dist/practices-check.d.ts

@@ -1,4 +1,4 @@
-export type PracticeKind = "wildcard-checkpoint" | "assert-no-type-arg" | "multi-input" | "combined-action";
+export type PracticeKind = "wildcard-checkpoint" | "assert-no-type-arg" | "multi-input" | "combined-action" | "empty-verify";
 export interface PracticeWarning {
     kind: PracticeKind;
     file: string;

package/dist/practices-check.js

@@ -9,6 +9,19 @@ import { relative } from "node:path";
 const WILDCARD_CHECKPOINT = /\bdefine(?:Method|Effect|Page|Nav|MemNav|NavClick|Action)Block\s*<[^>]*\bCheckpoint\s*<\s*string\s*>/;
 /** defineAssertBlock({ … }) with no explicit Out type — defaults to wildcard. */
 const ASSERT_NO_TYPE_ARG = /\bdefineAssertBlock\s*\(\s*\{/;
+/** defineAssertBlock, any form - used to scope the empty-verify check below. */
+const IS_ASSERT_BLOCK = /\bdefineAssertBlock\s*[<(]/;
+/**
+ * define(Method|Effect)Block<In, Out> with two BARE identifier type args
+ * (never a nested generic like Checkpoint<string> - that's WILDCARD_CHECKPOINT's
+ * own warning) - lets a real transition (In !== Out) be told apart from a
+ * self-loop (In === Out, e.g. fill-username) using only source text.
+ */
+const METHOD_EFFECT_GENERIC = /\bdefine(?:Method|Effect)Block\s*<\s*([A-Za-z_$][\w$]*)\s*,\s*([A-Za-z_$][\w$]*)\s*>/;
+/** `verify: []` - a literal empty array, the codegen-stub shape this check exists for. */
+const EMPTY_VERIFY_ARRAY = /\bverify\s*:\s*\[\s*\]/;
+/** Any `verify:` key at all, empty or not. */
+const HAS_VERIFY_KEY = /\bverify\s*:/;
 const SCAN_GLOB = /\.(block|flow)\.ts$/;
 const METHOD_OR_EFFECT_FILE = /\.(method|effect)\.block\.ts$/;
 const METHOD_OR_EFFECT_DEFINE = /\bdefine(?:Method|Effect)Block\b/;
@@ -80,6 +93,27 @@ export function collectPracticeWarnings(projectDir, walkDir, opts) {
                     detail: "Method/Effect act() mixes .fill() and .click() — fill and submit must be separate Blocks (see examples/saucedemo login split)",
                 });
             }
+            const genericMatch = METHOD_EFFECT_GENERIC.exec(src);
+            const isTransition = !!genericMatch && genericMatch[1] !== genericMatch[2];
+            if (isTransition &&
+                !isIgnored("empty-verify", ignore) &&
+                (!HAS_VERIFY_KEY.test(src) || EMPTY_VERIFY_ARRAY.test(src))) {
+                warnings.push({
+                    kind: "empty-verify",
+                    file: rel,
+                    detail: `transition Block (${genericMatch[1]} → ${genericMatch[2]}) has no verify checks — resolve() moving ` +
+                        "to a new Checkpoint is never confirmed by anything; add a Trait (or defineAssertBlock right after it), " +
+                        "or opt out explicitly with // waygraph-ignore: empty-verify if that's intentional",
+                });
+            }
+        }
+        if (!isIgnored("empty-verify", ignore) && IS_ASSERT_BLOCK.test(src) && EMPTY_VERIFY_ARRAY.test(src)) {
+            warnings.push({
+                kind: "empty-verify",
+                file: rel,
+                detail: "defineAssertBlock's verify array is empty — an assert Block whose only job is checking will pass " +
+                    "trivially forever; fill in real Traits or remove the stub",
+            });
         }
     }
     return warnings;
@@ -94,6 +128,8 @@ export function practiceKindLabel(kind) {
             return "multiple inputs in one Block";
         case "combined-action":
             return "fill and click in one Block";
+        case "empty-verify":
+            return "empty verify — transition unconfirmed";
         default: {
             const _exhaustive = kind;
             return _exhaustive;

package/examples/saucedemo/.waygraph-auto/9f0287e6.json

@@ -0,0 +1,8 @@
+{
+  "sessionId": "9f0287e6",
+  "socketPath": "/tmp/waygraph-auto/9f0287e6.sock",
+  "pid": 2653914,
+  "projectDir": "/home/dan/Desktop/Projects/waygraph/examples/saucedemo",
+  "startedAt": "2026-09-23T01:33:06.508Z",
+  "headless": false
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waygraph",
-  "version": "0.15.18",
+  "version": "0.15.19",
   "type": "module",
   "description": "A typed graph of reusable Blocks for driving a browser through E2E flows.",
   "license": "MIT",

package/templates/scaffold/src/map/(external)/mailpit/_methods/open-message.method.block.ts

@@ -1,3 +1,4 @@
+// waygraph-ignore: empty-verify (confirmed by AssertEmailContentBlock right after it in mail-verify.flow.ts)
 import { defineMethodBlock, checkpoint } from "waygraph";
 import type { MailpitInbox, MailpitMessageOpen } from "../../../../states/demo.states.js";
 import { ExpectedRecipient } from "../../../../states/demo.mem-keys.js";

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

@@ -24,9 +24,9 @@ against a live site, use `--skill-pilot-blind`.
    an explicit type argument when it sits between two specifically-typed Blocks in a Flow.
    Not just static content or an action's result - it also names a *feature state* worth a
    Checkpoint of its own (a submit button greyed out until required fields are filled, a
-   field error under one input, a stale "Save" re-enabling). No built-in `Trait.disabled` -
-   write the state condition as a custom Trait (`isDisabled()`, a class, `aria-disabled`),
-   same as any other Trait: real DOM check, no inline selector.
+   field error under one input, a stale "Save" re-enabling). `Trait.disabled(selector)` /
+   `Trait.enabled(selector)` cover that directly; write a custom Trait only for a state
+   condition neither one expresses.
 5. **`requires` = externally supplied.** A key an earlier Block in the same chain produces
    is never listed under `requires` - preflight checks the whole chain up front.
 6. **Keep Checkpoints typed — never `Checkpoint<string>`.** Block helpers take concrete
@@ -37,6 +37,16 @@ against a live site, use `--skill-pilot-blind`.
 7. **One input/action per Method Block.** No block that `.fill()`s two fields or `.fill()` + `.click()` in one
    `act()` — split like saucedemo login (`fill-username`, `fill-password`, `submit-login`). Opt out per file:
    `// waygraph-ignore: multi-input` or `// waygraph-ignore-practices`.
+8. **A transition never ships with an empty `verify`.** A framework can enforce that a check
+   *exists*; it can't author the semantic content of one - only whoever knows what "success"
+   means for this app can write it. That's the right line to draw, but it means an unfilled
+   `verify: []` placeholder (codegen's honest way of not guessing) is indistinguishable from
+   a Block that was never given real verification at all, and it passes `check`/`typecheck`/
+   the orphan scan/`tsc` silently unless something is actually looking for it. Something is:
+   `defineMethodBlock`/`defineEffectBlock` where `In`/`Out` genuinely differ (a transition,
+   not a self-loop) needs a non-empty `verify`, same for `defineAssertBlock`. Opt out only
+   when a *different* Block right after it in the `.flow.ts` is what actually confirms the
+   transition (e.g. an `AssertXBlock`) - `// waygraph-ignore: empty-verify`.
 
 ## Block kinds (file convention)