waygraph 0.15.54 → 0.16.0

package/dist/{traverse/run.js → live/traverse/traverse.js}

@@ -1,13 +1,16 @@
-import { Engine, start, end, locate } from "../core.js";
-import { MemPage } from "../mem-page.js";
-import { buildExploreContext, buildExploreMenu, } from "../session/auto-explore.js";
-import { defaultMemValueForKey } from "../session/auto-explore-run.js";
-import { resolveBaseUrl } from "../config.js";
+import { Engine } from "../../engine/engine.js";
+import { buildFlow } from "../../engine/flow/flow.js";
+import { MemPage } from "../../engine/mem/mem.js";
+import { buildExploreContext, buildExploreMenu, } from "../auto/explore.js";
+import { detectHere, memStubValue } from "../auto/auto.js";
+import { resolveBaseUrl } from "../../runtime/waygraph-config.js";
 import { EdgeLeaseCoordinator } from "./lease.js";
 import { buildCoverageReport, collectGraphEdgeKeys, defaultCoverageOutPath, formatCoverageLine, writeCoverageReport, } from "./coverage.js";
-import { chromiumExecutablePath } from "../browser.js";
+import { chromiumExecutablePath } from "../../runtime/browser.js";
+import { envFlag, envString } from "../../engine/env.js";
+import { ignorePageGone, ignoreTimeout } from "../../engine/page-gone.js";
 function seedMem(library, mem, dataJson) {
-    const raw = dataJson ?? process.env.WAYGRAPH_DATA ?? process.env.WAYGRAPH_AUTO_MEM;
+    const raw = dataJson ?? envString("WAYGRAPH_DATA") ?? envString("WAYGRAPH_AUTO_MEM");
     let envParsed = {};
     if (raw) {
         try {
@@ -25,7 +28,7 @@ function seedMem(library, mem, dataJson) {
                 mem.set(k, envParsed[k.name]);
                 continue;
             }
-            const def = defaultMemValueForKey(k.name);
+            const def = memStubValue(k);
             if (def !== undefined)
                 mem.set(k, def);
         }
@@ -36,12 +39,7 @@ function snapshotMem(library, mem) {
     for (const entry of library.values()) {
         for (const k of entry.block.requires ?? []) {
             if (mem.has(k) && !(k.name in out)) {
-                try {
-                    out[k.name] = mem.get(k);
-                }
-                catch {
-                    /* skip */
-                }
+                out[k.name] = mem.get(k);
             }
         }
     }
@@ -71,23 +69,8 @@ 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 flow = buildFlow([entry.block], engine.config);
     const BLOCK_TIMEOUT_MS = 45_000;
     let timer;
     try {
@@ -131,7 +114,7 @@ async function runTraverseWorker(opts) {
             if (page.isClosed()) {
                 page = await context.newPage();
                 if (startUrl) {
-                    await page.goto(startUrl, { waitUntil: "domcontentloaded" }).catch(() => { });
+                    await page.goto(startUrl, { waitUntil: "domcontentloaded" }).catch(ignorePageGone);
                 }
             }
             const detected = await detectHere(page, library.navBlocks);
@@ -238,8 +221,8 @@ export async function runTraverse(projectDir, options = {}) {
     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 ?? (await resolveBaseUrl(projectDir)) ?? process.env.WAYGRAPH_BASE_URL;
+    const headed = options.headed === true || envFlag("WAYGRAPH_HEADED");
+    const baseURL = options.baseURL ?? (await resolveBaseUrl(projectDir)) ?? envString("WAYGRAPH_BASE_URL");
     const startUrl = options.startUrl ?? baseURL;
     const minEdgeCoverage = options.minEdgeCoverage != null && Number.isFinite(options.minEdgeCoverage)
         ? options.minEdgeCoverage
@@ -253,7 +236,7 @@ export async function runTraverse(projectDir, options = {}) {
     const allEdgeKeys = collectGraphEdgeKeys(graph.edges);
     const leases = new EdgeLeaseCoordinator({ projectDir, persist: parallel > 1 });
     const engine = new Engine({ headless: !headed, slowMo: headed ? 100 : 0 });
-    if (process.env.WAYGRAPH_EXTENSIONS)
+    if (envString("WAYGRAPH_EXTENSIONS"))
         console.error("waygraph traverse: extensions are not loaded (workers use plain contexts)");
     const { chromium } = await import("@playwright/test");
     const executablePath = chromiumExecutablePath();
@@ -318,8 +301,8 @@ export async function runTraverse(projectDir, options = {}) {
             const mem = new MemPage();
             seedMem(library.byName, mem, options.data);
             if (startUrl) {
-                await page.goto(startUrl, { waitUntil: "domcontentloaded" }).catch(() => { });
-                await page.waitForLoadState("load").catch(() => { });
+                await page.goto(startUrl, { waitUntil: "domcontentloaded" }).catch(ignorePageGone);
+                await page.waitForLoadState("load").catch(ignoreTimeout);
             }
             const traverseId = options.traverseId ?? "traverse-1";
             const result = await runTraverseWorker({
@@ -342,7 +325,7 @@ export async function runTraverse(projectDir, options = {}) {
                 mem,
                 leases,
             });
-            await context.close().catch(() => { });
+            await context.close().catch(ignorePageGone);
             const coverageCode = emitCoverage([{ traverseId, result }]);
             if (result.exitCode !== 0)
                 return result.exitCode;
@@ -359,12 +342,12 @@ export async function runTraverse(projectDir, options = {}) {
         const bootMem = new MemPage();
         seedMem(library.byName, bootMem, options.data);
         if (startUrl) {
-            await bootPage.goto(startUrl, { waitUntil: "domcontentloaded" }).catch(() => { });
-            await bootPage.waitForLoadState("load").catch(() => { });
+            await bootPage.goto(startUrl, { waitUntil: "domcontentloaded" }).catch(ignorePageGone);
+            await bootPage.waitForLoadState("load").catch(ignoreTimeout);
         }
         const storageState = await bootContext.storageState();
         const memSnap = snapshotMem(library.byName, bootMem);
-        await bootContext.close().catch(() => { });
+        await bootContext.close().catch(ignorePageGone);
         console.error(`waygraph traverse: forked ${parallel} clone workers (storageState + mem snapshot)`);
         const workerMeta = await Promise.all(Array.from({ length: parallel }, async (_, i) => {
             const traverseId = `traverse-${i + 1}`;
@@ -379,7 +362,7 @@ export async function runTraverse(projectDir, options = {}) {
             const mem = new MemPage();
             restoreMem(library.byName, mem, memSnap, options.data);
             if (startUrl) {
-                await page.goto(startUrl, { waitUntil: "domcontentloaded" }).catch(() => { });
+                await page.goto(startUrl, { waitUntil: "domcontentloaded" }).catch(ignorePageGone);
             }
             try {
                 const result = await runTraverseWorker({
@@ -405,7 +388,7 @@ export async function runTraverse(projectDir, options = {}) {
                 return { traverseId, result };
             }
             finally {
-                await context.close().catch(() => { });
+                await context.close().catch(ignorePageGone);
             }
         }));
         const results = workerMeta.map((w) => w.result);
@@ -418,6 +401,6 @@ export async function runTraverse(projectDir, options = {}) {
         return coverageCode;
     }
     finally {
-        await browser.close().catch(() => { });
+        await browser.close().catch(ignorePageGone);
     }
 }

package/dist/manifest/manifest.d.ts

@@ -0,0 +1,52 @@
+import type { BlockKind, ProjectScan, ScanOptions } from "./project.js";
+export declare const MANIFEST_VERSION = 1;
+export interface ManifestBlock {
+    /** `file#exportName`, unique across the project. */
+    id: string;
+    name: string;
+    exportName: string;
+    kind: BlockKind;
+    description: string;
+    from: string[];
+    to: string[];
+    requires: string[];
+    file: string;
+    /** The `src/map/` group folder the Block lives in (e.g. `(external)/hoppscotch`), or the map package it came from. */
+    map?: string;
+}
+export interface ManifestFlow {
+    /** `file#exportName`. */
+    id: string;
+    exportName: string;
+    file: string;
+    /** The folders under `src/flows/` (the page or `(user-story)` it belongs to) and the file's name (the outcome). */
+    useCase: {
+        path: string[];
+        outcome: string;
+    };
+    /** Block names in run order, nested flows flattened. */
+    steps: string[];
+    settings: {
+        memStub?: true;
+        expectedFailure?: string;
+        sessionReset?: true;
+        demoPace?: unknown;
+    };
+}
+export interface Manifest {
+    version: number;
+    project: {
+        name: string;
+        dir: string;
+        waygraph: string;
+    };
+    checkpoints: string[];
+    maps: string[];
+    blocks: ManifestBlock[];
+    flows: ManifestFlow[];
+    skipped: ProjectScan["skipped"];
+}
+/** Builds the manifest from a scan. */
+export declare function manifestFromScan(scan: ProjectScan): Manifest;
+/** Scans the project and returns its manifest. */
+export declare function buildManifest(projectDir: string, opts?: ScanOptions): Promise<Manifest>;

package/dist/manifest/manifest.js

@@ -0,0 +1,93 @@
+// The manifest: everything a project defines, as plain JSON. `waygraph manifest` prints it; Waygraph UI and map packages
+// read it instead of importing the project.
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { scanProject } from "./project.js";
+export const MANIFEST_VERSION = 1;
+function packageVersion() {
+    try {
+        return JSON.parse(readFileSync(join(dirname(new URL(import.meta.url).pathname), "..", "..", "package.json"), "utf8")).version;
+    }
+    catch {
+        return "unknown";
+    }
+}
+function projectName(dir) {
+    try {
+        return JSON.parse(readFileSync(join(dir, "package.json"), "utf8")).name ?? dir;
+    }
+    catch {
+        return dir;
+    }
+}
+/** `(external)/hoppscotch` for `src/map/(external)/hoppscotch/_methods/x.block.ts`: the group plus its first folder. */
+function mapGroupOf(file) {
+    const parts = file.split(/[\\/]/);
+    const i = parts.indexOf("map");
+    if (i < 0 || parts[i - 1] !== "src")
+        return undefined;
+    const rest = parts.slice(i + 1, -1);
+    if (rest.length === 0)
+        return undefined;
+    return /^\(.*\)$/.test(rest[0]) && rest[1] && !rest[1].startsWith("_") ? `${rest[0]}/${rest[1]}` : rest[0];
+}
+function useCaseOf(file) {
+    const parts = file.split(/[\\/]/);
+    const i = parts.indexOf("flows");
+    const folders = i >= 0 ? parts.slice(i + 1, -1) : [];
+    return { path: folders, outcome: parts[parts.length - 1].replace(/\.flow\.ts$/, "") };
+}
+/** Builds the manifest from a scan. */
+export function manifestFromScan(scan) {
+    const checkpoints = new Set();
+    const maps = new Set();
+    const blocks = scan.blocks.map((b) => {
+        for (const t of [...b.from, ...b.to])
+            if (t !== "*")
+                checkpoints.add(t);
+        const map = b.map ?? mapGroupOf(b.file);
+        if (map)
+            maps.add(map);
+        return {
+            id: `${b.file}#${b.exportName}`,
+            name: b.name,
+            exportName: b.exportName,
+            kind: b.kind,
+            description: b.description,
+            from: b.from,
+            to: b.to,
+            requires: b.requires,
+            file: b.file,
+            ...(map ? { map } : {}),
+        };
+    });
+    const flows = scan.flows.map((f) => {
+        const flow = f.flow;
+        return {
+            id: `${f.file}#${f.exportName}`,
+            exportName: f.exportName,
+            file: f.file,
+            useCase: useCaseOf(f.file),
+            steps: flow.blocks().map((s) => s.name),
+            settings: {
+                ...(flow.memStub ? { memStub: true } : {}),
+                ...(flow.expectedFailureReason ? { expectedFailure: flow.expectedFailureReason } : {}),
+                ...(flow.resetSession ? { sessionReset: true } : {}),
+                ...(flow.demoPace !== undefined ? { demoPace: flow.demoPace } : {}),
+            },
+        };
+    });
+    return {
+        version: MANIFEST_VERSION,
+        project: { name: projectName(scan.projectDir), dir: scan.projectDir, waygraph: packageVersion() },
+        checkpoints: [...checkpoints].sort(),
+        maps: [...maps].sort(),
+        blocks,
+        flows,
+        skipped: scan.skipped,
+    };
+}
+/** Scans the project and returns its manifest. */
+export async function buildManifest(projectDir, opts = {}) {
+    return manifestFromScan(await scanProject(projectDir, opts));
+}

package/dist/manifest/map-imports.d.ts

@@ -0,0 +1,7 @@
+import type { MapGroup } from "./maps.js";
+export interface MapImportProblem {
+    file: string;
+    spec: string;
+}
+/** Imports in a group that reach outside it. */
+export declare function mapGroupImportProblems(group: MapGroup): MapImportProblem[];

package/dist/manifest/map-imports.js

@@ -0,0 +1,22 @@
+// The rule that makes a map group packable: its files import only waygraph, Playwright, `node:` modules and each other.
+import { dirname, resolve, sep } from "node:path";
+import { walkDir } from "./scan.js";
+import { importSpecifiers, parseSource } from "./source.js";
+const ALLOWED_BARE = /^(waygraph|@playwright\/test|playwright|playwright-core)(\/.*)?$|^node:/;
+/** Imports in a group that reach outside it. */
+export function mapGroupImportProblems(group) {
+    const problems = [];
+    for (const file of walkDir(group.dir, /\.ts$/)) {
+        for (const spec of importSpecifiers(parseSource(file))) {
+            if (spec.startsWith(".")) {
+                const target = resolve(dirname(file), spec);
+                if (target === group.dir || target.startsWith(group.dir + sep))
+                    continue;
+            }
+            else if (ALLOWED_BARE.test(spec))
+                continue;
+            problems.push({ file, spec });
+        }
+    }
+    return problems;
+}

package/dist/manifest/maps.d.ts

@@ -0,0 +1,33 @@
+export interface MapGroup {
+    /** Path under `src/map/`, e.g. `(external)/hoppscotch`. */
+    group: string;
+    dir: string;
+}
+/** Every packable group: a folder under `src/map/` with its own `_states.ts`. */
+export declare function mapGroups(projectDir: string): MapGroup[];
+/** Finds a group by its full path (`(external)/hoppscotch`) or its last folder (`hoppscotch`). */
+export declare function findMapGroup(projectDir: string, name: string): MapGroup | undefined;
+export interface MapPackageJson {
+    version: number;
+    name: string;
+    group: string;
+    checkpoints: string[];
+    blocks: {
+        name: string;
+        exportName: string;
+        kind: string;
+        from: string[];
+        to: string[];
+        requires: string[];
+        file: string;
+    }[];
+}
+export interface InstalledMapPackage {
+    name: string;
+    dir: string;
+    map: MapPackageJson;
+}
+/** Map packages the project depends on: dependencies whose root holds a `waygraph.map.json`. */
+export declare function installedMapPackages(projectDir: string): InstalledMapPackage[];
+/** The compiled Block files of an installed map package. */
+export declare function mapPackageBlockFiles(pkg: InstalledMapPackage): string[];

package/dist/manifest/maps.js

@@ -0,0 +1,62 @@
+// Map groups as packages. A group is a `src/map/` folder that owns its Checkpoints (`_states.ts`); it may import only
+// `waygraph`, Playwright, `node:` modules and its own files, so it can be packed (`waygraph map pack`) and installed in
+// another project, where the scanner finds it by its `waygraph.map.json`.
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { walkDir } from "./scan.js";
+/** Every packable group: a folder under `src/map/` with its own `_states.ts`. */
+export function mapGroups(projectDir) {
+    const mapRoot = join(resolve(projectDir), "src", "map");
+    if (!existsSync(mapRoot))
+        return [];
+    return walkDir(mapRoot, /^_states\.ts$/)
+        .map((f) => dirname(f))
+        .map((dir) => ({ group: relative(mapRoot, dir).split(sep).join("/"), dir }))
+        .sort((a, b) => a.group.localeCompare(b.group));
+}
+/** Finds a group by its full path (`(external)/hoppscotch`) or its last folder (`hoppscotch`). */
+export function findMapGroup(projectDir, name) {
+    const groups = mapGroups(projectDir);
+    return groups.find((g) => g.group === name) ?? groups.find((g) => g.group.split("/").pop() === name);
+}
+/** Map packages the project depends on: dependencies whose root holds a `waygraph.map.json`. */
+export function installedMapPackages(projectDir) {
+    let pkg;
+    try {
+        pkg = JSON.parse(readFileSync(join(projectDir, "package.json"), "utf8"));
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of Object.keys({ ...pkg.dependencies, ...pkg.devDependencies }).sort()) {
+        const dir = join(projectDir, "node_modules", name);
+        const file = join(dir, "waygraph.map.json");
+        if (!existsSync(file))
+            continue;
+        try {
+            out.push({ name, dir, map: JSON.parse(readFileSync(file, "utf8")) });
+        }
+        catch {
+            /* a broken waygraph.map.json is skipped, like a Block file that fails to import */
+        }
+    }
+    return out;
+}
+/** The compiled Block files of an installed map package. */
+export function mapPackageBlockFiles(pkg) {
+    const files = [];
+    const walk = (dir) => {
+        for (const name of readdirSync(dir)) {
+            const p = join(dir, name);
+            if (name === "node_modules")
+                continue;
+            if (statSync(p).isDirectory())
+                walk(p);
+            else if (/\.block\.js$/.test(name))
+                files.push(p);
+        }
+    };
+    walk(pkg.dir);
+    return files.sort();
+}

package/dist/manifest/pack.d.ts

@@ -0,0 +1,21 @@
+import type { MapImportProblem } from "./map-imports.js";
+export interface PackOptions {
+    /** Output folder. Default `.waygraph/packages/<group>`. */
+    out?: string | undefined;
+    /** Package name. Default `waygraph-map-<group>`. */
+    name?: string | undefined;
+    version?: string | undefined;
+}
+export type PackResult = {
+    ok: true;
+    name: string;
+    dir: string;
+    group: string;
+    blocks: number;
+} | {
+    ok: false;
+    reason: string;
+    problems?: MapImportProblem[];
+};
+/** Packs a map group (by `(external)/hoppscotch` or `hoppscotch`) into an installable package folder. */
+export declare function packMapGroup(projectDir: string, groupName: string, opts?: PackOptions): Promise<PackResult>;

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>;