waygraph 0.15.53 → 0.16.0

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

@@ -2,8 +2,11 @@ import { basename, join, relative, resolve, dirname } from "node:path";
 import { tmpdir } from "node:os";
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { spawnSync } from "node:child_process";
-import { packageRoot } from "../cli/util.js";
+import { packageRoot } from "../util.js";
 import { agentSkillFiles } from "./agent-dive-scaffold.js";
+import { codemodCheckpoints } from "./codemod-checkpoints.js";
+import { codemodFlows } from "./codemod-flows.js";
+import { parseCommand } from "../args.js";
 // Filled in per project at init, so they never compare equal to the template.
 const SKIP = new Set(["package.json", join("config", "waygraph.config.ts")]);
 function walk(dir, base = dir) {
@@ -20,14 +23,47 @@ const isOlder = (a, b) => {
             return (a[i] ?? 0) < (b[i] ?? 0);
     return false;
 };
+const OPTIONS = {
+    apply: { type: "boolean", help: "Copy the files (default: a dry run that lists them)" },
+    overwrite: { type: "boolean", help: "Also replace files that differ from the scaffold" },
+    diff: { type: "boolean", help: "Show what differs" },
+    skills: { type: "boolean", help: "Refresh .agents/skills to this waygraph's" },
+    codemod: { type: "string", value: "flows|checkpoints", help: "Rewrite the project's source onto the current API" },
+};
 /**
  * `waygraph upgrade [project] [paths...] [--apply] [--overwrite] [--diff] [--skills]`
  * Compares the project with the scaffold shipped in this waygraph. Dry run by default.
  * Only the paths you name are copied, because a real project deliberately drops parts of the demo.
  */
 export async function upgradeCase(args) {
-    const flags = new Set(args.filter((a) => a.startsWith("--")));
-    const positional = args.slice(1).filter((a) => !a.startsWith("--"));
+    const { values, positionals: positional } = parseCommand("upgrade", OPTIONS, args.slice(1));
+    const flags = new Set(Object.entries(values).filter(([, v]) => v === true).map(([k]) => "--" + k));
+    if (values.codemod !== undefined) {
+        const what = values.codemod;
+        const dir = resolve(positional[0] ?? process.cwd());
+        if (what === "flows") {
+            const { changed, problems } = await codemodFlows(dir);
+            for (const f of changed)
+                console.log(`  rewrote     ${f}`);
+            for (const p of problems)
+                console.log(`  by hand     ${p}`);
+            console.log(`waygraph upgrade --codemod flows: ${changed.length} file(s) changed, ${problems.length} left for you; run waygraph typecheck .`);
+            if (problems.length)
+                process.exitCode = 1;
+            return;
+        }
+        if (what !== "checkpoints") {
+            console.error("waygraph upgrade --codemod: known codemods: checkpoints, flows");
+            process.exit(1);
+        }
+        const { changed, skipped } = codemodCheckpoints(dir);
+        for (const f of changed)
+            console.log(`  rewrote     ${f}`);
+        for (const s of skipped)
+            console.log(`  left as is  ${s} (not a declared Checkpoint name)`);
+        console.log(`waygraph upgrade --codemod checkpoints: ${changed.length} file(s) changed; run waygraph typecheck .`);
+        return;
+    }
     // --skills: the agent skills are waygraph's own text, never edited by a project, so refresh them in place.
     if (flags.has("--skills")) {
         flags.add("--apply");
@@ -76,7 +112,7 @@ export async function upgradeCase(args) {
         console.log("  up to date");
     const legacy = ["ts", "mts", "js", "mjs", "cjs"].find((e) => existsSync(join(proj, `playwright.config.${e}`)));
     if (legacy) {
-        console.log(`  deprecated  playwright.config.${legacy} - move its settings into config/waygraph.config.ts (testDir, webServer, playwright: { ... })`);
+        console.log(`  not used    playwright.config.${legacy} - waygraph no longer reads it; move its settings into config/waygraph.config.ts (testDir, webServer, playwright: { ... })`);
     }
     if (flags.has("--diff")) {
         for (const rel of differing.filter((r) => paths.length === 0 || selected(r))) {

package/dist/cli/flags.d.ts

@@ -1,4 +1,3 @@
-import { resolveBaseUrl } from "../config.js";
 interface RunFlags {
     step?: boolean;
     autoplay?: boolean;
@@ -25,10 +24,6 @@ interface RunFlags {
     /** auto path-find: --blocks <fromCheckpoint> <toCheckpoint>. */
     blocksFromTo?: [string, string];
     cli?: boolean;
-    /** auto --cli --detach: run the explore session as a background socket server. */
-    detach?: boolean;
-    /** Force headed panel (compat; bare try auto / auto already headed). */
-    headed?: boolean;
     mermaid?: boolean;
     map?: boolean;
     /** demo: faster transitions / shorter auto-next gates. */
@@ -61,25 +56,206 @@ interface RunFlags {
     json?: boolean;
     /** check/typecheck: skip bad-practice warnings. */
     noPractices?: boolean;
+    /** __auto-serve (the detached session child): its session id. */
+    sessionId?: string;
 }
+/** Which commands document an option in their help (the parser accepts every option for every command that parses run flags). */
+type HelpFor = "demo" | "run" | "session";
 /**
- * Pulls run/demo/auto flags out of argv. Unknown bare `--*` that are not
- * recognized stay as positionals only when they are project paths; known
- * explore flags (--cli/--mermaid/--map) are parsed here.
+ * Every flag the run-style commands take: `parseArgs` reads them from this table, and `usage.ts` prints the demo / run
+ * help from it, so the two can't drift. A flag not listed here is an error, not a stray positional.
  */
-export declare function parseRunFlags(argv: string[]): RunFlags;
+export declare const RUN_OPTIONS: {
+    readonly blocks: {
+        readonly type: "string";
+        readonly value: "<flow|file|spec>";
+        readonly help: "Flow export, .flow.ts path or \"a then b\" chain; auto: <From> <To> Checkpoints";
+        readonly for: readonly ["demo", "run"];
+    };
+    readonly data: {
+        readonly type: "string";
+        readonly value: "'{...}'";
+        readonly help: "Mem seed JSON (or inline flow({...}))";
+        readonly for: readonly ["demo", "run"];
+    };
+    readonly "mem-stub": {
+        readonly type: "boolean";
+        readonly help: "Fill any requires key --data didn't cover from registerMemStub's registry";
+        readonly for: readonly ["demo", "run"];
+    };
+    readonly "auto-next": {
+        readonly type: "boolean";
+        readonly help: "Auto-advance steps";
+        readonly for: readonly ["demo"];
+    };
+    readonly "no-auto-next": {
+        readonly type: "boolean";
+        readonly help: "Wait for Next on every step (the default)";
+        readonly for: readonly ["demo"];
+    };
+    readonly fast: {
+        readonly type: "boolean";
+        readonly help: "Shorter auto-next / Next gates (keeps the smooth cursor)";
+        readonly for: readonly ["demo"];
+    };
+    readonly full: {
+        readonly type: "boolean";
+        readonly help: "Classic wrap-all block chips (default: carousel)";
+        readonly for: readonly ["demo"];
+    };
+    readonly mini: {
+        readonly type: "boolean";
+        readonly help: "Force the compact mini panel (Hide pill + Next)";
+        readonly for: readonly ["demo"];
+    };
+    readonly "todo-left": {
+        readonly type: "boolean";
+        readonly help: "Floating checklist dock on the left (also ctx.todos(id, items, { pos }))";
+        readonly for: readonly ["demo"];
+    };
+    readonly "todo-right": {
+        readonly type: "boolean";
+        readonly help: "Floating checklist dock on the right";
+        readonly for: readonly ["demo"];
+    };
+    readonly "todo-full": {
+        readonly type: "boolean";
+        readonly help: "Full checklist: no compact / collision / behind-ring";
+        readonly for: readonly ["demo"];
+    };
+    readonly "todo-smart": {
+        readonly type: "boolean";
+        readonly help: "Compact + collision + behind-ring (the default)";
+        readonly for: readonly ["demo"];
+    };
+    readonly "ff-expand": {
+        readonly type: "boolean";
+        readonly help: "Expand fastForwardComposeBlock inners as separate steps";
+        readonly for: readonly ["demo", "run"];
+    };
+    readonly "ff-disabled": {
+        readonly type: "boolean";
+        readonly help: "Dispute: expand FF; blitz kept on those inners";
+        readonly for: readonly ["demo", "run"];
+    };
+    readonly "auto-play-video": {
+        readonly type: "boolean";
+        readonly help: "Unattended + recorded: --auto-next + --video (+ step); headless";
+        readonly for: readonly ["demo"];
+    };
+    readonly "auto-play-video-head": {
+        readonly type: "boolean";
+        readonly help: "Same, but keep the browser visible (--non-headless)";
+        readonly for: readonly ["demo"];
+    };
+    readonly video: {
+        readonly type: "string";
+        readonly value: "[dir]";
+        readonly help: "Record .webm (default ~/Downloads/waygraph-videos/<project>, video.dir, WAYGRAPH_VIDEO_DIR)";
+        readonly for: readonly ["demo", "run"];
+    };
+    readonly "video-viewport": {
+        readonly type: "string";
+        readonly value: "WxH";
+        readonly help: "Recording size (demo 1920x1080, run 1280x720)";
+        readonly for: readonly ["demo", "run"];
+    };
+    readonly step: {
+        readonly type: "boolean";
+        readonly help: "Step through with the overlay";
+        readonly for: readonly ["run"];
+    };
+    readonly "no-step": {
+        readonly type: "boolean";
+        readonly help: "No step overlay (demo: plain run with narration off)";
+        readonly for: readonly ["demo"];
+    };
+    readonly "all-branches": {
+        readonly type: "boolean";
+        readonly help: "Bare Flow ref only: explore every branch() path, cloning the session at each";
+        readonly for: readonly ["run"];
+    };
+    readonly "shared-session": {
+        readonly type: "boolean";
+        readonly help: "With --all-branches: one shared session (follows only the live path)";
+        readonly for: readonly ["run"];
+    };
+    readonly "non-headless": {
+        readonly type: "boolean";
+        readonly help: "Show the browser";
+        readonly for: readonly ["demo", "run"];
+    };
+    readonly title: {
+        readonly type: "string";
+        readonly value: "<text>";
+        readonly help: "Banner title";
+        readonly for: readonly ["demo", "run"];
+    };
+    readonly "base-url": {
+        readonly type: "string";
+        readonly value: "<url>";
+        readonly help: "Base URL (beats WAYGRAPH_BASE_URL and the config)";
+        readonly for: readonly ["demo", "run", "session"];
+    };
+    readonly inject: {
+        readonly type: "string";
+        readonly multiple: true;
+        readonly value: "<preset|path>";
+        readonly help: "Merge an external Block library (repeatable)";
+        readonly for: readonly ["session"];
+    };
+    readonly goto: {
+        readonly type: "string";
+        readonly value: "<url>";
+        readonly help: "Navigate on start (disables the blank page)";
+        readonly for: readonly ["session"];
+    };
+    readonly blank: {
+        readonly type: "boolean";
+        readonly help: "Force about:blank on start (default)";
+        readonly for: readonly ["session"];
+    };
+    readonly headless: {
+        readonly type: "boolean";
+        readonly help: "Headless session (default: visible browser)";
+        readonly for: readonly ["session"];
+    };
+    readonly cli: {
+        readonly type: "boolean";
+        readonly help: "Terminal picker instead of the browser panel";
+        readonly for: readonly ["session"];
+    };
+    readonly json: {
+        readonly type: "boolean";
+        readonly help: "Machine-readable JSON";
+        readonly for: readonly ["session"];
+    };
+    readonly mermaid: {
+        readonly type: "boolean";
+        readonly help: "Print the graph as Mermaid";
+    };
+    readonly map: {
+        readonly type: "boolean";
+        readonly help: "Print the map";
+    };
+    readonly "no-practices": {
+        readonly type: "boolean";
+        readonly help: "check / typecheck: skip bad-practice warnings";
+    };
+    readonly "session-id": {
+        readonly type: "string";
+        readonly help: "Internal: the id a detached session child serves (set by browser start)";
+    };
+};
+/** The help lines for one command's options, from {@link RUN_OPTIONS}. */
+export declare function optionHelp(command: HelpFor, indent?: number): string;
+/** Reads run/demo/auto/session flags with `node:util`'s parseArgs; an unknown flag or a missing value exits with the reason. */
+export declare function parseRunFlags(argv: string[], command: string): RunFlags;
 /** Writes flag values into process.env so the chain child inherits them. Flags beat prior env. */
 export declare function applyRunFlags(flags: RunFlags, opts?: {
     allowAutoPlayVideo?: boolean;
     allowDemoUi?: boolean;
 }): void;
-/**
- * BASE_URL when neither --base-url nor WAYGRAPH_BASE_URL is set - see `../config.js`'s own
- * `resolveBaseUrl` for the full resolution order (env / `.env` / `waygraph.config.*` /
- * package.json / playwright.config). Re-exported here so existing importers of this module
- * don't need to change their import path.
- */
-export { resolveBaseUrl };
 /**
  * Friendly demo defaults: STEP on; headed only for live watch (no --video).
  * --video / --auto-play-video => headless unless --non-headless.
@@ -95,3 +271,4 @@ export declare function looksLikeFlowFileRef(ref: string): boolean;
  * `src/flows/shop.flow.ts` → `shopFlow`; leaves `loginFlow then nav-cart` alone.
  */
 export declare function expandSpecFlowFiles(projectDir: string, spec: string): Promise<string>;
+export {};