waygraph 0.12.7 → 0.12.8

package/dist/cli.d.ts

@@ -7,7 +7,7 @@
  *   demo   Watch (step overlay); `--blocks` `--data` `--auto-next` `--fast` `--full` `--ff-expand`
  *   run    Execute; `--blocks` `--data` `--non-headless` `--video`
  *
- * Also: list / nav / validate / check / graph / init / agent-dive / try
+ * Also: list / nav / validate / check / graph / init / agent-dive / traverse / try
  * Aliases (one release): `chain` -> run/demo --blocks; `--autoplay` -> `--auto-next`
  *
  * "project" defaults to cwd. Flags beat WAYGRAPH_* env.

package/dist/cli.js

@@ -7,7 +7,7 @@
  *   demo   Watch (step overlay); `--blocks` `--data` `--auto-next` `--fast` `--full` `--ff-expand`
  *   run    Execute; `--blocks` `--data` `--non-headless` `--video`
  *
- * Also: list / nav / validate / check / graph / init / agent-dive / try
+ * Also: list / nav / validate / check / graph / init / agent-dive / traverse / try
  * Aliases (one release): `chain` -> run/demo --blocks; `--autoplay` -> `--auto-next`
  *
  * "project" defaults to cwd. Flags beat WAYGRAPH_* env.
