@bugmole/cli 0.4.0 → 0.5.0

package/src/registry-worker/signup/attribution.ts

@@ -0,0 +1,194 @@
+// Sign-up attribution: which affiliate code (?ref=) and campaign (utm_* tags)
+// brought a new user. bugmole.com keeps the first visit's tags in the bm_attr
+// cookie on .bugmole.com; the dashboard reads it after sign-in and posts it
+// here once. First touch wins, and only accounts created in the last day can
+// be attributed, so visiting an affiliate link later can't claim an old user.
+// Nothing here is sent anywhere else; Scents reads the table.
+import type { Env, Principal } from "../core.js";
+import { requestJson, response } from "../core.js";
+import { registerRoutes } from "../routes/index.js";
+
+/** How long after an account first appears it may still be attributed. */
+export const ATTRIBUTION_WINDOW_HOURS = 24;
+/** How long after signing up someone may still type an affiliate's referral code. */
+export const REFERRAL_CODE_WINDOW_DAYS = 30;
+
+// The dashboard's own identity for calls made without a person (webhooks).
+const DASHBOARD_SERVICE_ID = "bugmole-dashboard-service";
+const UTM_FIELDS = ["utm_source", "utm_medium", "utm_campaign", "utm_content", "utm_term"] as const;
+// The cookie lives 90 days; allow a little over that, and a little clock skew.
+const MAX_AGE_MS = 100 * 86_400_000;
+const CLOCK_SKEW_MS = 5 * 60_000;
+
+export type SignupAttribution = {
+  ref: string | null;
+  utm_source: string | null;
+  utm_medium: string | null;
+  utm_campaign: string | null;
+  utm_content: string | null;
+  utm_term: string | null;
+  landing_path: string | null;
+  referrer_host: string | null;
+  first_seen_at: string | null;
+};
+
+function text(value: unknown, max: number): string | null {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  // Control characters mean the value was tampered with, not typed into a link.
+  if (!trimmed || /[\u0000-\u001f\u007f]/u.test(trimmed)) return null;
+  return trimmed.slice(0, max);
+}
+
+function ref(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const code = value.trim().toLowerCase();
+  return /^[a-z0-9_-]{1,40}$/u.test(code) ? code : null;
+}
+
+function landingPath(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const pathOnly = value.trim().split(/[?#]/u)[0];
+  // A path on bugmole.com: starts with one slash, no spaces.
+  if (!/^\/(?!\/)[^\s\u0000-\u001f\u007f]*$/u.test(pathOnly)) return null;
+  return pathOnly.slice(0, 200);
+}
+
+function referrerHost(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const host = value.trim().toLowerCase().replace(/\.$/u, "");
+  if (host.length > 100 || !/^[a-z0-9-]+(\.[a-z0-9-]+)*$/u.test(host)) return null;
+  // Only outside sites count as referrers.
+  if (host === "bugmole.com" || host.endsWith(".bugmole.com")) return null;
+  return host;
+}
+
+function firstSeenAt(value: unknown, now: number): string | null {
+  if (typeof value !== "string" || value.length > 40) return null;
+  const at = Date.parse(value);
+  if (!Number.isFinite(at) || at > now + CLOCK_SKEW_MS || at < now - MAX_AGE_MS) return null;
+  return new Date(at).toISOString();
+}
+
+/**
+ * Keeps only values that match the contract; anything else becomes null.
+ * Returns null when nothing usable is left.
+ */
+export function normalizeAttribution(input: unknown, now = Date.now()): SignupAttribution | null {
+  if (!input || typeof input !== "object" || Array.isArray(input)) return null;
+  const source = input as Record<string, unknown>;
+  const result: SignupAttribution = {
+    ref: ref(source.ref),
+    utm_source: null,
+    utm_medium: null,
+    utm_campaign: null,
+    utm_content: null,
+    utm_term: null,
+    landing_path: landingPath(source.landing_path),
+    referrer_host: referrerHost(source.referrer_host),
+    first_seen_at: firstSeenAt(source.first_seen_at, now),
+  };
+  for (const field of UTM_FIELDS) result[field] = text(source[field], 100);
+  const { first_seen_at: _when, ...facts } = result;
+  return Object.values(facts).some((value) => value !== null) ? result : null;
+}
+
+async function recordAttribution(request: Request, env: Env, principal: Principal): Promise<Response> {
+  // Only a person signed in on the dashboard, never an API key or runner.
+  if (principal.apiKeyId || principal.runner || !principal.scopes.includes("*") || principal.aegisId === DASHBOARD_SERVICE_ID) {
+    return response({ error: "Only the dashboard records sign-up attribution" }, 403);
+  }
+  const attribution = normalizeAttribution(await requestJson(request));
+  if (!attribution) return response({ recorded: false, reason: "nothing_to_record" });
+  const values = [
+    attribution.ref,
+    ...UTM_FIELDS.map((field) => attribution[field]),
+    attribution.landing_path,
+    attribution.referrer_host,
+    attribution.first_seen_at,
+  ];
+  const [, inserted] = await env.DB.batch([
+    // The dashboard can call this before anything else has created the row.
+    env.DB.prepare("INSERT INTO aegis_users (id) VALUES (?) ON CONFLICT(id) DO NOTHING").bind(principal.aegisId),
+    env.DB.prepare(`
+      INSERT INTO signup_attribution
+        (aegis_id, ref, utm_source, utm_medium, utm_campaign, utm_content, utm_term, landing_path, referrer_host, first_seen_at)
+      SELECT id, ?, ?, ?, ?, ?, ?, ?, ?, ?
+      FROM aegis_users
+      WHERE id = ? AND created_at > datetime('now', ?)
+      ON CONFLICT(aegis_id) DO NOTHING
+    `).bind(...values, principal.aegisId, `-${ATTRIBUTION_WINDOW_HOURS} hours`),
+  ]);
+  if (inserted?.meta?.changes === 1) return response({ recorded: true }, 201);
+  const existing = await env.DB.prepare("SELECT 1 AS found FROM signup_attribution WHERE aegis_id = ?")
+    .bind(principal.aegisId).first<{ found: number }>();
+  return response({ recorded: false, reason: existing ? "already_recorded" : "account_too_old" });
+}
+
+function signedInPerson(principal: Principal): boolean {
+  return !principal.apiKeyId && !principal.runner && principal.scopes.includes("*") && principal.aegisId !== DASHBOARD_SERVICE_ID;
+}
+
+/** Whether `code` is a real affiliate's code, asked of Scents (which owns the affiliate list). */
+export async function isAffiliateCode(env: Env, code: string): Promise<boolean | null> {
+  if (!env.SCENTS) return null;
+  try {
+    const res = await env.SCENTS.fetch(`https://scents.bugmole.com/public/ref/${encodeURIComponent(code)}`);
+    if (!res.ok) return null;
+    return ((await res.json()) as { valid?: boolean }).valid === true;
+  } catch {
+    return null;
+  }
+}
+
+/** The signed-in person's referral: the code that brought them, and whether they may still type one. */
+async function myReferral(env: Env, principal: Principal): Promise<Response> {
+  const row = await env.DB.prepare(
+    `SELECT u.created_at, a.ref FROM aegis_users u LEFT JOIN signup_attribution a ON a.aegis_id = u.id WHERE u.id = ?`,
+  ).bind(principal.aegisId).first<{ created_at: string | null; ref: string | null }>();
+  const created = row?.created_at ? Date.parse(`${row.created_at.replace(" ", "T")}Z`) : Date.now();
+  const deadline = new Date(created + REFERRAL_CODE_WINDOW_DAYS * 86_400_000);
+  return response({ ref: row?.ref ?? null, canEnterCode: !row?.ref && Date.now() < deadline.getTime(), deadline: deadline.toISOString() });
+}
+
+/**
+ * Someone types an affiliate's referral code (they may have heard it, or
+ * declined the cookie that would have carried the link's ?ref=). Once per
+ * person, within 30 days of signing up, only if nothing credited them yet,
+ * and only a code that belongs to an affiliate, so a typo can't lock in.
+ */
+async function enterReferralCode(request: Request, env: Env, principal: Principal): Promise<Response> {
+  const code = ref(((await requestJson(request)) as { code?: unknown } | null)?.code);
+  if (!code) return response({ error: "Enter the referral code: letters, numbers, - or _" }, 400);
+  const valid = await isAffiliateCode(env, code);
+  if (valid === null) return response({ error: "Couldn't check that code right now. Try again in a minute." }, 503);
+  if (!valid) return response({ error: "That referral code doesn't exist. Check the spelling." }, 404);
+  const [, written] = await env.DB.batch([
+    env.DB.prepare("INSERT INTO aegis_users (id) VALUES (?) ON CONFLICT(id) DO NOTHING").bind(principal.aegisId),
+    env.DB.prepare(`
+      INSERT INTO signup_attribution (aegis_id, ref)
+      SELECT id, ? FROM aegis_users WHERE id = ? AND created_at > datetime('now', ?)
+      ON CONFLICT(aegis_id) DO UPDATE SET ref = excluded.ref WHERE signup_attribution.ref IS NULL
+    `).bind(code, principal.aegisId, `-${REFERRAL_CODE_WINDOW_DAYS} days`),
+  ]);
+  if (written?.meta?.changes === 1) return response({ recorded: true, ref: code }, 201);
+  const existing = await env.DB.prepare("SELECT ref FROM signup_attribution WHERE aegis_id = ?").bind(principal.aegisId).first<{ ref: string | null }>();
+  return response(
+    existing?.ref
+      ? { error: `Your account is already credited to code ${existing.ref}.`, ref: existing.ref }
+      : { error: `Referral codes can only be added in the first ${REFERRAL_CODE_WINDOW_DAYS} days after signing up.` },
+    409,
+  );
+}
+
+registerRoutes(async ({ request, env, principal, url }) => {
+  if (url.pathname === "/api/attribution/me" || url.pathname === "/api/attribution/code") {
+    if (!signedInPerson(principal)) return response({ error: "Only the dashboard can do this" }, 403);
+    if (url.pathname === "/api/attribution/me" && request.method === "GET") return myReferral(env, principal);
+    if (url.pathname === "/api/attribution/code" && request.method === "POST") return enterReferralCode(request, env, principal);
+    return response({ error: "Method not allowed" }, 405);
+  }
+  if (url.pathname !== "/api/attribution") return null;
+  if (request.method !== "POST") return response({ error: "Method not allowed" }, 405);
+  return recordAttribution(request, env, principal);
+});

package/src/runtime/ai-exploration.test.ts

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import test from "node:test";
-import { explorationPrompt, parseExploration } from "./ai-exploration.js";
+import { explorationPrompt, parseCheckedExploration, parseExploration } from "./ai-exploration.js";
 import type { DiscoveryResult } from "./site-discovery.js";
 
 const result: DiscoveryResult = {
@@ -30,3 +30,36 @@ test("parseExploration only accepts well-formed journeys with at least two steps
   assert.equal(flows[0].name, "Sign up then buy");
   assert.equal(flows[0].kind, "journey");
 });
+
+// The real case that prompted the check: app.bugmole.com's sign-in page has one
+// button and no links, and the model wrote journeys through a "Forgot
+// password?" link and a sign-up page that don't exist.
+const signInOnly: DiscoveryResult = {
+  baseUrl: "https://app.test",
+  pages: [{ route: "/login", url: "https://app.test/login", title: "Bugmole", heading: "Welcome back", path: [], links: [], forms: [], controls: ["Continue with Aegis →"] }],
+  flows: [],
+  events: [],
+};
+
+test("the prompt shows the buttons discovery saw, and forbids inventing others", () => {
+  const prompt = explorationPrompt(signInOnly);
+  assert.match(prompt, /"buttons":\["Continue with Aegis →"\]/);
+  assert.match(prompt, /Never invent a page, link or button/);
+});
+
+test("journeys through controls or pages discovery never saw are set aside with the reason", () => {
+  const reply = JSON.stringify({
+    journeys: [
+      { name: "Forgot password", steps: [{ openLink: "/login" }, { tapOn: "Forgot password?" }, { assertVisible: "Reset your password" }] },
+      { name: "Sign up", steps: [{ openLink: "/signup" }, { assertVisible: "Create account" }] },
+      { name: "Hidden check", steps: [{ openLink: "/login" }, { assertVisible: "Remember me" }, { tapOn: "Continue with Aegis" }] },
+      { name: "Continue to Aegis", steps: [{ openLink: "/login" }, { assertVisible: "Welcome back" }, { tapOn: "Continue with Aegis" }, { assertVisible: "Sign in to Aegis" }] },
+    ],
+  });
+  const { flows, setAside } = parseCheckedExploration(reply, signInOnly);
+  assert.deepEqual(flows.map((flow) => flow.name), ["Continue to Aegis"], "the last assertion may be new text: it is the outcome");
+  assert.deepEqual(setAside.map((item) => item.name), ["Forgot password", "Sign up", "Hidden check"]);
+  assert.match(setAside[0].reason, /taps “Forgot password\?”/);
+  assert.match(setAside[1].reason, /opens \/signup/);
+  assert.match(setAside[2].reason, /expects “Remember me”/);
+});

package/src/runtime/ai-exploration.ts

@@ -4,7 +4,7 @@
 import YAML from "yaml";
 import { parseMaestroStyleFlow } from "./flow-language.js";
 import { extractJson } from "./platform-ai.js";
-import { slugify, type DiscoveredFlow, type DiscoveryResult } from "./site-discovery.js";
+import { slugify, type DiscoveredFlow, type DiscoveredPage, type DiscoveryResult } from "./site-discovery.js";
 
 const MAX_JOURNEYS = 8;
 const MAX_STEPS = 40;
@@ -19,12 +19,13 @@ export function explorationPrompt(result: DiscoveryResult, persona?: Exploration
     reachedBy: page.path,
     links: page.links.slice(0, 15).map((link) => link.label),
     forms: page.forms.map((form) => ({ name: form.name, fields: form.fields.map((field) => `${field.label} (${field.type}${field.required ? ", required" : ""})`), submit: form.submit })),
+    ...(page.controls?.length ? { buttons: page.controls.slice(0, 20) } : {}),
   }));
   return [
     "You are a QA engineer. Below is a map of a web app a crawler just explored.",
     ...(persona ? [`Decide what's worth testing from this persona's point of view — ${persona.name}: ${persona.description}`] : []),
     `Write up to ${MAX_JOURNEYS} end-to-end user journeys worth testing that span several pages (for example: sign up, then buy something).`,
-    "Only use pages, links, buttons and fields that appear in the map. Don't repeat single-page visits; those already exist.",
+    "Only use pages, links, buttons and fields that appear in the map, with their exact text. Never invent a page, link or button; if the map is too small for a journey, return fewer journeys or none. Don't repeat single-page visits; those already exist.",
     "Use obvious sample data (qa@example.com, Bugmole). Write passwords as \"{{secret.APP_PASSWORD}}\". Never submit destructive actions (delete, cancel, unsubscribe).",
     "Steps: openLink: \"/path\"; tapOn: \"<visible text>\"; inputText: \"<text>\"; assertVisible: \"<text>\"; scrollUntilVisible: { element: \"<text>\" }.",
     "Every journey starts with openLink and ends with an assertVisible that proves it worked.",
@@ -35,7 +36,99 @@ export function explorationPrompt(result: DiscoveryResult, persona?: Exploration
   ].join("\n");
 }
 
