@appium/coresim 1.0.0

package/src/native/value_bridge.mm

@@ -0,0 +1,111 @@
+#include "value_bridge.h"
+
+#include <string>
+
+namespace coresim {
+
+namespace {
+
+// A plain `.c_str()`/`UTF8String` round trip truncates at the first embedded NUL byte, since both
+// treat the buffer as a null-terminated C string — but a JS string (and an NSString) can validly
+// contain U+0000 mid-string. Converting via the actual byte length on both sides preserves it.
+NSString* ToNSString(const std::string& utf8) {
+  return [[NSString alloc] initWithBytes:utf8.data() length:utf8.size() encoding:NSUTF8StringEncoding];
+}
+
+std::string ToStdString(NSString* str) {
+  return std::string(str.UTF8String, [str lengthOfBytesUsingEncoding:NSUTF8StringEncoding]);
+}
+
+}  // namespace
+
+NSObject* JsValueToNSObject(Napi::Env env, Napi::Value value) {
+  if (value.IsNull() || value.IsUndefined()) {
+    return [NSNull null];
+  }
+  if (value.IsBoolean()) {
+    return @(value.As<Napi::Boolean>().Value());
+  }
+  if (value.IsNumber()) {
+    return @(value.As<Napi::Number>().DoubleValue());
+  }
+  if (value.IsString()) {
+    return ToNSString(value.As<Napi::String>().Utf8Value());
+  }
+  if (value.IsBuffer()) {
+    auto buffer = value.As<Napi::Buffer<uint8_t>>();
+    return [NSData dataWithBytes:buffer.Data() length:buffer.Length()];
+  }
+  if (value.IsArray()) {
+    auto array = value.As<Napi::Array>();
+    NSMutableArray* result = [NSMutableArray arrayWithCapacity:array.Length()];
+    for (uint32_t i = 0; i < array.Length(); i++) {
+      [result addObject:JsValueToNSObject(env, array.Get(i))];
+    }
+    return result;
+  }
+  if (value.IsObject()) {
+    auto object = value.As<Napi::Object>();
+    Napi::Array keys = object.GetPropertyNames();
+    NSMutableDictionary* result = [NSMutableDictionary dictionaryWithCapacity:keys.Length()];
+    for (uint32_t i = 0; i < keys.Length(); i++) {
+      Napi::Value key = keys.Get(i);
+      NSString* nsKey = ToNSString(key.As<Napi::String>().Utf8Value());
+      result[nsKey] = JsValueToNSObject(env, object.Get(key));
+    }
+    return result;
+  }
+  return [NSNull null];
+}
+
+Napi::Value NSObjectToJsValue(Napi::Env env, id object) {
+  if (object == nil || object == [NSNull null]) {
+    return env.Null();
+  }
+  if ([object isKindOfClass:[NSString class]]) {
+    return Napi::String::New(env, ToStdString((NSString*)object));
+  }
+  if ([object isKindOfClass:[NSNumber class]]) {
+    NSNumber* number = (NSNumber*)object;
+    if (strcmp(number.objCType, @encode(BOOL)) == 0 || strcmp(number.objCType, @encode(char)) == 0) {
+      return Napi::Boolean::New(env, number.boolValue);
+    }
+    return Napi::Number::New(env, number.doubleValue);
+  }
+  if ([object isKindOfClass:[NSArray class]]) {
+    NSArray* array = (NSArray*)object;
+    Napi::Array result = Napi::Array::New(env, array.count);
+    for (NSUInteger i = 0; i < array.count; i++) {
+      result[static_cast<uint32_t>(i)] = NSObjectToJsValue(env, array[i]);
+    }
+    return result;
+  }
+  if ([object isKindOfClass:[NSDictionary class]]) {
+    NSDictionary* dict = (NSDictionary*)object;
+    Napi::Object result = Napi::Object::New(env);
+    for (NSString* key in dict) {
+      // Napi::Object::Set's named-property overloads forward to napi_set_named_property, which
+      // (per the underlying N-API C function's own signature) only ever accepts a null-terminated
+      // C string for the key — there's no byte-length variant, so an embedded-NUL key can't go
+      // through that path no matter what we do here. Building the key as a proper Napi::String
+      // first and setting it via the napi_value-keyed overload (napi_set_property) sidesteps that
+      // limitation entirely.
+      Napi::String jsKey = Napi::String::New(env, ToStdString(key));
+      result.Set(jsKey, NSObjectToJsValue(env, dict[key]));
+    }
+    return result;
+  }
+  if ([object isKindOfClass:[NSURL class]]) {
+    return Napi::String::New(env, ToStdString([(NSURL*)object absoluteString]));
+  }
+  if ([object isKindOfClass:[NSUUID class]]) {
+    return Napi::String::New(env, ToStdString([(NSUUID*)object UUIDString]));
+  }
+  if ([object isKindOfClass:[NSData class]]) {
+    NSData* data = (NSData*)object;
+    return Napi::Buffer<uint8_t>::Copy(env, static_cast<const uint8_t*>(data.bytes), data.length);
+  }
+  return Napi::String::New(env, ToStdString([object description]));
+}
+
+}  // namespace coresim

