@appium/support 2.55.4 → 2.57.0

package/lib/npm.js

@@ -0,0 +1,278 @@
+// @ts-check
+
+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';
+import * as system from './system';
+import resolveFrom from 'resolve-from';
+
+
+/**
+ * Relative path to directory containing any Appium internal files
+ * XXX: this is duplicated in `appium/lib/constants.js`.
+ */
+export const CACHE_DIR_RELATIVE_PATH = path.join(
+  'node_modules',
+  '.cache',
+  'appium',
+);
+
+/**
+ * Relative path to lockfile used when installing an extension via `appium`
+ */
+export const INSTALL_LOCKFILE_RELATIVE_PATH = path.join(
+  CACHE_DIR_RELATIVE_PATH,
+  '.install.lock',
+);
+
+/**
+ * XXX: This should probably be a singleton, but it isn't.  Maybe this module should just export functions?
+ */
+export class NPM {
+  /**
+   * Returns path to "install" lockfile
+   * @private
+   * @param {string} cwd
+   */
+  _getInstallLockfilePath (cwd) {
+    return path.join(cwd, INSTALL_LOCKFILE_RELATIVE_PATH);
+  }
+
+  /**
+   * Execute `npm` with given args.
+   *
+   * If the process exits with a nonzero code, the contents of `STDOUT` and `STDERR` will be in the
+   * `message` of the {@link TeenProcessExecError} rejected.
+   * @param {string} cmd
+   * @param {string[]} args
+   * @param {ExecOpts} opts
+   * @param {ExecOpts} [execOpts]
+   */
+  async exec (cmd, args, opts, execOpts = /** @type {ExecOpts} */({})) {
+    let { cwd, json, lockFile } = opts;
+
+    // make sure we perform the current operation in cwd
+    execOpts = {...execOpts, cwd};
+
+    args.unshift(cmd);
+    if (json) {
+      args.push('--json');
+    }
+    const npmCmd = system.isWindows() ? 'npm.cmd' : 'npm';
+    let runner = async () => await exec(npmCmd, args, execOpts);
+    if (lockFile) {
+      const acquireLock = util.getLockFileGuard(lockFile);
+      const _runner = runner;
+      runner = async () => await acquireLock(_runner);
+    }
+
+    /** @type {import('teen_process').ExecResult<string> & {json?: any}} */
+    let ret;
+    try {
+      const {stdout, stderr, code} = await runner();
+      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
+      try {
+        ret.json = JSON.parse(stdout);
+      } catch (ign) {}
+    } catch (e) {
+      const {stdout = '', stderr = '', code = null} = /** @type {TeenProcessExecError} */(e);
+      const err = new Error(`npm command '${args.join(' ')}' failed with code ${code}.\n\nSTDOUT:\n${stdout.trim()}\n\nSTDERR:\n${stderr.trim()}`);
+      throw err;
+    }
+    return ret;
+  }
+
+  /**
+   * @param {string} cwd
+   * @param {string} pkg
+   */
+  async getLatestVersion (cwd, pkg) {
+    return (await this.exec('view', [pkg, 'dist-tags'], {
+      json: true,
+      cwd
+    })).json?.latest;
+  }
+
+  /**
+   * @param {string} cwd
+   * @param {string} pkg
+   * @param {string} curVersion
+   */
+  async getLatestSafeUpgradeVersion (cwd, pkg, curVersion) {
+    const allVersions = (await this.exec('view', [pkg, 'versions'], {
+      json: true,
+      cwd
+    })).json;
+    return this.getLatestSafeUpgradeFromVersions(curVersion, allVersions);
+  }
+
+  /**
+   * Runs `npm ls`, optionally for a particular package.
+   * @param {string} cwd
+   * @param {string} [pkg]
+   */
+  async list (cwd, pkg) {
+    return (await this.exec('list', pkg ? [pkg] : [], {cwd, json: true})).json;
+  }
+
+  /**
+   * Given a current version and a list of all versions for a package, return the version which is
+   * the highest safely-upgradable version (meaning not crossing any major revision boundaries, and
+   * not including any alpha/beta/rc versions)
+   *
+   * @param {string} curVersion - the current version of a package
+   * @param {Array<string>} allVersions - a list of version strings
+   *
+   * @return {string|null} - the highest safely-upgradable version, or null if there isn't one
+   */
+  getLatestSafeUpgradeFromVersions (curVersion, allVersions) {
+    let safeUpgradeVer = null;
+    const curSemver = semver.parse(curVersion);
+    if (curSemver === null) {
+      throw new Error(`Could not parse current version '${curVersion}'`);
+    }
+    for (const testVer of allVersions) {
+      const testSemver = semver.parse(testVer);
+      if (testSemver === null) {
+        throw new Error(`Could not parse version to test against: '${testVer}'`);
+      }
+      // if the test version is a prerelease, ignore it
+      if (testSemver.prerelease.length > 0) {
+        continue;
+      }
+      // if the current version is later than the test version, skip this test version
+      if (curSemver.compare(testSemver) === 1) {
+        continue;
+      }
+      // if the test version is newer, but crosses a major revision boundary, also skip it
+      if (testSemver.major > curSemver.major) {
+        continue;
+      }
+      // otherwise this version is safe to upgrade to. But there might be multiple ones of this
+      // kind, so keep iterating and keeping the highest
+      if (safeUpgradeVer === null || testSemver.compare(safeUpgradeVer) === 1) {
+        safeUpgradeVer = testSemver;
+      }
+    }
+    if (safeUpgradeVer) {
+      safeUpgradeVer = safeUpgradeVer.format();
+    }
+    return safeUpgradeVer;
+  }
+
+  /**
+   * Installs a package w/ `npm`
+   * @param {string} cwd
+   * @param {string} pkgName
+   * @param {InstallPackageOpts} [opts]
+   * @returns {Promise<import('type-fest').PackageJson>}
+   */
+  async installPackage (cwd, pkgName, {pkgVer} = {}) {
+    /** @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', [
+      ...installOpts,
+      pkgVer ? `${pkgName}@${pkgVer}` : pkgName
+    ], {
+      cwd,
+      json: true,
+      lockFile: this._getInstallLockfilePath(cwd)
+    });
+
+    if (res.json) {
+      // we parsed a valid json response, so if we got an error here, return that
+      // message straightaway
+      if (res.json.error) {
+        throw new Error(res.json.error);
+      }
+    }
+
+    // Now read package data from the installed package to return, and make sure
+    // everything got installed ok. Remember, pkgName might end up with a / in it due to an npm
+    // org, so if so, that will get correctly exploded into multiple directories, by path.resolve here
+    // (even on Windows!)
+    const pkgJsonPath = resolveFrom(cwd, `${pkgName}/package.json`);
+    try {
+      return require(pkgJsonPath);
+    } catch {
+      throw new Error('The package was not downloaded correctly; its package.json ' +
+                      'did not exist or was unreadable. We looked for it at ' +
+                      pkgJsonPath);
+    }
+  }
+
+  /**
+   * @param {string} cwd
+   * @param {string} pkg
+   */
+  async uninstallPackage (cwd, pkg) {
+    await this.exec('uninstall', [pkg], {
+      cwd,
+      lockFile: this._getInstallLockfilePath(cwd)
+    });
+  }
+}
+
+export const npm = new NPM();
+
+/**
+ * Options for {@link NPM.installPackage}
+ * @typedef InstallPackageOpts
+ * @property {string} [pkgVer] - the version of the package to install
+ */
+
+/**
+ * Options for {@link NPM.exec}
+ * @typedef ExecOpts
+ * @property {string} cwd - Current working directory
+ * @property {boolean} [json] - If `true`, supply `--json` flag to npm and resolve w/ parsed JSON
+ * @property {string} [lockFile] - Path to lockfile to use
+ */
+
+// THESE TYPES SHOULD BE IN TEEN PROCESS, NOT HERE
+
+/**
+ * Extra props `teen_process.exec` adds to its error objects
+ * @typedef TeenProcessExecErrorProps
+ * @property {string} stdout - STDOUT
+ * @property {string} stderr - STDERR
+ * @property {number?} code - Exit code
+ */
+
+/**
+ * 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

@@ -13,7 +13,7 @@ const RDWR_EXCL = cnst.O_CREAT | cnst.O_TRUNC | cnst.O_RDWR | cnst.O_EXCL;
  * - No `process.env.APPIUM_TMP_DIR`: `/var/folders/34/2222sh8n27d6rcp7jqlkw8km0000gn/T/xxxxxxxx.yyyy`
  * - With `process.env.APPIUM_TMP_DIR = '/path/to/root'`: `/path/to/root/xxxxxxxx.yyyy`
  *
- * @returns {string} A path to the temporary directory
+ * @returns {Promise<string>} A path to the temporary directory
  */
 async function tempDir () {
   const now = new Date();
@@ -33,9 +33,9 @@ async function tempDir () {
 }
 
 /**
- * @typedef {Object} Affixes
- * @property {string} prefix - prefix of the temp directory name
- * @property {string} suffix - suffix of the temp directory name
+ * @typedef Affixes
+ * @property {string} [prefix] - prefix of the temp directory name
+ * @property {string} [suffix] - suffix of the temp directory name
  */
 
 /**
@@ -43,8 +43,8 @@ async function tempDir () {
  * with arbitrary prefix/suffix for the directory name.
  *
  * @param {string|Affixes} rawAffixes
- * @param {?string} defaultPrefix
- * @returns {string}  A path to the temporary directory with rawAffixes and defaultPrefix
+ * @param {string} [defaultPrefix]
+ * @returns {Promise<string>}  A path to the temporary directory with rawAffixes and defaultPrefix
  */
 async function path (rawAffixes, defaultPrefix) {
   const affixes = parseAffixes(rawAffixes, defaultPrefix);
@@ -54,9 +54,9 @@ async function path (rawAffixes, defaultPrefix) {
 }
 
 /**
- * @typedef {Object} OpenedAffixes
+ * @typedef OpenedAffixes
  * @property {string} path - The path to file
- * @property {integer} fd - The file descriptor opened
+ * @property {number} fd - The file descriptor opened
  */
 
 /**
@@ -64,7 +64,7 @@ async function path (rawAffixes, defaultPrefix) {
  * with arbitrary prefix/suffix for the directory name and return it as open.
  *
  * @param {Affixes} affixes
- * @returns {OpenedAffixes}
+ * @returns {Promise<OpenedAffixes>}
  */
 async function open (affixes) {
   const filePath = await path(affixes, 'f-');
@@ -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':
@@ -116,7 +117,7 @@ const openDir = tempDir;
 /**
  * Returns a path to a temporary directory whcih is defined as static in the same process
  *
- * @returns {string} A temp directory path whcih is defined as static in the same process
+ * @returns {Promise<string>} A temp directory path whcih is defined as static in the same process
  */
 async function staticDir () { // eslint-disable-line require-await
   return _static;

package/lib/util.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 import B from 'bluebird';
 import _ from 'lodash';
 import os from 'os';
@@ -75,6 +77,7 @@ function localIp () {
   let ip = _.chain(os.networkInterfaces())
     .values()
     .flatten()
+    // @ts-ignore
     .filter(function (val) {
       return (val.family === 'IPv4' && val.internal === false);
     })
@@ -217,16 +220,16 @@ function filterObject (obj, predicate) {
  *                 if it is less than zero.
  */
 function toReadableSizeString (bytes) {
-  const intBytes = parseInt(bytes, 10);
+  const intBytes = parseInt(String(bytes), 10);
   if (isNaN(intBytes) || intBytes < 0) {
     throw new Error(`Cannot convert '${bytes}' to a readable size format`);
   }
   if (intBytes >= GiB) {
-    return `${parseFloat(intBytes / (GiB * 1.0)).toFixed(2)} GB`;
+    return `${(intBytes / (GiB * 1.0)).toFixed(2)} GB`;
   } else if (intBytes >= MiB) {
-    return `${parseFloat(intBytes / (MiB * 1.0)).toFixed(2)} MB`;
+    return `${(intBytes / (MiB * 1.0)).toFixed(2)} MB`;
   } else if (intBytes >= KiB) {
-    return `${parseFloat(intBytes / (KiB * 1.0)).toFixed(2)} KB`;
+    return `${(intBytes / (KiB * 1.0)).toFixed(2)} KB`;
   }
   return `${intBytes} B`;
 }
@@ -260,7 +263,7 @@ function isSubPath (originalPath, root, forcePosix = null) {
  * @param {string} path1 - Absolute or relative path to a file/folder
  * @param {string} path2 - Absolute or relative path to a file/folder
  * @param {...string} pathN - Zero or more absolute or relative paths to files/folders
- * @returns {boolean} true if all paths are pointing to the same file system item
+ * @returns {Promise<boolean>} true if all paths are pointing to the same file system item
  */
 async function isSameDestination (path1, path2, ...pathN) {
   const allPaths = [path1, path2, ...pathN];
@@ -273,34 +276,29 @@ 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));
 }
 
 /**
  * Coerces the given number/string to a valid version string
  *
- * @param {string|number} ver - Version string to coerce
- * @param {boolean} strict [true] - If true then an exception will be thrown
+ * @template {boolean} [Strict=true]
+ * @param {string} ver - Version string to coerce
+ * @param {Strict} [strict] - If `true` then an exception will be thrown
  * if `ver` cannot be coerced
- * @returns {string} Coerced version number or null if the string cannot be
+ * @returns {Strict extends true ? string : string|null} Coerced version number or null if the string cannot be
  * coerced and strict mode is disabled
  * @throws {Error} if strict mode is enabled and `ver` cannot be coerced
  */
-function coerceVersion (ver, strict = true) {
+function coerceVersion (ver, strict = /** @type {Strict} */(true)) {
   const result = semver.valid(semver.coerce(`${ver}`));
   if (strict && !result) {
     throw new Error(`'${ver}' cannot be coerced to a valid version number`);
   }
-  return result;
+  return /** @type {Strict extends true ? string : string?} */(result);
 }
 
 const SUPPORTED_OPERATORS = ['==', '!=', '>', '<', '>=', '<=', '='];
@@ -308,9 +306,9 @@ const SUPPORTED_OPERATORS = ['==', '!=', '>', '<', '>=', '<=', '='];
 /**
  * Compares two version strings
  *
- * @param {string|number} ver1 - The first version number to compare. Should be a valid
+ * @param {string} ver1 - The first version number to compare. Should be a valid
  * version number supported by semver parser.
- * @param {string|number} ver2 - The second version number to compare. Should be a valid
+ * @param {string} ver2 - The second version number to compare. Should be a valid
  * version number supported by semver parser.
  * @param {string} operator - One of supported version number operators:
  * ==, !=, >, <, <=, >=, =
@@ -333,11 +331,11 @@ function compareVersions (ver1, operator, ver2) {
  * Add appropriate quotes to command arguments. See https://github.com/substack/node-shell-quote
  * for more details
  *
- * @param {string|Array<string>} - The arguments that will be parsed
+ * @param {string|string[]} args - The arguments that will be parsed
  * @returns {string} - The arguments, quoted
  */
 function quote (args) {
-  return shellQuote(args);
+  return shellQuote(_.castArray(args));
 }
 
 /**
@@ -354,8 +352,8 @@ function unleakString (s) {
 
 
 /**
- * @typedef {Object} PluralizeOptions
- * @property {?boolean} inclusive [false] - Whether to prefix with the number (e.g., 3 ducks)
+ * @typedef PluralizeOptions
+ * @property {boolean} [inclusive=false] - Whether to prefix with the number (e.g., 3 ducks)
  */
 
 /**
@@ -363,7 +361,7 @@ function unleakString (s) {
  *
  * @param {string} word - The word to pluralize
  * @param {number} count - How many of the word exist
- * @param {?PluralizeOptions|boolean} options|inclusive - options for word pluralization,
+ * @param {PluralizeOptions|boolean} options - options for word pluralization,
  *   or a boolean indicating the options.inclusive property
  * @returns {string} The word pluralized according to the number
  */
@@ -380,8 +378,8 @@ function pluralize (word, count, options = {}) {
 }
 
 /**
- * @typedef {Object} EncodingOptions
- * @property {number} maxSize [1073741824] The maximum size of
+ * @typedef EncodingOptions
+ * @property {number} [maxSize=1073741824] The maximum size of
  * the resulting buffer in bytes. This is set to 1GB by default, because
  * Appium limits the maximum HTTP body size to 1GB. Also, the NodeJS heap
  * size must be enough to keep the resulting object (usually this size is
@@ -395,7 +393,7 @@ function pluralize (word, count, options = {}) {
  *
  * @param {string} srcPath The full path to the file being encoded
  * @param {EncodingOptions} opts
- * @returns {Buffer} base64-encoded content of the source file as memory buffer
+ * @returns {Promise<Buffer>} base64-encoded content of the source file as memory buffer
  * @throws {Error} if there was an error while reading the source file
  * or the source file is too
  */
@@ -445,9 +443,9 @@ async function toInMemoryBase64 (srcPath, opts = {}) {
 }
 
 /**
- * @typedef {Object} LockFileOptions
- * @property {number} timeout [120] The max time in seconds to wait for the lock
- * @property {boolean} tryRecovery [false] Whether to try lock recovery if
+ * @typedef LockFileOptions
+ * @property {number} [timeout=120] The max time in seconds to wait for the lock
+ * @property {boolean} [tryRecovery=false] Whether to try lock recovery if
  * the first attempt to acquire it timed out.
  */
 
@@ -456,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 {AsyncFunction} 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 = {}) {
@@ -467,10 +466,14 @@ function getLockFileGuard (lockFile, opts = {}) {
     tryRecovery = false,
   } = opts;
 
-  const lock = B.promisify(_lockfile.lock);
+  const lock = /** @type {(lockfile: string, opts: import('lockfile').Options)=>B<void>} */(B.promisify(_lockfile.lock));
   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 {