-export function parseExploration(reply: string, baseUrl: string, existing: readonly DiscoveredFlow[]): DiscoveredFlow[] {
+const normalize = (value: string) => value.toLowerCase().replace(/\s+/g, " ").replace(/^[^\p{L}\p{N}]+|[^\p{L}\p{N}]+$/gu, "");
+
+/**
+ * Everything a visitor could see or type into on the explored pages, and the
+ * routes that exist. A journey step outside this is something the model made
+ * up, however plausible ("Forgot password?" on a page that has no such link).
+ */
+function observedOn(pages: readonly DiscoveredPage[], baseUrl: string) {
+  const words = new Set<string>();
+  const add = (value?: string) => {
+    const normal = value ? normalize(value) : "";
+    if (normal) words.add(normal);
+  };
+  const routes = new Set<string>(["/"]);
+  for (const page of pages) {
+    routes.add(page.route);
+    add(page.title);
+    add(page.heading);
+    for (const link of page.links) {
+      add(link.label);
+      add(link.menu);
+      routes.add(link.route);
+    }
+    for (const form of page.forms) {
+      add(form.name);
+      add(form.submit);
+      for (const field of form.fields) add(field.label);
+    }
+    for (const control of page.controls ?? []) add(control);
+  }
+  const seen = (text: string) => {
+    const target = normalize(text);
+    if (!target) return false;
+    for (const word of words) {
+      if (word === target || (target.length >= 3 && word.includes(target)) || (word.length >= 3 && target.includes(word))) return true;
+    }
+    return false;
+  };
+  const routeExists = (link: string) => {
+    try {
+      const url = new URL(link, baseUrl);
+      if (url.origin !== new URL(baseUrl).origin) return false;
+      return routes.has(url.pathname) || routes.has(url.pathname.replace(/\/$/, "") || "/");
+    } catch {
+      return false;
+    }
+  };
+  return { seen, routeExists };
+}
+
+/**
+ * Why a journey can't be trusted, or null. Taps, scrolls and assertions along
+ * the way must name something observed, and every openLink a real route. The
+ * last assertVisible may name new text: it is the outcome the journey proves
+ * (a confirmation after a form), which discovery, being read-only, never saw.
+ */
+function unobservedStep(steps: readonly unknown[], observed: ReturnType<typeof observedOn>): string | null {
+  for (const [index, raw] of steps.entries()) {
+    const step = raw as Record<string, unknown>;
+    if (typeof step?.openLink === "string" && !observed.routeExists(step.openLink)) return `opens ${step.openLink}, which wasn't found`;
+    const tap = typeof step?.tapOn === "string" ? step.tapOn : undefined;
+    if (tap && !observed.seen(tap)) return `taps “${tap}”, which isn't on any explored page`;
+    const scroll = (step?.scrollUntilVisible as { element?: unknown } | undefined)?.element;
+    if (typeof scroll === "string" && !observed.seen(scroll)) return `looks for “${scroll}”, which isn't on any explored page`;
+    const assertion = typeof step?.assertVisible === "string" ? step.assertVisible : undefined;
+    if (assertion && index < steps.length - 1 && !observed.seen(assertion)) return `expects “${assertion}”, which isn't on any explored page`;
+  }
+  return null;
+}
+
+export type CheckedExploration = { flows: DiscoveredFlow[]; setAside: Array<{ name: string; reason: string }> };
+
+/**
+ * Parses the model's journeys and keeps only those built from what discovery
+ * actually saw on `pages`; the rest are set aside with the reason.
+ */
+export function parseCheckedExploration(reply: string, result: Pick<DiscoveryResult, "baseUrl" | "pages" | "flows">): CheckedExploration {
+  const observed = observedOn(result.pages, result.baseUrl);
+  const setAside: CheckedExploration["setAside"] = [];
+  const flows = parseExploration(reply, result.baseUrl, result.flows, (name, steps) => {
+    const reason = unobservedStep(steps, observed);
+    if (reason) setAside.push({ name, reason });
+    return !reason;
+  });
+  return { flows, setAside };
+}
+
+export function parseExploration(
+  reply: string,
+  baseUrl: string,
+  existing: readonly DiscoveredFlow[],
+  accept: (name: string, steps: readonly unknown[]) => boolean = () => true,
+): DiscoveredFlow[] {
   const data = extractJson(reply) as { journeys?: unknown } | null;
   if (!data || !Array.isArray(data.journeys)) return [];
   const taken = new Set(existing.map((flow) => flow.id));
@@ -44,6 +137,7 @@ export function parseExploration(reply: string, baseUrl: string, existing: reado
     const name = typeof journey?.name === "string" ? journey.name.trim().slice(0, 80) : "";
     const steps = Array.isArray(journey?.steps) ? journey.steps.slice(0, MAX_STEPS) : [];
     if (!name || steps.length < 2) continue;
+    if (!accept(name, steps)) continue;
     const content = `url: ${baseUrl}\nname: ${JSON.stringify(name)}\n---\n${YAML.stringify(steps)}`;
     let parsed;
     try {

package/src/runtime/appium-driver.ts

@@ -139,6 +139,12 @@ export class AppiumDriver implements AppDriver {
               }
               counter.n += step.steps.length;
               if (lastError) throw lastError;
+            } else if (step.type === "assertLayout" || step.type === "assertLinks") {
+              // Page checks read the page's layout and links, which a device
+              // cloud session doesn't expose; they run in the browser targets.
+              steps.push({ sequenceNumber: index, status: "passed", label: describeStepLabel(step), message: "Not checked on device clouds; checked in the browser targets", durationMs: 0 });
+              log.push(`Step ${index + 1}: ${describeStepForLog(step)} — skipped (checked in browsers, not on device clouds)`);
+              continue;
             } else {
               await this.step(session!, step, mode, flow, context, outDir, artifacts);
             }

package/src/runtime/discovery-task.ts

@@ -6,8 +6,8 @@ import { createProjectObjectStore } from "../storage/create-object-store.js";
 import { projectPrefix } from "../storage/keys.js";
 import { readJourneyGraph, writeJourneyGraph } from "./journey-editor.js";
 import type { JourneyEdge, JourneyNode, UserJourney } from "./journey-graph.js";
-import { discoverSite, type DiscoveryResult } from "./site-discovery.js";
-import { explorationPrompt, parseExploration, type ExplorationPersona } from "./ai-exploration.js";
+import { discoverSite, stoppedAtSignIn, type DiscoveryResult } from "./site-discovery.js";
+import { explorationPrompt, parseCheckedExploration, type ExplorationPersona } from "./ai-exploration.js";
 import { modelCaller } from "./platform-ai.js";
 
 /** Discovery tasks queued as "Explore with AI …" also have a model write multi-page journeys. */
@@ -248,7 +248,21 @@ export async function runDiscoveryTask(
         await send("running");
       },
     });
-    if (discoveryUsesAi(task)) {
+    // Everything reachable was a sign-in screen. Say so plainly, and don't
+    // ask AI to imagine the app behind it: that spends credits on journeys
+    // through pages nobody has seen.
+    const signInWall = stoppedAtSignIn(result);
+    if (signInWall) {
+      result.events.push({
+        at: new Date().toISOString(),
+        kind: "skip",
+        text: "Stopped at a sign-in page: Bugmole Cloud can't sign in to your app yet, so everything behind it is unexplored. "
+          + "To explore signed in, run discovery from your machine or CI with a sign-in flow: bugmole --mode discover --sign-in <flow>.",
+      });
+      latest = progressOf(url, result);
+      await send("running");
+    }
+    if (discoveryUsesAi(task) && !signInWall) {
       const caller = modelCaller(cfg, { projectId: cfg.project?.id ?? "default", requestId: task.id });
       const note = (text: string, kind: "flows" | "error") => {
         result.events.push({ at: new Date().toISOString(), kind, text });
@@ -262,9 +276,13 @@ export async function runDiscoveryTask(
         await note(persona ? `Asking AI for multi-page journeys as ${persona.name}…` : "Asking AI for multi-page journeys…", "flows");
         try {
           const reply = await caller(explorationPrompt(result, persona ?? undefined), "exploration");
-          const journeys = parseExploration(reply.text, result.baseUrl, result.flows);
+          const { flows: journeys, setAside } = parseCheckedExploration(reply.text, result);
           result.flows.push(...journeys);
           await note(`AI wrote ${journeys.length} journey${journeys.length === 1 ? "" : "s"}`, "flows");
+          for (const journey of setAside.slice(0, 5)) {
+            await note(`Set aside “${journey.name}”: it ${journey.reason}`, "error");
+          }
+          if (setAside.length > 5) await note(`Set aside ${setAside.length - 5} more that used things discovery didn't see`, "error");
         } catch (error) {
           await note(`AI exploration failed: ${error instanceof Error ? error.message : String(error)}`, "error");
         }
@@ -273,7 +291,8 @@ export async function runDiscoveryTask(
     const planIds = await saveDiscovery(cfg, client, result);
     latest = progressOf(url, result, planIds);
     await send("completed", {
-      completionSummary: `Explored ${result.pages.length} page(s) of ${url} and discovered ${result.flows.length} flow(s).`,
+      completionSummary: `Explored ${result.pages.length} page(s) of ${url} and discovered ${result.flows.length} flow(s).`
+        + (signInWall ? " Stopped at a sign-in page; the app behind it is unexplored." : ""),
     });
   } catch (error) {
     await send("error", { errorMessage: error instanceof Error ? error.message : String(error) });

package/src/runtime/flow-language.ts

@@ -25,6 +25,18 @@ export type FlowStep =
    * sitting on top of a link or button and silently swallowing the tap.
    */
   | { type: "assertClickable"; text: string; index: number; timeoutMs?: number }
+  /**
+   * The page looks right at this screen size: it doesn't scroll sideways,
+   * no text spills out of the card or box it sits in, and none is cut off
+   * without an ellipsis. What a person notices first on a phone.
+   */
+  | { type: "assertLayout" }
+  /**
+   * Every link on the page leads somewhere. Same-site links must answer;
+   * with `external`, other sites' links are checked too (a 404, 410 or
+   * server error fails; sites that refuse robots are not counted).
+   */
+  | { type: "assertLinks"; external: boolean }
   | { type: "scrollUntilVisible"; text: string }
   | { type: "wait"; ms: number }
   | { type: "takeScreenshot"; name: string }
@@ -128,6 +140,8 @@ function parseStep(raw: unknown): FlowStep {
     if (raw === "launchApp") return { type: "launchApp" };
     if (raw === "stopApp") return { type: "stopApp" };
     if (raw === "eraseText") return { type: "eraseText" };
+    if (raw === "assertLayout") return { type: "assertLayout" };
+    if (raw === "assertLinks") return { type: "assertLinks", external: false };
     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
@@ -187,6 +201,11 @@ function parseStep(raw: unknown): FlowStep {
     }
     return { type: "assertVisible", text: requireText(value.visible, "extendedWaitUntil"), timeoutMs };
   }
+  if ("assertLayout" in record) return { type: "assertLayout" };
+  if ("assertLinks" in record) {
+    const value = asRecord(record.assertLinks);
+    return { type: "assertLinks", external: Boolean(value?.external) };
+  }
   if ("scrollUntilVisible" in record) {
     const value = asRecord(record.scrollUntilVisible);
     return { type: "scrollUntilVisible", text: requireText(value ? value.element : record.scrollUntilVisible, "scrollUntilVisible") };
@@ -351,6 +370,8 @@ export function describeStepLabel(step: FlowStep): string {
     case "assertVisible": return `See “${step.text}”`;
     case "assertNotVisible": return `No “${step.text}”`;
     case "assertClickable": return `“${step.text}” is clickable`;
+    case "assertLayout": return "Nothing spills off the screen";
+    case "assertLinks": return step.external ? "Every link works" : "Every link on the site works";
     case "scrollUntilVisible": return `Scroll to “${step.text}”`;
     case "wait": return `Wait ${step.ms}ms`;
     case "takeScreenshot": return `Screenshot “${step.name}”`;

package/src/runtime/journey-editor.ts

@@ -98,6 +98,45 @@ function nextRevision(journey: UserJourney): UserJourney {
   };
 }
 
+/**
+ * A run that passed proves the flow it ran. Discovery saves what it finds as
+ * draft journeys, and only stable ones are drawn in the dashboard's journey
+ * graph, but nothing promoted them: a cloud run has no agent to call
+ * stabilizeJourney. This does it for the drafts discovery wrote, reading the
+ * stored graph (a cloud container has no local copy). Journeys an agent or a
+ * person made are left for them to stabilize. Returns the journey promoted.
+ */
+export async function stabilizeAfterPassingRun(
+  cfg: JourneyConfig,
+  run: { id: string; planId?: string | null; journeyId?: string | null },
+): Promise<string | null> {
+  const store = storeFor(cfg);
+  const key = `${projectPrefix(projectId(cfg))}/journeys/graph.json`;
+  if (!(await store.has(key))) return null;
+  const parsed = JSON.parse(await store.getText(key)) as JourneyGraph;
+  const graph = repairJourneyGraph({
+    ...emptyJourneyGraph(projectId(cfg)),
+    ...parsed,
+    journeys: Array.isArray(parsed.journeys) ? parsed.journeys : [],
+    nodes: Array.isArray(parsed.nodes) ? parsed.nodes : [],
+    edges: Array.isArray(parsed.edges) ? parsed.edges : [],
+  }, projectId(cfg));
+  const current = graph.journeys.find((journey) =>
+    (run.journeyId && journey.id === run.journeyId) || (run.planId && journey.metadata?.planId === run.planId));
+  if (!current || current.stability === "stable" || current.metadata?.generatedBy !== "site-discovery") return null;
+  const journey: UserJourney = {
+    ...current,
+    status: "published",
+    stability: "stable",
+    linkedToGraph: true,
+    verificationRunId: run.id,
+    verifiedAt: new Date().toISOString(),
+  };
+  graph.journeys = graph.journeys.map((item) => item.id === current.id ? journey : item);
+  await writeJourneyGraph(cfg, graph);
+  return journey.id;
+}
+
 export async function stabilizeJourney(
   cfg: JourneyConfig,
   input: { journeyId: string; verificationRunId: string; verifiedAt?: string },

package/src/runtime/journey-graph.test.ts

@@ -9,6 +9,7 @@ import {
   addJourneyTransition,
   createJourney,
   reuseJourneyStep,
+  stabilizeAfterPassingRun,
   stabilizeJourney,
   nextJourneyTask,
   readJourneyGraph,
@@ -255,3 +256,44 @@ test("requires runtime transition and terminal-goal completion for source paths"
   assert.equal(nextJourneyTask(cfg, "top-up-flow").status, "exhausted");
   await fs.promises.rm(root, { recursive: true, force: true });
 });
+
+test("a passing run promotes the explored draft it proved, from the stored graph alone", async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "bugmole-promote-"));
+  const storage = { provider: "local", localDirectory: path.join(root, "artifacts") };
+  const writer = { project: { id: "demo" }, runtime: { spec_dir: path.join(root, "spec"), artifacts_dir: path.join(root, "artifacts") }, storage };
+  // A cloud container: same project storage, no local copy of the graph.
+  const container = { project: { id: "demo" }, runtime: { spec_dir: path.join(root, "container"), artifacts_dir: path.join(root, "artifacts") }, storage };
+  try {
+    const graph = emptyJourneyGraph("demo");
+    graph.nodes = [{ id: "screen:/login", title: "Welcome back", kind: "screen", route: "/login" }];
+    const draft = (id: string, generatedBy?: string) => ({
+      id,
+      name: id,
+      actor: "visitor",
+      startNodeId: "screen:/login",
+      nodeIds: ["screen:/login"],
+      edgeIds: [],
+      revision: 1,
+      status: "draft" as const,
+      sourceOfTruth: "canonical_flow" as const,
+      stability: "discovered" as const,
+      linkedToGraph: false,
+      metadata: generatedBy ? { generatedBy, planId: id } : {},
+    });
+    graph.journeys = [draft("discovered-welcome-back", "site-discovery"), draft("hand-made")];
+    await writeJourneyGraph(writer, graph);
+
+    assert.equal(await stabilizeAfterPassingRun(container, { id: "run_1", planId: "discovered-welcome-back", journeyId: "discovered-welcome-back" }), "discovered-welcome-back");
+    const stored = JSON.parse(fs.readFileSync(path.join(root, "artifacts", "projects", "demo", "journeys", "graph.json"), "utf8"));
+    const promoted = stored.journeys.find((journey: { id: string }) => journey.id === "discovered-welcome-back");
+    assert.equal(promoted.stability, "stable");
+    assert.equal(promoted.linkedToGraph, true);
+    assert.equal(promoted.verificationRunId, "run_1");
+
+    assert.equal(await stabilizeAfterPassingRun(container, { id: "run_2", journeyId: "hand-made" }), null, "journeys a person or agent made are theirs to stabilize");
+    assert.equal(await stabilizeAfterPassingRun(container, { id: "run_3", journeyId: "discovered-welcome-back" }), null, "already stable");
+    assert.equal(await stabilizeAfterPassingRun(container, { id: "run_4", journeyId: "missing" }), null);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});