waygraph 0.15.53 → 0.16.0

package/dist/cli/flags.js

@@ -1,18 +1,54 @@
-// Split out of the former 8,700-line cli.ts (see src/ARCHITECTURE.md). Behavior unchanged.
 import { basename, relative, resolve } from "node:path";
-import { existsSync, readFileSync } from "node:fs";
-import { walkDir } from "./discover.js";
-import { loadWaygraphConfig, resolveBaseUrl } from "../config.js";
-function takeFlagValue(argv, i, a, flag) {
-    if (a.startsWith(flag + "=")) {
-        return { value: a.slice(flag.length + 1), nextI: i };
-    }
-    const v = argv[i + 1];
-    if (v === undefined || (v.startsWith("-") && !a.includes("="))) {
-        console.error(`waygraph: ${flag} needs a value`);
-        process.exit(1);
-    }
-    return { value: v, nextI: i + 1 };
+import { helpLines, parseCommand } from "./args.js";
+import { existsSync } from "node:fs";
+import { walkDir } from "../manifest/scan.js";
+import { exportedNames, parseSource } from "../manifest/source.js";
+import { loadWaygraphConfig, resolveBaseUrl } from "../runtime/waygraph-config.js";
+import { envFlag, envString, setEnv } from "../engine/env.js";
+/**
+ * Every flag the run-style commands take: `parseArgs` reads them from this table, and `usage.ts` prints the demo / run
+ * help from it, so the two can't drift. A flag not listed here is an error, not a stray positional.
+ */
+export const RUN_OPTIONS = {
+    "blocks": { type: "string", value: "<flow|file|spec>", help: "Flow export, .flow.ts path or \"a then b\" chain; auto: <From> <To> Checkpoints", for: ["demo", "run"] },
+    "data": { type: "string", value: "'{...}'", help: "Mem seed JSON (or inline flow({...}))", for: ["demo", "run"] },
+    "mem-stub": { type: "boolean", help: "Fill any requires key --data didn't cover from registerMemStub's registry", for: ["demo", "run"] },
+    "auto-next": { type: "boolean", help: "Auto-advance steps", for: ["demo"] },
+    "no-auto-next": { type: "boolean", help: "Wait for Next on every step (the default)", for: ["demo"] },
+    "fast": { type: "boolean", help: "Shorter auto-next / Next gates (keeps the smooth cursor)", for: ["demo"] },
+    "full": { type: "boolean", help: "Classic wrap-all block chips (default: carousel)", for: ["demo"] },
+    "mini": { type: "boolean", help: "Force the compact mini panel (Hide pill + Next)", for: ["demo"] },
+    "todo-left": { type: "boolean", help: "Floating checklist dock on the left (also ctx.todos(id, items, { pos }))", for: ["demo"] },
+    "todo-right": { type: "boolean", help: "Floating checklist dock on the right", for: ["demo"] },
+    "todo-full": { type: "boolean", help: "Full checklist: no compact / collision / behind-ring", for: ["demo"] },
+    "todo-smart": { type: "boolean", help: "Compact + collision + behind-ring (the default)", for: ["demo"] },
+    "ff-expand": { type: "boolean", help: "Expand fastForwardComposeBlock inners as separate steps", for: ["demo", "run"] },
+    "ff-disabled": { type: "boolean", help: "Dispute: expand FF; blitz kept on those inners", for: ["demo", "run"] },
+    "auto-play-video": { type: "boolean", help: "Unattended + recorded: --auto-next + --video (+ step); headless", for: ["demo"] },
+    "auto-play-video-head": { type: "boolean", help: "Same, but keep the browser visible (--non-headless)", for: ["demo"] },
+    "video": { type: "string", value: "[dir]", help: "Record .webm (default ~/Downloads/waygraph-videos/<project>, video.dir, WAYGRAPH_VIDEO_DIR)", for: ["demo", "run"] },
+    "video-viewport": { type: "string", value: "WxH", help: "Recording size (demo 1920x1080, run 1280x720)", for: ["demo", "run"] },
+    "step": { type: "boolean", help: "Step through with the overlay", for: ["run"] },
+    "no-step": { type: "boolean", help: "No step overlay (demo: plain run with narration off)", for: ["demo"] },
+    "all-branches": { type: "boolean", help: "Bare Flow ref only: explore every branch() path, cloning the session at each", for: ["run"] },
+    "shared-session": { type: "boolean", help: "With --all-branches: one shared session (follows only the live path)", for: ["run"] },
+    "non-headless": { type: "boolean", help: "Show the browser", for: ["demo", "run"] },
+    "title": { type: "string", value: "<text>", help: "Banner title", for: ["demo", "run"] },
+    "base-url": { type: "string", value: "<url>", help: "Base URL (beats WAYGRAPH_BASE_URL and the config)", for: ["demo", "run", "session"] },
+    "inject": { type: "string", multiple: true, value: "<preset|path>", help: "Merge an external Block library (repeatable)", for: ["session"] },
+    "goto": { type: "string", value: "<url>", help: "Navigate on start (disables the blank page)", for: ["session"] },
+    "blank": { type: "boolean", help: "Force about:blank on start (default)", for: ["session"] },
+    "headless": { type: "boolean", help: "Headless session (default: visible browser)", for: ["session"] },
+    "cli": { type: "boolean", help: "Terminal picker instead of the browser panel", for: ["session"] },
+    "json": { type: "boolean", help: "Machine-readable JSON", for: ["session"] },
+    "mermaid": { type: "boolean", help: "Print the graph as Mermaid" },
+    "map": { type: "boolean", help: "Print the map" },
+    "no-practices": { type: "boolean", help: "check / typecheck: skip bad-practice warnings" },
+    "session-id": { type: "string", help: "Internal: the id a detached session child serves (set by browser start)" },
+};
+/** The help lines for one command's options, from {@link RUN_OPTIONS}. */
+export function optionHelp(command, indent = 17) {
+    return helpLines(Object.fromEntries(Object.entries(RUN_OPTIONS).filter(([, o]) => "for" in o && o.for.includes(command))), indent);
 }
 /**
  * Looks like a Checkpoint tag for auto --blocks From To (PascalCase).
@@ -27,171 +63,94 @@ function looksLikeCheckpointArg(s) {
         return false;
     return /^[A-Z][A-Za-z0-9_]*$/.test(s);
 }
-/**
- * Pulls run/demo/auto flags out of argv. Unknown bare `--*` that are not
- * recognized stay as positionals only when they are project paths; known
- * explore flags (--cli/--mermaid/--map) are parsed here.
- */
-export function parseRunFlags(argv) {
-    const out = { positionals: [] };
-    for (let i = 0; i < argv.length; i++) {
-        const a = argv[i];
-        if (a === "--step") {
-            out.step = true;
-        }
-        else if (a === "--no-step") {
-            out.step = false;
-        }
-        else if (a === "--auto-next" || a === "--autoplay") {
-            out.autoplay = true;
-        }
-        else if (a === "--no-auto-next" || a === "--no-autoplay") {
-            out.autoplay = false;
-        }
-        else if (a === "--auto-play-video") {
-            out.autoPlayVideo = true;
-        }
-        else if (a === "--auto-play-video-head") {
-            out.autoPlayVideo = true;
-            out.nonHeadless = true;
-        }
-        else if (a === "--fast") {
-            out.fast = true;
-        }
-        else if (a === "--full") {
-            out.fullStepper = true;
-        }
-        else if (a === "--mini" || a === "--stepper-mini") {
-            out.miniStepper = true;
-        }
-        else if (a === "--todo-left") {
-            out.todoPos = "left";
-        }
-        else if (a === "--todo-right") {
-            out.todoPos = "right";
-        }
-        else if (a === "--todo-full" || a === "--no-todo-smart") {
-            out.todoUiFull = true;
-        }
-        else if (a === "--todo-smart") {
-            out.todoUiSmart = true;
-        }
-        else if (a === "--ff-expand") {
-            out.ffExpand = true;
-        }
-        else if (a === "--ff-disabled" || a === "--no-ff") {
-            out.ffDisabled = true;
-            out.ffExpand = true;
-        }
-        else if (a === "--non-headless") {
-            out.nonHeadless = true;
-        }
-        else if (a === "--headless") {
-            out.headlessBrowser = true;
-        }
-        else if (a === "--json") {
-            out.json = true;
-        }
-        else if (a === "--no-practices") {
-            out.noPractices = true;
-        }
-        else if (a === "--blank") {
-            out.blank = true;
-        }
-        else if (a === "--goto" || a.startsWith("--goto=")) {
-            const t = takeFlagValue(argv, i, a, "--goto");
-            out.goto = t.value;
-            i = t.nextI;
-        }
-        else if (a === "--inject" || a.startsWith("--inject=")) {
-            const t = takeFlagValue(argv, i, a, "--inject");
-            out.inject ??= [];
-            out.inject.push(t.value);
-            i = t.nextI;
-        }
-        else if (a === "--cli") {
-            out.cli = true;
-        }
-        else if (a === "--detach") {
-            out.detach = true;
-        }
-        else if (a === "--headed") {
-            out.headed = true;
-        }
-        else if (a === "--mermaid") {
-            out.mermaid = true;
-        }
-        else if (a === "--map") {
-            out.map = true;
-        }
-        else if (a === "--base-url" || a.startsWith("--base-url=")) {
-            const t = takeFlagValue(argv, i, a, "--base-url");
-            out.baseUrl = t.value;
-            i = t.nextI;
-        }
-        else if (a === "--title" || a.startsWith("--title=")) {
-            const t = takeFlagValue(argv, i, a, "--title");
-            out.title = t.value;
-            i = t.nextI;
-        }
-        else if (a === "--data" || a.startsWith("--data=")) {
-            const t = takeFlagValue(argv, i, a, "--data");
-            out.data = t.value;
-            i = t.nextI;
-        }
-        else if (a === "--mem-stub") {
-            out.memStub = true;
-        }
-        else if (a === "--all-branches") {
-            out.allBranches = true;
-        }
-        else if (a === "--shared-session") {
-            out.sharedSession = true;
-        }
-        else if (a === "--video" || a.startsWith("--video=")) {
-            if (a.startsWith("--video=")) {
-                out.video = a.slice("--video=".length);
-            }
-            else {
-                const v = argv[i + 1];
-                if (v === undefined || v.startsWith("-")) {
-                    out.video = "";
-                }
-                else {
-                    out.video = v;
-                    i++;
-                }
-            }
-        }
-        else if (a === "--video-viewport" || a.startsWith("--video-viewport=")) {
-            const t = takeFlagValue(argv, i, a, "--video-viewport");
-            out.videoViewport = t.value;
-            i = t.nextI;
-        }
-        else if (a === "--blocks" || a.startsWith("--blocks=")) {
-            if (a.startsWith("--blocks=")) {
-                out.blocks = a.slice("--blocks=".length);
-            }
-            else {
-                const v1 = argv[++i];
-                if (!v1 || v1.startsWith("-")) {
-                    console.error("waygraph: --blocks needs a flow/spec or <from> <to> checkpoints");
-                    process.exit(1);
-                }
-                const v2 = argv[i + 1];
-                if (v2 && looksLikeCheckpointArg(v1) && looksLikeCheckpointArg(v2)) {
-                    out.blocksFromTo = [v1, v2];
-                    i++;
-                }
-                else {
-                    out.blocks = v1;
-                }
-            }
-        }
-        else {
-            out.positionals.push(a);
-        }
-    }
+/** Reads run/demo/auto/session flags with `node:util`'s parseArgs; an unknown flag or a missing value exits with the reason. */
+export function parseRunFlags(argv, command) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        const forHelp = command === "demo" || command === "run" ? command : ["browser", "pilot", "auto"].includes(command) ? "session" : undefined;
+        console.log(`waygraph ${command} flags:\n${forHelp ? optionHelp(forHelp, 2) : helpLines(RUN_OPTIONS)}\n\nwaygraph --help lists every command.`);
+        process.exit(0);
+    }
+    // `--video` takes an optional folder: bare (end of args, or another flag next) means the default folder.
+    const args = argv.map((a, i) => (a === "--video" && (argv[i + 1] === undefined || argv[i + 1].startsWith("-")) ? "--video=" : a));
+    const parsed = parseCommand(command, RUN_OPTIONS, args);
+    const v = parsed.values;
+    const positionals = [...parsed.positionals];
+    const out = { positionals };
+    // `--blocks <From> <To>`: two Checkpoints in a row are a path to find, not a spec and a project path.
+    const blocksToken = parsed.tokens.find((t) => t.kind === "option" && t.name === "blocks" && !t.inlineValue);
+    const after = blocksToken && parsed.tokens.find((t) => t.kind === "positional" && t.index === blocksToken.index + 2);
+    if (v.blocks !== undefined && after?.kind === "positional" && looksLikeCheckpointArg(v.blocks) && looksLikeCheckpointArg(after.value)) {
+        out.blocksFromTo = [v.blocks, after.value];
+        positionals.splice(positionals.indexOf(after.value), 1);
+    }
+    else if (v.blocks !== undefined)
+        out.blocks = v.blocks;
+    if (v.step)
+        out.step = true;
+    if (v["no-step"])
+        out.step = false;
+    if (v["auto-next"])
+        out.autoplay = true;
+    if (v["no-auto-next"])
+        out.autoplay = false;
+    if (v["auto-play-video"] || v["auto-play-video-head"])
+        out.autoPlayVideo = true;
+    if (v["non-headless"] || v["auto-play-video-head"])
+        out.nonHeadless = true;
+    if (v.fast)
+        out.fast = true;
+    if (v.full)
+        out.fullStepper = true;
+    if (v.mini)
+        out.miniStepper = true;
+    if (v["todo-left"])
+        out.todoPos = "left";
+    if (v["todo-right"])
+        out.todoPos = "right";
+    if (v["todo-full"])
+        out.todoUiFull = true;
+    if (v["todo-smart"])
+        out.todoUiSmart = true;
+    if (v["ff-expand"] || v["ff-disabled"])
+        out.ffExpand = true;
+    if (v["ff-disabled"])
+        out.ffDisabled = true;
+    if (v.headless)
+        out.headlessBrowser = true;
+    if (v.json)
+        out.json = true;
+    if (v["no-practices"])
+        out.noPractices = true;
+    if (v["session-id"] !== undefined)
+        out.sessionId = v["session-id"];
+    if (v.blank)
+        out.blank = true;
+    if (v.goto !== undefined)
+        out.goto = v.goto;
+    if (v.inject !== undefined)
+        out.inject = [...v.inject];
+    if (v.cli)
+        out.cli = true;
+    if (v.mermaid)
+        out.mermaid = true;
+    if (v.map)
+        out.map = true;
+    if (v["base-url"] !== undefined)
+        out.baseUrl = v["base-url"];
+    if (v.title !== undefined)
+        out.title = v.title;
+    if (v.data !== undefined)
+        out.data = v.data;
+    if (v["mem-stub"])
+        out.memStub = true;
+    if (v["all-branches"])
+        out.allBranches = true;
+    if (v["shared-session"])
+        out.sharedSession = true;
+    if (v.video !== undefined)
+        out.video = v.video;
+    if (v["video-viewport"] !== undefined)
+        out.videoViewport = v["video-viewport"];
     return out;
 }
 /** Parses WAYGRAPH_VIDEO_VIEWPORT / --video-viewport: "1920x1080" or "1920,1080". */
