waygraph 0.15.53 → 0.16.0

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

@@ -0,0 +1,284 @@
+// `waygraph upgrade --codemod flows`: rewrites `defineFlow([start, ...Blocks, end], options)`, `chainFlow(...)` and the
+// flow wrappers (`withTitle`, `withMemStub`, `withSessionReset`, `withExpectedFailure`, `withDemoPace`,
+// `withHighlightStyle`, `withBlockPace`, `withStub*`) into `map()` chains. Works on the TypeScript AST (ts-morph); each
+// Block's kind (nav, method, assert, ...) comes from the project's own runtime scan, so it picks the right step method.
+// The same pass moves ctx stubs onto their one form (codemod-stubs.ts).
+import { existsSync } from "node:fs";
+import { join, relative } from "node:path";
+import { Node, Project, SyntaxKind } from "ts-morph";
+import { scanProject } from "../../manifest/project.js";
+import { walkDir } from "../../manifest/scan.js";
+import { convertStubs } from "./codemod-stubs.js";
+const SETTINGS = {
+    withMemStub: () => "memStub: true",
+    withSessionReset: () => "sessionReset: true",
+    withExpectedFailure: (a) => `expectedFailure: ${a}`,
+    withDemoPace: (a) => `demoPace: ${a}`,
+    withHighlightStyle: (a) => `highlightStyle: ${a}`,
+};
+const STUBS = { withStubBefore: "stubBefore", withStubAfter: "stubAfter", withStubOnError: "stubOnError" };
+const REMOVED = new Set(["start", "end", "chainFlow", "withTitle", "withBlockPace", "withHighlightFixtures", ...Object.keys(SETTINGS), ...Object.keys(STUBS)]);
+const STEP = { nav: "gotoPage", page: "gotoPage", method: "method", effect: "method", api: "method", assert: "assert" };
+/** The Block identifier an element of a flow is built from: `X`, `X.stubBefore(...)`, `withVerify(X, ...)`. */
+function rootIdentifier(expr) {
+    if (Node.isIdentifier(expr))
+        return expr;
+    if (Node.isCallExpression(expr)) {
+        const callee = expr.getExpression();
+        if (Node.isPropertyAccessExpression(callee))
+            return rootIdentifier(callee.getExpression());
+        if (Node.isIdentifier(callee) && callee.getText() === "withVerify")
+            return expr.getArguments()[0] && rootIdentifier(expr.getArguments()[0]);
+    }
+    return undefined;
+}
+/** Where an identifier is declared: its file and exported name, following imports. */
+function declarationOf(id) {
+    let symbol = id.getSymbol();
+    if (!symbol)
+        return undefined;
+    if (symbol.isAlias())
+        symbol = symbol.getAliasedSymbol() ?? symbol;
+    const decl = symbol.getDeclarations()[0];
+    if (!decl)
+        return undefined;
+    return { file: decl.getSourceFile().getFilePath(), name: symbol.getName() };
+}
+/** `engine.map({...}).start()...end()`: the `.map(...)` call at the root of a chain, or undefined. */
+function mapCallOf(expr) {
+    let cur = expr;
+    while (Node.isCallExpression(cur)) {
+        const callee = cur.getExpression();
+        if (!Node.isPropertyAccessExpression(callee))
+            return undefined;
+        if (callee.getName() === "map")
+            return cur;
+        cur = callee.getExpression();
+    }
+    return undefined;
+}
+/** The first step call after `.map(...)`/`.start()` in a chain. */
+function firstStepOf(mapCall) {
+    let parent = mapCall.getParent();
+    while (parent && Node.isPropertyAccessExpression(parent)) {
+        const call = parent.getParent();
+        if (!call || !Node.isCallExpression(call))
+            return undefined;
+        if (parent.getName() !== "start")
+            return call;
+        parent = call.getParent();
+    }
+    return undefined;
+}
+function addSetting(mapCall, setting) {
+    const arg = mapCall.getArguments()[0];
+    if (arg && Node.isObjectLiteralExpression(arg)) {
+        const inner = arg.getText().slice(1, -1).trim().replace(/,$/, "");
+        arg.replaceWithText(`{ ${inner ? `${inner}, ` : ""}${setting} }`);
+    }
+    else if (!arg) {
+        mapCall.addArgument(`{ ${setting} }`);
+    }
+    else {
+        arg.replaceWithText(`{ ...${arg.getText()}, ${setting} }`);
+    }
+}
+function addTitle(step, title) {
+    const block = step.getArguments()[0];
+    if (block)
+        block.replaceWithText(titleStub(block.getText(), title, indentOf(step)));
+}
+/** `engine` when the file has one in scope, else the standalone `map` export (imported from waygraph). */
+function mapRoot(sf, needsMap) {
+    const hasEngine = sf.getImportDeclarations().some((d) => d.getNamedImports().some((n) => (n.getAliasNode()?.getText() ?? n.getName()) === "engine"))
+        || sf.getVariableDeclaration("engine") !== undefined;
+    if (hasEngine)
+        return "engine.map";
+    needsMap.add(sf);
+    return "map";
+}
+/** The indentation of the statement a node sits in, so a rewritten chain lines up with the code around it. */
+function indentOf(node) {
+    const statement = node.getFirstAncestor((a) => Node.isStatement(a) || Node.isSourceFile(a.getParentOrThrow())) ?? node;
+    return " ".repeat(statement.getIndentationLevel() * 2);
+}
+function titleStub(block, title, indent) {
+    return `${block}.stubBefore((ctx) => {\n${indent}    ctx.title(${title});\n${indent}  })`;
+}
+function chain(head, steps, indent) {
+    return [head, ...steps, ".end()"].join(`\n${indent}  `);
+}
+/** Rewrites one call if it is one of the old forms; returns a problem message when it can't. */
+function rewrite(call, kindOf, needsMap) {
+    const sf = call.getSourceFile();
+    const callee = call.getExpression();
+    const args = call.getArguments();
+    const name = Node.isIdentifier(callee) ? callee.getText() : undefined;
+    const indent = indentOf(call);
+    if (Node.isPropertyAccessExpression(callee) && callee.getName() === "defineFlow") {
+        const list = args[0];
+        if (!list || !Node.isArrayLiteralExpression(list))
+            return "defineFlow without an array literal";
+        const elements = list.getElements().filter((e) => e.getText() !== "start" && e.getText() !== "end");
+        const steps = [];
+        for (const el of elements) {
+            let block = el;
+            let opts = "";
+            if (Node.isCallExpression(el) && el.getExpression().getText() === "withBlockPace") {
+                block = el.getArguments()[0];
+                opts = `, { pace: ${el.getArguments()[1]?.getText()} }`;
+            }
+            const id = rootIdentifier(block);
+            const decl = id && declarationOf(id);
+            const kind = decl && kindOf(decl.file, decl.name);
+            const step = kind && STEP[kind];
+            if (!step)
+                return `${el.getText().split("\n")[0]} is not a Block from a define*Block factory (kind: ${kind ?? "unknown"}); map() can't take it - rebuild it with a factory or nest it with .flow()`;
+            const external = step === "gotoPage" && /[\\/]\(external\)[\\/]/.test(decl.file);
+            steps.push(`.${external ? "gotoExternal" : step}(${block.getText()}${opts})`);
+        }
+        const options = args[1];
+        let settings = "";
+        let title;
+        if (options) {
+            if (!Node.isObjectLiteralExpression(options))
+                return "defineFlow options that aren't an object literal";
+            const kept = [];
+            for (const p of options.getProperties()) {
+                if (Node.isPropertyAssignment(p) && p.getName() === "title")
+                    title = p.getInitializer().getText();
+                else
+                    kept.push(p.getText());
+            }
+            if (kept.length)
+                settings = `{ ${kept.join(", ")} }`;
+        }
+        if (title && steps[0])
+            steps[0] = steps[0].replace(/^(\.\w+\()(.*)\)$/s, (_all, head, block) => `${head}${titleStub(block, title, indent)})`);
+        call.replaceWithText(chain(`${callee.getExpression().getText()}.map(${settings})`, [".start()", ...steps], indent));
+        return "changed";
+    }
+    if (name === "chainFlow") {
+        call.replaceWithText(chain(`${mapRoot(sf, needsMap)}()`, [".start()", ...args.map((a) => `.flow(${a.getText()})`)], indent));
+        return "changed";
+    }
+    if (name && STUBS[name] && args.length === 2) {
+        call.replaceWithText(`${args[0].getText()}.${STUBS[name]}(${args[1].getText()})`);
+        return "changed";
+    }
+    if (name && (SETTINGS[name] || name === "withTitle") && args[0]) {
+        const flow = args[0];
+        const mapCall = mapCallOf(flow);
+        if (name === "withTitle") {
+            const first = mapCall && firstStepOf(mapCall);
+            if (!first)
+                return `withTitle(${flow.getText().split("\n")[0]}, …): name the flow with ctx.title(…) in a stub on its first step`;
+            addTitle(first, args[1].getText());
+        }
+        else if (mapCall) {
+            addSetting(mapCall, SETTINGS[name](args[1]?.getText()));
+        }
+        else {
+            call.replaceWithText(chain(`${mapRoot(sf, needsMap)}({ ${SETTINGS[name](args[1]?.getText())} })`, [".start()", `.flow(${flow.getText()})`], indent));
+            return "changed";
+        }
+        call.replaceWithText(flow.getText());
+        return "changed";
+    }
+    if (name === "withHighlightFixtures")
+        return "withHighlightFixtures: chain ctx stubs on each Block where the flow uses it (Block.stubAfter((ctx) => …))";
+    if (name === "withBlockPace")
+        return "withBlockPace outside a flow: use the step option .method(Block, { pace })";
+    if (Node.isPropertyAccessExpression(callee) && callee.getName() === "end" && args[0] && mapCallOf(call)) {
+        const options = args[0];
+        if (Node.isObjectLiteralExpression(options)) {
+            const mapCall = mapCallOf(call);
+            for (const p of options.getProperties())
+                addSetting(mapCall, p.getText());
+            options.replaceWithText("");
+            call.replaceWithText(call.getText().replace(/\.end\(\s*\)$/, ".end()"));
+            return "changed";
+        }
+    }
+    return undefined;
+}
+/** Rewrites the old flow forms in a project's source files; returns problems it left for a person. */
+export function convertFlows(project, kindOf) {
+    const changed = new Set();
+    const problems = [];
+    const needsMap = new Set();
+    for (const sf of project.getSourceFiles()) {
+        // One rewrite per pass, innermost calls first, so a wrapper sees the map() chain its argument became. Calls left
+        // for a person never change, so the final pass (nothing left to rewrite) lists each of them once.
+        const rewritten = new Set();
+        for (;;) {
+            let progressed = false;
+            const left = [];
+            for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression).reverse()) {
+                if (call.wasForgotten())
+                    continue;
+                const top = sf.getStatements().indexOf(call.getFirstAncestor((a) => a.getParent() === sf));
+                const result = rewrite(call, kindOf, needsMap);
+                if (result === "changed") {
+                    changed.add(sf);
+                    rewritten.add(top);
+                    progressed = true;
+                    break;
+                }
+                if (result)
+                    left.push({ file: sf.getFilePath(), line: call.getStartLineNumber(), reason: result });
+            }
+            if (!progressed) {
+                problems.push(...left.reverse());
+                break;
+            }
+        }
+        if (!changed.has(sf))
+            continue;
+        // Replacing nested calls leaves odd indentation behind; TypeScript's formatter tidies just the rewritten statements.
+        const statements = sf.getStatements();
+        for (const i of rewritten)
+            statements[i]?.formatText({ indentSize: 2, convertTabsToSpaces: true });
+        for (const imp of sf.getImportDeclarations()) {
+            if (imp.getModuleSpecifierValue() !== "waygraph")
+                continue;
+            for (const n of imp.getNamedImports()) {
+                const local = n.getAliasNode()?.getText() ?? n.getName();
+                const stillUsed = sf.getDescendantsOfKind(SyntaxKind.Identifier).some((i) => {
+                    const parent = i.getParent();
+                    if (i.getText() !== local || Node.isImportSpecifier(parent))
+                        return false;
+                    return !(Node.isPropertyAccessExpression(parent) && parent.getNameNode() === i);
+                });
+                if (REMOVED.has(n.getName()) && !stillUsed)
+                    n.remove();
+            }
+            if (needsMap.has(sf) && !imp.getNamedImports().some((n) => n.getName() === "map"))
+                imp.addNamedImport("map");
+            if (imp.getNamedImports().length === 0 && !imp.getDefaultImport() && !imp.getNamespaceImport())
+                imp.remove();
+        }
+    }
+    return { changed: [...changed], problems };
+}
+/** Runs the codemod over a project's TypeScript files, using its runtime scan for each Block's kind. */
+export async function codemodFlows(projectDir) {
+    const scan = await scanProject(projectDir, { flows: false, maps: false });
+    const kinds = new Map(scan.blocks.map((b) => [`${b.absFile}#${b.exportName}`, b.kind]));
+    // Compiler options from the project's tsconfig; files from walkDir, which skips node_modules, dist and .git.
+    const tsconfig = join(projectDir, "tsconfig.json");
+    const project = new Project({ ...(existsSync(tsconfig) ? { tsConfigFilePath: tsconfig } : {}), skipAddingFilesFromTsConfig: true });
+    for (const file of walkDir(projectDir, /\.ts$/))
+        if (!file.endsWith(".d.ts"))
+            project.addSourceFileAtPath(file);
+    const flows = convertFlows(project, (file, name) => kinds.get(`${file}#${name}`));
+    const stubs = convertStubs(project);
+    const changed = [...new Set([...flows.changed, ...stubs.changed])];
+    const problems = [...flows.problems, ...stubs.problems];
+    for (const sf of changed)
+        sf.saveSync();
+    return {
+        changed: changed.map((sf) => relative(projectDir, sf.getFilePath())),
+        problems: problems.map((p) => `${relative(projectDir, p.file)}:${p.line}: ${p.reason}`),
+    };
+}

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

