appium-ios-remotexpc 0.19.0 → 0.21.0

package/build/src/services/ios/dvt/instruments/network-monitor.js

@@ -0,0 +1,157 @@
+import { getLogger } from '../../../../lib/logger.js';
+import { BaseInstrument } from './base-instrument.js';
+const log = getLogger('NetworkMonitor');
+/**
+ * Message types for network monitoring events
+ */
+export const NetworkMessageType = {
+    INTERFACE_DETECTION: 0,
+    CONNECTION_DETECTION: 1,
+    CONNECTION_UPDATE: 2,
+};
+/**
+ * NetworkMonitor provides real-time network activity monitoring on iOS devices.
+ *
+ * This instrument captures:
+ * - Interface detection events (network interfaces coming up)
+ * - Connection detection events (new TCP/UDP connections)
+ * - Connection update events (traffic statistics updates)
+ */
+export class NetworkMonitor extends BaseInstrument {
+    static IDENTIFIER = 'com.apple.instruments.server.services.networking';
+    async start() {
+        await this.initialize();
+        await this.channel.call('startMonitoring')(undefined, false);
+    }
+    async stop() {
+        if (this.channel) {
+            await this.channel.call('stopMonitoring')();
+        }
+    }
+    /**
+     * Async generator that yields network events as they occur.
+     *
+     * The generator automatically starts monitoring when iteration begins
+     * and stops when the iteration is terminated (via break, return, or error).
+     *
+     * @yields NetworkEvent - Interface detection, connection detection, or connection update events
+     */
+    async *events() {
+        await this.start();
+        log.debug('network monitoring started');
+        try {
+            while (true) {
+                const message = await this.channel.receivePlist();
+                if (message === null) {
+                    continue;
+                }
+                const event = this.parseMessage(message);
+                if (event) {
+                    yield event;
+                }
+            }
+        }
+        finally {
+            log.debug('network monitoring stopped');
+            await this.stop();
+        }
+    }
+    /**
+     * Parse a raw message into a typed NetworkEvent
+     */
+    parseMessage(message) {
+        if (!Array.isArray(message) || message.length < 2) {
+            return null;
+        }
+        const [messageType, data] = message;
+        switch (messageType) {
+            case NetworkMessageType.INTERFACE_DETECTION:
+                return this.parseInterfaceDetection(data);
+            case NetworkMessageType.CONNECTION_DETECTION:
+                return this.parseConnectionDetection(data);
+            case NetworkMessageType.CONNECTION_UPDATE:
+                return this.parseConnectionUpdate(data);
+            default:
+                return null;
+        }
+    }
+    /**
+     * Parse interface detection event data
+     */
+    parseInterfaceDetection(data) {
+        const [interfaceIndex, name] = data;
+        return {
+            type: NetworkMessageType.INTERFACE_DETECTION,
+            interfaceIndex,
+            name,
+        };
+    }
+    /**
+     * Parse connection detection event data
+     */
+    parseConnectionDetection(data) {
+        const [localAddressRaw, remoteAddressRaw, interfaceIndex, pid, recvBufferSize, recvBufferUsed, serialNumber, kind,] = data;
+        return {
+            type: NetworkMessageType.CONNECTION_DETECTION,
+            localAddress: this.parseAddress(localAddressRaw),
+            remoteAddress: this.parseAddress(remoteAddressRaw),
+            interfaceIndex,
+            pid,
+            recvBufferSize,
+            recvBufferUsed,
+            serialNumber,
+            kind,
+        };
+    }
+    /**
+     * Parse connection update event data
+     */
+    parseConnectionUpdate(data) {
+        const [rxPackets, rxBytes, txPackets, txBytes, rxDups, rx000, txRetx, minRtt, avgRtt, connectionSerial, time,] = data;
+        return {
+            type: NetworkMessageType.CONNECTION_UPDATE,
+            rxPackets,
+            rxBytes,
+            txPackets,
+            txBytes,
+            rxDups,
+            rx000,
+            txRetx,
+            minRtt,
+            avgRtt,
+            connectionSerial,
+            time,
+        };
+    }
+    /**
+     * Parse a raw address buffer into a NetworkAddress structure
+     *
+     * Address structure format (sockaddr):
+     * - Byte 0: Length (0x10 for IPv4, 0x1C for IPv6)
+     * - Byte 1: Address family (2 = AF_INET, 30 = AF_INET6)
+     * - Bytes 2-3: Port (big-endian)
+     * - For IPv4 (len=0x10): Bytes 4-7 are the IP address
+     * - For IPv6 (len=0x1C): Bytes 4-7 flow info, 8-23 address, 24-27 scope ID
+     */
+    parseAddress(raw) {
+        const buf = Buffer.isBuffer(raw) ? raw : Buffer.from(raw);
+        const len = buf[0];
+        const family = buf[1];
+        const port = buf.readUInt16BE(2);
+        const result = { len, family, port, address: '0.0.0.0' };
+        if (len === 0x1c) {
+            // IPv6: 8 groups of 16-bit hex values
+            result.flowInfo = buf.readUInt32LE(4);
+            result.address = Array.from({ length: 8 }, (_, i) => buf.readUInt16BE(8 + i * 2).toString(16)).join(':');
+            result.scopeId = buf.readUInt32LE(24);
+        }
+        else if (len === 0x10) {
+            // IPv4: 4 octets as decimal
+            result.address = Array.from(buf.subarray(4, 8)).join('.');
+        }
+        else {
+            log.warn(`Unknown address length: ${len}`);
+        }
+        return result;
+    }
+}

