@appium/coresim 1.0.0

package/src/commands/app.ts

@@ -0,0 +1,186 @@
+import {fileURLToPath} from 'node:url';
+
+import type {NativeSimctl} from '../native-simctl.js';
+import {runCatchingAsync} from '../utils/index.js';
+
+declare module '../native-simctl.js' {
+  interface NativeSimctl {
+    installApp(udid: string, appPath: string, options?: Record<string, unknown>): Promise<void>;
+    removeApp(udid: string, bundleId: string, options?: Record<string, unknown>): Promise<void>;
+    launchApp(udid: string, bundleId: string, options?: Record<string, unknown>): Promise<number>;
+    terminateApp(udid: string, bundleId: string): Promise<void>;
+    isAppInstalled(udid: string, bundleId: string): Promise<boolean>;
+    appInfo(udid: string, bundleId: string): Promise<Record<string, unknown>>;
+    installedApps(udid: string): Promise<Record<string, unknown>>;
+    getAppContainer(udid: string, bundleId: string, containerType?: AppContainerType | string): Promise<string>;
+  }
+}
+
+/**
+ * Which of an app's on-disk containers {@link getAppContainer} should resolve — `'app'` (the
+ * `.app` bundle itself), `'data'` (its data container), `'groups'` (its sole App Group container,
+ * if it has exactly one), or any other string naming a specific App Group identifier.
+ */
+export type AppContainerType = 'app' | 'data' | 'groups';
+
+/**
+ * Installs an `.app` bundle onto the given device.
+ *
+ * @param udid — UDID of the target device
+ * @param appPath — path to the `.app` bundle on disk
+ * @param options — passed through to `installApplication:withOptions:error:`
+ */
+export async function installApp(
+  this: NativeSimctl,
+  udid: string,
+  appPath: string,
+  options: Record<string, unknown> = {},
+): Promise<void> {
+  return runCatchingAsync(async () => (await this._findDevice(udid)).installApp(appPath, options));
+}
+
+/**
+ * Uninstalls an app from the given device.
+ *
+ * @param udid — UDID of the target device
+ * @param bundleId — bundle identifier of the app to remove
+ * @param options — passed through to `uninstallApplication:withOptions:error:`
+ */
+export async function removeApp(
+  this: NativeSimctl,
+  udid: string,
+  bundleId: string,
+  options: Record<string, unknown> = {},
+): Promise<void> {
+  return runCatchingAsync(async () => (await this._findDevice(udid)).uninstallApp(bundleId, options));
+}
+
+/**
+ * Launches an installed app on the given device.
+ *
+ * @param udid — UDID of the target device
+ * @param bundleId — bundle identifier of the app to launch
+ * @param options — passed through to `launchApplicationWithID:options:error:`
+ * @returns the launched process's pid
+ */
+export async function launchApp(
+  this: NativeSimctl,
+  udid: string,
+  bundleId: string,
+  options: Record<string, unknown> = {},
+): Promise<number> {
+  return runCatchingAsync(async () => (await this._findDevice(udid)).launchApp(bundleId, options));
+}
+
+/**
+ * @param udid — UDID of the target device
+ * @param bundleId — bundle identifier of the app to terminate
+ */
+export async function terminateApp(this: NativeSimctl, udid: string, bundleId: string): Promise<void> {
+  return runCatchingAsync(async () => (await this._findDevice(udid)).terminateApp(bundleId));
+}
+
+/**
+ * @param udid — UDID of the device to check
+ * @param bundleId — bundle identifier to look up
+ * @returns whether an app with that bundle identifier is installed
+ */
+export async function isAppInstalled(this: NativeSimctl, udid: string, bundleId: string): Promise<boolean> {
+  return runCatchingAsync(async () => bundleId in (await (await this._findDevice(udid)).installedApps()));
+}
+
+/**
+ * @param udid — UDID of the device to read from
+ * @param bundleId — bundle identifier of the installed app
+ * @returns the app's properties, as reported by `propertiesOfApplication:`
+ */
+export async function appInfo(this: NativeSimctl, udid: string, bundleId: string): Promise<Record<string, unknown>> {
+  return runCatchingAsync(async () => (await this._findDevice(udid)).propertiesOfApplication(bundleId));
+}
+
+/**
+ * @param udid — UDID of the device to read from
+ * @returns every installed app's properties, keyed by bundle identifier
+ */
+export async function installedApps(this: NativeSimctl, udid: string): Promise<Record<string, unknown>> {
+  return runCatchingAsync(async () => (await this._findDevice(udid)).installedApps());
+}
+
+/** Converts a `file://` URL string (as `appInfo`'s container fields report) to a plain fs path. */
+function toFsPath(fileUrl: unknown): string | undefined {
+  if (typeof fileUrl !== 'string') {
+    return undefined;
+  }
+  return fileURLToPath(fileUrl).replace(/\/$/, '');
+}
+
+/**
+ * Resolves the full filesystem path to one of an installed app's on-disk containers — the same
+ * paths {@link appInfo}'s `Path`/`DataContainer`/`GroupContainers` fields already carry, just
+ * picked out and normalized to a plain path (no new native call).
+ *
+ * @example
+ * // Resolve a specific App Group container by its identifier (see appInfo's GroupContainers
+ * // field, or catch the error thrown below, to discover which identifiers an app has)
+ * const groupPath = await sim.getAppContainer(udid, bundleId, 'group.com.example.myapp');
+ *
+ * @param udid — UDID of the (booted) device to read from
+ * @param bundleId — bundle identifier of the installed app
+ * @param containerType — see {@link AppContainerType}; defaults to `'app'`
+ * @returns the resolved container's path
+ * @throws if the requested container doesn't exist (e.g. `'data'` before the device has booted
+ * once with the app installed), if `'groups'` is ambiguous (more than one App Group container —
+ * pass the specific group identifier instead), or if a given group identifier doesn't match any
+ * of the app's App Group containers — in both of the latter cases, the error message lists the
+ * app's actual App Group identifiers
+ */
+export async function getAppContainer(
+  this: NativeSimctl,
+  udid: string,
+  bundleId: string,
+  containerType: AppContainerType | string = 'app',
+): Promise<string> {
+  return runCatchingAsync(async () => {
+    const info = await this.appInfo(udid, bundleId);
+    if (containerType === 'app') {
+      const path = info.Path;
+      if (typeof path !== 'string') {
+        throw new Error(`No app bundle path was reported for '${bundleId}'`);
+      }
+      return path;
+    }
+    if (containerType === 'data') {
+      const path = toFsPath(info.DataContainer);
+      if (!path) {
+        throw new Error(`No data container was found for '${bundleId}' — has the device been booted since install?`);
+      }
+      return path;
+    }
+    const groupContainers = (info.GroupContainers ?? {}) as Record<string, unknown>;
+    if (containerType === 'groups') {
+      const entries = Object.entries(groupContainers);
+      if (entries.length === 0) {
+        throw new Error(`'${bundleId}' has no App Group containers`);
+      }
+      if (entries.length > 1) {
+        throw new Error(
+          `'${bundleId}' has multiple App Group containers (${Object.keys(groupContainers).join(', ')}) — ` +
+            `specify one by its group identifier instead of 'groups'`,
+        );
+      }
+      const path = toFsPath(entries[0][1]);
+      if (!path) {
+        throw new Error(`'${bundleId}''s App Group container has no reported path`);
+      }
+      return path;
+    }
+    const path = toFsPath(groupContainers[containerType]);
+    if (!path) {
+      const available = Object.keys(groupContainers);
+      const availability =
+        available.length > 0 ? `available: ${available.join(', ')}` : 'it has no App Group containers at all';
+      throw new Error(`'${bundleId}' has no App Group container with identifier '${containerType}' — ${availability}`);
+    }
+    return path;
+  });
+}