@@ -0,0 +1,10 @@
+import type { Project, SourceFile } from "ts-morph";
+/** Rewrites the old stub forms in every file; returns the files it changed and the calls left for a person. */
+export declare function convertStubs(project: Project): {
+    changed: SourceFile[];
+    problems: {
+        file: string;
+        line: number;
+        reason: string;
+    }[];
+};

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

@@ -0,0 +1,187 @@
+// Part of `waygraph upgrade --codemod flows`: moves ctx stubs onto the one form each thing has in 0.16.0. The list-only
+// `ctx.todos([...])` and its setters (`todoId`, `todoTitle`, `todoStyle`, `todoPos`, `todoIndex`) become
+// `ctx.todos(id, items, { title, style, pos, index })`; `todoGroups(groups)` gets the same id and options; the method
+// aliases (`banner`, `bannerPos`, `clearDevice`, `clearTodos`, `landscape`, `portrait`, `todoDockFull`) become the
+// names they stood for. A stub written as a slot map (`{ email: { selector, label } }`) becomes a function of
+// `ctx.ring` calls, and a stub set in a `define*Block({ ... })` (options or instruction) moves out to a chained
+// `.stubBefore(...)` on the Block. Works on the TypeScript AST (ts-morph).
+import { Node, SyntaxKind } from "ts-morph";
+const RENAMED = {
+    banner: (a) => `title(${a.join(", ")})`,
+    bannerPos: (a) => `titlePos(${a.join(", ")})`,
+    clearDevice: () => "hideDevice()",
+    clearTodos: () => "hideTodos()",
+    landscape: () => 'orientation("landscape")',
+    portrait: () => 'orientation("portrait")',
+    todoDockFull: () => "todoDockUi({ compact: false, collision: false, behindRing: false })",
+};
+/** The setters that fold into `todos(id, items, opts)`, and the option each one becomes. */
+const DOCK_SETTERS = { todoId: "id", todoTitle: "title", todoStyle: "style", todoPos: "pos", todoIndex: "index" };
+const DEFAULT_DOCK_ID = '"todos"';
+/** `ctx.method(...)` as a statement on its own: the receiver, the method and the call. */
+function ctxCall(statement) {
+    if (!Node.isExpressionStatement(statement))
+        return undefined;
+    const call = statement.getExpression();
+    if (!Node.isCallExpression(call))
+        return undefined;
+    const callee = call.getExpression();
+    if (!Node.isPropertyAccessExpression(callee) || !Node.isIdentifier(callee.getExpression()))
+        return undefined;
+    return { receiver: callee.getExpression().getText(), method: callee.getName(), call };
+}
+/** Whether `receiver` is a stub's ctx: typed as StubCtx, or the first parameter of a function passed to a stub phase. */
+function isStubCtx(call, receiver) {
+    const fn = call.getFirstAncestor((a) => Node.isArrowFunction(a) || Node.isFunctionExpression(a) || Node.isFunctionDeclaration(a) || Node.isMethodDeclaration(a));
+    if (!fn || !(Node.isArrowFunction(fn) || Node.isFunctionExpression(fn) || Node.isFunctionDeclaration(fn) || Node.isMethodDeclaration(fn)))
+        return false;
+    const param = fn.getParameters()[0];
+    if (!param || param.getName() !== receiver)
+        return false;
+    if (/StubCtx/.test(param.getType().getText(param)))
+        return true;
+    const parent = fn.getParent();
+    const callee = Node.isCallExpression(parent) ? parent.getExpression() : undefined;
+    if (Node.isPropertyAccessExpression(callee) && /^stub(Before|After|OnError)$/.test(callee.getName()))
+        return true;
+    return Node.isPropertyAssignment(parent) && /^stub(Before|After|OnError)$/.test(parent.getName());
+}
+/** Todo items written with the old `name` key get `id`. */
+function renameItemNames(items) {
+    for (const obj of items.getDescendantsOfKind(SyntaxKind.ObjectLiteralExpression)) {
+        const name = obj.getProperty("name");
+        if (Node.isPropertyAssignment(name) && !obj.getProperty("id"))
+            name.getNameNode().replaceWithText("id");
+    }
+}
+/** Rewrites one statement list; returns whether anything changed and the calls it could not convert. */
+function convertStatements(statements, problems) {
+    const calls = statements.map(ctxCall);
+    let changed = false;
+    const consumed = new Set();
+    calls.forEach((c, i) => {
+        if (!c || !isStubCtx(c.call, c.receiver))
+            return;
+        const args = c.call.getArguments().map((a) => a.getText());
+        if (RENAMED[c.method]) {
+            c.call.replaceWithText(`${c.receiver}.${RENAMED[c.method](args)}`);
+            changed = true;
+            return;
+        }
+        const isList = c.method === "todos" && c.call.getArguments().length === 1;
+        if (!isList && c.method !== "todoGroups")
+            return;
+        if (c.method === "todoGroups" && c.call.getArguments().length !== 1)
+            return;
+        // The dock's setters in the same stub, before or after the list, fold into its options.
+        const opts = {};
+        calls.forEach((s, j) => {
+            if (!s || s.receiver !== c.receiver || !DOCK_SETTERS[s.method])
+                return;
+            if (s.method === "todoIndex" && c.method === "todoGroups")
+                return;
+            opts[DOCK_SETTERS[s.method]] = s.call.getArguments()[0]?.getText() ?? "undefined";
+            consumed.add(j);
+        });
+        const items = c.call.getArguments()[0];
+        renameItemNames(items);
+        const id = opts.id ?? DEFAULT_DOCK_ID;
+        delete opts.id;
+        const entries = Object.entries(opts);
+        const tail = entries.length ? `, { ${entries.map(([k, v]) => `${k}: ${v}`).join(", ")} }` : "";
+        c.call.replaceWithText(`${c.receiver}.${c.method}(${id}, ${items.getText()}${tail})`);
+        changed = true;
+    });
+    for (const i of [...consumed].sort((a, b) => b - a))
+        statements[i].remove();
+    for (const [i, c] of calls.entries()) {
+        if (!c || consumed.has(i) || c.call.wasForgotten() || !isStubCtx(c.call, c.receiver))
+            continue;
+        if (DOCK_SETTERS[c.method] && c.method !== "todoIndex")
+            problems.push({ line: c.call.getStartLineNumber(), reason: `ctx.${c.method}() with no ctx.todos(...) beside it: pass it as an option of ctx.todos(id, items, { ... })` });
+        if (c.method === "set")
+            problems.push({ line: c.call.getStartLineNumber(), reason: "ctx.set({...}) was removed: call ctx.ring / ctx.todos / ctx.title ... instead" });
+    }
+    return changed;
+}
+const PHASES = new Set(["stubBefore", "stubAfter", "stubOnError"]);
+/** A slot map as a stub function: `{ a: {...} }` -> `(ctx) => { ctx.ring("a", {...}); }`. */
+function mapToStub(map) {
+    if (!Node.isObjectLiteralExpression(map))
+        return map.getText();
+    const rings = map.getProperties().flatMap((p) => (Node.isPropertyAssignment(p) ? [`ctx.ring(${JSON.stringify(p.getName().replace(/^["']|["']$/g, ""))}, ${p.getInitializerOrThrow().getText()});`] : []));
+    return `(ctx) => {\n${rings.map((r) => "  " + r).join("\n")}\n}`;
+}
+/** `X.stubAfter({ ... })` -> `X.stubAfter((ctx) => { ctx.ring(...) })`. */
+function convertSlotMaps(sf) {
+    let changed = false;
+    for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression).reverse()) {
+        if (call.wasForgotten())
+            continue;
+        const callee = call.getExpression();
+        const arg = call.getArguments()[0];
+        if (Node.isPropertyAccessExpression(callee) && PHASES.has(callee.getName()) && Node.isObjectLiteralExpression(arg)) {
+            arg.replaceWithText(mapToStub(arg));
+            changed = true;
+        }
+    }
+    return changed;
+}
+/** `defineXBlock({ ..., stubBefore: fn })` (or in its instruction) -> `defineXBlock({ ... }).stubBefore(fn)`. */
+function hoistDefinitionStubs(sf) {
+    let changed = false;
+    for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression).reverse()) {
+        if (call.wasForgotten() || !/^define\w*Block$/.test(call.getExpression().getText()))
+            continue;
+        const options = call.getArguments()[0];
+        if (!Node.isObjectLiteralExpression(options))
+            continue;
+        const holders = [options];
+        const instruction = options.getProperty("instruction");
+        if (Node.isPropertyAssignment(instruction) && Node.isObjectLiteralExpression(instruction.getInitializer()))
+            holders.push(instruction.getInitializer());
+        const chained = [];
+        for (const holder of holders) {
+            for (const prop of holder.getProperties()) {
+                const name = Node.isPropertyAssignment(prop) || Node.isMethodDeclaration(prop) ? prop.getName() : "";
+                if (!PHASES.has(name))
+                    continue;
+                let fn;
+                if (Node.isMethodDeclaration(prop))
+                    fn = `(${prop.getParameters().map((p) => p.getText()).join(", ")}) => ${prop.getBodyOrThrow().getText()}`;
+                else {
+                    const init = prop.getInitializerOrThrow();
+                    fn = Node.isObjectLiteralExpression(init) ? mapToStub(init) : init.getText();
+                }
+                chained.push(`.${name}(${fn})`);
+                prop.remove();
+            }
+        }
+        if (chained.length) {
+            call.replaceWithText(call.getText() + chained.join(""));
+            changed = true;
+        }
+    }
+    return changed;
+}
+/** Rewrites the old stub forms in every file; returns the files it changed and the calls left for a person. */
+export function convertStubs(project) {
+    const changed = [];
+    const problems = [];
+    for (const sf of project.getSourceFiles()) {
+        const left = [];
+        let touched = hoistDefinitionStubs(sf);
+        if (convertSlotMaps(sf))
+            touched = true;
+        for (const block of sf.getDescendantsOfKind(SyntaxKind.Block).reverse()) {
+            if (block.wasForgotten())
+                continue;
+            if (convertStatements(block.getStatements(), left))
+                touched = true;
+        }
+        if (touched)
+            changed.push(sf);
+        problems.push(...left.map((p) => ({ file: sf.getFilePath(), ...p })));
+    }
+    return { changed, problems };
+}

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

