waygraph 0.15.53 → 0.16.0

package/dist/manifest/pack.js

@@ -0,0 +1,109 @@
+// `waygraph map pack <group>`: compiles one map group with the project's own TypeScript into an installable package
+// (JavaScript + types, an index re-exporting everything, and `waygraph.map.json` for the scanner and Waygraph UI).
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { findMapGroup, mapGroups } from "./maps.js";
+import { mapGroupImportProblems } from "./map-imports.js";
+import { MANIFEST_VERSION } from "./manifest.js";
+import { scanProject } from "./project.js";
+import { walkDir } from "./scan.js";
+function waygraphVersion() {
+    const pkg = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json");
+    return JSON.parse(readFileSync(pkg, "utf8")).version;
+}
+function compile(projectDir, group, out) {
+    let tsc;
+    try {
+        tsc = createRequire(join(projectDir, "package.json")).resolve("typescript/bin/tsc");
+    }
+    catch {
+        return "TypeScript is not installed in this project (npm i -D typescript)";
+    }
+    const base = join(projectDir, "tsconfig.json");
+    const config = join(out, "tsconfig.pack.json");
+    writeFileSync(config, JSON.stringify({
+        ...(existsSync(base) ? { extends: base } : {}),
+        compilerOptions: {
+            ...(existsSync(base) ? {} : { target: "ES2022", module: "NodeNext", moduleResolution: "NodeNext", strict: true, skipLibCheck: true }),
+            noEmit: false,
+            declaration: true,
+            rootDir: group.dir,
+            outDir: out,
+        },
+        include: [join(group.dir, "**", "*.ts")],
+        exclude: [],
+    }, null, 2));
+    const run = spawnSync(process.execPath, [tsc, "-p", config], { cwd: projectDir, encoding: "utf8" });
+    rmSync(config, { force: true });
+    if (run.status !== 0)
+        return `tsc failed:\n${run.stdout}${run.stderr}`;
+    return undefined;
+}
+/** Packs a map group (by `(external)/hoppscotch` or `hoppscotch`) into an installable package folder. */
+export async function packMapGroup(projectDir, groupName, opts = {}) {
+    const group = findMapGroup(projectDir, groupName);
+    if (!group) {
+        const known = mapGroups(projectDir).map((g) => g.group);
+        return {
+            ok: false,
+            reason: `no map group "${groupName}" (a src/map/ folder with its own _states.ts)${known.length ? `; groups: ${known.join(", ")}` : ""}`,
+        };
+    }
+    const problems = mapGroupImportProblems(group);
+    if (problems.length > 0)
+        return { ok: false, reason: `${group.group} imports files outside the group`, problems };
+    const slug = group.group.split("/").pop().replace(/[()]/g, "");
+    const name = opts.name ?? `waygraph-map-${slug}`;
+    const out = resolve(projectDir, opts.out ?? join(".waygraph", "packages", slug));
+    rmSync(out, { recursive: true, force: true });
+    mkdirSync(out, { recursive: true });
+    const failed = compile(projectDir, group, out);
+    if (failed)
+        return { ok: false, reason: failed };
+    const scan = await scanProject(projectDir, { flows: false, maps: false });
+    const blocks = scan.blocks.filter((b) => b.absFile.startsWith(group.dir + sep));
+    const checkpoints = new Set();
+    for (const b of blocks)
+        for (const t of [...b.from, ...b.to])
+            if (t !== "*")
+                checkpoints.add(t);
+    const map = {
+        version: MANIFEST_VERSION,
+        name,
+        group: group.group,
+        checkpoints: [...checkpoints].sort(),
+        blocks: blocks.map((b) => ({
+            name: b.name,
+            exportName: b.exportName,
+            kind: b.kind,
+            from: b.from,
+            to: b.to,
+            requires: b.requires,
+            file: relative(group.dir, b.absFile).split(sep).join("/").replace(/\.ts$/, ".js"),
+        })),
+    };
+    writeFileSync(join(out, "waygraph.map.json"), JSON.stringify(map, null, 2) + "\n");
+    const modules = walkDir(out, /\.js$/)
+        .map((f) => "./" + relative(out, f).split(sep).join("/"))
+        .filter((f) => f !== "./index.js")
+        .sort();
+    const index = modules.map((m) => `export * from "${m}";`).join("\n") + "\n";
+    writeFileSync(join(out, "index.js"), index);
+    writeFileSync(join(out, "index.d.ts"), index);
+    writeFileSync(join(out, "package.json"), JSON.stringify({
+        name,
+        version: opts.version ?? "0.1.0",
+        description: `waygraph map: ${group.group}`,
+        type: "module",
+        main: "./index.js",
+        types: "./index.d.ts",
+        exports: { ".": { types: "./index.d.ts", default: "./index.js" }, "./*": "./*" },
+        files: ["**/*.js", "**/*.d.ts", "waygraph.map.json"],
+        keywords: ["waygraph", "waygraph-map"],
+        peerDependencies: { waygraph: `^${waygraphVersion()}` },
+    }, null, 2) + "\n");
+    return { ok: true, name, dir: out, group: group.group, blocks: blocks.length };
+}

