@vostride/agent-qa-plugin-browserstack 0.0.1 → 0.3.1

package/dist/plugin-fBvi25yB.js

@@ -0,0 +1,954 @@
+import { PluginError, credential, definePlugin, z } from "@vostride/agent-qa-plugin-kit";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { execFile, spawnSync } from "node:child_process";
+import { openAsBlob, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
+import { format } from "node:util";
+import { Local } from "browserstack-local";
+// src/browserstack-api.ts
+function browserStackFailureKind(status) {
+	if (status === void 0) return "unreachable";
+	if (status === 401) return "auth";
+	if (status === 429) return "capacity";
+	return "refused";
+}
+const MAX_REASON_LENGTH = 200;
+function oneLine(text) {
+	const line = text.replace(/\s+/g, " ").trim();
+	return line.length > MAX_REASON_LENGTH ? `${line.slice(0, MAX_REASON_LENGTH)}…` : line;
+}
+function vendorMessage(body) {
+	if (typeof body !== "object" || body === null) return void 0;
+	for (const field of ["message", "error"]) if (field in body) {
+		const value = body[field];
+		if (typeof value === "string" && value.trim() !== "") return oneLine(value);
+	}
+}
+function parseJson(text) {
+	try {
+		return JSON.parse(text);
+	} catch {
+		return;
+	}
+}
+async function statusFailure(response, request) {
+	const message = vendorMessage(parseJson(await response.text().catch(() => "")));
+	const reason = message === void 0 ? "" : `: ${message}`;
+	const retryAfter = response.headers.get("retry-after");
+	const wait = response.status === 429 && retryAfter !== null ? `, retry after ${retryAfter} s` : "";
+	return new PluginError(`BrowserStack answered ${response.status} to ${request}${reason}${wait}`, { kind: browserStackFailureKind(response.status) });
+}
+function causeText(error) {
+	if (!(error instanceof Error)) return oneLine(String(error));
+	const cause = error.cause;
+	if (cause instanceof Error) return oneLine("code" in cause && typeof cause.code === "string" ? cause.code : cause.message);
+	return oneLine(error.message);
+}
+function withSlash(url) {
+	return url.endsWith("/") ? url : `${url}/`;
+}
+function createBrowserStackApi(input) {
+	const appBase = withSlash(input.appApiUrl);
+	const automateBase = withSlash(input.apiUrl);
+	const authorization = `Basic ${Buffer.from(`${input.username}:${input.accessKey}`).toString("base64")}`;
+	const send = async (method, path, init) => {
+		const url = new URL(path, init.base ?? appBase);
+		try {
+			return await fetch(url, {
+				method,
+				headers: {
+					accept: "application/json",
+					...init.headers,
+					authorization
+				},
+				...init.body === void 0 ? {} : { body: init.body },
+				...init.signal === void 0 ? {} : { signal: init.signal }
+			});
+		} catch (error) {
+			if (init.signal?.aborted === true) throw error;
+			throw new PluginError(`BrowserStack could not be reached at ${url.origin}: ${causeText(error)}`, { kind: "unreachable" });
+		}
+	};
+	const readJson = async (response, request) => {
+		if (!response.ok) throw await statusFailure(response, request);
+		return parseJson(await response.text());
+	};
+	const sessionPath = (id) => `app-automate/sessions/${encodeURIComponent(id)}.json`;
+	const webSessionPath = (id) => `automate/sessions/${encodeURIComponent(id)}.json`;
+	const mark = async (base, path, request, body, signal) => {
+		const response = await send("PUT", path, {
+			base,
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify(body),
+			signal
+		});
+		if (!response.ok) throw await statusFailure(response, request);
+		await response.body?.cancel();
+	};
+	const plan = async (base, path, signal) => {
+		const response = await send("GET", path, {
+			base,
+			signal
+		});
+		if (response.status === 404) {
+			await response.body?.cancel();
+			return;
+		}
+		return readJson(response, `GET /${path}`);
+	};
+	return {
+		async appSession(id, signal) {
+			const response = await send("GET", sessionPath(id), { signal });
+			return readJson(response, "GET /app-automate/sessions/{id}.json");
+		},
+		markAppSession(id, body, signal) {
+			return mark(appBase, sessionPath(id), "PUT /app-automate/sessions/{id}.json", body, signal);
+		},
+		async runningBuilds(signal) {
+			const response = await send("GET", "automate/builds.json?limit=100&status=running", {
+				base: automateBase,
+				signal
+			});
+			return readJson(response, "GET /automate/builds.json");
+		},
+		async runningBuildSessions(buildId, signal) {
+			const path = `automate/builds/${encodeURIComponent(buildId)}/sessions.json?limit=100&status=running`;
+			const response = await send("GET", path, {
+				base: automateBase,
+				signal
+			});
+			return readJson(response, "GET /automate/builds/{id}/sessions.json");
+		},
+		async webSession(id, signal) {
+			const response = await send("GET", webSessionPath(id), {
+				base: automateBase,
+				signal
+			});
+			return readJson(response, "GET /automate/sessions/{id}.json");
+		},
+		markWebSession(id, body, signal) {
+			return mark(automateBase, webSessionPath(id), "PUT /automate/sessions/{id}.json", body, signal);
+		},
+		automatePlan(signal) {
+			return plan(automateBase, "automate/plan.json", signal);
+		},
+		appAutomatePlan(signal) {
+			return plan(appBase, "app-automate/plan.json", signal);
+		},
+		async recentApps(customId, signal) {
+			const path = `app-automate/recent_apps/${encodeURIComponent(customId)}`;
+			const response = await send("GET", path, { signal });
+			if (response.status === 404) {
+				await response.body?.cancel();
+				return;
+			}
+			return readJson(response, "GET /app-automate/recent_apps/{custom_id}");
+		},
+		async uploadApp(form, signal) {
+			const response = await send("POST", "app-automate/upload", {
+				body: form,
+				signal
+			});
+			return readJson(response, "POST /app-automate/upload");
+		}
+	};
+}
+function browserStackApiFor(options) {
+	return createBrowserStackApi({
+		apiUrl: options.apiUrl,
+		appApiUrl: options.appApiUrl,
+		username: options.username,
+		accessKey: options.accessKey
+	});
+}
+const MAX_MARK_REASON_LENGTH = 255;
+const DeviceHandleSchema = z.object({
+	kind: z.literal("device"),
+	id: z.string().min(1),
+	platform: z.enum(["android", "ios"]),
+	appiumVersion: z.string().min(1)
+});
+function ownAppiumVersion(capabilities) {
+	const own = capabilities["bstack:options"];
+	if (typeof own !== "object" || own === null || !("appiumVersion" in own)) return void 0;
+	const { appiumVersion } = own;
+	return typeof appiumVersion === "string" && appiumVersion !== "" ? appiumVersion : void 0;
+}
+function deviceAnswer(request) {
+	const { options, settings } = request;
+	const appiumVersion = ownAppiumVersion(request.capabilities) ?? settings.appiumVersion ?? "3.5.2";
+	const build = settings.build ?? request.runId;
+	const name = request.testName;
+	return {
+		handle: {
+			kind: "device",
+			id: randomUUID(),
+			platform: request.platform,
+			appiumVersion,
+			...build === void 0 ? {} : { build },
+			...name === void 0 ? {} : { name }
+		},
+		protocol: "appium",
+		url: options.hubUrl,
+		capabilities: { "bstack:options": {
+			userName: options.username,
+			accessKey: options.accessKey,
+			appiumVersion,
+			projectName: settings.project,
+			...build === void 0 ? {} : { buildName: build },
+			...name === void 0 ? {} : { sessionName: name },
+			...request.localIdentifier === void 0 ? {} : {
+				local: true,
+				localIdentifier: request.localIdentifier
+			},
+			...settings.extra
+		} },
+		mask: []
+	};
+}
+function sessionDetails(body) {
+	if (typeof body !== "object" || body === null) return void 0;
+	const wrapped = body.automation_session;
+	if (typeof wrapped === "object" && wrapped !== null) return wrapped;
+	return body;
+}
+function warn(line) {
+	process.stderr.write(`${line.replace(/\s+/g, " ").trim()}\n`);
+}
+function failureText(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+async function deviceStarted(input) {
+	const { appiumVersion } = input.handle;
+	if (input.sessionId === void 0) return { appiumVersion };
+	try {
+		const link = sessionDetails(await browserStackApiFor(input.options).appSession(input.sessionId, input.signal))?.browser_url;
+		if (typeof link === "string" && link !== "") return {
+			link,
+			appiumVersion
+		};
+		warn(`BrowserStack: App Automate session ${input.sessionId} has no dashboard link.`);
+	} catch (error) {
+		warn(`BrowserStack: could not read App Automate session ${input.sessionId}: ${failureText(error)}`);
+	}
+	return { appiumVersion };
+}
+function sessionMark(outcome, reason) {
+	if (outcome === "cancelled") return void 0;
+	if (outcome === "passed") return { status: "passed" };
+	return {
+		status: "failed",
+		...reason === void 0 ? {} : { reason: reason.slice(0, MAX_MARK_REASON_LENGTH) }
+	};
+}
+async function markAppSession(input) {
+	const mark = sessionMark(input.outcome, input.reason);
+	if (mark === void 0) return;
+	try {
+		await browserStackApiFor(input.options).markAppSession(input.sessionId, mark, input.signal);
+	} catch (error) {
+		warn(`BrowserStack: could not mark App Automate session ${input.sessionId} ${mark.status}: ${failureText(error)}`);
+	}
+}
+// src/playwright-versions.ts
+const BROWSERSTACK_PLAYWRIGHT_VERSIONS = [
+	"1.59",
+	"1.60",
+	"1.61",
+	"1.62",
+	"1.63"
+];
+function playwrightMajorMinor(version) {
+	const match = /^(\d+)\.(\d+)(?:\.|$|-)/.exec(version);
+	return match === null ? void 0 : `${match[1]}.${match[2]}`;
+}
+function listedPlaywright(version) {
+	const majorMinor = playwrightMajorMinor(version);
+	return BROWSERSTACK_PLAYWRIGHT_VERSIONS.some((listed) => listed === majorMinor);
+}
+// src/check.ts
+const PlanSchema = z.object({
+	parallel_sessions_running: z.number(),
+	parallel_sessions_max_allowed: z.number(),
+	queued_sessions: z.number()
+});
+async function readPlan(product, read) {
+	let answer;
+	try {
+		answer = await read();
+	} catch (error) {
+		if (error instanceof PluginError && error.kind === "auth") return { kind: "refused" };
+		return {
+			kind: "warn",
+			line: `${product} plan not readable: ${failureText(error)}`
+		};
+	}
+	if (answer === void 0) return {
+		kind: "warn",
+		line: `${product} is not on this account`
+	};
+	const plan = PlanSchema.safeParse(answer);
+	if (!plan.success) return {
+		kind: "warn",
+		line: `${product} plan not readable: BrowserStack answered another shape`
+	};
+	const { parallel_sessions_running: running, parallel_sessions_max_allowed: allowed } = plan.data;
+	const queued = plan.data.queued_sessions;
+	return {
+		kind: "plan",
+		line: `${product}: ${String(running)} of ${String(allowed)} parallel sessions running, ${String(queued)} queued`
+	};
+}
+function playwrightLine(version) {
+	if (listedPlaywright(version)) return void 0;
+	const first = BROWSERSTACK_PLAYWRIGHT_VERSIONS[0];
+	const last = BROWSERSTACK_PLAYWRIGHT_VERSIONS[BROWSERSTACK_PLAYWRIGHT_VERSIONS.length - 1];
+	const ours = playwrightMajorMinor(version);
+	if (ours === void 0) return `BrowserStack lists Playwright ${first} to ${last}, and agent-qa's Playwright version is unknown; web tests on BrowserStack are refused until it is known.`;
+	return `BrowserStack lists Playwright ${first} to ${last}, not ${ours}; web tests on BrowserStack are refused until it does.`;
+}
+async function checkAccount(input) {
+	const api = browserStackApiFor(input.options);
+	const reads = await Promise.all([readPlan("Automate", () => api.automatePlan(input.signal)), readPlan("App Automate", () => api.appAutomatePlan(input.signal))]);
+	const version = playwrightLine(input.playwrightVersion);
+	const extra = version === void 0 ? [] : [version];
+	if (reads.some((read) => read.kind === "refused")) return {
+		state: "warn",
+		lines: ["the username or access key was refused", ...extra]
+	};
+	const lines = reads.flatMap((read) => read.kind === "refused" ? [] : [read.line]);
+	return {
+		state: extra.length > 0 || reads.some((read) => read.kind === "warn") ? "warn" : "ok",
+		lines: [...lines, ...extra]
+	};
+}
+// src/local.ts
+const STOP_BOUND_MS = 3e3;
+const CHECK_BOUND_MS = 5e3;
+const BAD_CPU_TYPE = -86;
+function cannotRunReason(binary, error, platform) {
+	if (platform === "darwin" && error.errno === BAD_CPU_TYPE) return `this machine cannot run ${binary} (EBADARCH: bad CPU type in executable). Install Rosetta (softwareupdate --install-rosetta --agree-to-license) or set localBinary to a binary built for this Mac`;
+	const code = error.code ?? error.message;
+	if (code === "ENOENT") return `${binary} does not exist (ENOENT). Set localBinary to the path of a BrowserStackLocal binary`;
+	if (code === "EACCES") return `this machine cannot run ${binary} (EACCES). Check that it is an executable file, or set localBinary to one that is`;
+	return `this machine cannot run ${binary} (${code}). Set localBinary to a binary this machine can run`;
+}
+function wrapperBinary(wrapper, accessKey) {
+	wrapper.key = accessKey;
+	return new Promise((resolve, reject) => {
+		wrapper.getBinaryPath((path) => {
+			if (path) {
+				resolve(path);
+				return;
+			}
+			reject(/* @__PURE__ */ new Error("browserstack-local found no BrowserStack Local binary and could not download one"));
+		});
+	});
+}
+function cannotRun(binary) {
+	const { error } = spawnSync(binary, ["--version"], {
+		stdio: "ignore",
+		timeout: CHECK_BOUND_MS
+	});
+	if (error === void 0) return void 0;
+	return error.code === "ETIMEDOUT" ? void 0 : error;
+}
+function stopDaemon(binary, request) {
+	const args = [
+		"--daemon",
+		"stop",
+		"--local-identifier",
+		request.identifier
+	];
+	return new Promise((done) => {
+		execFile(binary, [
+			...args,
+			"--key",
+			request.accessKey
+		], { timeout: STOP_BOUND_MS }, () => done());
+	});
+}
+const CONSOLE_METHODS = [
+	"log",
+	"info",
+	"debug",
+	"warn",
+	"error"
+];
+function maskConsole(secret) {
+	if (secret === "") return () => {};
+	const originals = CONSOLE_METHODS.map((method) => console[method]);
+	CONSOLE_METHODS.forEach((method, index) => {
+		const original = originals[index];
+		console[method] = (...args) => original(format(...args).split(secret).join("***"));
+	});
+	return () => {
+		CONSOLE_METHODS.forEach((method, index) => {
+			console[method] = originals[index];
+		});
+	};
+}
+function localLogFile() {
+	const name = `agent-qa-browserstack-local-${process.pid}-${randomBytes(4).toString("hex")}.log`;
+	return join(tmpdir(), name);
+}
+const browserStackLocalFactory = { start(request) {
+	const local = new Local();
+	const wrapper = local;
+	wrapper.retriesLeft = 0;
+	const unmask = maskConsole(request.accessKey);
+	let aborted = false;
+	return {
+		running: (async () => {
+			const binary = request.binary ?? await wrapperBinary(wrapper, request.accessKey);
+			const failure = cannotRun(binary);
+			if (failure !== void 0) throw new Error(cannotRunReason(binary, failure, process.platform));
+			if (aborted) throw new Error("it was stopped while it was starting");
+			const logFile = localLogFile();
+			writeFileSync(logFile, "", { mode: 384 });
+			return new Promise((resolve, reject) => {
+				local.start({
+					key: request.accessKey,
+					localIdentifier: request.identifier,
+					logFile,
+					binarypath: binary
+				}, (error) => {
+					if (error) {
+						const [first] = error.message.split("\n");
+						reject(/* @__PURE__ */ new Error(`${first} (its log is ${logFile})`));
+						return;
+					}
+					resolve({ stop: () => new Promise((done) => local.stop(() => done())) });
+				});
+			});
+		})().finally(unmask),
+		async abort() {
+			aborted = true;
+			wrapper.tunnel?.kill();
+			if (wrapper.binaryPath !== void 0) await stopDaemon(wrapper.binaryPath, request);
+		}
+	};
+} };
+function freshLocalIdentifier() {
+	return `agent-qa-${randomBytes(8).toString("hex")}`;
+}
+function startFailure(error, accessKey, binarySet) {
+	if (error instanceof PluginError) return error;
+	const text = error instanceof Error ? error.message : String(error);
+	const shown = accessKey === "" ? text : text.split(accessKey).join("***");
+	return new PluginError(`BrowserStack Local did not start: ${shown}`, {
+		kind: "unreachable",
+		path: binarySet ? "options.localBinary" : "options.local"
+	});
+}
+function bounded(work, boundMs) {
+	let timer;
+	const bound = new Promise((resolve) => {
+		timer = setTimeout(resolve, boundMs);
+	});
+	return Promise.race([work.catch(() => {}), bound]).finally(() => clearTimeout(timer));
+}
+function createTunnelManager(input) {
+	const identifier = input.local ? input.localIdentifier ?? freshLocalIdentifier() : input.localIdentifier;
+	const binarySet = input.localBinary !== void 0;
+	let starting;
+	let stopped = false;
+	let connected = false;
+	const start = () => {
+		if (starting !== void 0) return starting.running;
+		let begun;
+		try {
+			begun = input.factory.start({
+				accessKey: input.accessKey,
+				identifier,
+				binary: input.localBinary
+			});
+		} catch (error) {
+			return Promise.reject(startFailure(error, input.accessKey, binarySet));
+		}
+		const attempt = {
+			running: begun.running.catch((error) => {
+				throw startFailure(error, input.accessKey, binarySet);
+			}),
+			abort: () => begun.abort()
+		};
+		starting = attempt;
+		attempt.running.then(() => {
+			connected = true;
+		}, () => {
+			if (starting === attempt) starting = void 0;
+		});
+		return attempt.running;
+	};
+	return {
+		identifier,
+		async ensure(signal, progress) {
+			if (!input.local) return;
+			if (stopped) throw new PluginError("BrowserStack Local was already stopped for this run.", {
+				kind: "unreachable",
+				path: "options.local"
+			});
+			signal.throwIfAborted();
+			const shared = start();
+			if (!connected) progress({ message: "starting BrowserStack Local" });
+			await new Promise((resolve, reject) => {
+				const onAbort = () => reject(/* @__PURE__ */ new Error("the acquire was cancelled while BrowserStack Local was starting"));
+				signal.addEventListener("abort", onAbort, { once: true });
+				shared.then(() => {
+					signal.removeEventListener("abort", onAbort);
+					resolve();
+				}, (error) => {
+					signal.removeEventListener("abort", onAbort);
+					reject(error);
+				});
+			});
+		},
+		async stop() {
+			if (stopped) return;
+			stopped = true;
+			const pending = starting;
+			if (pending === void 0) return;
+			const stopRunning = pending.running.then((tunnel) => tunnel.stop());
+			if (connected) {
+				await bounded(stopRunning, STOP_BOUND_MS);
+				return;
+			}
+			await bounded(Promise.allSettled([pending.abort(), stopRunning]).then(() => {}), STOP_BOUND_MS);
+		}
+	};
+}
+// src/options.ts
+const BROWSERSTACK_BROWSERS = [
+	"chrome",
+	"edge",
+	"playwright-chromium",
+	"playwright-firefox",
+	"playwright-webkit"
+];
+const options = z.strictObject({
+	username: credential("The BrowserStack username"),
+	accessKey: credential("The BrowserStack access key"),
+	apiUrl: z.url().default("https://api.browserstack.com").describe("BrowserStack's Automate API, https:// unless it points at this machine"),
+	appApiUrl: z.url().default("https://api-cloud.browserstack.com").describe("BrowserStack's App Automate API, https:// unless it points at this machine"),
+	hubUrl: z.url().default("https://hub.browserstack.com/wd/hub").describe("BrowserStack's Appium hub, https:// unless it points at this machine"),
+	playwrightUrl: z.url().default("wss://cdp.browserstack.com/playwright").describe("BrowserStack's Playwright endpoint, wss:// unless it points at this machine"),
+	local: z.boolean().default(false).describe("Start a BrowserStack Local tunnel for this run, named by localIdentifier or a fresh one"),
+	localIdentifier: z.string().min(1).optional().describe("The identifier of a BrowserStack Local tunnel; without local, a tunnel already running"),
+	localBinary: z.string().min(1).optional().describe("The BrowserStackLocal binary to run instead of the one the wrapper downloads")
+});
+const settings = z.strictObject({
+	os: z.string().min(1).default("OS X").describe("The operating system, for example Windows"),
+	osVersion: z.string().min(1).default("Sequoia").describe("The operating system version, for example 11 or Sequoia"),
+	browser: z.enum(BROWSERSTACK_BROWSERS).optional().describe("BrowserStack's browser; by default it follows the test's engine"),
+	browserVersion: z.string().min(1).optional().describe("The Chrome or Edge version, for example latest or latest-1"),
+	project: z.string().min(1).default("agent-qa").describe("The BrowserStack project the sessions are filed under"),
+	build: z.string().min(1).optional().describe("The BrowserStack build name; by default the run id"),
+	appiumVersion: z.string().min(1).optional().describe("The Appium version device sessions ask for; by default the plugin's own"),
+	extra: z.record(z.string(), z.unknown()).optional().describe("Capabilities merged last, overriding the ones above")
+});
+const ENDPOINTS = [
+	{
+		path: "apiUrl",
+		secure: "https:",
+		plain: "http:"
+	},
+	{
+		path: "appApiUrl",
+		secure: "https:",
+		plain: "http:"
+	},
+	{
+		path: "hubUrl",
+		secure: "https:",
+		plain: "http:"
+	},
+	{
+		path: "playwrightUrl",
+		secure: "wss:",
+		plain: "ws:"
+	}
+];
+function isLoopback(hostname) {
+	return hostname === "localhost" || hostname === "[::1]" || /^127(?:\.\d{1,3}){3}$/.test(hostname);
+}
+function checkLocal(input) {
+	if (input.localBinary !== void 0 && !input.local) throw new PluginError("localBinary names the tunnel the plugin starts, so it needs local: true.", {
+		kind: "refused",
+		path: "localBinary"
+	});
+}
+function checkEndpoints(input) {
+	for (const endpoint of ENDPOINTS) {
+		const url = new URL(input[endpoint.path]);
+		if (!(url.username === "" && url.password === "" && (url.protocol === endpoint.secure || url.protocol === endpoint.plain && isLoopback(url.hostname)))) {
+			const scheme = endpoint.secure.slice(0, -1);
+			throw new PluginError(`${endpoint.path} must use ${scheme}:// with no user or password, unless it points at this machine.`, {
+				kind: "refused",
+				path: endpoint.path
+			});
+		}
+	}
+}
+// src/upload.ts
+const MEGABYTE = 1048576;
+function customIdFor(sha256) {
+	if (!/^[0-9a-f]{64}$/i.test(sha256)) throw new PluginError("sha256 must be the 64 hex digits of the app's SHA-256.", {
+		kind: "refused",
+		path: "sha256"
+	});
+	return `agent-qa-${sha256.slice(0, 32).toLowerCase()}`;
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function appUrlOf(value) {
+	if (!isRecord(value)) return void 0;
+	const appUrl = value.app_url;
+	return typeof appUrl === "string" && appUrl !== "" ? appUrl : void 0;
+}
+function uploadedAt(value) {
+	const at = typeof value.uploaded_at === "string" ? Date.parse(value.uploaded_at) : NaN;
+	return Number.isNaN(at) ? Number.NEGATIVE_INFINITY : at;
+}
+function newestAppUrl(recent) {
+	if (!Array.isArray(recent)) return void 0;
+	const newest = [...recent.filter(isRecord).filter((app) => appUrlOf(app) !== void 0)].sort((a, b) => uploadedAt(b) - uploadedAt(a))[0];
+	return appUrlOf(newest);
+}
+function megabytes(size) {
+	const amount = size / MEGABYTE;
+	return amount >= .1 ? amount.toFixed(1) : "<0.1";
+}
+async function readApp(path) {
+	try {
+		return await openAsBlob(path);
+	} catch (error) {
+		const code = error instanceof Error && "code" in error && typeof error.code === "string" ? error.code : "unreadable";
+		throw new PluginError(`The app at ${path} cannot be read (${code}).`, {
+			kind: "refused",
+			path: "path"
+		});
+	}
+}
+async function checkContent(app, request) {
+	const changed = () => new PluginError(`The app at ${request.path} no longer matches the SHA-256 agent-qa computed; run again.`, {
+		kind: "refused",
+		path: "path"
+	});
+	if (app.size !== request.size) throw changed();
+	const hash = createHash("sha256");
+	try {
+		for await (const chunk of app.stream()) {
+			request.signal.throwIfAborted();
+			hash.update(chunk);
+		}
+	} catch (error) {
+		if (request.signal.aborted) throw error;
+		throw changed();
+	}
+	if (hash.digest("hex") !== request.sha256.toLowerCase()) throw changed();
+}
+async function uploadApp(request) {
+	const customId = customIdFor(request.sha256);
+	const api = browserStackApiFor(request.options);
+	const reused = newestAppUrl(await api.recentApps(customId, request.signal));
+	if (reused !== void 0) return { ref: reused };
+	const app = await readApp(request.path);
+	await checkContent(app, request);
+	const form = new FormData();
+	form.append("custom_id", customId);
+	form.append("file", app, basename(request.path));
+	request.progress({ message: `uploading app (${megabytes(request.size)} MB)` });
+	const ref = appUrlOf(await api.uploadApp(form, request.signal));
+	if (ref === void 0) throw new PluginError("BrowserStack answered the app upload without an app_url.", { kind: "refused" });
+	request.progress({ message: "app uploaded" });
+	return { ref };
+}
+// src/web.ts
+const START_SLACK_MS = 5e3;
+const WebHandleSchema = z.object({
+	kind: z.literal("web"),
+	id: z.string().min(1),
+	build: z.string().optional(),
+	name: z.string().optional(),
+	startedAt: z.string()
+});
+const ENGINE_BROWSERS = {
+	chromium: "chrome",
+	firefox: "playwright-firefox",
+	webkit: "playwright-webkit"
+};
+const BROWSER_ENGINES = {
+	chrome: "chromium",
+	edge: "chromium",
+	"playwright-chromium": "chromium",
+	"playwright-firefox": "firefox",
+	"playwright-webkit": "webkit"
+};
+function checkPlaywrightVersion(version) {
+	if (listedPlaywright(version)) return;
+	const first = BROWSERSTACK_PLAYWRIGHT_VERSIONS[0];
+	const last = BROWSERSTACK_PLAYWRIGHT_VERSIONS[BROWSERSTACK_PLAYWRIGHT_VERSIONS.length - 1];
+	const ours = playwrightMajorMinor(version);
+	const which = ours === void 0 ? "and agent-qa's Playwright version is unknown" : `not ${ours}`;
+	throw new PluginError(`BrowserStack lists Playwright ${first} to ${last}, ${which}, so web tests cannot run there yet; run this test here or on another remote.`, { kind: "version" });
+}
+function webCapabilities(request) {
+	const { options, settings, engine } = request;
+	const browser = settings.browser ?? ENGINE_BROWSERS[engine];
+	if (BROWSER_ENGINES[browser] !== engine) throw new PluginError(`BrowserStack's ${browser} cannot run a ${engine} test.`, {
+		kind: "refused",
+		path: "settings.browser"
+	});
+	const build = settings.build ?? request.runId;
+	return {
+		"browserstack.username": options.username,
+		"browserstack.accessKey": options.accessKey,
+		browser,
+		os: settings.os,
+		os_version: settings.osVersion,
+		...settings.browserVersion === void 0 ? {} : { browser_version: settings.browserVersion },
+		"client.playwrightVersion": request.playwrightVersion,
+		project: settings.project,
+		...build === void 0 ? {} : { build },
+		...request.testName === void 0 ? {} : { name: request.testName },
+		...request.localIdentifier === void 0 ? {} : {
+			"browserstack.local": true,
+			"browserstack.localIdentifier": request.localIdentifier
+		},
+		...settings.extra
+	};
+}
+function playwrightAnswer(request) {
+	checkPlaywrightVersion(request.playwrightVersion);
+	const caps = webCapabilities(request);
+	const base = request.options.playwrightUrl;
+	const query = `caps=${encodeURIComponent(JSON.stringify(caps))}`;
+	const url = `${base}${base.includes("?") ? "&" : "?"}${query}`;
+	const { build, name } = caps;
+	return {
+		handle: {
+			kind: "web",
+			id: randomUUID(),
+			...typeof build === "string" ? { build } : {},
+			...typeof name === "string" ? { name } : {},
+			startedAt: (/* @__PURE__ */ new Date()).toISOString()
+		},
+		protocol: "playwright",
+		url,
+		mask: [url]
+	};
+}
+function itemsOf(body, wrapper) {
+	if (!Array.isArray(body)) return [];
+	return body.flatMap((item) => {
+		if (typeof item !== "object" || item === null) return [];
+		const wrapped = item[wrapper];
+		if (typeof wrapped === "object" && wrapped !== null) return [wrapped];
+		return [item];
+	});
+}
+function text(value) {
+	return typeof value === "string" && value !== "" ? value : void 0;
+}
+async function findWebSession(input) {
+	const { api, signal } = input;
+	const earliest = Date.parse(input.startedAt) - START_SLACK_MS;
+	const builds = itemsOf(await api.runningBuilds(signal), "automation_build").filter((build) => build.name === input.build);
+	const found = [];
+	for (const build of builds) {
+		const buildId = text(build.hashed_id);
+		if (buildId === void 0) continue;
+		const sessions = itemsOf(await api.runningBuildSessions(buildId, signal), "automation_session").filter((session) => session.name === input.name);
+		for (const session of sessions) {
+			const hashedId = text(session.hashed_id);
+			if (hashedId === void 0) continue;
+			const details = sessionDetails(await api.webSession(hashedId, signal));
+			const createdAt = Date.parse(text(details?.created_at) ?? "");
+			if (!Number.isFinite(createdAt) || createdAt < earliest) continue;
+			found.push({
+				hashedId,
+				link: text(details?.browser_url) ?? text(session.browser_url)
+			});
+		}
+	}
+	return found.length === 1 ? found[0] : void 0;
+}
+async function webStarted(input) {
+	const { build, name, startedAt } = input.handle;
+	const unmarked = `BrowserStack: no single web session matched build ${build ?? "(none)"} and name ${name ?? "(none)"}; it stays unmarked.`;
+	if (build === void 0 || name === void 0) {
+		warn(unmarked);
+		return { session: void 0 };
+	}
+	let session;
+	try {
+		session = await findWebSession({
+			api: browserStackApiFor(input.options),
+			build,
+			name,
+			startedAt,
+			signal: input.signal
+		});
+	} catch (error) {
+		warn(`BrowserStack: could not look up the web session for build ${build} and name ${name}: ${failureText(error)}; it stays unmarked.`);
+		return { session: void 0 };
+	}
+	if (session === void 0) {
+		warn(unmarked);
+		return { session: void 0 };
+	}
+	if (session.link === void 0) {
+		warn(`BrowserStack: Automate session ${session.hashedId} has no dashboard link.`);
+		return { session };
+	}
+	return {
+		session,
+		link: session.link
+	};
+}
+async function markWebSession(input) {
+	const mark = sessionMark(input.outcome, input.reason);
+	if (mark === void 0) return;
+	try {
+		const body = {
+			...mark,
+			reason: mark.reason ?? ""
+		};
+		await browserStackApiFor(input.options).markWebSession(input.sessionId, body, input.signal);
+	} catch (error) {
+		warn(`BrowserStack: could not mark Automate session ${input.sessionId} ${mark.status}: ${failureText(error)}`);
+	}
+}
+// src/plugin.ts
+const HandleSchema = z.union([WebHandleSchema, DeviceHandleSchema]);
+function createBrowserStackPlugin(input = {}) {
+	const tunnelFactory = input.tunnelFactory ?? browserStackLocalFactory;
+	let playwrightVersion = "unknown";
+	let tunnel;
+	const appSessions = /* @__PURE__ */ new Map();
+	const webSessions = /* @__PURE__ */ new Map();
+	return definePlugin({
+		options,
+		settings,
+		serves: ["playwright", "appium"],
+		runFacts: [
+			"testName",
+			"runId",
+			"failure"
+		],
+		skill: "./skill",
+		initialize({ options, host }) {
+			checkEndpoints(options);
+			checkLocal(options);
+			playwrightVersion = host.playwrightVersion;
+			tunnel = createTunnelManager({
+				factory: tunnelFactory,
+				accessKey: options.accessKey,
+				local: options.local,
+				localIdentifier: options.localIdentifier,
+				localBinary: options.localBinary
+			});
+		},
+		check({ options }, ctx) {
+			return checkAccount({
+				options,
+				playwrightVersion,
+				signal: ctx.signal
+			});
+		},
+		async acquire({ options, settings, session, run }, ctx) {
+			const localIdentifier = tunnel?.identifier;
+			const answer = session.platform === "web" ? playwrightAnswer({
+				options,
+				settings,
+				engine: session.engine,
+				playwrightVersion,
+				testName: run?.testName,
+				runId: ctx.runFacts?.runId,
+				localIdentifier
+			}) : deviceAnswer({
+				options,
+				settings,
+				platform: session.platform,
+				capabilities: session.capabilities,
+				testName: run?.testName,
+				runId: ctx.runFacts?.runId,
+				localIdentifier
+			});
+			await tunnel?.ensure(ctx.signal, ctx.progress);
+			return answer;
+		},
+		uploadApp({ options, path, sha256, size }, ctx) {
+			return uploadApp({
+				options,
+				path,
+				sha256,
+				size,
+				signal: ctx.signal,
+				progress: ctx.progress
+			});
+		},
+		async started({ options, handle, sessionId }, ctx) {
+			const web = WebHandleSchema.safeParse(handle);
+			if (web.success) {
+				const { session, link } = await webStarted({
+					options,
+					handle: web.data,
+					signal: ctx.signal
+				});
+				if (session !== void 0) webSessions.set(web.data.id, session.hashedId);
+				return link === void 0 ? {} : { link };
+			}
+			const device = DeviceHandleSchema.safeParse(handle);
+			if (!device.success) return {};
+			if (sessionId !== void 0) appSessions.set(device.data.id, sessionId);
+			return deviceStarted({
+				options,
+				handle: device.data,
+				sessionId,
+				signal: ctx.signal
+			});
+		},
+		async end({ options, handle, outcome, reason }, ctx) {
+			const web = WebHandleSchema.safeParse(handle);
+			if (web.success) {
+				const sessionId = webSessions.get(web.data.id);
+				if (sessionId === void 0) return;
+				await markWebSession({
+					options,
+					sessionId,
+					outcome,
+					reason,
+					signal: ctx.signal
+				});
+				return;
+			}
+			const device = DeviceHandleSchema.safeParse(handle);
+			if (!device.success) return;
+			const sessionId = appSessions.get(device.data.id);
+			if (sessionId === void 0) return;
+			await markAppSession({
+				options,
+				sessionId,
+				outcome,
+				reason,
+				signal: ctx.signal
+			});
+		},
+		release({ handle }) {
+			const parsed = HandleSchema.safeParse(handle);
+			if (!parsed.success) throw new PluginError("A BrowserStack handle names its kind of session.", { kind: "refused" });
+			if (parsed.data.kind === "device") appSessions.delete(parsed.data.id);
+			else webSessions.delete(parsed.data.id);
+		},
+		async shutdown() {
+			await tunnel?.stop();
+		}
+	});
+}
+var plugin_default = createBrowserStackPlugin();
+export { plugin_default as n, createBrowserStackPlugin as t };
+
+//# sourceMappingURL=plugin-fBvi25yB.js.map