waygraph 0.15.44 → 0.15.45

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

@@ -0,0 +1,57 @@
+import type { Page } from "@playwright/test";
+import type { Block, Checkpoint, WaygraphInstanceOption } from "../types.js";
+import { type WaygraphGraph, type WaygraphEdge } from "../analysis/graph.js";
+export interface ExploreContextOpts {
+    blocksSelect?: import("../blocks-select.js").BlocksSelect;
+    /** Absolute paths of extra Block trees to merge (host projectDir is always first). */
+    inject?: string[];
+}
+export interface BlockEntry {
+    block: Block<Checkpoint<string>, Checkpoint<string>>;
+    exportName: string;
+    file: string;
+    kind: "nav" | "action";
+    description: string;
+}
+/**
+ * One menu row. Usually just a `WaygraphEdge` as discovered statically; when
+ * a Block declares `instanceOptions`, one `ExploreEdge` is produced per live
+ * option instead of a single generic row - `label` overrides the default
+ * "block -> checkpoint" text, and `instanceOption` is what the runner
+ * `mem.set()`s before running that row's Block.
+ */
+export interface ExploreEdge extends WaygraphEdge {
+    label?: string;
+    instanceOption?: WaygraphInstanceOption;
+}
+export interface ExploreSection {
+    title: string;
+    edges: ExploreEdge[];
+}
+/** Grouped menu for auto explore — `flat` preserves pick indices for CLI/headful. */
+export interface ExploreMenu {
+    here: string | null;
+    sections: ExploreSection[];
+    flat: ExploreEdge[];
+}
+/**
+ * Import every `*.block.ts` export keyed by runtime Block `.name`.
+ */
+export declare function loadBlockLibrary(projectDir: string, opts?: ExploreContextOpts): Promise<{
+    byName: Map<string, BlockEntry>;
+    navBlocks: BlockEntry[];
+}>;
+/**
+ * @deprecated Use {@link buildExploreMenu} — kept for unit tests.
+ */
+export declare function exploreChoices(graph: WaygraphGraph, here: string | null): WaygraphEdge[];
+/**
+ * Runtime-filtered menu: only Blocks that can run on the live page, grouped forward/back.
+ */
+export declare function buildExploreMenu(page: Page, graph: WaygraphGraph, library: {
+    byName: Map<string, BlockEntry>;
+}, here: string | null): Promise<ExploreMenu>;
+export declare function buildExploreContext(projectDir: string, opts?: ExploreContextOpts): Promise<{
+    graph: WaygraphGraph;
+    library: Awaited<ReturnType<typeof loadBlockLibrary>>;
+}>;

package/dist/session/auto-explore.js