package/dist/manifest/project.d.ts

@@ -0,0 +1,60 @@
+import type { BlocksSelect } from "./select.js";
+import type { AnyBlock } from "./scan.js";
+export type BlockKind = "nav" | "page" | "assert" | "method" | "effect" | "api" | "block";
+export interface ScannedBlock {
+    block: AnyBlock;
+    name: string;
+    exportName: string;
+    kind: BlockKind;
+    description: string;
+    /** Checkpoint tags it runs from (`"*"` = anywhere) and lands on. Empty `to` = route unknown (see `skipped`). */
+    from: string[];
+    to: string[];
+    requires: string[];
+    /** Project-relative path; Blocks from an injected library are tagged `@label/...`. */
+    file: string;
+    absFile: string;
+    /** The installed map package it came from (its `file` is then `<package>/<path>`). */
+    map?: string;
+}
+export interface ScannedFlow {
+    flow: {
+        run: (...args: unknown[]) => Promise<unknown>;
+        blocks: () => unknown[];
+    };
+    exportName: string;
+    file: string;
+    absFile: string;
+}
+/** A Block as the live menus (auto, pilot) hold it: navigation or action. */
+export interface BlockEntry {
+    block: AnyBlock;
+    exportName: string;
+    file: string;
+    kind: "nav" | "action";
+    description: string;
+}
+export interface ProjectScan {
+    projectDir: string;
+    blocks: ScannedBlock[];
+    flows: ScannedFlow[];
+    skipped: {
+        block: string;
+        file: string;
+        reason: string;
+    }[];
+}
+export interface ScanOptions {
+    blocksSelect?: BlocksSelect | undefined;
+    inject?: string[] | undefined;
+    /** Also import `*.flow.ts` files. Default true. */
+    flows?: boolean;
+    /** Also scan installed map packages (dependencies with a `waygraph.map.json`). Default true. */
+    maps?: boolean;
+    /** Called when a file fails to import (default: a one-line warning for Playwright double-install errors). */
+    onImportError?: (relFile: string, err: unknown) => void;
+}
+/** A file that fails to import is left out of the scan, and said so: a silent skip reads as "nothing there". */
+export declare function reportImportError(relFile: string, err: unknown): void;
+/** Imports every `*.block.ts` (and `*.flow.ts`) under the project and its injected roots. */
+export declare function scanProject(projectDir: string, opts?: ScanOptions): Promise<ProjectScan>;

package/dist/manifest/project.js

