@bugmole/cli 0.4.0

package/src/integrations/device-farm.ts

@@ -0,0 +1,155 @@
+// AWS Device Farm through its managed Appium endpoint: a remote access
+// session on a real device, driven over WebDriver, metered by AWS in minutes.
+// https://docs.aws.amazon.com/devicefarm/latest/developerguide/appium-endpoint.html
+import { signAwsRequest, type AwsCredentials } from "./aws-sigv4.js";
+
+/** Device Farm only runs in us-west-2. */
+export const DEVICE_FARM_REGION = "us-west-2";
+const ENDPOINT = `https://devicefarm.${DEVICE_FARM_REGION}.amazonaws.com/`;
+
+export type DeviceFarmOptions = { credentials: AwsCredentials; projectArn: string; fetch?: typeof fetch };
+
+export class DeviceFarmError extends Error {
+  constructor(readonly status: number, readonly code: string, message: string) {
+    super(message);
+    this.name = "DeviceFarmError";
+  }
+}
+
+export type DeviceFarmDevice = {
+  arn: string;
+  name: string;
+  platform: "ANDROID" | "IOS";
+  os: string;
+  formFactor?: string;
+  availability?: string;
+  manufacturer?: string;
+};
+
+export type RemoteSession = {
+  arn: string;
+  status: string;
+  result?: string;
+  remoteDriverEndpoint?: string;
+  meteredMinutes?: number;
+  message?: string;
+};
+
+export async function deviceFarmCall<T>(options: DeviceFarmOptions, action: string, payload: Record<string, unknown>): Promise<T> {
+  const body = JSON.stringify(payload);
+  const headers = await signAwsRequest({
+    credentials: options.credentials,
+    region: DEVICE_FARM_REGION,
+    service: "devicefarm",
+    method: "POST",
+    url: ENDPOINT,
+    headers: { "content-type": "application/x-amz-json-1.1", "x-amz-target": `DeviceFarm_20150623.${action}` },
+    body,
+  });
+  const response = await (options.fetch ?? fetch)(ENDPOINT, { method: "POST", headers, body });
+  const text = await response.text();
+  const parsed = text ? JSON.parse(text) : {};
+  if (!response.ok) {
+    const code = String(parsed.__type ?? "").split("#").pop() || `http_${response.status}`;
+    throw new DeviceFarmError(response.status, code, `Device Farm ${action} failed: ${code}${parsed.message ? ` (${parsed.message})` : ""}`);
+  }
+  return parsed as T;
+}
+
+export async function listDevices(options: DeviceFarmOptions): Promise<DeviceFarmDevice[]> {
+  const devices: DeviceFarmDevice[] = [];
+  let nextToken: string | undefined;
+  do {
+    const page = await deviceFarmCall<{ devices?: DeviceFarmDevice[]; nextToken?: string }>(options, "ListDevices", {
+      arn: options.projectArn,
+      ...(nextToken ? { nextToken } : {}),
+    });
+    devices.push(...(page.devices ?? []));
+    nextToken = page.nextToken;
+  } while (nextToken && devices.length < 2_000);
+  return devices;
+}
+
+/** Uploads an app build (APK or IPA) and waits until Device Farm has processed it. */
+export async function uploadApp(options: DeviceFarmOptions, app: { name: string; platform: "android" | "ios"; bytes: Uint8Array }, pollMs = 3_000): Promise<string> {
+  const created = await deviceFarmCall<{ upload: { arn: string; url: string } }>(options, "CreateUpload", {
+    projectArn: options.projectArn,
+    name: app.name,
+    type: app.platform === "android" ? "ANDROID_APP" : "IOS_APP",
+    contentType: "application/octet-stream",
+  });
+  const put = await (options.fetch ?? fetch)(created.upload.url, {
+    method: "PUT",
+    headers: { "content-type": "application/octet-stream" },
+    body: app.bytes as BodyInit,
+  });
+  if (!put.ok) throw new DeviceFarmError(put.status, "UploadFailed", `Device Farm didn't accept the app upload (${put.status})`);
+  for (let attempt = 0; attempt < 100; attempt++) {
+    const { upload } = await deviceFarmCall<{ upload: { status: string; message?: string } }>(options, "GetUpload", { arn: created.upload.arn });
+    if (upload.status === "SUCCEEDED") return created.upload.arn;
+    if (upload.status === "FAILED") throw new DeviceFarmError(400, "UploadFailed", `Device Farm couldn't process the app: ${upload.message ?? "unknown reason"}`);
+    await new Promise((resolve) => setTimeout(resolve, pollMs));
+  }
+  throw new DeviceFarmError(504, "UploadTimeout", "Device Farm took too long to process the app");
+}
+
+function toSession(raw: any): RemoteSession {
+  return {
+    arn: raw.arn,
+    status: raw.status,
+    result: raw.result,
+    remoteDriverEndpoint: raw.endpoints?.remoteDriverEndpoint,
+    meteredMinutes: typeof raw.deviceMinutes?.metered === "number" ? raw.deviceMinutes.metered : undefined,
+    message: raw.message,
+  };
+}
+
+export async function startSession(
+  options: DeviceFarmOptions,
+  params: { deviceArn: string; name: string; appArn?: string; appiumVersion?: "2" | "3" },
+  pollMs = 5_000,
+  maxWaitMs = 15 * 60_000,
+): Promise<RemoteSession> {
+  const created = await deviceFarmCall<{ remoteAccessSession: any }>(options, "CreateRemoteAccessSession", {
+    projectArn: options.projectArn,
+    deviceArn: params.deviceArn,
+    name: params.name.slice(0, 250),
+    ...(params.appArn ? { appArn: params.appArn } : {}),
+    configuration: { parameters: { "appium:version": params.appiumVersion ?? "3" } },
+  });
+  let session = toSession(created.remoteAccessSession);
+  const deadline = Date.now() + maxWaitMs;
+  while (!(session.status === "RUNNING" && session.remoteDriverEndpoint)) {
+    if (["COMPLETED", "STOPPING"].includes(session.status) || session.result === "ERRORED" || session.result === "FAILED") {
+      throw new DeviceFarmError(409, "SessionEnded", `The device session ended before it started${session.message ? `: ${session.message}` : ""}`);
+    }
+    if (Date.now() > deadline) {
+      await stopSession(options, session.arn).catch(() => undefined);
+      throw new DeviceFarmError(504, "SessionTimeout", "No device became available in time");
+    }
+    await new Promise((resolve) => setTimeout(resolve, pollMs));
+    session = toSession((await deviceFarmCall<{ remoteAccessSession: any }>(options, "GetRemoteAccessSession", { arn: session.arn })).remoteAccessSession);
+  }
+  return session;
+}
+
+export async function stopSession(options: DeviceFarmOptions, arn: string): Promise<void> {
+  await deviceFarmCall(options, "StopRemoteAccessSession", { arn });
+}
+
+/** Waits for a stopped session's final minutes. */
+export async function finishedSession(options: DeviceFarmOptions, arn: string, pollMs = 5_000, maxWaitMs = 5 * 60_000): Promise<RemoteSession> {
+  const deadline = Date.now() + maxWaitMs;
+  for (;;) {
+    const session = toSession((await deviceFarmCall<{ remoteAccessSession: any }>(options, "GetRemoteAccessSession", { arn })).remoteAccessSession);
+    if (session.status === "COMPLETED" || Date.now() > deadline) return session;
+    await new Promise((resolve) => setTimeout(resolve, pollMs));
+  }
+}
+
+export type DeviceFarmArtifact = { name: string; type: string; extension: string; url: string };
+
+export async function sessionArtifacts(options: DeviceFarmOptions, arn: string): Promise<DeviceFarmArtifact[]> {
+  const result = await deviceFarmCall<{ artifacts?: DeviceFarmArtifact[] }>(options, "ListArtifacts", { arn, type: "FILE" });
+  return result.artifacts ?? [];
+}