package/src/commands/biometric.ts

@@ -0,0 +1,69 @@
+import type {NativeSimctl} from '../native-simctl.js';
+
+declare module '../native-simctl.js' {
+  interface NativeSimctl {
+    isBiometricEnrolled(udid: string): Promise<boolean>;
+    enrollBiometric(udid: string, isEnabled?: boolean): Promise<void>;
+    sendBiometricMatch(udid: string, shouldMatch?: boolean, biometricName?: BiometricName): Promise<void>;
+  }
+}
+
+/** A simulated biometric sensor — Face ID is only available since iOS 11. */
+export type BiometricName = 'touchId' | 'faceId';
+
+// Simulator.app's own Features > Face ID/Touch ID menu drives the same two Darwin notifications
+// (see darwin-notification.ts) rather than any dedicated CoreSimulator API — no native call needed.
+const ENROLLMENT_NOTIFICATION_NAME = 'com.apple.BiometricKit.enrollmentChanged';
+const BIOMETRIC_DOMAIN_COMPONENTS: Record<BiometricName, string> = {
+  touchId: 'fingerTouch',
+  faceId: 'pearl',
+};
+
+/**
+ * @param udid — UDID of the device to read from
+ * @returns whether a biometric sensor is currently simulated as enrolled
+ */
+export async function isBiometricEnrolled(this: NativeSimctl, udid: string): Promise<boolean> {
+  return (await this.getDarwinNotificationState(udid, ENROLLMENT_NOTIFICATION_NAME)) === 1n;
+}
+
+/**
+ * Simulates enrolling (or un-enrolling) a biometric sensor — the prerequisite for
+ * {@link sendBiometricMatch} to have any effect.
+ *
+ * @param udid — UDID of the target device
+ * @param isEnabled — whether the device should report a biometric sensor as enrolled; defaults to `true`
+ */
+export async function enrollBiometric(this: NativeSimctl, udid: string, isEnabled = true): Promise<void> {
+  await this.setDarwinNotificationState(udid, ENROLLMENT_NOTIFICATION_NAME, isEnabled ? 1n : 0n);
+  await this.postDarwinNotification(udid, ENROLLMENT_NOTIFICATION_NAME);
+  if ((await isBiometricEnrolled.call(this, udid)) !== isEnabled) {
+    throw new Error(`Failed to set biometric enrolled state for '${udid}' to '${isEnabled}'`);
+  }
+}
+
+/**
+ * Simulates a successful or failed biometric match attempt — only takes effect once
+ * {@link enrollBiometric} has enrolled the corresponding sensor.
+ *
+ * @param udid — UDID of the target device
+ * @param shouldMatch — whether the simulated attempt should succeed; defaults to `true`
+ * @param biometricName — which sensor to simulate; defaults to `'touchId'`
+ */
+export async function sendBiometricMatch(
+  this: NativeSimctl,
+  udid: string,
+  shouldMatch = true,
+  biometricName: BiometricName = 'touchId',
+): Promise<void> {
+  if (!Object.hasOwn(BIOMETRIC_DOMAIN_COMPONENTS, biometricName)) {
+    throw new Error(
+      `'${biometricName}' is not a valid biometric — use one of: ${Object.keys(BIOMETRIC_DOMAIN_COMPONENTS).join(', ')}`,
+    );
+  }
+  const domainComponent = BIOMETRIC_DOMAIN_COMPONENTS[biometricName];
+  await this.postDarwinNotification(
+    udid,
+    `com.apple.BiometricKit_Sim.${domainComponent}.${shouldMatch ? '' : 'no'}match`,
+  );
+}