@@ -0,0 +1,101 @@
+// Scans a project (and any injected Block libraries) into its Blocks and Flows, with each Block's route.
+import { relative } from "node:path";
+import { matchBlocksSelect } from "./select.js";
+import { exploreRoots, injectTaggedFile } from "./roots.js";
+import { blockKind, importFresh, isBlockLike, isFlowLike, walkDir } from "./scan.js";
+import { installedMapPackages, mapPackageBlockFiles } from "./maps.js";
+function kindOf(block) {
+    const kind = blockKind(block);
+    if (kind === "nav" || kind === "page" || kind === "assert" || kind === "api")
+        return kind;
+    const salt = block.__waygraphSalt;
+    if (salt === "effect" || salt === "method" || salt === "api")
+        return salt;
+    return "block";
+}
+/** A file that fails to import is left out of the scan, and said so: a silent skip reads as "nothing there". */
+export function reportImportError(relFile, err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`waygraph: skip ${relFile}: ${msg.split("\n")[0]}`);
+}
+/** Imports every `*.block.ts` (and `*.flow.ts`) under the project and its injected roots. */
+export async function scanProject(projectDir, opts = {}) {
+    const select = opts.blocksSelect;
+    const onError = opts.onImportError ?? reportImportError;
+    const blocks = [];
+    const flows = [];
+    const skipped = [];
+    const scanBlockFile = async (absFile, rel, file, map) => {
+        let mod;
+        try {
+            mod = await importFresh(absFile);
+        }
+        catch (err) {
+            onError(rel, err);
+            return;
+        }
+        for (const [exportName, exported] of Object.entries(mod)) {
+            if (!isBlockLike(exported))
+                continue;
+            if (select && !matchBlocksSelect(select, { relFile: file, blockName: exported.name }))
+                continue;
+            const marked = exported;
+            const from = marked.__waygraphFrom ?? [];
+            const to = marked.__waygraphTo ?? [];
+            // Every factory records a route; only a bare defineBlock has none.
+            if (to.length === 0)
+                skipped.push({ block: exported.name, file, reason: "no route: build it with a define*Block factory and Checkpoint values" });
+            blocks.push({
+                block: exported,
+                name: exported.name,
+                exportName,
+                kind: kindOf(exported),
+                description: typeof exported.description === "string" ? exported.description : "",
+                from: [...from],
+                to: [...to],
+                requires: (exported.requires ?? []).map((k) => k.name),
+                file,
+                absFile,
+                ...(map ? { map } : {}),
+            });
+        }
+    };
+    for (const root of exploreRoots(projectDir, opts.inject)) {
+        let files = walkDir(root, /\.block\.ts$/);
+        if (select && select.kind !== "regex") {
+            files = files.filter((f) => matchBlocksSelect(select, { relFile: relative(root, f).replace(/\\/g, "/") }));
+        }
+        for (const absFile of files) {
+            const rel = relative(root, absFile).replace(/\\/g, "/");
+            await scanBlockFile(absFile, rel, injectTaggedFile(projectDir, root, rel));
+        }
+        if (opts.flows === false)
+            continue;
+        for (const absFile of walkDir(root, /\.flow\.ts$/)) {
+            const rel = relative(root, absFile).replace(/\\/g, "/");
+            let mod;
+            try {
+                mod = await importFresh(absFile);
+            }
+            catch (err) {
+                onError(rel, err);
+                continue;
+            }
+            for (const [exportName, exported] of Object.entries(mod)) {
+                if (isFlowLike(exported))
+                    flows.push({ flow: exported, exportName, file: injectTaggedFile(projectDir, root, rel), absFile });
+            }
+        }
+    }
+    if (opts.maps !== false) {
+        for (const pkg of installedMapPackages(projectDir)) {
+            for (const absFile of mapPackageBlockFiles(pkg)) {
+                const rel = relative(pkg.dir, absFile).replace(/\\/g, "/");
+                if (select && select.kind !== "regex" && !matchBlocksSelect(select, { relFile: `${pkg.name}/${rel}` }))
+                    continue;
+                await scanBlockFile(absFile, rel, `${pkg.name}/${rel}`, pkg.name);
+            }
+        }
+    }
+    return { projectDir, blocks, flows, skipped };
+}

package/dist/{session/block-inject.js → manifest/roots.js}