@@ -1,9 +1,10 @@
 import { resolve } from "node:path";
-import { loadWaygraphConfig } from "../config.js";
-import { extensionInfo, resolveExtension } from "../extensions.js";
+import { loadWaygraphConfig } from "../../runtime/waygraph-config.js";
+import { extensionInfo, resolveExtension } from "../../runtime/extensions.js";
+import { parseCommand } from "../args.js";
 export async function extensionsCase(args) {
-    const update = args.includes("--update");
-    const rest = args.slice(2).filter((a) => a !== "--update");
+    const { values, positionals: rest } = parseCommand("extensions", { update: { type: "boolean", help: "Download again" } }, args.slice(2));
+    const update = values.update === true;
     if (args[1] !== "install") {
         console.error("usage: waygraph extensions install [project] [--update]");
         process.exit(1);

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

@@ -1,5 +1,4 @@
-// Split out of the former 8,700-line cli.ts (see src/ARCHITECTURE.md). Behavior unchanged.
-import { packageRoot } from "../cli/util.js";
+import { packageRoot } from "../util.js";
 import { agentSkillFiles } from "./agent-dive-scaffold.js";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { spawnSync } from "node:child_process";

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

@@ -1,12 +1,13 @@
-// Split out of the former 8,700-line cli.ts (see src/ARCHITECTURE.md). Behavior unchanged.
-import { blockExportToLabel, discoverFlows, extractFlowNames, extractGotos, extractUrlTraits, parseBlockImports, walkDir } from "../cli/discover.js";
+import { blockExportToLabel, extractFlowNames, extractGotos, extractUrlTraits, parseBlockImports } from "../../analysis/flow-source.js";
+import { walkDir } from "../../manifest/scan.js";
+import { exportedNames, parseSource } from "../../manifest/source.js";
 import { relative, resolve } from "node:path";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 // ---------------------------------------------------------------------------
 // `list`
 // ---------------------------------------------------------------------------
 function listCommand(projectDir) {
-    const files = discoverFlows(projectDir);
+    const files = walkDir(projectDir, /\.flow\.ts$/);
     if (files.length === 0) {
         console.log(`waygraph: no flows found under ${projectDir}`);
         return;
@@ -22,7 +23,7 @@ function listCommand(projectDir) {
 // `nav`
 // ---------------------------------------------------------------------------
 function navCommand(projectDir, flowName) {
-    const files = discoverFlows(projectDir);
+    const files = walkDir(projectDir, /\.flow\.ts$/);
     const targets = flowName
         ? files.filter((f) => extractFlowNames(f).includes(flowName))
         : files;
@@ -33,13 +34,14 @@ function navCommand(projectDir, flowName) {
         process.exitCode = 1;
         return;
     }
+    let scanned;
+    const blockFiles = () => (scanned ??= walkDir(projectDir, /\.block\.ts$/).map((f) => ({ file: f, exports: exportedNames(parseSource(f)) })));
     for (const file of targets) {
         for (const name of extractFlowNames(file)) {
             console.log(`${name}  (${relative(projectDir, file)})`);
-            const blockDir = projectDir;
             for (const blockExport of parseBlockImports(file)) {
                 console.log(`  -> ${blockExportToLabel(blockExport)}`);
-                const blockFile = walkDir(blockDir, /\.block\.ts$/).find((f) => readFileSync(f, "utf-8").includes(`export const ${blockExport}`));
+                const blockFile = blockFiles().find((f) => f.exports.includes(blockExport))?.file;
                 if (!blockFile)
                     continue;
                 for (const url of extractGotos(blockFile))

package/dist/cli/commands/manifest.d.ts

@@ -0,0 +1,2 @@
+/** `waygraph manifest [project] [--out <file>]`: every Block, Flow and Checkpoint of the project, as JSON. */
+export declare function manifestCase(args: string[]): Promise<void>;

package/dist/cli/commands/manifest.js

@@ -0,0 +1,20 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { buildManifest } from "../../manifest/manifest.js";
+import { parseCommand } from "../args.js";
+/** `waygraph manifest [project] [--out <file>]`: every Block, Flow and Checkpoint of the project, as JSON. */
+export async function manifestCase(args) {
+    const { values, positionals: positional } = parseCommand("manifest", { out: { type: "string", help: "Write to this file" } }, args.slice(1));
+    const out = values.out;
+    const proj = resolve(positional[0] ?? process.cwd());
+    const manifest = await buildManifest(proj);
+    const json = JSON.stringify(manifest, null, 2) + "\n";
+    if (!out) {
+        process.stdout.write(json);
+        return;
+    }
+    const file = resolve(proj, out);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, json);
+    console.error(`waygraph manifest: ${manifest.blocks.length} Block(s), ${manifest.flows.length} flow(s) -> ${file}`);
+}

package/dist/cli/commands/map.js

@@ -0,0 +1,57 @@
+import { relative, resolve } from "node:path";
+import { checkMap } from "../../analysis/map-check.js";
+import { packMapGroup } from "../../manifest/pack.js";
+import { parseCommand } from "../args.js";
+const PACK_OPTIONS = {
+    out: { type: "string", value: "<dir>", help: "Output folder (default .waygraph/packages/<group>)" },
+    name: { type: "string", value: "<package>", help: "Package name (default waygraph-map-<group>)" },
+    version: { type: "string", value: "<x.y.z>", help: "Package version (default 0.1.0)" },
+};
+async function packCase(args) {
+    const { values, positionals } = parseCommand("map pack", PACK_OPTIONS, args);
+    const group = positionals[0];
+    if (!group) {
+        console.error("usage: waygraph map pack <group> [project] [--out <dir>] [--name <package>] [--version <x.y.z>]");
+        process.exitCode = 1;
+        return;
+    }
+    const proj = resolve(positionals[1] ?? process.cwd());
+    const result = await packMapGroup(proj, group, { out: values.out, name: values.name, version: values.version });
+    if (!result.ok) {
+        console.error(`waygraph map pack: ${result.reason}`);
+        for (const p of result.problems ?? [])
+            console.error(`  ${relative(proj, p.file)} imports "${p.spec}"`);
+        process.exitCode = 1;
+        return;
+    }
+    console.log(`waygraph map pack: ${result.group} -> ${relative(proj, result.dir) || "."} (${result.name}, ${result.blocks} Blocks)`);
+    console.log(`  publish: cd ${relative(process.cwd(), result.dir) || "."} && npm publish   install elsewhere: npm i ${result.name}`);
+}
+export async function mapCase(args) {
+    if (args[1] === "pack")
+        return packCase(args.slice(2));
+    const proj = resolve(args[1] ?? process.cwd());
+    const result = await checkMap(proj);
+    if (!result.hasMapDir) {
+        console.log(`waygraph map: no src/map/ directory under ${proj} - nothing to check ` +
+            "(this project isn't on the Waygraph Map convention, or hasn't been migrated yet)");
+        return;
+    }
+    console.log(`waygraph map: ${result.nodes.length} node(s) found under ${relative(proj, result.mapRoot)}`);
+    if (result.violations.length === 0) {
+        console.log("waygraph map: 0 violations - every static Nav/Page url verbatim-matches its folder path");
+    }
+    else {
+        for (const v of result.violations) {
+            console.error(`waygraph map: ${v.file} (${v.block}) - ${v.reason}`);
+        }
+        console.error(`waygraph map: ${result.violations.length} violation${result.violations.length === 1 ? "" : "s"}`);
+        // Unlike `check`'s warnings-only stance, a Map violation is exactly
+        // the class of bug this command exists to catch (a fabricated
+        // folder grouping that never matched the real site, e.g. the real
+        // (auth)/signin/ mistake this command's own header comment cites) -
+        // fail loud, not just warn.
+        process.exitCode = 1;
+    }
+    return;
+}

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

@@ -1,3 +1,2 @@
 export declare function runCase(args: string[]): Promise<void>;
-export declare function chainCase(args: string[]): Promise<void>;
 export declare function demoCase(args: string[]): Promise<void>;