waygraph 0.10.3 → 0.10.5

package/README.md

@@ -3,7 +3,7 @@
 A typed graph of reusable Blocks for driving a browser through E2E flows, in place of a
 flat pile of ad hoc helper functions.
 
-**Current:** `0.10.2` — CLI less-is-more (`auto` / `demo` / `run` + flags). Page hubs still as in 0.9.0.
+**Current:** `0.10.5` — CLI less-is-more (`auto` / `demo` / `run` + `.flow.ts` paths). Page hubs still as in 0.9.0.
 
 This repo is the `waygraph` npm package itself. The full live **Sauce Demo** example
 (Page inventory hub, Effect Add/Remove, MemNav Open details, `waygraph auto`) ships
@@ -22,7 +22,7 @@ Browser docs (quick start, **demo / run**, **auto explore**, engine handout, con
 - **Source:** [`docs/`](./docs/) — static HTML, no build step
 - **Local preview:** `npm run docs:preview` → http://127.0.0.1:4173/
 - **Deploy:** push to `main` touching `docs/**` runs [`.github/workflows/pages.yml`](./.github/workflows/pages.yml) (`workflow_dispatch` also works)
-- **Demo / run contract:** [`docs/demo.html`](./docs/demo.html) — `demo` / `run` / flags (`--auto-next`, `--auto-play-video`)
+- **Demo / run contract:** [`docs/demo.html`](./docs/demo.html) — `list` / `.flow.ts` path / export / flags
 - **Auto explore:** [`docs/auto.html`](./docs/auto.html) — prefer `auto --cli` / `npm run auto:cli` (same menus as headed)
 - **In-repo example:** [`examples/saucedemo`](./examples/saucedemo) — full Sauce Demo project
 - **Convention showcase (Pages):** [`docs/saucedemo/`](./docs/saucedemo/) —
@@ -262,11 +262,15 @@ Deliberately **not yet implemented** (tracked on the project board):
 Mermaid) is `waygraph graph [project]` (`--mermaid`). Unattended JSON execution is
 `chain` + `WAYGRAPH_JSON=1`.
 
-**Friendly demo / run / auto (0.10.2 — less is more):**
+**Friendly demo / run / auto (0.10.5 — flows are files):**
 
 | Want | Command |
 |------|---------|
-| Manual watch | `waygraph demo --blocks shopFlow` |
+| List flows | `waygraph list` → `src/flows/shop.flow.ts  shopFlow` |
+| Run by file | `waygraph run src/flows/shop.flow.ts --data '{…}'` |
+| Same via `auto` | `waygraph auto src/flows/shop.flow.ts --data '{…}'` |
+| Run by export | `waygraph run --blocks shopFlow` |
+| Manual watch | `waygraph demo src/flows/shop.flow.ts` |
 | Auto-advance | `waygraph demo --blocks shopFlow --auto-next` |
 | QA watch + record | `waygraph demo --blocks shopFlow --auto-play-video` |
 | Ad-hoc Blocks | `waygraph run --blocks "login then nav-cart" --data '{…}'` |
@@ -274,6 +278,8 @@ Mermaid) is `waygraph graph [project]` (`--mermaid`). Unattended JSON execution
 | Explore | `waygraph auto` / `waygraph auto --cli` |
 | Path-find | `waygraph auto --blocks LoginPage OrderComplete` |
 
+`--blocks` / positional accepts a Flow export, a `.flow.ts` path, or `"a then b"`.
+`auto <file.flow.ts>` **runs** that flow (same as `run`); bare `auto` still explores.
 `--auto-next` (alias `--autoplay`) = panel Auto-advance. `--auto-play-video` is **demo only**.
 `chain` remains a compat alias for `run --blocks` / `auto --blocks`.
 

package/dist/cli.d.ts

@@ -3,7 +3,7 @@
  * waygraph CLI -- tooling around this same package's engine.
  *
  * Primary verbs (less is more):
- *   auto   Explore picker; `--blocks From To` = graph path-find + run
+ *   auto   Explore picker; `.flow.ts` / `--blocks From To` = run that path
  *   demo   Watch (step overlay); `--blocks` `--data` `--auto-next` `--auto-play-video`
  *   run    Execute; `--blocks` `--data` `--non-headless` `--video`
  *

package/dist/cli.js

@@ -3,7 +3,7 @@
  * waygraph CLI -- tooling around this same package's engine.
  *
  * Primary verbs (less is more):
