waygraph 0.16.0 → 0.16.2

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/codemod-stubs.js

@@ -4,7 +4,9 @@
 // aliases (`banner`, `bannerPos`, `clearDevice`, `clearTodos`, `landscape`, `portrait`, `todoDockFull`) become the
 // names they stood for. A stub written as a slot map (`{ email: { selector, label } }`) becomes a function of
 // `ctx.ring` calls, and a stub set in a `define*Block({ ... })` (options or instruction) moves out to a chained
-// `.stubBefore(...)` on the Block. Works on the TypeScript AST (ts-morph).
+// `.stubBefore(...)` on the Block; a Block's `slides` become `ctx.slides(...)` in its chained `.stubAfter(...)`;
+// `ctx.highlights({ a: ring })` becomes one `ctx.ring("a", ring)` per ring; `narrate(locator, caption, action)` in an
+// `act` becomes the action, reported so the caption can move to a stubBefore ring. Works on the TypeScript AST (ts-morph).
 import { Node, SyntaxKind } from "ts-morph";
 const RENAMED = {
     banner: (a) => `title(${a.join(", ")})`,
@@ -127,7 +129,7 @@ function convertSlotMaps(sf) {
     }
     return changed;
 }
-/** `defineXBlock({ ..., stubBefore: fn })` (or in its instruction) -> `defineXBlock({ ... }).stubBefore(fn)`. */
+/** `defineXBlock({ ..., stubBefore: fn, slides })` (or in its instruction) -> `defineXBlock({ ... }).stubBefore(fn).stubAfter(slides)`. */
 function hoistDefinitionStubs(sf) {
     let changed = false;
     for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression).reverse()) {
@@ -141,9 +143,17 @@ function hoistDefinitionStubs(sf) {
         if (Node.isPropertyAssignment(instruction) && Node.isObjectLiteralExpression(instruction.getInitializer()))
             holders.push(instruction.getInitializer());
         const chained = [];
+        let slides;
         for (const holder of holders) {
             for (const prop of holder.getProperties()) {
                 const name = Node.isPropertyAssignment(prop) || Node.isMethodDeclaration(prop) ? prop.getName() : "";
+                if (name === "slides" && Node.isPropertyAssignment(prop)) {
+                    const init = prop.getInitializerOrThrow();
+                    // `slides: (out) => [...]` read the Checkpoint the step reached; in stubAfter that is ctx.out.
+                    slides = Node.isArrowFunction(init) || Node.isFunctionExpression(init) ? `(${init.getText()})(ctx.out!)` : init.getText();
+                    prop.remove();
+                    continue;
+                }
                 if (!PHASES.has(name))
                     continue;
                 let fn;
@@ -157,6 +167,15 @@ function hoistDefinitionStubs(sf) {
                 prop.remove();
             }
         }
+        if (slides !== undefined) {
+            const after = chained.findIndex((c) => c.startsWith(".stubAfter("));
+            if (after < 0)
+                chained.push(`.stubAfter((ctx) => ctx.slides(${slides}))`);
+            else {
+                const fn = chained[after].slice(".stubAfter(".length, -1);
+                chained[after] = `.stubAfter(async (ctx) => {\n  await (${fn})(ctx);\n  ctx.slides(${slides});\n})`;
+            }
+        }
         if (chained.length) {
             call.replaceWithText(call.getText() + chained.join(""));
             changed = true;
@@ -164,6 +183,71 @@ function hoistDefinitionStubs(sf) {
     }
     return changed;
 }
+/** `ctx.highlights({ a: ring, b: ring })` -> `ctx.ring("a", ring); ctx.ring("b", ring);`, one call at a time. */
+function convertHighlights(sf, problems) {
+    let changed = false;
+    const skipped = new Set();
+    for (;;) {
+        // Raw text replacement forgets the file's nodes, so look the next call up again each time.
+        const statement = sf.getDescendantsOfKind(SyntaxKind.ExpressionStatement).find((st) => {
+            const c = ctxCall(st);
+            return c && c.method === "highlights" && !skipped.has(st.getStart()) && isStubCtx(c.call, c.receiver);
+        });
+        if (!statement)
+            return changed;
+        const c = ctxCall(statement);
+        const map = c.call.getArguments()[0];
+        if (!Node.isObjectLiteralExpression(map)) {
+            problems.push({ line: c.call.getStartLineNumber(), reason: "ctx.highlights(...) was removed and its argument is not an object literal: call ctx.ring(id, ring) for each ring" });
+            skipped.add(statement.getStart());
+            continue;
+        }
+        // Each ring keeps its own lines, moved to the statement's indent (replaceWithText would re-indent them).
+        const column = (n) => n.getStart() - n.getStartLinePos();
+        const indent = " ".repeat(column(statement));
+        const rings = map.getProperties().flatMap((p) => {
+            if (!Node.isPropertyAssignment(p))
+                return [];
+            const from = column(p);
+            const value = p.getInitializerOrThrow().getText().split("\n").map((l, n) => (n === 0 ? l : indent + l.slice(Math.min(from, l.search(/\S|$/))))).join("\n");
+            return [`${c.receiver}.ring(${JSON.stringify(p.getName().replace(/^["']|["']$/g, ""))}, ${value});`];
+        });
+        sf.replaceText([statement.getStart(), statement.getEnd()], rings.join("\n" + indent));
+        changed = true;
+    }
+}
+/**
+ * `narrate(locator, caption, () => action)` in an `act` -> just the action. The caption was narration inside the
+ * Block; it belongs in a `stubBefore` ring where the flow uses the Block, which the codemod can't place, so it is
+ * reported.
+ */
+function unwrapNarrate(sf, problems) {
+    let changed = false;
+    for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression).reverse()) {
+        if (call.wasForgotten() || call.getExpression().getText() !== "narrate" || call.getArguments().length !== 3)
+            continue;
+        const [, captionNode, action] = call.getArguments();
+        const caption = captionNode.getText();
+        const line = call.getStartLineNumber();
+        let body = `(${action.getText()})()`;
+        if (Node.isArrowFunction(action) && !Node.isBlock(action.getBody()))
+            body = action.getBody().getText();
+        call.replaceWithText(body);
+        problems.push({ line, reason: `narrate(...) was removed; its caption ${caption} is gone: ring the element in a stubBefore where the flow uses this Block` });
+        changed = true;
+    }
+    if (changed) {
+        for (const decl of sf.getImportDeclarations()) {
+            const spec = decl.getNamedImports().find((n) => n.getName() === "narrate");
+            if (!spec)
+                continue;
+            spec.remove();
+            if (decl.getNamedImports().length === 0 && !decl.getDefaultImport() && !decl.getNamespaceImport())
+                decl.remove();
+        }
+    }
+    return changed;
+}
 /** Rewrites the old stub forms in every file; returns the files it changed and the calls left for a person. */
 export function convertStubs(project) {
     const changed = [];
@@ -171,6 +255,10 @@ export function convertStubs(project) {
     for (const sf of project.getSourceFiles()) {
         const left = [];
         let touched = hoistDefinitionStubs(sf);
+        if (unwrapNarrate(sf, left))
+            touched = true;
+        if (convertHighlights(sf, left))
+            touched = true;
         if (convertSlotMaps(sf))
             touched = true;
         for (const block of sf.getDescendantsOfKind(SyntaxKind.Block).reverse()) {

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