appium-ios-remotexpc 0.19.0 → 0.20.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.20.0](https://github.com/appium/appium-ios-remotexpc/compare/v0.19.0...v0.20.0) (2025-12-19)
+
+### Features
+
+* **afc:** add `recursive` option to pull, `mkdir` method and fix race condition in `pull` ([#113](https://github.com/appium/appium-ios-remotexpc/issues/113)) ([9a7d61f](https://github.com/appium/appium-ios-remotexpc/commit/9a7d61fcb0a47e5e1e4fbacf2cdc9e76d922e09f))
+
 ## [0.19.0](https://github.com/appium/appium-ios-remotexpc/compare/v0.18.1...v0.19.0) (2025-12-17)
 
 ### Features

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

@@ -1,6 +1,33 @@
 import { Readable, Writable } from 'node:stream';
 import { AFC_FOPEN_TEXTUAL_MODES } from './constants.js';
 import { AfcFileMode } from './enums.js';
+/**
+ * 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;
@@ -39,7 +66,30 @@ export declare class AfcService {
     setFileContents(filePath: string, data: Buffer): Promise<void>;
     readToStream(filePath: string): Promise<Readable>;
     writeFromStream(filePath: string, stream: Readable): Promise<void>;
-    pull(remoteSrc: string, localDst: string): Promise<void>;
+    /**
+     * 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`.
+     */
+    pull(remoteSrc: string, localDst: string, options?: PullOptions): Promise<void>;
+    /**
+     * 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.
+     */
+    mkdir(dirPath: string): Promise<void>;
     rmSingle(filePath: string, force?: boolean): Promise<boolean>;
     rm(filePath: string, force?: boolean): Promise<string[]>;
     rename(src: string, dst: string): Promise<void>;
@@ -53,6 +103,29 @@ export declare class AfcService {
      * Close the underlying socket
      */
     close(): void;
+    /**
+     * 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 _pullFile;
+    /**
+     * 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 _pullRecursiveInternal;
+    /**
+     * Helper to check if a local filesystem path exists and is a directory.
+     */
+    private _isLocalDirectory;
+    /**
+     * Helper to check if a local path (file or directory) exists.
+     */
+    private _localPathExists;
     /**
      * Connect to RSD port and perform RSDCheckin.
      * Keeps the underlying socket for raw AFC I/O.

package/build/src/services/ios/afc/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/services/ios/afc/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/services/ios/afc/index.ts"],"names":[],"mappings":"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"}

package/build/src/services/ios/afc/index.js

@@ -1,10 +1,12 @@
+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';
 import { pipeline } from 'node:stream/promises';
 import { getLogger } from '../../../lib/logger.js';
-import { buildClosePayload, buildFopenPayload, buildReadPayload, buildRemovePayload, buildRenamePayload, buildStatPayload, nanosecondsToMilliseconds, nextReadChunkSize, parseCStringArray, parseKeyValueNullList, readAfcResponse, rsdHandshakeForRawService, sendAfcPacket, writeUInt64LE, } from './codec.js';
+import { buildClosePayload, buildFopenPayload, buildMkdirPayload, buildReadPayload, buildRemovePayload, buildRenamePayload, buildStatPayload, nanosecondsToMilliseconds, nextReadChunkSize, parseCStringArray, parseKeyValueNullList, readAfcResponse, rsdHandshakeForRawService, sendAfcPacket, writeUInt64LE, } from './codec.js';
 import { AFC_FOPEN_TEXTUAL_MODES, AFC_WRITE_THIS_LENGTH } from './constants.js';
 import { AfcError, AfcFileMode, AfcOpcode } from './enums.js';
 import { createAfcReadStream, createAfcWriteStream } from './stream-utils.js';
@@ -200,12 +202,70 @@ export class AfcService {
             await this.fclose(handle);
         }
     }
-    async pull(remoteSrc, localDst) {
-        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, localDst, options) {
+        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, localFilePath) => {
+            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) {
+        await this._doOperation(AfcOpcode.MAKE_DIR, buildMkdirPayload(dirPath));
+        log.debug(`Successfully created directory: ${dirPath}`);
     }
     async rmSingle(filePath, force = false) {
         log.debug(`Removing single path: ${filePath} (force: ${force})`);
@@ -315,6 +375,112 @@ 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
+     */
+    async _pullFile(remoteSrc, localDst) {
+        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.
+     */
+    async _pullRecursiveInternal(remoteSrcDir, localDstDir, options, relativePath = '') {
+        const { match, overwrite = true, callback } = options ?? {};
+        let localDirPath;
+        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.
+     */
+    async _isLocalDirectory(localPath) {
+        try {
+            const stats = await fsp.stat(localPath);
+            return stats.isDirectory();
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Helper to check if a local path (file or directory) exists.
+     */
+    async _localPathExists(localPath) {
+        try {
+            await fsp.access(localPath, fsp.constants.F_OK);
+            return true;
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                return false;
+            }
+            throw err;
+        }
+    }
     /**
      * Connect to RSD port and perform RSDCheckin.
      * Keeps the underlying socket for raw AFC I/O.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appium-ios-remotexpc",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "main": "build/src/index.js",
   "types": "build/src/index.d.ts",
   "type": "module",
@@ -91,6 +91,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/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.