@appium/support 2.56.1 → 2.57.2

package/lib/npm.js

@@ -2,6 +2,7 @@
 
 import path from 'path';
 import semver from 'semver';
+import { hasAppiumDependency } from './env';
 import { exec } from 'teen_process';
 import { fs } from './fs';
 import * as util from './util';
@@ -27,14 +28,6 @@ export const INSTALL_LOCKFILE_RELATIVE_PATH = path.join(
   '.install.lock',
 );
 
-/**
- * Relative path to lockfile used when linking an extension via `appium`
- */
-export const LINK_LOCKFILE_RELATIVE_PATH = path.join(
-  CACHE_DIR_RELATIVE_PATH,
-  '.link.lock',
-);
-
 /**
  * XXX: This should probably be a singleton, but it isn't.  Maybe this module should just export functions?
  */
@@ -48,15 +41,6 @@ export class NPM {
     return path.join(cwd, INSTALL_LOCKFILE_RELATIVE_PATH);
   }
 
-  /**
-   * Returns path to "link" lockfile
-   * @private
-   * @param {string} cwd
-   */
-  _getLinkLockfilePath (cwd) {
-    return path.join(cwd, LINK_LOCKFILE_RELATIVE_PATH);
-  }
-
   /**
    * Execute `npm` with given args.
    *
@@ -65,9 +49,9 @@ export class NPM {
    * @param {string} cmd
    * @param {string[]} args
    * @param {ExecOpts} opts
-   * @param {TeenProcessExecOpts} [execOpts]
+   * @param {ExecOpts} [execOpts]
    */
