waygraph 0.12.6 → 0.12.8

package/README.md

@@ -89,7 +89,8 @@ Live reference: `examples/saucedemo/src/blocks/saucedemo-web/inventory/`
 |------|---------|
 | Watch Sauce Demo step-through (temp dir only) | `npx waygraph try demo` |
 | Interactive explore (Add/Remove/Open details from live page) | `cd examples/saucedemo && npm i && npx waygraph auto` |
-| Scaffold a new **offline** project (green `npm test` on a `data:` URL) | `npx create-waygraph my-app` **or** `npx waygraph init my-app` |
+| Scaffold a new **offline** project (green `npm test` on local fixture `:4177`) | `npx create-waygraph my-app` **or** `npx waygraph init my-app` |
+| Install coding-agent defs for diving an app into Blocks | `npx waygraph agent-dive --loop claude` (also `opencode` / `cursor` / `vscode`) |
 | Add waygraph to an existing repo | `npm install waygraph @playwright/test` |
 
 **Scaffold is not hidden inside waygraph alone** - the offline starter also ships as

package/dist/agent-dive.d.ts

@@ -0,0 +1,19 @@
+export type AgentDiveLoop = "claude" | "opencode" | "cursor" | "vscode";
+export interface AgentSpec {
+    name: string;
+    description: string;
+    model?: string;
+    color?: string;
+    tools: string[];
+    instructions: string;
+}
+/** Minimal YAML-ish frontmatter parser for `*.agent.md` templates. */
+export declare function parseAgentSpec(filePath: string): AgentSpec;
+export declare function loadAgentSpecs(): AgentSpec[];
+export interface AgentDiveOptions {
+    loop: AgentDiveLoop;
+    projectDir: string;
+    /** Also copy raw prompts under docs/waygraph-agents/ */
+    prompts?: boolean;
+}
+export declare function runAgentDive(opts: AgentDiveOptions): void;

package/dist/agent-dive.js

