@appium/support 2.58.0 → 2.59.0

package/lib/console.js

@@ -0,0 +1,173 @@
+import _ from 'lodash';
+import {supportsColor} from 'supports-color';
+import {Console as NodeConsole} from 'console';
+import '@colors/colors';
+import symbols from 'log-symbols';
+import {Writable} from 'stream';
+
+/**
+ * Stream to nowhere. Used when we want to disable any output other than JSON output.
+ */
+class NullWritable extends Writable {
+  // eslint-disable-next-line promise/prefer-await-to-callbacks
+  _write(chunk, encoding, callback) {
+    setImmediate(callback);
+  }
+}
+
+/**
+ * A particular console/logging class for Appium's CLI.
+ *
+ * - By default, uses some fancy symbols
+ * - Writes to `STDERR`, generally.
+ * - In "JSON mode", `STDERR` is squelched. Use {@linkcode Console.json} to write the JSON.
+ *
+ * DO NOT extend this to do anything other than what it already does. Download a library or something.
+ */
+export class CliConsole {
+  /**
+   * Internal console
+   * @type {globalThis.Console}
+   */
+  #console;
+
+  /**
+   * Whether or not to use fancy symbols when logging.
+   * @type {boolean}
+   *
+   */
+  #useSymbols;
+
+  /**
+   * Whether or not to use color.
+   */
+  #useColor;
+
+  /**
+   * @type {Record<keyof typeof symbols,keyof Extract<import('@colors/colors').Color, 'string'>>}
+   */
+  static symbolToColor = {
+    success: 'green',
+    info: 'cyan',
+    warning: 'yellow',
+    error: 'red',
+  };
+
+  /**
+   *
+   * @param {ConsoleOpts} opts
+   */
+  constructor({jsonMode = false, useSymbols = true, useColor} = {}) {
+    this.#console = new NodeConsole(process.stdout, jsonMode ? new NullWritable() : process.stderr);
+    this.#useSymbols = Boolean(useSymbols);
+    this.#useColor = Boolean(useColor ?? supportsColor(process.stderr));
+  }
+
+  /**
+   * Wraps a message string in breathtaking fanciness
+   *
+   * Returns `undefined` if `msg` is `undefined`.
+   * @param {string} [msg] - Message to decorate, if anything
+   * @param {keyof typeof CliConsole['symbolToColor']} [symbol] - Symbol to use
+   * @returns {string|undefined}
+   */
+  decorate(msg, symbol) {
+    if (_.isString(msg)) {
+      let newMsg = /** @type {string} */ (msg);
+      if (_.isString(symbol) && this.#useSymbols) {
+        newMsg = `${symbols[symbol]} ${newMsg}`;
+        if (this.#useColor) {
+          newMsg = newMsg[CliConsole.symbolToColor[symbol]];
+        }
+      }
+      return newMsg;
+    }
+    return msg;
+  }
+
+  /**
+   * Writes to `STDOUT`.  Must be stringifyable.
+   *
+   * You probably don't want to call this more than once before exiting (since that will output invalid JSON).
+   * @param {import('type-fest').JsonValue} value
+   */
+  json(value) {
+    this.#console.log(JSON.stringify(value));
+  }
+
+  /**
+   * General logging function.
+   * @param {string} [message]
+   * @param {...any} args
+   */
+  log(message, ...args) {
+    this.#console.error(message, ...args);
+  }
+
+  /**
+   * A "success" message
+   * @param {string} [message]
+   * @param {...any} args
+   */
+  ok(message, ...args) {
+    this.#console.error(this.decorate(message, 'success'), ...args);
+  }
+
+  /**
+   * Alias for {@linkcode Console.log}
+   * @param {string} [message]
+   * @param {...any} args
+   */
+  debug(message, ...args) {
+    this.log(message, ...args);
+  }
+
+  /**
+   * Wraps {@link console.dir}
+   * @param {any} item
+   * @param {import('util').InspectOptions} [opts]
+   */
+  dump(item, opts) {
+    this.#console.dir(item, opts);
+  }
+
+  /**
+   * An "info" message
+   * @param {string} [message]
+   * @param {...any} args
+   */
+  info(message, ...args) {
+    this.log(this.decorate(message, 'info'), ...args);
+  }
+
+  /**
+   * A "warning" message
+   * @param {string} [message]
+   * @param {...any} args
+   */
+  warn(message, ...args) {
+    this.log(this.decorate(message, 'warning'), ...args);
+  }
+
+  /**
+   * An "error" message
+   * @param {string} [message]
+   * @param {...any} args
+   */
+  error(message, ...args) {
+    this.log(this.decorate(message, 'error'), ...args);
+  }
+}
+
+/**
+ * Options for {@linkcode CliConsole}.
+ *
+ * @typedef ConsoleOpts
+ * @property {boolean} [jsonMode] - If _truthy_, supress all output except JSON (use {@linkcode CliConsole#json}), which writes to `STDOUT`.
+ * @property {boolean} [useSymbols] - If _falsy_, do not use fancy symbols.
+ * @property {boolean} [useColor] - If _falsy_, do not use color output. If _truthy_, forces color output. By default, checks terminal/TTY for support via pkg `supports-color`. Ignored if `useSymbols` is `false`.
+ * @see https://npm.im/supports-color
+ */
+
+export const console = new CliConsole();
+export {symbols};

