waygraph 0.10.4 → 0.10.6

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.4` — CLI less-is-more (`auto` / `demo` / `run` + `.flow.ts` paths). Page hubs still as in 0.9.0.
+**Current:** `0.10.6` — `try auto` headed by default; `init` / create-waygraph scaffolds on 0.10 + `.flow.ts` scripts.
 
 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
@@ -262,12 +262,13 @@ 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.4 — flows are files):**
+**Friendly demo / run / auto (0.10.5 — flows are files):**
 
 | Want | Command |
 |------|---------|
 | 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` |
@@ -278,6 +279,7 @@ Mermaid) is `waygraph graph [project]` (`--mermaid`). Unattended JSON execution
 | 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";
@@ -2557,26 +2557,27 @@ async function runTryDemo() {
 const TRY_AUTO_DATA = '{"saucedemo.credentials":{"username":"standard_user","password":"secret_sauce"}}';
 /**
  * `waygraph try auto` / `try auto:cli` - temp Sauce Demo explore.
- * Default is CLI menu (same as `npm run auto:cli`). Pass `--headed` for the browser panel.
+ * Default is the **headed** browser panel. Pass `auto:cli` or `--cli` for the
+ * terminal menu (same rows).
  *
  * Runs as a child in the temp project so Block imports share that install's
  * `@playwright/test`. In-process explore from the outer CLI against a packed
  * `file:*.tgz` copy double-loads Playwright and silently yields 0 graph edges
  * ("LoginPage / No moves").
  */
-async function runTryAuto(opts = { cli: true }) {
+async function runTryAuto(opts = { cli: false }) {
     const destDir = await prepareTryQuickstart("waygraph-try-auto");
     if (!destDir)
         return;
     process.env.WAYGRAPH_BASE_URL ??= "https://www.saucedemo.com";
-    const cli = opts.cli !== false;
+    const cli = opts.cli === true;
     console.log(cli
         ? "waygraph try auto: CLI explore on Sauce Demo (temp dir).\n" +
             "  Creds pre-seeded (saucedemo.credentials).\n" +
             "  Pick [1] submit-login, then inventory Add/Remove / Open details.\n" +
-            "  Type q to quit. Headed panel: waygraph try auto --headed\n"
+            "  Type q to quit. Headed panel: waygraph try auto\n"
         : "waygraph try auto: headed explore on Sauce Demo (temp dir).\n" +
-            "  Creds pre-seeded. Prefer CLI: waygraph try auto:cli\n" +
+            "  Creds pre-seeded. CLI menu: waygraph try auto:cli\n" +
             "  Pick submit-login, then inventory menus. Quit from the panel.\n");
     const bin = join(destDir, "node_modules", ".bin", "waygraph");
     const args = ["auto"];
@@ -2589,8 +2590,8 @@ async function runTryAuto(opts = { cli: true }) {
     console.log("\nwaygraph try auto: explorer closed.\n\n" +
         `Temp project:\n  ${destDir}\n\n` +
         "Run again:\n" +
-        `  cd ${destDir} && npm run auto:cli\n` +
-        `  cd ${destDir} && npm run auto\n\n` +
+        `  cd ${destDir} && npm run auto\n` +
+        `  cd ${destDir} && npm run auto:cli\n\n` +
         "In-package: examples/saucedemo\n" +
         "Docs: https://deviate-dv8.github.io/waygraph/auto.html\n");
 }
@@ -2721,8 +2722,11 @@ function initCommand(projectName) {
     console.log("  npm install");
     console.log("  npx playwright install chromium");
     console.log("  npm test");
+    console.log("  waygraph list        # .flow.ts → export map");
     console.log("  waygraph check       # nav hygiene + orphan Blocks");
-    console.log("  waygraph auto        # interactive explore (headful picker)");
+    console.log("  waygraph auto        # interactive explore (headed panel)");
+    console.log("  waygraph auto --cli  # same menus in the terminal");
+    console.log("  waygraph demo src/flows/example.flow.ts");
     console.log("  waygraph graph       # static state graph JSON");
 }
 async function checkCommand(projectDir) {
@@ -3058,10 +3062,11 @@ 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)
+                 (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)
@@ -3075,14 +3080,18 @@ Primary (less is more):
 Also:
   waygraph list | nav | validate | check | graph | init <name>
   waygraph try [demo|auto|auto:cli]        One-shot saucedemo in a temp dir
-                 try auto --headed         Browser panel instead of CLI
+                 try auto                  Headed browser panel (default)
+                 try auto:cli / --cli      Terminal menu instead
+                 try auto --headed         Same as try auto (compat)
 
 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
   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 run  --blocks "loginFlow then add-all-to-cart" --data '{...}' --video
@@ -3091,7 +3100,7 @@ Aliases (compat): \`chain <spec>\` -> run --blocks; \`chain auto A B\` -> auto -
   --autoplay -> --auto-next. Prefer the primary verbs above.
 
 Project path optional (defaults to cwd). Flags beat WAYGRAPH_* env.
-\`--blocks\` / positional: Flow export (shopFlow), .flow.ts path, or "a then b" chain.
+\`run\`/\`demo\`/\`auto\`: Flow export, .flow.ts path, or "a then b" chain (auto also explores).
 `);
     process.exit(0);
 }
@@ -3241,11 +3250,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) {
@@ -3255,7 +3288,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) {
@@ -3283,19 +3317,18 @@ async function main() {
             const flags = parseRunFlags(args.slice(1));
             applyRunFlags(flags);
             const modeRaw = (flags.positionals[0] ?? "demo").toLowerCase();
-            // auto:cli / auto-cli = CLI explore; auto --headed = browser panel; auto = CLI default
+            // auto:cli / --cli = CLI; bare try auto = headed panel
             const mode = modeRaw === "auto:cli" || modeRaw === "auto-cli"
                 ? "auto:cli"
                 : modeRaw === "auto"
                     ? "auto"
                     : modeRaw;
             if (mode === "auto" || mode === "auto:cli") {
-                // CLI is the default for try auto (same menus as headed). --headed = panel.
                 const cli = mode === "auto:cli" || flags.cli === true
                     ? true
                     : flags.headed === true || flags.nonHeadless === true
                         ? false
-                        : true;
+                        : false; // try auto default = headed
                 await runTryAuto({ cli });
             }
             else if (mode === "demo" || mode === "") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waygraph",
-  "version": "0.10.4",
+  "version": "0.10.6",
   "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.4"
+    "waygraph": "^0.10.6"
   },
   "devDependencies": {
     "@playwright/test": "^1.55.0",

package/templates/scaffold/package.json

@@ -6,17 +6,19 @@
   "scripts": {
     "typecheck": "tsc --noEmit",
     "test": "playwright test",
-    "flows": "waygraph list",
+    "list": "waygraph list",
     "check": "waygraph check",
     "auto": "waygraph auto",
-    "graph": "waygraph graph",
-    "demo": "waygraph demo exampleFlow"
+    "auto:cli": "waygraph auto --cli",
+    "demo": "waygraph demo src/flows/example.flow.ts",
+    "run": "waygraph run src/flows/example.flow.ts",
+    "graph": "waygraph graph"
   },
   "waygraph": {
     "baseUrl": "https://example.com"
   },
   "dependencies": {
-    "waygraph": "^0.9.0"
+    "waygraph": "^0.10.6"
   },
   "devDependencies": {
     "@playwright/test": "^1.55.0",