waygraph 0.15.54 → 0.16.1

package/dist/cli/commands/codemod-stubs.js

@@ -0,0 +1,187 @@
+// Part of `waygraph upgrade --codemod flows`: moves ctx stubs onto the one form each thing has in 0.16.0. The list-only
+// `ctx.todos([...])` and its setters (`todoId`, `todoTitle`, `todoStyle`, `todoPos`, `todoIndex`) become
+// `ctx.todos(id, items, { title, style, pos, index })`; `todoGroups(groups)` gets the same id and options; the method
+// aliases (`banner`, `bannerPos`, `clearDevice`, `clearTodos`, `landscape`, `portrait`, `todoDockFull`) become the
+// names they stood for. A stub written as a slot map (`{ email: { selector, label } }`) becomes a function of
+// `ctx.ring` calls, and a stub set in a `define*Block({ ... })` (options or instruction) moves out to a chained
+// `.stubBefore(...)` on the Block. Works on the TypeScript AST (ts-morph).
+import { Node, SyntaxKind } from "ts-morph";
+const RENAMED = {
+    banner: (a) => `title(${a.join(", ")})`,
+    bannerPos: (a) => `titlePos(${a.join(", ")})`,
+    clearDevice: () => "hideDevice()",
+    clearTodos: () => "hideTodos()",
+    landscape: () => 'orientation("landscape")',
+    portrait: () => 'orientation("portrait")',
+    todoDockFull: () => "todoDockUi({ compact: false, collision: false, behindRing: false })",
+};
+/** The setters that fold into `todos(id, items, opts)`, and the option each one becomes. */
+const DOCK_SETTERS = { todoId: "id", todoTitle: "title", todoStyle: "style", todoPos: "pos", todoIndex: "index" };
+const DEFAULT_DOCK_ID = '"todos"';
+/** `ctx.method(...)` as a statement on its own: the receiver, the method and the call. */
+function ctxCall(statement) {
+    if (!Node.isExpressionStatement(statement))
+        return undefined;
+    const call = statement.getExpression();
+    if (!Node.isCallExpression(call))
+        return undefined;
+    const callee = call.getExpression();
+    if (!Node.isPropertyAccessExpression(callee) || !Node.isIdentifier(callee.getExpression()))
+        return undefined;
+    return { receiver: callee.getExpression().getText(), method: callee.getName(), call };
+}
+/** Whether `receiver` is a stub's ctx: typed as StubCtx, or the first parameter of a function passed to a stub phase. */
+function isStubCtx(call, receiver) {
+    const fn = call.getFirstAncestor((a) => Node.isArrowFunction(a) || Node.isFunctionExpression(a) || Node.isFunctionDeclaration(a) || Node.isMethodDeclaration(a));
+    if (!fn || !(Node.isArrowFunction(fn) || Node.isFunctionExpression(fn) || Node.isFunctionDeclaration(fn) || Node.isMethodDeclaration(fn)))
+        return false;
+    const param = fn.getParameters()[0];
+    if (!param || param.getName() !== receiver)
+        return false;
+    if (/StubCtx/.test(param.getType().getText(param)))
+        return true;
+    const parent = fn.getParent();
+    const callee = Node.isCallExpression(parent) ? parent.getExpression() : undefined;
+    if (Node.isPropertyAccessExpression(callee) && /^stub(Before|After|OnError)$/.test(callee.getName()))
+        return true;
+    return Node.isPropertyAssignment(parent) && /^stub(Before|After|OnError)$/.test(parent.getName());
+}
+/** Todo items written with the old `name` key get `id`. */
+function renameItemNames(items) {
+    for (const obj of items.getDescendantsOfKind(SyntaxKind.ObjectLiteralExpression)) {
+        const name = obj.getProperty("name");
+        if (Node.isPropertyAssignment(name) && !obj.getProperty("id"))
+            name.getNameNode().replaceWithText("id");
+    }
+}
+/** Rewrites one statement list; returns whether anything changed and the calls it could not convert. */
+function convertStatements(statements, problems) {
+    const calls = statements.map(ctxCall);
+    let changed = false;
+    const consumed = new Set();
+    calls.forEach((c, i) => {
+        if (!c || !isStubCtx(c.call, c.receiver))
+            return;
+        const args = c.call.getArguments().map((a) => a.getText());
+        if (RENAMED[c.method]) {
+            c.call.replaceWithText(`${c.receiver}.${RENAMED[c.method](args)}`);
+            changed = true;
+            return;
+        }
+        const isList = c.method === "todos" && c.call.getArguments().length === 1;
+        if (!isList && c.method !== "todoGroups")
+            return;
+        if (c.method === "todoGroups" && c.call.getArguments().length !== 1)
+            return;
+        // The dock's setters in the same stub, before or after the list, fold into its options.
+        const opts = {};
+        calls.forEach((s, j) => {
+            if (!s || s.receiver !== c.receiver || !DOCK_SETTERS[s.method])
+                return;
+            if (s.method === "todoIndex" && c.method === "todoGroups")
+                return;
+            opts[DOCK_SETTERS[s.method]] = s.call.getArguments()[0]?.getText() ?? "undefined";
+            consumed.add(j);
+        });
+        const items = c.call.getArguments()[0];
+        renameItemNames(items);
+        const id = opts.id ?? DEFAULT_DOCK_ID;
+        delete opts.id;
+        const entries = Object.entries(opts);
+        const tail = entries.length ? `, { ${entries.map(([k, v]) => `${k}: ${v}`).join(", ")} }` : "";
+        c.call.replaceWithText(`${c.receiver}.${c.method}(${id}, ${items.getText()}${tail})`);
+        changed = true;
+    });
+    for (const i of [...consumed].sort((a, b) => b - a))
+        statements[i].remove();
+    for (const [i, c] of calls.entries()) {
+        if (!c || consumed.has(i) || c.call.wasForgotten() || !isStubCtx(c.call, c.receiver))
+            continue;
+        if (DOCK_SETTERS[c.method] && c.method !== "todoIndex")
+            problems.push({ line: c.call.getStartLineNumber(), reason: `ctx.${c.method}() with no ctx.todos(...) beside it: pass it as an option of ctx.todos(id, items, { ... })` });
+        if (c.method === "set")
+            problems.push({ line: c.call.getStartLineNumber(), reason: "ctx.set({...}) was removed: call ctx.ring / ctx.todos / ctx.title ... instead" });
+    }
+    return changed;
+}
+const PHASES = new Set(["stubBefore", "stubAfter", "stubOnError"]);
+/** A slot map as a stub function: `{ a: {...} }` -> `(ctx) => { ctx.ring("a", {...}); }`. */
+function mapToStub(map) {
+    if (!Node.isObjectLiteralExpression(map))
+        return map.getText();
+    const rings = map.getProperties().flatMap((p) => (Node.isPropertyAssignment(p) ? [`ctx.ring(${JSON.stringify(p.getName().replace(/^["']|["']$/g, ""))}, ${p.getInitializerOrThrow().getText()});`] : []));
+    return `(ctx) => {\n${rings.map((r) => "  " + r).join("\n")}\n}`;
+}
+/** `X.stubAfter({ ... })` -> `X.stubAfter((ctx) => { ctx.ring(...) })`. */
+function convertSlotMaps(sf) {
+    let changed = false;
+    for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression).reverse()) {
+        if (call.wasForgotten())
+            continue;
+        const callee = call.getExpression();
+        const arg = call.getArguments()[0];
+        if (Node.isPropertyAccessExpression(callee) && PHASES.has(callee.getName()) && Node.isObjectLiteralExpression(arg)) {
+            arg.replaceWithText(mapToStub(arg));
+            changed = true;
+        }
+    }
+    return changed;
+}
+/** `defineXBlock({ ..., stubBefore: fn })` (or in its instruction) -> `defineXBlock({ ... }).stubBefore(fn)`. */
+function hoistDefinitionStubs(sf) {
+    let changed = false;
+    for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression).reverse()) {
+        if (call.wasForgotten() || !/^define\w*Block$/.test(call.getExpression().getText()))
+            continue;
+        const options = call.getArguments()[0];
+        if (!Node.isObjectLiteralExpression(options))
+            continue;
+        const holders = [options];
+        const instruction = options.getProperty("instruction");
+        if (Node.isPropertyAssignment(instruction) && Node.isObjectLiteralExpression(instruction.getInitializer()))
+            holders.push(instruction.getInitializer());
+        const chained = [];
+        for (const holder of holders) {
+            for (const prop of holder.getProperties()) {
+                const name = Node.isPropertyAssignment(prop) || Node.isMethodDeclaration(prop) ? prop.getName() : "";
+                if (!PHASES.has(name))
+                    continue;
+                let fn;
+                if (Node.isMethodDeclaration(prop))
+                    fn = `(${prop.getParameters().map((p) => p.getText()).join(", ")}) => ${prop.getBodyOrThrow().getText()}`;
+                else {
+                    const init = prop.getInitializerOrThrow();
+                    fn = Node.isObjectLiteralExpression(init) ? mapToStub(init) : init.getText();
+                }
+                chained.push(`.${name}(${fn})`);
+                prop.remove();
+            }
+        }
+        if (chained.length) {
+            call.replaceWithText(call.getText() + chained.join(""));
+            changed = true;
+        }
+    }
+    return changed;
+}
+/** Rewrites the old stub forms in every file; returns the files it changed and the calls left for a person. */
+export function convertStubs(project) {
+    const changed = [];
+    const problems = [];
+    for (const sf of project.getSourceFiles()) {
+        const left = [];
+        let touched = hoistDefinitionStubs(sf);
+        if (convertSlotMaps(sf))
+            touched = true;
+        for (const block of sf.getDescendantsOfKind(SyntaxKind.Block).reverse()) {
+            if (block.wasForgotten())
+                continue;
+            if (convertStatements(block.getStatements(), left))
+                touched = true;
+        }
+        if (touched)
+            changed.push(sf);
+        problems.push(...left.map((p) => ({ file: sf.getFilePath(), ...p })));
+    }
+    return { changed, problems };
+}

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

