waygraph 0.15.53 → 0.16.0

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

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

@@ -0,0 +1,186 @@
+// `waygraph upgrade --codemod checkpoints`: rewrites a project from tag strings and `<In, Out>` type arguments to
+// Checkpoint values (`export const Home = checkpoint("Home")`, `checkpoint: Home`, `from: Home, to: ItemInCart`). Works
+// on the TypeScript AST (ts-morph), so formatting, comments and odd line breaks don't fool it.
+import { readFileSync, writeFileSync } from "node:fs";
+import { relative } from "node:path";
+import { IndentationText, Node, Project, SyntaxKind } from "ts-morph";
+import { walkDir } from "../../manifest/scan.js";
+function parse(text) {
+    const indentationText = /\n\t/.test(text) ? IndentationText.Tab : /\n {4}\S/.test(text) && !/\n {2}\S/.test(text) ? IndentationText.FourSpaces : IndentationText.TwoSpaces;
+    return new Project({ useInMemoryFileSystem: true, manipulationSettings: { indentationText } }).createSourceFile("/file.ts", text);
+}
+/** Whether `name` is still used anywhere outside import statements. */
+function usedOutsideImports(sf, name) {
+    return sf.getDescendantsOfKind(SyntaxKind.Identifier).some((id) => {
+        if (id.getText() !== name || id.getFirstAncestorByKind(SyntaxKind.ImportDeclaration))
+            return false;
+        const parent = id.getParent();
+        return !(Node.isPropertyAccessExpression(parent) && parent.getNameNode() === id) && !(Node.isPropertyAssignment(parent) && parent.getNameNode() === id);
+    });
+}
+/** Drops a named import from "waygraph" that nothing uses any more (and the import, when it ends up empty). */
+function dropUnusedWaygraphImport(sf, name) {
+    if (usedOutsideImports(sf, name))
+        return;
+    for (const imp of sf.getImportDeclarations().filter((d) => d.getModuleSpecifierValue() === "waygraph")) {
+        imp.getNamedImports().find((n) => n.getName() === name)?.remove();
+        if (imp.getNamedImports().length === 0 && !imp.getDefaultImport() && !imp.getNamespaceImport())
+            imp.remove();
+    }
+}
+/** Learns Checkpoint declarations already in value form, so the codemod can run again after a partial run. */
+function learnValues(sf, info) {
+    for (const decl of sf.getVariableDeclarations()) {
+        const init = decl.getInitializer();
+        if (Node.isCallExpression(init) && init.getExpression().getText() === "checkpoint") {
+            const tag = init.getArguments()[0];
+            if (Node.isStringLiteral(tag))
+                info.tags.set(decl.getName(), tag.getLiteralValue());
+        }
+        else if (Node.isAsExpression(init) && Node.isArrayLiteralExpression(init.getExpression())) {
+            info.unions.set(decl.getName(), init.getExpression().asKindOrThrow(SyntaxKind.ArrayLiteralExpression).getElements().map((e) => e.getText()));
+        }
+    }
+}
+/** Rewrites one states file; returns the new text and what it declared. */
+export function convertStates(text, info) {
+    const sf = parse(text);
+    learnValues(sf, info);
+    let changed = false;
+    for (const alias of sf.getTypeAliases()) {
+        if (!alias.isExported())
+            continue;
+        const name = alias.getName();
+        const type = alias.getTypeNodeOrThrow();
+        if (Node.isTypeReference(type) && type.getTypeName().getText() === "Checkpoint") {
+            const arg = type.getTypeArguments()[0];
+            if (!Node.isLiteralTypeNode(arg) || !Node.isStringLiteral(arg.getLiteral()))
+                continue;
+            const tag = arg.getLiteral().asKindOrThrow(SyntaxKind.StringLiteral).getLiteralValue();
+            info.tags.set(name, tag);
+            alias.replaceWithText(`export const ${name} = checkpoint("${tag}");\nexport type ${name} = typeof ${name};`);
+            changed = true;
+        }
+        else if (Node.isUnionTypeNode(type)) {
+            const names = type.getTypeNodes().map((t) => t.getText());
+            if (!names.every((n) => info.tags.has(n) || info.unions.has(n)))
+                continue;
+            const flat = names.flatMap((n) => info.unions.get(n) ?? [n]);
+            info.unions.set(name, flat);
+            alias.replaceWithText(`export const ${name} = [${flat.join(", ")}] as const;\nexport type ${name} = (typeof ${name})[number];`);
+            changed = true;
+        }
+    }
+    if (!changed)
+        return text;
+    // `checkpoint` is now used as a value; `Checkpoint` stays only while something still names the type.
+    const wg = sf.getImportDeclarations().find((d) => d.getModuleSpecifierValue() === "waygraph");
+    if (!wg)
+        sf.insertImportDeclaration(0, { moduleSpecifier: "waygraph", namedImports: ["checkpoint"] });
+    else if (wg.isTypeOnly())
+        sf.insertImportDeclaration(wg.getChildIndex(), { moduleSpecifier: "waygraph", namedImports: ["checkpoint"] });
+    else if (!wg.getNamedImports().some((n) => n.getName() === "checkpoint"))
+        wg.addNamedImport("checkpoint");
+    dropUnusedWaygraphImport(sf, "Checkpoint");
+    return sf.getFullText();
+}
+const SINGLE_CHECKPOINT = ["defineNavBlock", "defineNavClickBlock", "defineMemNavBlock", "definePageBlock", "defineAssertBlock"];
+const ROUTED = ["defineMethodBlock", "defineEffectBlock"];
+function optionsOf(call) {
+    const arg = call.getArguments()[0];
+    return Node.isObjectLiteralExpression(arg) ? arg : undefined;
+}
+/** `checkpoint: "Home"` with `<Home>` becomes `checkpoint: Home`. */
+function convertSingle(call, fn, info, skipped) {
+    const typeArg = call.getTypeArguments()[0];
+    const prop = optionsOf(call)?.getProperty("checkpoint");
+    const value = Node.isPropertyAssignment(prop) ? prop.getInitializer() : undefined;
+    if (!typeArg || !Node.isPropertyAssignment(prop) || !Node.isStringLiteral(value))
+        return;
+    const name = typeArg.getText();
+    if (info.tags.get(name) !== value.getLiteralValue()) {
+        skipped.push(`${fn}<${name}>`);
+        return;
+    }
+    call.removeTypeArgument(typeArg);
+    prop.setInitializer(name);
+}
+/** `<In, Out>` becomes `from: In, to: Out` (right after the name and description); a resolve that only returns `to` goes. */
+function convertRouted(call, fn, info, skipped) {
+    const [fromArg, toArg] = call.getTypeArguments();
+    const options = optionsOf(call);
+    if (!fromArg || !toArg || !options)
+        return;
+    const from = fromArg.getText();
+    const to = toArg.getText();
+    const known = (n) => info.tags.has(n) || info.unions.has(n);
+    const anywhere = from === "Checkpoint<string>";
+    if ((!anywhere && !known(from)) || !known(to)) {
+        skipped.push(`${fn}<${from}, ${to}>`);
+        return;
+    }
+    call.removeTypeArgument(toArg);
+    call.removeTypeArgument(fromArg);
+    const props = options.getProperties();
+    const after = Math.max(...["name", "description"].map((n) => props.findIndex((p) => Node.isPropertyAssignment(p) && p.getName() === n)));
+    options.insertPropertyAssignments(after + 1, [...(anywhere ? [] : [{ name: "from", initializer: from }]), { name: "to", initializer: to }]);
+    const tag = info.tags.get(to);
+    const instruction = options.getProperty("instruction");
+    const body = Node.isPropertyAssignment(instruction) ? instruction.getInitializer() : undefined;
+    const resolve = Node.isObjectLiteralExpression(body) ? body.getProperty("resolve") : undefined;
+    if (tag && Node.isPropertyAssignment(resolve) && resolve.getInitializer()?.getText().replace(/\s/g, "") === `()=>checkpoint("${tag}")`)
+        resolve.remove();
+    // Inserting and removing properties leaves the object's indentation uneven; tidy just this call.
+    call.formatText({ indentSize: call.getSourceFile().getProject().manipulationSettings.getIndentationText().length, convertTabsToSpaces: !call.getSourceFile().getFullText().includes("\n\t") });
+}
+/** Rewrites one Block file. Calls whose Checkpoints are not plain declared names are left as they are. */
+export function convertBlocks(text, info) {
+    const sf = parse(text);
+    const skipped = [];
+    for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression).reverse()) {
+        if (call.wasForgotten())
+            continue;
+        const fn = call.getExpression().getText();
+        if (SINGLE_CHECKPOINT.includes(fn))
+            convertSingle(call, fn, info, skipped);
+        else if (ROUTED.includes(fn))
+            convertRouted(call, fn, info, skipped);
+    }
+    if (sf.getFullText() === text)
+        return { text, skipped };
+    dropUnusedWaygraphImport(sf, "Checkpoint");
+    dropUnusedWaygraphImport(sf, "checkpoint");
+    // Checkpoints are now used as values: import them as values.
+    const known = (n) => info.tags.has(n) || info.unions.has(n);
+    for (const imp of sf.getImportDeclarations()) {
+        if (imp.isTypeOnly() && /states/.test(imp.getModuleSpecifierValue()) && imp.getNamedImports().some((n) => known(n.getName())))
+            imp.setIsTypeOnly(false);
+    }
+    return { text: sf.getFullText(), skipped };
+}
+/** Runs the codemod over a project; returns the files changed and the calls it left alone. */
+export function codemodCheckpoints(projectDir) {
+    const info = { tags: new Map(), unions: new Map() };
+    const files = walkDir(projectDir, /\.ts$/).filter((f) => !f.endsWith(".d.ts"));
+    const states = files.filter((f) => /\.states\.ts$|[/\\]_states\.ts$/.test(f));
+    const changed = [];
+    const skipped = [];
+    for (const f of states) {
+        const before = readFileSync(f, "utf8");
+        const after = convertStates(before, info);
+        if (after !== before) {
+            writeFileSync(f, after);
+            changed.push(relative(projectDir, f));
+        }
+    }
+    for (const f of files.filter((x) => !states.includes(x))) {
+        const before = readFileSync(f, "utf8");
+        const { text, skipped: s } = convertBlocks(before, info);
+        skipped.push(...s.map((c) => `${relative(projectDir, f)}: ${c}`));
+        if (text !== before) {
+            writeFileSync(f, text);
+            changed.push(relative(projectDir, f));
+        }
+    }
+    return { changed, skipped };
+}

package/dist/cli/commands/codemod-flows.d.ts

@@ -0,0 +1,18 @@
+import { Project } from "ts-morph";
+import type { SourceFile } from "ts-morph";
+/** A Block's kind by the file and export it is declared in; undefined when it isn't a known Block. */
+export type KindOf = (file: string, exportName: string) => string | undefined;
+/** Rewrites the old flow forms in a project's source files; returns problems it left for a person. */
+export declare function convertFlows(project: Project, kindOf: KindOf): {
+    changed: SourceFile[];
+    problems: {
+        file: string;
+        line: number;
+        reason: string;
+    }[];
+};
+/** Runs the codemod over a project's TypeScript files, using its runtime scan for each Block's kind. */
+export declare function codemodFlows(projectDir: string): Promise<{
+    changed: string[];
+    problems: string[];
+}>;