waygraph 0.15.53 → 0.16.0

package/dist/cli/commands/run.js

@@ -0,0 +1,64 @@
+import { resolveBaseUrl } from "../../runtime/waygraph-config.js";
+import { applyDemoDefaults, applyRunFlags, parseRunFlags, resolveProjectDir, resolveSpec } from "../flags.js";
+import { runChain } from "../run-chain.js";
+import { resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { envFlag, envString, setEnv } from "../../engine/env.js";
+export async function runCase(args) {
+    const flags = parseRunFlags(args.slice(1), "run");
+    applyRunFlags(flags);
+    const spec = resolveSpec(flags);
+    if (!spec) {
+        console.error("waygraph run: missing flow/spec — e.g.\n" +
+            "  waygraph run src/flows/shop.flow.ts\n" +
+            "  waygraph run --blocks shopFlow\n" +
+            "  waygraph list   # file → export map\n" +
+            "  Flags: --blocks --data --mem-stub --non-headless --video [dir] --step/--no-step");
+        process.exit(1);
+    }
+    const proj = flags.blocks
+        ? resolveProjectDir(flags, 0)
+        : resolve(flags.positionals[1] ?? process.cwd());
+    if (!existsSync(proj)) {
+        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, spec);
+    return;
+}
+export async function demoCase(args) {
+    const flags = parseRunFlags(args.slice(1), "demo");
+    applyRunFlags(flags, { allowAutoPlayVideo: true, allowDemoUi: true });
+    const spec = resolveSpec(flags);
+    if (!spec) {
+        console.error("waygraph demo: missing flow/spec — e.g.\n" +
+            "  waygraph demo src/flows/shop.flow.ts\n" +
+            "  waygraph demo --blocks shopFlow\n" +
+            "  Flags: --blocks --data --mem-stub --auto-next --fast --full --mini --ff-expand --ff-disabled --auto-play-video --title --base-url --video");
+        process.exit(1);
+    }
+    const proj = flags.blocks
+        ? resolveProjectDir(flags, 0)
+        : resolve(flags.positionals[1] ?? process.cwd());
+    if (!existsSync(proj)) {
+        console.error(`waygraph: no such directory: ${proj}`);
+        process.exit(1);
+    }
+    if (flags.step === undefined && envString("WAYGRAPH_STEP") === undefined) {
+        setEnv("WAYGRAPH_STEP", "1");
+    }
+    await applyDemoDefaults(proj);
+    console.error(`waygraph demo: STEP=${envFlag("WAYGRAPH_STEP") ? "on" : "off"}` +
+        ` AUTO_NEXT=${envFlag("WAYGRAPH_AUTOPLAY") ? "on" : "off"}` +
+        ` HEADED=${envString("WAYGRAPH_HEADED") === "0" ? "off" : "on"}` +
+        ` BASE_URL=${envString("WAYGRAPH_BASE_URL") ?? "(unset)"}` +
+        (envString("WAYGRAPH_VIDEO") ? ` VIDEO=${envString("WAYGRAPH_VIDEO")}` : "") +
+        (envString("WAYGRAPH_TITLE") ? ` TITLE=${JSON.stringify(envString("WAYGRAPH_TITLE"))}` : ""));
+    await runChain(proj, spec);
+    return;
+}

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

@@ -1,25 +1,35 @@
-// Split out of the former 8,700-line cli.ts (see src/ARCHITECTURE.md). Behavior unchanged.
-import { printBrowserSessionsList, printBrowserUsage } from "../cli/usage.js";
-import { applyRunFlags, looksLikeFlowFileRef, parseRunFlags, resolveBaseUrl } from "../cli/flags.js";
-import { runChain } from "../cli/run-chain.js";
-import { runChainAuto } from "./check.js";
+import { resolveBaseUrl } from "../../runtime/waygraph-config.js";
+import { printBrowserSessionsList, printBrowserUsage } from "../usage.js";
+import { applyRunFlags, looksLikeFlowFileRef, parseRunFlags } from "../flags.js";
+import { runChain } from "../run-chain.js";
+import { runChainAuto } from "../run-chain.js";
 import { resolve } from "node:path";
-import { browserStart, listBrowserSessions, stopAllBrowserSessions, stopBrowserSession } from "../session/browser.js";
+import { browserStart } from "../../live/auto-session/start.js";
+import { listBrowserSessions, stopAllBrowserSessions, stopBrowserSession } from "../../live/auto-session/ipc.js";
 import { existsSync, statSync } from "node:fs";
-import { resolveInjectRoots } from "../session/block-inject.js";
-import { requestSession, resolveSessionMeta, runAttachLoop, runAutoServeCommand, spawnDetachedSession } from "../session/auto-session-ipc.js";
-import { pilotAttach, pilotStart } from "../session/pilot.js";
-import { parseHighlightShorthand } from "../highlights/shorthand.js";
-import { isFileSelectToken, parseBlocksSelect } from "../blocks-select.js";
-import { runAutoExplore } from "../session/auto-explore-run.js";
-import { discoverGraph, findOrphanBlocks, toMermaid } from "../analysis/graph.js";
+import { resolveInjectRoots } from "../../manifest/roots.js";
+import { requestSession, resolveSessionMeta, runAttachLoop, runAutoServeCommand } from "../../live/auto-session/ipc.js";
+import { pilotAttach, pilotStart } from "../../live/pilot/pilot.js";
+import { parseHighlightShorthand } from "../../demo/narration/shorthand.js";
+import { isFileSelectToken, parseBlocksSelect } from "../../manifest/select.js";
+import { runAutoExplore } from "../../live/auto/auto.js";
+import { discoverGraph, findOrphanBlocks, toMermaid } from "../../analysis/graph.js";
+import { envString, setEnv } from "../../engine/env.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" },
+};
 export async function sessionCase(args, command) {
     if (command === "browser") {
         const sub = args[1];
         if (sub === "sessions") {
-            const rest = args.slice(2);
-            const json = rest.includes("--json");
-            const positional = rest.filter((a) => a !== "--json");
+            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) {
@@ -55,14 +65,14 @@ export async function sessionCase(args, command) {
         }
         if (sub === "start" || sub.startsWith("-")) {
             const flagArgs = sub === "start" ? args.slice(2) : args.slice(1);
-            const flags = parseRunFlags(flagArgs);
+            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 ?? process.env.WAYGRAPH_BASE_URL ?? (await resolveBaseUrl(proj));
+            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({
@@ -111,9 +121,8 @@ export async function sessionCase(args, command) {
     }
     if (command === "pilot") {
         if (args[1] === "sessions") {
-            const rest = args.slice(2);
-            const json = rest.includes("--json");
-            const positional = rest.filter((a) => a !== "--json");
+            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) {
@@ -130,7 +139,7 @@ export async function sessionCase(args, command) {
                 console.error("waygraph pilot attach: usage: waygraph pilot attach <sessionId> [--inject …] [project]");
                 process.exit(1);
             }
-            const flags = parseRunFlags(args.slice(3));
+            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;
@@ -145,10 +154,10 @@ export async function sessionCase(args, command) {
         }
         if (args[1] === "start" || !args[1] || args[1].startsWith("-")) {
             const flagArgs = args[1] === "start" ? args.slice(2) : args.slice(1);
-            const flags = parseRunFlags(flagArgs);
+            const flags = parseRunFlags(flagArgs, "pilot");
             applyRunFlags(flags);
             const proj = resolve(flags.positionals[0] ?? process.cwd());
-            const baseURL = flags.baseUrl ?? process.env.WAYGRAPH_BASE_URL ?? (await resolveBaseUrl(proj));
+            const baseURL = flags.baseUrl ?? envString("WAYGRAPH_BASE_URL") ?? (await resolveBaseUrl(proj));
             try {
                 const result = await pilotStart({
                     projectDir: proj,
@@ -252,16 +261,14 @@ export async function sessionCase(args, command) {
             // 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;
-            for (let i = 4; i < args.length; i++) {
-                if (args[i] === "--timeout") {
-                    const raw = args[++i];
-                    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 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));
@@ -274,32 +281,22 @@ export async function sessionCase(args, command) {
             let mode;
             let selector;
             let depth;
-            for (let i = 0; i < domArgs.length; i++) {
-                const a = domArgs[i];
-                if (a === "--mode" || a.startsWith("--mode=")) {
-                    const v = a.startsWith("--mode=") ? a.slice("--mode=".length) : domArgs[++i];
-                    if (v !== "aria" && v !== "full") {
-                        console.error(`waygraph auto dom: --mode must be "aria" or "full", got "${v}"`);
-                        process.exit(1);
-                    }
-                    mode = v;
-                }
-                else if (a === "--selector" || a.startsWith("--selector=")) {
-                    selector = a.startsWith("--selector=") ? a.slice("--selector=".length) : domArgs[++i];
-                }
-                else if (a === "--depth" || a.startsWith("--depth=")) {
-                    const raw = a.startsWith("--depth=") ? a.slice("--depth=".length) : domArgs[++i];
-                    const n = Number(raw);
-                    if (!Number.isInteger(n) || n < 1) {
-                        console.error(`waygraph auto dom: --depth must be a positive integer, got "${raw}"`);
-                        process.exit(1);
-                    }
-                    depth = n;
+            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);
                 }
-                else {
-                    console.error(`waygraph auto dom: unrecognized argument "${a}"`);
+                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",
@@ -468,7 +465,7 @@ export async function sessionCase(args, command) {
             process.exitCode = 1;
         return;
     }
-    const flags = parseRunFlags(args.slice(1));
+    const flags = parseRunFlags(args.slice(1), command ?? "auto");
     applyRunFlags(flags);
     const mermaid = flags.mermaid === true;
     const mapOnly = command === "graph" || flags.map === true;
@@ -482,10 +479,10 @@ export async function sessionCase(args, command) {
             console.error(`waygraph: no such directory: ${proj}`);
             process.exit(1);
         }
-        if (!process.env.WAYGRAPH_BASE_URL) {
+        if (!envString("WAYGRAPH_BASE_URL")) {
             const resolved = await resolveBaseUrl(proj);
             if (resolved)
-                process.env.WAYGRAPH_BASE_URL = resolved;
+                setEnv("WAYGRAPH_BASE_URL", resolved);
         }
         await runChain(proj, firstPos);
         return;
@@ -502,29 +499,6 @@ export async function sessionCase(args, command) {
             "  or path-find: waygraph auto --blocks LoginPage OrderComplete");
         process.exit(1);
     }
-    // auto --cli --detach: start the explore session as a background socket
-    // server instead of blocking in the interactive loop. Session control
-    // only applies to --cli (spec: "Headful mode is unaffected").
-    if (command === "auto" && flags.detach) {
-        if (!cliPicker) {
-            console.error("waygraph auto --detach requires --cli (headful has no session control)");
-            process.exit(1);
-        }
-        const baseURL = flags.baseUrl ?? process.env.WAYGRAPH_BASE_URL ?? (await resolveBaseUrl(proj));
-        try {
-            const meta = await spawnDetachedSession({
-                projectDir: proj,
-                ...(baseURL ? { baseURL } : {}),
-                ...(flags.nonHeadless ? { headless: false } : {}),
-            });
-            console.log(JSON.stringify({ sessionId: meta.sessionId, socketPath: meta.socketPath, headless: meta.headless }));
-        }
-        catch (err) {
-            console.error(`waygraph auto --detach: ${err instanceof Error ? err.message : String(err)}`);
-            process.exit(1);
-        }
-        return;
-    }
     // 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)) {
@@ -535,7 +509,7 @@ export async function sessionCase(args, command) {
         }
         if (flags.blocks && isFileSelectToken(flags.blocks)) {
             const blocksSelect = parseBlocksSelect(flags.blocks);
-            const baseURL = flags.baseUrl ?? process.env.WAYGRAPH_BASE_URL ?? (await resolveBaseUrl(proj));
+            const baseURL = flags.baseUrl ?? envString("WAYGRAPH_BASE_URL") ?? (await resolveBaseUrl(proj));
             await runAutoExplore(proj, baseURL
                 ? { cli: cliPicker, baseURL, blocksSelect }
                 : { cli: cliPicker, blocksSelect });
@@ -565,20 +539,19 @@ export async function sessionCase(args, command) {
         }
         return;
     }
-    const baseURL = flags.baseUrl ?? process.env.WAYGRAPH_BASE_URL ?? (await resolveBaseUrl(proj));
+    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));
-    const sessionIdIdx = args.indexOf("--session-id");
-    const sessionId = sessionIdIdx >= 0 ? args[sessionIdIdx + 1] : undefined;
+    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 ?? process.env.WAYGRAPH_BASE_URL ?? (await resolveBaseUrl(proj));
+    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)

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 === "") {