waygraph 0.15.54 → 0.16.1

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

package/dist/cli/commands/session.js

@@ -0,0 +1,132 @@
+// `waygraph auto` / `graph` / `browser` / `pilot`: hands `browser` and `pilot` subcommands and session ops to their
+// files, then runs the interactive explore (or the graph print) for a project; `__auto-serve` is the session child.
+import { existsSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { discoverGraph, findOrphanBlocks, toMermaid } from "../../analysis/graph.js";
+import { envString, setEnv } from "../../engine/env.js";
+import { runAutoServeCommand } from "../../live/auto-session/ipc.js";
+import { runAutoExplore } from "../../live/auto/auto.js";
+import { resolveInjectRoots } from "../../manifest/roots.js";
+import { isFileSelectToken, parseBlocksSelect } from "../../manifest/select.js";
+import { resolveBaseUrl } from "../../runtime/waygraph-config.js";
+import { applyRunFlags, looksLikeFlowFileRef, parseRunFlags } from "../flags.js";
+import { runChain, runChainAuto } from "../run-chain.js";
+import { browserCase } from "./browser.js";
+import { pilotCase } from "./pilot.js";
+import { isSessionOp, sessionOpCase } from "./session-ops.js";
+export async function sessionCase(args, command) {
+    if (command === "browser" && (await browserCase(args)))
+        return;
+    if (command === "pilot" && (await pilotCase(args)))
+        return;
+    // A session op (`auto|browser|pilot send <sessionId> ...`) runs against a running session, before any project path.
+    if ((command === "auto" || command === "browser" || command === "pilot") && isSessionOp(command, args[1])) {
+        await sessionOpCase(args, command);
+        return;
+    }
+    const flags = parseRunFlags(args.slice(1), command ?? "auto");
+    applyRunFlags(flags);
+    const mermaid = flags.mermaid === true;
+    const mapOnly = command === "graph" || flags.map === true;
+    const cliPicker = flags.cli === true;
+    const firstPos = flags.positionals[0];
+    // auto src/flows/shop.flow.ts → run that flow (same as `run`). Do not
+    // treat a .flow.ts path as a project directory (existsSync is true for files).
+    if (command === "auto" && firstPos && looksLikeFlowFileRef(firstPos) && !flags.blocksFromTo) {
+        const proj = resolve(process.cwd());
+        if (!existsSync(proj) || !statSync(proj).isDirectory()) {
+            console.error(`waygraph: no such directory: ${proj}`);
+            process.exit(1);
+        }
+        if (!envString("WAYGRAPH_BASE_URL")) {
+            const resolved = await resolveBaseUrl(proj);
+            if (resolved)
+                setEnv("WAYGRAPH_BASE_URL", resolved);
+        }
+        await runChain(proj, firstPos);
+        return;
+    }
+    const proj = resolve(firstPos ?? process.cwd());
+    if (!existsSync(proj)) {
+        console.error(`waygraph: no such directory: ${proj}`);
+        process.exit(1);
+    }
+    if (!statSync(proj).isDirectory()) {
+        console.error(`waygraph ${command}: "${firstPos}" is a file, not a project directory\n` +
+            "  run a flow:  waygraph auto src/flows/shop.flow.ts\n" +
+            "  or explore:  waygraph auto\n" +
+            "  or path-find: waygraph auto --blocks LoginPage OrderComplete");
+        process.exit(1);
+    }
+    // auto --blocks From To  (graph path-find + run)
+    // auto --blocks '/regex/' or '**/*.block.ts'  (Phase C file select → explore)
+    if (command === "auto" && (flags.blocksFromTo || flags.blocks)) {
+        if (flags.blocksFromTo) {
+            const [fromTag, toTag] = flags.blocksFromTo;
+            await runChainAuto(proj, fromTag, toTag);
+            return;
+        }
+        if (flags.blocks && isFileSelectToken(flags.blocks)) {
+            const blocksSelect = parseBlocksSelect(flags.blocks);
+            const baseURL = flags.baseUrl ?? envString("WAYGRAPH_BASE_URL") ?? (await resolveBaseUrl(proj));
+            await runAutoExplore(proj, baseURL
+                ? { cli: cliPicker, baseURL, blocksSelect }
+                : { cli: cliPicker, blocksSelect });
+            return;
+        }
+        console.error("waygraph auto --blocks expects <fromCheckpoint> <toCheckpoint>\n" +
+            "  or file select: --blocks '**/mailpit/**/*.block.ts' / --blocks '/mailpit/'\n" +
+            '  e.g. waygraph auto --blocks LoginPage OrderComplete\n' +
+            '  for a hand-named chain use: waygraph run --blocks "a then b"\n' +
+            "  or: waygraph auto src/flows/shop.flow.ts");
+        process.exit(1);
+    }
+    if (mapOnly || mermaid) {
+        const orphans = await findOrphanBlocks(proj);
+        const graph = await discoverGraph(proj);
+        if (mermaid) {
+            console.log(toMermaid(graph));
+        }
+        else {
+            console.log(JSON.stringify({ ...graph, orphans }, null, 2));
+        }
+        console.error(`waygraph graph: ${graph.nodes.length} node(s), ${graph.edges.length} edge(s), ` +
+            `${graph.skipped.length} Block(s) skipped (Out not resolvable), ` +
+            `${orphans.length} orphan Block(s)`);
+        if (orphans.length > 0) {
+            console.error("waygraph graph: orphan Blocks block auto --blocks path-find - wire each into a .flow.ts (waygraph check)");
+        }
+        return;
+    }
+    const baseURL = flags.baseUrl ?? envString("WAYGRAPH_BASE_URL") ?? (await resolveBaseUrl(proj));
+    await runAutoExplore(proj, baseURL ? { cli: cliPicker, baseURL } : { cli: cliPicker });
+    return;
+}
+export async function autoServeCase(args) {
+    const proj = resolve(args[1] ?? process.cwd());
+    const flags = parseRunFlags(args.slice(2), "__auto-serve");
+    const sessionId = flags.sessionId;
+    if (!sessionId) {
+        console.error("waygraph __auto-serve: missing --session-id");
+        process.exit(1);
+    }
+    const baseURL = flags.baseUrl ?? envString("WAYGRAPH_BASE_URL") ?? (await resolveBaseUrl(proj));
+    const inject = flags.inject?.length ? resolveInjectRoots(flags.inject, proj) : undefined;
+    let headless;
+    if (flags.headlessBrowser)
+        headless = true;
+    else if (flags.nonHeadless)
+        headless = false;
+    await runAutoServeCommand({
+        projectDir: proj,
+        ...(baseURL ? { baseURL } : {}),
+        ...(flags.goto
+            ? { startUrl: flags.goto, skipInitialNavigation: false }
+            : flags.blank === true
+                ? { skipInitialNavigation: true }
+                : {}),
+        ...(headless !== undefined ? { headless } : {}),
+        ...(inject?.length ? { inject } : {}),
+    }, sessionId);
+    return;
+}

package/dist/{commands → cli/commands}/test.js

@@ -1,9 +1,10 @@
-// Split out of the former 8,700-line cli.ts (see src/ARCHITECTURE.md). Behavior unchanged.
-import { configuredExtensions } from "../config.js";
-import { runInherited } from "../cli/util.js";
+import { configuredExtensions } from "../../runtime/waygraph-config.js";
+import { defaultRunLogDir } from "../../runtime/run-log.js";
+import { runInherited } from "../util.js";
 import { join } from "node:path";
 import { existsSync } from "node:fs";
-import { packageRoot } from "../cli/util.js";
+import { packageRoot } from "../util.js";
+import { envString, setEnv } from "../../engine/env.js";
 export async function testCase(args) {
     const rest = args.slice(1);
     const proj = process.cwd();
@@ -26,17 +27,13 @@ export async function testCase(args) {
         return;
     }
     const extensions = await configuredExtensions(proj);
+    if (envString("WAYGRAPH_RUN_LOG") === undefined)
+        setEnv("WAYGRAPH_RUN_LOG", defaultRunLogDir(proj));
     if (extensions.length > 0)
-        process.env.WAYGRAPH_EXTENSIONS = extensions.join(",");
-    // No playwright.config in the project: waygraph builds one from config/waygraph.config.ts.
-    const hasOwnConfig = ["ts", "mts", "js", "mjs", "cjs"].some((e) => existsSync(join(proj, `playwright.config.${e}`)));
-    if (hasOwnConfig) {
-        console.error("waygraph: playwright.config is deprecated - move its settings into config/waygraph.config.ts");
-    }
-    else {
-        process.env.WAYGRAPH_PROJECT_DIR = proj;
-    }
-    const configArgs = hasOwnConfig ? [] : ["-c", join(packageRoot(), "dist", "playwright.config.js")];
+        setEnv("WAYGRAPH_EXTENSIONS", extensions.join(","));
+    // The Playwright config is built from config/waygraph.config.ts; a project has none of its own.
+    setEnv("WAYGRAPH_PROJECT_DIR", proj);
+    const configArgs = ["-c", join(packageRoot(), "dist", "runtime", "playwright.config.js")];
     const wantsUi = rest[0] === "ui" || rest.includes("--ui");
     const forwarded = rest[0] === "ui" ? rest.slice(1) : rest;
     const pwArgs = wantsUi && !forwarded.includes("--ui")

package/dist/cli/commands/traverse.js

@@ -0,0 +1,105 @@
+import { resolve } from "node:path";
+import { existsSync, statSync } from "node:fs";
+import { parseBlocksSelect } from "../../manifest/select.js";
+import { parseMinEdgeCoverage } from "../../live/traverse/coverage.js";
+import { runTraverse } from "../../live/traverse/traverse.js";
+import { helpLines, parseCommand } from "../args.js";
+const OPTIONS = {
+    "blocks": { type: "string", value: "<glob|/regex/|substr>", help: "Phase C: filter *.block.ts discovery" },
+    "parallel": { type: "string", value: "N", help: "Phase D: N clone workers (default 1, max 4)" },
+    "session": { type: "string", value: "clone|inherit", help: "Phase D: default clone; inherit refused if parallel>1" },
+    "min-edge-coverage": { type: "string", value: "X", help: "Phase E: suite gate 0.8 | 80% | 80 (exit 2 if below)" },
+    "coverage-out": { type: "string", value: "PATH", help: "Phase E: write JSON (default .waygraph-traverse/coverage.json)" },
+    "no-coverage-report": { type: "boolean", help: "Phase E: print the Coverage line only (no JSON file)" },
+    "from": { type: "string", value: "<Checkpoint>", help: "Start checkpoint (optional)" },
+    "data": { type: "string", value: "'{...}'", help: "Mem seed JSON" },
+    "max-steps": { type: "string", value: "N", help: "Default 50 (per worker)" },
+    "max-visits": { type: "string", value: "N", help: "Per-node visit cap (default 2)" },
+    "max-visits-per-edge": { type: "string", value: "N", help: "Default 1" },
+    "non-headless": { type: "boolean", help: "Show the browser" },
+    "base-url": { type: "string", value: "<url>", help: "Base URL" },
+    "help": { type: "boolean", help: "This help" },
+};
+/** A number flag, or exit naming it. */
+function numberFlag(name, raw) {
+    if (raw === undefined)
+        return undefined;
+    const n = Number(raw);
+    if (!Number.isFinite(n)) {
+        console.error(`waygraph traverse: --${name} needs a number (got ${JSON.stringify(raw)})`);
+        process.exit(1);
+    }
+    return n;
+}
+export async function traverseCase(args) {
+    const { values: v, positionals } = parseCommand("traverse", OPTIONS, args.slice(1));
+    if (v.help) {
+        console.log(`waygraph traverse [project] [flags]
+
+Graph crawl (RFC Phase B-E). Walks unused legal edges until a leaf,
+budget kill, or first broken edge. --parallel N uses session clone + edge leases.
+
+${helpLines(OPTIONS)}
+
+Examples:
+  waygraph traverse --blocks '**/mailpit/**/*.block.ts'
+  waygraph traverse --parallel 2 --session clone --max-steps 20
+  waygraph traverse --min-edge-coverage 80% --coverage-out ./cov.json
+
+PASS:  [Reached Leaf Node[traverse-1] at=... steps=N]
+FAIL:  [Broke at edge[traverse-1] block=... from=... to=...]
+COVER: [Coverage edges=H/T ratio=R% min=M% PASS|FAIL]
+`);
+        process.exit(0);
+    }
+    if (v.session !== undefined && v.session !== "clone" && v.session !== "inherit") {
+        console.error('waygraph traverse: --session must be "clone" or "inherit"');
+        process.exit(1);
+    }
+    const session = v.session;
+    const projectDir = resolve(positionals[0] ?? process.cwd());
+    const from = v.from;
+    const data = v.data;
+    const maxSteps = numberFlag("max-steps", v["max-steps"]);
+    const maxVisits = numberFlag("max-visits", v["max-visits"]);
+    const maxEdge = numberFlag("max-visits-per-edge", v["max-visits-per-edge"]);
+    const parallel = numberFlag("parallel", v.parallel);
+    const headed = v["non-headless"] === true;
+    const baseUrl = v["base-url"];
+    const blocksFilter = v.blocks;
+    const minEdgeCoverageRaw = v["min-edge-coverage"];
+    const coverageOut = v["coverage-out"];
+    const noCoverageReport = v["no-coverage-report"] === true;
+    if (!existsSync(projectDir) || !statSync(projectDir).isDirectory()) {
+        console.error(`waygraph traverse: no such directory: ${projectDir}`);
+        process.exit(1);
+    }
+    const blocksSelect = blocksFilter
+        ? parseBlocksSelect(blocksFilter)
+        : undefined;
+    let minEdgeCoverage;
+    if (minEdgeCoverageRaw !== undefined) {
+        const parsed = parseMinEdgeCoverage(minEdgeCoverageRaw);
+        if (parsed === null) {
+            console.error(`waygraph traverse: --min-edge-coverage expects 0.8, 80%, or 80 (got ${JSON.stringify(minEdgeCoverageRaw)})`);
+            process.exit(1);
+        }
+        minEdgeCoverage = parsed;
+    }
+    const code = await runTraverse(projectDir, {
+        ...(from ? { from } : {}),
+        ...(data ? { data } : {}),
+        ...(maxSteps !== undefined ? { maxSteps } : {}),
+        ...(maxVisits !== undefined ? { maxVisitsPerNode: maxVisits } : {}),
+        ...(maxEdge !== undefined ? { maxVisitsPerEdge: maxEdge } : {}),
+        headed,
+        ...(baseUrl ? { baseURL: baseUrl } : {}),
+        ...(blocksSelect ? { blocksSelect } : {}),
+        ...(parallel !== undefined ? { parallel } : {}),
+        ...(session ? { session } : {}),
+        ...(minEdgeCoverage !== undefined ? { minEdgeCoverage } : {}),
+        ...(coverageOut ? { coverageOut: resolve(coverageOut) } : {}),
+        ...(noCoverageReport ? { noCoverageReport: true } : {}),
+    });
+    process.exit(code);
+}

package/dist/{commands → cli/commands}/try.js

@@ -1,12 +1,12 @@
-// Split out of the former 8,700-line cli.ts (see src/ARCHITECTURE.md). Behavior unchanged.
 import { join } from "node:path";
 import { cpSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { spawn } from "node:child_process";
-import { packageRoot, runInherited } from "../cli/util.js";
+import { packageRoot, runInherited } from "../util.js";
 import { tmpdir } from "node:os";
-import { runChain } from "../cli/run-chain.js";
-import { applyRunFlags, parseRunFlags } from "../cli/flags.js";
-import { resolveVideoDir } from "../video-dir.js";
+import { runChain } from "../run-chain.js";
+import { applyRunFlags, parseRunFlags } from "../flags.js";
+import { resolveVideoDir } from "../../runtime/video-dir.js";
+import { envString, setEnv } from "../../engine/env.js";
 /**
  * Runs a throwaway probe script rooted at `projectDir` - the exact same
  * directory the real demo files get copied into, so it resolves "waygraph"
@@ -167,7 +167,7 @@ async function prepareTryQuickstart(label) {
 }
 /**
  * `waygraph try demo` - copy a self-contained saucedemo project into a temp
- * dir (never the caller's cwd), run a chainFlow step demo (Sign In + Shop +
+ * dir (never the caller's cwd), run a chained-flows step demo (Sign In + Shop +
  * blocked Viewer), then run the headless Playwright test, and print where
  * everything lives.
  */
@@ -175,26 +175,32 @@ async function runTryDemo() {
     const destDir = await prepareTryQuickstart("waygraph-try-demo");
     if (!destDir)
         return;
-    process.env.WAYGRAPH_BASE_URL ??= "https://www.saucedemo.com";
-    process.env.WAYGRAPH_STEP ??= "1";
-    process.env.WAYGRAPH_AUTOPLAY ??= "0";
+    if (envString("WAYGRAPH_BASE_URL") === undefined)
+        setEnv("WAYGRAPH_BASE_URL", "https://www.saucedemo.com");
+    if (envString("WAYGRAPH_STEP") === undefined)
+        setEnv("WAYGRAPH_STEP", "1");
+    if (envString("WAYGRAPH_AUTOPLAY") === undefined)
+        setEnv("WAYGRAPH_AUTOPLAY", "0");
     // Explicit --no-step --video = unattended headless .webm only (the
     // documented cloud/CI recipe above) - nobody needs to watch a live
     // window for Playwright's own recordVideo to capture the right thing.
     // This must be decided BEFORE the headed default below, or the
     // unconditional "??=" there always wins and the documented recipe never
     // actually runs headless.
-    const unattendedVideo = Boolean(process.env.WAYGRAPH_VIDEO) && process.env.WAYGRAPH_STEP === "0";
+    const unattendedVideo = Boolean(envString("WAYGRAPH_VIDEO")) && envString("WAYGRAPH_STEP") === "0";
     if (unattendedVideo) {
-        process.env.WAYGRAPH_AUTOPLAY ??= "1";
-        process.env.WAYGRAPH_HEADED ??= "0";
+        if (envString("WAYGRAPH_AUTOPLAY") === undefined)
+            setEnv("WAYGRAPH_AUTOPLAY", "1");
+        if (envString("WAYGRAPH_HEADED") === undefined)
+            setEnv("WAYGRAPH_HEADED", "0");
     }
     else {
         // Default: headed stepper, manual Next. --video records that session
         // too (not a headless rush) as long as --step is still on.
-        process.env.WAYGRAPH_HEADED ??= "1";
+        if (envString("WAYGRAPH_HEADED") === undefined)
+            setEnv("WAYGRAPH_HEADED", "1");
     }
-    const videoTo = process.env.WAYGRAPH_VIDEO;
+    const videoTo = envString("WAYGRAPH_VIDEO");
     console.log(videoTo
         ? "waygraph try demo: step-through + record (Sign In -> Shop & Checkout -> blocked Viewer login) - click Next; video -> " +
             (videoTo === "1" ? await resolveVideoDir(destDir) : videoTo)
@@ -202,7 +208,7 @@ async function runTryDemo() {
     await runChain(destDir, TRY_DEMO_CHAIN);
     if (process.exitCode)
         return;
-    console.log("\nwaygraph try demo: running headless chainFlow test ...");
+    console.log("\nwaygraph try demo: running headless chained-flows test ...");
     const testCode = await runInherited("npm", ["test"], destDir);
     if (testCode !== 0) {
         process.exitCode = testCode;
@@ -219,13 +225,13 @@ async function runTryDemo() {
         `  ${loginFlowFile}\n` +
         `  ${shopFlowFile}\n` +
         `  ${viewerBlockedFlowFile}\n\n` +
-        "Headless chainFlow test (automated - no clicking):\n" +
+        "Headless chained-flows test (automated - no clicking):\n" +
         `  ${testFile}\n\n` +
         "Run again in that temp folder:\n" +
         `  cd ${destDir}\n` +
-        "  npm run demo    # step-through, manual Next (--step --no-autoplay)\n" +
+        "  npm run demo    # step-through, manual Next (--step --no-auto-next)\n" +
         "  npm run auto    # interactive explore (Effect Add/Remove, MemNav Open details)\n" +
-        "  npm test        # playwright chainFlow test\n\n" +
+        "  npm test        # playwright chained-flows test\n\n" +
         "Permanent full example in this package: examples/saucedemo\n" +
         "Keep a permanent scaffold in your tree: waygraph init my-app\n");
 }
@@ -244,7 +250,8 @@ async function runTryAuto(opts = { cli: false }) {
     const destDir = await prepareTryQuickstart("waygraph-try-auto");
     if (!destDir)
         return;
-    process.env.WAYGRAPH_BASE_URL ??= "https://www.saucedemo.com";
+    if (envString("WAYGRAPH_BASE_URL") === undefined)
+        setEnv("WAYGRAPH_BASE_URL", "https://www.saucedemo.com");
     const cli = opts.cli === true;
     console.log(cli
         ? "waygraph try auto: CLI explore on Sauce Demo (temp dir).\n" +
@@ -271,7 +278,7 @@ async function runTryAuto(opts = { cli: false }) {
         "Docs: https://deviate-dv8.github.io/waygraph/auto.html\n");
 }
 export async function tryCase(args) {
-    const flags = parseRunFlags(args.slice(1));
+    const flags = parseRunFlags(args.slice(1), "try");
     applyRunFlags(flags);
     const modeRaw = (flags.positionals[0] ?? "demo").toLowerCase();
     // auto:cli / --cli = CLI; bare try auto = headed panel
@@ -281,11 +288,8 @@ export async function tryCase(args) {
             ? "auto"
             : modeRaw;
     if (mode === "auto" || mode === "auto:cli") {
-        const cli = mode === "auto:cli" || flags.cli === true
-            ? true
-            : flags.headed === true || flags.nonHeadless === true
-                ? false
-                : false; // try auto default = headed
+        // try auto opens the headed browser panel; auto:cli / --cli is the terminal menu.
+        const cli = mode === "auto:cli" || flags.cli === true;
         await runTryAuto({ cli });
     }
     else if (mode === "demo" || mode === "") {