package/src/commands/darwin-notification.ts

@@ -0,0 +1,51 @@
+import type {NativeSimctl} from '../native-simctl.js';
+import {runCatchingAsync} from '../utils/index.js';
+
+declare module '../native-simctl.js' {
+  interface NativeSimctl {
+    getDarwinNotificationState(udid: string, name: string): Promise<bigint>;
+    setDarwinNotificationState(udid: string, name: string, state: bigint): Promise<void>;
+    postDarwinNotification(udid: string, name: string): Promise<void>;
+  }
+}
+
+/**
+ * The "state" here is Darwin's low-level `notify(3)` per-name state value (`notify_get_state`) —
+ * a full 64-bit integer any process can attach to a notification name independently of posting
+ * it, so a reader can check the last-set value without having been listening at post time.
+ * Returned as `bigint`, not `number` — a JS `number` only has 53 bits of safe integer precision,
+ * not enough for an arbitrary 64-bit counter or bit field another process may have stored.
+ *
+ * @see https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man3/notify.3.html
+ * @param udid — UDID of the device to read from
+ * @param name — Darwin notification name
+ * @returns the last-set state value for that notification (`0n` if never set)
+ */
+export async function getDarwinNotificationState(this: NativeSimctl, udid: string, name: string): Promise<bigint> {
+  return runCatchingAsync(async () => (await this._findDevice(udid)).darwinNotificationGetState(name));
+}
+
+/**
+ * Sets the state value of a Darwin notification on the given device, without posting it (see
+ * {@link getDarwinNotificationState} for what "state" means here — `notify(3)`'s `notify_set_state`).
+ *
+ * @param udid — UDID of the target device
+ * @param name — Darwin notification name
+ * @param state — state value to store; must fit in an unsigned 64-bit integer (`0n` to `2n**64n-1n`)
+ */
+export async function setDarwinNotificationState(
+  this: NativeSimctl,
+  udid: string,
+  name: string,
+  state: bigint,
+): Promise<void> {
+  return runCatchingAsync(async () => (await this._findDevice(udid)).darwinNotificationSetState(name, state));
+}
+
+/**
+ * @param udid — UDID of the target device
+ * @param name — Darwin notification name to post
+ */
+export async function postDarwinNotification(this: NativeSimctl, udid: string, name: string): Promise<void> {
+  return runCatchingAsync(async () => (await this._findDevice(udid)).postDarwinNotification(name));
+}

