waygraph 0.15.22 → 0.15.24

package/dist/cli/discover.d.ts

@@ -0,0 +1,40 @@
+export declare function walkDir(dir: string, pattern: RegExp): string[];
+export declare function discoverFlows(projectDir: string): string[];
+export declare function extractFlowNames(filePath: string): string[];
+/** `LoginBlock` -> `"login"`; `OverviewMetricsBlock` -> `"overview-metrics"`. */
+export declare function blockExportToLabel(exportId: string): string;
+/** Every `...Block` identifier a `.flow.ts` file imports, in source order. */
+export declare function parseBlockImports(filePath: string): string[];
+/** Every `page.goto("...")` string literal in a file, in source order. */
+export declare function extractGotos(filePath: string): string[];
+/** Every `Trait.url({ pathname: "..." })` target in a file, in source order. */
+export declare function extractUrlTraits(filePath: string): string[];
+export declare function importModule(filePath: string): Promise<Record<string, unknown>>;
+/** Kept as a named alias - `run`/`validate` below were written against this name first. */
+export declare const importFlowFile: typeof importModule;
+export declare function isFlowLike(val: unknown): val is {
+    run: (...args: unknown[]) => Promise<unknown>;
+};
+export declare function discoverBlocks(projectDir: string): string[];
+export declare function isBlockLike(val: unknown): val is {
+    name: string;
+    instruction: {
+        act: unknown;
+    };
+};
+/** Set by `defineNavBlock` (non-enumerable) - see src/engine.ts. */
+export declare function isNavBlockMarked(val: Record<string, unknown>): boolean;
+export declare const NAV_METHOD_CALLS: readonly ["page.goto(", "page.reload(", "page.goBack(", "page.goForward("];
+/**
+ * Matches a selector-taking Trait factory call whose first argument is a
+ * literal string/template, not an identifier or property access - the exact
+ * shape found repeatedly in hand-written assertion Blocks
+ * (`Trait.visible("#some-id")` instead of `Trait.visible(SomeSel.thing)`).
+ * `Trait.url(...)` is deliberately excluded - it takes a URLPatternInit, never
+ * a DOM selector. Same file-scoped-regex bluntness the nav-escape sweep above
+ * already accepts (see openspec/specs/nav-block-and-check/spec.md) - a known
+ * blind spot on string concatenation/template-built selectors, not solved
+ * here for the same "recipe before promotion" reason that check accepts its
+ * own shared-helper blind spot.
+ */
+export declare const INLINE_SELECTOR_CALL: RegExp;

package/dist/cli/discover.js