@@ -0,0 +1,162 @@
+/**
+ * `waygraph agent-dive` — initialize coding-agent definitions for diving an app
+ * into waygraph Blocks (Playwright `init-agents` analogue).
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+function packageRoot() {
+    // dist/agent-dive.js -> ..
+    return resolve(dirname(fileURLToPath(import.meta.url)), "..");
+}
+function agentsTemplateDir() {
+    return join(packageRoot(), "templates", "agents");
+}
+/** Minimal YAML-ish frontmatter parser for `*.agent.md` templates. */
+export function parseAgentSpec(filePath) {
+    const raw = readFileSync(filePath, "utf-8");
+    if (!raw.startsWith("---\n")) {
+        throw new Error(`agent-dive: missing frontmatter in ${filePath}`);
+    }
+    const end = raw.indexOf("\n---\n", 4);
+    if (end < 0)
+        throw new Error(`agent-dive: unclosed frontmatter in ${filePath}`);
+    const fm = raw.slice(4, end);
+    const body = raw.slice(end + 5).trim();
+    const meta = {};
+    let listKey = null;
+    const lists = {};
+    for (const line of fm.split("\n")) {
+        if (/^\s+-\s+/.test(line) && listKey) {
+            lists[listKey].push(line.replace(/^\s+-\s+/, "").trim());
+            continue;
+        }
+        listKey = null;
+        const m = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line);
+        if (!m)
+            continue;
+        const key = m[1];
+        const val = m[2].trim();
+        if (val === "") {
+            listKey = key;
+            lists[key] = [];
+        }
+        else {
+            meta[key] = val;
+        }
+    }
+    const name = meta.name || basename(filePath).replace(/\.agent\.md$/, "");
+    return {
+        name,
+        description: meta.description || name,
+        ...(meta.model ? { model: meta.model } : {}),
+        ...(meta.color ? { color: meta.color } : {}),
+        tools: lists.tools ?? [],
+        instructions: body,
+    };
+}
+export function loadAgentSpecs() {
+    const dir = agentsTemplateDir();
+    if (!existsSync(dir)) {
+        throw new Error(`agent-dive: templates missing at ${dir}`);
+    }
+    return readdirSync(dir)
+        .filter((f) => f.endsWith(".agent.md"))
+        .sort()
+        .map((f) => parseAgentSpec(join(dir, f)));
+}
+function writeFileLogged(path, content, kind) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, content.endsWith("\n") ? content : content + "\n");
+    console.log(`  wrote ${path} (${kind})`);
+}
+function claudeAgentMd(agent) {
+    const tools = agent.tools.join(", ");
+    const lines = [
+        "---",
+        `name: ${agent.name}`,
+        `description: ${agent.description}`,
+        ...(agent.model ? [`model: ${agent.model}`] : []),
+        ...(agent.color ? [`color: ${agent.color}`] : []),
+        ...(tools ? [`tools: ${tools}`] : []),
+        "---",
+        "",
+        agent.instructions,
+        "",
+    ];
+    return lines.join("\n");
+}
+function opencodePromptMd(agent) {
+    return `${agent.instructions}\n`;
+}
+function cursorRuleMdc(agent) {
+    return `---
+description: ${agent.description}
+globs:
+alwaysApply: false
+---
+
+# ${agent.name}
+
+${agent.instructions}
+`;
+}
+function vscodeAgentMd(agent) {
+    return claudeAgentMd(agent);
+}
+export function runAgentDive(opts) {
+    const agents = loadAgentSpecs();
+    const root = opts.projectDir;
+    console.log(`waygraph agent-dive (${opts.loop}) -> ${root}`);
+    console.log(`  ${agents.length} agent(s) from package templates`);
+    switch (opts.loop) {
+        case "claude": {
+            const dir = join(root, ".claude", "agents");
+            mkdirSync(dir, { recursive: true });
+            for (const a of agents) {
+                writeFileLogged(join(dir, `${a.name}.md`), claudeAgentMd(a), "claude agent");
+            }
+            break;
+        }
+        case "opencode": {
+            const dir = join(root, ".opencode", "prompts");
+            mkdirSync(dir, { recursive: true });
+            for (const a of agents) {
+                writeFileLogged(join(dir, `${a.name}.md`), opencodePromptMd(a), "opencode prompt");
+            }
+            break;
+        }
+        case "cursor": {
+            const dir = join(root, ".cursor", "rules");
+            mkdirSync(dir, { recursive: true });
+            for (const a of agents) {
+                writeFileLogged(join(dir, `${a.name}.mdc`), cursorRuleMdc(a), "cursor rule");
+            }
+            break;
+        }
+        case "vscode": {
+            const dir = join(root, ".github", "agents");
+            mkdirSync(dir, { recursive: true });
+            for (const a of agents) {
+                writeFileLogged(join(dir, `${a.name}.md`), vscodeAgentMd(a), "vscode agent");
+            }
+            break;
+        }
+        default: {
+            const _exhaustive = opts.loop;
+            throw new Error(`agent-dive: unsupported loop ${_exhaustive}`);
+        }
+    }
+    if (opts.prompts) {
+        const dir = join(root, "docs", "waygraph-agents");
+        mkdirSync(dir, { recursive: true });
+        for (const a of agents) {
+            writeFileLogged(join(dir, `${a.name}.md`), `# ${a.name}\n\n${a.description}\n\n${a.instructions}\n`, "prompt copy");
+        }
+    }
+    console.log("");
+    console.log("Next: point your coding agent at those files, then:");
+    console.log("  npx waygraph check .");
+    console.log("  npx waygraph auto --cli");
+    console.log("  (scaffold: npx waygraph init my-app)");
+}

package/dist/auto-explore-run.d.ts

@@ -5,6 +5,11 @@ export interface AutoExploreOptions {
     /** Initial URL when the page is blank (defaults to baseURL). */
     startUrl?: string;
 }
+/**
+ * Saucedemo-only defaults. Exact key names only — never substring `"login"`
+ * (PIA `login-email` string must stay unset; see docs/proposals/auto-login-email-seed-bug.md).
+ */
+export declare function defaultMemValueForKey(keyName: string): unknown | undefined;
 /**
  * Interactive waygraph auto: locate current Checkpoint, list runnable Blocks, pick one, repeat.
  */

package/dist/auto-explore-run.js

@@ -77,12 +77,24 @@ function missingMemKeys(entry, mem) {
     return requires.filter((k) => !mem.has(k));
 }
 const DEFAULT_CREDENTIALS = { username: "standard_user", password: "secret_sauce" };