package/src/integrations/github-app.test.ts

@@ -0,0 +1,57 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createVerify, generateKeyPairSync } from "node:crypto";
+import { createCheckRun, githubAppJwt, installationToken, pkcs1ToPkcs8 } from "./github-app.js";
+
+const { privateKey, publicKey } = generateKeyPairSync("rsa", { modulusLength: 2048 });
+const pkcs1Pem = privateKey.export({ type: "pkcs1", format: "pem" }).toString();
+const pkcs8Pem = privateKey.export({ type: "pkcs8", format: "pem" }).toString();
+
+function verifyJwt(jwt: string) {
+  const [header, payload, signature] = jwt.split(".");
+  const verifier = createVerify("RSA-SHA256");
+  verifier.update(`${header}.${payload}`);
+  return {
+    valid: verifier.verify(publicKey, Buffer.from(signature, "base64url")),
+    header: JSON.parse(Buffer.from(header, "base64url").toString()),
+    payload: JSON.parse(Buffer.from(payload, "base64url").toString()),
+  };
+}
+
+test("the app JWT is signed with GitHub's PKCS#1 key as downloaded, escaped newlines and all", async () => {
+  const now = Date.parse("2026-09-17T10:00:00Z");
+  for (const pem of [pkcs1Pem, pkcs8Pem, pkcs1Pem.replace(/\n/g, "\\n")]) {
+    const jwt = await githubAppJwt({ GITHUB_APP_ID: "12345", GITHUB_APP_PRIVATE_KEY: pem }, now);
+    const { valid, header, payload } = verifyJwt(jwt);
+    assert.equal(valid, true);
+    assert.deepEqual(header, { alg: "RS256", typ: "JWT" });
+    assert.deepEqual(payload, { iat: now / 1000 - 60, exp: now / 1000 + 540, iss: "12345" });
+  }
+  await assert.rejects(githubAppJwt({}), /isn't configured/);
+});
+
+test("PKCS#1 is wrapped into the PKCS#8 structure byte for byte", () => {
+  const pkcs1 = privateKey.export({ type: "pkcs1", format: "der" });
+  const pkcs8 = privateKey.export({ type: "pkcs8", format: "der" });
+  assert.deepEqual(Buffer.from(pkcs1ToPkcs8(new Uint8Array(pkcs1))), pkcs8);
+});
+
+test("installation tokens are cached until close to expiry, and calls go out as the installation", async () => {
+  const calls: Array<{ url: string; auth: string | null; body?: string }> = [];
+  const doFetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const url = String(input);
+    calls.push({ url, auth: new Headers(init?.headers).get("authorization"), body: init?.body as string | undefined });
+    if (url.endsWith("/access_tokens")) return Response.json({ token: "ghs_install", expires_at: new Date(Date.now() + 3_600_000).toISOString() }, { status: 201 });
+    return Response.json({ id: 77, html_url: "https://github.com/acme/shop/runs/77" }, { status: 201 });
+  }) as unknown as typeof fetch;
+  const env = { GITHUB_APP_ID: "999", GITHUB_APP_PRIVATE_KEY: pkcs8Pem, GITHUB_FETCH: doFetch };
+  assert.equal(await installationToken(env, 42), "ghs_install");
+  assert.equal(await installationToken(env, 42), "ghs_install");
+  const check = await createCheckRun(env, 42, "acme/shop", { name: "Bugmole: checkout", head_sha: "abc", status: "queued" });
+  assert.equal(check.id, 77);
+  assert.equal(calls.filter((call) => call.url.endsWith("/access_tokens")).length, 1);
+  const create = calls.at(-1)!;
+  assert.equal(create.url, "https://api.github.com/repos/acme/shop/check-runs");
+  assert.equal(create.auth, "Bearer ghs_install");
+  assert.deepEqual(JSON.parse(create.body!), { name: "Bugmole: checkout", head_sha: "abc", status: "queued" });
+});

