@appium/coresim 1.0.0

package/src/errors.ts

@@ -0,0 +1,93 @@
+/** Base error for every failure raised by the native CoreSimulator addon. */
+export class NativeSimError extends Error {
+  public override name = 'NativeSimError';
+
+  constructor(message: string) {
+    super(message);
+  }
+}
+
+/**
+ * The class/selector a call needed doesn't exist on the currently loaded CoreSimulator.framework,
+ * or a dynamic dispatch raised an NSException that got caught instead of crashing the process.
+ * Distinct from {@link NativeSimOperationError}: this means "not supported on this simulator
+ * runtime", not "the call ran and Apple's own code rejected it".
+ */
+export class NativeSimUnavailableError extends NativeSimError {
+  public override name = 'NativeSimUnavailableError';
+
+  /**
+   * @param message — human-readable description
+   * @param kind — `'class'` | `'selector'` | `'framework'`
+   * @param missing — the missing class/selector/framework name
+   * @param frameworkVersion — `CFBundleVersion` of the loaded CoreSimulator.framework
+   */
+  constructor(
+    message: string,
+    public readonly kind: string,
+    public readonly missing: string,
+    public readonly frameworkVersion: string,
+  ) {
+    super(message);
+  }
+}
+
+/** A dynamic dispatch raised an NSException that was caught rather than crashing the process. */
+export class NativeSimDispatchError extends NativeSimError {
+  public override name = 'NativeSimDispatchError';
+
+  /**
+   * @param message — human-readable description
+   * @param exceptionName — the caught `NSException`'s `name`
+   * @param reason — the caught `NSException`'s `reason`
+   */
+  constructor(
+    message: string,
+    public readonly exceptionName: string,
+    public readonly reason: string,
+  ) {
+    super(message);
+  }
+}
+
+/** The call reached CoreSimulator and Apple's own code rejected it (a structured `NSError`). */
+export class NativeSimOperationError extends NativeSimError {
+  public override name = 'NativeSimOperationError';
+
+  /**
+   * @param message — `NSError.localizedDescription`
+   * @param domain — `NSError.domain`
+   * @param code — `NSError.code`
+   */
+  constructor(
+    message: string,
+    public readonly domain: string,
+    public readonly code: number,
+  ) {
+    super(message);
+  }
+}
+
+/** Re-throws a raw error surfaced by the native addon as the matching typed {@link NativeSimError}. */
+export function wrapNativeError(err: unknown): never {
+  if (err instanceof NativeSimError) {
+    throw err;
+  }
+  const error = err as Error & Record<string, unknown>;
+  const message = error?.message ?? String(err);
+  switch (error?.name) {
+    case 'NativeSimUnavailableError':
+      throw new NativeSimUnavailableError(
+        message,
+        String(error.kind ?? ''),
+        String(error.missing ?? ''),
+        String(error.frameworkVersion ?? ''),
+      );
+    case 'NativeSimDispatchError':
+      throw new NativeSimDispatchError(message, String(error.exceptionName ?? ''), String(error.reason ?? ''));
+    case 'NativeSimOperationError':
+      throw new NativeSimOperationError(message, String(error.domain ?? ''), Number(error.code ?? 0));
+    default:
+      throw new NativeSimError(message);
+  }
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+export {NativeSimError, NativeSimUnavailableError, NativeSimDispatchError, NativeSimOperationError} from './errors.js';
+export {NativeSimctl} from './native-simctl.js';
+export {SpawnedProcess} from './commands/spawn.js';
+export type {AppContainerType} from './commands/app.js';
+export type {BiometricName} from './commands/biometric.js';
+export {
+  SimBootStatus,
+  SimDeviceState,
+  type ApnsAlert,
+  type ApnsPayload,
+  type ApnsSound,
+  type PushNotificationPayload,
+  type ScreenshotOptions,
+  type SimBootInfo,
+  type SimDeviceInfo,
+  type SimDeviceTypeInfo,
+  type SimDisplayInfo,
+  type SimPermissionService,
+  type SimPermissionStatus,
+  type SimProcessInfo,
+  type SimRuntimeInfo,
+  type SpawnOptions,
+} from './types.js';

package/src/native/async_bridge.h

@@ -0,0 +1,164 @@
+#pragma once
+
+#include <napi.h>
+
+#include <functional>
+#include <memory>
+
+#include "nserror_bridge.h"
+#include "objc_runtime.h"
+#include "safe_dispatch.h"
+
+namespace coresim {
+
+// Runs `work` on a libuv threadpool thread (Napi::AsyncWorker::Execute) and resolves/rejects the
+// returned Promise from its result, converting it to a JS value via `toValue` — which, like every
+// other Napi call, must run on the main thread, hence OnOK rather than Execute. This is what
+// keeps Node's event loop responsive regardless of whether the underlying CoreSimulator call is
+// itself async (has a completion-block variant) or a plain blocking objc_msgSend: either way, the
+// blocking happens off the main thread.
+//
+// `T` must be safe to hold as a plain default-constructed class member with no ARC-ownership
+// wrapper needed beyond what the type already provides on its own — plain C++ types (bool, int,
+// long long, std::string) work as expected; `id`/`NSString*`/`NSArray*`/`NSDictionary*`/... also
+// work here because this header is only ever included from an Objective-C++ (.mm) translation
+// unit compiled with ARC, where a bare ObjC-pointer-typed class member already gets correct
+// retain/release semantics, same as every other such member in this addon (e.g. NativeDevice's
+// `device_`). `toValue` runs in OnOK (main thread), so it's the right — and only safe — place to
+// do any Napi-consuming conversion (NSObjectToJsValue, building a NativeDevice, ...), even though
+// the raw ObjC object it receives was produced by `work` on a background thread. `toValue` takes
+// `T` by value, not `T&`: for an ObjC pointer T, a reference parameter's ARC ownership qualifier
+// (implicitly `__strong`) has to match the callable's declared parameter type exactly, which a
+// plain `NSString*&`-style lambda parameter doesn't — by-value sidesteps that entirely, and every
+// T here (primitives, std::string, ObjC pointers) is cheap to copy/retain anyway.
+template <typename T>
+class ValueAsyncWorker : public Napi::AsyncWorker {
+ public:
+  ValueAsyncWorker(Napi::Env env, std::function<T()> work, std::function<Napi::Value(Napi::Env, T)> toValue)
+      : Napi::AsyncWorker(env),
+        work_(std::move(work)),
+        toValue_(std::move(toValue)),
+        deferred_(Napi::Promise::Deferred::New(env)) {}
+
+  Napi::Promise GetPromise() { return deferred_.Promise(); }
+
+  void Execute() override {
+    // libuv threadpool threads are persistent and reused across many Execute() calls, with no
+    // implicit per-iteration autorelease pool the way the main thread gets from a run loop —
+    // without one here, every autoreleased Foundation temporary `work_`/its callees produce (e.g.
+    // -stringWithFormat:, -pipe) would sit until the thread itself exits, growing without bound.
+    // `result_`/the caught exceptions below are real (retained) members, not autoreleased
+    // temporaries, so assigning into them before the pool drains keeps them alive regardless.
+    @autoreleasepool {
+      try {
+        result_ = work_();
+      } catch (const NativeSimUnavailableError& error) {
+        unavailable_ = std::make_unique<NativeSimUnavailableError>(error);
+      } catch (const NSErrorException& error) {
+        nsError_ = std::make_unique<NSErrorException>(error);
+      } catch (const ObjCException& error) {
+        objcException_ = std::make_unique<ObjCException>(error);
+      } catch (const std::exception& error) {
+        SetError(error.what());
+      }
+    }
+  }
+
+  void OnOK() override {
+    Napi::Env env = Env();
+    Napi::HandleScope scope(env);
+    if (unavailable_) {
+      deferred_.Reject(UnavailableToJsError(env, *unavailable_).Value());
+    } else if (nsError_) {
+      deferred_.Reject(NSErrorExceptionToJsError(env, *nsError_).Value());
+    } else if (objcException_) {
+      deferred_.Reject(ObjCExceptionToJsError(env, *objcException_).Value());
+    } else {
+      deferred_.Resolve(toValue_(env, result_));
+    }
+  }
+
+  void OnError(const Napi::Error& error) override {
+    Napi::HandleScope scope(Env());
+    deferred_.Reject(error.Value());
+  }
+
+ private:
+  std::function<T()> work_;
+  std::function<Napi::Value(Napi::Env, T)> toValue_;
+  T result_{};
+  std::unique_ptr<NativeSimUnavailableError> unavailable_;
+  std::unique_ptr<NSErrorException> nsError_;
+  std::unique_ptr<ObjCException> objcException_;
+  Napi::Promise::Deferred deferred_;
+};
+
+// Same as ValueAsyncWorker but for work with no result to convert — resolves with undefined.
+class VoidAsyncWorker : public Napi::AsyncWorker {
+ public:
+  VoidAsyncWorker(Napi::Env env, std::function<void()> work)
+      : Napi::AsyncWorker(env), work_(std::move(work)), deferred_(Napi::Promise::Deferred::New(env)) {}
+
+  Napi::Promise GetPromise() { return deferred_.Promise(); }
+
+  void Execute() override {
+    // See ValueAsyncWorker::Execute() above for why this pool is needed on a reused threadpool
+    // thread.
+    @autoreleasepool {
+      try {
+        work_();
+      } catch (const NativeSimUnavailableError& error) {
+        unavailable_ = std::make_unique<NativeSimUnavailableError>(error);
+      } catch (const NSErrorException& error) {
+        nsError_ = std::make_unique<NSErrorException>(error);
+      } catch (const ObjCException& error) {
+        objcException_ = std::make_unique<ObjCException>(error);
+      } catch (const std::exception& error) {
+        SetError(error.what());
+      }
+    }
+  }
+
+  void OnOK() override {
+    Napi::Env env = Env();
+    Napi::HandleScope scope(env);
+    if (unavailable_) {
+      deferred_.Reject(UnavailableToJsError(env, *unavailable_).Value());
+    } else if (nsError_) {
+      deferred_.Reject(NSErrorExceptionToJsError(env, *nsError_).Value());
+    } else if (objcException_) {
+      deferred_.Reject(ObjCExceptionToJsError(env, *objcException_).Value());
+    } else {
+      deferred_.Resolve(env.Undefined());
+    }
+  }
+
+  void OnError(const Napi::Error& error) override {
+    Napi::HandleScope scope(Env());
+    deferred_.Reject(error.Value());
+  }
+
+ private:
+  std::function<void()> work_;
+  std::unique_ptr<NativeSimUnavailableError> unavailable_;
+  std::unique_ptr<NSErrorException> nsError_;
+  std::unique_ptr<ObjCException> objcException_;
+  Napi::Promise::Deferred deferred_;
+};
+
+template <typename T>
+Napi::Promise RunAsync(Napi::Env env, std::function<T()> work, std::function<Napi::Value(Napi::Env, T)> toValue) {
+  auto* worker = new ValueAsyncWorker<T>(env, std::move(work), std::move(toValue));
+  Napi::Promise promise = worker->GetPromise();
+  worker->Queue();
+  return promise;
+}
+
+inline Napi::Promise RunAsyncVoid(Napi::Env env, std::function<void()> work) {
+  auto* worker = new VoidAsyncWorker(env, std::move(work));
+  Napi::Promise promise = worker->GetPromise();
+  worker->Queue();
+  return promise;
+}
+
+}  // namespace coresim

package/src/native/nserror_bridge.h

@@ -0,0 +1,64 @@
+#pragma once
+
+#import <Foundation/Foundation.h>
+
+#include <napi.h>
+
+#include <string>
+
+#include "objc_runtime.h"
+#include "safe_dispatch.h"
+
+namespace coresim {
+
+// Thrown by async work lambdas (see async_bridge.h) when a native call fails via an NSError**
+// out-param rather than raising. domain/code/message are captured immediately at throw time
+// (never the NSError* itself), since this only ever needs to survive within the same background
+// thread's try/catch — it's never constructed on, or crossed onto, the main thread.
+class NSErrorException : public std::runtime_error {
+ public:
+  explicit NSErrorException(NSError* error)
+      : std::runtime_error(error.localizedDescription ? error.localizedDescription.UTF8String : "Operation failed"),
+        domain(error.domain ? error.domain.UTF8String : ""),
+        code(error.code) {}
+
+  std::string domain;
+  long long code;
+};
+
+// Converts an NSError into a JS Error with {name: 'NativeSimOperationError', domain, code,
+// message} — errors.ts wraps this into NativeSimError. Built from an already-caught
+// NSErrorException's extracted fields, never a live NSError*: this only ever runs in OnOK (main
+// thread), after the exception already crossed out of the background thread's try/catch.
+Napi::Error NSErrorExceptionToJsError(Napi::Env env, const NSErrorException& error);
+
+// {name: 'NativeSimUnavailableError', kind, missing, frameworkVersion} — errors.ts wraps this
+// into NativeSimUnavailableError.
+Napi::Error UnavailableToJsError(Napi::Env env, const NativeSimUnavailableError& error);
+
+// {name: 'NativeSimDispatchError', exceptionName, reason} — errors.ts wraps this into
+// NativeSimDispatchError.
+Napi::Error ObjCExceptionToJsError(Napi::Env env, const ObjCException& error);
+
+// Runs `fn` (the Napi-facing body of a synchronous exported method) and converts any of the three
+// exception types this addon throws into the matching pending JS exception, so a C++/ObjC failure
+// always surfaces as a catchable JS Error, never an uncaught native exception. On any exception,
+// returns env.Undefined(); the pending JS exception (set via ThrowAsJavaScriptException) is what the
+// caller actually sees.
+template <typename Fn>
+Napi::Value CatchToJs(Napi::Env env, Fn&& fn) {
+  try {
+    return fn();
+  } catch (const NativeSimUnavailableError& error) {
+    UnavailableToJsError(env, error).ThrowAsJavaScriptException();
+  } catch (const NSErrorException& error) {
+    NSErrorExceptionToJsError(env, error).ThrowAsJavaScriptException();
+  } catch (const ObjCException& error) {
+    ObjCExceptionToJsError(env, error).ThrowAsJavaScriptException();
+  } catch (const std::exception& error) {
+    Napi::Error::New(env, error.what()).ThrowAsJavaScriptException();
+  }
+  return env.Undefined();
+}
+
+}  // namespace coresim

package/src/native/nserror_bridge.mm

@@ -0,0 +1,30 @@
+#include "nserror_bridge.h"
+
+namespace coresim {
+
+Napi::Error NSErrorExceptionToJsError(Napi::Env env, const NSErrorException& error) {
+  Napi::Error jsError = Napi::Error::New(env, error.what());
+  jsError.Set("name", "NativeSimOperationError");
+  jsError.Set("domain", error.domain);
+  jsError.Set("code", static_cast<double>(error.code));
+  return jsError;
+}
+
+Napi::Error UnavailableToJsError(Napi::Env env, const NativeSimUnavailableError& error) {
+  Napi::Error jsError = Napi::Error::New(env, error.what());
+  jsError.Set("name", "NativeSimUnavailableError");
+  jsError.Set("kind", error.kind);
+  jsError.Set("missing", error.name);
+  jsError.Set("frameworkVersion", error.detail);
+  return jsError;
+}
+
+Napi::Error ObjCExceptionToJsError(Napi::Env env, const ObjCException& error) {
+  Napi::Error jsError = Napi::Error::New(env, error.what());
+  jsError.Set("name", "NativeSimDispatchError");
+  jsError.Set("exceptionName", error.name);
+  jsError.Set("reason", error.reason);
+  return jsError;
+}
+
+}  // namespace coresim

package/src/native/objc_runtime.h

@@ -0,0 +1,45 @@
+#pragma once
+
+#import <Foundation/Foundation.h>
+
+#include <stdexcept>
+#include <string>
+
+namespace coresim {
+
+// Thrown when a class/selector CoreSimulator.framework is expected to have doesn't exist on the
+// currently loaded framework, or when @try/@catch around objc_msgSend caught an NSException.
+// Distinct from ObjCDispatchError (an NSError-carrying operational failure): this means "not
+// supported on this simulator runtime", not "the call ran and failed".
+class NativeSimUnavailableError : public std::runtime_error {
+ public:
+  NativeSimUnavailableError(std::string kind, std::string name, std::string detail);
+
+  // "class" | "selector" | "exception"
+  std::string kind;
+  // The missing class/selector name, or the NSException name.
+  std::string name;
+  // CFBundleVersion of the loaded CoreSimulator.framework, or the NSException reason.
+  std::string detail;
+};
+
+// The loaded CoreSimulator.framework's CFBundleVersion (e.g. "1171.6"), or "unknown" if the
+// framework/its Info.plist can't be found. Cached after first call.
+const std::string& CoreSimulatorFrameworkVersion();
+
+// dlopen()s CoreSimulator.framework by absolute path (never statically linked) exactly once.
+// Idempotent; safe to call before every class lookup. Throws NativeSimUnavailableError if the
+// framework can't be loaded at all.
+void EnsureCoreSimulatorLoaded();
+
+// NSClassFromString(name), throwing NativeSimUnavailableError if the class doesn't exist.
+Class RequireClass(const std::string& name);
+
+// Throws NativeSimUnavailableError unless `target` (instance or Class) responds to `selectorName`.
+void RequireSelector(id target, const std::string& selectorName);
+void RequireClassSelector(Class cls, const std::string& selectorName);
+
+// SEL for a selector name; selectors are process-global so this never fails.
+SEL SelectorNamed(const std::string& name);
+
+}  // namespace coresim

package/src/native/objc_runtime.mm

@@ -0,0 +1,76 @@
+#include "objc_runtime.h"
+
+#import <dlfcn.h>
+#import <objc/message.h>
+#import <objc/runtime.h>
+
+namespace coresim {
+
+namespace {
+
+constexpr auto kCoreSimulatorPath =
+    "/Library/Developer/PrivateFrameworks/CoreSimulator.framework/Versions/A/CoreSimulator";
+constexpr auto kCoreSimulatorInfoPlist =
+    "/Library/Developer/PrivateFrameworks/CoreSimulator.framework/Versions/A/Resources/Info.plist";
+
+}  // namespace
+
+NativeSimUnavailableError::NativeSimUnavailableError(std::string kind, std::string name, std::string detail)
+    : std::runtime_error("CoreSimulator " + kind + " unavailable: " + name + " (" + detail + ")"),
+      kind(std::move(kind)),
+      name(std::move(name)),
+      detail(std::move(detail)) {}
+
+const std::string& CoreSimulatorFrameworkVersion() {
+  static const std::string version = [] {
+    @autoreleasepool {
+      NSDictionary* plist = [NSDictionary dictionaryWithContentsOfFile:@(kCoreSimulatorInfoPlist)];
+      NSString* bundleVersion = plist[@"CFBundleVersion"];
+      return bundleVersion ? std::string(bundleVersion.UTF8String) : std::string("unknown");
+    }
+  }();
+  return version;
+}
+
+void EnsureCoreSimulatorLoaded() {
+  static const bool loaded = [] {
+    void* handle = dlopen(kCoreSimulatorPath, RTLD_NOW | RTLD_LOCAL);
+    return handle != nullptr;
+  }();
+  if (!loaded) {
+    throw NativeSimUnavailableError("framework", "CoreSimulator", dlerror() ?: "dlopen failed");
+  }
+}
+
+Class RequireClass(const std::string& name) {
+  EnsureCoreSimulatorLoaded();
+  Class cls = NSClassFromString(@(name.c_str()));
+  if (cls == nil) {
+    throw NativeSimUnavailableError("class", name, CoreSimulatorFrameworkVersion());
+  }
+  return cls;
+}
+
+SEL SelectorNamed(const std::string& name) { return NSSelectorFromString(@(name.c_str())); }
+
+void RequireSelector(id target, const std::string& selectorName) {
+  if (target == nil) {
+    // A nil deviceType/runtime/etc. is a legitimate CoreSimulator state (e.g. a device whose
+    // runtime profile is no longer installed) — distinct from a genuinely missing selector, so
+    // callers can tell the two apart instead of getting a misleading "selector unavailable".
+    throw NativeSimUnavailableError("nil-target", selectorName, CoreSimulatorFrameworkVersion());
+  }
+  SEL selector = SelectorNamed(selectorName);
+  if (![target respondsToSelector:selector]) {
+    throw NativeSimUnavailableError("selector", selectorName, CoreSimulatorFrameworkVersion());
+  }
+}
+
+void RequireClassSelector(Class cls, const std::string& selectorName) {
+  SEL selector = SelectorNamed(selectorName);
+  if (![cls respondsToSelector:selector]) {
+    throw NativeSimUnavailableError("selector", selectorName, CoreSimulatorFrameworkVersion());
+  }
+}
+
+}  // namespace coresim

package/src/native/safe_dispatch.h

@@ -0,0 +1,38 @@
+#pragma once
+
+#import <Foundation/Foundation.h>
+
+#include <stdexcept>
+#include <string>
+#include <utility>
+
+namespace coresim {
+
+// Thrown when @try/@catch around an objc_msgSend call caught an NSException (e.g.
+// -doesNotRecognizeSelector:, an internal framework assertion, an argument-type mismatch).
+// Distinct from NativeSimUnavailableError: the class/selector existed and responded, but the
+// call itself raised.
+class ObjCException : public std::runtime_error {
+ public:
+  ObjCException(std::string name, std::string reason)
+      : std::runtime_error(name + ": " + reason), name(std::move(name)), reason(std::move(reason)) {}
+
+  std::string name;
+  std::string reason;
+};
+
+// Runs `fn` inside @try/@catch, converting any caught NSException into a C++ ObjCException.
+// Every objc_msgSend call in this addon must be wrapped in SafeInvoke — no exceptions
+// (pun intended) — so an uncaught NSException never reaches the caller and kills the process.
+template <typename Fn>
+auto SafeInvoke(Fn&& fn) -> decltype(fn()) {
+  @try {
+    return fn();
+  } @catch (NSException* exception) {
+    std::string name = exception.name ? exception.name.UTF8String : "NSException";
+    std::string reason = exception.reason ? exception.reason.UTF8String : "";
+    throw ObjCException(std::move(name), std::move(reason));
+  }
+}
+
+}  // namespace coresim