waygraph 0.15.54 → 0.16.1

package/dist/auto-session/verbose-log.js

@@ -1,16 +0,0 @@
-/**
- * One log format for every overlay surface (demo / auto / browser / pilot): `waygraph <surface>: ...`
- * with a `HH:MM:SS.mmm` prefix, same shape as `runner/demo-log.js`'s (demo stays on the JS copy since
- * it runs in the target project's own process; this one is for TS-side code — pilot/auto/browser —
- * that can't import a plain .js runner module). Silenced by WAYGRAPH_JSON=1, same convention as demo.
- */
-function ts() {
-    const d = new Date();
-    const p = (n) => String(n).padStart(2, "0");
-    return `${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}.${String(d.getMilliseconds()).padStart(3, "0")}`;
-}
-export function verboseLog(surface, msg) {
-    if (process.env.WAYGRAPH_JSON === "1")
-        return;
-    console.log(`[${ts()}] waygraph ${surface}: ${msg}`);
-}

package/dist/auto-session.d.ts

@@ -1,2 +0,0 @@
-export * from "./auto-session/helpers.js";
-export * from "./auto-session/session.js";

package/dist/auto-session.js

@@ -1,3 +0,0 @@
-// Barrel: auto-session lives in src/auto-session/ (see src/ARCHITECTURE.md). Kept so existing imports of "./auto-session.js" don't change.
-export * from "./auto-session/helpers.js";
-export * from "./auto-session/session.js";

package/dist/cli/discover.d.ts

@@ -1,40 +0,0 @@
-export declare function walkDir(dir: string, pattern: RegExp): string[];
-export declare function discoverFlows(projectDir: string): string[];
-export declare function extractFlowNames(filePath: string): string[];
-/** `LoginBlock` -> `"login"`; `OverviewMetricsBlock` -> `"overview-metrics"`. */
-export declare function blockExportToLabel(exportId: string): string;
-/** Every `...Block` identifier a `.flow.ts` file imports, in source order. */
-export declare function parseBlockImports(filePath: string): string[];
-/** Every `page.goto("...")` string literal in a file, in source order. */
-export declare function extractGotos(filePath: string): string[];
-/** Every `Trait.url({ pathname: "..." })` target in a file, in source order. */
-export declare function extractUrlTraits(filePath: string): string[];
-export declare function importModule(filePath: string): Promise<Record<string, unknown>>;
-/** Kept as a named alias - `run`/`validate` below were written against this name first. */
-export declare const importFlowFile: typeof importModule;
-export declare function isFlowLike(val: unknown): val is {
-    run: (...args: unknown[]) => Promise<unknown>;
-};
-export declare function discoverBlocks(projectDir: string): string[];
-export declare function isBlockLike(val: unknown): val is {
-    name: string;
-    instruction: {
-        act: unknown;
-    };
-};
-/** Set by `defineNavBlock` (non-enumerable) - see src/core.ts. */
-export declare function isNavBlockMarked(val: Record<string, unknown>): boolean;
-export declare const NAV_METHOD_CALLS: readonly ["page.goto(", "page.reload(", "page.goBack(", "page.goForward("];
-/**
- * Matches a selector-taking Trait factory call whose first argument is a
- * literal string/template, not an identifier or property access - the exact
- * shape found repeatedly in hand-written assertion Blocks
- * (`Trait.visible("#some-id")` instead of `Trait.visible(SomeSel.thing)`).
- * `Trait.url(...)` is deliberately excluded - it takes a URLPatternInit, never
- * a DOM selector. Same file-scoped-regex bluntness the nav-escape sweep above
- * already accepts (see openspec/specs/nav-block-and-check/spec.md) - a known
- * blind spot on string concatenation/template-built selectors, not solved
- * here for the same "recipe before promotion" reason that check accepts its
- * own shared-helper blind spot.
- */
-export declare const INLINE_SELECTOR_CALL: RegExp;

package/dist/cli/discover.js