@@ -0,0 +1,376 @@
+import { readdirSync, statSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { discoverGraph } from "../analysis/graph.js";
+import { exploreRoots, injectTaggedFile } from "./block-inject.js";
+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;
+}
+/**
+ * Real, confirmed bug this fixes: a bare `import(url.href)` is permanently
+ * cached by Node's ESM loader for the lifetime of the process, keyed on the
+ * exact specifier. `AutoSession.reloadLibrary()` exists specifically so a
+ * Block edited on disk mid-session takes effect without restarting the
+ * session - but a SECOND `reload` of a file already imported once in this
+ * process silently kept returning the FIRST version's content, no matter
+ * how many times the file changed on disk after that. A one-shot CLI
+ * process (`waygraph graph`, etc.) never hits this - it only ever imports
+ * each file once anyway - but a long-running `--detach` session calling
+ * `reloadLibrary()` repeatedly does.
+ *
+ * Fix: bust the cache with the file's own mtime as a query param - a
+ * genuinely changed file gets a new specifier (forcing a fresh import); an
+ * UNCHANGED file between two reloads keeps hitting the SAME specifier (no
+ * unbounded accumulation of dead module instances across many reloads).
+ */
+async function importModule(filePath) {
+    const resolved = resolve(filePath);
+    const url = new URL(`file://${resolved}`);
+    const mtimeMs = statSync(resolved).mtimeMs;
+    url.searchParams.set("t", String(mtimeMs));
+    return (await import(url.href));
+}
+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";
+}
+function isNavBlockMarked(val) {
+    const kind = val.__waygraphKind;
+    return kind === "nav" || kind === "page";
+}
+function isUrlNav(entry) {
+    return entry.block.__waygraphNavClick === undefined;
+}
+function isBackEdge(edge) {
+    return /^nav-back/.test(edge.block) || edge.block === "submit-logout";
+}
+async function navRunnable(page, entry) {
+    const click = entry.block.__waygraphNavClick;
+    if (click === undefined)
+        return true;
+    if (typeof click !== "string")
+        return false;
+    try {
+        // Short timeout: menu scan must stay snappy (many edges miss on this page).
+        return await page.locator(click).first().isVisible({ timeout: 150 });
+    }
+    catch {
+        return false;
+    }
+}
+async function wildcardActionRunnable(page, entry, here) {
+    if (here === null)
+        return false;
+    const name = entry.block.name;
+    // Bulk / non-instance * actions: show when matching live buttons exist.
+    try {
+        if (name === "add-all-to-cart" || name === "add-to-cart") {
+            return await page.locator('button[data-test^="add-to-cart-"]').first().isVisible({ timeout: 150 });
+        }
+        if (name === "remove-all-from-cart" || name === "remove-from-cart") {
+            return await page.locator('button[data-test^="remove-"]').first().isVisible({ timeout: 150 });
+        }
+    }
+    catch {
+        return false;
+    }
+    return false;
+}
+/**
+ * Import every `*.block.ts` export keyed by runtime Block `.name`.
+ */
+export async function loadBlockLibrary(projectDir, opts) {
+    const { matchBlocksSelect } = await import("../blocks-select.js");
+    const byName = new Map();
+    const navBlocks = [];
+    const navSeen = new Set();
+    const select = opts?.blocksSelect;
+    for (const root of exploreRoots(projectDir, opts?.inject)) {
+        for (const file of walkDir(root, /\.block\.ts$/)) {
+            const relFile = relative(root, file).replace(/\\/g, "/");
+            const taggedFile = injectTaggedFile(projectDir, root, relFile);
+            // 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);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                if (/second time|playwright/i.test(msg)) {
+                    console.error(`waygraph auto: skip ${relFile}: ${msg.split("\n")[0]}`);
+                }
+                continue;
+            }
+            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,
+                    exportName,
+                    file: taggedFile,
+                    kind,
+                    description: typeof exported.description === "string" ? exported.description : "",
+                };
+                if (byName.has(exported.name)) {
+                    console.error(`waygraph: inject skipped duplicate Block name "${exported.name}" (${taggedFile})`);
+                    continue;
+                }
+                byName.set(exported.name, entry);
+                if (kind === "nav" && !navSeen.has(exported.name)) {
+                    navSeen.add(exported.name);
+                    navBlocks.push(entry);
+                }
+            }
+        }
+    }
+    navBlocks.sort((a, b) => {
+        const aUrl = isUrlNav(a) ? 0 : 1;
+        const bUrl = isUrlNav(b) ? 0 : 1;
+        return aUrl - bUrl || a.block.name.localeCompare(b.block.name);
+    });
+    return { byName, navBlocks };
+}
+/**
+ * @deprecated Use {@link buildExploreMenu} — kept for unit tests.
+ */
+export function exploreChoices(graph, here) {
+    const seen = new Set();
+    const out = [];
+    for (const edge of graph.edges) {
+        if (here === null) {
+            if (edge.kind !== "nav")
+                continue;
+        }
+        else if (edge.from !== here && edge.from !== "*") {
+            continue;
+        }
+        if (seen.has(edge.block))
+            continue;
+        seen.add(edge.block);
+        out.push(edge);
+    }
+    return out.sort((a, b) => a.block.localeCompare(b.block));
+}
+/**
+ * Runtime-filtered menu: only Blocks that can run on the live page, grouped forward/back.
+ */
+export async function buildExploreMenu(page, graph, library, here) {
+    const forward = [];
+    const anywhere = [];
+    const navigate = [];
+    const back = [];
+    const seen = new Set();
+    // Union Out tags create duplicate edges for the same Block - cache instanceOptions
+    // so we only scrape the DOM once per Block name per menu build.
+    const instanceOptionsCache = new Map();
+    const push = (bucket, edge) => {
+        if (seen.has(edge.block))
+            return;
+        seen.add(edge.block);
+        bucket.push(edge);
+    };
+    async function loadInstanceOptions(entry) {
+        const fn = entry.block.instanceOptions;
+        if (!fn)
+            return [];
+        const cached = instanceOptionsCache.get(entry.block.name);
+        if (cached)
+            return cached;
+        let options = [];
+        try {
+            options = await fn(page);
+        }
+        catch {
+            options = [];
+        }
+        instanceOptionsCache.set(entry.block.name, options);
+        return options;
+    }
+    for (const edge of graph.edges) {
+        const entry = library.byName.get(edge.block);
+        if (!entry)
+            continue;
+        if (edge.kind === "action") {
+            if (here !== null && edge.from === here) {
+                if (entry.block.instanceOptions) {
+                    const options = await loadInstanceOptions(entry);
+                    for (const option of options) {
+                        const seenKey = `${edge.block}::${option.id}`;
+                        if (seen.has(seenKey))
+                            continue;
+                        seen.add(seenKey);
+                        (isBackEdge(edge) ? back : forward).push({
+                            ...edge,
+                            label: option.label,
+                            instanceOption: option,
+                        });
+                    }
+                }
+                else {
+                    push(isBackEdge(edge) ? back : forward, edge);
+                }
+            }
+            else if (here !== null && edge.from === "*") {
+                if (entry.block.instanceOptions) {
+                    const options = await loadInstanceOptions(entry);
+                    for (const option of options) {
+                        const seenKey = `${edge.block}::${option.id}`;
+                        if (seen.has(seenKey))
+                            continue;
+                        seen.add(seenKey);
+                        anywhere.push({ ...edge, label: option.label, instanceOption: option });
+                    }
+                }
+                else if (await wildcardActionRunnable(page, entry, here)) {
+                    const bulkLabel = {
+                        "add-all-to-cart": "Add all to cart",
+                        "remove-all-from-cart": "Remove all from cart",
+                    };
+                    const label = bulkLabel[entry.block.name] ?? (entry.description?.trim() || undefined);
+                    push(anywhere, label ? { ...edge, label } : edge);
+                }
+            }
+            continue;
+        }
+        // Nav: MemNavBlock (instanceOptions) expands one row per live target;
+        // plain NavBlock still uses click-visibility (navRunnable).
+        if (here !== null && (edge.from === here || edge.from === "*") && edge.to !== here) {
+            if (entry.block.instanceOptions) {
+                const options = await loadInstanceOptions(entry);
+                const bucket = isBackEdge(edge) ? back : navigate;
+                for (const option of options) {
+                    const seenKey = `${edge.block}::${option.id}`;
+                    if (seen.has(seenKey))
+                        continue;
+                    seen.add(seenKey);
+                    bucket.push({ ...edge, label: option.label, instanceOption: option });
+                }
+                continue;
+            }
+        }
+        if (!(await navRunnable(page, entry)))
+            continue;
+        if (here === null) {
+            // Bootstrap only: URL deep-links as "Start here". Click-nav needs a live
+            // control so it cannot seed an unknown page.
+            if (!isUrlNav(entry))
+                continue;
+            push(navigate, edge);
+            continue;
+        }
+        if (edge.to === here)
+            continue;
+        // Known screen: do NOT dump every defineNavBlock({ url }) under Navigate.
+        // Graph still marks NavBlocks from:"*" for pathfinding/traverse; auto menu
+        // only offers click-nav whose control is visible on this page (navRunnable).
+        // Otherwise LoginForm lists every app route + mailpit as if legal moves.
+        if (isUrlNav(entry))
+            continue;
+        if (isBackEdge(edge) && (edge.from === here || edge.from === "*")) {
+            push(back, edge);
+        }
+        else if (edge.from === here || edge.from === "*") {
+            push(navigate, edge);
+        }
+    }
+    const sections = [];
+    if (here === null) {
+        if (navigate.length > 0) {
+            sections.push({ title: "Start here", edges: navigate.sort((a, b) => a.block.localeCompare(b.block)) });
+        }
+    }
+    else {
+        if (forward.length > 0) {
+            sections.push({
+                title: `Methods from ${here}`,
+                edges: forward.sort((a, b) => a.block.localeCompare(b.block)),
+            });
+        }
+        if (anywhere.length > 0) {
+            sections.push({
+                title: "Also on this page",
+                edges: anywhere.sort((a, b) => (a.label ?? a.block).localeCompare(b.label ?? b.block)),
+            });
+        }
+        if (navigate.length > 0) {
+            sections.push({
+                title: "Navigate",
+                edges: navigate.sort((a, b) => (a.label ?? a.block).localeCompare(b.label ?? b.block)),
+            });
+        }
+        if (back.length > 0) {
+            sections.push({
+                title: "Go back",
+                edges: back.sort((a, b) => a.block.localeCompare(b.block)),
+            });
+        }
+    }
+    const flat = sections.flatMap((s) => s.edges);
+    // Stuck screen: graph knows actions from `here` but none made it into the menu
+    // (failed library load, empty instanceOptions, etc.). Surface them so LoginPage
+    // never shows a dead "No moves" when submit-login is in the graph.
+    if (here !== null && flat.length === 0) {
+        const rescue = [];
+        const rescued = new Set();
+        for (const edge of graph.edges) {
+            if (edge.kind !== "action" || edge.from !== here)
+                continue;
+            if (rescued.has(edge.block))
+                continue;
+            const entry = library.byName.get(edge.block);
+            if (!entry)
+                continue;
+            if (entry.block.instanceOptions)
+                continue; // still need live rows
+            rescued.add(edge.block);
+            rescue.push(edge);
+        }
+        if (rescue.length > 0) {
+            sections.push({
+                title: `Methods from ${here}`,
+                edges: rescue.sort((a, b) => a.block.localeCompare(b.block)),
+            });
+            return { here, sections, flat: sections.flatMap((s) => s.edges) };
+        }
+    }
+    return { here, sections, flat };
+}
+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, opts);
+    const graph = await discoverGraph(projectDir, opts);
+    return { graph, library };
+}

