waygraph 0.15.54 → 0.16.1

package/dist/cli/args.js

@@ -0,0 +1,20 @@
+// Every command's flags, read with node:util's parseArgs from the command's own table, which also prints its help. An
+// unknown flag or a flag missing its value stops the command with the reason.
+import { parseArgs } from "node:util";
+export function parseCommand(command, table, argv) {
+    const options = Object.fromEntries(Object.entries(table).map(([name, o]) => [name, { type: o.type, multiple: o.multiple === true }]));
+    try {
+        const { values, positionals, tokens } = parseArgs({ args: argv, options, allowPositionals: true, strict: true, tokens: true });
+        return { values: values, positionals, tokens };
+    }
+    catch (err) {
+        console.error(`waygraph ${command}: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+}
+/** The table as aligned help lines (`--name <value>  help`). */
+export function helpLines(table, indent = 2) {
+    const rows = Object.entries(table).map(([name, o]) => [`--${name}${o.value ? " " + o.value : ""}`, o.help]);
+    const width = Math.max(...rows.map(([flag]) => flag.length)) + 2;
+    return rows.map(([flag, help]) => " ".repeat(indent) + flag.padEnd(width) + help).join("\n");
+}

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

@@ -10,7 +10,6 @@
  *
  * Also: list / nav / validate / check / graph / init / agent-dive / traverse / try
  * Skills: --skill / --skill-pilot / --skill-pilot-blind / --skill-convention
- * Aliases (one release): `chain` -> run/demo --blocks; `--autoplay` -> `--auto-next`
  *
  * "project" defaults to cwd. Flags beat WAYGRAPH_* env.
  */

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

@@ -10,17 +10,16 @@
  *
  * Also: list / nav / validate / check / graph / init / agent-dive / traverse / try
  * Skills: --skill / --skill-pilot / --skill-pilot-blind / --skill-convention
- * Aliases (one release): `chain` -> run/demo --blocks; `--autoplay` -> `--auto-next`
  *
  * "project" defaults to cwd. Flags beat WAYGRAPH_* env.
  */
 import { SKILL_FLAG_MAP, printSkillIndex, readSkillMarkdown } from "./commands/agent-dive-scaffold.js";
-import { takeEnvFlag } from "./env-file.js";
-import { takeConfigFlag } from "./config.js";
-import { usage } from "./cli/usage.js";
+import { takeEnvFlag } from "../runtime/env-file.js";
+import { takeConfigFlag } from "../runtime/waygraph-config.js";
+import { usage } from "./usage.js";
 import { listCase, navCase } from "./commands/list.js";
 import { checkCase, typecheckCase, validateCase } from "./commands/check.js";
-import { chainCase, demoCase, runCase } from "./commands/run.js";
+import { demoCase, runCase } from "./commands/run.js";
 import { testCase } from "./commands/test.js";
 import { initCase } from "./commands/init.js";
 import { traverseCase } from "./commands/traverse.js";
@@ -28,12 +27,14 @@ import { agentDiveCase } from "./commands/agent-dive.js";
 import { autoServeCase, sessionCase } from "./commands/session.js";
 import { tryCase } from "./commands/try.js";
 import { upgradeCase } from "./commands/upgrade.js";
+import { manifestCase } from "./commands/manifest.js";
 import { extensionsCase } from "./commands/extensions.js";
 import { mapCase } from "./commands/map.js";
+import { setEnv } from "../engine/env.js";
 const args = takeConfigFlag(takeEnvFlag(process.argv.slice(2)));
 const command = args[0];
 if (command)
-    process.env.WAYGRAPH_COMMAND = command;
+    setEnv("WAYGRAPH_COMMAND", command);
 async function main() {
     if (!command || command === "--help" || command === "-h") {
         usage();
@@ -73,9 +74,6 @@ async function main() {
         case "init-agents":
             await agentDiveCase(args);
             break;
-        case "chain":
-            await chainCase(args);
-            break;
         case "demo":
             await demoCase(args);
             break;
@@ -106,6 +104,9 @@ async function main() {
         case "upgrade":
             await upgradeCase(args);
             break;
+        case "manifest":
+            await manifestCase(args);
+            break;
         case "extensions":
             await extensionsCase(args);
             break;

package/dist/{commands → cli/commands}/agent-dive-scaffold.js

@@ -5,9 +5,10 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
 function packageRoot() {
     // dist/commands/agent-dive-scaffold.js -> ../..
-    return resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+    return resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
 }
 function agentsTemplateDir() {
     return join(packageRoot(), "templates", "agents");
@@ -15,46 +16,33 @@ function agentsTemplateDir() {
 function skillsTemplateDir() {
     return join(packageRoot(), "templates", "skills");
 }
-/** Minimal YAML-ish frontmatter parser for `*.agent.md` templates. */
-function parseAgentSpec(filePath) {
+/** A markdown file's YAML frontmatter (between the leading `---` lines) and its body. */
+function readFrontmatter(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$/, "");
+    const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(raw);
+    if (!m)
+        throw new Error(`agent-dive: missing or unclosed frontmatter in ${filePath}`);
+    const data = parseYaml(m[1]);
+    if (data === null || typeof data !== "object" || Array.isArray(data))
+        throw new Error(`agent-dive: frontmatter in ${filePath} is not a mapping`);
+    return { data: data, body: m[2].trim() };
+}
+/** Markdown with `data` as YAML frontmatter. */
+function withFrontmatter(data, body) {
+    return `---\n${stringifyYaml(data, { lineWidth: 0 })}---\n\n${body}\n`;
+}
+function parseAgentSpec(filePath) {
+    const { data, body } = readFrontmatter(filePath);
+    const text = (k) => (typeof data[k] === "string" && data[k] !== "" ? data[k] : undefined);
+    const name = text("name") ?? basename(filePath).replace(/\.(agent|skill)\.md$/, "");
+    const model = text("model");
+    const color = text("color");
     return {
         name,
-        description: meta.description || name,
-        ...(meta.model ? { model: meta.model } : {}),
-        ...(meta.color ? { color: meta.color } : {}),
-        tools: lists.tools ?? [],
+        description: text("description") ?? name,
+        ...(model ? { model } : {}),
+        ...(color ? { color } : {}),
+        tools: Array.isArray(data.tools) ? data.tools.map(String) : [],
         instructions: body,
     };
 }
@@ -126,42 +114,25 @@ function writeFileLogged(path, content, kind) {
     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");
+    return withFrontmatter({
+        name: agent.name,
+        description: agent.description,
+        ...(agent.model ? { model: agent.model } : {}),
+        ...(agent.color ? { color: agent.color } : {}),
+        ...(agent.tools.length ? { tools: agent.tools.join(", ") } : {}),
+    }, agent.instructions);
 }
 function opencodePromptMd(agent) {
     return `${agent.instructions}\n`;
 }
 function cursorRuleMdc(agent) {
-    return `---
-description: ${agent.description}
-globs:
-alwaysApply: false
----
-
-# ${agent.name}
-
-${agent.instructions}
-`;
+    return withFrontmatter({ description: agent.description, globs: null, alwaysApply: false }, `# ${agent.name}\n\n${agent.instructions}`);
 }
 function vscodeAgentMd(agent) {
     return claudeAgentMd(agent);
 }
 function claudeSkillMd(skill) {
-    const lines = ["---", `name: ${skill.name}`, `description: ${skill.description}`, "---", "", skill.instructions, ""];
-    return lines.join("\n");
+    return withFrontmatter({ name: skill.name, description: skill.description }, skill.instructions);
 }
 export function runAgentDive(opts) {
     const agents = loadAgentSpecs();

package/dist/cli/commands/agent-dive.js

@@ -0,0 +1,42 @@
+import { runAgentDive } from "./agent-dive-scaffold.js";
+import { resolve } from "node:path";
+import { existsSync, statSync } from "node:fs";
+import { helpLines, parseCommand } from "../args.js";
+const LOOPS = ["claude", "opencode", "cursor", "vscode"];
+const OPTIONS = {
+    loop: { type: "string", value: "claude|opencode|cursor|vscode", help: "Which agent tool to write for (default claude)" },
+    prompts: { type: "boolean", help: "Also copy docs/waygraph-agents/*.md" },
+    help: { type: "boolean", help: "This help" },
+};
+export async function agentDiveCase(args) {
+    // Playwright analogue: npx playwright init-agents --loop <provider>
+    const { values, positionals } = parseCommand("agent-dive", OPTIONS, args.slice(1));
+    if (values.help) {
+        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).
+
+${helpLines(OPTIONS)}
+
+  --loop claude writes .claude/agents/*.md, opencode .opencode/prompts/*.md,
+  cursor .cursor/rules/waygraph-*.mdc, vscode .github/agents/*.md.
+
+Agents shipped: waygraph-planner, waygraph-author, waygraph-healer.
+`);
+        process.exit(0);
+    }
+    const loop = (values.loop ?? "claude");
+    if (!LOOPS.includes(loop)) {
+        console.error("waygraph agent-dive: --loop must be claude | opencode | cursor | vscode");
+        process.exit(1);
+    }
+    const prompts = values.prompts === true;
+    const projectDir = resolve(positionals[0] ?? process.cwd());
+    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/cli/commands/browser.d.ts

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

package/dist/cli/commands/browser.js

@@ -0,0 +1,109 @@
+// `waygraph browser start | sessions | stop`: start a detached session, list them, stop them. The session ops
+// (send, status, ...) are session-ops.ts.
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { envString } from "../../engine/env.js";
+import { listBrowserSessions, stopAllBrowserSessions, stopBrowserSession } from "../../live/auto-session/files.js";
+import { runAttachLoop } from "../../live/auto-session/ipc.js";
+import { browserStart } from "../../live/auto-session/start.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, printBrowserUsage } from "../usage.js";
+/** Runs a `browser` subcommand; false when it is a session op for session-ops.ts. */
+export async function browserCase(args) {
+    const sub = args[1];
+    if (sub === "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 (sub === "stop") {
+        const proj = resolve(args[3] ?? process.cwd());
+        const target = args[2];
+        if (!target) {
+            console.error("waygraph browser stop: usage: waygraph browser stop <sessionId|--all> [project]");
+            process.exit(1);
+        }
+        if (target === "--all") {
+            const n = stopAllBrowserSessions(proj);
+            console.log(JSON.stringify({ stopped: n, projectDir: proj }));
+            return true;
+        }
+        if (!stopBrowserSession(proj, target)) {
+            console.error(`waygraph browser stop: no such session "${target}"`);
+            process.exit(1);
+        }
+        console.log(JSON.stringify({ stopped: target }));
+        return true;
+    }
+    if (!sub) {
+        printBrowserUsage();
+        return true;
+    }
+    if (sub === "start" || sub.startsWith("-")) {
+        const flagArgs = sub === "start" ? args.slice(2) : args.slice(1);
+        const flags = parseRunFlags(flagArgs, "browser");
+        applyRunFlags(flags);
+        const proj = resolve(flags.positionals[0] ?? process.cwd());
+        if (!existsSync(proj)) {
+            console.error(`waygraph browser: no such directory: ${proj}`);
+            process.exit(1);
+        }
+        const baseURL = flags.baseUrl ?? envString("WAYGRAPH_BASE_URL") ?? (await resolveBaseUrl(proj));
+        try {
+            const inject = flags.inject?.length ? resolveInjectRoots(flags.inject, proj) : undefined;
+            const result = await browserStart({
+                projectDir: proj,
+                ...(inject?.length ? { inject } : {}),
+                ...(baseURL ? { baseURL } : {}),
+                ...(flags.goto
+                    ? { startUrl: flags.goto, skipInitialNavigation: false }
+                    : { skipInitialNavigation: flags.blank !== false }),
+                headless: flags.headlessBrowser === true,
+            });
+            console.log(JSON.stringify(result));
+            if (!result.headless) {
+                console.error(`Session ${result.sessionId} started. List all: waygraph browser sessions`);
+            }
+            if (flags.cli) {
+                await runAttachLoop(proj, result.sessionId);
+            }
+        }
+        catch (err) {
+            console.error(`waygraph browser start: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+        return true;
+    }
+    if (sub !== "send" &&
+        sub !== "status" &&
+        sub !== "attach" &&
+        sub !== "dom" &&
+        sub !== "trace" &&
+        sub !== "console" &&
+        sub !== "storage" &&
+        sub !== "upload" &&
+        sub !== "click" &&
+        sub !== "type" &&
+        sub !== "press" &&
+        sub !== "goto" &&
+        sub !== "reload" &&
+        sub !== "reach" &&
+        sub !== "resync" &&
+        sub !== "highlight") {
+        console.error("waygraph browser: unknown subcommand — run `waygraph browser` for usage");
+        printBrowserUsage();
+        process.exit(1);
+    }
+    return false;
+}

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

@@ -1,4 +1,3 @@
-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/cli/commands/check.js

@@ -0,0 +1,104 @@
+import { relative, resolve } from "node:path";
+import { findOrphanBlocks } from "../../analysis/graph.js";
+import { checkMapGroups, checkProject, validateFlows } from "../../analysis/check.js";
+import { parseRunFlags } from "../flags.js";
+import { walkDir } from "../../manifest/scan.js";
+import { collectPracticeWarnings, practiceKindLabel } from "../../analysis/practices-check.js";
+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 used in any flow - wire it into a .flow.ts before chain auto shorthand`);
+    }
+    console.log(`waygraph check: ${orphans.length} orphan Block${orphans.length === 1 ? "" : "s"}`);
+}
+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 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), args[0] ?? "check");
+    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), args[0] ?? "check");
+    const proj = resolve(flags.positionals[0] ?? process.cwd());
+    const { navWarnings, selWarnings, practiceWarnings } = await checkProject(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 groupProblems = checkMapGroups(proj);
+    for (const p of groupProblems) {
+        console.warn(`waygraph check: ${relative(proj, p.file)} imports "${p.spec}" from outside map group ${p.group} - a group imports only waygraph and its own files, so it can be packed`);
+    }
+    if (groupProblems.length > 0)
+        console.log(`waygraph check: ${groupProblems.length} map group import warning${groupProblems.length === 1 ? "" : "s"}`);
+    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/cli/commands/codemod-checkpoints.d.ts

@@ -0,0 +1,18 @@
+/** Checkpoint name -> tag, and union aliases -> member names, found in the states files. */
+interface StatesInfo {
+    tags: Map<string, string>;
+    unions: Map<string, string[]>;
+}
+/** Rewrites one states file; returns the new text and what it declared. */
+export declare function convertStates(text: string, info: StatesInfo): string;
+/** Rewrites one Block file. Calls whose Checkpoints are not plain declared names are left as they are. */
+export declare function convertBlocks(text: string, info: StatesInfo): {
+    text: string;
+    skipped: string[];
+};
+/** Runs the codemod over a project; returns the files changed and the calls it left alone. */
+export declare function codemodCheckpoints(projectDir: string): {
+    changed: string[];
+    skipped: string[];
+};
+export {};