@@ -5,12 +5,9 @@
 import { existsSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { homedir } from "node:os";
 /**
  * This package's own installed root (contains `templates/`/`examples/`, sibling to `dist/`) -
- * this file compiles to `dist/session/block-inject.js`, two levels down, not one. Same class of
- * bug as `cli/util.ts`'s own `packageRoot()` (see its comment) - self-inflicted here by moving
- * this file into `src/session/` without updating the path math to match the new depth.
+ * this file compiles to `dist/manifest/roots.js`, two levels down.
  */
 function packageRoot() {
     return resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
@@ -32,20 +29,6 @@ export function injectTaggedFile(hostDir, root, relFile) {
 }
 const PRESETS = {
     saucedemo: () => join(packageRoot(), "examples", "saucedemo"),
-    demosauce: () => join(packageRoot(), "examples", "saucedemo"),
-    veciro: () => {
-        if (process.env.WAYGRAPH_INJECT_VECIRO) {
-            return resolve(process.env.WAYGRAPH_INJECT_VECIRO);
-        }
-        for (const c of [
-            join(homedir(), "Desktop", "Work", "veciro-waygraph"),
-            join(homedir(), "Desktop", "Projects", "veciro-waygraph"),
-        ]) {
-            if (existsSync(c))
-                return c;
-        }
-        return null;
-    },
 };
 /**
  * Resolve one `--inject` token to an absolute directory (preset name or path).

package/dist/manifest/scan.d.ts

@@ -0,0 +1,19 @@
+import type { Block } from "../engine/block/block.js";
+import type { Checkpoint } from "../engine/checkpoint/checkpoint.js";
+/** Every file under `dir` whose name matches, skipping `node_modules`, `dist` and `.git`. */
+export declare function walkDir(dir: string, pattern: RegExp): string[];
+/**
+ * Imports a project file. The file's mtime is part of the URL: Node caches an ESM import per specifier for the life of the
+ * process, so a long-running session reloading an edited Block would otherwise keep the first version.
+ */
+export declare function importFresh(filePath: string): Promise<Record<string, unknown>>;
+export type AnyBlock = Block<Checkpoint<string>, Checkpoint<string>> & {
+    description?: string;
+};
+export declare function isBlockLike(val: unknown): val is AnyBlock;
+export declare function isFlowLike(val: unknown): val is {
+    run: (...args: unknown[]) => Promise<unknown>;
+    blocks: () => unknown[];
+};
+/** The factory kind a Block was built with (`nav`, `page`, `assert`), or undefined for Methods and Effects. */
+export declare function blockKind(block: object): string | undefined;

package/dist/manifest/scan.js

@@ -0,0 +1,57 @@
+// The one place a project's files are walked and imported. Everything that needs the project's Blocks or Flows
+// (graph, check, map, auto, traverse, the runner) goes through here.
+import { readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+/** Every file under `dir` whose name matches, skipping `node_modules`, `dist` and `.git`. */
+export function walkDir(dir, pattern) {
+    const results = [];
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return results;
+    }
+    for (const entry of entries) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (entry.name === "node_modules" || entry.name === "dist" || entry.name === ".git")
+                continue;
+            results.push(...walkDir(full, pattern));
+        }
+        else if (pattern.test(entry.name)) {
+            results.push(full);
+        }
+    }
+    return results;
+}
+/**
+ * Imports a project file. The file's mtime is part of the URL: Node caches an ESM import per specifier for the life of the
+ * process, so a long-running session reloading an edited Block would otherwise keep the first version.
+ */
+export async function importFresh(filePath) {
+    const resolved = resolve(filePath);
+    const url = pathToFileURL(resolved);
+    url.searchParams.set("t", String(statSync(resolved).mtimeMs));
+    return (await import(url.href));
+}
+export function isBlockLike(val) {
+    if (val === null || typeof val !== "object")
+        return false;
+    const obj = val;
+    if (typeof obj.name !== "string")
+        return false;
+    const instruction = obj.instruction;
+    return instruction !== null && typeof instruction === "object" && typeof instruction?.act === "function";
+}
+export function isFlowLike(val) {
+    return (val !== null &&
+        typeof val === "object" &&
+        typeof val.run === "function" &&
+        typeof val.blocks === "function");
+}
+/** The factory kind a Block was built with (`nav`, `page`, `assert`), or undefined for Methods and Effects. */
+export function blockKind(block) {
+    return block.__waygraphKind;
+}

package/dist/{blocks-select.d.ts → manifest/select.d.ts}

@@ -6,6 +6,7 @@
  * - otherwise    -> bare token (flow export / checkpoint / block name) — caller decides
  */
 export type BlocksSelectKind = "regex" | "glob" | "bare";
