waygraph 0.16.0 → 0.16.1

package/dist/cli/commands/browser.d.ts

@@ -0,0 +1,2 @@
+/** Runs a `browser` subcommand; false when it is a session op for session-ops.ts. */
+export declare function browserCase(args: string[]): Promise<boolean>;

package/dist/cli/commands/browser.js

@@ -0,0 +1,109 @@
+// `waygraph browser start | sessions | stop`: start a detached session, list them, stop them. The session ops
+// (send, status, ...) are session-ops.ts.
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { envString } from "../../engine/env.js";
+import { listBrowserSessions, stopAllBrowserSessions, stopBrowserSession } from "../../live/auto-session/files.js";
+import { runAttachLoop } from "../../live/auto-session/ipc.js";
+import { browserStart } from "../../live/auto-session/start.js";
+import { resolveInjectRoots } from "../../manifest/roots.js";
+import { resolveBaseUrl } from "../../runtime/waygraph-config.js";
+import { parseCommand } from "../args.js";
+import { applyRunFlags, parseRunFlags } from "../flags.js";
+import { printBrowserSessionsList, printBrowserUsage } from "../usage.js";
+/** Runs a `browser` subcommand; false when it is a session op for session-ops.ts. */
+export async function browserCase(args) {
+    const sub = args[1];
+    if (sub === "sessions") {
+        const { values, positionals: positional } = parseCommand("sessions", { json: { type: "boolean", help: "Machine-readable JSON" } }, args.slice(2));
+        const json = values.json === true;
+        const proj = resolve(positional[0] ?? process.cwd());
+        const sessions = listBrowserSessions(proj);
+        if (json) {
+            console.log(JSON.stringify(sessions, null, 2));
+        }
+        else {
+            printBrowserSessionsList(sessions, proj);
+        }
+        return true;
+    }
+    if (sub === "stop") {
+        const proj = resolve(args[3] ?? process.cwd());
+        const target = args[2];
+        if (!target) {
+            console.error("waygraph browser stop: usage: waygraph browser stop <sessionId|--all> [project]");
+            process.exit(1);
+        }
+        if (target === "--all") {
+            const n = stopAllBrowserSessions(proj);
+            console.log(JSON.stringify({ stopped: n, projectDir: proj }));
+            return true;
+        }
+        if (!stopBrowserSession(proj, target)) {
+            console.error(`waygraph browser stop: no such session "${target}"`);
+            process.exit(1);
+        }
+        console.log(JSON.stringify({ stopped: target }));
+        return true;
+    }
+    if (!sub) {
+        printBrowserUsage();
+        return true;
+    }
+    if (sub === "start" || sub.startsWith("-")) {
+        const flagArgs = sub === "start" ? args.slice(2) : args.slice(1);
+        const flags = parseRunFlags(flagArgs, "browser");
+        applyRunFlags(flags);
+        const proj = resolve(flags.positionals[0] ?? process.cwd());
+        if (!existsSync(proj)) {
+            console.error(`waygraph browser: no such directory: ${proj}`);
+            process.exit(1);
+        }
+        const baseURL = flags.baseUrl ?? envString("WAYGRAPH_BASE_URL") ?? (await resolveBaseUrl(proj));
+        try {
+            const inject = flags.inject?.length ? resolveInjectRoots(flags.inject, proj) : undefined;
+            const result = await browserStart({
+                projectDir: proj,
+                ...(inject?.length ? { inject } : {}),
+                ...(baseURL ? { baseURL } : {}),
+                ...(flags.goto
+                    ? { startUrl: flags.goto, skipInitialNavigation: false }
+                    : { skipInitialNavigation: flags.blank !== false }),
+                headless: flags.headlessBrowser === true,
+            });
+            console.log(JSON.stringify(result));
+            if (!result.headless) {
+                console.error(`Session ${result.sessionId} started. List all: waygraph browser sessions`);
+            }
+            if (flags.cli) {
+                await runAttachLoop(proj, result.sessionId);
+            }
+        }
+        catch (err) {
+            console.error(`waygraph browser start: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+        return true;
+    }
+    if (sub !== "send" &&
+        sub !== "status" &&
+        sub !== "attach" &&
+        sub !== "dom" &&
+        sub !== "trace" &&
+        sub !== "console" &&
+        sub !== "storage" &&
+        sub !== "upload" &&
+        sub !== "click" &&
+        sub !== "type" &&
+        sub !== "press" &&
+        sub !== "goto" &&
+        sub !== "reload" &&
+        sub !== "reach" &&
+        sub !== "resync" &&
+        sub !== "highlight") {
+        console.error("waygraph browser: unknown subcommand — run `waygraph browser` for usage");
+        printBrowserUsage();
+        process.exit(1);
+    }
+    return false;
+}

package/dist/cli/commands/pilot.d.ts

@@ -0,0 +1,2 @@
+/** Runs a `pilot` subcommand; false when it is a session op for session-ops.ts. */
+export declare function pilotCase(args: string[]): Promise<boolean>;

package/dist/cli/commands/pilot.js

@@ -0,0 +1,102 @@
+// `waygraph pilot start | sessions | attach`: a session plus the whole graph and a starting snapshot in one call.
+import { resolve } from "node:path";
+import { envString } from "../../engine/env.js";
+import { listBrowserSessions } from "../../live/auto-session/files.js";
+import { runAttachLoop } from "../../live/auto-session/ipc.js";
+import { pilotAttach, pilotStart } from "../../live/pilot/pilot.js";
+import { resolveInjectRoots } from "../../manifest/roots.js";
+import { resolveBaseUrl } from "../../runtime/waygraph-config.js";
+import { parseCommand } from "../args.js";
+import { applyRunFlags, parseRunFlags } from "../flags.js";
+import { printBrowserSessionsList } from "../usage.js";
+/** Runs a `pilot` subcommand; false when it is a session op for session-ops.ts. */
+export async function pilotCase(args) {
+    if (args[1] === "sessions") {
+        const { values, positionals: positional } = parseCommand("sessions", { json: { type: "boolean", help: "Machine-readable JSON" } }, args.slice(2));
+        const json = values.json === true;
+        const proj = resolve(positional[0] ?? process.cwd());
+        const sessions = listBrowserSessions(proj);
+        if (json) {
+            console.log(JSON.stringify(sessions, null, 2));
+        }
+        else {
+            printBrowserSessionsList(sessions, proj);
+        }
+        return true;
+    }
+    if (args[1] === "attach") {
+        const sessionId = args[2];
+        if (!sessionId) {
+            console.error("waygraph pilot attach: usage: waygraph pilot attach <sessionId> [--inject …] [project]");
+            process.exit(1);
+        }
+        const flags = parseRunFlags(args.slice(3), "pilot");
+        const proj = resolve(flags.positionals[0] ?? process.cwd());
+        try {
+            const inject = flags.inject?.length ? resolveInjectRoots(flags.inject, proj) : undefined;
+            const result = await pilotAttach(proj, sessionId, inject);
+            console.log(JSON.stringify(result));
+        }
+        catch (err) {
+            console.error(`waygraph pilot attach: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+        return true;
+    }
+    if (args[1] === "start" || !args[1] || args[1].startsWith("-")) {
+        const flagArgs = args[1] === "start" ? args.slice(2) : args.slice(1);
+        const flags = parseRunFlags(flagArgs, "pilot");
+        applyRunFlags(flags);
+        const proj = resolve(flags.positionals[0] ?? process.cwd());
+        const baseURL = flags.baseUrl ?? envString("WAYGRAPH_BASE_URL") ?? (await resolveBaseUrl(proj));
+        try {
+            const result = await pilotStart({
+                projectDir: proj,
+                ...(flags.inject?.length ? { injectTokens: flags.inject } : {}),
+                ...(baseURL ? { baseURL } : {}),
+                ...(flags.goto
+                    ? { startUrl: flags.goto, skipInitialNavigation: false }
+                    : flags.blank === true
+                        ? { skipInitialNavigation: true }
+                        : {}),
+                headless: flags.headlessBrowser === true,
+            });
+            console.log(JSON.stringify(result));
+            if (!result.headless) {
+                console.error(`Chromium window opened (session ${result.sessionId}). ` +
+                    `Terminal menu: waygraph pilot attach ${result.sessionId}`);
+            }
+            if (flags.cli) {
+                await runAttachLoop(proj, result.sessionId);
+            }
+        }
+        catch (err) {
+            console.error(`waygraph pilot start: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+        return true;
+    }
+    if (args[1] !== "send" &&
+        args[1] !== "status" &&
+        args[1] !== "dom" &&
+        args[1] !== "trace" &&
+        args[1] !== "console" &&
+        args[1] !== "storage" &&
+        args[1] !== "upload" &&
+        args[1] !== "click" &&
+        args[1] !== "type" &&
+        args[1] !== "press" &&
+        args[1] !== "goto" &&
+        args[1] !== "reload" &&
+        args[1] !== "reach" &&
+        args[1] !== "resync" &&
+        args[1] !== "highlight") {
+        console.error("waygraph pilot: usage:\n" +
+            "  waygraph pilot start [--inject …] [--goto <url>] [--headless] [--cli] [--base-url <url>] [project]\n" +
+            "  waygraph pilot sessions [project]   # list live browser sessions\n" +
+            "  waygraph pilot attach <sessionId>   # graph + snapshot for an existing session\n" +
+            "  waygraph pilot send|status|attach|highlight|… <sessionId> …  (controls browser — same as browser/auto)");
+        process.exit(1);
+    }
+    return false;
+}

package/dist/cli/commands/session-ops.d.ts

@@ -0,0 +1,3 @@
+/** Whether `sub` is a session op (`attach` is pilot's own subcommand, not an op, under `pilot`). */
+export declare function isSessionOp(command: string, sub: string | undefined): boolean;
+export declare function sessionOpCase(args: string[], command: string): Promise<void>;

package/dist/cli/commands/session-ops.js

@@ -0,0 +1,257 @@
+// Session ops against a running session by id: `waygraph auto|browser|pilot <op> <sessionId> ...` (send, status,
+// attach, dom, trace, console, storage, click, type, press, goto, upload, reload, reach, resync, highlight).
+import { resolve } from "node:path";
+import { parseHighlightShorthand } from "../../demo/narration/shorthand.js";
+import { resolveSessionMeta } from "../../live/auto-session/files.js";
+import { requestSession, runAttachLoop } from "../../live/auto-session/ipc.js";
+import { parseCommand } from "../args.js";
+const SEND_OPTIONS = {
+    timeout: { type: "string", value: "<ms>", help: "How long one Block may run (default 15000)" },
+};
+const DOM_OPTIONS = {
+    mode: { type: "string", value: "aria|full", help: "Accessibility tree (default) or the full DOM" },
+    selector: { type: "string", value: "<css>", help: "Only this element's subtree" },
+    depth: { type: "string", value: "N", help: "Levels to read" },
+};
+const OPS = new Set(["send", "status", "attach", "dom", "trace", "console", "storage", "upload", "click", "type", "press", "goto", "reload", "reach", "resync", "highlight"]);
+/** Whether `sub` is a session op (`attach` is pilot's own subcommand, not an op, under `pilot`). */
+export function isSessionOp(command, sub) {
+    return sub !== undefined && OPS.has(sub) && !(sub === "attach" && command === "pilot");
+}
+export async function sessionOpCase(args, command) {
+    const sub = args[1];
+    const sessionId = args[2];
+    if (!sessionId) {
+        console.error(`waygraph ${command} ${sub}: missing <sessionId>`);
+        process.exit(1);
+    }
+    const projHint = resolve(process.cwd());
+    const meta = resolveSessionMeta(sessionId, projHint);
+    if (!meta) {
+        console.error(`waygraph ${command} ${sub}: no such session "${sessionId}" — ` +
+            "wrong directory? run `waygraph pilot sessions` from the project that started it");
+        process.exit(1);
+    }
+    const proj = meta.projectDir;
+    if (sub === "attach") {
+        await runAttachLoop(proj, sessionId);
+        return;
+    }
+    if (sub === "send") {
+        const pick = args[3];
+        if (pick === undefined) {
+            console.error('waygraph auto send: usage: waygraph auto send <sessionId> "<pick>" [--timeout <ms>]');
+            process.exit(1);
+        }
+        // Real, direct need found live: a single Block can legitimately
+        // run a genuinely slow real interaction (e.g. a multi-step mouse
+        // drag) that exceeds the 15s default - same reasoning `auto
+        // reach` already gets a 90s default for (multiple Blocks in one
+        // call). Unlike reach, send has no way to know ahead of time
+        // whether the ONE Block it's running is fast or slow, so this is
+        // opt-in via a flag rather than a raised default.
+        let timeoutMs;
+        const raw = parseCommand("auto send", SEND_OPTIONS, args.slice(4)).values.timeout;
+        if (raw !== undefined) {
+            const n = Number(raw);
+            if (!Number.isFinite(n) || n <= 0) {
+                console.error(`waygraph auto send: --timeout must be a positive number of ms, got "${raw}"`);
+                process.exit(1);
+            }
+            timeoutMs = n;
+        }
+        const res = await requestSession(proj, sessionId, { op: "send", pick }, timeoutMs);
+        console.log(JSON.stringify(res));
+        if (!res.ok)
+            process.exitCode = 1;
+        return;
+    }
+    if (sub === "dom") {
+        const domArgs = args.slice(3);
+        let mode;
+        let selector;
+        let depth;
+        const dom = parseCommand("auto dom", DOM_OPTIONS, domArgs).values;
+        if (dom.mode !== undefined) {
+            if (dom.mode !== "aria" && dom.mode !== "full") {
+                console.error(`waygraph auto dom: --mode must be "aria" or "full", got "${dom.mode}"`);
+                process.exit(1);
+            }
+            mode = dom.mode;
+        }
+        selector = dom.selector;
+        if (dom.depth !== undefined) {
+            const n = Number(dom.depth);
+            if (!Number.isInteger(n) || n < 1) {
+                console.error(`waygraph auto dom: --depth must be a positive integer, got "${dom.depth}"`);
+                process.exit(1);
+            }
+            depth = n;
+        }
+        const res = await requestSession(proj, sessionId, {
+            op: "dom",
+            ...(mode ? { mode } : {}),
+            ...(selector ? { selector } : {}),
+            ...(depth !== undefined ? { depth } : {}),
+        });
+        console.log(JSON.stringify(res));
+        if (!res.ok)
+            process.exitCode = 1;
+        return;
+    }
+    if (sub === "trace") {
+        const res = await requestSession(proj, sessionId, { op: "trace" });
+        console.log(JSON.stringify(res));
+        if (!res.ok)
+            process.exitCode = 1;
+        return;
+    }
+    if (sub === "console") {
+        const res = await requestSession(proj, sessionId, { op: "console" });
+        console.log(JSON.stringify(res));
+        if (!res.ok)
+            process.exitCode = 1;
+        return;
+    }
+    if (sub === "storage") {
+        const res = await requestSession(proj, sessionId, { op: "storage" });
+        console.log(JSON.stringify(res));
+        if (!res.ok)
+            process.exitCode = 1;
+        return;
+    }
+    if (sub === "click") {
+        const selector = args[3];
+        if (selector === undefined) {
+            console.error('waygraph auto click: usage: waygraph auto click <sessionId> "<selector>"');
+            process.exit(1);
+        }
+        const res = await requestSession(proj, sessionId, { op: "click", selector });
+        console.log(JSON.stringify(res));
+        if (!res.ok)
+            process.exitCode = 1;
+        return;
+    }
+    if (sub === "type") {
+        const selector = args[3];
+        const text = args[4];
+        if (selector === undefined || text === undefined) {
+            console.error('waygraph auto type: usage: waygraph auto type <sessionId> "<selector>" "<text>"');
+            process.exit(1);
+        }
+        const res = await requestSession(proj, sessionId, { op: "type", selector, text });
+        console.log(JSON.stringify(res));
+        if (!res.ok)
+            process.exitCode = 1;
+        return;
+    }
+    if (sub === "press") {
+        const selector = args[3];
+        const key = args[4];
+        if (selector === undefined || key === undefined) {
+            console.error('waygraph auto press: usage: waygraph auto press <sessionId> "<selector>" <key>');
+            process.exit(1);
+        }
+        const res = await requestSession(proj, sessionId, { op: "press", selector, key });
+        console.log(JSON.stringify(res));
+        if (!res.ok)
+            process.exitCode = 1;
+        return;
+    }
+    if (sub === "goto") {
+        const url = args[3];
+        if (url === undefined) {
+            console.error("waygraph auto goto: usage: waygraph auto goto <sessionId> <url>");
+            process.exit(1);
+        }
+        const res = await requestSession(proj, sessionId, { op: "goto", url });
+        console.log(JSON.stringify(res));
+        if (!res.ok)
+            process.exitCode = 1;
+        return;
+    }
+    if (sub === "upload") {
+        const selector = args[3];
+        const kindOrPath = args[4];
+        if (selector === undefined || kindOrPath === undefined) {
+            console.error('waygraph auto upload: usage: waygraph auto upload <sessionId> "<selector>" <image|pdf|video|path-to-file>');
+            process.exit(1);
+        }
+        const stub = kindOrPath === "image" || kindOrPath === "pdf" || kindOrPath === "video"
+            ? { selector, stub: kindOrPath }
+            : { selector, stub: { filePath: resolve(process.cwd(), kindOrPath) } };
+        const res = await requestSession(proj, sessionId, { op: "upload", ...stub });
+        console.log(JSON.stringify(res));
+        if (!res.ok)
+            process.exitCode = 1;
+        return;
+    }
+    if (sub === "reload") {
+        const res = await requestSession(proj, sessionId, { op: "reload" });
+        console.log(JSON.stringify(res));
+        if (!res.ok)
+            process.exitCode = 1;
+        return;
+    }
+    if (sub === "reach") {
+        const checkpoint = args[3];
+        if (checkpoint === undefined) {
+            console.error("waygraph auto reach: usage: waygraph auto reach <sessionId> <Checkpoint>");
+            process.exit(1);
+        }
+        // Longer than every other op's default (15s): a real multi-step
+        // route runs several real Blocks in sequence server-side before
+        // responding - a legitimately slow single request, not a hang.
+        const res = await requestSession(proj, sessionId, { op: "reach", checkpoint }, 90_000);
+        console.log(JSON.stringify(res));
+        if (!res.ok)
+            process.exitCode = 1;
+        return;
+    }
+    if (sub === "resync") {
+        const res = await requestSession(proj, sessionId, { op: "resync" });
+        console.log(JSON.stringify(res));
+        if (!res.ok)
+            process.exitCode = 1;
+        return;
+    }
+    if (sub === "highlight") {
+        const raw = args[3];
+        if (raw === undefined) {
+            console.error(`waygraph ${command} highlight: usage:\n` +
+                `  waygraph ${command} highlight <sessionId> '{"rings":[{"selector":"#x","label":"X"}]}'\n` +
+                `  waygraph ${command} highlight <sessionId> "#x|X" (shorthand: <selector>|<label>[|<tone>], rings separated by ";")`);
+            process.exit(1);
+        }
+        let fixtures;
+        try {
+            fixtures = JSON.parse(raw);
+        }
+        catch (jsonErr) {
+            const shorthand = parseHighlightShorthand(raw);
+            if (shorthand.type === "error") {
+                console.error(`waygraph ${command} highlight: body is neither valid JSON (${jsonErr instanceof Error ? jsonErr.message : String(jsonErr)}) nor valid shorthand (${shorthand.reason})`);
+                process.exit(1);
+            }
+            fixtures = shorthand.fixtures;
+        }
+        if (fixtures.op !== undefined && fixtures.op !== "highlight") {
+            console.error(`waygraph ${command} highlight: do not set "op" (or set it to "highlight")`);
+            process.exit(1);
+        }
+        const { op: _ignore, ...rest } = fixtures;
+        const res = await requestSession(proj, sessionId, {
+            op: "highlight",
+            ...rest,
+        });
+        console.log(JSON.stringify(res));
+        if (!res.ok)
+            process.exitCode = 1;
+        return;
+    }
+    const res = await requestSession(proj, sessionId, { op: "status" });
+    console.log(JSON.stringify(res));
+    if (!res.ok)
+        process.exitCode = 1;
+    return;
+}