- *   auto   Explore picker; `--blocks From To` = graph path-find + run
+ *   auto   Explore picker; `.flow.ts` / `--blocks From To` = run that path
  *   demo   Watch (step overlay); `--blocks` `--data` `--auto-next` `--auto-play-video`
  *   run    Execute; `--blocks` `--data` `--non-headless` `--video`
  *
@@ -12,7 +12,7 @@
  *
  * "project" defaults to cwd. Flags beat WAYGRAPH_* env.
  */
-import { existsSync, readdirSync, readFileSync, writeFileSync, rmSync, cpSync, mkdirSync, mkdtempSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, writeFileSync, rmSync, cpSync, mkdirSync, mkdtempSync, statSync } from "node:fs";
 import { resolve, relative, join, basename, dirname } from "node:path";
 import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
@@ -2020,9 +2020,14 @@ async function main() {
     const flow = await findFlow(projectDir, bareRef);
     if (flow && typeof flow.blocks === "function") {
       const blockInfos = flow.blocks();
+      // Same --data / WAYGRAPH_DATA seeding as the multi-segment path.
+      // Without this, \`waygraph run shop.flow.ts --data '{...}'\` (and bare
+      // export names) hit preflight with an empty MemPage.
+      const seedMem = () => seedMemForFlow(mem, blockInfos, undefined, bareRef);
       resolved = blockInfos.map((bi, idx) => ({
         block: bi.block,
         exportName: bi.name,
+        seedMem: idx === 0 ? seedMem : undefined,
         expectedFailureReason:
           flow.expectedFailureReason && idx === blockInfos.length - 1
             ? flow.expectedFailureReason
@@ -2291,6 +2296,7 @@ main().catch((err) => {
  * `WAYGRAPH_SLOWMO=<ms>` pass straight through from this process's own env.
  */
 async function runChain(projectDir, spec) {
+    const expanded = await expandSpecFlowFiles(projectDir, spec);
     if (process.env.WAYGRAPH_VIDEO && !process.env.WAYGRAPH_BASE_URL) {
         const resolved = resolveBaseUrl(projectDir);
         if (resolved)
@@ -2301,7 +2307,7 @@ async function runChain(projectDir, spec) {
     writeFileSync(scriptPath, CHAIN_RUNNER_SCRIPT);
     try {
         const code = await new Promise((res, rej) => {
-            const child = spawn(process.execPath, ["--import", tsxEsm, scriptPath, projectDir, spec], {
+            const child = spawn(process.execPath, ["--import", tsxEsm, scriptPath, projectDir, expanded], {
                 stdio: "inherit",
                 env: process.env,
             });
@@ -2969,22 +2975,100 @@ function resolveProjectDir(flags, fallbackIndex = 0) {
 function resolveSpec(flags) {
     return flags.blocks ?? flags.positionals[0];
 }
+/** `shop.flow.ts` / `src/flows/cart-bulk.flow.ts` / absolute path — not a Checkpoint or export id. */
+function looksLikeFlowFileRef(ref) {
+    if (!ref || ref.includes("then") || ref.includes("("))
+        return false;
+    return /\.flow\.ts$/i.test(ref) || (/\.ts$/i.test(ref) && (ref.includes("/") || ref.includes("\\")));
+}
+function flowExportNameFromBasename(filePath) {
+    const base = basename(filePath).replace(/\.flow\.ts$/i, "").replace(/\.ts$/i, "");
+    const camel = base.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+    return /Flow$/i.test(camel) ? camel : `${camel}Flow`;
+}
+/**
+ * Map a `.flow.ts` path (relative to project or absolute) to its Flow export
+ * name so the chain runner can `findFlow(exportName)`. Prefers
+ * `shop.flow.ts` → `shopFlow`. Reads source only (no import) so the outer CLI
+ * does not dual-load `@playwright/test` against the project tree.
+ */
+async function resolveFlowFileToExport(projectDir, fileArg) {
+    let abs = resolve(projectDir, fileArg);
+    if (!existsSync(abs)) {
+        const want = basename(fileArg);
+        const hits = walkDir(projectDir, new RegExp(`${want.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}$`));
+        if (hits.length === 1)
+            abs = hits[0];
+        else if (hits.length === 0) {
+            throw new Error(`waygraph: no flow file "${fileArg}" under ${projectDir}`);
+        }
+        else {
+            throw new Error(`waygraph: "${fileArg}" matches ${hits.length} files - use a path from \`waygraph list\``);
+        }
+    }
+    const expected = flowExportNameFromBasename(abs);
+    const src = readFileSync(abs, "utf-8");
+    if (new RegExp(`\\bexport\\s+(?:const|let|var|async\\s+function|function)\\s+${expected}\\b`).test(src)) {
+        return expected;
+    }
+    if (new RegExp(`\\bexport\\s*\\{[^}]*\\b${expected}\\b`).test(src)) {
+        return expected;
+    }
+    const flowNames = [
+        ...src.matchAll(/\bexport\s+(?:const|let|var|async\s+function|function)\s+(\w*Flow)\b/g),
+    ].map((m) => m[1]);
+    const unique = [...new Set(flowNames)];
+    if (unique.length === 1)
+        return unique[0];
+    if (unique.includes(expected))
+        return expected;
+    if (unique.length === 0) {
+        throw new Error(`waygraph: ${relative(projectDir, abs)} has no exported *Flow (expected ${expected})`);
+    }
+    throw new Error(`waygraph: ${relative(projectDir, abs)} exports ${unique.join(", ")} - pass the export name or rename to ${expected}`);
+}
+/**
+ * Expand `.flow.ts` path segments in a run/demo spec to export names.
+ * `src/flows/shop.flow.ts` → `shopFlow`; leaves `loginFlow then nav-cart` alone.
+ */
+async function expandSpecFlowFiles(projectDir, spec) {
+    const parts = spec.split(/\bthen\b/).map((s) => s.trim()).filter((s) => s.length > 0);
+    const out = [];
+    for (const part of parts) {
+        const m = /^([^\s(]+)(\s*\([\s\S]*\))?$/.exec(part);
+        if (!m) {
+            out.push(part);
+            continue;
+        }
+        const ref = m[1];
+        const payload = m[2] ?? "";
+        if (looksLikeFlowFileRef(ref)) {
+            const exportName = await resolveFlowFileToExport(projectDir, ref);
+            out.push(exportName + payload);
+        }
+        else {
+            out.push(part);
+        }
+    }
+    return out.join(" then ");
+}
 const args = process.argv.slice(2);
 const command = args[0];
 function usage() {
     console.log(`waygraph -- graph project tool + engine CLI
 
 Primary (less is more):
-  waygraph auto  [project]                 Interactive explore (picker)
+  waygraph auto  [project|.flow.ts]        Interactive explore (picker)
                  --cli                     Terminal menu instead of browser panel
                  --blocks <From> <To>      Graph path-find From->To, then run
                  --data '{...}'            Mem seed (same as demo/run)
-  waygraph demo  [--blocks <flow|spec>]    Watch with step overlay (QA path)
+                 (pass a .flow.ts to run that flow - same as run)
+  waygraph demo  [--blocks <flow|file|spec>]  Watch with step overlay (QA path)
                  --data '{...}'            Mem seed JSON (or inline flow({...}))
                  --auto-next               Auto-advance steps (alias: --autoplay)
                  --auto-play-video         QA: --auto-next + --video (+ step)
                  --title / --base-url
-  waygraph run   [--blocks <flow|spec>]    Execute (no overlay unless --step)
+  waygraph run   [--blocks <flow|file|spec>]  Execute (no overlay unless --step)
                  --data '{...}'
                  --non-headless            Show browser
                  --video [dir]             Record .webm
@@ -2995,18 +3079,21 @@ Also:
                  try auto --headed         Browser panel instead of CLI
 
 Examples:
+  waygraph list                                          # file → export map
+  waygraph run src/flows/shop.flow.ts --data '{...}'
+  waygraph run --blocks shopFlow --non-headless --video
+  waygraph demo --blocks src/flows/cart-bulk.flow.ts --auto-next
   waygraph try auto:cli
+  waygraph auto src/flows/shop.flow.ts --data '{...}'   # run by file (same as run)
   waygraph auto --cli --data '{"saucedemo.credentials":{...}}'
   waygraph auto --blocks LoginPage OrderComplete
-  waygraph demo --blocks shopFlow --auto-next
-  waygraph demo --blocks cartBulkFlow --data '{"saucedemo.credentials":{...}}' --auto-play-video
   waygraph run  --blocks "loginFlow then add-all-to-cart" --data '{...}' --video
-  waygraph run  --blocks shopFlow --non-headless --video
 
 Aliases (compat): \`chain <spec>\` -> run --blocks; \`chain auto A B\` -> auto --blocks A B;
   --autoplay -> --auto-next. Prefer the primary verbs above.
 
 Project path optional (defaults to cwd). Flags beat WAYGRAPH_* env.
+\`run\`/\`demo\`/\`auto\`: Flow export, .flow.ts path, or "a then b" chain (auto also explores).
 `);
     process.exit(0);
 }
@@ -3053,7 +3140,10 @@ async function main() {
             applyRunFlags(flags);
             const spec = resolveSpec(flags);
             if (!spec) {
-                console.error('waygraph run: missing flow/spec — e.g. waygraph run --blocks shopFlow\n' +
+                console.error("waygraph run: missing flow/spec — e.g.\n" +
+                    "  waygraph run src/flows/shop.flow.ts\n" +
+                    "  waygraph run --blocks shopFlow\n" +
+                    "  waygraph list   # file → export map\n" +
                     "  Flags: --blocks --data --non-headless --video [dir] --step/--no-step");
                 process.exit(1);
             }
@@ -3121,7 +3211,9 @@ async function main() {
             applyRunFlags(flags, { allowAutoPlayVideo: true });
             const spec = resolveSpec(flags);
             if (!spec) {
-                console.error('waygraph demo: missing flow/spec — e.g. waygraph demo --blocks shopFlow\n' +
+                console.error("waygraph demo: missing flow/spec — e.g.\n" +
+                    "  waygraph demo src/flows/shop.flow.ts\n" +
+                    "  waygraph demo --blocks shopFlow\n" +
                     "  Flags: --blocks --data --auto-next --auto-play-video --title --base-url --video");
                 process.exit(1);
             }
@@ -3151,11 +3243,35 @@ async function main() {
             const mermaid = flags.mermaid === true;
             const mapOnly = command === "graph" || flags.map === true;
             const cliPicker = flags.cli === true;
-            const proj = resolve(flags.positionals[0] ?? process.cwd());
+            const firstPos = flags.positionals[0];
+            // auto src/flows/shop.flow.ts → run that flow (same as `run`). Do not
+            // treat a .flow.ts path as a project directory (existsSync is true for files).
+            if (command === "auto" && firstPos && looksLikeFlowFileRef(firstPos) && !flags.blocksFromTo) {
+                const proj = resolve(process.cwd());
+                if (!existsSync(proj) || !statSync(proj).isDirectory()) {
+                    console.error(`waygraph: no such directory: ${proj}`);
+                    process.exit(1);
+                }
+                if (!process.env.WAYGRAPH_BASE_URL) {
+                    const resolved = resolveBaseUrl(proj);
+                    if (resolved)
+                        process.env.WAYGRAPH_BASE_URL = resolved;
+                }
+                await runChain(proj, firstPos);
+                break;
+            }
+            const proj = resolve(firstPos ?? process.cwd());
             if (!existsSync(proj)) {
                 console.error(`waygraph: no such directory: ${proj}`);
                 process.exit(1);
             }
+            if (!statSync(proj).isDirectory()) {
+                console.error(`waygraph ${command}: "${firstPos}" is a file, not a project directory\n` +
+                    "  run a flow:  waygraph auto src/flows/shop.flow.ts\n" +
+                    "  or explore:  waygraph auto\n" +
+                    "  or path-find: waygraph auto --blocks LoginPage OrderComplete");
+                process.exit(1);
+            }
             // auto --blocks From To  (graph path-find + run)
             if (command === "auto" && (flags.blocksFromTo || flags.blocks)) {
                 if (flags.blocksFromTo) {
@@ -3165,7 +3281,8 @@ async function main() {
                 }
                 console.error("waygraph auto --blocks expects <fromCheckpoint> <toCheckpoint>\n" +
                     '  e.g. waygraph auto --blocks LoginPage OrderComplete\n' +
-                    '  for a hand-named chain use: waygraph run --blocks "a then b"');
+                    '  for a hand-named chain use: waygraph run --blocks "a then b"\n' +
+                    "  or: waygraph auto src/flows/shop.flow.ts");
                 process.exit(1);
             }
             if (mapOnly || mermaid) {

package/package.json

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

package/templates/quickstart/package.json

@@ -23,7 +23,7 @@
     "baseUrl": "https://www.saucedemo.com"
   },
   "dependencies": {
-    "waygraph": "^0.10.2"
+    "waygraph": "^0.10.5"
   },
   "devDependencies": {
     "@playwright/test": "^1.55.0",