-function defaultMemValueForKey(keyName) {
-    if (keyName.includes("credential") || keyName.includes("login")) {
+/**
+ * Saucedemo-only defaults. Exact key names only — never substring `"login"`
+ * (PIA `login-email` string must stay unset; see docs/proposals/auto-login-email-seed-bug.md).
+ */
+export function defaultMemValueForKey(keyName) {
+    if (keyName === "login-credentials" ||
+        keyName === "credentials" ||
+        keyName === "saucedemo.credentials") {
         return DEFAULT_CREDENTIALS;
     }
     return undefined;
 }
+function defaultMemJsonPrompt(keyName) {
+    const def = defaultMemValueForKey(keyName);
+    if (def !== undefined)
+        return JSON.stringify(def);
+    return "{}";
+}
 function seedMemFromEnv(mem, entry) {
     const raw = process.env.WAYGRAPH_DATA ?? process.env.WAYGRAPH_AUTO_MEM;
     if (!raw)
@@ -129,9 +141,7 @@ async function promptMemCli(entry, mem) {
     const rl = createInterface({ input, output });
     try {
         for (const k of missingMemKeys(entry, mem)) {
-            const def = k.name.includes("credential") || k.name.includes("login")
-                ? '{"username":"standard_user","password":"secret_sauce"}'
-                : "{}";
+            const def = defaultMemJsonPrompt(k.name);
             const line = await rl.question(`  ${k.name} JSON [${def}]: `);
             const json = line.trim() || def;
             mem.set(k, JSON.parse(json));

package/dist/cli.d.ts

@@ -7,7 +7,7 @@
  *   demo   Watch (step overlay); `--blocks` `--data` `--auto-next` `--fast` `--full` `--ff-expand`
  *   run    Execute; `--blocks` `--data` `--non-headless` `--video`
  *
- * Also: list / nav / validate / check / graph / init / try
+ * Also: list / nav / validate / check / graph / init / agent-dive / traverse / try
  * Aliases (one release): `chain` -> run/demo --blocks; `--autoplay` -> `--auto-next`
  *
  * "project" defaults to cwd. Flags beat WAYGRAPH_* env.

package/dist/cli.js

@@ -7,7 +7,7 @@
  *   demo   Watch (step overlay); `--blocks` `--data` `--auto-next` `--fast` `--full` `--ff-expand`
  *   run    Execute; `--blocks` `--data` `--non-headless` `--video`
  *
- * Also: list / nav / validate / check / graph / init / try
+ * Also: list / nav / validate / check / graph / init / agent-dive / traverse / try
  * Aliases (one release): `chain` -> run/demo --blocks; `--autoplay` -> `--auto-next`
  *
  * "project" defaults to cwd. Flags beat WAYGRAPH_* env.
@@ -19,6 +19,8 @@ import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
 import { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./graph.js";
 import { runAutoExplore } from "./auto-explore-run.js";
+import { runAgentDive } from "./agent-dive.js";
+import { runTraverse } from "./traverse-run.js";
 // ---------------------------------------------------------------------------
 // Filesystem
 // ---------------------------------------------------------------------------
@@ -3660,6 +3662,14 @@ Primary (less is more):
 
 Also:
   waygraph list | nav | validate | check | graph | init <name>
+  waygraph traverse [project]              Serial graph crawl (Phase B)
+                 --from <Checkpoint>       Seed / start checkpoint
+                 --data '{...}'            Mem seed
+                 --max-steps N             Cap Block runs (default 50)
+                 --max-visits N            Cap visits per node (default 2)
+                 --non-headless            Show browser
+  waygraph agent-dive [--loop claude|opencode|cursor|vscode] [--prompts]
+                 Initialize coding-agent defs (Playwright init-agents analogue)
   waygraph try [demo|auto|auto:cli]        One-shot saucedemo in a temp dir
                  try auto                  Headed browser panel (default)
                  try auto:cli / --cli      Terminal menu instead
@@ -3756,6 +3766,147 @@ async function main() {
             initCommand(args[1] ?? "");
             break;
         }
+        case "traverse": {
+            if (args.includes("--step") || args.includes("--auto-next") || args.includes("--autoplay")) {
+                console.error("waygraph traverse: --step / --auto-next not supported (not a demo)");
+                process.exit(1);
+            }
+            const rest = args.slice(1);
+            let from;
+            let data;
+            let maxSteps;
+            let maxVisits;
+            let maxEdge;
+            let headed = false;
+            let baseUrl;
+            let projectDir = process.cwd();
+            for (let i = 0; i < rest.length; i++) {
+                const a = rest[i];
+                if (a === "--from" || a.startsWith("--from=")) {
+                    from = a.startsWith("--from=") ? a.slice(7) : rest[++i];
+                    continue;
+                }
+                if (a === "--data" || a.startsWith("--data=")) {
+                    data = a.startsWith("--data=") ? a.slice(7) : rest[++i];
+                    continue;
+                }
+                if (a === "--max-steps" || a.startsWith("--max-steps=")) {
+                    const v = a.startsWith("--max-steps=") ? a.slice(12) : rest[++i];
+                    maxSteps = Number(v);
+                    continue;
+                }
+                if (a === "--max-visits" || a.startsWith("--max-visits=")) {
+                    const v = a.startsWith("--max-visits=") ? a.slice(13) : rest[++i];
+                    maxVisits = Number(v);
+                    continue;
+                }
+                if (a === "--max-visits-per-edge" || a.startsWith("--max-visits-per-edge=")) {
+                    const v = a.startsWith("--max-visits-per-edge=")
+                        ? a.slice("--max-visits-per-edge=".length)
+                        : rest[++i];
+                    maxEdge = Number(v);
+                    continue;
+                }
+                if (a === "--non-headless" || a === "--headed") {
+                    headed = true;
+                    continue;
+                }
+                if (a === "--base-url" || a.startsWith("--base-url=")) {
+                    baseUrl = a.startsWith("--base-url=") ? a.slice(11) : rest[++i];
+                    continue;
+                }
+                if (a === "--help" || a === "-h") {
+                    console.log(`waygraph traverse [project] [flags]
+
+Serial graph crawl (RFC Phase B). Walks unused legal edges until a leaf,
+budget kill, or first broken edge.
+
+  --from <Checkpoint>     start checkpoint (optional)
+  --data '{...}'          Mem seed JSON
+  --max-steps N           default 50
+  --max-visits N          per-node visit cap (default 2)
+  --max-visits-per-edge N default 1
+  --non-headless          show browser
+  --base-url URL
+
+PASS:  [Reached Leaf Node[traverse-1] at=... steps=N]
+FAIL:  [Broke at edge[traverse-1] block=... from=... to=...]
+`);
+                    process.exit(0);
+                }
+                if (!a.startsWith("-")) {
+                    projectDir = resolve(a);
+                }
+            }
+            if (!existsSync(projectDir) || !statSync(projectDir).isDirectory()) {
+                console.error(`waygraph traverse: no such directory: ${projectDir}`);
+                process.exit(1);
+            }
+            const code = await runTraverse(projectDir, {
+                ...(from ? { from } : {}),
+                ...(data ? { data } : {}),
+                ...(maxSteps !== undefined && Number.isFinite(maxSteps) ? { maxSteps } : {}),
+                ...(maxVisits !== undefined && Number.isFinite(maxVisits)
+                    ? { maxVisitsPerNode: maxVisits }
+                    : {}),
+                ...(maxEdge !== undefined && Number.isFinite(maxEdge)
+                    ? { maxVisitsPerEdge: maxEdge }
+                    : {}),
+                headed,
+                ...(baseUrl ? { baseURL: baseUrl } : {}),
+            });
+            process.exitCode = code;
+            break;
+        }
+        case "agent-dive":
+        case "init-agents": {
+            // 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 });
+            break;
+        }
         case "chain": {
             // Compat alias: chain auto A B -> auto --blocks A B; else -> run --blocks.
             const flags = parseRunFlags(args.slice(1));

package/dist/traverse-run.d.ts

@@ -0,0 +1,24 @@
+export interface TraverseOptions {
+    baseURL?: string;
+    startUrl?: string;
+    /** Seed checkpoint label (optional - otherwise detect from page / nav). */
+    from?: string;
+    /** Global Mem seed JSON (or use WAYGRAPH_DATA / WAYGRAPH_AUTO_MEM). */
+    data?: string;
+    /** Max Block runs this traverse (default 50). */
+    maxSteps?: number;
+    /** Max times a checkpoint may be visited (default 2). */
+    maxVisitsPerNode?: number;
+    /** Max times an edge key (block::instanceId) may be taken (default 1). */
+    maxVisitsPerEdge?: number;
+    /** Wall-clock budget ms (default 15m). */
+    timeoutMs?: number;
+    /** Show browser (default headless). */
+    headed?: boolean;
+    /** Traverse id for greppable lines (default traverse-1). */
+    traverseId?: string;
+}
+/**
+ * Serial graph crawl. Prints greppable PASS/FAIL lines; non-zero exit on break.
+ */
+export declare function runTraverse(projectDir: string, options?: TraverseOptions): Promise<number>;