package/src/commands/interaction.ts

@@ -0,0 +1,74 @@
+import type {NativeSimctl} from '../native-simctl.js';
+import type {PushNotificationPayload} from '../types.js';
+import {runCatchingAsync} from '../utils/index.js';
+
+declare module '../native-simctl.js' {
+  interface NativeSimctl {
+    getEnv(udid: string, name: string): Promise<string>;
+    openUrl(udid: string, url: string): Promise<void>;
+    setLocation(udid: string, latitude: number, longitude: number): Promise<void>;
+    clearLocation(udid: string): Promise<void>;
+    pushNotification(udid: string, bundleId: string, payload: PushNotificationPayload): Promise<void>;
+  }
+}
+
+/**
+ * @param udid — UDID of the (booted) device to read from
+ * @param name — environment variable name
+ * @returns the variable's value
+ */
+export async function getEnv(this: NativeSimctl, udid: string, name: string): Promise<string> {
+  return runCatchingAsync(async () => (await this._findDevice(udid)).getenv(name));
+}
+
+/**
+ * Opens a URL on the given device; iOS resolves the app matching the URL's scheme.
+ *
+ * @param udid — UDID of the target device
+ * @param url — the URL to open, e.g. `https://appium.io`
+ */
+export async function openUrl(this: NativeSimctl, udid: string, url: string): Promise<void> {
+  return runCatchingAsync(async () => (await this._findDevice(udid)).openUrl(url));
+}
+
+/**
+ * Sets the given device's simulated GPS location.
+ *
+ * @param udid — UDID of the target device
+ * @param latitude — location latitude
+ * @param longitude — location longitude
+ */
+export async function setLocation(
+  this: NativeSimctl,
+  udid: string,
+  latitude: number,
+  longitude: number,
+): Promise<void> {
+  return runCatchingAsync(async () => (await this._findDevice(udid)).setLocation(latitude, longitude));
+}
+
+/**
+ * Stops simulating a GPS location previously set via {@link setLocation}, reverting the device to
+ * its default (no simulated location) behavior.
+ *
+ * @param udid — UDID of the target device
+ */
+export async function clearLocation(this: NativeSimctl, udid: string): Promise<void> {
+  return runCatchingAsync(async () => (await this._findDevice(udid)).clearLocation());
+}
+
+/**
+ * Delivers a simulated push notification to the given device.
+ *
+ * @param udid — UDID of the target device
+ * @param bundleId — bundle identifier of the app to receive the notification
+ * @param payload — see {@link PushNotificationPayload}
+ */
+export async function pushNotification(
+  this: NativeSimctl,
+  udid: string,
+  bundleId: string,
+  payload: PushNotificationPayload,
+): Promise<void> {
+  return runCatchingAsync(async () => (await this._findDevice(udid)).sendPushNotification(bundleId, payload));
+}

package/src/commands/keychain.ts

