waygraph 0.15.23 → 0.15.24

package/dist/commands/agent-dive.d.ts

@@ -0,0 +1 @@
+export declare function agentDiveCase(args: string[]): Promise<void>;

package/dist/commands/agent-dive.js

@@ -0,0 +1,52 @@
+// Split out of the former 8,700-line cli.ts (see src/ARCHITECTURE.md). Behavior unchanged.
+import { runAgentDive } from "../agent-dive.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.d.ts

@@ -0,0 +1,4 @@
+export declare function runChainAuto(projectDir: string, fromTag: string, toTag: string): Promise<void>;
+export declare function validateCase(args: string[]): Promise<void>;
+export declare function typecheckCase(args: string[]): Promise<void>;
+export declare function checkCase(args: string[]): Promise<void>;

package/dist/commands/check.js

@@ -0,0 +1,192 @@
+// 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 "../graph.js";
+import { parseRunFlags, resolveBaseUrl } from "../cli/flags.js";
+import { runChain } from "../cli/run-chain.js";
+import { collectPracticeWarnings, practiceKindLabel } from "../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 = 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/init.d.ts

@@ -0,0 +1 @@
+export declare function initCase(args: string[]): Promise<void>;

package/dist/commands/init.js

@@ -0,0 +1,54 @@
+// Split out of the former 8,700-line cli.ts (see src/ARCHITECTURE.md). Behavior unchanged.
+import { packageRoot } from "../cli/util.js";
+import { basename, join, relative, resolve } from "node:path";
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+function initCommand(projectName) {
+    if (!projectName) {
+        console.error("waygraph init: missing <project-name>, e.g. waygraph init my-app");
+        process.exit(1);
+    }
+    const targetDir = resolve(process.cwd(), projectName);
+    const pkgName = basename(targetDir);
+    if (existsSync(targetDir)) {
+        const entries = readdirSync(targetDir);
+        if (entries.length > 0) {
+            console.error(`waygraph init: "${targetDir}" already exists and is not empty`);
+            process.exit(1);
+        }
+    }
+    else {
+        mkdirSync(targetDir, { recursive: true });
+    }
+    const templateDir = join(packageRoot(), "templates", "scaffold");
+    if (!existsSync(templateDir)) {
+        console.error(`waygraph init: scaffold template missing at ${templateDir}`);
+        process.exit(1);
+    }
+    cpSync(templateDir, targetDir, { recursive: true });
+    const gitignoreSrc = join(targetDir, "gitignore");
+    if (existsSync(gitignoreSrc)) {
+        writeFileSync(join(targetDir, ".gitignore"), readFileSync(gitignoreSrc, "utf-8"));
+        rmSync(gitignoreSrc);
+    }
+    const packageJsonPath = join(targetDir, "package.json");
+    writeFileSync(packageJsonPath, readFileSync(packageJsonPath, "utf-8").replaceAll("__PROJECT_NAME__", pkgName));
+    console.log(`Scaffolded ${pkgName}/`);
+    console.log("");
+    console.log(`  cd ${relative(process.cwd(), targetDir) || pkgName}`);
+    console.log("  npm install");
+    console.log("  npx playwright install chromium");
+    console.log("  npm test");
+    console.log("  waygraph list        # .flow.ts → export map");
+    console.log("  waygraph check       # nav hygiene + inline selectors + bad practices + orphan Blocks");
+    console.log("  waygraph typecheck   # tsc --noEmit + bad-practice warnings (use --no-practices to skip)");
+    console.log("  waygraph auto        # interactive explore (headed panel)");
+    console.log("  waygraph auto --cli  # same menus in the terminal");
+    console.log("  waygraph demo --blocks exampleFlow");
+    console.log("  waygraph graph       # static state graph JSON");
+    console.log("");
+    console.log("  Layout: see STRUCTURE.md (or https://deviate-dv8.github.io/waygraph/scaffold.html)");
+}
+export async function initCase(args) {
+    initCommand(args[1] ?? "");
+    return;
+}

package/dist/commands/list.d.ts

@@ -0,0 +1,2 @@
+export declare function listCase(args: string[]): Promise<void>;
+export declare function navCase(args: string[]): Promise<void>;

package/dist/commands/list.js

@@ -0,0 +1,67 @@
+// 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 { relative, resolve } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+// ---------------------------------------------------------------------------
+// `list`
+// ---------------------------------------------------------------------------
+function listCommand(projectDir) {
+    const files = discoverFlows(projectDir);
+    if (files.length === 0) {
+        console.log(`waygraph: no flows found under ${projectDir}`);
+        return;
+    }
+    for (const file of files) {
+        const rel = relative(projectDir, file);
+        for (const name of extractFlowNames(file)) {
+            console.log(`${rel}  ${name}`);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// `nav`
+// ---------------------------------------------------------------------------
+function navCommand(projectDir, flowName) {
+    const files = discoverFlows(projectDir);
+    const targets = flowName
+        ? files.filter((f) => extractFlowNames(f).includes(flowName))
+        : files;
+    if (targets.length === 0) {
+        console.error(flowName
+            ? `waygraph nav: no flow named "${flowName}" found under ${projectDir}`
+            : `waygraph: no flows found under ${projectDir}`);
+        process.exitCode = 1;
+        return;
+    }
+    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}`));
+                if (!blockFile)
+                    continue;
+                for (const url of extractGotos(blockFile))
+                    console.log(`       goto ${url}`);
+                for (const url of extractUrlTraits(blockFile))
+                    console.log(`       verify url ~ ${url}`);
+            }
+        }
+    }
+}
+export async function listCase(args) {
+    const proj = resolve(args[1] ?? process.cwd());
+    if (!existsSync(proj)) {
+        console.error(`waygraph: no such directory: ${proj}`);
+        process.exit(1);
+    }
+    listCommand(proj);
+    return;
+}
+export async function navCase(args) {
+    const flowName = args[1] && args[1] !== "." ? args[1] : undefined;
+    const proj = resolve(args[2] ?? process.cwd());
+    navCommand(proj, flowName);
+    return;
+}

package/dist/commands/map.d.ts

@@ -0,0 +1 @@
+export declare function mapCase(args: string[]): Promise<void>;

package/dist/commands/map.js

@@ -0,0 +1,29 @@
+// 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 "../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.d.ts

@@ -0,0 +1,3 @@
+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/commands/run.js

@@ -0,0 +1,104 @@
+// 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 = 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 = 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") {
+        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";
+    }
+    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;
+}

package/dist/commands/session.d.ts

@@ -0,0 +1,2 @@
+export declare function sessionCase(args: string[], command: string | undefined): Promise<void>;
+export declare function autoServeCase(args: string[]): Promise<void>;