package/lib/env.js

@@ -1,10 +1,10 @@
 // @ts-check
 import _ from 'lodash';
-import { homedir } from 'os';
+import {homedir} from 'os';
 import path from 'path';
 import pkgDir from 'pkg-dir';
 import readPkg from 'read-pkg';
-import { npm } from './npm';
+import {npm} from './npm';
 
 /**
  * Path to the default `APPIUM_HOME` dir (`~/.appium`).
@@ -26,7 +26,7 @@ export const MANIFEST_RELATIVE_PATH = path.join(
   'node_modules',
   '.cache',
   'appium',
-  MANIFEST_BASENAME,
+  MANIFEST_BASENAME
 );
 
 /**
@@ -45,7 +45,7 @@ export const MANIFEST_RELATIVE_PATH = path.join(
  * @param {string} cwd
  * @returns {Promise<boolean>}
  */
-export async function hasAppiumDependency (cwd) {
+export async function hasAppiumDependency(cwd) {
   /**
    * @todo type this
    * @type {object}
@@ -78,7 +78,7 @@ export async function hasAppiumDependency (cwd) {
       // doing any further checking here may be a fool's errand, because you can pin the version
       // to a _lot_ of different things (tags, URLs, etc).
       !version.startsWith('1') &&
-      !version.startsWith('0'),
+      !version.startsWith('0')
   );
 }
 
@@ -91,9 +91,9 @@ export const readPackageInDir = _.memoize(
    * @param {string} cwd - Directory ostensibly having a `package.json`
    * @returns {Promise<import('read-pkg').NormalizedPackageJson|undefined>}
    */
-  async function _readPackageInDir (cwd) {
+  async function _readPackageInDir(cwd) {
     return await readPkg({cwd, normalize: true});
-  },
+  }
 );
 
 /**
@@ -108,7 +108,7 @@ export const resolveAppiumHome = _.memoize(
    * @param {string} [cwd] - Current working directory.  _Must_ be absolute, if specified.
    * @returns {Promise<string>}
    */
-  async function _resolveAppiumHome (cwd = process.cwd()) {
+  async function _resolveAppiumHome(cwd = process.cwd()) {
     if (process.env.APPIUM_HOME) {
       return process.env.APPIUM_HOME;
     }
@@ -133,10 +133,8 @@ export const resolveAppiumHome = _.memoize(
       return DEFAULT_APPIUM_HOME;
     }
 
-    return (await hasAppiumDependency(currentPkgDir))
-      ? currentPkgDir
-      : DEFAULT_APPIUM_HOME;
-  },
+    return (await hasAppiumDependency(currentPkgDir)) ? currentPkgDir : DEFAULT_APPIUM_HOME;
+  }
 );
 
 /**
@@ -150,11 +148,11 @@ export const resolveManifestPath = _.memoize(
    * @param {string} [appiumHome] - Appium home directory
    * @returns {Promise<string>}
    */