package/build/src/services.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"services.d.ts","sourceRoot":"","sources":["../../src/services.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,MAAM,2CAA2C,CAAC;AAGhF,OAAO,KAAK,EACV,wBAAwB,EACxB,gCAAgC,EAChC,6BAA6B,EAC7B,iCAAiC,EACjC,uCAAuC,EACvC,sCAAsC,EACtC,mCAAmC,EACnC,gCAAgC,EAChC,aAAa,IAAI,iBAAiB,EAClC,iCAAiC,EAClC,MAAM,gBAAgB,CAAC;AACxB,OAAO,UAAU,MAAM,6BAA6B,CAAC;AAsBrD,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,gCAAgC,CAAC,CAY3C;AAED,wBAAsB,6BAA6B,CACjD,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,sCAAsC,CAAC,CAYjD;AAED,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,iCAAiC,CAAC,CAY5C;AAED,wBAAsB,8BAA8B,CAClD,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,uCAAuC,CAAC,CAYlD;AAED,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,gCAAgC,CAAC,CAY3C;AAED,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,6BAA6B,CAAC,CAYxC;AAED,wBAAsB,0BAA0B,CAC9C,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,mCAAmC,CAAC,CAY9C;AAED,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,iBAAiB,CAAC,CAG5B;AAED;;;GAGG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAOvE;AAED,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,iCAAiC,CAAC,CAY5C;AAED,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,wBAAwB,CAAC,CAmCnC;AAED,wBAAsB,yBAAyB,CAAC,IAAI,EAAE,MAAM;;;;;;;;GAO3D"}
+{"version":3,"file":"services.d.ts","sourceRoot":"","sources":["../../src/services.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,MAAM,2CAA2C,CAAC;AAGhF,OAAO,KAAK,EACV,wBAAwB,EACxB,gCAAgC,EAChC,6BAA6B,EAC7B,iCAAiC,EACjC,uCAAuC,EACvC,sCAAsC,EACtC,mCAAmC,EACnC,gCAAgC,EAChC,aAAa,IAAI,iBAAiB,EAClC,iCAAiC,EAClC,MAAM,gBAAgB,CAAC;AACxB,OAAO,UAAU,MAAM,6BAA6B,CAAC;AAuBrD,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,gCAAgC,CAAC,CAY3C;AAED,wBAAsB,6BAA6B,CACjD,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,sCAAsC,CAAC,CAYjD;AAED,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,iCAAiC,CAAC,CAY5C;AAED,wBAAsB,8BAA8B,CAClD,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,uCAAuC,CAAC,CAYlD;AAED,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,gCAAgC,CAAC,CAY3C;AAED,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,6BAA6B,CAAC,CAYxC;AAED,wBAAsB,0BAA0B,CAC9C,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,mCAAmC,CAAC,CAY9C;AAED,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,iBAAiB,CAAC,CAG5B;AAED;;;GAGG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAOvE;AAED,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,iCAAiC,CAAC,CAY5C;AAED,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,wBAAwB,CAAC,CAqCnC;AAED,wBAAsB,yBAAyB,CAAC,IAAI,EAAE,MAAM;;;;;;;;GAO3D"}

package/build/src/services.js

@@ -10,6 +10,7 @@ import { ConditionInducer } from './services/ios/dvt/instruments/condition-induc
 import { DeviceInfo } from './services/ios/dvt/instruments/device-info.js';
 import { Graphics } from './services/ios/dvt/instruments/graphics.js';
 import { LocationSimulation } from './services/ios/dvt/instruments/location-simulation.js';
+import { NetworkMonitor } from './services/ios/dvt/instruments/network-monitor.js';
 import { Notifications } from './services/ios/dvt/instruments/notifications.js';
 import { Screenshot } from './services/ios/dvt/instruments/screenshot.js';
 import { MisagentService } from './services/ios/misagent/index.js';
@@ -144,6 +145,7 @@ export async function startDVTService(udid) {
     const graphics = new Graphics(dvtService);
     const deviceInfo = new DeviceInfo(dvtService);
     const notification = new Notifications(dvtService);
+    const networkMonitor = new NetworkMonitor(dvtService);
     return {
         remoteXPC: remoteXPC,
         dvtService,
@@ -154,6 +156,7 @@ export async function startDVTService(udid) {
         graphics,
         deviceInfo,
         notification,
+        networkMonitor,
     };
 }
 export async function createRemoteXPCConnection(udid) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appium-ios-remotexpc",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "main": "build/src/index.js",
   "types": "build/src/index.d.ts",
   "type": "module",
@@ -47,6 +47,7 @@
     "test:dvt:device-info": "mocha test/integration/dvt_instruments/device-info-test.ts --exit --timeout 1m",
     "test:dvt:applist": "mocha test/integration/dvt_instruments/app-listing-test.ts --exit --timeout 1m",
     "test:dvt:notification": "mocha test/integration/dvt_instruments/notifications-test.ts --exit --timeout 1m",
+    "test:dvt:network-monitor": "mocha test/integration/dvt_instruments/network-monitor-test.ts --exit --timeout 1m",
     "test:tunnel-creation": "sudo tsx scripts/test-tunnel-creation.ts",
     "test:tunnel-creation:lsof": "sudo tsx scripts/test-tunnel-creation.ts --keep-open"
   },
@@ -91,6 +92,7 @@
     "@xmldom/xmldom": "^0.9.8",
     "appium-ios-tuntap": "^0.x",
     "axios": "^1.12.0",
+    "minimatch": "^10.1.1",
     "npm-run-all2": "^8.0.4"
   },
   "files": [

package/src/index.ts

@@ -30,6 +30,7 @@ export type {
   ScreenshotService,
   GraphicsService,
   DeviceInfoService,
+  NetworkMonitorService,
   ProcessInfo,
   ConditionProfile,
   ConditionGroup,
@@ -46,8 +47,14 @@ export type {
   WebInspectorServiceWithConnection,
   MisagentServiceWithConnection,
   DVTServiceWithConnection,
+  NetworkAddress,
+  InterfaceDetectionEvent,
+  ConnectionDetectionEvent,
+  ConnectionUpdateEvent,
+  NetworkEvent,
 } from './lib/types.js';
 export { PowerAssertionType } from './lib/types.js';
+export { NetworkMessageType } from './services/ios/dvt/instruments/network-monitor.js';
 export {
   STRONGBOX_CONTAINER_NAME,
   createUsbmux,

package/src/lib/types.ts

@@ -575,6 +575,140 @@ export interface GraphicsService {
   messages(): AsyncGenerator<unknown, void, unknown>;
 }
 
+/**
+ * Network address information
+ */
+export interface NetworkAddress {
+  /** Length of the address structure */
+  len: number;
+  /** Address family (2 = IPv4, 30 = IPv6) */
+  family: number;
+  /** Port number */
+  port: number;
+  /** Parsed IP address string */
+  address: string;
+  /** Flow info (IPv6 only) */
+  flowInfo?: number;
+  /** Scope ID (IPv6 only) */
+  scopeId?: number;
+}
+
+/**
+ * Event emitted when a network interface is detected
+ */
+export interface InterfaceDetectionEvent {
+  type: 0;
+  /** Interface index */
+  interfaceIndex: number;
+  /** Interface name (e.g., 'en0', 'lo0') */
+  name: string;
+}
+
+/**
+ * Event emitted when a network connection is detected
+ */
+export interface ConnectionDetectionEvent {
+  type: 1;
+  /** Local address information */
+  localAddress: NetworkAddress;
+  /** Remote address information */
+  remoteAddress: NetworkAddress;
+  /** Interface index */
+  interfaceIndex: number;
+  /** Process ID owning the connection */
+  pid: number;
+  /** Receive buffer size */
+  recvBufferSize: number;
+  /** Receive buffer used */
+  recvBufferUsed: number;
+  /** Connection serial number */
+  serialNumber: number;
+  /** Connection kind/type */
+  kind: number;
+}
+
+/**
+ * Event emitted when connection statistics are updated
+ */
+export interface ConnectionUpdateEvent {
+  type: 2;
+  /** Received packets count */
+  rxPackets: number;
+  /** Received bytes count */
+  rxBytes: number;
+  /** Transmitted packets count */
+  txPackets: number;
+  /** Transmitted bytes count */
+  txBytes: number;
+  /** Duplicate received packets */
+  rxDups: number;
+  /** Reserved field */
+  rx000: number;
+  /** Retransmitted packets */
+  txRetx: number;
+  /** Minimum round-trip time */
+  minRtt: number;
+  /** Average round-trip time */
+  avgRtt: number;
+  /** Connection serial number (links to ConnectionDetectionEvent) */
+  connectionSerial: number;
+  /** Timestamp */
+  time: number;
+}
+
+/**
+ * Union type for all network monitoring events
+ */
+export type NetworkEvent =
+  | InterfaceDetectionEvent
+  | ConnectionDetectionEvent
+  | ConnectionUpdateEvent;
+
+/**
+ * Network monitor service interface for real-time network activity monitoring
+ */
+export interface NetworkMonitorService {
+  /**
+   * Async iterator for network events.
+   * Yields interface detection, connection detection, and connection update events.
+   *
+   * @example
+   * const networkMonitor = device.networkMonitor();
+   * for await (const event of networkMonitor.events()) {
+   *   console.log(event);
+   * }
+   *
+   * // Example output:
+   * // { type: 0, interfaceIndex: 25, name: 'utun5' }
+   * // {
+   * //   type: 1,
+   * //   localAddress: {
+   * //     len: 28,
+   * //     family: 30,
+   * //     port: 50063,
+   * //     address: 'fdc2:1118:d2ac:0:0:0:0:1',
+   * //     flowInfo: 0,
+   * //     scopeId: 0
+   * //   },
+   * //   remoteAddress: {
+   * //     len: 28,
+   * //     family: 30,
+   * //     port: 65334,
+   * //     address: 'fdc2:1118:d2ac:0:0:0:0:2',
+   * //     flowInfo: 0,
+   * //     scopeId: 0
+   * //   },
+   * //   interfaceIndex: 25,
+   * //   pid: -2,
+   * //   recvBufferSize: 397120,
+   * //   recvBufferUsed: 0,
+   * //   serialNumber: 0,
+   * //   kind: 1
+   * // }
+   */
+  events(): AsyncGenerator<NetworkEvent, void, unknown>;
+}
+
 /**
  * Process information
  */
@@ -862,6 +996,8 @@ export interface DVTServiceWithConnection {
   deviceInfo: DeviceInfoService;
   /** The Notifications service instance */
   notification: NotificationService;
+  /** The NetworkMonitor service instance */
+  networkMonitor: NetworkMonitorService;
   /** The RemoteXPC connection that can be used to close the connection */
   remoteXPC: RemoteXpcConnection;
 }

package/src/services/ios/afc/index.ts

@@ -1,4 +1,6 @@
+import { minimatch } from 'minimatch';
 import fs from 'node:fs';
+import fsp from 'node:fs/promises';
 import net from 'node:net';
 import path from 'node:path';
 import { Readable, Writable } from 'node:stream';
@@ -8,6 +10,7 @@ import { getLogger } from '../../../lib/logger.js';
 import {
   buildClosePayload,
   buildFopenPayload,
+  buildMkdirPayload,
   buildReadPayload,
   buildRemovePayload,
   buildRenamePayload,
@@ -29,6 +32,38 @@ const log = getLogger('AfcService');
 
 const NON_LISTABLE_ENTRIES = ['', '.', '..'];
 
+/**
+ * Callback invoked for each file successfully pulled from the device.
+ *
+ * @param remotePath - The remote file path on the device
+ * @param localPath - The local file path where it was saved
+ *
+ * @remarks
+ * If the callback throws an error, the pull operation will be aborted immediately.
+ */
+export type PullRecursiveCallback = (
+  remotePath: string,
+  localPath: string,
+) => unknown | Promise<unknown>;
+
+/** Options for the pull method. */
+export interface PullOptions {
+  /**
+   * If true, recursively pull directories.
+   * @default false
+   */
+  recursive?: boolean;
+  /** Glob pattern to filter files (e.g., '*.txt', '**\/*.log'). */
+  match?: string;
+  /**
+   * If false, throws error when local file exists.
+   * @default true
+   */
+  overwrite?: boolean;
+  /** Callback invoked for each pulled file. */
+  callback?: PullRecursiveCallback;
+}
+
 export interface StatInfo {
   st_ifmt: AfcFileMode;
   st_size: bigint;
@@ -288,12 +323,97 @@ export class AfcService {
     }
   }
 
-  async pull(remoteSrc: string, localDst: string): Promise<void> {
-    log.debug(`Pulling file from '${remoteSrc}' to '${localDst}'`);
-    const stream = await this.readToStream(remoteSrc);
-    const writeStream = fs.createWriteStream(localDst);
-    await pipeline(stream, writeStream);
-    log.debug(`Successfully pulled file to '${localDst}'`);
+  /**
+   * Pull file(s) or directory from the device to the local filesystem.
+   *
+   * @param remoteSrc - Remote path on the device (file or directory)
+   * @param localDst - Local destination path
+   * @param options - Optional configuration
+   *
+   * @throws {Error} If the remote source path does not exist
+   * @throws {Error} If overwrite is false and local file already exists
+   *
+   * @remarks
+   * When pulling a directory with `recursive: true`, the directory itself will be created
+   * inside the destination. For example, pulling `/Downloads` to `/tmp` will create `/tmp/Downloads`.
+   */
+  async pull(
+    remoteSrc: string,
+    localDst: string,
+    options?: PullOptions,
+  ): Promise<void> {
+    const {
+      recursive = false,
+      match,
+      overwrite = true,
+      callback,
+    } = options ?? {};
+
+    if (!(await this.exists(remoteSrc))) {
+      throw new Error(`Remote path does not exist: ${remoteSrc}`);
+    }
+
+    const pullSingleFile = async (
+      remoteFilePath: string,
+      localFilePath: string,
+    ): Promise<void> => {
+      log.debug(`Pulling file from '${remoteFilePath}' to '${localFilePath}'`);
+
+      if (!overwrite && (await this._localPathExists(localFilePath))) {
+        throw new Error(`Local file already exists: ${localFilePath}`);
+      }
+
+      await this._pullFile(remoteFilePath, localFilePath);
+
+      if (callback) {
+        await callback(remoteFilePath, localFilePath);
+      }
+    };
+
+    const isDir = await this.isdir(remoteSrc);
+
+    if (!isDir) {
+      const baseName = path.posix.basename(remoteSrc);
+
+      if (match && !minimatch(baseName, match)) {
+        return;
+      }
+
+      const localDstIsDirectory = await this._isLocalDirectory(localDst);
+      const targetPath = localDstIsDirectory
+        ? path.join(localDst, baseName)
+        : localDst;
+
+      await pullSingleFile(remoteSrc, targetPath);
+      return;
+    }
+
+    // Source is a directory, recursive option required
+    if (!recursive) {
+      throw new Error(
+        `Cannot pull directory '${remoteSrc}' without recursive option. Set recursive: true to pull directories.`,
+      );
+    }
+
+    log.debug(`Starting recursive pull from '${remoteSrc}' to '${localDst}'`);
+    await this._pullRecursiveInternal(remoteSrc, localDst, {
+      match,
+      overwrite,
+      callback,
+    });
+  }
+
+  /**
+   * Create a directory on the device.
+   *
+   * Creates parent directories automatically and is idempotent (no error if the directory exists).
+   *
+   * @param dirPath - Path of the directory to create.
+   * @returns A promise that resolves when the directory has been created.
+   */
+  async mkdir(dirPath: string): Promise<void> {
+    await this._doOperation(AfcOpcode.MAKE_DIR, buildMkdirPayload(dirPath));
+    log.debug(`Successfully created directory: ${dirPath}`);
   }
 
   async rmSingle(filePath: string, force = false): Promise<boolean> {
@@ -418,6 +538,137 @@ export class AfcService {
     this.socket = null;
   }
 
+  /**
+   * Private primitive to pull a single file from device to local filesystem.
+   *
+   * @param remoteSrc - Remote file path on the device (must be a file)
+   * @param localDst - Local destination file path
+   */
+  private async _pullFile(remoteSrc: string, localDst: string): Promise<void> {
+    log.debug(`Pulling file from '${remoteSrc}' to '${localDst}'`);
+
+    const resolved = await this._resolvePath(remoteSrc);
+    const st = await this.stat(resolved);
+
+    if (st.st_ifmt !== AfcFileMode.S_IFREG) {
+      throw new Error(`'${resolved}' isn't a regular file`);
+    }
+
+    const handle = await this.fopen(resolved, 'r');
+    try {
+      const stream = this.createReadStream(handle, st.st_size);
+      const writeStream = fs.createWriteStream(localDst);
+      await pipeline(stream, writeStream);
+      log.debug(
+        `Successfully pulled file to '${localDst}' (${st.st_size} bytes)`,
+      );
+    } finally {
+      await this.fclose(handle);
+    }
+  }
+
+  /**
+   * Recursively pull directory contents from device to local filesystem.
+   *
+   * @remarks
+   * This method is intended for directories only. Caller must validate that remoteSrcDir
+   * is a directory before invoking.
+   */
+  private async _pullRecursiveInternal(
+    remoteSrcDir: string,
+    localDstDir: string,
+    options?: Omit<PullOptions, 'recursive'>,
+    relativePath = '',
+  ): Promise<void> {
+    const { match, overwrite = true, callback } = options ?? {};
+
+    let localDirPath: string;
+    if (!relativePath) {
+      const localDstIsDirectory = await this._isLocalDirectory(localDstDir);
+
+      if (!localDstIsDirectory) {
+        const stat = await fsp.stat(localDstDir).catch((err) => {
+          if (err.code === 'ENOENT') {
+            return null;
+          }
+          throw err;
+        });
+        if (stat?.isFile()) {
+          throw new Error(
+            `Local destination exists and is a file, not a directory: ${localDstDir}`,
+          );
+        }
+      }
+
+      const baseName = path.posix.basename(remoteSrcDir);
+      localDirPath = localDstIsDirectory
+        ? path.join(localDstDir, baseName)
+        : localDstDir;
+    } else {
+      localDirPath = localDstDir;
+    }
+
+    await fsp.mkdir(localDirPath, { recursive: true });
+
+    for (const entry of await this.listdir(remoteSrcDir)) {
+      const entryPath = path.posix.join(remoteSrcDir, entry);
+      const entryRelativePath = relativePath
+        ? path.posix.join(relativePath, entry)
+        : entry;
+
+      if (await this.isdir(entryPath)) {
+        await this._pullRecursiveInternal(
+          entryPath,
+          path.join(localDirPath, entry),
+          options,
+          entryRelativePath,
+        );
+      } else {
+        if (match && !minimatch(entryRelativePath, match)) {
+          continue;
+        }
+
+        const targetPath = path.join(localDirPath, entry);
+        if (!overwrite && (await this._localPathExists(targetPath))) {
+          throw new Error(`Local file already exists: ${targetPath}`);
+        }
+
+        await this._pullFile(entryPath, targetPath);
+
+        if (callback) {
+          await callback(entryPath, targetPath);
+        }
+      }
+    }
+  }
+
+  /**
+   * Helper to check if a local filesystem path exists and is a directory.
+   */
+  private async _isLocalDirectory(localPath: string): Promise<boolean> {
+    try {
+      const stats = await fsp.stat(localPath);
+      return stats.isDirectory();
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Helper to check if a local path (file or directory) exists.
+   */
+  private async _localPathExists(localPath: string): Promise<boolean> {
+    try {
+      await fsp.access(localPath, fsp.constants.F_OK);
+      return true;
+    } catch (err: any) {
+      if (err.code === 'ENOENT') {
+        return false;
+      }
+      throw err;
+    }
+  }
+
   /**
    * Connect to RSD port and perform RSDCheckin.
    * Keeps the underlying socket for raw AFC I/O.