@@ -20,6 +20,7 @@ import { spawn } from "node:child_process";
 import { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./graph.js";
 import { runAutoExplore } from "./auto-explore-run.js";
 import { runAgentDive } from "./agent-dive.js";
+import { runTraverse } from "./traverse-run.js";
 // ---------------------------------------------------------------------------
 // Filesystem
 // ---------------------------------------------------------------------------
@@ -3661,6 +3662,12 @@ Primary (less is more):
 
 Also:
   waygraph list | nav | validate | check | graph | init <name>
+  waygraph traverse [project]              Serial graph crawl (Phase B)
+                 --from <Checkpoint>       Seed / start checkpoint
+                 --data '{...}'            Mem seed
+                 --max-steps N             Cap Block runs (default 50)
+                 --max-visits N            Cap visits per node (default 2)
+                 --non-headless            Show browser
   waygraph agent-dive [--loop claude|opencode|cursor|vscode] [--prompts]
                  Initialize coding-agent defs (Playwright init-agents analogue)
   waygraph try [demo|auto|auto:cli]        One-shot saucedemo in a temp dir
@@ -3759,6 +3766,98 @@ async function main() {
             initCommand(args[1] ?? "");
             break;
         }
+        case "traverse": {
+            if (args.includes("--step") || args.includes("--auto-next") || args.includes("--autoplay")) {
+                console.error("waygraph traverse: --step / --auto-next not supported (not a demo)");
+                process.exit(1);
+            }
+            const rest = args.slice(1);
+            let from;
+            let data;
+            let maxSteps;
+            let maxVisits;
+            let maxEdge;
+            let headed = false;
+            let baseUrl;
+            let projectDir = process.cwd();
+            for (let i = 0; i < rest.length; i++) {
+                const a = rest[i];
+                if (a === "--from" || a.startsWith("--from=")) {
+                    from = a.startsWith("--from=") ? a.slice(7) : rest[++i];
+                    continue;
+                }
+                if (a === "--data" || a.startsWith("--data=")) {
+                    data = a.startsWith("--data=") ? a.slice(7) : rest[++i];
+                    continue;
+                }
+                if (a === "--max-steps" || a.startsWith("--max-steps=")) {
+                    const v = a.startsWith("--max-steps=") ? a.slice(12) : rest[++i];
+                    maxSteps = Number(v);
+                    continue;
+                }
+                if (a === "--max-visits" || a.startsWith("--max-visits=")) {
+                    const v = a.startsWith("--max-visits=") ? a.slice(13) : rest[++i];
+                    maxVisits = Number(v);
+                    continue;
+                }
+                if (a === "--max-visits-per-edge" || a.startsWith("--max-visits-per-edge=")) {
+                    const v = a.startsWith("--max-visits-per-edge=")
+                        ? a.slice("--max-visits-per-edge=".length)
+                        : rest[++i];
+                    maxEdge = Number(v);
+                    continue;
+                }
+                if (a === "--non-headless" || a === "--headed") {
+                    headed = true;
+                    continue;
+                }
+                if (a === "--base-url" || a.startsWith("--base-url=")) {
+                    baseUrl = a.startsWith("--base-url=") ? a.slice(11) : rest[++i];
+                    continue;
+                }
+                if (a === "--help" || a === "-h") {
+                    console.log(`waygraph traverse [project] [flags]
+
+Serial graph crawl (RFC Phase B). Walks unused legal edges until a leaf,
+budget kill, or first broken edge.
+
+  --from <Checkpoint>     start checkpoint (optional)
+  --data '{...}'          Mem seed JSON
+  --max-steps N           default 50
+  --max-visits N          per-node visit cap (default 2)
+  --max-visits-per-edge N default 1
+  --non-headless          show browser
+  --base-url URL
+
+PASS:  [Reached Leaf Node[traverse-1] at=... steps=N]
+FAIL:  [Broke at edge[traverse-1] block=... from=... to=...]
+`);
+                    process.exit(0);
+                }
+                if (!a.startsWith("-")) {
+                    projectDir = resolve(a);
+                }
+            }
+            if (!existsSync(projectDir) || !statSync(projectDir).isDirectory()) {
+                console.error(`waygraph traverse: no such directory: ${projectDir}`);
+                process.exit(1);
+            }
+            const code = await runTraverse(projectDir, {
+                ...(from ? { from } : {}),
+                ...(data ? { data } : {}),
+                ...(maxSteps !== undefined && Number.isFinite(maxSteps) ? { maxSteps } : {}),
+                ...(maxVisits !== undefined && Number.isFinite(maxVisits)
+                    ? { maxVisitsPerNode: maxVisits }
+                    : {}),
+                ...(maxEdge !== undefined && Number.isFinite(maxEdge)
+                    ? { maxVisitsPerEdge: maxEdge }
+                    : {}),
+                headed,
+                ...(baseUrl ? { baseURL: baseUrl } : {}),
+            });
+            process.exitCode = code;
+            break;
+        }
         case "agent-dive":
         case "init-agents": {
             // Playwright analogue: npx playwright init-agents --loop <provider>

package/dist/traverse-run.d.ts

@@ -0,0 +1,24 @@
+export interface TraverseOptions {
+    baseURL?: string;
+    startUrl?: string;
+    /** Seed checkpoint label (optional - otherwise detect from page / nav). */
+    from?: string;
+    /** Global Mem seed JSON (or use WAYGRAPH_DATA / WAYGRAPH_AUTO_MEM). */
+    data?: string;
+    /** Max Block runs this traverse (default 50). */
+    maxSteps?: number;
+    /** Max times a checkpoint may be visited (default 2). */
+    maxVisitsPerNode?: number;
+    /** Max times an edge key (block::instanceId) may be taken (default 1). */
+    maxVisitsPerEdge?: number;
+    /** Wall-clock budget ms (default 15m). */
+    timeoutMs?: number;
+    /** Show browser (default headless). */
+    headed?: boolean;
+    /** Traverse id for greppable lines (default traverse-1). */
+    traverseId?: string;
+}
+/**
+ * Serial graph crawl. Prints greppable PASS/FAIL lines; non-zero exit on break.
+ */
+export declare function runTraverse(projectDir: string, options?: TraverseOptions): Promise<number>;

package/dist/traverse-run.js

@@ -0,0 +1,227 @@
+/**
+ * Phase B: serial graph traverse (RFC traverse-ffcompose).
+ * Walk unused legal edges until leaf / budget / break. No parallel yet.
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { Engine, start, end, locate } from "./engine.js";
+import { MemPage } from "./mem-page.js";
+import { buildExploreContext, buildExploreMenu, } from "./auto-explore.js";
+import { defaultMemValueForKey } from "./auto-explore-run.js";
+function resolveBaseUrl(projectDir) {
+    if (process.env.WAYGRAPH_BASE_URL)
+        return process.env.WAYGRAPH_BASE_URL;
+    const pkgPath = join(projectDir, "package.json");
+    if (!existsSync(pkgPath))
+        return undefined;
+    try {
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+        return pkg.waygraph?.baseUrl;
+    }
+    catch {
+        return undefined;
+    }
+}
+function seedMem(library, mem, dataJson) {
+    const raw = dataJson ?? process.env.WAYGRAPH_DATA ?? process.env.WAYGRAPH_AUTO_MEM;
+    let envParsed = {};
+    if (raw) {
+        try {
+            envParsed = JSON.parse(raw);
+        }
+        catch {
+            throw new Error(`waygraph traverse: --data / WAYGRAPH_DATA is not valid JSON`);
+        }
+    }
+    for (const entry of library.values()) {
+        for (const k of entry.block.requires ?? []) {
+            if (mem.has(k))
+                continue;
+            if (k.name in envParsed) {
+                mem.set(k, envParsed[k.name]);
+                continue;
+            }
+            const def = defaultMemValueForKey(k.name);
+            if (def !== undefined)
+                mem.set(k, def);
+        }
+    }
+}
+function missingMemKeys(entry, mem) {
+    return (entry.block.requires ?? []).filter((k) => !mem.has(k));
+}
+function ensureMem(entry, mem) {
+    const missing = missingMemKeys(entry, mem);
+    if (missing.length === 0)
+        return;
+    throw new Error(`Block "${entry.block.name}" needs Mem keys: ${missing.map((k) => k.name).join(", ")} ` +
+        `(pass --data '{...}' or WAYGRAPH_DATA)`);
+}
+function edgeKey(edge) {
+    const id = edge.instanceOption?.id;
+    return id ? `${edge.block}::${id}` : edge.block;
+}
+async function detectHere(page, navBlocks) {
+    try {
+        const url = page.url();
+        if (url.includes("/login"))
+            return "PiaLogin";
+        if (url.includes("mailpit") || url.includes(":54324") || url.includes("/mailhog")) {
+            return "PiaMailpitGui";
+        }
+    }
+    catch {
+        /* ignore */
+    }
+    const tags = navBlocks.map((n) => n.block);
+    return locate(page, tags, { timeoutMs: 1500 });
+}
+async function runOneBlock(engine, entry, context, page, mem) {
+    const flow = engine.defineFlow([start, entry.block, end]);
+    const BLOCK_TIMEOUT_MS = 45_000;
+    let timer;
+    try {
+        const ran = await Promise.race([
+            flow.run(context, mem, { page, closeOnFinish: false }),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`Block "${entry.block.name}" timed out after ${BLOCK_TIMEOUT_MS / 1000}s`)), BLOCK_TIMEOUT_MS);
+            }),
+        ]);
+        return ran.result;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+/**
+ * Serial graph crawl. Prints greppable PASS/FAIL lines; non-zero exit on break.
+ */
+export async function runTraverse(projectDir, options = {}) {
+    const traverseId = options.traverseId ?? "traverse-1";
+    const maxSteps = options.maxSteps ?? 50;
+    const maxVisitsPerNode = options.maxVisitsPerNode ?? 2;
+    const maxVisitsPerEdge = options.maxVisitsPerEdge ?? 1;
+    const timeoutMs = options.timeoutMs ?? 15 * 60_000;
+    const headed = options.headed === true || process.env.WAYGRAPH_HEADED === "1";
+    const baseURL = options.baseURL ?? resolveBaseUrl(projectDir) ?? process.env.WAYGRAPH_BASE_URL;
+    const startUrl = options.startUrl ?? baseURL;
+    const { graph, library } = await buildExploreContext(projectDir);
+    const mem = new MemPage();
+    seedMem(library.byName, mem, options.data);
+    const engine = new Engine({ headless: !headed, slowMo: headed ? 100 : 0 });
+    const { chromium } = await import("@playwright/test");
+    const executablePath = process.env.CHROME_PATH || process.env.CHROMIUM_PATH;
+    const launchOpts = {
+        headless: !headed,
+    };
+    if (executablePath)
+        launchOpts.executablePath = executablePath;
+    const browser = await chromium.launch(launchOpts);
+    const contextOpts = {
+        viewport: { width: 1280, height: 720 },
+    };
+    if (baseURL)
+        contextOpts.baseURL = baseURL;
+    const context = await browser.newContext(contextOpts);
+    let page = await context.newPage();
+    const nodeVisits = new Map();
+    const edgeVisits = new Map();
+    const edgesHit = new Set();
+    let steps = 0;
+    const startedAt = Date.now();
+    let lastHere = options.from ?? null;
+    let exitCode = 0;
+    console.error(`waygraph traverse[${traverseId}]: ${graph.nodes.length} node(s), ${graph.edges.length} edge(s)` +
+        (baseURL ? ` base=${baseURL}` : "") +
+        ` maxSteps=${maxSteps} maxVisits/node=${maxVisitsPerNode} maxVisits/edge=${maxVisitsPerEdge}`);
+    try {
+        if (startUrl) {
+            await page.goto(startUrl, { waitUntil: "domcontentloaded" }).catch(() => { });
+            await page.waitForLoadState("load").catch(() => { });
+        }
+        for (;;) {
+            if (Date.now() - startedAt > timeoutMs) {
+                console.log(`[Killed timeout[${traverseId}] node=${lastHere ?? "?"} wallMs=${timeoutMs}]`);
+                exitCode = 1;
+                break;
+            }
+            if (steps >= maxSteps) {
+                console.log(`[Killed max-steps[${traverseId}] node=${lastHere ?? "?"} steps=${steps} max=${maxSteps}]`);
+                exitCode = 1;
+                break;
+            }
+            if (page.isClosed()) {
+                page = await context.newPage();
+                if (startUrl) {
+                    await page.goto(startUrl, { waitUntil: "domcontentloaded" }).catch(() => { });
+                }
+            }
+            const detected = await detectHere(page, library.navBlocks);
+            const here = lastHere ?? detected ?? options.from ?? null;
+            if (here && (nodeVisits.get(here) ?? 0) >= maxVisitsPerNode) {
+                console.log(`[Killed loop[${traverseId}] node=${here} visits=${nodeVisits.get(here)} max=${maxVisitsPerNode}]`);
+                exitCode = 1;
+                break;
+            }
+            const menu = await buildExploreMenu(page, graph, library, here);
+            const candidates = menu.flat.filter((edge) => {
+                const key = edgeKey(edge);
+                return (edgeVisits.get(key) ?? 0) < maxVisitsPerEdge;
+            });
+            if (candidates.length === 0) {
+                const label = here ?? detected ?? "unknown";
+                console.log(`[Reached Leaf Node[${traverseId}] at=${label} steps=${steps}]`);
+                console.error(`waygraph traverse[${traverseId}]: PASS leaf edgesHit=${edgesHit.size} steps=${steps}`);
+                break;
+            }
+            const pick = [...candidates].sort((a, b) => {
+                const aWild = a.from === "*" ? 1 : 0;
+                const bWild = b.from === "*" ? 1 : 0;
+                if (aWild !== bWild)
+                    return aWild - bWild;
+                return edgeKey(a).localeCompare(edgeKey(b));
+            })[0];
+            const entry = library.byName.get(pick.block);
+            if (!entry) {
+                console.log(`[Broke at edge[${traverseId}] block=${pick.block} from=${here ?? "?"} to=${pick.to} reason=not-loaded]`);
+                exitCode = 1;
+                break;
+            }
+            const fromLabel = here ?? pick.from;
+            try {
+                if (pick.instanceOption) {
+                    mem.set(pick.instanceOption.key, pick.instanceOption.value);
+                }
+                ensureMem(entry, mem);
+                console.error(`waygraph traverse[${traverseId}]: step ${steps + 1} ${fromLabel} -[${pick.block}]-> ${pick.to}` +
+                    (pick.label ? ` (${pick.label})` : ""));
+                const out = await runOneBlock(engine, entry, context, page, mem);
+                const observed = typeof out === "object" && out && "__state" in out
+                    ? String(out.__state)
+                    : pick.to;
+                const key = edgeKey(pick);
+                edgeVisits.set(key, (edgeVisits.get(key) ?? 0) + 1);
+                edgesHit.add(key);
+                if (here)
+                    nodeVisits.set(here, (nodeVisits.get(here) ?? 0) + 1);
+                lastHere = observed;
+                steps += 1;
+                if (observed !== pick.to && pick.to !== "*") {
+                    console.error(`waygraph traverse[${traverseId}]: WARN static to=${pick.to} observed=${observed}`);
+                }
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                console.log(`[Broke at edge[${traverseId}] block=${pick.block} from=${fromLabel} to=${pick.to}] ${msg}`);
+                exitCode = 1;
+                break;
+            }
+        }
+    }
+    finally {
+        await browser.close().catch(() => { });
+    }
+    console.error(`waygraph traverse[${traverseId}]: done exit=${exitCode} steps=${steps} edgesHit=${edgesHit.size}`);
+    return exitCode;
+}

package/package.json

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