waygraph 0.12.9 → 0.12.10

package/dist/auto-explore-run.d.ts

@@ -4,6 +4,8 @@ export interface AutoExploreOptions {
     baseURL?: string;
     /** Initial URL when the page is blank (defaults to baseURL). */
     startUrl?: string;
+    /** Phase C: glob / regex / bare `--blocks` file select for discovery. */
+    blocksSelect?: import("./blocks-select.js").BlocksSelect;
 }
 /**
  * Saucedemo-only defaults. Exact key names only — never substring `"login"`

package/dist/auto-explore-run.js

@@ -491,7 +491,11 @@ export async function runAutoExplore(projectDir, options = {}) {
     const cli = options.cli === true;
     const baseURL = options.baseURL ?? resolveBaseUrl(projectDir) ?? process.env.WAYGRAPH_BASE_URL;
     const startUrl = options.startUrl ?? baseURL;
-    const { graph, library } = await buildExploreContext(projectDir);
+    const { graph, library } = await buildExploreContext(projectDir, options.blocksSelect ? { blocksSelect: options.blocksSelect } : undefined);
+    if (options.blocksSelect) {
+        console.error(`waygraph auto: --blocks ${options.blocksSelect.raw} → ` +
+            `${library.byName.size} block(s), ${graph.edges.length} edge(s)`);
+    }
     const mem = new MemPage();
     seedDefaultMem(library.byName, mem);
     const engine = cli ? new Engine({ headless: true }) : new Engine({ headless: false, slowMo: 250 });

package/dist/auto-explore.d.ts

@@ -32,7 +32,9 @@ export interface ExploreMenu {
 /**
  * Import every `*.block.ts` export keyed by runtime Block `.name`.
  */
