@appium/coresim 1.12.0 → 1.13.1

package/src/native-simctl.ts

@@ -56,6 +56,13 @@ import {
 import {isVideoRecording, startVideoRecording, stopVideoRecording} from './commands/video-recording.js';
 import {startVideoStream} from './commands/video-stream.js';
 import {getWebInspectorSocket} from './commands/webinspector.js';
+import {NativeSimUnavailableError} from './errors.js';
+import type {
+  NativeCoreSimModule,
+  NativeDeviceHandle,
+  NativeDeviceSetHandle,
+  NativeServiceContextHandle,
+} from './types.js';
 // Bare re-imports so `declare module './native-simctl.js'` augmentations in the command modules
 // (which add their methods to NativeSimctl's type) reach downstream consumers' emitted .d.ts
 // import graph — the named imports above alone aren't part of NativeSimctl's emitted type
@@ -78,17 +85,26 @@ import './commands/ui.js';
 import './commands/video-recording.js';
 import './commands/video-stream.js';
 import './commands/webinspector.js';
-import {NativeSimUnavailableError} from './errors.js';
-import type {
-  NativeCoreSimModule,
-  NativeDeviceHandle,
-  NativeDeviceSetHandle,
-  NativeServiceContextHandle,
-} from './types.js';
 import {getPkgRoot, PACKAGE_NAME, runCatchingAsync} from './utils/index.js';
 
 const require = createRequire(import.meta.url);
 
+export interface NativeSimctlOptions {
+  /** Defaults to `xcode-select -p` (the active Xcode's Developer dir). */
+  developerDir?: string;
+  /**
+   * Defaults to the default device set (`~/Library/Developer/CoreSimulator/Devices`), same as
+   * `simctl --set <path>`.
+   */
+  deviceSetPath?: string;
+  /**
+   * The versions of SpringBoard's notifications store (`sectionInfoVersionNumber`) the runtimes in
+   * use may have, the oldest first. Defaults to all the known ones; callers that know their Xcode
+   * narrow it. A store of any other version is refused.
+   */
+  bulletinBoardVersions?: readonly number[];
+}
+
 /**
  * Drives `CoreSimulator.framework` directly — no `simctl`/`xcrun` subprocess — for the operations
  * `node-simctl`'s `Simctl` class exposes over the CLI. Devices are addressed by UDID; each call
@@ -110,18 +126,28 @@ const require = createRequire(import.meta.url);
 export class NativeSimctl {
   private cachedServiceContext: Promise<NativeServiceContextHandle> | undefined;
 
+  /** @internal Read by the command mixins. */
+  readonly _options: Readonly<NativeSimctlOptions>;
+
   /**
-   * @param developerDir — defaults to `xcode-select -p` (the active Xcode's Developer dir).
-   * @param deviceSetPath — defaults to the default device set
-   * (`~/Library/Developer/CoreSimulator/Devices`), same as `simctl --set <path>`. Constructing a
-   * NativeSimctl must never throw — the platform check and the native sharedServiceContext call
-   * both happen lazily in the `_serviceContext` getter below, so only a method that actually needs
-   * the simulator (getDevices(), createDevice(), ...) can raise.
+   * Constructing a NativeSimctl must never throw — the platform check and the native
+   * sharedServiceContext call both happen lazily in the `_serviceContext` getter below, so only a
+   * method that actually needs the simulator (getDevices(), createDevice(), ...) can raise.
+   *
+   * @param options — see {@link NativeSimctlOptions}.
    */
-  constructor(
-    private readonly developerDir?: string,
-    private readonly deviceSetPath?: string,
-  ) {}
+  constructor(options?: NativeSimctlOptions);
+  /**
+   * @deprecated Pass {@link NativeSimctlOptions} instead.
+   * @param developerDir — see {@link NativeSimctlOptions.developerDir}.
+   * @param deviceSetPath — see {@link NativeSimctlOptions.deviceSetPath}.
+   */
+  constructor(developerDir?: string, deviceSetPath?: string);
+  constructor(optionsOrDeveloperDir?: NativeSimctlOptions | string, deviceSetPath?: string) {
+    this._options = util.isPlainObject(optionsOrDeveloperDir)
+      ? {...(optionsOrDeveloperDir as NativeSimctlOptions)}
+      : {developerDir: optionsOrDeveloperDir as string | undefined, deviceSetPath};
+  }
 
   /** @returns `CFBundleVersion` of the loaded `CoreSimulator.framework` (e.g. `"1171.6"`). */
   static async frameworkVersion(): Promise<string> {
@@ -143,7 +169,7 @@ export class NativeSimctl {
   async _serviceContext(): Promise<NativeServiceContextHandle> {
     if (!this.cachedServiceContext) {
       this.cachedServiceContext = runCatchingAsync(() =>
-        loadNative().sharedServiceContext(this.developerDir ?? defaultDeveloperDir()),
+        loadNative().sharedServiceContext(this._options.developerDir ?? defaultDeveloperDir()),
       ).catch((err: unknown) => {
         this.cachedServiceContext = undefined;
         throw err;
@@ -155,7 +181,7 @@ export class NativeSimctl {
   /** @internal Not part of the public API — exposed only so `src/commands/*.ts` mixins can call it. */
   async _deviceSet(): Promise<NativeDeviceSetHandle> {
     const context = await this._serviceContext();
-    const deviceSetPath = this.deviceSetPath;
+    const deviceSetPath = this._options.deviceSetPath;
     return runCatchingAsync(() =>
       deviceSetPath ? context.deviceSetWithPath(deviceSetPath) : context.defaultDeviceSet(),
     );

package/src/types.ts

@@ -87,9 +87,10 @@ export type SimPermissionStatus = 'unset' | 'denied' | 'granted' | 'limited';
 
 /**
  * A privacy permission grantable via `NativeSimctl.grantPermission`/`revokePermission`/
- * `resetPermission`. Each is backed by a row in the simulator's own TCC (privacy) database —
- * `location` isn't included since CoreLocation simulation has its own subsystem, not a plain TCC
- * row (see CLAUDE.md).
+ * `resetPermission`. Each except `notifications` is backed by a row in the simulator's own TCC
+ * (privacy) database — `location` isn't included since CoreLocation simulation has its own
+ * subsystem, not a plain TCC row (see CLAUDE.md). `notifications` is SpringBoard's own setting:
+ * changing it restarts SpringBoard, and its status can't be read back via `getPermission`.
  */
 export type SimPermissionService =
   | 'calendar'
@@ -101,6 +102,7 @@ export type SimPermissionService =
   | 'medialibrary'
   | 'microphone'
   | 'motion'
+  | 'notifications'
   | 'photos'
   | 'reminders'
   | 'siri'
@@ -424,6 +426,7 @@ export interface NativeDeviceHandle {
   deviceTypeIdentifier(): string;
   runtimeIdentifier(): string;
   runtimeRootPath(): string;
+  dataPath(): string;
   boot(options?: Record<string, unknown>): Promise<void>;
   getBootStatus(): Promise<SimBootInfo | null>;
   shutdown(): Promise<void>;

package/src/utils/bulletin-board-model-v2.ts

@@ -0,0 +1,79 @@
+import {plist} from '@appium/support';
+
+import type {BulletinBoardModel, NotificationsStatus} from './bulletin-board-model.js';
+
+/** The format used by SpringBoard since iOS 18. */
+export const bulletinBoardModelV2: BulletinBoardModel = {
+  version: 2,
+  createStore: () => ({sectionInfoVersionNumber: 2}),
+  setNotificationsStatus(store, bundleId, status) {
+    const sectionInfo = (store.sectionInfo ??= {});
+    if (status === 'unset') {
+      delete sectionInfo[bundleId];
+    } else {
+      sectionInfo[bundleId] = buildSectionInfo(bundleId, status);
+    }
+  },
+};
+
+/**
+ * Builds the NSKeyedArchiver-encoded `BBSectionInfo` of `bundleId`, the same archive
+ * AppleSimulatorUtils writes (SetNotificationsPermission.m). SpringBoard migrates its
+ * `allowsNotifications` flag to the current `authorizationStatus` when it loads the section.
+ */
+export function buildSectionInfo(
+  bundleId: string,
+  status: Exclude<NotificationsStatus, 'unset'>,
+  extraSectionKeys: Record<string, unknown> = {},
+): Buffer {
+  const nil = {UID: 0};
+  return plist.createBinaryPlist({
+    $version: 100000,
+    $objects: [
+      '$null',
+      {
+        suppressFromSettings: false,
+        suppressedSettings: 0,
+        hideWeeApp: false,
+        sectionID: {UID: 2},
+        displayName: {UID: 5},
+        icon: nil,
+        displaysCriticalBulletins: false,
+        subsections: nil,
+        sectionInfoSettings: {UID: 3},
+        $class: {UID: 7},
+        sectionCategory: 0,
+        subsectionPriority: 0,
+        version: {UID: 6},
+        managedSectionInfoSettings: nil,
+        appName: {UID: 5},
+        sectionType: 0,
+        factorySectionID: nil,
+        dataProviderIDs: nil,
+        subsectionID: nil,
+        filters: nil,
+        pathToWeeAppPluginBundle: nil,
+        ...extraSectionKeys,
+      },
+      bundleId,
+      {
+        pushSettings: 63,
+        showsInNotificationCenter: true,
+        allowsNotifications: status !== 'denied',
+        showsOnExternalDevices: true,
+        contentPreviewSetting: 0,
+        carPlaySetting: 0,
+        $class: {UID: 4},
+        showsInLockScreen: true,
+        alertType: 1,
+        criticalAlertSetting: status === 'critical' ? 2 : 0,
+      },
+      {$classname: 'BBSectionInfoSettings', $classes: ['BBSectionInfoSettings', 'NSObject']},
+      bundleId,
+      0,
+      {$classname: 'BBSectionInfo', $classes: ['BBSectionInfo', 'NSObject']},
+    ],
+    $archiver: 'NSKeyedArchiver',
+    $top: {root: {UID: 1}},
+  });
+}

package/src/utils/bulletin-board-model-v3.ts

@@ -0,0 +1,16 @@
+import {buildSectionInfo} from './bulletin-board-model-v2.js';
+import type {BulletinBoardModel} from './bulletin-board-model.js';
+
+/** The format used by SpringBoard since iOS 27: v2 with `isLocked` in the `BBSectionInfo`. */
+export const bulletinBoardModelV3: BulletinBoardModel = {
+  version: 3,
+  createStore: () => ({sectionInfoVersionNumber: 3}),
+  setNotificationsStatus(store, bundleId, status) {
+    const sectionInfo = (store.sectionInfo ??= {});
+    if (status === 'unset') {
+      delete sectionInfo[bundleId];
+    } else {
+      sectionInfo[bundleId] = buildSectionInfo(bundleId, status, {isLocked: false});
+    }
+  },
+};

package/src/utils/bulletin-board-model.ts

@@ -0,0 +1,20 @@
+export type NotificationsStatus = 'granted' | 'denied' | 'critical' | 'unset';
+
+/** Content of `VersionedSectionInfo.plist`. */
+export interface BulletinBoardStoreContent {
+  sectionInfoVersionNumber?: number;
+  sectionInfo?: Record<string, Uint8Array>;
+}
+
+/**
+ * The data model of one `sectionInfoVersionNumber` of the BulletinBoard store. The store operations
+ * (locking, atomic replace, ...) don't depend on it, so a new format version only needs a new model.
+ */
+export interface BulletinBoardModel {
+  /** The `sectionInfoVersionNumber` this model reads and writes. */
+  readonly version: number;
+  /** An empty store, as SpringBoard of this version would start it. */
+  createStore(): BulletinBoardStoreContent;
+  /** Adds, replaces or (`unset`) removes the app's notifications section in place. */
+  setNotificationsStatus(store: BulletinBoardStoreContent, bundleId: string, status: NotificationsStatus): void;
+}

package/src/utils/bulletin-board-store.ts

@@ -0,0 +1,126 @@
+import {execFile} from 'node:child_process';
+import {randomUUID} from 'node:crypto';
+import path from 'node:path';
+import {promisify} from 'node:util';
+
+import {fs, plist} from '@appium/support';
+
+import {bulletinBoardModelV2} from './bulletin-board-model-v2.js';
+import {bulletinBoardModelV3} from './bulletin-board-model-v3.js';
+import type {BulletinBoardModel, BulletinBoardStoreContent, NotificationsStatus} from './bulletin-board-model.js';
+
+const execFileAsync = promisify(execFile);
+
+// All the known data models, the oldest first.
+const KNOWN_MODELS: readonly BulletinBoardModel[] = [bulletinBoardModelV2, bulletinBoardModelV3];
+
+// The last pending update of each store, see BulletinBoardStore.withLock.
+const pendingUpdates = new Map<string, Promise<void>>();
+
+/**
+ * SpringBoard's BulletinBoard store of a device (`Library/BulletinBoard/VersionedSectionInfo.plist`),
+ * which keeps the notifications settings of every app as one archived `BBSectionInfo` per bundle id.
+ */
+export class BulletinBoardStore {
+  readonly path: string;
+  private readonly models: readonly BulletinBoardModel[];
+
+  /**
+   * @param dataPath — data directory of the device
+   * @param versions — the `sectionInfoVersionNumber`s supported by the runtime, the oldest first
+   * (all the known ones by default). A store of any other version is refused, as the format may
+   * change in a future runtime. A missing store (a never-booted device) is created in the first
+   * one, as SpringBoard migrates older versions but not newer ones.
+   * @throws {Error} if a version is unknown
+   */
+  constructor(dataPath: string, versions: readonly number[] = KNOWN_MODELS.map(({version}) => version)) {
+    this.models = versions.map((version) => {
+      const model = KNOWN_MODELS.find((m) => m.version === version);
+      if (!model) {
+        throw new Error(`Unknown BulletinBoard store version ${version}`);
+      }
+      return model;
+    });
+    this.path = path.join(dataPath, 'Library', 'BulletinBoard', 'VersionedSectionInfo.plist');
+  }
+
+  /**
+   * Runs `update` once every earlier update of the same store has settled: concurrent updates for
+   * different apps would otherwise read the same store, and the last write would drop the other app's
+   * section. Only the calls made by this process are serialized.
+   */
+  async withLock<T>(update: () => Promise<T>): Promise<T> {
+    const result = (pendingUpdates.get(this.path) ?? Promise.resolve()).then(update);
+    const settled = result.then(
+      () => {},
+      () => {},
+    );
+    pendingUpdates.set(this.path, settled);
+    try {
+      return await result;
+    } finally {
+      if (pendingUpdates.get(this.path) === settled) {
+        pendingUpdates.delete(this.path);
+      }
+    }
+  }
+
+  /**
+   * Adds, replaces or (`unset`) removes the app's section. The store is replaced atomically, so a
+   * failed write leaves the previous one intact. A device that has never been booted has no store
+   * yet: it is created with just this section, and SpringBoard adds the rest on boot.
+   *
+   * @returns `false` if there was nothing to write (`unset` without a store)
+   * @throws {Error} if the existing store is of an unsupported format version
+   */
+  async setNotificationsStatus(bundleId: string, status: NotificationsStatus): Promise<boolean> {
+    let store: BulletinBoardStoreContent;
+    let model: BulletinBoardModel;
+    if (await fs.exists(this.path)) {
+      store = (await plist.parsePlistFile(this.path)) as BulletinBoardStoreContent;
+      model = this.modelOf(store);
+    } else if (status === 'unset') {
+      return false;
+    } else {
+      await fs.mkdir(path.dirname(this.path), {recursive: true});
+      model = this.models[0];
+      store = model.createStore();
+    }
+    model.setNotificationsStatus(store, bundleId, status);
+    await this.replace(store);
+    return true;
+  }
+
+  /**
+   * Makes the store immutable (`uchg`) so that nothing, including a dying SpringBoard, can rewrite it.
+   * Best effort.
+   */
+  async setImmutable(immutable: boolean): Promise<void> {
+    try {
+      await execFileAsync('chflags', [immutable ? 'uchg' : 'nouchg', this.path]);
+    } catch {}
+  }
+
+  private modelOf(store: BulletinBoardStoreContent): BulletinBoardModel {
+    const model = this.models.find(({version}) => version === store.sectionInfoVersionNumber);
+    if (!model) {
+      throw new Error(
+        `Unsupported version of ${this.path}: sectionInfoVersionNumber is ${store.sectionInfoVersionNumber}, ` +
+          `supported: ${this.models.map(({version}) => version).join(', ')}`,
+      );
+    }
+    return model;
+  }
+
+  private async replace(store: BulletinBoardStoreContent): Promise<void> {
+    // In the same directory, so that the rename is atomic.
+    const tmpPath = `${this.path}.${randomUUID()}.tmp`;
+    try {
+      await fs.writeFile(tmpPath, plist.createPlist(store, false), {flag: 'wx'});
+      await fs.rename(tmpPath, this.path);
+    } catch (err) {
+      await fs.unlink(tmpPath).catch(() => {});
+      throw err;
+    }
+  }
+}

package/src/utils/index.ts

@@ -1,3 +1,6 @@
 export {getPkgRoot, PACKAGE_NAME} from './pkg-root.js';
 export {runCatchingAsync, toTypedError} from './run-catching.js';
 export {resolveDisplayPortId, validateDisplayId} from './display.js';
+export {BulletinBoardStore} from './bulletin-board-store.js';
+export type {NotificationsStatus} from './bulletin-board-model.js';
+export {SpringBoard} from './springboard.js';

package/src/utils/springboard.ts

@@ -0,0 +1,119 @@
+import {once} from 'node:events';
+
+import {waitForCondition} from 'asyncbox';
+
+import type {NativeSimctl} from '../native-simctl.js';
+
+const SPRINGBOARD_SERVICE = 'com.apple.SpringBoard';
+const SPRINGBOARD_RESTART_TIMEOUT_MS = 30000;
+
+/**
+ * SpringBoard of a booted device: the process that owns the BulletinBoard store, see
+ * setNotificationsAccess. The simulator shares the host kernel, so it is signalled directly.
+ */
+export class SpringBoard {
+  private pausedPid: number | undefined;
+
+  constructor(
+    private readonly simctl: NativeSimctl,
+    private readonly udid: string,
+  ) {}
+
+  /**
+   * Pauses the running SpringBoard so that it cannot rewrite the BulletinBoard store. It can be in
+   * the middle of a restart, hence the retries.
+   */
+  async pause(): Promise<void> {
+    try {
+      await waitForCondition(
+        async () => {
+          const pid = await this.pid().catch(() => undefined);
+          if (pid && sendSignal(pid, 'SIGSTOP')) {
+            this.pausedPid = pid;
+          }
+          return Boolean(this.pausedPid);
+        },
+        {waitMs: SPRINGBOARD_RESTART_TIMEOUT_MS, intervalMs: 300},
+      );
+    } catch {}
+    if (!this.pausedPid) {
+      throw new Error(`${SPRINGBOARD_SERVICE} is not running`);
+    }
+  }
+
+  /** Lets the paused SpringBoard run again. */
+  resume(): void {
+    if (this.pausedPid) {
+      sendSignal(this.pausedPid, 'SIGCONT');
+    }
+  }
+
+  /**
+   * Replaces the paused SpringBoard with a new one: asks launchd to stop it (launchd starts a new
+   * one right away), resumes it so that it can exit, then waits for the new process.
+   */
+  async restart(): Promise<void> {
+    const previousPid = this.pausedPid;
+    try {
+      await this.stop();
+    } finally {
+      this.resume();
+      this.pausedPid = undefined;
+    }
+    try {
+      await waitForCondition(
+        async () => {
+          const pid = await this.pid().catch(() => undefined);
+          return Number.isInteger(pid) && pid !== previousPid;
+        },
+        {waitMs: SPRINGBOARD_RESTART_TIMEOUT_MS, intervalMs: 300},
+      );
+    } catch {
+      throw new Error(`${SPRINGBOARD_SERVICE} did not restart within ${SPRINGBOARD_RESTART_TIMEOUT_MS}ms`);
+    }
+  }
+
+  private async pid(): Promise<number | undefined> {
+    return (await this.simctl.listProcesses(this.udid)).find(({name}) => name === SPRINGBOARD_SERVICE)?.pid;
+  }
+
+  private async stop(): Promise<void> {
+    // Bare name: resolved against the guest runtime's own bin dirs, like in listProcesses.
+    const proc = await this.simctl.spawnProcess(this.udid, 'launchctl', {
+      arguments: ['launchctl', 'stop', SPRINGBOARD_SERVICE],
+    });
+    let stderr = '';
+    proc.stdout.resume();
+    proc.stderr.on('data', (chunk: Buffer) => {
+      stderr += chunk;
+    });
+    const streamError = Promise.race([once(proc.stdout, 'error'), once(proc.stderr, 'error')]).then(([err]) => {
+      throw err;
+    });
+    const [[code, signal]] = await Promise.race([
+      Promise.all([once(proc, 'exit'), once(proc.stderr, 'end')]),
+      streamError,
+    ]);
+    if (code !== 0) {
+      const reason = signal ? `signal ${signal}` : `exit code ${code}`;
+      throw new Error(
+        `'launchctl stop ${SPRINGBOARD_SERVICE}' failed with ${reason}${stderr.trim() ? `: ${stderr.trim()}` : ''}`,
+      );
+    }
+  }
+}
+
+/**
+ * @returns `false` if the process no longer exists
+ */
+function sendSignal(pid: number, name: NodeJS.Signals): boolean {
+  try {
+    process.kill(pid, name);
+    return true;
+  } catch (err: any) {
+    if (err?.code === 'ESRCH') {
+      return false;
+    }
+    throw err;
+  }
+}