waygraph 0.15.53 → 0.16.0

package/templates/skills/waygraph-convention.skill.md

@@ -45,13 +45,15 @@ against a live site, use `--skill-pilot-blind`.
    hand-supplied every time, `registerMemStub(key, fake)` + `memStub: true` on the flow (or
    `--mem-stub`) fills it from a registry instead - a key with no registration still fails
    preflight exactly as before, so this narrows what needs real input, never removes the guard.
-6. **Keep Checkpoints typed.** Block helpers take concrete Checkpoint types from `src/states/`
-   (e.g. `defineMethodBlock<LoginPage, LoggedIn>`). A Block's **output** must never be
-   `Checkpoint<string>` — `waygraph check` / `waygraph typecheck` warn. When a Block runs from a
-   few known states, name them as a union in `src/states/` (`type CanAddItem = Home | CartEmpty`);
-   a `Checkpoint<string>` **input** is only for a Block that's genuinely reachable from anywhere.
-   Same for `defineAssertBlock({…})` without an explicit type arg — use
-   `defineAssertBlock<YourCheckpoint>({…})`.
+   Put those `registerMemStub` calls in a `*.mem-stubs.ts` file (`src/states/demo.mem-stubs.ts`): live sessions (`auto`,
+   `pilot`, `traverse`) load every one and use them as the default for a Block's `requires`.
+6. **Checkpoints are values.** Declare each once in `src/states/`: `export const Home = checkpoint("Home");
+   export type Home = typeof Home;` (a union: `export const CanAddItem = [Home, CartEmpty] as const`). Blocks take
+   the values, never tag strings or `<In, Out>` type arguments: `defineNavBlock({ checkpoint: Home, … })`,
+   `defineAssertBlock({ checkpoint: ItemInCart, … })`, `defineMethodBlock({ from: CanAddItem, to: ItemInCart, … })`
+   (leave `from` out for "from anywhere"; `resolve` is implied when `to` is one Checkpoint). The Block then carries its
+   route at runtime, so `waygraph graph`, `auto` and the manifest read it exactly. Older projects:
+   `waygraph upgrade --codemod checkpoints`.
 7. **One input/action per Method Block.** No block that `.fill()`s two fields or `.fill()` + `.click()` in one
    `act()` — split like saucedemo login (`fill-username`, `fill-password`, `submit-login`). Opt out per file:
    `// waygraph-ignore: multi-input` or `// waygraph-ignore-practices`.
@@ -69,22 +71,23 @@ against a live site, use `--skill-pilot-blind`.
 ## Flows, stubs and config (the scaffold's shape)
 
 - **Build flows with `map()`** (`engine.map({ memStub }).start().gotoPage(Nav).method(B, { pace }).assert(A).end()`;
-  `.gotoExternal` for another origin), never a raw `defineFlow([start, ...])`. Flow settings go in `map({ … })` before the chain
-  and `.end()` takes nothing. The flow's title is `ctx.title(...)` in a stub. **Nest flows with `.flow(sub, { reset: true })`**,
-  not `chainFlow` / `withSessionReset`. No `withMemStub(withTitle(...))` wrappers.
+  `.gotoExternal` for another origin); it is the only way to build one. Flow settings (`memStub`, `expectedFailure`, `demoPace`, `sessionReset`) go in `map({ … })` before the chain
+  and `.end()` takes nothing. The flow's title is `ctx.title(...)` in a stub. **Nest flows with `.flow(sub, { reset: true })`**.
+  `defineFlow`, `chainFlow` and the `with*` flow wrappers were removed in 0.16.0; `waygraph upgrade --codemod flows` converts them.
 - **`src/flows/` holds use cases and mirrors the front end's endpoints**: a folder per page (`flows/auth/login/`) with one
   file per scenario named for its outcome (`success.flow.ts`, `wrong-password.flow.ts`, `empty-fields.flow.ts`), and
   `(user-stories)/` (any `(group)`) for flows that cross pages. Export names are `<page><Outcome>Flow`. Not one file per
   Block chain, not a flat folder of unrelated flows.
 - **Blocks carry no stubs; the flow does.** Demo highlights are ctx stubs chained on the Block where the flow uses it:
   `AddItemBlock.stubAfter((ctx) => { ctx.ring("cart", { selector: DemoSel.cartCount, label: "AC · item in cart" }); })`.