package/dist/session/auto-session-ipc.d.ts

@@ -0,0 +1,150 @@
+import { AutoSession, type AutoSessionInit, type SessionSnapshot, type InspectDomOptions, type DomSnapshot, type TraceStep, type ApplyPathResult, type ConsoleLogEntry, type StorageSnapshot, type StubFileKind } from "../auto-session.js";
+import type { PilotHighlightFixtures } from "../pilot-overlay.js";
+export type { PilotHighlightFixtures, PilotFixtureRing } from "../pilot-overlay.js";
+export interface SessionMeta {
+    sessionId: string;
+    socketPath: string;
+    pid: number;
+    projectDir: string;
+    startedAt: string;
+    headless: boolean;
+}
+export type StatusOrSendResponse = {
+    ok: true;
+    snapshot: SessionSnapshot;
+    quit: boolean;
+} | {
+    ok: false;
+    error: string;
+};
+export type DomResponse = {
+    ok: true;
+    snapshot: DomSnapshot;
+} | {
+    ok: false;
+    error: string;
+};
+export type TraceResponse = {
+    ok: true;
+    trace: TraceStep[];
+} | {
+    ok: false;
+    error: string;
+};
+export type ConsoleResponse = {
+    ok: true;
+    consoleLog: ConsoleLogEntry[];
+} | {
+    ok: false;
+    error: string;
+};
+export type StorageResponse = ({
+    ok: true;
+} & StorageSnapshot) | {
+    ok: false;
+    error: string;
+};
+export type ReachResponse = ApplyPathResult;
+export type HighlightResponse = {
+    ok: true;
+    painted: number;
+    missing: string[];
+    snapshot: SessionSnapshot;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function readSessionMeta(projectDir: string, sessionId: string): SessionMeta | null;
+/**
+ * Resolve session metadata from a project hint (cwd) or the global registry.
+ * Fixes "session unreachable" when the agent calls status/send from a different
+ * directory or pane than the one that ran `pilot start`.
+ */
+export declare function resolveSessionMeta(sessionId: string, projectDirHint?: string): SessionMeta | null;
+/**
+ * Client-side: sends one request to a running session and returns its
+ * response. Reports a stale/unreachable session as an error within
+ * `timeoutMs`, never hangs indefinitely.
+ */
+export declare function requestSession(projectDir: string, sessionId: string, request: {
+    op: "status";
+} | {
+    op: "send";
+    pick: string;
+} | {
+    op: "click";
+    selector: string;
+} | {
+    op: "type";
+    selector: string;
+    text: string;
+} | {
+    op: "press";
+    selector: string;
+    key: string;
+} | {
+    op: "goto";
+    url: string;
+} | {
+    op: "reload";
+} | {
+    op: "resync";
+} | {
+    op: "upload";
+    selector: string;
+    stub: StubFileKind | {
+        filePath: string;
+    };
+}, timeoutMs?: number): Promise<StatusOrSendResponse>;
+export declare function requestSession(projectDir: string, sessionId: string, request: {
+    op: "dom";
+} & InspectDomOptions, timeoutMs?: number): Promise<DomResponse>;
+export declare function requestSession(projectDir: string, sessionId: string, request: {
+    op: "trace";
+}, timeoutMs?: number): Promise<TraceResponse>;
+export declare function requestSession(projectDir: string, sessionId: string, request: {
+    op: "console";
+}, timeoutMs?: number): Promise<ConsoleResponse>;
+export declare function requestSession(projectDir: string, sessionId: string, request: {
+    op: "storage";
+}, timeoutMs?: number): Promise<StorageResponse>;
+export declare function requestSession(projectDir: string, sessionId: string, request: {
+    op: "reach";
+    checkpoint: string;
+}, timeoutMs?: number): Promise<ReachResponse>;
+export declare function requestSession(projectDir: string, sessionId: string, request: {
+    op: "highlight";
+} & PilotHighlightFixtures, timeoutMs?: number): Promise<HighlightResponse>;
+/**
+ * Server-side: runs `session` behind a unix socket at
+ * `.waygraph-auto/<sessionId>.sock`, writing session metadata only once the
+ * socket is actually listening (the metadata file's existence is the
+ * "session is ready" signal a spawning parent polls for). Requests are
+ * processed one at a time via a queue - Node's single-threaded event loop
+ * already prevents true parallelism, but two overlapping `await`-heavy
+ * handlers could still interleave against the same page/mem.
+ */
+export declare function serveSession(session: AutoSession, projectDir: string, sessionId: string, headless?: boolean): Promise<void>;
+/** Entry point for the hidden `__auto-serve` CLI command (runs in the detached child). */
+export declare function runAutoServeCommand(init: AutoSessionInit, sessionId: string): Promise<void>;
+/**
+ * Parent-side: spawns a detached background process running the same
+ * explore session as a socket server, waits for it to signal readiness (its
+ * metadata file appearing), and returns its identity. Recurses through the
+ * existing `bin/waygraph` launcher (same tsx/esm registration every other
+ * invocation already gets) with the hidden `__auto-serve` command, rather
+ * than re-implementing that resolution here.
+ */
+export declare function spawnDetachedSession(init: AutoSessionInit, readyTimeoutMs?: number): Promise<SessionMeta>;
+/** Stop one detached session (SIGTERM + cleanup metadata/socket). */
+export declare function stopBrowserSession(projectDir: string, sessionId: string): boolean;
+/** Stop every live session registered for a project. */
+export declare function stopAllBrowserSessions(projectDir: string): number;
+/** Live browser sessions for a project (metadata + socket + pid still present). */
+export declare function listBrowserSessions(projectDir: string): SessionMeta[];
+/**
+ * Client-only interactive loop against a running detached session - reopens
+ * the same rendering/parsing the foreground `--cli` loop uses, driven purely
+ * through `status`/`send`. No server-side support beyond those two ops.
+ */
+export declare function runAttachLoop(projectDir: string, sessionId: string): Promise<void>;