@@ -0,0 +1,63 @@
+import {randomUUID} from 'node:crypto';
+import {rm, writeFile} from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import type {NativeSimctl} from '../native-simctl.js';
+import {runCatchingAsync} from '../utils/index.js';
+
+declare module '../native-simctl.js' {
+  interface NativeSimctl {
+    addCertificate(udid: string, cert: string | Buffer): Promise<void>;
+    addRootCertificate(udid: string, cert: string | Buffer): Promise<void>;
+    resetKeychain(udid: string): Promise<void>;
+  }
+}
+
+/**
+ * Adds a certificate to the given device's keychain (not trusted as root).
+ *
+ * @param udid — UDID of the target device
+ * @param cert — path to a `.cert`/`.pem` file on disk, or the raw certificate content
+ */
+export async function addCertificate(this: NativeSimctl, udid: string, cert: string | Buffer): Promise<void> {
+  const {path: certPath, cleanup} = await resolveCertPath(cert);
+  try {
+    return await runCatchingAsync(async () => (await this._findDevice(udid)).addCertificate(certPath, false));
+  } finally {
+    await cleanup();
+  }
+}
+
+/**
+ * Adds a certificate to the given device's Trusted Root Store.
+ *
+ * @param udid — UDID of the target device
+ * @param cert — path to a `.cert`/`.pem` file on disk, or the raw certificate content
+ */
+export async function addRootCertificate(this: NativeSimctl, udid: string, cert: string | Buffer): Promise<void> {
+  const {path: certPath, cleanup} = await resolveCertPath(cert);
+  try {
+    return await runCatchingAsync(async () => (await this._findDevice(udid)).addCertificate(certPath, true));
+  } finally {
+    await cleanup();
+  }
+}
+
+/** @param udid — UDID of the device whose keychain should be reset */
+export async function resetKeychain(this: NativeSimctl, udid: string): Promise<void> {
+  return runCatchingAsync(async () => (await this._findDevice(udid)).resetKeychain());
+}
+
+/**
+ * The native call only accepts a file path — a `Buffer` is written to a throwaway temp file first,
+ * cleaned up by the caller once done.
+ */
+async function resolveCertPath(cert: string | Buffer): Promise<{path: string; cleanup: () => Promise<void>}> {
+  if (typeof cert === 'string') {
+    return {path: cert, cleanup: async () => {}};
+  }
+  const tmpPath = path.join(os.tmpdir(), `${randomUUID()}.pem`);
+  await writeFile(tmpPath, cert);
+  return {path: tmpPath, cleanup: () => rm(tmpPath, {force: true})};
+}

package/src/commands/lifecycle.ts

