@deeeed/metamask-harness 0.36.0 → 0.38.0

package/dist/adapters/extension/runtime.js

@@ -83,11 +83,15 @@ async function checkExtensionRuntimeHealth(projectRoot, cdpPort, options = {}) {
     (target2) => target2.type === "page" && String(target2.url ?? "").startsWith("chrome-extension://") && String(target2.url ?? "").includes("/sidepanel.html") && Boolean(target2.webSocketDebuggerUrl)
   );
   const extensionTargets = pageMode === "home-or-sidepanel" && homeTargets.length === 0 ? sidepanelTargets : homeTargets;
-  if (extensionTargets.length !== 1) {
-    const expected = pageMode === "home-or-sidepanel" ? "exactly one MetaMask extension home page target, or one sidepanel target when home is intentionally closed" : "exactly one MetaMask extension home page target";
+  if (extensionTargets.length === 0) {
+    const expected = pageMode === "home-or-sidepanel" ? "a MetaMask extension home page target, or one sidepanel target when home is intentionally closed" : "a MetaMask extension home page target";
     findings.push(`Expected ${expected}, found ${extensionTargets.length}.`);
   }
-  const target = extensionTargets[0];
+  const targetSelection = await selectResponsiveExtensionTarget(extensionTargets, cdpCallTimeoutMs);
+  const target = targetSelection.target;
+  if (extensionTargets.length > 1) {
+    warnings.push(`Found ${extensionTargets.length} MetaMask Extension page targets; health selected ${target?.url ?? "none"} after probing each candidate.`);
+  }
   if (!target?.webSocketDebuggerUrl) {
     return failReport(cdpPort, findings, {
       targetUrls: targets.map((entry) => entry.url).filter(Boolean)
@@ -147,6 +151,12 @@ async function checkExtensionRuntimeHealth(projectRoot, cdpPort, options = {}) {
       };
     }
     const runtime = await evaluateHealth(session, cdpCallTimeoutMs);
+    if (runtime.hasSubmitRequest !== true) {
+      const providerProbe = await probeUiEthereumProvider(session, cdpCallTimeoutMs);
+      runtime.evmRpcProbeOk = providerProbe.ok;
+      runtime.evmRpcProbeError = providerProbe.error;
+      runtime.evmRpcProbeSource = providerProbe.source;
+    }
     if (runtime.href && !String(runtime.href).startsWith("chrome-extension://")) {
       findings.push(`Extension page href is not an extension URL: ${runtime.href}`);
     }
@@ -199,6 +209,41 @@ async function checkExtensionRuntimeHealth(projectRoot, cdpPort, options = {}) {
     session?.close();
   }
 }
+async function selectResponsiveExtensionTarget(targets, timeoutMs) {
+  if (targets.length <= 1) return { target: targets[0] };
+  const probeTimeoutMs = Math.min(1e3, timeoutMs);
+  const ranked = [];
+  for (const [index, target] of targets.entries()) {
+    let session;
+    try {
+      session = await CdpSession.connect(target.webSocketDebuggerUrl, { timeoutMs: probeTimeoutMs });
+      await boundedCdpCall(session, "Runtime.enable", {}, probeTimeoutMs);
+      await boundedCdpCall(session, "Page.enable", {}, probeTimeoutMs);
+      const compositor = await probeCdpCompositorInteractivity(session, probeTimeoutMs);
+      const result = await boundedCdpCall(session, "Runtime.evaluate", {
+        expression: `(() => ({
+          readyState: String(document.readyState || ''),
+          href: String(location.href || ''),
+          text: String(document.body?.innerText || '').slice(0, 5000),
+        }))()`,
+        returnByValue: true
+      }, probeTimeoutMs);
+      const value = result.result?.value ?? {};
+      const text = String(value.text ?? "");
+      const href = String(value.href ?? target.url ?? "");
+      const blocked = text.includes("Background connection unresponsive") || text.includes("MetaMask had trouble starting") || text.includes("Unable to connect to Ethereum");
+      const onboarding = href.includes("/onboarding/");
+      const score = (compositor.status === "ready" ? 100 : compositor.status === "not-interactive" ? 10 : 0) + (value.readyState === "complete" ? 10 : 0) + (blocked ? 0 : 5) + (onboarding ? 0 : 2);
+      ranked.push({ target, score, index });
+    } catch {
+      ranked.push({ target, score: -1, index });
+    } finally {
+      session?.close();
+    }
+  }
+  ranked.sort((left, right) => right.score - left.score || left.index - right.index);
+  return { target: ranked[0]?.target };
+}
 function failReport(cdpPort, findings, details, extensionPageTargets = 0) {
   return {
     status: "FAIL",
@@ -316,6 +361,127 @@ async function evaluateHealth(session, timeoutMs) {
   }
   return result.result?.value ?? {};
 }
+async function probeUiEthereumProvider(session, timeoutMs) {
+  const bridgeKey = "mm-harness.runtime.evm-provider-probe";
+  const preload = await boundedCdpCall(
+    session,
+    "Page.addScriptToEvaluateOnNewDocument",
+    {
+      source: `(() => {
+        const bridgeKey = Symbol.for(${JSON.stringify(bridgeKey)});
+        let provider;
+        Object.defineProperty(globalThis, 'ethereumProvider', {
+          configurable: true,
+          get() { return provider; },
+          set(value) { provider = value; },
+        });
+        Object.defineProperty(globalThis, bridgeKey, {
+          configurable: true,
+          value: {
+            async probe() {
+              if (!provider || typeof provider.request !== 'function') {
+                return { ok: false, error: 'Ethereum provider is unavailable' };
+              }
+              try {
+                const code = await provider.request({
+                  method: 'eth_getCode',
+                  params: ['0x0000000000000000000000000000000000000000', 'latest'],
+                });
+                const ok = typeof code === 'string' && /^0x[0-9a-f]*$/iu.test(code);
+                return {
+                  ok,
+                  error: ok ? null : 'Ethereum provider returned invalid contract code',
+                };
+              } catch (error) {
+                return { ok: false, error: String(error?.message || error) };
+              }
+            },
+            cleanup() {
+              const descriptor = Object.getOwnPropertyDescriptor(globalThis, 'ethereumProvider');
+              if (descriptor?.configurable === true) {
+                Object.defineProperty(globalThis, 'ethereumProvider', {
+                  configurable: true,
+                  writable: true,
+                  value: provider,
+                });
+              }
+              return delete globalThis[bridgeKey];
+            },
+          },
+        });
+      })();`
+    },
+    timeoutMs
+  );
+  if (typeof preload?.identifier !== "string" || preload.identifier.length === 0) {
+    return {
+      ok: false,
+      error: "Ethereum provider preload was not installed",
+      source: "ui-ethereum-provider"
+    };
+  }
+  let outcome = {
+    ok: false,
+    error: "Ethereum provider is unavailable",
+    source: "ui-ethereum-provider"
+  };
+  const cleanupErrors = [];
+  try {
+    await boundedCdpCall(session, "Page.reload", { ignoreCache: false }, timeoutMs);
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() <= deadline) {
+      try {
+        const result = await boundedCdpCall(session, "Runtime.evaluate", {
+          expression: `globalThis[Symbol.for(${JSON.stringify(bridgeKey)})]?.probe()`,
+          awaitPromise: true,
+          returnByValue: true
+        }, Math.max(1, deadline - Date.now()));
+        const value = result.result?.value;
+        if (value?.ok === true) {
+          outcome = { ok: true, error: null, source: "ui-ethereum-provider" };
+          break;
+        }
+        if (typeof value?.error === "string") outcome.error = value.error;
+      } catch (error) {
+        outcome.error = messageOf(error);
+      }
+      if (outcome.ok) break;
+      await sleep(100);
+    }
+  } catch (error) {
+    outcome = { ok: false, error: messageOf(error), source: "ui-ethereum-provider" };
+  } finally {
+    try {
+      const cleanup = await boundedCdpCall(session, "Runtime.evaluate", {
+        expression: `(() => {
+          const key = Symbol.for(${JSON.stringify(bridgeKey)});
+          const bridge = globalThis[key];
+          if (!bridge) return true;
+          return bridge.cleanup() === true && !(key in globalThis);
+        })()`,
+        returnByValue: true
+      }, timeoutMs);
+      if (cleanup.result?.value !== true) cleanupErrors.push("page bridge removal was not confirmed");
+    } catch (error) {
+      cleanupErrors.push(messageOf(error));
+    }
+    try {
+      await boundedCdpCall(
+        session,
+        "Page.removeScriptToEvaluateOnNewDocument",
+        { identifier: preload.identifier },
+        timeoutMs
+      );
+    } catch (error) {
+      cleanupErrors.push(messageOf(error));
+    }
+  }
+  return cleanupErrors.length > 0 ? {
+    ok: false,
+    error: `Ethereum provider probe cleanup failed: ${cleanupErrors.join("; ")}`,
+    source: "ui-ethereum-provider"
+  } : outcome;
+}
 function extensionBackgroundProbeTimeoutMs(cdpCallTimeoutMs) {
   return Math.max(1, Math.floor(cdpCallTimeoutMs * 0.8));
 }

package/dist/adapters/mobile/provision.js

@@ -14,6 +14,8 @@ const RUNWAY_IOS_METADATA = {
 };
 class SimulatorTargetError extends Error {
 }
+class SimulatorUnresponsiveError extends Error {
+}
 function resolvePoolIdentity(target) {
   const out = resolveSlotPortsByRepo(target);
   const id = {};
@@ -75,7 +77,7 @@ async function provisionRunwayMobile(target, options) {
     const sim = ensureSimulator(simulator, runtime, deviceType);
     let resolved;
     let reason = options.force ? "forced" : "fresh-install";
-    if (!options.force && appInstalled(sim.udid ?? sim.name)) {
+    if (!options.force && appInstalledWithRecovery(sim.udid ?? sim.name, options)) {
       const installed = readInstalledBaselineArtifact(resolvedTarget, sim, options.runtimeDir);
       let requestedRunId = options.run;
       if (installed && !requestedRunId) {
@@ -445,6 +447,24 @@ function bootSimulator(device, options) {
     log(options, `runway: bootstatus wait for ${device} did not confirm; continuing to install`);
   }
 }
+function restartSimulator(device, options) {
+  log(options, `runway: simulator ${device} did not answer the app probe; restarting it once`);
+  execFileSync("xcrun", ["simctl", "shutdown", device], {
+    stdio: ["ignore", "ignore", "ignore"],
+    timeout: 3e4
+  });
+  try {
+    execFileSync("xcrun", ["simctl", "boot", device], {
+      stdio: ["ignore", "ignore", "ignore"],
+      timeout: 3e4
+    });
+  } catch {
+  }
+  execFileSync("xcrun", ["simctl", "bootstatus", device, "-b"], {
+    stdio: ["ignore", "ignore", "ignore"],
+    timeout: 12e4
+  });
+}
 function preapproveDeepLinkScheme(device, bundleId, options) {
   const scheme = process.env.IOS_DEV_CLIENT_SCHEME ?? "expo-metamask";
   try {
@@ -572,12 +592,27 @@ function readInstalledBaselineArtifact(target, sim, runtimeDir) {
 }
 function appInstalled(device) {
   try {
-    execFileSync("xcrun", ["simctl", "get_app_container", device, RUNWAY_IOS_METADATA.bundleId, "app"], { stdio: ["ignore", "ignore", "ignore"] });
+    execFileSync("xcrun", ["simctl", "get_app_container", device, RUNWAY_IOS_METADATA.bundleId, "app"], {
+      stdio: ["ignore", "ignore", "ignore"],
+      timeout: 15e3
+    });
     return true;
-  } catch {
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ETIMEDOUT") {
+      throw new SimulatorUnresponsiveError(`simulator ${device} timed out while checking the installed app`);
+    }
     return false;
   }
 }
+function appInstalledWithRecovery(device, options) {
+  try {
+    return appInstalled(device);
+  } catch (error) {
+    if (!(error instanceof SimulatorUnresponsiveError)) throw error;
+    restartSimulator(device, options);
+    return appInstalled(device);
+  }
+}
 function writeRunwayBaseline(target, slot, platform, resolved, artifact, simulator, alreadyInstalled, runtimeDir, preservedArtifact) {
   const file = runwayBaselinePath(target, runtimeDir);
   fs.mkdirSync(path.dirname(file), { recursive: true });

package/dist/adapters/mobile/release-artifact-state.js

@@ -0,0 +1,124 @@
+import { randomBytes } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { recipeRuntimePath } from "../../paths.js";
+import {
+  assertAndroidReleaseArtifactRuntime
+} from "./release-artifact.js";
+function mobileReleaseArtifactStatePath(target) {
+  return recipeRuntimePath(target, "mobile-release-artifact.json");
+}
+function writeMobileReleaseArtifactState(target, report) {
+  const state = {
+    schemaVersion: 1,
+    adapter: "mobile",
+    platform: "android",
+    packageId: report.packageId,
+    versionName: report.versionName,
+    versionCode: report.versionCode,
+    sha256: report.sha256,
+    deviceSerial: report.deviceSerial,
+    installedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  const file = mobileReleaseArtifactStatePath(target);
+  const directory = ensureSafeRuntimeDirectory(target, file);
+  const existing = fs.lstatSync(file, { throwIfNoEntry: false });
+  if (existing && (!existing.isFile() || existing.isSymbolicLink())) throw invalidState(file);
+  const temporary = path.join(
+    directory,
+    `.mobile-release-artifact.${process.pid}.${randomBytes(8).toString("hex")}.tmp`
+  );
+  let descriptor;
+  try {
+    descriptor = fs.openSync(temporary, "wx", 384);
+    fs.writeFileSync(descriptor, `${JSON.stringify(state, null, 2)}
+`, "utf8");
+    fs.fsyncSync(descriptor);
+    fs.closeSync(descriptor);
+    descriptor = void 0;
+    fs.renameSync(temporary, file);
+  } finally {
+    if (descriptor !== void 0) fs.closeSync(descriptor);
+    const temporaryStat = fs.lstatSync(temporary, { throwIfNoEntry: false });
+    if (temporaryStat) fs.unlinkSync(temporary);
+  }
+  return state;
+}
+function requireCurrentMobileReleaseArtifactState(target, verify = assertAndroidReleaseArtifactRuntime) {
+  const state = readMobileReleaseArtifactState(target);
+  if (state) verify(state);
+  return state;
+}
+function clearMobileReleaseArtifactState(target) {
+  const file = mobileReleaseArtifactStatePath(target);
+  const existing = fs.lstatSync(file, { throwIfNoEntry: false });
+  if (!existing) return;
+  ensureSafeRuntimeDirectory(target, file);
+  if (!existing.isFile() || existing.isSymbolicLink()) throw invalidState(file);
+  fs.unlinkSync(file);
+}
+function readMobileReleaseArtifactState(target) {
+  const file = mobileReleaseArtifactStatePath(target);
+  let stat;
+  try {
+    stat = fs.lstatSync(file);
+  } catch (error) {
+    if (isMissing(error)) return null;
+    throw invalidState(file);
+  }
+  try {
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size <= 0 || stat.size > 16 * 1024) {
+      throw invalidState(file);
+    }
+    const value = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (value.schemaVersion !== 1 || value.adapter !== "mobile" || value.platform !== "android" || !text(value.packageId) || !text(value.versionName) || !text(value.versionCode) || !/^[a-f0-9]{64}$/u.test(value.sha256 ?? "") || !text(value.deviceSerial) || !text(value.installedAt)) throw invalidState(file);
+    return value;
+  } catch (error) {
+    if (error instanceof Error && error.message.startsWith("The Mobile release artifact state is invalid")) {
+      throw error;
+    }
+    throw invalidState(file);
+  }
+}
+function text(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+function isMissing(error) {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+function invalidState(file) {
+  return new Error(`The Mobile release artifact state is invalid: ${file}. Next: rerun runtime-launch with the same artifact source.`);
+}
+function ensureSafeRuntimeDirectory(target, file) {
+  const root = path.resolve(target);
+  const directory = path.dirname(path.resolve(file));
+  const relative = path.relative(root, directory);
+  if (!relative || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw invalidState(file);
+  }
+  let current = root;
+  const rootStat = fs.lstatSync(root, { throwIfNoEntry: false });
+  if (!rootStat?.isDirectory() || rootStat.isSymbolicLink()) throw invalidState(file);
+  for (const segment of relative.split(path.sep)) {
+    current = path.join(current, segment);
+    const stat = fs.lstatSync(current, { throwIfNoEntry: false });
+    if (stat) {
+      if (!stat.isDirectory() || stat.isSymbolicLink()) throw invalidState(file);
+    } else {
+      fs.mkdirSync(current, { mode: 448 });
+    }
+  }
+  const realRoot = fs.realpathSync(root);
+  const realDirectory = fs.realpathSync(directory);
+  if (realDirectory !== realRoot && !realDirectory.startsWith(`${realRoot}${path.sep}`)) {
+    throw invalidState(file);
+  }
+  return directory;
+}
+export {
+  clearMobileReleaseArtifactState,
+  mobileReleaseArtifactStatePath,
+  readMobileReleaseArtifactState,
+  requireCurrentMobileReleaseArtifactState,
+  writeMobileReleaseArtifactState
+};

package/dist/adapters/mobile/release-artifact.js

@@ -0,0 +1,295 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import { promises as fsp } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+async function installAndroidReleaseArtifact(options, deps = defaultDeps) {
+  validateInputs(options);
+  const sourcePath = path.resolve(options.file);
+  const stagingDirectory = await fsp.mkdtemp(path.join(os.tmpdir(), "mm-harness-android-artifact-"));
+  try {
+    const stagedPath = path.join(stagingDirectory, "release.apk");
+    const { sha256, bytes } = await stageRegularFile(sourcePath, stagedPath);
+    if (sha256 !== options.expectedSha256) {
+      throw new Error(`Android artifact SHA-256 ${sha256} does not match expected ${options.expectedSha256}.`);
+    }
+    const { packageId, versionName, versionCode } = readAndroidPackageIdentity(deps, stagedPath);
+    if (packageId !== options.packageId) {
+      throw new Error(`Android artifact package ${packageId || "missing"} does not match expected ${options.packageId}.`);
+    }
+    if (versionName !== options.expectedVersion) {
+      throw new Error(`Android artifact version ${versionName || "missing"} does not match expected ${options.expectedVersion}.`);
+    }
+    if (versionCode !== options.expectedBuildId) {
+      throw new Error(`Android artifact build ${versionCode || "missing"} does not match expected ${options.expectedBuildId}.`);
+    }
+    const adb = resolveAdb(deps);
+    const state = runChecked(deps, adb, ["-s", options.deviceSerial, "get-state"]).trim();
+    if (state !== "device") {
+      throw new Error(`Android device ${options.deviceSerial} is not ready.`);
+    }
+    runChecked(deps, adb, ["-s", options.deviceSerial, "install", "-r", "-d", stagedPath]);
+    assertInstalledAndroidReleaseArtifact({
+      packageId,
+      versionName,
+      versionCode,
+      sha256,
+      deviceSerial: options.deviceSerial
+    }, deps, adb);
+    runChecked(deps, adb, [
+      "-s",
+      options.deviceSerial,
+      "shell",
+      "monkey",
+      "-p",
+      packageId,
+      "-c",
+      "android.intent.category.LAUNCHER",
+      "1"
+    ]);
+    let pid = "";
+    for (let attempt = 0; attempt < 20; attempt += 1) {
+      const result = deps.run(adb, ["-s", options.deviceSerial, "shell", "pidof", packageId]);
+      if (result.status === 0 && result.stdout.trim()) {
+        pid = result.stdout.trim();
+        break;
+      }
+      await deps.sleep(250);
+    }
+    if (!pid) throw new Error(`Android package ${packageId} did not start on ${options.deviceSerial}.`);
+    return {
+      schemaVersion: 1,
+      status: "pass",
+      adapter: "mobile",
+      platform: "android",
+      source: { kind: "local", path: sourcePath },
+      sha256,
+      bytes,
+      packageId,
+      versionName,
+      versionCode,
+      deviceSerial: options.deviceSerial,
+      installed: true,
+      launched: true
+    };
+  } finally {
+    await fsp.rm(stagingDirectory, { recursive: true, force: true });
+  }
+}
+function assertAndroidReleaseArtifactRuntime(identity, deps = defaultDeps) {
+  validateInputs({
+    file: "runtime.apk",
+    expectedVersion: identity.versionName,
+    expectedBuildId: identity.versionCode,
+    expectedSha256: identity.sha256,
+    packageId: identity.packageId,
+    deviceSerial: identity.deviceSerial
+  });
+  const adb = resolveAdb(deps);
+  assertInstalledAndroidReleaseArtifact(identity, deps, adb);
+}
+async function relaunchAndroidReleaseArtifactRuntime(identity, deps = defaultDeps) {
+  assertAndroidReleaseArtifactRuntime(identity, deps);
+  const adb = resolveAdb(deps);
+  runChecked(deps, adb, [
+    "-s",
+    identity.deviceSerial,
+    "shell",
+    "monkey",
+    "-p",
+    identity.packageId,
+    "-c",
+    "android.intent.category.LAUNCHER",
+    "1"
+  ]);
+  for (let attempt = 0; attempt < 20; attempt += 1) {
+    const result = deps.run(adb, ["-s", identity.deviceSerial, "shell", "pidof", identity.packageId]);
+    if (result.status === 0 && result.stdout.trim()) return;
+    await deps.sleep(250);
+  }
+  throw new Error(`Android package ${identity.packageId} did not start on ${identity.deviceSerial}.`);
+}
+function validateInputs(options) {
+  if (!/^\d+\.\d+\.\d+(?:[-+][A-Za-z0-9._-]+)?$/u.test(options.expectedVersion)) {
+    throw new Error("--artifact-version must be an Android version name such as X.Y.Z.");
+  }
+  if (!/^\d+$/u.test(options.expectedBuildId)) {
+    throw new Error("--artifact-build-id must be the numeric Android version code.");
+  }
+  if (!/^[a-f0-9]{64}$/u.test(options.expectedSha256)) {
+    throw new Error("--artifact-sha256 must be 64 lowercase hexadecimal characters.");
+  }
+  if (!/^[A-Za-z][A-Za-z0-9_]*(?:\.[A-Za-z][A-Za-z0-9_]*)+$/u.test(options.packageId)) {
+    throw new Error("--artifact-package-id must be an Android application ID.");
+  }
+  if (!/^[A-Za-z0-9._:-]+$/u.test(options.deviceSerial)) {
+    throw new Error("Android artifact launch requires an explicit device serial.");
+  }
+}
+function assertInstalledAndroidReleaseArtifact(identity, deps, adb) {
+  const state = runChecked(deps, adb, ["-s", identity.deviceSerial, "get-state"]).trim();
+  if (state !== "device") throw new Error(`Android device ${identity.deviceSerial} is not ready.`);
+  const paths = runChecked(deps, adb, [
+    "-s",
+    identity.deviceSerial,
+    "shell",
+    "pm",
+    "path",
+    identity.packageId
+  ]).split(/\r?\n/u).filter(Boolean);
+  if (paths.length !== 1 || !paths[0].startsWith("package:/") || !paths[0].endsWith("/base.apk")) {
+    throw new Error(`Android package ${identity.packageId} is not a single installed APK on ${identity.deviceSerial}.`);
+  }
+  const installedPath = paths[0].slice("package:".length);
+  if (!/^\/data\/app\/[A-Za-z0-9._~+=/-]+\/base\.apk$/u.test(installedPath)) {
+    throw new Error(`Android package ${identity.packageId} returned an unsafe installed path.`);
+  }
+  const installedSha256 = runChecked(deps, adb, [
+    "-s",
+    identity.deviceSerial,
+    "shell",
+    "sha256sum",
+    installedPath
+  ]).trim().split(/\s+/u)[0];
+  if (installedSha256 !== identity.sha256) {
+    throw new Error(`Android package ${identity.packageId} no longer matches the trusted release artifact SHA-256.`);
+  }
+  const installed = runChecked(deps, adb, [
+    "-s",
+    identity.deviceSerial,
+    "shell",
+    "dumpsys",
+    "package",
+    identity.packageId
+  ]);
+  if (!new RegExp(`^\\s*versionName=${escapeRegExp(identity.versionName)}\\s*$`, "mu").test(installed) || !new RegExp(`^\\s*versionCode=${escapeRegExp(identity.versionCode)}(?:\\s|$)`, "mu").test(installed)) {
+    throw new Error(`Android package ${identity.packageId} installed with an unexpected version on ${identity.deviceSerial}.`);
+  }
+}
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+}
+async function stageRegularFile(file, destination) {
+  const descriptor = await fsp.open(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+  const output = await fsp.open(destination, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL, 384);
+  try {
+    const stat = await descriptor.stat();
+    if (!stat.isFile() || stat.size <= 0 || stat.size > 2 * 1024 * 1024 * 1024) {
+      throw new Error(`Android artifact must be a non-empty regular file smaller than 2 GiB: ${file}`);
+    }
+    const digest = createHash("sha256");
+    const stream = descriptor.createReadStream({ autoClose: false });
+    for await (const chunk of stream) {
+      digest.update(chunk);
+      await output.writeFile(chunk);
+    }
+    await output.sync();
+    return { sha256: digest.digest("hex"), bytes: stat.size };
+  } finally {
+    await output.close();
+    await descriptor.close();
+  }
+}
+function resolveAdb(deps) {
+  const configured = process.env.ANDROID_HOME || process.env.ANDROID_SDK_ROOT;
+  const candidates = [
+    configured ? path.join(configured, "platform-tools", "adb") : "",
+    path.join(os.homedir(), "Library", "Android", "sdk", "platform-tools", "adb"),
+    "adb"
+  ].filter(Boolean);
+  return firstRunnable(deps, candidates, ["version"], "adb");
+}
+function readAndroidPackageIdentity(deps, file) {
+  const analyzer = resolveApkAnalyzer(deps);
+  if (analyzer) {
+    const packageId2 = deps.run(analyzer, ["manifest", "application-id", file]);
+    const versionName2 = deps.run(analyzer, ["manifest", "version-name", file]);
+    const versionCode2 = deps.run(analyzer, ["manifest", "version-code", file]);
+    if (packageId2.status === 0 && packageId2.stdout.trim() && versionName2.status === 0 && versionName2.stdout.trim() && versionCode2.status === 0 && versionCode2.stdout.trim()) {
+      return {
+        packageId: packageId2.stdout.trim(),
+        versionName: versionName2.stdout.trim(),
+        versionCode: versionCode2.stdout.trim()
+      };
+    }
+  }
+  const aapt2 = resolveAapt2(deps);
+  const badging = runChecked(deps, aapt2, ["dump", "badging", file]);
+  const line = badging.split(/\r?\n/u).find((entry) => entry.startsWith("package: ")) ?? "";
+  const packageId = /\bname='([^']+)'/u.exec(line)?.[1] ?? "";
+  const versionCode = /\bversionCode='([^']+)'/u.exec(line)?.[1] ?? "";
+  const versionName = /\bversionName='([^']+)'/u.exec(line)?.[1] ?? "";
+  if (!packageId || !versionCode || !versionName) {
+    throw new Error("aapt2 could not read the Android artifact package identity.");
+  }
+  return { packageId, versionName, versionCode };
+}
+function resolveApkAnalyzer(deps) {
+  const configured = process.env.ANDROID_HOME || process.env.ANDROID_SDK_ROOT;
+  const candidates = [
+    configured ? path.join(configured, "cmdline-tools", "latest", "bin", "apkanalyzer") : "",
+    path.join(os.homedir(), "Library", "Android", "sdk", "cmdline-tools", "latest", "bin", "apkanalyzer")
+  ].filter(Boolean);
+  for (const candidate of candidates) {
+    try {
+      fs.accessSync(candidate, fs.constants.X_OK);
+      if (fs.statSync(candidate).isFile()) return candidate;
+    } catch {
+      continue;
+    }
+  }
+  const probe = deps.run("apkanalyzer", []);
+  if (`${probe.stdout}
+${probe.stderr}`.includes("manifest application-id")) return "apkanalyzer";
+  return null;
+}
+function resolveAapt2(deps) {
+  const configured = process.env.ANDROID_HOME || process.env.ANDROID_SDK_ROOT;
+  const buildToolsRoot = configured ? path.join(configured, "build-tools") : path.join(os.homedir(), "Library", "Android", "sdk", "build-tools");
+  let candidates = [];
+  try {
+    candidates = fs.readdirSync(buildToolsRoot).sort((left, right) => right.localeCompare(left, void 0, { numeric: true })).map((version) => path.join(buildToolsRoot, version, "aapt2"));
+  } catch {
+    candidates = [];
+  }
+  candidates.push("aapt2");
+  return firstRunnable(deps, candidates, ["version"], "apkanalyzer or aapt2");
+}
+function firstRunnable(deps, candidates, args, label) {
+  for (const candidate of candidates) {
+    if (deps.run(candidate, args).status === 0) return candidate;
+  }
+  throw new Error(`${label} is required to validate and install an Android release artifact.`);
+}
+function runChecked(deps, command, args) {
+  const result = deps.run(command, args);
+  if (result.status !== 0) {
+    const detail = result.stderr.trim() || result.stdout.trim() || `exit ${result.status}`;
+    throw new Error(`${path.basename(command)} failed: ${detail}`);
+  }
+  return result.stdout;
+}
+const defaultDeps = {
+  run(command, args) {
+    const result = spawnSync(command, args, {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: 12e4,
+      maxBuffer: 4 * 1024 * 1024
+    });
+    return {
+      status: result.status ?? 1,
+      stdout: result.stdout || "",
+      stderr: result.stderr || result.error?.message || ""
+    };
+  },
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+export {
+  assertAndroidReleaseArtifactRuntime,
+  installAndroidReleaseArtifact,
+  relaunchAndroidReleaseArtifactRuntime
+};