@@ -1,9 +1,10 @@
 import { resolve } from "node:path";
-import { loadWaygraphConfig } from "../config.js";
-import { extensionInfo, resolveExtension } from "../extensions.js";
+import { loadWaygraphConfig } from "../../runtime/waygraph-config.js";
+import { extensionInfo, resolveExtension } from "../../runtime/extensions.js";
+import { parseCommand } from "../args.js";
 export async function extensionsCase(args) {
-    const update = args.includes("--update");
-    const rest = args.slice(2).filter((a) => a !== "--update");
+    const { values, positionals: rest } = parseCommand("extensions", { update: { type: "boolean", help: "Download again" } }, args.slice(2));
+    const update = values.update === true;
     if (args[1] !== "install") {
         console.error("usage: waygraph extensions install [project] [--update]");
         process.exit(1);

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

@@ -1,5 +1,4 @@
-// Split out of the former 8,700-line cli.ts (see src/ARCHITECTURE.md). Behavior unchanged.
-import { packageRoot } from "../cli/util.js";
+import { packageRoot } from "../util.js";
 import { agentSkillFiles } from "./agent-dive-scaffold.js";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { spawnSync } from "node:child_process";

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

@@ -1,12 +1,13 @@
-// Split out of the former 8,700-line cli.ts (see src/ARCHITECTURE.md). Behavior unchanged.
-import { blockExportToLabel, discoverFlows, extractFlowNames, extractGotos, extractUrlTraits, parseBlockImports, walkDir } from "../cli/discover.js";
+import { blockExportToLabel, extractFlowNames, extractGotos, extractUrlTraits, parseBlockImports } from "../../analysis/flow-source.js";
+import { walkDir } from "../../manifest/scan.js";
+import { exportedNames, parseSource } from "../../manifest/source.js";
 import { relative, resolve } from "node:path";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 // ---------------------------------------------------------------------------
 // `list`
 // ---------------------------------------------------------------------------
 function listCommand(projectDir) {
-    const files = discoverFlows(projectDir);
+    const files = walkDir(projectDir, /\.flow\.ts$/);
     if (files.length === 0) {
         console.log(`waygraph: no flows found under ${projectDir}`);
         return;
@@ -22,7 +23,7 @@ function listCommand(projectDir) {
 // `nav`
 // ---------------------------------------------------------------------------
 function navCommand(projectDir, flowName) {
-    const files = discoverFlows(projectDir);
+    const files = walkDir(projectDir, /\.flow\.ts$/);
     const targets = flowName
         ? files.filter((f) => extractFlowNames(f).includes(flowName))
         : files;
@@ -33,13 +34,14 @@ function navCommand(projectDir, flowName) {
         process.exitCode = 1;
         return;
     }
+    let scanned;
+    const blockFiles = () => (scanned ??= walkDir(projectDir, /\.block\.ts$/).map((f) => ({ file: f, exports: exportedNames(parseSource(f)) })));
     for (const file of targets) {
         for (const name of extractFlowNames(file)) {
             console.log(`${name}  (${relative(projectDir, file)})`);
-            const blockDir = projectDir;
             for (const blockExport of parseBlockImports(file)) {
                 console.log(`  -> ${blockExportToLabel(blockExport)}`);
-                const blockFile = walkDir(blockDir, /\.block\.ts$/).find((f) => readFileSync(f, "utf-8").includes(`export const ${blockExport}`));
+                const blockFile = blockFiles().find((f) => f.exports.includes(blockExport))?.file;
                 if (!blockFile)
                     continue;
                 for (const url of extractGotos(blockFile))

package/dist/cli/commands/manifest.d.ts

@@ -0,0 +1,2 @@
+/** `waygraph manifest [project] [--out <file>]`: every Block, Flow and Checkpoint of the project, as JSON. */
+export declare function manifestCase(args: string[]): Promise<void>;

package/dist/cli/commands/manifest.js

@@ -0,0 +1,20 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { buildManifest } from "../../manifest/manifest.js";
+import { parseCommand } from "../args.js";
+/** `waygraph manifest [project] [--out <file>]`: every Block, Flow and Checkpoint of the project, as JSON. */
+export async function manifestCase(args) {
+    const { values, positionals: positional } = parseCommand("manifest", { out: { type: "string", help: "Write to this file" } }, args.slice(1));
+    const out = values.out;
+    const proj = resolve(positional[0] ?? process.cwd());
+    const manifest = await buildManifest(proj);
+    const json = JSON.stringify(manifest, null, 2) + "\n";
+    if (!out) {
+        process.stdout.write(json);
+        return;
+    }
+    const file = resolve(proj, out);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, json);
+    console.error(`waygraph manifest: ${manifest.blocks.length} Block(s), ${manifest.flows.length} flow(s) -> ${file}`);
+}

package/dist/cli/commands/map.js

@@ -0,0 +1,57 @@
+import { relative, resolve } from "node:path";
+import { checkMap } from "../../analysis/map-check.js";
+import { packMapGroup } from "../../manifest/pack.js";
+import { parseCommand } from "../args.js";
+const PACK_OPTIONS = {
+    out: { type: "string", value: "<dir>", help: "Output folder (default .waygraph/packages/<group>)" },
+    name: { type: "string", value: "<package>", help: "Package name (default waygraph-map-<group>)" },
+    version: { type: "string", value: "<x.y.z>", help: "Package version (default 0.1.0)" },
+};
+async function packCase(args) {
+    const { values, positionals } = parseCommand("map pack", PACK_OPTIONS, args);
+    const group = positionals[0];
+    if (!group) {
+        console.error("usage: waygraph map pack <group> [project] [--out <dir>] [--name <package>] [--version <x.y.z>]");
+        process.exitCode = 1;
+        return;
+    }
+    const proj = resolve(positionals[1] ?? process.cwd());
+    const result = await packMapGroup(proj, group, { out: values.out, name: values.name, version: values.version });
+    if (!result.ok) {
+        console.error(`waygraph map pack: ${result.reason}`);
+        for (const p of result.problems ?? [])
+            console.error(`  ${relative(proj, p.file)} imports "${p.spec}"`);
+        process.exitCode = 1;
+        return;
+    }
+    console.log(`waygraph map pack: ${result.group} -> ${relative(proj, result.dir) || "."} (${result.name}, ${result.blocks} Blocks)`);
+    console.log(`  publish: cd ${relative(process.cwd(), result.dir) || "."} && npm publish   install elsewhere: npm i ${result.name}`);
+}
+export async function mapCase(args) {
+    if (args[1] === "pack")
+        return packCase(args.slice(2));
+    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/cli/commands/pilot.d.ts

@@ -0,0 +1,2 @@
+/** Runs a `pilot` subcommand; false when it is a session op for session-ops.ts. */
+export declare function pilotCase(args: string[]): Promise<boolean>;

package/dist/cli/commands/pilot.js

@@ -0,0 +1,102 @@
+// `waygraph pilot start | sessions | attach`: a session plus the whole graph and a starting snapshot in one call.
+import { resolve } from "node:path";
+import { envString } from "../../engine/env.js";
+import { listBrowserSessions } from "../../live/auto-session/files.js";
+import { runAttachLoop } from "../../live/auto-session/ipc.js";
+import { pilotAttach, pilotStart } from "../../live/pilot/pilot.js";
+import { resolveInjectRoots } from "../../manifest/roots.js";
+import { resolveBaseUrl } from "../../runtime/waygraph-config.js";
+import { parseCommand } from "../args.js";
+import { applyRunFlags, parseRunFlags } from "../flags.js";
+import { printBrowserSessionsList } from "../usage.js";
+/** Runs a `pilot` subcommand; false when it is a session op for session-ops.ts. */
+export async function pilotCase(args) {
+    if (args[1] === "sessions") {
+        const { values, positionals: positional } = parseCommand("sessions", { json: { type: "boolean", help: "Machine-readable JSON" } }, args.slice(2));
+        const json = values.json === true;
+        const proj = resolve(positional[0] ?? process.cwd());
+        const sessions = listBrowserSessions(proj);
+        if (json) {
+            console.log(JSON.stringify(sessions, null, 2));
+        }
+        else {
+            printBrowserSessionsList(sessions, proj);
+        }
+        return true;
+    }
+    if (args[1] === "attach") {
+        const sessionId = args[2];
+        if (!sessionId) {
+            console.error("waygraph pilot attach: usage: waygraph pilot attach <sessionId> [--inject …] [project]");
+            process.exit(1);
+        }
+        const flags = parseRunFlags(args.slice(3), "pilot");
+        const proj = resolve(flags.positionals[0] ?? process.cwd());
+        try {
+            const inject = flags.inject?.length ? resolveInjectRoots(flags.inject, proj) : undefined;
+            const result = await pilotAttach(proj, sessionId, inject);
+            console.log(JSON.stringify(result));
+        }
+        catch (err) {
+            console.error(`waygraph pilot attach: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+        return true;
+    }
+    if (args[1] === "start" || !args[1] || args[1].startsWith("-")) {
+        const flagArgs = args[1] === "start" ? args.slice(2) : args.slice(1);
+        const flags = parseRunFlags(flagArgs, "pilot");
+        applyRunFlags(flags);
+        const proj = resolve(flags.positionals[0] ?? process.cwd());
+        const baseURL = flags.baseUrl ?? envString("WAYGRAPH_BASE_URL") ?? (await resolveBaseUrl(proj));
+        try {
+            const result = await pilotStart({
+                projectDir: proj,
+                ...(flags.inject?.length ? { injectTokens: flags.inject } : {}),
+                ...(baseURL ? { baseURL } : {}),
+                ...(flags.goto
+                    ? { startUrl: flags.goto, skipInitialNavigation: false }
+                    : flags.blank === true
+                        ? { skipInitialNavigation: true }
+                        : {}),
+                headless: flags.headlessBrowser === true,
+            });
+            console.log(JSON.stringify(result));
+            if (!result.headless) {
+                console.error(`Chromium window opened (session ${result.sessionId}). ` +
+                    `Terminal menu: waygraph pilot attach ${result.sessionId}`);
+            }
+            if (flags.cli) {
+                await runAttachLoop(proj, result.sessionId);
+            }
+        }
+        catch (err) {
+            console.error(`waygraph pilot start: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+        return true;
+    }
+    if (args[1] !== "send" &&
+        args[1] !== "status" &&
+        args[1] !== "dom" &&
+        args[1] !== "trace" &&
+        args[1] !== "console" &&
+        args[1] !== "storage" &&
+        args[1] !== "upload" &&
+        args[1] !== "click" &&
+        args[1] !== "type" &&
+        args[1] !== "press" &&
+        args[1] !== "goto" &&
+        args[1] !== "reload" &&
+        args[1] !== "reach" &&
+        args[1] !== "resync" &&
+        args[1] !== "highlight") {
+        console.error("waygraph pilot: usage:\n" +
+            "  waygraph pilot start [--inject …] [--goto <url>] [--headless] [--cli] [--base-url <url>] [project]\n" +
+            "  waygraph pilot sessions [project]   # list live browser sessions\n" +
+            "  waygraph pilot attach <sessionId>   # graph + snapshot for an existing session\n" +
+            "  waygraph pilot send|status|attach|highlight|… <sessionId> …  (controls browser — same as browser/auto)");
+        process.exit(1);
+    }
+    return false;
+}

package/dist/{commands → cli/commands}/run.d.ts

@@ -1,3 +1,2 @@
 export declare function runCase(args: string[]): Promise<void>;
-export declare function chainCase(args: string[]): Promise<void>;
 export declare function demoCase(args: string[]): Promise<void>;

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/cli/commands/session-ops.d.ts

@@ -0,0 +1,3 @@
+/** Whether `sub` is a session op (`attach` is pilot's own subcommand, not an op, under `pilot`). */
+export declare function isSessionOp(command: string, sub: string | undefined): boolean;
+export declare function sessionOpCase(args: string[], command: string): Promise<void>;