@@ -0,0 +1,210 @@
+import {waitForCondition} from 'asyncbox';
+
+import type {NativeSimctl} from '../native-simctl.js';
+import {SimDeviceState, type NativeDeviceHandle, type SimBootInfo, type SimDeviceInfo} from '../types.js';
+import type {SimDeviceTypeInfo, SimRuntimeInfo} from '../types.js';
+import {runCatchingAsync} from '../utils/index.js';
+
+const DEFAULT_BOOT_TIMEOUT_MS = 240_000;
+
+declare module '../native-simctl.js' {
+  interface NativeSimctl {
+    getDevices(): Promise<SimDeviceInfo[]>;
+    getSupportedDeviceTypes(): Promise<SimDeviceTypeInfo[]>;
+    getSupportedRuntimes(): Promise<SimRuntimeInfo[]>;
+    createDevice(name: string, deviceTypeIdentifier: string, runtimeIdentifier: string): Promise<SimDeviceInfo>;
+    deleteDevice(udid: string): Promise<void>;
+    bootDevice(udid: string, options?: Record<string, unknown>): Promise<void>;
+    getBootStatus(udid: string): Promise<SimBootInfo | null>;
+    waitForBoot(udid: string, options?: {timeoutMs?: number}): Promise<void>;
+    shutdownDevice(udid: string): Promise<void>;
+    shutdownAllDevices(): Promise<void>;
+    eraseDevice(udid: string): Promise<void>;
+  }
+}
+
+/** @returns every device in the default device set. */
+export async function getDevices(this: NativeSimctl): Promise<SimDeviceInfo[]> {
+  return runCatchingAsync(async () => {
+    const deviceSet = await this._deviceSet();
+    return (await deviceSet.devices()).map(toDeviceInfo);
+  });
+}
+
+/** @returns every simulator device type this CoreSimulator install supports (e.g. "iPhone 15"). */
+export async function getSupportedDeviceTypes(this: NativeSimctl): Promise<SimDeviceTypeInfo[]> {
+  return runCatchingAsync(async () => (await this._serviceContext()).supportedDeviceTypes());
+}
+
+/** @returns every simulator runtime this CoreSimulator install supports (e.g. iOS 17.4). */
+export async function getSupportedRuntimes(this: NativeSimctl): Promise<SimRuntimeInfo[]> {
+  return runCatchingAsync(async () => (await this._serviceContext()).supportedRuntimes());
+}
+
+/**
+ * Creates a new device in the default device set. Settles into the `Shutdown` state — never
+ * observed as `Creating` (see CLAUDE.md).
+ *
+ * @param name — display name for the new device
+ * @param deviceTypeIdentifier — e.g. `com.apple.CoreSimulator.SimDeviceType.iPhone-15`
+ * @param runtimeIdentifier — e.g. `com.apple.CoreSimulator.SimRuntime.iOS-17-4`
+ * @returns the newly created device
+ */
+export async function createDevice(
+  this: NativeSimctl,
+  name: string,
+  deviceTypeIdentifier: string,
+  runtimeIdentifier: string,
+): Promise<SimDeviceInfo> {
+  return runCatchingAsync(async () => {
+    const deviceSet = await this._deviceSet();
+    return toDeviceInfo(await deviceSet.createDevice(deviceTypeIdentifier, runtimeIdentifier, name));
+  });
+}
+
+/**
+ * Deletes the given device from the default device set. Returns before the underlying
+ * filesystem cleanup finishes — eventually consistent (see CLAUDE.md).
+ *
+ * @param udid — UDID of the device to delete
+ */
+export async function deleteDevice(this: NativeSimctl, udid: string): Promise<void> {
+  return runCatchingAsync(async () => {
+    const [deviceSet, device] = await Promise.all([this._deviceSet(), this._findDevice(udid)]);
+    await deviceSet.deleteDevice(device);
+  });
+}
+
+/**
+ * Boots the given device; resolves only once CoreSimulator's own async completion handler
+ * fires (see CLAUDE.md for a rare eventual-consistency caveat on the resulting `state`).
+ *
+ * @param udid — UDID of the device to boot
+ * @param options — passed through to `bootWithOptions:`/`bootAsyncWithOptions:...:`; the
+ * option-dictionary keys are currently unverified (see CLAUDE.md)
+ */
+export async function bootDevice(
+  this: NativeSimctl,
+  udid: string,
+  options: Record<string, unknown> = {},
+): Promise<void> {
+  return runCatchingAsync(async () => (await this._findDevice(udid)).boot(options));
+}
+
+/**
+ * Reads the device's current boot-progress status — the same underlying signal `simctl bootstatus`
+ * itself monitors (see CLAUDE.md), distinct from and more granular than `SimDeviceState`.
+ *
+ * @param udid — UDID of the device to read from
+ * @returns `null` if the device has never been booted; otherwise its most recent {@link SimBootInfo}.
+ * Confirmed empirically to **not** reset after shutdown — a shut-down device that was booted
+ * before still reports its last boot's terminal status, so check `getDevices()`'s `state` too if
+ * you need to know whether the device is *currently* booted (see {@link waitForBoot}, which does).
+ */
+export async function getBootStatus(this: NativeSimctl, udid: string): Promise<SimBootInfo | null> {
+  return runCatchingAsync(async () => (await this._findDevice(udid)).getBootStatus());
+}
+
+/**
+ * Waits for the given device's boot to fully settle — matching `simctl bootstatus`'s own notion of
+ * "done" (`SimBootInfo.isTerminal`), not just `SimDeviceState` reaching `Booted`, which happens
+ * *tens of seconds* earlier while data migration/system-app startup are still in progress (see
+ * CLAUDE.md). Returns immediately if the device is already fully booted (its very first status
+ * check already sees `isTerminal`).
+ *
+ * @param udid — UDID of the device to monitor
+ * @param options.timeoutMs — how long to wait before giving up (default 4 minutes, matching
+ * `simctl bootstatus`'s own default timeout)
+ * @throws if the device isn't currently `Booting` or `Booted` — there's nothing to monitor
+ * @throws if the device stops booting (e.g. is shut down) before it finishes
+ * @throws if `timeoutMs` elapses before boot settles
+ */
+export async function waitForBoot(this: NativeSimctl, udid: string, options: {timeoutMs?: number} = {}): Promise<void> {
+  const {timeoutMs = DEFAULT_BOOT_TIMEOUT_MS} = options;
+  return runCatchingAsync(async () => {
+    const initialState = (await this._findDevice(udid)).state();
+    if (initialState !== SimDeviceState.Booting && initialState !== SimDeviceState.Booted) {
+      throw new Error(`Device '${udid}' is not booting or booted (state: ${initialState})`);
+    }
+    // Re-resolves the device handle on every check (never caches it across the wait), matching
+    // every other method here — a device deleted mid-wait then surfaces as a normal "not found"
+    // error instead of a stale native reference failing in some less obvious way.
+    await waitForCondition(
+      async () => {
+        const device = await this._findDevice(udid);
+        const stateBefore = device.state();
+        if (stateBefore !== SimDeviceState.Booting && stateBefore !== SimDeviceState.Booted) {
+          // getBootStatus()'s isTerminal is confirmed to never reset on shutdown, so it would
+          // still read true from a *previous* boot session here if the device stopped booting
+          // partway through this wait (e.g. shut down by another caller) — checking current state
+          // too prevents reporting that stale old boot as this wait having succeeded.
+          throw new Error(`Device '${udid}' stopped booting before it finished (state: ${stateBefore})`);
+        }
+        const bootInfo = await device.getBootStatus();
+        // getBootStatus() is itself an async native call — the device can stop booting while it's
+        // in flight, which would otherwise let a stale isTerminal from the check above pass this
+        // predicate. Rechecking afterward, and requiring Booted specifically (not just Booting):
+        // isTerminal only ever turns true once state has already reached Booted (see CLAUDE.md —
+        // SimDeviceState reaches Booted well before boot info settles), so Booting + isTerminal can
+        // only mean a stale status from a previous boot session, never real completion.
+        const stateAfter = device.state();
+        if (stateAfter !== SimDeviceState.Booting && stateAfter !== SimDeviceState.Booted) {
+          throw new Error(`Device '${udid}' stopped booting before it finished (state: ${stateAfter})`);
+        }
+        return stateAfter === SimDeviceState.Booted && bootInfo?.isTerminal === true;
+      },
+      {
+        waitMs: timeoutMs,
+        intervalMs: 500,
+        error: `Device '${udid}' did not finish booting within ${timeoutMs}ms`,
+      },
+    );
+  });
+}
+
+/**
+ * @param udid — UDID of the device to shut down
+ * @throws if the device is already `Shutdown` — this is not an idempotent no-op
+ */
+export async function shutdownDevice(this: NativeSimctl, udid: string): Promise<void> {
+  return runCatchingAsync(async () => (await this._findDevice(udid)).shutdown());
+}
+
+/**
+ * Best-effort shutdown of every device in the default device set that isn't already `Shutdown` —
+ * the native equivalent of `xcrun simctl shutdown all`. A fan-out over {@link shutdownDevice}
+ * rather than `SimDeviceSet`'s own bulk method, whose completion-block signature couldn't be
+ * confirmed safely (see commit message). Per-device failures are swallowed.
+ */
+export async function shutdownAllDevices(this: NativeSimctl): Promise<void> {
+  return runCatchingAsync(async () => {
+    const deviceSet = await this._deviceSet();
+    const devices = await deviceSet.devices();
+    await Promise.all(
+      devices
+        .filter((device) => device.state() !== SimDeviceState.Shutdown)
+        .map((device) => device.shutdown().catch(() => {})),
+    );
+  });
+}
+
+/**
+ * Resets the given device's content and settings. Requires it to already be `Shutdown` — call
+ * {@link shutdownDevice} first if it's booted (see CLAUDE.md).
+ *
+ * @param udid — UDID of the device to erase
+ * @throws if the device isn't currently `Shutdown`
+ */
+export async function eraseDevice(this: NativeSimctl, udid: string): Promise<void> {
+  return runCatchingAsync(async () => (await this._findDevice(udid)).erase());
+}
+
+function toDeviceInfo(device: NativeDeviceHandle): SimDeviceInfo {
+  return {
+    udid: device.udid(),
+    name: device.name(),
+    state: device.state() as SimDeviceState,
+    deviceTypeIdentifier: device.deviceTypeIdentifier(),
+    runtimeIdentifier: device.runtimeIdentifier(),
+  };
+}