-export declare function loadBlockLibrary(projectDir: string): Promise<{
+export declare function loadBlockLibrary(projectDir: string, opts?: {
+    blocksSelect?: import("./blocks-select.js").BlocksSelect;
+}): Promise<{
     byName: Map<string, BlockEntry>;
     navBlocks: BlockEntry[];
 }>;
@@ -46,7 +48,9 @@ export declare function exploreChoices(graph: WaygraphGraph, here: string | null
 export declare function buildExploreMenu(page: Page, graph: WaygraphGraph, library: {
     byName: Map<string, BlockEntry>;
 }, here: string | null): Promise<ExploreMenu>;
-export declare function buildExploreContext(projectDir: string): Promise<{
+export declare function buildExploreContext(projectDir: string, opts?: {
+    blocksSelect?: import("./blocks-select.js").BlocksSelect;
+}): Promise<{
     graph: WaygraphGraph;
     library: Awaited<ReturnType<typeof loadBlockLibrary>>;
 }>;

package/dist/auto-explore.js

@@ -81,11 +81,17 @@ async function wildcardActionRunnable(page, entry, here) {
 /**
  * Import every `*.block.ts` export keyed by runtime Block `.name`.
  */
-export async function loadBlockLibrary(projectDir) {
+export async function loadBlockLibrary(projectDir, opts) {
+    const { matchBlocksSelect } = await import("./blocks-select.js");
     const byName = new Map();
     const navBlocks = [];
+    const select = opts?.blocksSelect;
     for (const file of walkDir(projectDir, /\.block\.ts$/)) {
-        const relFile = relative(projectDir, file);
+        const relFile = relative(projectDir, file).replace(/\\/g, "/");
+        // Glob/bare: path filter before import. Regex: need block name — filter after.
+        if (select && select.kind !== "regex" && !matchBlocksSelect(select, { relFile })) {
+            continue;
+        }
         let mod;
         try {
             mod = await importModule(file);
@@ -100,6 +106,10 @@ export async function loadBlockLibrary(projectDir) {
         for (const [exportName, exported] of Object.entries(mod)) {
             if (!isBlockLike(exported))
                 continue;
+            if (select &&
+                !matchBlocksSelect(select, { relFile, blockName: exported.name })) {
+                continue;
+            }
             const kind = isNavBlockMarked(exported) ? "nav" : "action";
             const entry = {
                 block: exported,
@@ -317,11 +327,11 @@ export async function buildExploreMenu(page, graph, library, here) {
     }
     return { here, sections, flat };
 }
-export async function buildExploreContext(projectDir) {
+export async function buildExploreContext(projectDir, opts) {
     // Sequential: parallel import of the same *.block.ts tree raced Playwright's
     // dual-copy guard in some installs and left graph edges without library entries
     // (LoginPage → "No moves").
-    const library = await loadBlockLibrary(projectDir);
-    const graph = await discoverGraph(projectDir);
+    const library = await loadBlockLibrary(projectDir, opts);
+    const graph = await discoverGraph(projectDir, opts);
     return { graph, library };
 }

package/dist/blocks-select.d.ts

@@ -0,0 +1,22 @@
+export type BlocksSelectKind = "regex" | "glob" | "bare";
+export interface BlocksSelect {
+    kind: BlocksSelectKind;
+    /** Original token. */
+    raw: string;
+    /** For regex: compiled without wrapping slashes. For glob: pattern as given. */
+    pattern: string;
+    re?: RegExp;
+}
+/** True when the token is file-select (glob/regex), not a bare flow/checkpoint name. */
+export declare function isFileSelectToken(token: string): boolean;
+export declare function parseBlocksSelect(token: string): BlocksSelect;
+/** Glob → RegExp (simple: ** / * / ? only; no brace expansion). */
+export declare function globToRegExp(glob: string): RegExp;
+export declare function matchBlocksSelect(select: BlocksSelect, opts: {
+    relFile: string;
+    blockName?: string;
+}): boolean;
+export declare function filterByBlocksSelect<T extends {
+    file: string;
+    block?: string;
+}>(items: T[], select: BlocksSelect | undefined, projectDir: string): T[];

package/dist/blocks-select.js

@@ -0,0 +1,85 @@
+/**
+ * Shared `--blocks` select grammar (RFC Phase C).
+ *
+ * - `/pattern/`  -> regex on relative file path OR block name
+ * - has `*`/`**` -> glob on relative file path (POSIX-ish)
+ * - otherwise    -> bare token (flow export / checkpoint / block name) — caller decides
+ */
+import { relative } from "node:path";
+/** True when the token is file-select (glob/regex), not a bare flow/checkpoint name. */
+export function isFileSelectToken(token) {
+    if (!token)
+        return false;
+    if (token.length >= 2 && token.startsWith("/") && token.endsWith("/") && token.length > 2) {
+        return true;
+    }
+    return token.includes("*");
+}
+export function parseBlocksSelect(token) {
+    const raw = token.trim();
+    if (raw.length >= 2 && raw.startsWith("/") && raw.endsWith("/")) {
+        const body = raw.slice(1, -1);
+        return { kind: "regex", raw, pattern: body, re: new RegExp(body) };
+    }
+    if (raw.includes("*")) {
+        return { kind: "glob", raw, pattern: raw };
+    }
+    return { kind: "bare", raw, pattern: raw };
+}
+/** Glob → RegExp (simple: ** / * / ? only; no brace expansion). */
+export function globToRegExp(glob) {
+    let out = "";
+    for (let i = 0; i < glob.length; i++) {
+        const c = glob[i];
+        if (c === "*" && glob[i + 1] === "*") {
+            out += ".*";
+            i++;
+            if (glob[i + 1] === "/")
+                i++;
+            continue;
+        }
+        if (c === "*") {
+            out += "[^/]*";
+            continue;
+        }
+        if (c === "?") {
+            out += "[^/]";
+            continue;
+        }
+        if (".+^${}()|[]\\".includes(c))
+            out += "\\" + c;
+        else
+            out += c;
+    }
+    return new RegExp("^" + out + "$");
+}
+export function matchBlocksSelect(select, opts) {
+    const file = opts.relFile.replace(/\\/g, "/");
+    const name = opts.blockName ?? "";
+    if (select.kind === "regex") {
+        const re = select.re ?? new RegExp(select.pattern);
+        return re.test(file) || (name !== "" && re.test(name));
+    }
+    if (select.kind === "glob") {
+        return globToRegExp(select.pattern.replace(/\\/g, "/")).test(file);
+    }
+    // bare: match block name equality (case-sensitive) or path substring
+    if (name && name === select.pattern)
+        return true;
+    if (file.includes(select.pattern))
+        return true;
+    return false;
+}
+export function filterByBlocksSelect(items, select, projectDir) {
+    if (!select)
+        return items;
+    return items.filter((it) => {
+        const relFile = it.file.startsWith(projectDir)
+            ? relative(projectDir, it.file)
+            : it.file;
+        return matchBlocksSelect(select, {
+            relFile: relFile.replace(/\\/g, "/"),
+            ...(it.block !== undefined ? { blockName: it.block } : {}),
+        });
+    });
+}

package/dist/cli.js

@@ -21,6 +21,7 @@ import { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./gra
 import { runAutoExplore } from "./auto-explore-run.js";
 import { runAgentDive } from "./agent-dive.js";
 import { runTraverse } from "./traverse-run.js";
+import { isFileSelectToken, parseBlocksSelect, } from "./blocks-select.js";
 // ---------------------------------------------------------------------------
 // Filesystem
 // ---------------------------------------------------------------------------
@@ -3673,7 +3674,8 @@ Primary (less is more):
 
 Also:
   waygraph list | nav | validate | check | graph | init <name>
-  waygraph traverse [project]              Serial graph crawl (Phase B)
+  waygraph traverse [project]              Serial graph crawl (Phase B+)
+                 --blocks <glob|/re/|sub>  Phase C: filter *.block.ts discovery
                  --from <Checkpoint>       Seed / start checkpoint
                  --data '{...}'            Mem seed
                  --max-steps N             Cap Block runs (default 50)
@@ -3697,6 +3699,8 @@ Examples:
   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 auto --blocks '/mailpit/'                     # Phase C filtered explore
+  waygraph traverse --blocks '**/mailpit/**/*.block.ts'  # Phase C filtered crawl
   waygraph run  --blocks "loginFlow then add-all-to-cart" --data '{...}' --video
 
 Aliases (compat): \`chain <spec>\` -> run --blocks; \`chain auto A B\` -> auto --blocks A B;
@@ -3790,6 +3794,7 @@ async function main() {
             let maxEdge;
             let headed = false;
             let baseUrl;
+            let blocksFilter;
             let projectDir = process.cwd();
             for (let i = 0; i < rest.length; i++) {
                 const a = rest[i];
@@ -3801,6 +3806,20 @@ async function main() {
                     data = a.startsWith("--data=") ? a.slice(7) : rest[++i];
                     continue;
                 }
+                if (a === "--blocks" || a.startsWith("--blocks=")) {
+                    if (a.startsWith("--blocks=")) {
+                        blocksFilter = a.slice("--blocks=".length);
+                    }
+                    else {
+                        const v = rest[++i];
+                        if (!v || v.startsWith("-")) {
+                            console.error("waygraph traverse: --blocks needs a glob, /regex/, or path substring");
+                            process.exit(1);
+                        }
+                        blocksFilter = v;
+                    }
+                    continue;
+                }
                 if (a === "--max-steps" || a.startsWith("--max-steps=")) {
                     const v = a.startsWith("--max-steps=") ? a.slice(12) : rest[++i];
                     maxSteps = Number(v);
@@ -3832,6 +3851,7 @@ async function main() {
 Serial graph crawl (RFC Phase B). Walks unused legal edges until a leaf,
 budget kill, or first broken edge.
 
+  --blocks <glob|/regex/|substr>  Phase C: filter *.block.ts discovery
   --from <Checkpoint>     start checkpoint (optional)
   --data '{...}'          Mem seed JSON
   --max-steps N           default 50
@@ -3840,6 +3860,10 @@ budget kill, or first broken edge.
   --non-headless          show browser
   --base-url URL
 
+Examples:
+  waygraph traverse --blocks '**/mailpit/**/*.block.ts'
+  waygraph traverse --blocks '/mailpit|login/'
+
 PASS:  [Reached Leaf Node[traverse-1] at=... steps=N]
 FAIL:  [Broke at edge[traverse-1] block=... from=... to=...]
 `);
@@ -3853,6 +3877,9 @@ FAIL:  [Broke at edge[traverse-1] block=... from=... to=...]
                 console.error(`waygraph traverse: no such directory: ${projectDir}`);
                 process.exit(1);
             }
+            const blocksSelect = blocksFilter
+                ? parseBlocksSelect(blocksFilter)
+                : undefined;
             const code = await runTraverse(projectDir, {
                 ...(from ? { from } : {}),
                 ...(data ? { data } : {}),
@@ -3865,6 +3892,7 @@ FAIL:  [Broke at edge[traverse-1] block=... from=... to=...]
                     : {}),
                 headed,
                 ...(baseUrl ? { baseURL: baseUrl } : {}),
+                ...(blocksSelect ? { blocksSelect } : {}),
             });
             process.exit(code);
         }
@@ -4024,13 +4052,23 @@ Agents shipped: waygraph-planner, waygraph-author, waygraph-healer.
                 process.exit(1);
             }
             // auto --blocks From To  (graph path-find + run)
+            // auto --blocks '/regex/' or '**/*.block.ts'  (Phase C file select → explore)
             if (command === "auto" && (flags.blocksFromTo || flags.blocks)) {
                 if (flags.blocksFromTo) {
                     const [fromTag, toTag] = flags.blocksFromTo;
                     await runChainAuto(proj, fromTag, toTag);
                     break;
                 }
+                if (flags.blocks && isFileSelectToken(flags.blocks)) {
+                    const blocksSelect = parseBlocksSelect(flags.blocks);
+                    const baseURL = flags.baseUrl ?? process.env.WAYGRAPH_BASE_URL ?? resolveBaseUrl(proj);
+                    await runAutoExplore(proj, baseURL
+                        ? { cli: cliPicker, baseURL, blocksSelect }
+                        : { cli: cliPicker, blocksSelect });
+                    break;
+                }
                 console.error("waygraph auto --blocks expects <fromCheckpoint> <toCheckpoint>\n" +
+                    "  or file select: --blocks '**/mailpit/**/*.block.ts' / --blocks '/mailpit/'\n" +
                     '  e.g. waygraph auto --blocks LoginPage OrderComplete\n' +
                     '  for a hand-named chain use: waygraph run --blocks "a then b"\n' +
                     "  or: waygraph auto src/flows/shop.flow.ts");

package/dist/graph.d.ts

@@ -1,3 +1,4 @@
+import { type BlocksSelect } from "./blocks-select.js";
 /**
  * The state-machine shape `waygraph auto` discovers from a project's own
  * Blocks - Checkpoints are nodes, Blocks are edges. Kept as plain data (not
@@ -67,4 +68,6 @@ export declare function findBlockPath(graph: WaygraphGraph, fromTag: string, toT
  * already is for `check`, unlike `chain`, which spawns a child process
  * specifically because it also EXECUTES Blocks, not just imports them.
  */
-export declare function discoverGraph(projectDir: string): Promise<WaygraphGraph>;
+export declare function discoverGraph(projectDir: string, opts?: {
+    blocksSelect?: BlocksSelect;
+}): Promise<WaygraphGraph>;

package/dist/graph.js

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { join, dirname, relative, resolve } from "node:path";
+import { matchBlocksSelect, } from "./blocks-select.js";
 /**
  * Renders a `WaygraphGraph` as Mermaid `stateDiagram-v2` text - paste
  * straight into a `.md` file's ```mermaid fence or a live editor. `"*"`
@@ -296,8 +297,15 @@ function extractDefineBlockGenerics(src) {
  * already is for `check`, unlike `chain`, which spawns a child process
  * specifically because it also EXECUTES Blocks, not just imports them.
  */
-export async function discoverGraph(projectDir) {
-    const files = discoverBlocks(projectDir);
+export async function discoverGraph(projectDir, opts) {
+    let files = discoverBlocks(projectDir);
+    const select = opts?.blocksSelect;
+    // Glob/bare: drop files early. Regex needs block names — filter per export below.
+    if (select && select.kind !== "regex") {
+        files = files.filter((file) => matchBlocksSelect(select, {
+            relFile: relative(projectDir, file).replace(/\\/g, "/"),
+        }));
+    }
     const nodeTags = new Set();
     const edges = [];
     const skipped = [];
@@ -326,6 +334,13 @@ export async function discoverGraph(projectDir) {
             if (!isBlockLike(exported))
                 continue;
             const blockName = exported.name;
+            if (select &&
+                !matchBlocksSelect(select, {
+                    relFile: relFile.replace(/\\/g, "/"),
+                    blockName,
+                })) {
+                continue;
+            }
             if (isNavBlockMarked(exported)) {
                 try {
                     // NavBlock / PageBlock resolve() ignores input - always checkpoint(tag).

package/dist/index.d.ts

@@ -9,3 +9,5 @@ export type { Flow, EngineConfig, ComposedBlock, FastForwardComposedBlock, RunGr
 export type { ActionPage } from "./types.js";
 export { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./graph.js";
 export type { WaygraphGraph, WaygraphNode, WaygraphEdge, SkippedBlock, OrphanBlock } from "./graph.js";
+export { isFileSelectToken, parseBlocksSelect, matchBlocksSelect, globToRegExp, } from "./blocks-select.js";
+export type { BlocksSelect, BlocksSelectKind } from "./blocks-select.js";

package/dist/index.js

@@ -4,3 +4,4 @@ export { Trait, urlMatches, textEquals, visible } from "./trait.js";
 export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, fastForwardComposeBlock, isFastForwardBlock, preflight, withSessionReset, withTitle, withExpectedFailure, withHighlightFixtures, chainFlow, } from "./engine.js";
 export { resolveHighlightSlots, resolveSlides, resolveFixtureDwellMs, resolveSlideDwellMs, formatHighlightCaption, hasAuthoredStubAfter, hasAuthoredStubOnError, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, SLIDE_DURATION_MS_DEFAULT, SLIDE_DURATION_FAST_MS_DEFAULT, } from "./highlights.js";
 export { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./graph.js";
+export { isFileSelectToken, parseBlocksSelect, matchBlocksSelect, globToRegExp, } from "./blocks-select.js";

package/dist/traverse-run.d.ts

@@ -17,6 +17,8 @@ export interface TraverseOptions {
     headed?: boolean;
     /** Traverse id for greppable lines (default traverse-1). */
     traverseId?: string;
+    /** Phase C: glob / regex / bare `--blocks` file select. */
+    blocksSelect?: import("./blocks-select.js").BlocksSelect;
 }
 /**
  * Serial graph crawl. Prints greppable PASS/FAIL lines; non-zero exit on break.

package/dist/traverse-run.js

@@ -106,7 +106,11 @@ export async function runTraverse(projectDir, options = {}) {
     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 { graph, library } = await buildExploreContext(projectDir, options.blocksSelect ? { blocksSelect: options.blocksSelect } : undefined);
+    if (options.blocksSelect) {
+        console.error(`waygraph traverse: --blocks ${options.blocksSelect.raw} → ` +
+            `${library.byName.size} block(s), ${graph.edges.length} edge(s)`);
+    }
     const mem = new MemPage();
     seedMem(library.byName, mem, options.data);
     const engine = new Engine({ headless: !headed, slowMo: headed ? 100 : 0 });

package/package.json

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