-  Not a static `withHighlightFixtures({ "add-item": { stubAfter: {...} } })` map, and not an inline
-  `instruction: { stubAfter() {} }`. A Block used twice gets one `const AddShown = AddItemBlock.stubAfter(...)`.
+  That chained function is the only form: a Block's definition (its options or `instruction`) takes no stub, and a stub
+  is never a slot map. A Block used twice gets one `const AddShown = AddItemBlock.stubAfter(...)`. A stub that throws
+  fails its step in the demo, named.
 - **Reading a value into `mem` happens in `act`** (`mem.set(Key, value)`), like Mailpit's `extract-email-link`.
   `observe` is only for a Block that branches (it feeds `resolve`); an empty `act(){}` plus an `observe` that
   writes `mem` is a misuse.
 - **Demo pace is a map option or config, never a wrapper.** `.method(SetBearerTokenBlock, { pace: "blitz" })` speeds one step,
-  `map({ demoPace: "fast" })` a flow, `demo: { pace, typingMs, slowMo }` in the config the whole project. Not `withBlockPace(...)`.
+  `map({ demoPace: "fast" })` a flow, `demo: { pace, typingMs, slowMo }` in the config the whole project.
 - **Per-environment values** (a different `baseUrl` for staging) come from `.env` files read in the config function:
   `defineConfig(({ env }) => ({ baseUrl: env.BASE_URL }))`; `--env staging` loads `.env.staging`. Never edit the config to switch.
 - **More than one config** (staging, another app) is another file, `config/waygraph.<name>.config.ts`, chosen with `--config <name>`.
@@ -93,7 +96,7 @@ against a live site, use `--skill-pilot-blind`.
   Block's `act`; the click Block stays a plain click.
 - **Project settings live in `config/waygraph.config.ts`** (`defineConfig({ baseUrl, testDir, webServer,
   extensions, playwright: {...} })`). The config file also exports `engine = new Engine(config)`; flows `import { engine } from "../../config/waygraph.config.js"`; a project needs no