package/src/native-simctl.ts

@@ -0,0 +1,288 @@
+import {execFileSync} from 'node:child_process';
+import {createRequire} from 'node:module';
+
+import {util} from '@appium/support';
+
+import {
+  appInfo,
+  getAppContainer,
+  installApp,
+  installedApps,
+  isAppInstalled,
+  launchApp,
+  removeApp,
+  terminateApp,
+} from './commands/app.js';
+import {enrollBiometric, isBiometricEnrolled, sendBiometricMatch} from './commands/biometric.js';
+import {
+  getDarwinNotificationState,
+  postDarwinNotification,
+  setDarwinNotificationState,
+} from './commands/darwin-notification.js';
+import {clearLocation, getEnv, openUrl, pushNotification, setLocation} from './commands/interaction.js';
+import {addCertificate, addRootCertificate, resetKeychain} from './commands/keychain.js';
+import {
+  bootDevice,
+  createDevice,
+  deleteDevice,
+  eraseDevice,
+  getBootStatus,
+  getDevices,
+  getSupportedDeviceTypes,
+  getSupportedRuntimes,
+  shutdownAllDevices,
+  shutdownDevice,
+  waitForBoot,
+} from './commands/lifecycle.js';
+import {addMedia, addPhoto, addVideo} from './commands/media.js';
+import {shake} from './commands/misc.js';
+import {getPasteboard, setPasteboard} from './commands/pasteboard.js';
+import {getPermission, grantPermission, resetPermission, revokePermission} from './commands/permissions.js';
+import {listProcesses} from './commands/process.js';
+import {getDisplays, getScreenshot} from './commands/screenshot.js';
+import {spawnProcess} from './commands/spawn.js';
+import {
+  getAppearance,
+  getContentSize,
+  getIncreaseContrast,
+  setAppearance,
+  setContentSize,
+  setIncreaseContrast,
+} from './commands/ui.js';
+import {getWebInspectorSocket} from './commands/webinspector.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
+// surface, so `tsc` would otherwise drop them from the declaration output.
+import './commands/app.js';
+import './commands/biometric.js';
+import './commands/darwin-notification.js';
+import './commands/interaction.js';
+import './commands/keychain.js';
+import './commands/lifecycle.js';
+import './commands/media.js';
+import './commands/misc.js';
+import './commands/pasteboard.js';
+import './commands/permissions.js';
+import './commands/process.js';
+import './commands/screenshot.js';
+import './commands/spawn.js';
+import './commands/ui.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);
+
+/**
+ * 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
+ * re-resolves the native handle from the live device set, so a device deleted by another process
+ * surfaces as a normal "not found" error rather than stale state.
+ *
+ * Every method that can trigger a CoreSimulator dispatch is `async`: the native layer runs the
+ * underlying call on a libuv threadpool thread (see coresim.mm/async_bridge.h), so a slow
+ * install/erase/create/etc. never blocks Node's event loop.
+ *
+ * The public command surface (everything except the constructor, `frameworkVersion`, and the
+ * `_`-prefixed internal helpers below) lives in `src/commands/*.ts`, grouped by topic and mixed
+ * into this class via `Object.assign(NativeSimctl.prototype, ...)` at the bottom of this file —
+ * mirroring how `@appium/base-driver`'s `BaseDriver` composes its own command surface from
+ * `basedriver/commands/*.ts`. Each command module also declares a `declare module
+ * './native-simctl.js'` augmentation so `NativeSimctl`'s emitted type includes methods it doesn't
+ * textually define.
+ */
+export class NativeSimctl {
+  private cachedServiceContext: Promise<NativeServiceContextHandle> | undefined;
+
+  /**
+   * @param developerDir — defaults to `xcode-select -p` (the active Xcode's Developer dir).
+   * 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.
+   */
+  constructor(private readonly developerDir?: string) {}
+
+  /** @returns `CFBundleVersion` of the loaded `CoreSimulator.framework` (e.g. `"1171.6"`). */
+  static async frameworkVersion(): Promise<string> {
+    return runCatchingAsync(() => loadNative().frameworkVersion());
+  }
+
+  /**
+   * @internal Not part of the public API — exposed (not `private`) only so `src/commands/*.ts`
+   * mixins can call it. Resolves and memoizes the native `SimServiceContext` on first access —
+   * never in the constructor. `loadNative()` must run (and throw its typed platform error) before
+   * `defaultDeveloperDir()` ever shells out to `xcode-select`, which doesn't exist off macOS — so
+   * the fallback is resolved as an argument to the native call, not eagerly, preserving that
+   * evaluation order. Caching the in-flight promise (not just its resolved value) means concurrent
+   * callers before the first resolution still only trigger one `sharedServiceContext` call. On
+   * rejection the cache is cleared again — a Promise is truthy even once rejected, so leaving a
+   * failed one cached would otherwise make every later call reuse that same stale rejection
+   * forever instead of retrying once the underlying condition clears.
+   */
+  async _serviceContext(): Promise<NativeServiceContextHandle> {
+    if (!this.cachedServiceContext) {
+      this.cachedServiceContext = runCatchingAsync(() =>
+        loadNative().sharedServiceContext(this.developerDir ?? defaultDeveloperDir()),
+      ).catch((err: unknown) => {
+        this.cachedServiceContext = undefined;
+        throw err;
+      });
+    }
+    return this.cachedServiceContext;
+  }
+
+  /** @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();
+    return runCatchingAsync(() => context.defaultDeviceSet());
+  }
+
+  /** @internal Not part of the public API — exposed only so `src/commands/*.ts` mixins can call it. */
+  async _findDevice(udid: string): Promise<NativeDeviceHandle> {
+    return runCatchingAsync(async () => {
+      const deviceSet = await this._deviceSet();
+      const device = (await deviceSet.devices()).find((candidate) => candidate.udid() === udid);
+      if (!device) {
+        throw new Error(`No simulator device found with udid '${udid}'`);
+      }
+      return device;
+    });
+  }
+}
+
+Object.assign(NativeSimctl.prototype, {
+  // lifecycle
+  getDevices,
+  getSupportedDeviceTypes,
+  getSupportedRuntimes,
+  createDevice,
+  deleteDevice,
+  bootDevice,
+  getBootStatus,
+  waitForBoot,
+  shutdownDevice,
+  shutdownAllDevices,
+  eraseDevice,
+
+  // app
+  installApp,
+  removeApp,
+  launchApp,
+  terminateApp,
+  isAppInstalled,
+  appInfo,
+  installedApps,
+  getAppContainer,
+
+  // media
+  addMedia,
+  addPhoto,
+  addVideo,
+
+  // biometric
+  isBiometricEnrolled,
+  enrollBiometric,
+  sendBiometricMatch,
+
+  // misc
+  shake,
+
+  // interaction
+  getEnv,
+  openUrl,
+  setLocation,
+  clearLocation,
+  pushNotification,
+
+  // keychain
+  addCertificate,
+  addRootCertificate,
+  resetKeychain,
+
+  // ui
+  getAppearance,
+  setAppearance,
+  getIncreaseContrast,
+  setIncreaseContrast,
+  getContentSize,
+  setContentSize,
+
+  // permissions
+  grantPermission,
+  revokePermission,
+  resetPermission,
+  getPermission,
+
+  // process
+  listProcesses,
+
+  // darwin notification
+  getDarwinNotificationState,
+  setDarwinNotificationState,
+  postDarwinNotification,
+
+  // pasteboard
+  getPasteboard,
+  setPasteboard,
+
+  // screenshot
+  getScreenshot,
+  getDisplays,
+
+  // webinspector
+  getWebInspectorSocket,
+
+  // spawn
+  spawnProcess,
+});
+
+// Loaded lazily (not at module import time) so merely depending on/importing @appium/coresim —
+// e.g. for its error classes or types — works on any platform; only actually using it (booting a
+// simulator, etc.) requires macOS, where CoreSimulator.framework exists. `npm install` never
+// attempts to build the addon on other platforms either (see scripts/install.mjs). Any macOS arch
+// works — node-gyp-build falls back to compiling from source on an arch with no matching
+// prebuild (e.g. an Intel Mac, since only darwin-arm64 is prebuilt today). util.memoize only
+// caches a normal return, never a throw (see @appium/support's util.js), so the platform check
+// below re-runs — and re-throws — on every call until it actually succeeds once.
+const loadNative = util.memoize(function loadNative(): NativeCoreSimModule {
+  if (process.platform !== 'darwin') {
+    throw new NativeSimUnavailableError(
+      `${PACKAGE_NAME} requires macOS — CoreSimulator.framework does not exist on ${process.platform}`,
+      'platform',
+      process.platform,
+      'n/a',
+    );
+  }
+  return require('node-gyp-build')(getPkgRoot()) as NativeCoreSimModule;
+});
+
+const DEFAULT_DEVELOPER_DIR_TIMEOUT_MS = 15_000;
+
+function defaultDeveloperDir(): string {
+  try {
+    return execFileSync('xcode-select', ['-p'], {
+      encoding: 'utf8',
+      timeout: DEFAULT_DEVELOPER_DIR_TIMEOUT_MS,
+    }).trim();
+  } catch (err) {
+    // A non-zero exit (e.g. CLT installed but no Xcode selected) already carries a clear stderr
+    // message from xcode-select itself; only ENOENT (the binary isn't on PATH at all) and
+    // ETIMEDOUT need a friendlier message than Node's raw "spawnSync xcode-select ENOENT/ETIMEDOUT".
+    if ((err as NodeJS.ErrnoException)?.code === 'ENOENT') {
+      throw new Error('xcode-select not found on PATH — install Xcode or the Xcode Command Line Tools', {
+        cause: err,
+      });
+    }
+    if ((err as NodeJS.ErrnoException)?.code === 'ETIMEDOUT') {
+      throw new Error(`xcode-select -p did not respond within ${DEFAULT_DEVELOPER_DIR_TIMEOUT_MS}ms`, {cause: err});
+    }
+    throw err;
+  }
+}