-  async function _resolveManifestPath (appiumHome) {
+  async function _resolveManifestPath(appiumHome) {
     // can you "await" in a default parameter? is that a good idea?
     appiumHome = appiumHome ?? (await resolveAppiumHome());
     return path.join(appiumHome, MANIFEST_RELATIVE_PATH);
-  },
+  }
 );
 
 /**

package/lib/fs.js

@@ -2,7 +2,16 @@
 
 import B from 'bluebird';
 import crypto from 'crypto';
-import { close, constants, createReadStream, createWriteStream, promises as fsPromises, read, write, open } from 'fs';
+import {
+  close,
+  constants,
+  createReadStream,
+  createWriteStream,
+  promises as fsPromises,
+  read,
+  write,
+  open,
+} from 'fs';
 import glob from 'glob';
 import klaw from 'klaw';
 import _ from 'lodash';
@@ -16,9 +25,12 @@ import sanitize from 'sanitize-filename';
 import which from 'which';
 import log from './logger';
 import Timer from './timing';
-import { pluralize } from './util';
+import {pluralize} from './util';
 
-const ncpAsync = /** @type {(source: string, dest: string, opts: ncp.Options|undefined) => B<void>} */(B.promisify(ncp));
+const ncpAsync =
+  /** @type {(source: string, dest: string, opts: ncp.Options|undefined) => B<void>} */ (
+    B.promisify(ncp)
+  );
 const findRootCached = _.memoize(pkgDir.sync);
 
 const fs = {
@@ -27,7 +39,7 @@ const fs = {
    * @param {import('fs').PathLike} path
    * @returns {Promise<boolean>}
    */
-  async hasAccess (path) {
+  async hasAccess(path) {
     try {
       await fsPromises.access(path, constants.R_OK);
     } catch (err) {
@@ -40,7 +52,7 @@ const fs = {
    * Alias for {@linkcode fs.hasAccess}
    * @param {import('fs').PathLike} path
    */
-  async exists (path) {
+  async exists(path) {
     return await fs.hasAccess(path);
   },
 
@@ -48,7 +60,9 @@ const fs = {
    * Remove a directory and all its contents, recursively
    * @todo Replace with `rm()` from `fs.promises` when Node.js v12 support is dropped.
    */
-  rimraf: /** @type {(dirpath: string, opts?: import('rimraf').Options) => Promise<void>} */(B.promisify(rimrafIdx)),
+  rimraf: /** @type {(dirpath: string, opts?: import('rimraf').Options) => Promise<void>} */ (
+    B.promisify(rimrafIdx)
+  ),
 
   /**
    * Alias of {@linkcode rimrafIdx.sync}
@@ -64,7 +78,7 @@ const fs = {
    * @returns {Promise<string|undefined>}
    * @see https://nodejs.org/api/fs.html#fspromisesmkdirpath-options
    */
-  async mkdir (filepath, opts = {}) {
+  async mkdir(filepath, opts = {}) {
     try {
       return await fsPromises.mkdir(filepath, opts);
     } catch (err) {
@@ -81,8 +95,8 @@ const fs = {
    * @see https://npm.im/ncp
    * @returns {Promise<void>}
    */
-  async copyFile (source, destination, opts = {}) {
-    if (!await fs.hasAccess(source)) {
+  async copyFile(source, destination, opts = {}) {
+    if (!(await fs.hasAccess(source))) {
       throw new Error(`The file at '${source}' does not exist or is not accessible`);
     }
     return await ncpAsync(source, destination, opts);
@@ -93,14 +107,14 @@ const fs = {
    * @param {import('fs').PathLike} filePath
    * @returns {Promise<string>}
    */
-  async md5 (filePath) {
+  async md5(filePath) {
     return await fs.hash(filePath, 'md5');
   },
 
   /**
    * Move a file
    */
-  mv: /** @type {(from: string, to: string, opts?: mv.Options) => B<void>} */(B.promisify(mv)),
+  mv: /** @type {(from: string, to: string, opts?: mv.Options) => B<void>} */ (B.promisify(mv)),
 
   /**
    * Find path to an executable in system `PATH`
@@ -112,7 +126,7 @@ const fs = {
    * Given a glob pattern, resolve with list of files matching that pattern
    * @see https://github.com/isaacs/node-glob
    */
-  glob: /** @type {(pattern: string, opts?: glob.IOptions) => B<string[]>} */(B.promisify(glob)),
+  glob: /** @type {(pattern: string, opts?: glob.IOptions) => B<string[]>} */ (B.promisify(glob)),
 
   /**
    * Sanitize a filename
@@ -126,12 +140,17 @@ const fs = {
    * @param {string} [algorithm]
    * @returns {Promise<string>}
    */
-  async hash (filePath, algorithm = 'sha1') {
+  async hash(filePath, algorithm = 'sha1') {
     return await new B((resolve, reject) => {
       const fileHash = crypto.createHash(algorithm);
       const readStream = createReadStream(filePath);
-      readStream.on('error', (e) => reject(
-        new Error(`Cannot calculate ${algorithm} hash for '${filePath}'. Original error: ${e.message}`)));
+      readStream.on('error', (e) =>
+        reject(
+          new Error(
+            `Cannot calculate ${algorithm} hash for '${filePath}'. Original error: ${e.message}`
+          )
+        )
+      );
       readStream.on('data', (chunk) => fileHash.update(chunk));
       readStream.on('end', () => resolve(fileHash.digest('hex')));
     });
@@ -145,7 +164,7 @@ const fs = {
    * @returns {import('klaw').Walker}
    * @see https://www.npmjs.com/package/klaw
    */
-  walk (dir, opts) {
+  walk(dir, opts) {
     return klaw(dir, opts);
   },
 
@@ -154,7 +173,7 @@ const fs = {
    * @param {import('fs').PathLike} dir
    * @returns {Promise<string|undefined>}
    */
-  async mkdirp (dir) {
+  async mkdirp(dir) {
     return await fs.mkdir(dir, {recursive: true});
   },
 
@@ -166,7 +185,8 @@ const fs = {
    * @throws {Error} If the `dir` parameter contains a path to an invalid folder
    * @returns {Promise<string?>} returns the found path or null if the item was not found
    */
-  async walkDir (dir, recursive, callback) { //eslint-disable-line promise/prefer-await-to-callbacks
+  async walkDir(dir, recursive, callback) {
+    //eslint-disable-line promise/prefer-await-to-callbacks
     let isValidRoot = false;
     let errMsg = null;
     try {
@@ -175,7 +195,9 @@ const fs = {
       errMsg = e.message;
     }
     if (!isValidRoot) {
-      throw Error(`'${dir}' is not a valid root directory` + (errMsg ? `. Original error: ${errMsg}` : ''));
+      throw Error(
+        `'${dir}' is not a valid root directory` + (errMsg ? `. Original error: ${errMsg}` : '')
+      );
     }
 
     let walker;
@@ -187,48 +209,51 @@ const fs = {
       walker = klaw(dir, {
         depthLimit: recursive ? -1 : 0,
       });
-      walker.on('data', function (item) {
-        walker.pause();
+      walker
+        .on('data', function (item) {
+          walker.pause();
 
-        if (!item.stats.isDirectory()) {
-          fileCount++;
-        } else {
-          directoryCount++;
-        }
+          if (!item.stats.isDirectory()) {
+            fileCount++;
+          } else {
+            directoryCount++;
+          }
 
-        // eslint-disable-next-line promise/prefer-await-to-callbacks
-        lastFileProcessed = B.try(async () => await callback(item.path, item.stats.isDirectory()))
-          .then(function (done = false) {
-            if (done) {
-              resolve(item.path);
-            } else {
-              walker.resume();
-            }
-          })
-          .catch(reject);
-      })
-      .on('error', function (err, item) {
-        log.warn(`Got an error while walking '${item.path}': ${err.message}`);
-        // klaw cannot get back from an ENOENT error
-        if (err.code === 'ENOENT') {
-          log.warn('All files may not have been accessed');
-          reject(err);
-        }
-      })
-      .on('end', function () {
-        lastFileProcessed
-          .then((file) => {
-            resolve(/** @type {string|undefined} */(file) ?? null);
-          })
-          .catch(function (err) {
-            log.warn(`Unexpected error: ${err.message}`);
+          // eslint-disable-next-line promise/prefer-await-to-callbacks
+          lastFileProcessed = B.try(async () => await callback(item.path, item.stats.isDirectory()))
+            .then(function (done = false) {
+              if (done) {
+                resolve(item.path);
+              } else {
+                walker.resume();
+              }
+            })
+            .catch(reject);
+        })
+        .on('error', function (err, item) {
+          log.warn(`Got an error while walking '${item.path}': ${err.message}`);
+          // klaw cannot get back from an ENOENT error
+          if (err.code === 'ENOENT') {
+            log.warn('All files may not have been accessed');
             reject(err);
-          });
-      });
+          }
+        })
+        .on('end', function () {
+          lastFileProcessed
+            .then((file) => {
+              resolve(/** @type {string|undefined} */ (file) ?? null);
+            })
+            .catch(function (err) {
+              log.warn(`Unexpected error: ${err.message}`);
+              reject(err);
+            });
+        });
     }).finally(function () {
-      log.debug(`Traversed ${pluralize('directory', directoryCount, true)} ` +
-        `and ${pluralize('file', fileCount, true)} ` +
-        `in ${timer.getDuration().asMilliSeconds.toFixed(0)}ms`);
+      log.debug(
+        `Traversed ${pluralize('directory', directoryCount, true)} ` +
+          `and ${pluralize('file', fileCount, true)} ` +
+          `in ${timer.getDuration().asMilliSeconds.toFixed(0)}ms`
+      );
       if (walker) {
         walker.destroy();
       }
@@ -241,7 +266,7 @@ const fs = {
    * @throws {Error} If there were problems finding or reading a `package.json` file
    * @returns {object} A parsed `package.json`
    */
-  readPackageJsonFrom (dir, opts = {}) {
+  readPackageJsonFrom(dir, opts = {}) {
     const cwd = fs.findRoot(dir);
     try {
       return readPkg.sync({...opts, cwd});
@@ -257,7 +282,7 @@ const fs = {
    * @throws {Error} If there were problems finding the project root
    * @returns {string} The closeset parent dir containing `package.json`
    */
-  findRoot (dir) {
+  findRoot(dir) {
     if (!dir || !path.isAbsolute(dir)) {
       throw new TypeError('`findRoot()` must be provided a non-empty, absolute path');
     }
@@ -320,10 +345,10 @@ const fs = {
    * Use `constants.X_OK` instead.
    * @deprecated
    */
-  X_OK: constants.X_OK
+  X_OK: constants.X_OK,
 };
 
-export { fs };
+export {fs};
 export default fs;
 
 /**
@@ -332,7 +357,7 @@ export default fs;
  * @param {string} itemPath The path of the file or folder
  * @param {boolean} isDirectory Shows if it is a directory or a file
  * @return {boolean} return true if you want to stop walking
-*/
+ */
 
 /**
  * @typedef {import('glob')} glob