package/src/integrations/github-app.ts

@@ -0,0 +1,143 @@
+// A GitHub App client that runs anywhere WebCrypto does (Cloudflare Workers,
+// Node): the app JWT, installation tokens, and the few REST calls Bugmole
+// makes as the app (check runs, issues).
+
+export type GithubAppEnv = {
+  GITHUB_APP_ID?: string;
+  /** PEM, PKCS#1 ("BEGIN RSA PRIVATE KEY", GitHub's download) or PKCS#8. Newlines may be escaped as \n. */
+  GITHUB_APP_PRIVATE_KEY?: string;
+  /** Test seam. */
+  GITHUB_FETCH?: typeof fetch;
+};
+
+export class GithubAppError extends Error {
+  constructor(readonly status: number, message: string) {
+    super(message);
+  }
+}
+
+const API = "https://api.github.com";
+
+export function githubAppConfigured(env: GithubAppEnv): boolean {
+  return Boolean(env.GITHUB_APP_ID?.trim() && env.GITHUB_APP_PRIVATE_KEY?.trim());
+}
+
+function base64UrlBytes(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+
+function base64UrlJson(value: unknown): string {
+  return base64UrlBytes(new TextEncoder().encode(JSON.stringify(value)));
+}
+
+function derLength(length: number): number[] {
+  if (length < 0x80) return [length];
+  const bytes: number[] = [];
+  let rest = length;
+  while (rest > 0) {
+    bytes.unshift(rest & 0xff);
+    rest >>= 8;
+  }
+  return [0x80 | bytes.length, ...bytes];
+}
+
+function der(tag: number, content: Uint8Array): Uint8Array {
+  return new Uint8Array([tag, ...derLength(content.length), ...content]);
+}
+
+/** Wraps a PKCS#1 RSAPrivateKey in the PKCS#8 structure WebCrypto imports. */
+export function pkcs1ToPkcs8(pkcs1: Uint8Array): Uint8Array {
+  const version = new Uint8Array([0x02, 0x01, 0x00]);
+  // SEQUENCE { OID 1.2.840.113549.1.1.1 (rsaEncryption), NULL }
+  const algorithm = new Uint8Array([0x30, 0x0d, 0x06, 0x09, 0x2a, 0x86, 0x48, 0x86, 0xf7, 0x0d, 0x01, 0x01, 0x01, 0x05, 0x00]);
+  const key = der(0x04, pkcs1);
+  return der(0x30, new Uint8Array([...version, ...algorithm, ...key]));
+}
+
+function pemBody(pem: string): Uint8Array {
+  const base64 = pem.replace(/-----[^-]+-----/g, "").replace(/\s+/g, "");
+  return Uint8Array.from(atob(base64), (char) => char.charCodeAt(0));
+}
+
+const keyCache = new Map<string, Promise<CryptoKey>>();
+
+function signingKey(pem: string): Promise<CryptoKey> {
+  const cached = keyCache.get(pem);
+  if (cached) return cached;
+  const normalized = pem.replace(/\\n/g, "\n").trim();
+  const bytes = pemBody(normalized);
+  const pkcs8 = normalized.includes("BEGIN RSA PRIVATE KEY") ? pkcs1ToPkcs8(bytes) : bytes;
+  const key = crypto.subtle.importKey("pkcs8", pkcs8 as BufferSource, { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" }, false, ["sign"]);
+  keyCache.set(pem, key);
+  return key;
+}
+
+/** The app's own JWT: valid for ten minutes, backdated a minute for clock drift (GitHub's guidance). */
+export async function githubAppJwt(env: GithubAppEnv, now = Date.now()): Promise<string> {
+  if (!githubAppConfigured(env)) throw new GithubAppError(503, "The GitHub App isn't configured");
+  const seconds = Math.floor(now / 1000);
+  const header = base64UrlJson({ alg: "RS256", typ: "JWT" });
+  const payload = base64UrlJson({ iat: seconds - 60, exp: seconds + 540, iss: env.GITHUB_APP_ID!.trim() });
+  const signature = await crypto.subtle.sign("RSASSA-PKCS1-v1_5", await signingKey(env.GITHUB_APP_PRIVATE_KEY!), new TextEncoder().encode(`${header}.${payload}`));
+  return `${header}.${payload}.${base64UrlBytes(new Uint8Array(signature))}`;
+}
+
+const tokenCache = new Map<string, { token: string; expiresAt: number }>();
+
+export async function installationToken(env: GithubAppEnv, installationId: number): Promise<string> {
+  const cacheKey = `${env.GITHUB_APP_ID}:${installationId}`;
+  const cached = tokenCache.get(cacheKey);
+  if (cached && cached.expiresAt > Date.now() + 60_000) return cached.token;
+  const response = await (env.GITHUB_FETCH ?? fetch)(`${API}/app/installations/${installationId}/access_tokens`, {
+    method: "POST",
+    headers: githubHeaders(await githubAppJwt(env)),
+  });
+  if (!response.ok) throw new GithubAppError(response.status, `GitHub refused an installation token (${response.status})`);
+  const body = await response.json() as { token: string; expires_at: string };
+  tokenCache.set(cacheKey, { token: body.token, expiresAt: Date.parse(body.expires_at) });
+  return body.token;
+}
+
+function githubHeaders(token: string): Record<string, string> {
+  return {
+    accept: "application/vnd.github+json",
+    authorization: `Bearer ${token}`,
+    "x-github-api-version": "2022-11-28",
+    "user-agent": "bugmole",
+  };
+}
+
+/** A REST call as the installation. Throws GithubAppError with GitHub's status. */
+export async function githubRequest<T>(env: GithubAppEnv, installationId: number, method: string, path: string, body?: unknown): Promise<T> {
+  const token = await installationToken(env, installationId);
+  const response = await (env.GITHUB_FETCH ?? fetch)(`${API}${path}`, {
+    method,
+    headers: { ...githubHeaders(token), ...(body === undefined ? {} : { "content-type": "application/json" }) },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  if (!response.ok) {
+    const text = await response.text().catch(() => "");
+    throw new GithubAppError(response.status, `GitHub ${method} ${path} failed (${response.status}) ${text.slice(0, 200)}`);
+  }
+  return (response.status === 204 ? undefined : await response.json()) as T;
+}
+
+export type CheckRunUpdate = {
+  status?: "queued" | "in_progress" | "completed";
+  conclusion?: "success" | "failure" | "neutral" | "cancelled" | "timed_out" | "action_required";
+  details_url?: string;
+  external_id?: string;
+  started_at?: string;
+  completed_at?: string;
+  output?: { title: string; summary: string; text?: string };
+};
+
+export function createCheckRun(env: GithubAppEnv, installationId: number, repo: string, check: CheckRunUpdate & { name: string; head_sha: string }) {
+  return githubRequest<{ id: number; html_url: string }>(env, installationId, "POST", `/repos/${repo}/check-runs`, check);
+}
+
+export function updateCheckRun(env: GithubAppEnv, installationId: number, repo: string, checkRunId: number, update: CheckRunUpdate) {
+  return githubRequest<{ id: number }>(env, installationId, "PATCH", `/repos/${repo}/check-runs/${checkRunId}`, update);
+}

package/src/integrations/gitlab.ts

@@ -0,0 +1,81 @@
+// A GitLab client for the one thing Bugmole needs as itself: posting a
+// commit status. Unlike the GitHub App, there is no Bugmole-operated app to
+// register — each project supplies its own access token (Project or Group
+// access token, scope `api`), stored encrypted, so there is nothing for an
+// operator to configure globally.
+
+export type GitlabFetchEnv = {
+  /** Test seam. */
+  GITLAB_FETCH?: typeof fetch;
+};
+
+export class GitlabApiError extends Error {
+  constructor(readonly status: number, message: string) {
+    super(message);
+  }
+}
+
+const DEFAULT_HOST = "gitlab.com";
+const HOST = /^[A-Za-z0-9.-]{1,255}$/;
+
+export function validGitlabHost(host: string): boolean {
+  return HOST.test(host) && !host.includes("..");
+}
+
+export function normalizeGitlabHost(host: string | null | undefined): string {
+  const trimmed = (host ?? "").trim().toLowerCase();
+  return trimmed || DEFAULT_HOST;
+}
+
+function api(host: string): string {
+  return `https://${host}/api/v4`;
+}
+
+/** A REST call to the given GitLab instance, authenticated with a project/group access token. */
+export async function gitlabRequest<T>(
+  env: GitlabFetchEnv,
+  host: string,
+  token: string,
+  method: string,
+  path: string,
+  body?: unknown,
+): Promise<T> {
+  const response = await (env.GITLAB_FETCH ?? fetch)(`${api(host)}${path}`, {
+    method,
+    headers: {
+      "PRIVATE-TOKEN": token,
+      ...(body === undefined ? {} : { "content-type": "application/json" }),
+    },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  if (!response.ok) {
+    const text = await response.text().catch(() => "");
+    throw new GitlabApiError(response.status, `GitLab ${method} ${path} failed (${response.status}) ${text.slice(0, 200)}`);
+  }
+  return (response.status === 204 ? undefined : await response.json()) as T;
+}
+
+export type GitlabProject = { id: number; path_with_namespace: string; web_url: string };
+
+/** Confirms the token can see this project, and returns GitLab's own id and path for it. */
+export function fetchGitlabProject(env: GitlabFetchEnv, host: string, token: string, projectPath: string): Promise<GitlabProject> {
+  return gitlabRequest<GitlabProject>(env, host, token, "GET", `/projects/${encodeURIComponent(projectPath)}`);
+}
+
+export type CommitStatusState = "pending" | "running" | "success" | "failed" | "canceled";
+
+/**
+ * Posting a new status with the same `name` for the same commit replaces the
+ * previous one in GitLab's UI — there's no separate "check run id" to track
+ * and update, unlike GitHub Checks.
+ */
+export function postCommitStatus(
+  env: GitlabFetchEnv,
+  host: string,
+  token: string,
+  gitlabProjectId: number,
+  sha: string,
+  status: { state: CommitStatusState; name: string; target_url?: string; description?: string },
+): Promise<unknown> {
+  return gitlabRequest(env, host, token, "POST", `/projects/${gitlabProjectId}/statuses/${sha}`, status);
+}

package/src/integrations/temp-email.test.ts

@@ -0,0 +1,123 @@
+import { strict as assert } from "node:assert";
+import test from "node:test";
+import { createTempEmailInbox, deleteTempEmailInbox, extractFirstLink, waitForTempEmailMessage } from "./temp-email.js";
+
+function mockFetchSequence(handlers: Array<(url: string, init?: RequestInit) => unknown>) {
+  let call = 0;
+  const original = globalThis.fetch;
+  globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const handler = handlers[Math.min(call, handlers.length - 1)];
+    call += 1;
+    const body = handler(String(input), init);
+    return new Response(JSON.stringify(body), { status: 200, headers: { "content-type": "application/json" } });
+  }) as typeof fetch;
+  return () => {
+    globalThis.fetch = original;
+  };
+}
+
+test("createTempEmailInbox picks a served domain, creates an account, and authenticates", async () => {
+  const restore = mockFetchSequence([
+    () => ({ "hydra:member": [{ domain: "example-temp.test" }] }),
+    (_url, init) => {
+      const body = JSON.parse(String(init?.body));
+      assert.ok(body.address.endsWith("@example-temp.test"));
+      assert.ok(body.password.length > 0);
+      return { id: "acct-1", address: body.address };
+    },
+    () => ({ token: "jwt-token" }),
+  ]);
+  try {
+    const inbox = await createTempEmailInbox();
+    assert.equal(inbox.accountId, "acct-1");
+    assert.equal(inbox.token, "jwt-token");
+    assert.ok(inbox.address.endsWith("@example-temp.test"));
+  } finally {
+    restore();
+  }
+});
+
+test("createTempEmailInbox fails clearly when mail.tm has no active domain", async () => {
+  const restore = mockFetchSequence([() => ({ "hydra:member": [] })]);
+  try {
+    await assert.rejects(createTempEmailInbox(), /no active domain/);
+  } finally {
+    restore();
+  }
+});
+
+const inbox = { address: "qa@example-temp.test", password: "x", accountId: "acct-1", token: "jwt-token" };
+
+test("waitForTempEmailMessage polls until a message matching from/subject arrives", async () => {
+  let listCalls = 0;
+  const restore = mockFetchSequence([
+    () => {
+      listCalls += 1;
+      return { "hydra:member": [] };
+    },
+    () => {
+      listCalls += 1;
+      return {
+        "hydra:member": [
+          { id: "msg-wrong", from: { address: "someone-else@cinely.net" }, subject: "Unrelated", createdAt: "now" },
+          { id: "msg-right", from: { address: "no-reply@cinely.net" }, subject: "Confirm your email address", createdAt: "now" },
+        ],
+      };
+    },
+    () => ({ id: "msg-right", from: { address: "no-reply@cinely.net" }, subject: "Confirm your email address", text: "", html: ["<a href='https://x.test/confirm'>Confirm</a>"], createdAt: "now" }),
+  ]);
+  try {
+    const message = await waitForTempEmailMessage(inbox, { from: "cinely.net", subject: "confirm", pollIntervalMs: 1 });
+    assert.equal(message.id, "msg-right");
+    assert.ok(message.html.includes("confirm"));
+    assert.ok(listCalls >= 2);
+  } finally {
+    restore();
+  }
+});
+
+test("waitForTempEmailMessage times out with a clear message naming the criteria", async () => {
+  const restore = mockFetchSequence([() => ({ "hydra:member": [] })]);
+  try {
+    await assert.rejects(
+      waitForTempEmailMessage(inbox, { from: "cinely.net", subject: "confirm", timeoutMs: 5, pollIntervalMs: 1 }),
+      /from containing "cinely\.net" and subject containing "confirm"/,
+    );
+  } finally {
+    restore();
+  }
+});
+
+test("extractFirstLink returns the first link by default", () => {
+  const href = extractFirstLink({ html: `<a href="https://a.test">First</a><a href="https://b.test">Second</a>`, text: "" });
+  assert.equal(href, "https://a.test");
+});
+
+test("extractFirstLink prefers a link whose text or URL matches", () => {
+  const href = extractFirstLink({
+    html: `<a href="https://a.test/unsubscribe">Unsubscribe</a><a href="https://a.test/confirm-email">Confirm email address</a>`,
+    text: "",
+  }, "confirm");
+  assert.equal(href, "https://a.test/confirm-email");
+});
+
+test("extractFirstLink falls back to a bare URL in the text body when there's no html link", () => {
+  const href = extractFirstLink({ html: "", text: "Confirm here: https://a.test/confirm?token=abc" });
+  assert.equal(href, "https://a.test/confirm?token=abc");
+});
+
+test("extractFirstLink fails clearly when nothing matches", () => {
+  assert.throws(() => extractFirstLink({ html: `<a href="https://a.test">Unsubscribe</a>`, text: "" }, "confirm"), /No link matching "confirm"/);
+});
+
+test("deleteTempEmailInbox is best-effort and never throws", async () => {
+  const original = globalThis.fetch;
+  globalThis.fetch = (async () => {
+    throw new Error("network down");
+  }) as typeof fetch;
+  try {
+    await deleteTempEmailInbox(inbox);
+  } finally {
+    globalThis.fetch = original;
+  }
+});