-  `playwright.config.ts` - `waygraph test` builds one from it. A leftover `playwright.config.*` is deprecated.
+  `playwright.config.ts` - `waygraph test` builds one from it (a project's own `playwright.config.*` is not read).
 - **Another origin the test needs is a Map external** under `src/map/(external)/<tool>/`. For REST API
   tests, `(external)/hoppscotch` (list `extensions: ["hoppscotch"]` in the config) drives hoppscotch.io's client
   with the extension, so requests skip CORS: `set-method`, `set-url`, `set-headers`, `set-json-body`,
@@ -110,6 +113,7 @@ against a live site, use `--skill-pilot-blind`.
 | Effect | `*.effect.block.ts` in `methods/` / `_methods/` | `defineEffectBlock` | No |
 | Method | `*.method.block.ts` in `methods/` / `_methods/` | `defineMethodBlock` | No |
 | Assert | with Method/Effect peers | `defineAssertBlock` | No |
+| API | `*.api.block.ts` in `methods/` | `defineApiBlock({ from, to, call })` (a real HTTP request; `map().method(...)`) | No |
 
 Effects that appear in `waygraph auto` menus need `instanceOptions` that scan the live DOM
 (or mem) for labeled rows.
@@ -165,9 +169,14 @@ npx waygraph check --no-practices .   # skip bad-practice scan only
 npx waygraph map .            # exit 1 if src/map/ folder path != real static url
 npx waygraph validate .       # every .flow.ts loads
 npx waygraph graph .          # nodes/edges/skipped/orphans - counts should make sense
+npx waygraph manifest .       # JSON of every Block (kind, from/to, requires), Flow and Checkpoint
+npx waygraph map pack <group> # a src/map/ group with its own _states.ts/_keys.ts -> installable package
 npm run typecheck             # when the consumer has it
 ```
 
+Every `run`/`demo`/`test` also writes `.waygraph/runs/<runId>.jsonl` (step start/end/error, artifacts): read the
+newest one to see which Block failed and with what error, instead of re-running.
+
 `waygraph check` should report zero nav warnings. Orphan Blocks (not in any `.flow.ts`)
 are still runnable in Pilot's live menu - orphan status only blocks
 `auto --blocks <From> <To>` pathfinding.

package/templates/skills/waygraph-pilot.skill.md

@@ -50,6 +50,11 @@ waygraph auto highlight <sessionId> '<json>'  # paint rings/todos on the live pa
 just what's reachable from here - use it to plan several steps ahead before you start
 sending picks.
 
+A Block's `requires` are filled from `--data '{...}'` first, then from the project's mem stubs: the session loads
+every `*.mem-stubs.ts` and uses each `registerMemStub` fake as that key's default. A start URL that can't be opened
+(server down, DNS) fails `browser start` / `pilot start` with the reason; it never starts a blank session silently.
+An unknown flag is an error, not a project path.
+
 ## Bad practices (`waygraph check` / `waygraph typecheck`)
 
 Run `waygraph typecheck .` (or `npm run typecheck`) — runs `tsc --noEmit` then bad-practice warnings.
@@ -58,8 +63,6 @@ Use `--no-practices` on either command to skip the practice scan.
 
 Patterns warned (does not fail `check`; fails `typecheck` only when `tsc` fails):
 
-- **`Checkpoint<string>` as a Block's output** — e.g. `defineMethodBlock<…, Checkpoint<string>>` instead of a project Checkpoint type from `src/states/` (a wildcard *input* means "reachable from anywhere" and is allowed).
-- **`defineAssertBlock({…})` without an explicit type arg** — use `defineAssertBlock<YourCheckpoint>({…})` so `defineFlow` typing stays honest.
 - **Multiple `.fill()` in one Method** — split into one Block per input (fill-username, fill-password, …).
 - **`.fill()` + `.click()` in one Method** — split fill and submit into separate Blocks.
 
@@ -105,7 +108,7 @@ thing that differs from demo is *who* triggers the paint:
 | Mode | Who paints | How |
 |------|------------|-----|
 | `waygraph demo` | Engine, automatically | ctx stubs chained in the flow run each step |
-| Pilot / `auto --detach` | **You (the agent)** | `waygraph auto highlight <sessionId> '<json>'` before (or between) sends |
+| Pilot / `browser start` session | **You (the agent)** | `waygraph auto highlight <sessionId> '<json>'` before (or between) sends |
 
 The ctx stubs a flow chains onto Blocks show up in Pilot's `auto trace` as metadata, but they do **not**
 auto-draw. You re-express the same intent with `auto highlight` (copy selectors/labels from the flow's stubs or
@@ -133,7 +136,7 @@ waygraph auto highlight <sessionId> '{"clear":true}'
 Supported fields (demo parity):
 - `rings[]`: `selector`, `label`, `detail`, `tag`, `tone`, `size`, `weight`, `color`, `zoom`, `zoomOut`, `focus`
 - `todos` / `todoIndex` / `todoTitle` / `todoPos` (`right` default | `left`)
-- `todoUi`: `{ compact?, cap?, expandCap?, collision?, behindRing? }` — same dock UX as demo (defaults smart-on; see docs/REFERENCE.md "Todo dock UI")
+- `todoUi`: `{ compact?, cap?, expandCap?, collision?, behindRing? }` — same dock UX as demo (defaults smart-on; see docs/reference/cli.md "Todo dock UI")
 - `zoom` / `zoomSelector` / `zoomOut` - scroll + zoom badge (not CSS page scale)
 - `device`: `mobile` | `tablet` | `desktop` (Playwright viewport)
 - `holdMs`: ms to keep fixtures; `0` = until the next highlight / clear (default 30000)

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;
-}