@@ -0,0 +1,148 @@
+// Split out of the former 8,700-line cli.ts (see src/ARCHITECTURE.md). Behavior unchanged.
+import { readFileSync, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+// ---------------------------------------------------------------------------
+// Filesystem
+// ---------------------------------------------------------------------------
+export function walkDir(dir, pattern) {
+    const results = [];
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return results;
+    }
+    for (const entry of entries) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (entry.name === "node_modules" || entry.name === "dist" || entry.name === ".git")
+                continue;
+            results.push(...walkDir(full, pattern));
+        }
+        else if (pattern.test(entry.name)) {
+            results.push(full);
+        }
+    }
+    return results;
+}
+export function discoverFlows(projectDir) {
+    return walkDir(projectDir, /\.flow\.ts$/);
+}
+// ---------------------------------------------------------------------------
+// Static analysis for `list`/`nav` (no import, regex only)
+// ---------------------------------------------------------------------------
+export function extractFlowNames(filePath) {
+    const src = readFileSync(filePath, "utf-8");
+    const names = [];
+    const re = /export\s+const\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*[=:]/g;
+    let m;
+    while ((m = re.exec(src)) !== null) {
+        const name = m[1];
+        if (name !== undefined)
+            names.push(name);
+    }
+    return names;
+}
+/** `LoginBlock` -> `"login"`; `OverviewMetricsBlock` -> `"overview-metrics"`. */
+export function blockExportToLabel(exportId) {
+    const base = exportId.replace(/Block$/, "");
+    return base
+        .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2")
+        .toLowerCase();
+}
+/** Every `...Block` identifier a `.flow.ts` file imports, in source order. */
+export function parseBlockImports(filePath) {
+    const src = readFileSync(filePath, "utf-8");
+    const names = [];
+    const re = /import\s*\{([^}]*)\}\s*from\s*["'][^"']*\.block(?:\.js)?["']/g;
+    let m;
+    while ((m = re.exec(src)) !== null) {
+        for (const part of m[1].split(",")) {
+            const name = part.trim().split(/\s+as\s+/)[0]?.trim();
+            if (name)
+                names.push(name);
+        }
+    }
+    return names;
+}
+/** Every `page.goto("...")` string literal in a file, in source order. */
+export function extractGotos(filePath) {
+    const src = readFileSync(filePath, "utf-8");
+    const results = [];
+    const re = /\.goto\(\s*["'`]([^"'`]*)["'`]/g;
+    let m;
+    while ((m = re.exec(src)) !== null) {
+        const url = m[1];
+        if (url !== undefined)
+            results.push(url);
+    }
+    return results;
+}
+/** Every `Trait.url({ pathname: "..." })` target in a file, in source order. */
+export function extractUrlTraits(filePath) {
+    const src = readFileSync(filePath, "utf-8");
+    const results = [];
+    const re = /Trait\.url\(\s*\{[^}]*pathname:\s*["'`]([^"'`]*)["'`]/g;
+    let m;
+    while ((m = re.exec(src)) !== null) {
+        const url = m[1];
+        if (url !== undefined)
+            results.push(url);
+    }
+    return results;
+}
+// ---------------------------------------------------------------------------
+// Dynamic import + validation
+// ---------------------------------------------------------------------------
+export async function importModule(filePath) {
+    const url = new URL(`file://${resolve(filePath)}`);
+    return (await import(url.href));
+}
+/** Kept as a named alias - `run`/`validate` below were written against this name first. */
+export const importFlowFile = importModule;
+export function isFlowLike(val) {
+    if (val === null || typeof val !== "object")
+        return false;
+    const obj = val;
+    return typeof obj.run === "function";
+}
+// ---------------------------------------------------------------------------
+// `check` - secondary/complementary to the ActionPage @deprecated warning
+// (src/types.ts). That's the primary, always-on signal an editor shows the
+// instant a regular Block's act() calls a navigation method; this command
+// sweeps a whole project in one shot for contexts with no editor watching
+// (CI, an autonomous agent writing Block files without a language server).
+// See openspec/specs/nav-block-and-check/spec.md for the full rationale.
+// ---------------------------------------------------------------------------
+export function discoverBlocks(projectDir) {
+    return walkDir(projectDir, /\.block\.ts$/);
+}
+export function isBlockLike(val) {
+    if (val === null || typeof val !== "object")
+        return false;
+    const obj = val;
+    if (typeof obj.name !== "string")
+        return false;
+    const instruction = obj.instruction;
+    return instruction !== null && typeof instruction === "object" && typeof instruction?.act === "function";
+}
+/** Set by `defineNavBlock` (non-enumerable) - see src/engine.ts. */
+export function isNavBlockMarked(val) {
+    return val.__waygraphKind === "nav";
+}
+export const NAV_METHOD_CALLS = ["page.goto(", "page.reload(", "page.goBack(", "page.goForward("];
+/**
+ * Matches a selector-taking Trait factory call whose first argument is a
+ * literal string/template, not an identifier or property access - the exact
+ * shape found repeatedly in hand-written assertion Blocks
+ * (`Trait.visible("#some-id")` instead of `Trait.visible(SomeSel.thing)`).
+ * `Trait.url(...)` is deliberately excluded - it takes a URLPatternInit, never
+ * a DOM selector. Same file-scoped-regex bluntness the nav-escape sweep above
+ * already accepts (see openspec/specs/nav-block-and-check/spec.md) - a known
+ * blind spot on string concatenation/template-built selectors, not solved
+ * here for the same "recipe before promotion" reason that check accepts its
+ * own shared-helper blind spot.
+ */
+export const INLINE_SELECTOR_CALL = /\b(?:Trait\.visible|Trait\.text|textEquals|visible)\(\s*["'`]/;

package/dist/cli/flags.d.ts

@@ -0,0 +1,91 @@
+interface RunFlags {
+    step?: boolean;
+    autoplay?: boolean;
+    /** demo only: --auto-next + --video (+ step). */
+    autoPlayVideo?: boolean;
+    /** run/demo: show browser (WAYGRAPH_HEADED=1). */
+    nonHeadless?: boolean;
+    baseUrl?: string;
+    title?: string;
+    /** Set when --video present; empty string = default dir under project. */
+    video?: string;
+    /** Recording viewport, e.g. 1920x1080 (--video-viewport). */
+    videoViewport?: string;
+    /** Global Mem seed JSON (--data). */
+    data?: string;
+    /** Fill any requires key with no --data coverage from registerMemStub's registry (--mem-stub). */
+    memStub?: boolean;
+    /** Flow/chain spec from --blocks <spec>. */
+    blocks?: string;
+    /** 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. */
+    fast?: boolean;
+    /** demo: classic wrap-all block chips instead of carousel. */
+    fullStepper?: boolean;
+    /** demo: force compact mini panel (--mini / WAYGRAPH_MINI=1). */
+    miniStepper?: boolean;
+    /** demo: floating todo dock side (--todo-left | --todo-right). */
+    todoPos?: "left" | "right";
+    /** demo: todo-dock UX — full list / no smart behaviors. */
+    todoUiFull?: boolean;
+    /** demo: todo-dock UX — smart compact/collision/behind (default). */
+    todoUiSmart?: boolean;
+    /** demo/run: expand fastForwardComposeBlock inners as separate steps. */
+    ffExpand?: boolean;
+    /** demo/run: dispute mode — expand FF + keep blitz on former FF inners. */
+    ffDisabled?: boolean;
+    /** Positional args with run flags stripped. */
+    positionals: string[];
+    /** browser/pilot: merge Block trees from preset names or paths (repeatable). */
+    inject?: string[];
+    /** browser/pilot: navigate on start (disables blank page). */
+    goto?: string;
+    /** browser/pilot: force about:blank on start. */
+    blank?: boolean;
+    /** browser/pilot: headless session (default visible for browser). */
+    headlessBrowser?: boolean;
+    /** browser/pilot sessions: machine-readable JSON. */
+    json?: boolean;
+    /** check/typecheck: skip bad-practice warnings. */
+    noPractices?: boolean;
+}
+/**
+ * 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.
+ */
+export declare function parseRunFlags(argv: 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:
+ * package.json `waygraph.baseUrl` (or `baseURL`), then playwright.config `baseURL`.
+ */
+export declare function resolveBaseUrl(projectDir: string): string | undefined;
+/**
+ * Friendly demo defaults: STEP on; headed only for live watch (no --video).
+ * --video / --auto-play-video => headless unless --non-headless.
+ * Call after applyRunFlags so explicit flags already won.
+ */
+export declare function applyDemoDefaults(projectDir: string): void;
+export declare function resolveProjectDir(flags: RunFlags, fallbackIndex?: number): string;
+export declare function resolveSpec(flags: RunFlags): string | undefined;
+/** `shop.flow.ts` / `src/flows/cart-bulk.flow.ts` / absolute path — not a Checkpoint or export id. */
+export declare function looksLikeFlowFileRef(ref: string): boolean;
+/**
+ * Expand `.flow.ts` path segments in a run/demo spec to export names.
+ * `src/flows/shop.flow.ts` → `shopFlow`; leaves `loginFlow then nav-cart` alone.
+ */
+export declare function expandSpecFlowFiles(projectDir: string, spec: string): Promise<string>;
+export {};