@@ -226,9 +185,9 @@ export function applyRunFlags(flags, opts) {
         // capture the right thing. Headless by default; --non-headless (or the
         // --auto-play-video-head alias, parsed above) opts back into a
         // visible browser for someone who wants to watch it live too.
-        process.env.WAYGRAPH_STEP = "1";
-        if (!flags.nonHeadless && process.env.WAYGRAPH_HEADED === undefined) {
-            process.env.WAYGRAPH_HEADED = "0";
+        setEnv("WAYGRAPH_STEP", "1");
+        if (!flags.nonHeadless && envString("WAYGRAPH_HEADED") === undefined) {
+            setEnv("WAYGRAPH_HEADED", "0");
         }
     }
     if ((flags.fast || flags.fullStepper || flags.miniStepper || flags.todoPos || flags.todoUiFull || flags.todoUiSmart) &&
@@ -237,86 +196,79 @@ export function applyRunFlags(flags, opts) {
         process.exit(1);
     }
     if (flags.step === true) {
-        process.env.WAYGRAPH_STEP = "1";
-        process.env.WAYGRAPH_HEADED = "1";
+        setEnv("WAYGRAPH_STEP", "1");
+        setEnv("WAYGRAPH_HEADED", "1");
     }
     else if (flags.step === false) {
-        process.env.WAYGRAPH_STEP = "0";
+        setEnv("WAYGRAPH_STEP", "0");
     }
     if (flags.autoplay === true) {
-        process.env.WAYGRAPH_AUTOPLAY = "1";
+        setEnv("WAYGRAPH_AUTOPLAY", "1");
     }
     else if (flags.autoplay === false) {
-        process.env.WAYGRAPH_AUTOPLAY = "0";
+        setEnv("WAYGRAPH_AUTOPLAY", "0");
     }
     if (flags.nonHeadless) {
-        process.env.WAYGRAPH_HEADED = "1";
+        setEnv("WAYGRAPH_HEADED", "1");
     }
     // Any --video on demo/run: headless unless --non-headless already won.
-    if (flags.video !== undefined && !flags.nonHeadless && process.env.WAYGRAPH_HEADED === undefined) {
-        process.env.WAYGRAPH_HEADED = "0";
+    if (flags.video !== undefined && !flags.nonHeadless && envString("WAYGRAPH_HEADED") === undefined) {
+        setEnv("WAYGRAPH_HEADED", "0");
     }
     if (flags.baseUrl !== undefined) {
-        process.env.WAYGRAPH_BASE_URL = flags.baseUrl;
+        setEnv("WAYGRAPH_BASE_URL", flags.baseUrl);
     }
     if (flags.title !== undefined) {
-        process.env.WAYGRAPH_TITLE = flags.title;
+        setEnv("WAYGRAPH_TITLE", flags.title);
     }
     if (flags.video !== undefined) {
-        process.env.WAYGRAPH_VIDEO = flags.video || "1";
+        setEnv("WAYGRAPH_VIDEO", flags.video || "1");
     }
     if (flags.videoViewport !== undefined) {
         if (!parseVideoViewportFlag(flags.videoViewport)) {
             console.error('waygraph: --video-viewport must look like "1920x1080"');
             process.exit(1);
         }
-        process.env.WAYGRAPH_VIDEO_VIEWPORT = flags.videoViewport;
+        setEnv("WAYGRAPH_VIDEO_VIEWPORT", flags.videoViewport);
     }
     if (flags.data !== undefined) {
-        process.env.WAYGRAPH_DATA = flags.data;
+        setEnv("WAYGRAPH_DATA", flags.data);
     }
     if (flags.memStub) {
-        process.env.WAYGRAPH_MEM_STUB = "1";
+        setEnv("WAYGRAPH_MEM_STUB", "1");
     }
     if (flags.allBranches) {
-        process.env.WAYGRAPH_ALL_BRANCHES = "1";
+        setEnv("WAYGRAPH_ALL_BRANCHES", "1");
     }
     if (flags.sharedSession) {
-        process.env.WAYGRAPH_SHARED_SESSION = "1";
+        setEnv("WAYGRAPH_SHARED_SESSION", "1");
     }
     if (flags.fast) {
-        process.env.WAYGRAPH_DEMO_FAST = "1";
+        setEnv("WAYGRAPH_DEMO_FAST", "1");
     }
     if (flags.fullStepper) {
-        process.env.WAYGRAPH_STEPPER = "full";
+        setEnv("WAYGRAPH_STEPPER", "full");
     }
     if (flags.miniStepper) {
-        process.env.WAYGRAPH_MINI = "1";
+        setEnv("WAYGRAPH_MINI", "1");
     }
     if (flags.todoPos === "left" || flags.todoPos === "right") {
-        process.env.WAYGRAPH_TODO_POS = flags.todoPos;
+        setEnv("WAYGRAPH_TODO_POS", flags.todoPos);
     }
     if (flags.todoUiFull) {
-        process.env.WAYGRAPH_TODO_UI = "full";
+        setEnv("WAYGRAPH_TODO_UI", "full");
     }
     else if (flags.todoUiSmart) {
-        process.env.WAYGRAPH_TODO_UI = "smart";
+        setEnv("WAYGRAPH_TODO_UI", "smart");
     }
     if (flags.ffExpand) {
-        process.env.WAYGRAPH_FF_EXPAND = "1";
+        setEnv("WAYGRAPH_FF_EXPAND", "1");
     }
     if (flags.ffDisabled) {
-        process.env.WAYGRAPH_FF_DISABLED = "1";
-        process.env.WAYGRAPH_FF_EXPAND = "1";
+        setEnv("WAYGRAPH_FF_DISABLED", "1");
+        setEnv("WAYGRAPH_FF_EXPAND", "1");
     }
 }
-/**
- * BASE_URL when neither --base-url nor WAYGRAPH_BASE_URL is set - see `../config.js`'s own
- * `resolveBaseUrl` for the full resolution order (env / `.env` / `waygraph.config.*` /
- * package.json / playwright.config). Re-exported here so existing importers of this module
- * don't need to change their import path.
- */
-export { resolveBaseUrl };
 /**
  * Friendly demo defaults: STEP on; headed only for live watch (no --video).
  * --video / --auto-play-video => headless unless --non-headless.
@@ -325,26 +277,26 @@ export { resolveBaseUrl };
 export async function applyDemoDefaults(projectDir) {
     // Config first: its defaults (headed, autoNext, pace...) must land before the demo defaults below fill the same variables.
     await loadWaygraphConfig(projectDir);
-    if (process.env.WAYGRAPH_STEP === undefined)
-        process.env.WAYGRAPH_STEP = "1";
-    if (process.env.WAYGRAPH_STEP === "1" && process.env.WAYGRAPH_HEADED === undefined) {
+    if (envString("WAYGRAPH_STEP") === undefined)
+        setEnv("WAYGRAPH_STEP", "1");
+    if (envFlag("WAYGRAPH_STEP") && envString("WAYGRAPH_HEADED") === undefined) {
         // Recording locks headless - a live window fights fixed video viewport /
         // device shell centering. Watch live only with --non-headless.
-        process.env.WAYGRAPH_HEADED = process.env.WAYGRAPH_VIDEO ? "0" : "1";
+        setEnv("WAYGRAPH_HEADED", envString("WAYGRAPH_VIDEO") ? "0" : "1");
     }
     // Manual Next by default. --auto-next / --auto-play-video flip this.
-    if (process.env.WAYGRAPH_AUTOPLAY === undefined) {
-        if (process.env.WAYGRAPH_VIDEO && process.env.WAYGRAPH_STEP === "0") {
-            process.env.WAYGRAPH_AUTOPLAY = "1";
+    if (envString("WAYGRAPH_AUTOPLAY") === undefined) {
+        if (envString("WAYGRAPH_VIDEO") && envString("WAYGRAPH_STEP") === "0") {
+            setEnv("WAYGRAPH_AUTOPLAY", "1");
         }
         else {
-            process.env.WAYGRAPH_AUTOPLAY = "0";
+            setEnv("WAYGRAPH_AUTOPLAY", "0");
         }
     }
-    if (!process.env.WAYGRAPH_BASE_URL) {
+    if (!envString("WAYGRAPH_BASE_URL")) {
         const resolved = await resolveBaseUrl(projectDir);
         if (resolved)
-            process.env.WAYGRAPH_BASE_URL = resolved;
+            setEnv("WAYGRAPH_BASE_URL", resolved);
     }
 }
 export function resolveProjectDir(flags, fallbackIndex = 0) {
@@ -386,17 +338,10 @@ async function resolveFlowFileToExport(projectDir, fileArg) {
         }
     }
     const expected = flowExportNameFromBasename(abs);
-    const src = readFileSync(abs, "utf-8");
-    if (new RegExp(`\\bexport\\s+(?:const|let|var|async\\s+function|function)\\s+${expected}\\b`).test(src)) {
+    const exported = exportedNames(parseSource(abs));
+    if (exported.includes(expected))
         return expected;
-    }
-    if (new RegExp(`\\bexport\\s*\\{[^}]*\\b${expected}\\b`).test(src)) {
-        return expected;
-    }
-    const flowNames = [
-        ...src.matchAll(/\bexport\s+(?:const|let|var|async\s+function|function)\s+(\w*Flow)\b/g),
-    ].map((m) => m[1]);
-    const unique = [...new Set(flowNames)];
+    const unique = [...new Set(exported.filter((n) => n.endsWith("Flow")))];
     if (unique.length === 1)
         return unique[0];
     if (unique.includes(expected))

package/dist/cli/run-chain.d.ts

@@ -6,3 +6,4 @@
  * `WAYGRAPH_SLOWMO=<ms>` pass straight through from this process's own env.
  */
 export declare function runChain(projectDir: string, spec: string): Promise<void>;
+export declare function runChainAuto(projectDir: string, fromTag: string, toTag: string): Promise<void>;

package/dist/cli/run-chain.js

@@ -1,9 +1,12 @@
-// Split out of the former 8,700-line cli.ts (see src/ARCHITECTURE.md). Behavior unchanged.
-import { configuredExtensions } from "../config.js";
-import { expandSpecFlowFiles, resolveBaseUrl } from "./flags.js";
+import { configuredExtensions } from "../runtime/waygraph-config.js";
+import { defaultRunLogDir } from "../runtime/run-log.js";
+import { expandSpecFlowFiles } from "./flags.js";
+import { resolveBaseUrl } from "../runtime/waygraph-config.js";
+import { discoverGraph, findBlockPath, findOrphanBlocks } from "../analysis/graph.js";
 import { join } from "node:path";
 import { rmSync, writeFileSync } from "node:fs";
 import { spawn } from "node:child_process";
+import { envString, setEnv } from "../engine/env.js";
 // ---------------------------------------------------------------------------
 // `chain`
 // ---------------------------------------------------------------------------
@@ -41,19 +44,21 @@ mod.startRunner();
  */
 export async function runChain(projectDir, spec) {
     const expanded = await expandSpecFlowFiles(projectDir, spec);
-    if (process.env.WAYGRAPH_VIDEO && !process.env.WAYGRAPH_BASE_URL) {
+    if (envString("WAYGRAPH_VIDEO") && !envString("WAYGRAPH_BASE_URL")) {
         const resolved = await resolveBaseUrl(projectDir);
         if (resolved)
-            process.env.WAYGRAPH_BASE_URL = resolved;
+            setEnv("WAYGRAPH_BASE_URL", resolved);
     }
     const extensions = await configuredExtensions(projectDir);
+    if (envString("WAYGRAPH_RUN_LOG") === undefined)
+        setEnv("WAYGRAPH_RUN_LOG", defaultRunLogDir(projectDir));
     if (extensions.length > 0)
-        process.env.WAYGRAPH_EXTENSIONS = extensions.join(",");
+        setEnv("WAYGRAPH_EXTENSIONS", extensions.join(","));
     const tsxEsm = import.meta.resolve("tsx/esm");
     const scriptPath = join(projectDir, `.waygraph-chain-${process.pid}.mjs`);
     writeFileSync(scriptPath, CHAIN_RUNNER_BOOTSTRAP);
     try {
-        // webServer is started inside the child (runner/main.js), never here - see CHAIN_RUNNER_BOOTSTRAP.
+        // webServer is started inside the child (runner/runner.ts), never here - see CHAIN_RUNNER_BOOTSTRAP.
         const code = await new Promise((res, rej) => {
             const child = spawn(process.execPath, ["--import", tsxEsm, scriptPath, projectDir, expanded], {
                 stdio: "inherit",
@@ -70,3 +75,33 @@ export async function runChain(projectDir, spec) {
         rmSync(scriptPath, { force: true });
     }
 }
+async function requireNoOrphans(projectDir, forCommand) {
+    const orphans = await findOrphanBlocks(projectDir);
+    if (orphans.length === 0)
+        return true;
+    console.error(`waygraph ${forCommand}: ${orphans.length} orphan Block(s) - wire every Block into a .flow.ts before auto shorthand. Run: waygraph check ${projectDir === process.cwd() ? "." : JSON.stringify(projectDir)}`);
+    for (const o of orphans) {
+        console.error(`  - ${o.file} (${o.exportName} / "${o.block}")`);
+    }
+    process.exitCode = 1;
+    return false;
+}
+export async function runChainAuto(projectDir, fromTag, toTag) {
+    if (!(await requireNoOrphans(projectDir, "chain auto")))
+        return;
+    const graph = await discoverGraph(projectDir);
+    const path = findBlockPath(graph, fromTag, toTag);
+    if (!path) {
+        console.error(`waygraph chain auto: no Block path from "${fromTag}" to "${toTag}" in the discovered graph`);
+        process.exitCode = 1;
+        return;
+    }
+    const spec = path.join(" then ");
+    console.error(`waygraph chain auto: ${fromTag} -> ${toTag} via ${spec}`);
+    if (!envString("WAYGRAPH_BASE_URL")) {
+        const resolved = await resolveBaseUrl(projectDir);
+        if (resolved)
+            setEnv("WAYGRAPH_BASE_URL", resolved);
+    }
+    await runChain(projectDir, spec);
+}

package/dist/cli/usage.d.ts

@@ -1,4 +1,4 @@
-import type { SessionMeta } from "../session/browser.js";
+import type { SessionMeta } from "../live/auto-session/ipc.js";
 export declare function printBrowserUsage(): void;
 export declare function printBrowserSessionsList(sessions: SessionMeta[], projectDir: string): void;
 export declare function usage(): void;