+/** A parsed `--blocks` selector: which Blocks, by name, glob or file, a command should use. */
 export interface BlocksSelect {
     kind: BlocksSelectKind;
     /** Original token. */
@@ -16,9 +17,11 @@ export interface BlocksSelect {
 }
 /** True when the token is file-select (glob/regex), not a bare flow/checkpoint name. */
 export declare function isFileSelectToken(token: string): boolean;
+/** Parses a `--blocks` argument into a selector. */
 export declare function parseBlocksSelect(token: string): BlocksSelect;
 /** Glob → RegExp (simple: ** / * / ? only; no brace expansion). */
 export declare function globToRegExp(glob: string): RegExp;
+/** True when a Block name and file match a parsed `--blocks` selector. */
 export declare function matchBlocksSelect(select: BlocksSelect, opts: {
     relFile: string;
     blockName?: string;

package/dist/{blocks-select.js → manifest/select.js}

@@ -14,6 +14,7 @@ export function isFileSelectToken(token) {
     }
     return token.includes("*");
 }
+/** Parses a `--blocks` argument into a selector. */
 export function parseBlocksSelect(token) {
     const raw = token.trim();
     if (raw.length >= 2 && raw.startsWith("/") && raw.endsWith("/")) {
@@ -52,6 +53,7 @@ export function globToRegExp(glob) {
     }
     return new RegExp("^" + out + "$");
 }
+/** True when a Block name and file match a parsed `--blocks` selector. */
 export function matchBlocksSelect(select, opts) {
     const file = opts.relFile.replace(/\\/g, "/");
     const name = opts.blockName ?? "";

package/dist/manifest/source.d.ts

@@ -0,0 +1,23 @@
+import type { SourceFile } from "ts-morph";
+/** The file as it is on disk now. */
+export declare function parseSource(file: string): SourceFile;
+/** Names the file exports: `export const|let|var|function|class X`, and `export { X }`. */
+export declare function exportedNames(sf: SourceFile): string[];
+/** Every module the file imports or re-exports from, including dynamic `import("x")`. */
+export declare function importSpecifiers(sf: SourceFile): string[];
+/** Names imported from modules whose specifier passes `from`, in source order (the imported name, not an alias). */
+export declare function namedImportsFrom(sf: SourceFile, from: (specifier: string) => boolean): string[];
+/** The string literal at `argIndex` of every call whose callee text passes `callee`, in source order. */
+export declare function stringArgs(sf: SourceFile, callee: (text: string) => boolean, argIndex?: number): string[];
+/** A string property of the object literal passed to every matching call: `Trait.url({ pathname: "/x" })` -> "/x". */
+export declare function objectArgProperty(sf: SourceFile, callee: (text: string) => boolean, property: string): string[];
+/** Every string literal in the file (comments are not strings), with the property name it initializes, if any. */
+export declare function stringLiterals(sf: SourceFile): {
+    value: string;
+    property: string | undefined;
+}[];
+/** Every call in the file (comments and strings are not calls): its callee as written and whether its first argument is a string. */
+export declare function calls(sf: SourceFile): {
+    callee: string;
+    literalFirstArg: boolean;
+}[];

package/dist/manifest/source.js

@@ -0,0 +1,86 @@
+// Reads a TypeScript file's shape (its exports, imports, string arguments) from the AST (ts-morph), for the places that
+// need it without importing the file: `list`, `nav`, a flow file's export name, a map group's imports.
+import { readFileSync } from "node:fs";
+import { Node, Project, SyntaxKind } from "ts-morph";
+const project = new Project({ useInMemoryFileSystem: true, skipFileDependencyResolution: true });
+/** The file as it is on disk now. */
+export function parseSource(file) {
+    return project.createSourceFile(file.replace(/\\/g, "/").replace(/^[A-Za-z]:/, ""), readFileSync(file, "utf8"), { overwrite: true });
+}
+/** Names the file exports: `export const|let|var|function|class X`, and `export { X }`. */
+export function exportedNames(sf) {
+    const names = [];
+    for (const statement of sf.getStatements()) {
+        if (Node.isVariableStatement(statement) && statement.isExported())
+            names.push(...statement.getDeclarations().map((d) => d.getName()));
+        else if ((Node.isFunctionDeclaration(statement) || Node.isClassDeclaration(statement)) && statement.isExported() && statement.getName())
+            names.push(statement.getName());
+        else if (Node.isExportDeclaration(statement) && !statement.getModuleSpecifier())
+            names.push(...statement.getNamedExports().map((e) => e.getAliasNode()?.getText() ?? e.getName()));
+    }
+    return names;
+}
+/** Every module the file imports or re-exports from, including dynamic `import("x")`. */
+export function importSpecifiers(sf) {
+    const specs = [
+        ...sf.getImportDeclarations().map((d) => d.getModuleSpecifierValue()),
+        ...sf.getExportDeclarations().flatMap((d) => d.getModuleSpecifierValue() ?? []),
+    ];
+    for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+        const arg = call.getArguments()[0];
+        if (call.getExpression().getKind() === SyntaxKind.ImportKeyword && Node.isStringLiteral(arg))
+            specs.push(arg.getLiteralValue());
+    }
+    return specs;
+}
+/** Names imported from modules whose specifier passes `from`, in source order (the imported name, not an alias). */
+export function namedImportsFrom(sf, from) {
+    return sf
+        .getImportDeclarations()
+        .filter((d) => from(d.getModuleSpecifierValue()))
+        .flatMap((d) => d.getNamedImports().map((n) => n.getName()));
+}
+/** The string literal at `argIndex` of every call whose callee text passes `callee`, in source order. */
+export function stringArgs(sf, callee, argIndex = 0) {
+    const out = [];
+    for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+        if (!callee(call.getExpression().getText()))
+            continue;
+        const arg = call.getArguments()[argIndex];
+        if (Node.isStringLiteral(arg) || Node.isNoSubstitutionTemplateLiteral(arg))
+            out.push(arg.getLiteralValue());
+    }
+    return out;
+}
+/** A string property of the object literal passed to every matching call: `Trait.url({ pathname: "/x" })` -> "/x". */
+export function objectArgProperty(sf, callee, property) {
+    const out = [];
+    for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+        if (!callee(call.getExpression().getText()))
+            continue;
+        const arg = call.getArguments()[0];
+        const prop = Node.isObjectLiteralExpression(arg) ? arg.getProperty(property) : undefined;
+        const value = Node.isPropertyAssignment(prop) ? prop.getInitializer() : undefined;
+        if (Node.isStringLiteral(value) || Node.isNoSubstitutionTemplateLiteral(value))
+            out.push(value.getLiteralValue());
+    }
+    return out;
+}
+/** Every string literal in the file (comments are not strings), with the property name it initializes, if any. */
+export function stringLiterals(sf) {
+    const out = [];
+    for (const node of [...sf.getDescendantsOfKind(SyntaxKind.StringLiteral), ...sf.getDescendantsOfKind(SyntaxKind.NoSubstitutionTemplateLiteral)]) {
+        const parent = node.getParent();
+        if (Node.isImportDeclaration(parent) || Node.isExportDeclaration(parent))
+            continue;
+        out.push({ value: node.getLiteralValue(), property: Node.isPropertyAssignment(parent) && parent.getInitializer() === node ? parent.getName() : undefined });
+    }
+    return out;
+}
+/** Every call in the file (comments and strings are not calls): its callee as written and whether its first argument is a string. */
+export function calls(sf) {
+    return sf.getDescendantsOfKind(SyntaxKind.CallExpression).map((call) => {
+        const arg = call.getArguments()[0];
+        return { callee: call.getExpression().getText(), literalFirstArg: Node.isStringLiteral(arg) || Node.isTemplateExpression(arg) || Node.isNoSubstitutionTemplateLiteral(arg) };
+    });
+}

package/dist/runner/mode.d.ts

@@ -0,0 +1,71 @@
+import type { BrowserContext } from "@playwright/test";
+import type { Checkpoint } from "../engine/checkpoint/checkpoint.js";
+import type { EngineConfig } from "../engine/config.js";
+import type { MemPage } from "../engine/mem/mem.js";
+import type { DemoPace } from "../engine/stub/pace.js";
+import type { HighlightStyleDefaults } from "../engine/stub/ring.js";
+import type { WgPage } from "../demo/types.js";
+import type { SomeBlock } from "../engine/block/block.js";
+/** One Block to play, with what its flow says about it. */
+export interface PlayStep {
+    block: SomeBlock;
+    exportName: string;
+    /** The engine config of the flow it came from (its layouts apply when it runs). */
+    config: EngineConfig;
+    /** Set on a named flow's steps; ad hoc Block chains have no episodes. */
+    episodeNumber?: number | undefined;
+    episodeTitle?: string | undefined;
+    /** Clear cookies and storage before this step (a flow with `sessionReset`, chained after another). */
+    resetSession: boolean;
+    /** Seeds this segment's `--data` into mem; set on a segment's first step. */
+    seedMem?: (() => void) | undefined;
+    /** Set on a flow's last step when the flow is meant to fail (`map({ expectedFailure })`). */
+    expectedFailureReason?: string | undefined;
+    demoPace?: DemoPace | undefined;
+    highlightStyle?: HighlightStyleDefaults | undefined;
+    /** An inner step of an expanded fast-forward unit (`--ff-expand`). */
+    wasFastForward?: boolean | undefined;
+    ffSource?: string | undefined;
+}
+/** The browser everything plays in. */
+export interface PlaySession {
+    context: BrowserContext;
+    page: WgPage;
+    mem: MemPage;
+    baseURL: string | undefined;
+}
+/** How a step ended, for a mode's `failed` hook: it threw, or it landed on the branch its flow expects to fail on. */
+export type StepFailure = {
+    error: unknown;
+    result?: undefined;
+} | {
+    error?: undefined;
+    result: Checkpoint<string>;
+};
+export interface PlayOutcome {
+    ok: boolean;
+    result?: Checkpoint<string> | undefined;
+    /** The step that failed, when one did. */
+    failedAt?: {
+        index: number;
+        step: PlayStep;
+        error: unknown;
+    } | undefined;
+    /** Set when the run stopped where its flow expects to fail. */
+    expectedFailure?: {
+        step: PlayStep;
+        reason: string;
+    } | undefined;
+}
+/** A way of playing steps. Every hook is optional; with none, it is a plain Playwright run. */
+export interface Mode {
+    name: string;
+    begin?(steps: readonly PlayStep[]): Promise<void>;
+    /** After the page was reset between episodes. */
+    afterReset?(): Promise<void>;
+    before?(index: number): Promise<void>;
+    after?(index: number, result: Checkpoint<string>, ms: number): Promise<void>;
+    /** A step failed (or reached its expected failure): retry its episode, or stop. Without the hook: stop. */
+    failed?(index: number, failure: StepFailure, ms: number): Promise<"retry" | "stop">;
+    end?(outcome: PlayOutcome): Promise<void>;
+}

package/dist/runner/mode.js

@@ -0,0 +1 @@
+export {};

package/dist/runner/modes/branches.d.ts

@@ -0,0 +1,5 @@
+import type { MemPage } from "../../engine/mem/mem.js";
+import type { Flow } from "../../engine/flow/flow.js";
+import type { PlayOptions } from "../options.js";
+import type { Checkpoint } from "../../engine/checkpoint/checkpoint.js";
+export declare function playBranches(flows: readonly Flow<Checkpoint<string>>[], mem: MemPage, options: PlayOptions): Promise<void>;

package/dist/runner/modes/branches.js

@@ -0,0 +1,37 @@
+import { branchRoutes, runBranchRegression } from "../../engine/flow/branch-regression.js";
+import { extensionPathsFromEnv } from "../../runtime/browser.js";
+export async function playBranches(flows, mem, options) {
+    const flow = flows.length === 1 ? flows[0] : undefined;
+    if (!flow) {
+        console.error("waygraph run --all-branches: needs a single Flow reference (e.g. --blocks loginFlow), not a multi-segment chain spec - nothing else has one branch tree to explore.");
+        process.exitCode = 1;
+        return;
+    }
+    if (!branchRoutes(flow)) {
+        console.error("waygraph run --all-branches: this Flow was not built with MapBuilder.branch() - there is no branch tree to explore. Run it normally instead.");
+        process.exitCode = 1;
+        return;
+    }
+    if (extensionPathsFromEnv().length > 0) {
+        console.warn("waygraph run --all-branches: extensions are not loaded (branches run in cloned contexts)");
+    }
+    const { chromium } = await import("@playwright/test");
+    const browser = await chromium.launch({ headless: !options.headed });
+    try {
+        const context = await browser.newContext(options.baseURL ? { baseURL: options.baseURL } : undefined);
+        const results = await runBranchRegression(flow, context, mem, { cloneSession: !options.sharedSession });
+        for (const r of results) {
+            console.log(`waygraph run --all-branches: ${r.path || "(root)"} -> ${r.status}` +
+                (r.result ? ` (${JSON.stringify(r.result)})` : "") +
+                (r.error ? ` - ${r.error}` : ""));
+        }
+        const failed = results.filter((r) => r.status === "failed");
+        if (failed.length) {
+            console.error(`waygraph run --all-branches: ${failed.length}/${results.length} path(s) failed`);
+            process.exitCode = 1;
+        }
+    }
+    finally {
+        await browser.close();
+    }
+}

package/dist/runner/modes/demo.d.ts

@@ -0,0 +1,3 @@
+import type { Mode, PlaySession, PlayStep } from "../mode.js";
+import type { PlayOptions } from "../options.js";
+export declare function demoMode(session: PlaySession, steps: readonly PlayStep[], options: PlayOptions, beat: number): Promise<Mode>;