-  async exec (cmd, args, opts, execOpts = {}) {
+  async exec (cmd, args, opts, execOpts = /** @type {ExecOpts} */({})) {
     let { cwd, json, lockFile } = opts;
 
     // make sure we perform the current operation in cwd
@@ -85,10 +69,11 @@ export class NPM {
       runner = async () => await acquireLock(_runner);
     }
 
+    /** @type {import('teen_process').ExecResult<string> & {json?: any}} */
     let ret;
     try {
       const {stdout, stderr, code} = await runner();
-      ret = /** @type {TeenProcessExecResult} */({stdout, stderr, code});
+      ret = {stdout, stderr, code};
       // if possible, parse NPM's json output. During NPM install 3rd-party
       // packages can write to stdout, so sometimes the json output can't be
       // guaranteed to be parseable
@@ -189,18 +174,37 @@ export class NPM {
    * @returns {Promise<import('type-fest').PackageJson>}
    */
   async installPackage (cwd, pkgName, {pkgVer} = {}) {
-    // not only this, this directory needs a 'package.json' inside of it, otherwise, if any
-    // directory in the filesystem tree ABOVE cwd happens to have a package.json or a node_modules
-    // dir in it, NPM will install the module up there instead (silly NPM)
-    const dummyPkgJson = path.resolve(cwd, 'package.json');
-    if (!await fs.exists(dummyPkgJson)) {
-      await fs.writeFile(dummyPkgJson, '{}');
+    /** @type {any} */
+    let dummyPkgJson;
+    const dummyPkgPath = path.join(cwd, 'package.json');
+    try {
+      dummyPkgJson = JSON.parse(await fs.readFile(dummyPkgPath, 'utf8'));
+    } catch (err) {
+      if (err.code === 'ENOENT') {
+        dummyPkgJson = {};
+        await fs.writeFile(dummyPkgPath, JSON.stringify(dummyPkgJson, null, 2), 'utf8');
+      } else {
+        throw err;
+      }
     }
 
+    /**
+     * If we've found a `package.json` containined the `appiumCreated` property,
+     * then we can do whatever we please with it, since we created it.  This is
+     * likely when `APPIUM_HOME` is the default (in `~/.appium`).  In that case,
+     * we want `--global-style` to avoid deduping, and we also do not need a
+     * `package-lock.json`.
+     *
+     * If we _haven't_ found such a key, then this `package.json` isn't a
+     * "dummy" and is controlled by the user.  So we'll just add it as a dev
+     * dep; whatever else it does is up to the user's npm config.
+     */
+    const installOpts = await hasAppiumDependency(cwd) ?
+      ['--save-dev'] :
+      ['--save-dev', '--save-exact', '--global-style', '--no-package-lock'];
+
     const res = await this.exec('install', [
-      '--no-save',
-      '--global-style',
-      '--no-package-lock',
+      ...installOpts,
       pkgVer ? `${pkgName}@${pkgVer}` : pkgName
     ], {
       cwd,
@@ -230,46 +234,6 @@ export class NPM {
     }
   }
 
-  /**
-   * @todo: I think this can be an `install` instead of a `link`.
-   * @param {string} cwd
-   * @param {string} pkgPath
-   */
-  async linkPackage (cwd, pkgPath) {
-    // from the path alone we don't know the npm package name, so we need to
-    // look in package.json
-    let pkgName;
-    try {
-      pkgName = require(path.resolve(pkgPath, 'package.json')).name;
-    } catch {
-      throw new Error('Could not find package.json inside the package path ' +
-                      `provided: ${pkgPath}`);
-    }
-
-    // this is added to handle commands with relative paths
-    // ie: "node . driver install --source=local ../fake-driver"
-    pkgPath = path.resolve(process.cwd(), pkgPath);
-
-    // call link with --no-package-lock to ensure no corruption while installing local packages
-    const args = [
-      '--global-style',
-      '--no-package-lock',
-      pkgPath
-    ];
-    const res = await this.exec('link', args, {cwd, lockFile: this._getLinkLockfilePath(cwd)});
-    if (res.json && res.json.error) {
-      throw new Error(res.json.error);
-    }
-
-    // now ensure it was linked to the correct place
-    try {
-      return require(resolveFrom(cwd, `${pkgName}/package.json`));
-    } catch {
-      throw new Error('The package was not linked correctly; its package.json ' +
-                      'did not exist or was unreadable');
-    }
-  }
-
   /**
    * @param {string} cwd
    * @param {string} pkg
@@ -300,15 +264,6 @@ export const npm = new NPM();
 
 // THESE TYPES SHOULD BE IN TEEN PROCESS, NOT HERE
 
-/**
- * Result from a non-zero-exit execution of `appium`
- * @typedef TeenProcessExecResult
- * @property {string} stdout - Stdout
- * @property {string} stderr - Stderr
- * @property {number?} code - Exit code
- * @property {any} json - JSON parsed from stdout
- */
-
 /**
  * Extra props `teen_process.exec` adds to its error objects
  * @typedef TeenProcessExecErrorProps
@@ -317,18 +272,6 @@ export const npm = new NPM();
  * @property {number?} code - Exit code
  */
 
-/**
- * Options unique to `teen_process.exec`. I probably missed some
- * @typedef TeenProcessExecExtraOpts
- * @property {number} [maxStdoutBufferSize]
- * @property {number} [maxStderrBufferSize]
- */
-
-/**
- * All options for `teen_process.exec`
- * @typedef {import('child_process').SpawnOptions & TeenProcessExecExtraOpts} TeenProcessExecOpts
- */
-
 /**
  * Error thrown by `teen_process.exec`
  * @typedef {Error & TeenProcessExecErrorProps} TeenProcessExecError

package/lib/plist.js

@@ -26,7 +26,7 @@ async function parseXmlPlistFile (plistFilename) {
  * @param {string} plist The plist file path
  * @param {boolean} mustExist If set to false, this method will return an empty object when the file doesn't exist
  * @param {boolean} quiet If set to false, the plist path will be logged in debug level
- * @returns {Object} parsed plist JS Object
+ * @returns {Promise<any>} parsed plist JS Object
  */
 async function parsePlistFile (plist, mustExist = true, quiet = true) {
   // handle nonexistant file
@@ -103,6 +103,8 @@ function createBinaryPlist (data) {
  * @param {Buffer} data The beffer of a binary plist
  */
 function parseBinaryPlist (data) {
+  // this function exists, but is not in the type declarations.
+  // @ts-expect-error
   return bplistParse.parseBuffer(data);
 }
 

package/lib/tempdir.js

@@ -34,8 +34,8 @@ async function tempDir () {
 
 /**
  * @typedef Affixes
- * @property {string} prefix - prefix of the temp directory name
- * @property {string} suffix - suffix of the temp directory name
+ * @property {string} [prefix] - prefix of the temp directory name
+ * @property {string} [suffix] - suffix of the temp directory name
  */
 
 /**
@@ -43,7 +43,7 @@ async function tempDir () {
  * with arbitrary prefix/suffix for the directory name.
  *
  * @param {string|Affixes} rawAffixes
- * @param {?string} defaultPrefix
+ * @param {string} [defaultPrefix]
  * @returns {Promise<string>}  A path to the temporary directory with rawAffixes and defaultPrefix
  */
 async function path (rawAffixes, defaultPrefix) {
@@ -56,7 +56,7 @@ async function path (rawAffixes, defaultPrefix) {
 /**
  * @typedef OpenedAffixes
  * @property {string} path - The path to file
- * @property {integer} fd - The file descriptor opened
+ * @property {number} fd - The file descriptor opened
  */
 
 /**
@@ -73,7 +73,7 @@ async function open (affixes) {
     // opens the file in mode 384
     return {path: filePath, fd};
   } catch (err) {
-    log.errorAndThrow(err);
+    return log.errorAndThrow(err);
   }
 }
 
@@ -82,11 +82,12 @@ async function open (affixes) {
  * Returns prefix/suffix object
  *
  * @param {string|Affixes} rawAffixes
- * @param {?string} defaultPrefix
+ * @param {string} [defaultPrefix]
  * @returns {Affixes}
  */
 function parseAffixes (rawAffixes, defaultPrefix) {
-  let affixes = {prefix: null, suffix: null};
+  /** @type {Affixes} */
+  let affixes = {};
   if (rawAffixes) {
     switch (typeof rawAffixes) {
       case 'string':

package/lib/util.js

@@ -276,15 +276,9 @@ async function isSameDestination (path1, path2, ...pathN) {
     return true;
   }
 
-  // Node 10.5.0 introduced bigint support in stat, which allows for more precision
-  // however below that the options get interpreted as the callback
-  // TODO: remove when Node 10 is no longer supported
-  let mapCb = async (x) => await fs.stat(x, {
+  let mapCb = async (x) => (await fs.stat(x, {
     bigint: true,
-  }).ino;
-  if (semver.lt(process.version, '10.5.0')) {
-    mapCb = async (x) => await fs.stat(x).ino;
-  }
+  })).ino;
   return areAllItemsEqual(await B.map(allPaths, mapCb));
 }
 
@@ -304,7 +298,7 @@ function coerceVersion (ver, strict = /** @type {Strict} */(true)) {
   if (strict && !result) {
     throw new Error(`'${ver}' cannot be coerced to a valid version number`);
   }
-  return /** @type {Strict extends true ? string : string|null} */(result);
+  return /** @type {Strict extends true ? string : string?} */(result);
 }
 
 const SUPPORTED_OPERATORS = ['==', '!=', '>', '<', '>=', '<=', '='];
@@ -341,7 +335,7 @@ function compareVersions (ver1, operator, ver2) {
  * @returns {string} - The arguments, quoted
  */
 function quote (args) {
-  return shellQuote(args);
+  return shellQuote(_.castArray(args));
 }
 
 /**
@@ -460,9 +454,10 @@ async function toInMemoryBase64 (srcPath, opts = {}) {
  * longer present on the system. This allows for preventing concurrent behavior across processes
  * using a known lockfile path.
  *
+ * @template T
  * @param {string} lockFile The full path to the file used for the lock
  * @param {LockFileOptions} opts
- * @returns {(behavior: () => Promise<void>) => Promise<void>} async function that takes another async function defining the locked
+ * @returns async function that takes another async function defining the locked
  * behavior
  */
 function getLockFileGuard (lockFile, opts = {}) {
@@ -475,6 +470,10 @@ function getLockFileGuard (lockFile, opts = {}) {
   const check = B.promisify(_lockfile.check);
   const unlock = B.promisify(_lockfile.unlock);
 
+  /**
+   * @param {(...args: any[]) => T} behavior
+   * @returns {Promise<T>}
+   */
   const guard = async (behavior) => {
     let triedRecovery = false;
     do {

package/lib/zip.js

@@ -14,7 +14,13 @@ import log from './logger';
 import getStream from 'get-stream';
 import { exec } from 'teen_process';
 
+/**
+ * @type {(path: string, options?: yauzl.Options) => Promise<yauzl.ZipFile>}
+ */
 const openZip = B.promisify(yauzl.open);
+/**
+ * @type {(source: NodeJS.ReadableStream, destination: NodeJS.WritableStream) => Promise<NodeJS.WritableStream>}
+ */
 const pipeline = B.promisify(stream.pipeline);
 const ZIP_MAGIC = 'PK';
 const IFMT = 61440;
@@ -23,6 +29,9 @@ const IFLNK = 40960;
 
 // This class is mostly copied from https://github.com/maxogden/extract-zip/blob/master/index.js
 class ZipExtractor {
+  /** @type {yauzl.ZipFile} */
+  zipfile;
+
   constructor (sourcePath, opts = {}) {
     this.zipPath = sourcePath;
     this.opts = opts;
@@ -125,7 +134,9 @@ class ZipExtractor {
       return;
     }
 
-    const readStream = await B.promisify(this.zipfile.openReadStream.bind(this.zipfile))(entry);
+    /** @type {(entry: yauzl.Entry) => Promise<NodeJS.ReadableStream>} */
+    const openReadStream = B.promisify(this.zipfile.openReadStream.bind(this.zipfile));
+    const readStream = await openReadStream(entry);
     if (isSymlink) {
       const link = await getStream(readStream);
       await fs.symlink(link, dest);
@@ -183,9 +194,9 @@ class ZipExtractor {
  *
  * @param {string} zipFilePath The full path to the source ZIP file
  * @param {string} destDir The full path to the destination folder
- * @param {?ExtractAllOptions} opts
+ * @param {ExtractAllOptions} [opts]
  */
-async function extractAllTo (zipFilePath, destDir, opts = {}) {
+async function extractAllTo (zipFilePath, destDir, opts = /** @type {ExtractAllOptions} */({})) {
   if (!path.isAbsolute(destDir)) {
     throw new Error(`Target path '${destDir}' is expected to be absolute`);
   }
@@ -250,8 +261,8 @@ async function extractWithSystemUnzip (zipFilePath, destDir) {
 /**
  * Extract a single zip entry to a directory
  *
- * @param {Streamable} zipFile The source ZIP stream
- * @param {yauzl.ZipEntry} entry The entry instance
+ * @param {yauzl.ZipFile} zipFile The source ZIP stream
+ * @param {yauzl.Entry} entry The entry instance
  * @param {string} destDir The full path to the destination folder
  */
 async function _extractEntryTo (zipFile, entry, destDir) {
@@ -294,7 +305,7 @@ async function _extractEntryTo (zipFile, entry, destDir) {
 
 /**
  * @typedef ZipEntry
- * @property {yauzl.ZipEntry} entry The actual entry instance
+ * @property {yauzl.Entry} entry The actual entry instance
  * @property {function} extractEntryTo An async function, which accepts one parameter.
  * This parameter contains the destination folder path to which this function is going to extract the entry.
  */
@@ -354,12 +365,12 @@ async function readEntries (zipFilePath, onEntry) {
  *
  * @param {string} srcPath The full path to the folder or file being zipped
  * @param {ZipOptions} opts Zipping options
- * @returns {Buffer} Zipped (and encoded if `encodeToBase64` is truthy)
+ * @returns {Promise<Buffer>} Zipped (and encoded if `encodeToBase64` is truthy)
  * content of the source path as memory buffer
  * @throws {Error} if there was an error while reading the source
  * or the source is too big
  */
-async function toInMemoryZip (srcPath, opts = {}) {
+async function toInMemoryZip (srcPath, opts = /** @type {ZipOptions} */({})) {
   if (!await fs.exists(srcPath)) {
     throw new Error(`No such file or folder: ${srcPath}`);
   }
@@ -481,10 +492,10 @@ async function assertValidZip (filePath) {
 
 /**
  * @typedef ZipSourceOptions
- * @property {!string} pattern ['**\/*'] - GLOB pattern for compression
- * @property {!string} cwd - The source root folder (the parent folder of
+ * @property {string} pattern ['**\/*'] - GLOB pattern for compression
+ * @property {string} cwd - The source root folder (the parent folder of
  * the destination file by default)
- * @property {?Array<string>} ignore - The list of ignored patterns
+ * @property {string[]} [ignore] - The list of ignored patterns
  */
 
 /**
@@ -495,7 +506,7 @@ async function assertValidZip (filePath) {
  * @param {ZipCompressionOptions} opts - Compression options
  * @throws {Error} If there was an error while creating the archive
  */
-async function toArchive (dstPath, src = {}, opts = {}) {
+async function toArchive (dstPath, src = /** @type {ZipSourceOptions} */({}), opts = /** @type {ZipCompressionOptions} */({})) {
   const {
     level = 9,
   } = opts;
@@ -532,7 +543,7 @@ async function toArchive (dstPath, src = {}, opts = {}) {
  */
 const getExecutablePath = _.memoize(
   /**
-   * @returns {B<string>} Full Path to the executable
+   * @returns {Promise<string>} Full Path to the executable
    */
   async function getExecutablePath (binaryName) {
     const fullPath = await fs.which(binaryName);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appium/support",
-  "version": "2.56.1",
+  "version": "2.57.2",
   "description": "Support libs used across appium packages",
   "keywords": [
     "automation",
@@ -32,17 +32,17 @@
     "build"
   ],
   "scripts": {
-    "build": "babel lib --root-mode=upward --delete-dir-on-start --out-dir=build/lib",
+    "build": "babel lib --root-mode=upward --out-dir=build/lib",
     "dev": "npm run build -- --watch",
     "fix": "npm run lint -- --fix",
     "lint": "eslint -c ../../.eslintrc --ignore-path ../../.eslintignore .",
     "test": "npm run test:unit",
-    "test:e2e": "mocha --require ../../test/setup-babel.js --timeout 20s --slow 10s \"./test/e2e/**/*.spec.js\"",
-    "test:unit": "mocha --require ../../test/setup-babel.js \"./test/unit/**/*.spec.js\""
+    "test:e2e": "mocha --timeout 20s --slow 10s \"./test/e2e/**/*.spec.js\"",
+    "test:unit": "mocha \"./test/unit/**/*.spec.js\""
   },
   "dependencies": {
-    "@babel/runtime": "7.17.8",
-    "archiver": "5.3.0",
+    "@babel/runtime": "7.17.9",
+    "archiver": "5.3.1",
     "axios": "0.26.1",
     "base64-stream": "1.0.0",
     "bluebird": "3.7.2",
@@ -50,26 +50,26 @@
     "bplist-parser": "0.3.1",
     "form-data": "4.0.0",
     "get-stream": "6.0.1",
-    "glob": "7.2.0",
+    "glob": "8.0.1",
     "jimp": "0.16.1",
     "jsftp": "2.1.3",
     "klaw": "3.0.0",
     "lockfile": "1.0.4",
     "lodash": "4.17.21",
-    "moment": "2.29.1",
+    "moment": "2.29.3",
     "mv": "2.1.1",
     "ncp": "2.0.0",
     "npmlog": "6.0.1",
     "opencv-bindings": "4.5.5",
     "pkg-dir": "5.0.0",
-    "plist": "3.0.4",
+    "plist": "3.0.5",
     "pluralize": "8.0.0",
     "pngjs": "6.0.0",
     "read-pkg": "5.2.0",
     "resolve-from": "5.0.0",
     "rimraf": "3.0.2",
     "sanitize-filename": "1.6.3",
-    "semver": "7.3.5",
+    "semver": "7.3.7",
     "shell-quote": "1.7.3",
     "source-map-support": "0.5.21",
     "teen_process": "1.16.0",
@@ -84,5 +84,12 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "6d35def9ed754121fee691cdaf7b30e3a7ac3e8b"
+  "types": "./build/lib/index.d.ts",
+  "devDependencies": {
+    "type-fest": "2.12.2"
+  },
+  "overrides": {
+    "type-fest": "$type-fest"
+  },
+  "gitHead": "8b7906f757f23b7abc09a0acf41a3daa6671c2ec"
 }