@@ -1,148 +0,0 @@
-// Split out of the former 8,700-line cli.ts (see src/ARCHITECTURE.md). Behavior unchanged.
-import { readFileSync, readdirSync } from "node:fs";
-import { join, resolve } from "node:path";
-// ---------------------------------------------------------------------------
-// Filesystem
-// ---------------------------------------------------------------------------
-export function walkDir(dir, pattern) {
-    const results = [];
-    let entries;
-    try {
-        entries = readdirSync(dir, { withFileTypes: true });
-    }
-    catch {
-        return results;
-    }
-    for (const entry of entries) {
-        const full = join(dir, entry.name);
-        if (entry.isDirectory()) {
-            if (entry.name === "node_modules" || entry.name === "dist" || entry.name === ".git")
-                continue;
-            results.push(...walkDir(full, pattern));
-        }
-        else if (pattern.test(entry.name)) {
-            results.push(full);
-        }
-    }
-    return results;
-}
-export function discoverFlows(projectDir) {
-    return walkDir(projectDir, /\.flow\.ts$/);
-}
-// ---------------------------------------------------------------------------
-// Static analysis for `list`/`nav` (no import, regex only)
-// ---------------------------------------------------------------------------
-export function extractFlowNames(filePath) {
-    const src = readFileSync(filePath, "utf-8");
-    const names = [];
-    const re = /export\s+const\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*[=:]/g;
-    let m;
-    while ((m = re.exec(src)) !== null) {
-        const name = m[1];
-        if (name !== undefined)
-            names.push(name);
-    }
-    return names;
-}
-/** `LoginBlock` -> `"login"`; `OverviewMetricsBlock` -> `"overview-metrics"`. */
-export function blockExportToLabel(exportId) {
-    const base = exportId.replace(/Block$/, "");
-    return base
-        .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
-        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2")
-        .toLowerCase();
-}
-/** Every `...Block` identifier a `.flow.ts` file imports, in source order. */
-export function parseBlockImports(filePath) {
-    const src = readFileSync(filePath, "utf-8");
-    const names = [];
-    const re = /import\s*\{([^}]*)\}\s*from\s*["'][^"']*\.block(?:\.js)?["']/g;
-    let m;
-    while ((m = re.exec(src)) !== null) {
-        for (const part of m[1].split(",")) {
-            const name = part.trim().split(/\s+as\s+/)[0]?.trim();
-            if (name)
-                names.push(name);
-        }
-    }
-    return names;
-}
-/** Every `page.goto("...")` string literal in a file, in source order. */
-export function extractGotos(filePath) {
-    const src = readFileSync(filePath, "utf-8");
-    const results = [];
-    const re = /\.goto\(\s*["'`]([^"'`]*)["'`]/g;
-    let m;
-    while ((m = re.exec(src)) !== null) {
-        const url = m[1];
-        if (url !== undefined)
-            results.push(url);
-    }
-    return results;
-}
-/** Every `Trait.url({ pathname: "..." })` target in a file, in source order. */
-export function extractUrlTraits(filePath) {
-    const src = readFileSync(filePath, "utf-8");
-    const results = [];
-    const re = /Trait\.url\(\s*\{[^}]*pathname:\s*["'`]([^"'`]*)["'`]/g;
-    let m;
-    while ((m = re.exec(src)) !== null) {
-        const url = m[1];
-        if (url !== undefined)
-            results.push(url);
-    }
-    return results;
-}
-// ---------------------------------------------------------------------------
-// Dynamic import + validation
-// ---------------------------------------------------------------------------
-export async function importModule(filePath) {
-    const url = new URL(`file://${resolve(filePath)}`);
-    return (await import(url.href));
-}
-/** Kept as a named alias - `run`/`validate` below were written against this name first. */
-export const importFlowFile = importModule;
-export function isFlowLike(val) {
-    if (val === null || typeof val !== "object")
-        return false;
-    const obj = val;
-    return typeof obj.run === "function";
-}
-// ---------------------------------------------------------------------------
-// `check` - secondary/complementary to the ActionPage @deprecated warning
-// (src/types.ts). That's the primary, always-on signal an editor shows the
-// instant a regular Block's act() calls a navigation method; this command
-// sweeps a whole project in one shot for contexts with no editor watching
-// (CI, an autonomous agent writing Block files without a language server).
-// See openspec/specs/nav-block-and-check/spec.md for the full rationale.
-// ---------------------------------------------------------------------------
-export function discoverBlocks(projectDir) {
-    return walkDir(projectDir, /\.block\.ts$/);
-}
-export function isBlockLike(val) {
-    if (val === null || typeof val !== "object")
-        return false;
-    const obj = val;
-    if (typeof obj.name !== "string")
-        return false;
-    const instruction = obj.instruction;
-    return instruction !== null && typeof instruction === "object" && typeof instruction?.act === "function";
-}
-/** Set by `defineNavBlock` (non-enumerable) - see src/core.ts. */
-export function isNavBlockMarked(val) {
-    return val.__waygraphKind === "nav";
-}
-export const NAV_METHOD_CALLS = ["page.goto(", "page.reload(", "page.goBack(", "page.goForward("];
-/**
- * Matches a selector-taking Trait factory call whose first argument is a
- * literal string/template, not an identifier or property access - the exact
- * shape found repeatedly in hand-written assertion Blocks
- * (`Trait.visible("#some-id")` instead of `Trait.visible(SomeSel.thing)`).
- * `Trait.url(...)` is deliberately excluded - it takes a URLPatternInit, never
- * a DOM selector. Same file-scoped-regex bluntness the nav-escape sweep above
- * already accepts (see openspec/specs/nav-block-and-check/spec.md) - a known
- * blind spot on string concatenation/template-built selectors, not solved
- * here for the same "recipe before promotion" reason that check accepts its
- * own shared-helper blind spot.
- */
-export const INLINE_SELECTOR_CALL = /\b(?:Trait\.visible|Trait\.text|textEquals|visible)\(\s*["'`]/;

package/dist/commands/agent-dive.js

@@ -1,52 +0,0 @@
-// Split out of the former 8,700-line cli.ts (see src/ARCHITECTURE.md). Behavior unchanged.
-import { runAgentDive } from "./agent-dive-scaffold.js";
-import { resolve } from "node:path";
-import { existsSync, statSync } from "node:fs";
-export async function agentDiveCase(args) {
-    // Playwright analogue: npx playwright init-agents --loop <provider>
-    const rest = args.slice(1);
-    let loop = "claude";
-    let prompts = false;
-    let projectDir = process.cwd();
-    for (let i = 0; i < rest.length; i++) {
-        const a = rest[i];
-        if (a === "--prompts") {
-            prompts = true;
-            continue;
-        }
-        if (a === "--loop" || a.startsWith("--loop=")) {
-            const v = a.startsWith("--loop=") ? a.slice("--loop=".length) : rest[++i];
-            if (!v || !["claude", "opencode", "cursor", "vscode"].includes(v)) {
-                console.error("waygraph agent-dive: --loop must be claude | opencode | cursor | vscode");
-                process.exit(1);
-            }
-            loop = v;
-            continue;
-        }
-        if (a === "--help" || a === "-h") {
-            console.log(`waygraph agent-dive [--loop claude|opencode|cursor|vscode] [--prompts] [project]
-
-Initialize coding-agent definitions for diving an app into waygraph Blocks
-(Playwright \`init-agents\` analogue).
-
-  --loop claude     write .claude/agents/*.md (default)
-  --loop opencode   write .opencode/prompts/*.md
-  --loop cursor     write .cursor/rules/waygraph-*.mdc
-  --loop vscode     write .github/agents/*.md
-  --prompts         also copy docs/waygraph-agents/*.md
-
-Agents shipped: waygraph-planner, waygraph-author, waygraph-healer.
-`);
-            process.exit(0);
-        }
-        if (!a.startsWith("-")) {
-            projectDir = resolve(a);
-        }
-    }
-    if (!existsSync(projectDir) || !statSync(projectDir).isDirectory()) {
-        console.error(`waygraph agent-dive: no such directory: ${projectDir}`);
-        process.exit(1);
-    }
-    runAgentDive({ loop, projectDir, prompts });
-    return;
-}

package/dist/commands/check.js

@@ -1,192 +0,0 @@
-// Split out of the former 8,700-line cli.ts (see src/ARCHITECTURE.md). Behavior unchanged.
-import { INLINE_SELECTOR_CALL, NAV_METHOD_CALLS, discoverBlocks, discoverFlows, importFlowFile, importModule, isBlockLike, isFlowLike, isNavBlockMarked, walkDir } from "../cli/discover.js";
-import { basename, relative, resolve } from "node:path";
-import { discoverGraph, findBlockPath, findOrphanBlocks } from "../analysis/graph.js";
-import { parseRunFlags, resolveBaseUrl } from "../cli/flags.js";
-import { runChain } from "../cli/run-chain.js";
-import { collectPracticeWarnings, practiceKindLabel } from "../analysis/practices-check.js";
-import { readFileSync } from "node:fs";
-async function validateFlows(projectDir) {
-    const files = discoverFlows(projectDir);
-    const results = [];
-    for (const file of files) {
-        try {
-            const mod = await importFlowFile(file);
-            for (const [exportName, exported] of Object.entries(mod)) {
-                if (isFlowLike(exported)) {
-                    results.push({ file, name: exportName, valid: true });
-                }
-            }
-        }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            results.push({ file, name: basename(file, ".ts"), valid: false, error: msg });
-        }
-    }
-    return results;
-}
-/**
- * Walks every `*.block.ts` file under `projectDir`, imports each to find its
- * exported Blocks, and for any Block NOT built via `defineNavBlock`, scans
- * that file's own source text for a navigation call. Warning only - never
- * throws, never changes the caller's exit code on its own account (a Block
- * file that fails to import for unrelated reasons is silently skipped here;
- * `validate` is the command that reports import failures).
- */
-function printOrphanReport(projectDir, orphans) {
-    if (orphans.length === 0) {
-        console.log(`waygraph check: no orphan Blocks (every *.block.ts export is wired into a flow)`);
-        return;
-    }
-    for (const o of orphans) {
-        console.warn(`waygraph check: orphan Block ${o.file} (${o.exportName} / "${o.block}") is not referenced in any defineFlow([...]) - wire it into a .flow.ts before chain auto shorthand`);
-    }
-    console.log(`waygraph check: ${orphans.length} orphan Block${orphans.length === 1 ? "" : "s"}`);
-}
-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 (!process.env.WAYGRAPH_BASE_URL) {
-        const resolved = await resolveBaseUrl(projectDir);
-        if (resolved)
-            process.env.WAYGRAPH_BASE_URL = resolved;
-    }
-    await runChain(projectDir, spec);
-}
-function printPracticeReport(projectDir, practiceWarnings) {
-    if (practiceWarnings.length === 0) {
-        console.log(`waygraph check: no bad-practice patterns under ${projectDir}`);
-        return;
-    }
-    for (const w of practiceWarnings) {
-        console.warn(`waygraph check: ${w.file} (${practiceKindLabel(w.kind)}) — ${w.detail}`);
-    }
-    console.log(`waygraph check: ${practiceWarnings.length} bad-practice warning${practiceWarnings.length === 1 ? "" : "s"}`);
-}
-async function checkCommand(projectDir, opts) {
-    const files = discoverBlocks(projectDir);
-    const navWarnings = [];
-    const selWarnings = [];
-    for (const file of files) {
-        let mod;
-        try {
-            mod = await importModule(file);
-        }
-        catch {
-            continue;
-        }
-        let src;
-        for (const [exportName, exported] of Object.entries(mod)) {
-            if (!isBlockLike(exported))
-                continue;
-            src ??= readFileSync(file, "utf-8");
-            // Nav-escape: NavBlocks are exempt (their generated act() is the one
-            // legitimate goto/click call site).
-            if (!isNavBlockMarked(exported) &&
-                NAV_METHOD_CALLS.some((needle) => src.includes(needle))) {
-                navWarnings.push({ file, blockName: exported.name, exportName });
-            }
-            // Inline selector: applies to every Block kind, including NavBlocks -
-            // a Nav's own `verify` array is just as likely to inline a selector.
-            if (INLINE_SELECTOR_CALL.test(src)) {
-                selWarnings.push({ file, blockName: exported.name, exportName });
-            }
-        }
-    }
-    const practiceWarnings = collectPracticeWarnings(projectDir, walkDir, {
-        disabled: opts?.noPractices === true,
-    });
-    return { navWarnings, selWarnings, practiceWarnings };
-}
-async function runTypecheckCommand(projectDir, noPractices) {
-    const { spawnSync } = await import("node:child_process");
-    const tsc = spawnSync("npx", ["tsc", "--noEmit"], {
-        cwd: projectDir,
-        stdio: "inherit",
-        shell: false,
-    });
-    if (tsc.status !== 0) {
-        process.exit(tsc.status === null ? 1 : tsc.status);
-    }
-    if (noPractices)
-        return;
-    const practiceWarnings = collectPracticeWarnings(projectDir, walkDir);
-    printPracticeReport(projectDir, practiceWarnings);
-}
-export async function validateCase(args) {
-    const proj = resolve(args[1] ?? process.cwd());
-    const results = await validateFlows(proj);
-    let failed = 0;
-    for (const r of results) {
-        const rel = relative(proj, r.file);
-        if (r.valid) {
-            console.log(`OK    ${rel}  ${r.name}`);
-        }
-        else {
-            failed++;
-            console.log(`FAIL  ${rel}  ${r.name} -- ${r.error}`);
-        }
-    }
-    if (failed > 0)
-        process.exitCode = 1;
-    return;
-}
-export async function typecheckCase(args) {
-    const flags = parseRunFlags(args.slice(1));
-    const proj = resolve(flags.positionals[0] ?? process.cwd());
-    await runTypecheckCommand(proj, flags.noPractices === true);
-    return;
-}
-export async function checkCase(args) {
-    const flags = parseRunFlags(args.slice(1));
-    const proj = resolve(flags.positionals[0] ?? process.cwd());
-    const { navWarnings, selWarnings, practiceWarnings } = await checkCommand(proj, flags.noPractices ? { noPractices: true } : undefined);
-    if (navWarnings.length === 0) {
-        console.log(`waygraph check: no navigation found outside NavBlocks under ${proj}`);
-    }
-    else {
-        for (const w of navWarnings) {
-            const rel = relative(proj, w.file);
-            console.warn(`waygraph check: ${rel} (${w.blockName}) calls page.goto/reload/goBack/goForward outside a NavBlock - consider defineNavBlock instead`);
-        }
-        console.log(`waygraph check: ${navWarnings.length} nav warning${navWarnings.length === 1 ? "" : "s"}`);
-    }
-    if (selWarnings.length === 0) {
-        console.log(`waygraph check: no inline selectors found in verify arrays under ${proj}`);
-    }
-    else {
-        for (const w of selWarnings) {
-            const rel = relative(proj, w.file);
-            console.warn(`waygraph check: ${rel} (${w.blockName}) has an inline selector literal in verify - move it into a *Sel object`);
-        }
-        console.log(`waygraph check: ${selWarnings.length} inline-selector warning${selWarnings.length === 1 ? "" : "s"}`);
-    }
-    if (!flags.noPractices) {
-        printPracticeReport(proj, practiceWarnings);
-    }
-    const orphans = await findOrphanBlocks(proj);
-    printOrphanReport(proj, orphans);
-    // Warnings only - never fail exit code. Orphans are reported for
-    // human/agent cleanup; chain auto refuses while any remain.
-    return;
-}

package/dist/commands/map.js

@@ -1,29 +0,0 @@
-// Split out of the former 8,700-line cli.ts (see src/ARCHITECTURE.md). Behavior unchanged.
-import { relative, resolve } from "node:path";
-import { checkMap } from "../analysis/map-check.js";
-export async function mapCase(args) {
-    const proj = resolve(args[1] ?? process.cwd());
-    const result = await checkMap(proj);
-    if (!result.hasMapDir) {
-        console.log(`waygraph map: no src/map/ directory under ${proj} - nothing to check ` +
-            "(this project isn't on the Waygraph Map convention, or hasn't been migrated yet)");
-        return;
-    }
-    console.log(`waygraph map: ${result.nodes.length} node(s) found under ${relative(proj, result.mapRoot)}`);
-    if (result.violations.length === 0) {
-        console.log("waygraph map: 0 violations - every static Nav/Page url verbatim-matches its folder path");
-    }
-    else {
-        for (const v of result.violations) {
-            console.error(`waygraph map: ${v.file} (${v.block}) - ${v.reason}`);
-        }
-        console.error(`waygraph map: ${result.violations.length} violation${result.violations.length === 1 ? "" : "s"}`);
-        // Unlike `check`'s warnings-only stance, a Map violation is exactly
-        // the class of bug this command exists to catch (a fabricated
-        // folder grouping that never matched the real site, e.g. the real
-        // (auth)/signin/ mistake this command's own header comment cites) -
-        // fail loud, not just warn.
-        process.exitCode = 1;
-    }
-    return;
-}

package/dist/commands/run.js

@@ -1,104 +0,0 @@
-// Split out of the former 8,700-line cli.ts (see src/ARCHITECTURE.md). Behavior unchanged.
-import { applyDemoDefaults, applyRunFlags, parseRunFlags, resolveBaseUrl, resolveProjectDir, resolveSpec } from "../cli/flags.js";
-import { runChain } from "../cli/run-chain.js";
-import { resolve } from "node:path";
-import { existsSync } from "node:fs";
-import { runChainAuto } from "./check.js";
-export async function runCase(args) {
-    const flags = parseRunFlags(args.slice(1));
-    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 (!process.env.WAYGRAPH_BASE_URL) {
-        const resolved = await resolveBaseUrl(proj);
-        if (resolved)
-            process.env.WAYGRAPH_BASE_URL = resolved;
-    }
-    await runChain(proj, spec);
-    return;
-}
-export async function chainCase(args) {
-    // Compat alias: chain auto A B -> auto --blocks A B; else -> run --blocks.
-    const flags = parseRunFlags(args.slice(1));
-    applyRunFlags(flags);
-    const first = flags.positionals[0];
-    if (first === "auto") {
-        const fromTag = flags.positionals[1];
-        const toTag = flags.positionals[2];
-        if (!fromTag || !toTag) {
-            console.error("waygraph chain auto: missing <fromCheckpoint> <toCheckpoint> [project]");
-            console.error("  prefer: waygraph auto --blocks LoggedIn OrderComplete");
-            process.exit(1);
-        }
-        const proj = resolve(flags.positionals[3] ?? process.cwd());
-        if (!existsSync(proj)) {
-            console.error(`waygraph: no such directory: ${proj}`);
-            process.exit(1);
-        }
-        await runChainAuto(proj, fromTag, toTag);
-        return;
-    }
-    const spec = flags.blocks ?? first;
-    if (!spec) {
-        console.error('waygraph chain: missing <spec> — prefer: waygraph run --blocks "a then b"\n' +
-            "  or: waygraph auto --blocks <fromCheckpoint> <toCheckpoint>");
-        process.exit(1);
-    }
-    const proj = resolve(flags.blocks ? (flags.positionals[0] ?? process.cwd()) : (flags.positionals[1] ?? process.cwd()));
-    if (!process.env.WAYGRAPH_BASE_URL) {
-        const resolved = await resolveBaseUrl(proj);
-        if (resolved)
-            process.env.WAYGRAPH_BASE_URL = resolved;
-    }
-    // If caller asked for step overlay, behave like demo; else like run.
-    if (flags.step === true || process.env.WAYGRAPH_STEP === "1") {
-        await applyDemoDefaults(proj);
-    }
-    await runChain(proj, spec);
-    return;
-}
-export async function demoCase(args) {
-    const flags = parseRunFlags(args.slice(1));
-    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 && process.env.WAYGRAPH_STEP === undefined) {
-        process.env.WAYGRAPH_STEP = "1";
-    }
-    await applyDemoDefaults(proj);
-    console.error(`waygraph demo: STEP=${process.env.WAYGRAPH_STEP === "1" ? "on" : "off"}` +
-        ` AUTO_NEXT=${process.env.WAYGRAPH_AUTOPLAY === "1" ? "on" : "off"}` +
-        ` HEADED=${process.env.WAYGRAPH_HEADED === "0" ? "off" : "on"}` +
-        ` BASE_URL=${process.env.WAYGRAPH_BASE_URL ?? "(unset)"}` +
-        (process.env.WAYGRAPH_VIDEO ? ` VIDEO=${process.env.WAYGRAPH_VIDEO}` : "") +
-        (process.env.WAYGRAPH_TITLE ? ` TITLE=${JSON.stringify(process.env.WAYGRAPH_TITLE)}` : ""));
-    await runChain(proj, spec);
-    return;
-}